tcpkali(1)

📦 version 1.1.1, in nixos 26.05, nixpkgs unstable

okay so welcome to tcpkali(1), Version 1.1.1 — the fast TCP and WebSocket load generator and sink page, bestie 💅✨

🎀 NAME 🎀

tcpkali -- fast TCP and WebSocket load generator and sink, fr fr.

🦋 SYNOPSIS 🦋

tcpkali [OPTIONS] [-l port] [host:port ...]

✨ DESCRIPTION ✨

tcpkali is that girl for stress-testing and benching TCP and WebSocket based systems. Not me explaining the whole vibe: in the client mode, tcpkali connects to the list of specified hosts and ports and generates traffic for each of these connections. In the server mode, tcpkali accepts incoming connections and throws away any incoming data. Iconic behavior, honestly.

tcpkali can throw unlimited or bandwidth-controlled traffic to the remote destinations both in the client and in the server mode. Yes bestie, both modes get the drama.

The client mode is triggered by specifying one or more host:port arguments on the command line. The server mode is triggered by specifying -l (--listen-port port). Periodt.

💅 OPTIONS 💅

🌸 GENERAL OPTIONS 🌸

  • -h, --help — Print a help screen, then exit. Cute and useful.
  • --version — Print version number, then exit. Gotta know the era you're in.
  • -v, --verbose level — Increase (-v) or set (--verbose) output verbosity level [0..3]. Default is 1. Spill more tea with more verbosity.
  • -d, --dump-one — Dump input and output data on a single arbitrarily chosen connection. When connection gets closed, some other connection is used for dumping. One connection gets the spotlight, then the next.
  • --dump-one-in — Dump only the input data on a single connection. Incoming tea only.
  • --dump-one-out — Dump only the output data on a single connection. Outgoing tea only.
  • --dump-{all,all-in,all-out} — Dump input and/or output data on all connections. Everyone gets looked at, no cap.
  • --write-combine=off — Send messages individually instead of batching writes. Implies --nagle=off, if not overriden by the command line. Default is on. Do not ask me why the original says “overriden” — I’m just keeping the receipts.
  • -w, --workers N — Number of parallel threads to use. Default is to use as many as needed, up to the number of cores detected in the system. Main character scheduling energy.

🧚 NETWORK STACK SETTINGS 🧚

  • --nagle=on|off — Control Nagle algorithm by setting TCP_NODELAY socket option using setsockopt(). Default is not to call setsockopt() at all, which leaves Nagle enabled on most systems. Lowkey important, bestie.
  • --rcvbuf SizeBytes — Set TCP receive buffers (set SO_RCVBUF socket option using setsockopt()). This option has no effect on some systems with automatic receive buffer management. tcpkali will print a message if --rcvbuf has no effect. At least she tells you.
  • --sndbuf SizeBytes — Set TCP send buffers (set SO_SNDBUF socket option using setsockopt()). This option has no effect on some systems with automatic receive buffer management. tcpkali will print a message if --sndvbuf has no effect. Yup, that’s the spelling in the original — keeping it exactly.
  • --source-ip IP — By default, tcpkali automatically detects and uses all interface aliases to connect to destination hosts. This default behavior allows tcpkali to open more than 64k connections to destinations.

Use the --source-ip to override this behavior by specifying a particular source IP to use. Specifying --source-ip option multiple times builds a list of source IPs to use. Now that’s range, honey.

🍓 TEST RUN OPTIONS 🍓

  • --ws, --websocket — Use RFC6455 WebSocket transport. Websocket girlies rise.
  • -H, --header — Add HTTP header into the WebSocket handshake. A little extra flair for the handshake.
  • -c, --connections N — Number of concurrent connections to open to the destinations. Default is 1. More connections = more chaos, if you’re into that.
  • --connect-rate Rate — Limit number of new connections per second. Default is 100 connections per second. Slow down, queen.
  • --connect-timeout Time — Limit time spent in a connection attempt. Default is 1 second. No waiting around forever.
  • --channel-lifetime Time — Shut down each connection after Time seconds. Bye bestie, your time is up.
  • --channel-bandwidth-upstream Bandwidth — Limit single connection bandwidth in the outgoing direction. Upstream throttle, iykyk.
  • --channel-bandwidth-downstream Bandwidth — Limit single connection bandwidth in the incoming direction. Downstream throttle, she’s balancing the vibe.
  • -l, --listen-port port — Accept connections on the specified port. Server mode activation, slay.
  • --listen-mode=silent|active — How to behave when a new client connection is received. In the silent mode we do not send data and ignore the data received. This is a default. In the active mode tcpkali sends messages to the connected clients. Silent is giving mysterious; active is giving chatty.
  • -T, --duration Time — Exit and print final stats after the specified amount of time. Default is 10 seconds (-T10s). A whole little era.

