Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  TCPKALI (1)


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


     General Options
     Network Stack Settings
     Test Run Options
     Traffic Content Options
     Traffic content expressions
     Latency Measurement Options
     Statsd Options
Variable Units
See Also
     Sysctls to tune the system to be able to open more connections


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


tcpkali is a tool that helps stress-test and bench TCP and WebSocket based systems. In the I]client] mode tcpkali connects to the list of specified hosts and ports and generates traffic for each of these connections. In the I]server] mode tcpkali accepts incoming connections and throws away any incoming data.

tcpkali can throw unlimited or bandwidth-controlled traffic to the remote destinations both in the I]client] and in the I]server] mode.

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



-h, --help Print a help screen, then exit.
  Print version number, then exit.
-v, --verbose I]level]
  Increase (B]-v]) or set (B]--verbose]) output verbosity level [0..3]. Default is 1.
-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.
  Dump only the input data on a single connection.
  Dump only the output data on a single connection.
  Dump input and/or output data on I]all] connections.
  Send messages individually instead of batching writes. Implies B]--nagle=off], if not overriden by the command line. Default is C]on].
-w, --workers I]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.


  Control Nagle algorithm by setting C]TCP_NODELAY] socket option using B]setsockopt](). Default is not to call B]setsockopt]() at all, which leaves Nagle I]enabled] on most systems.
--rcvbuf I]SizeBytes]
  Set TCP receive buffers (set C]SO_RCVBUF] socket option using B]setsockopt]()). This option has no effect on some systems with automatic receive buffer management. tcpkali will print a message if B]--rcvbuf] has no effect.
--sndbuf I]SizeBytes]
  Set TCP send buffers (set C]SO_SNDBUF] socket option using B]setsockopt]()). This option has no effect on some systems with automatic receive buffer management. tcpkali will print a message if B]--sndvbuf] has no effect.
--source-ip I]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 B]--source-ip] to override this behavior by specifying a particular source IP to use. Specifying B]--source-ip] option multiple times builds a list of source IPs to use.


--ws, --websocket
  Use RFC6455 WebSocket transport.
-c, --connections I]N]
  Number of concurrent connections to open to the destinations. Default is 1.
--connect-rate I]Rate]
  Limit number of new connections per second. Default is 100 connections per second.
--connect-timeout I]Time]
  Limit time spent in a connection attempt. Default is 1 second.
--channel-lifetime I]Time]
  Shut down each connection after I]Time] seconds.
--channel-bandwidth-upstream I]Bandwidth]
  Limit single connection bandwidth in the outgoing direction.
--channel-bandwidth-downstream I]Bandwidth]
  Limit single connection bandwidth in the incoming direction.
-l, --listen-port I]port]
  Accept connections on the specified port.
  How to behave when a new client connection is received. In the C]silent] mode we do not send data and ignore the data received. This is a default. In the C]active] mode tcpkali sends messages to the connected clients.
-T, --duration I]Time]
  Exit and print final stats after the specified amount of time. Default is 10 seconds (C]-T10s]).


-e, --unescape-message-args
  Unescape the message data specified using the B]-m], B]-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.
  Send this message first, once at the beginning of each connection.
--first-message-file I]filename]
  Read the message from a file and send it once at the beginning of each connection.
-m, --message I]string]
  Repeatedly send the specified message to each destination.
-f, --message-file I]filename]
  Repeatedly send the message read from the file to each destination.
-r, --message-rate I]Rate]
  Messages per second to send in a connection. tcpkali attempts to preserve message boundaries. This setting is mutually incompatible with the B]--channel-bandwidth-upstream] option, because they both control the message sending rate.

    Traffic content expressions

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

Expressions can be of the following forms:

Expression Description   
connection.uid Unique number incremented for each new connection.   
connection.ptr Pointer to a connection structure. Don[aq]t use.   
EXPRESSION % I]int] Remainder of the expression value divided by I]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 B]-em] C][aq]GET /image-\{connection.uid%10}.jpg\r\n\r\n[aq]]

Expressions are evaluated even if the B]-e] option is not given.


tcpkali can measure TCP connect latency, time to first byte, and request-response latencies.
  Measure TCP connect latency.
  Measure latency to first byte. Works only for the active sockets.
tcpkali measures request-response latency by repeatedly recording the time difference between the time the message is sent (as specified by B]-m] or B]-f]) and the time the latency marker is observed in the downstream traffic (as set by B]--latency-marker]).
--latency-marker I]string]
  Specify a per-message sequence of characters to look for in the data stream.
--latency-marker-skip I]N]
  Ignore the first I]N] observations of a B]--latency-marker].
--latency-percentiles I]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 B]--latency-percentiles 50,100]. Default is C]95,99,99.5].


  Enable StatsD output. StatsD output is disabled by default.
--statsd-host I]host]
  StatsD host to send metrics data to. Default is C]localhost].
--statsd-port I]port]
  StatsD port to use. Default is 8125.
--statsd-namespace I]string]
  Metric namespace. Default is "tcpkali".


tcpkali recognizes a number of suffixes for numeric values.

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

I]Rate] and I]Time] can be fractional values, such as 0.25.


1. Throw 42 requests per second (B]-r]) in each of the 10,000 connections (B]-c]) to an HTTP server (B]-m]), replacing \n with newlines (B]-e]):

tcpkali -c10k -r42 -em [aq]GET / HTTP/1.0\r\n\r\n[aq]

2. Create a WebSocket (B]--ws]) server on a specifed port (B]-l]) for an hour (B]-T]), but block clients from actually sending data:

tcpkali --ws -l8080 --channel-bandwidth-downstream=0 -T1h

3. Show server responses (B]--verbose]) when we ping SMTP server once a second (B]--connect-rate]) disconnecting promptly (B]--channel-lifetime]):

tcpkali --connect-rate=1 --channel-lifetime=0.1 -vvv


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

...for N connections, such as 50k:
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 ]


[bu] On TIME-WAIT state and its reuse:
[bu] On netfliter settings:


Lev Walkin <>.
Search for    or go to Top of page |  Section 1 |  Main Index

TCPKali user manual TCPKALI (1) 2016-01-15

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.