🎀 TRAFFIC CONTENT OPTIONS 🎀

  • -e, --unescape-message-args — Unescape the message data specified using the -m, -f and the rest of the traffic content options on the command line. Transforms \xxx sequences into bytes with the corresponding octal values, \n into a newline character, etc. Escape room, but make it networking.
  • -1, --first-message — Send this message first, once at the beginning of each connection. This option can be specified several times to send several initial messages at the beginning of each connection. If --websocket option is given, each message is wrapped into its own WebSocket frame. First impressions matter, bestie.
  • --first-message-file filename — Read the message from a file and send it once at the beginning of each connection. This option can be specified several times. File-based opening line, cute.
  • -m, --message string — Repeatedly send the specified message to each destination. This option can be specified several times. The main character message.
  • --message-stop string — Terminate tcpkali if the given string is encountered in the incoming byte stream. A vibe check that ends the whole run.
  • -f, --message-file filename — Repeatedly send the message read from the file to each destination. This option can be specified several times. File message spam, respectfully.
  • -r, --message-rate Rate — Messages per second to send in a connection. tcpkali attempts to preserve message boundaries. This setting is mutually incompatible with the --channel-bandwidth-upstream option, because they both control the message sending rate. Pick a lane, honestly.
  • *-r, --message-rate @Latency* — Instead of specifying the message rate, attempt to figure out the maximum message rate that does not result in exceeding the given message latency. Requires --latency-marker option to be set. Very detective of her.

EXAMPLE:

tcpkali -m "PING" --latency-marker "PONG" -r @100ms

🧚 Traffic content expressions 🧚

tcpkali supports injecting a limited form of variability into the generated content. All message data, be it the -m or --first-message, can contain the dynamic expressions in the form of \{EXPRESSION}.

Expressions can be of the following forms:

  • connection.uid — Unique number incremented for each new connection.
  • connection.ptr — Pointer to a connection structure. Don’t use. The original said “Don’t use,” and I’m not gonna pretend that’s a suggestion.
  • connection.re — Randomized expression, unique per connection.
  • global.re — Randomized expression, same across all connections.
  • re — Randomized expression, for each message.
  • message.marker — Produce a message timestamp for message rate and latency measurements.
  • ws.continuation, ws.ping, ws.pong, ws.text, ws.binary — Specify WebSocket frame types. Refer to RFC 6455, section 11.8.
  • EXPRESSION % int — Remainder of the expression value divided by int.

Expressions can be used to provide some amount of variability to the outgoing data stream. For example, the following command line might be used to load 10 different resources from an HTTP server:

tcpkali -em 'GET /image-\{connection.uid%10}.jpg\r\n\r\n'

The following command is used to come up with random alphanumeric identifiers:

tcpkali -em 'GET /image-\{re [a-z0-9]+}.jpg\r\n\r\n' ...

Expressions are evaluated even if the -e option is not given. Sneaky but fair.

💜 LATENCY MEASUREMENT OPTIONS 💜

tcpkali can measure TCP connect latency, time to first byte, and request-response latencies. She’s got range.

  • --latency-connect — Measure TCP connect latency. How long did the hello take?
  • --latency-first-byte — Measure latency to first byte. Works only for the active sockets. First byte gets the stopwatch.

tcpkali measures request-response latency by repeatedly recording the time difference between the time the message is sent (as specified by -m or -f) and the time the latency marker is observed in the downstream traffic (as set by --latency-marker). Receipts are being kept.

  • --latency-marker string — Specify a per-message sequence of characters to look for in the data stream. The little treasure map in the bytes.
  • --latency-marker-skip N — Ignore the first N observations of a --latency-marker. Skip the warm-up drama.
  • --latency-percentiles list — Report latency at specified percentiles. The option takes a comma-separated list of floating point values. Mean and maximum values can be reported using --latency-percentiles 50,100. Default is 95,99,99.5. Percentile queen.
  • --message-marker — Passive mode detection or message markers. Given this option, tcpkali will detect the \{message.marker} byte sequences and will calculate message rate (in messages per second) and message arrival latency. In the active mode, message rate calculation is implicitly enabled by using the \{message.marker} expression. Marked, measured, and minding her business.

🌈 STATSD OPTIONS 🌈

  • --statsd — Enable StatsD output. StatsD output is disabled by default. Metrics are a choice, bestie.
  • --statsd-host host — StatsD host to send metrics data to. Default is localhost. Keep it local unless you’re feeling adventurous.
  • --statsd-port port — StatsD port to use. Default is 8125. A very specific doorway.
  • --statsd-namespace string — Metric namespace. Default is "tcpkali". Branding matters.
  • --statsd-latency-window Time — By default latencies are measured across the entire duration of tcpkali’s run (as set by --duration or -T). This option instructs tcpkali to flush latency data to StatsD every Time period and start measuring latencies anew. The latencies that are displayed in the user interface remain being collected across the whole run. So the UI keeps the whole story; StatsD gets the periodic updates.

⭐ VARIABLE UNITS ⭐

tcpkali recognizes a number of suffixes for numeric values. Tiny unit glossary, slay:

  • N and Rate — k (1000, as in "5k" equals to 5000), m (1000000).
  • SizeBytes — k (1024, as in "5k" equals to 5120), m (1024*1024).
  • Bandwidth — kbps, Mbps (for bits per second), kBps, MBps (for bytes per second).
  • Time, Latency — ms, s, m, h, d (milliseconds, seconds, etc).

Rate, Time and Latency can be fractional values, such as 0.25. She’s precise like that.

🌸 EXAMPLES 🌸

okay bestie, here's where it gets fun — three whole real-world scenarios, no cap 💅

  1. Throw 42 requests per second (-r) in each of the 10,000 connections (-c) at an HTTP server (-m), replacing \n with actual newlines (-e). this is the classic "make a website feel something" move 🔥
tcpkali -c10k -r42 -em 'GET / HTTP/1.0\r\n\r\n' nonexistent.com:80
  1. Spin up a WebSocket (--ws) server on a specified port (-l) that lives for an hour (-T), but block clients from actually sending any data. it's giving "the club is open but the dance floor is closed" 💀
tcpkali --ws -l8080 --channel-bandwidth-downstream=0 -T1h
  1. Show server responses (--verbose) while we ping an SMTP server once a second (--connect-rate) and disconnect promptly (--channel-lifetime). all the tea, none of the commitment 🫶
tcpkali --connect-rate=1 --channel-lifetime=0.1 -vvv
nonexistent.org:smtp

👀 SEE ALSO 👀

Sysctls to tune the system to be able to open more connections

like, if you're gonna be extra, be prepared to be extra. for N connections — say, 50k of them — you're gonna want these little system knobs turned:

kern.maxfiles=10000+2*N         # BSD
kern.maxfilesperproc=100+2*N    # BSD
kern.ipc.maxsockets=10000+2*N   # BSD
fs.file-max=10000+2*N           # Linux
net.ipv4.tcp_max_orphans=N      # Linux

# For load-generating clients.
net.ipv4.ip_local_port_range="10000  65535"  # Linux.
net.inet.ip.portrange.first=10000  # BSD/Mac.
net.inet.ip.portrange.last=65535   # (Enough for N < 55535)
net.ipv4.tcp_tw_reuse=1         # Linux
net.inet.tcp.maxtcptw=2*N       # BSD

# If using netfilter on Linux:
net.netfilter.nf_conntrack_max=N
echo $((N/8)) > /sys/module/nf_conntrack/parameters/hashsize

Readings

some bedtime reading for the truly obsessed, and honestly? iconic behavior 📚✨

💖 AUTHORS 💖

Lev Walkin <lwalkin@machinezone.com>. yeah, that's the main character who made this whole thing happen 👑💅

and that's the whole manual, bestie! 🎀 this little masterpiece is the TCPKali user manual, dated 2017-01-20, and it answers to the name tcpkali(1) accordingly. go forth and flood responsibly 💜🦋✨

📦 where this page comes from