GSP
Quick Navigator
Search Site

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

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
tcpkali(1) Version 1.1.1 tcpkali(1)

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

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

tcpkali is a tool that helps stress-test and bench TCP and WebSocket based systems. 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.

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

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).

-h, --help
Print a help screen, then exit.
--version
Print version number, then exit.
-v, --verbose level
Increase (-v) or set (--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-one-in
Dump only the input data on a single connection.
--dump-one-out
Dump only the output data on a single connection.
--dump-{all,all-in,all-out}
Dump input and/or output data on all connections.
--write-combine=off
Send messages individually instead of batching writes. Implies --nagle=off, if not overriden by the command line. Default is on.
-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.

--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.
--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.
--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.
--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.

--ws, --websocket
Use RFC6455 WebSocket transport.
-H, --header
Add HTTP header into the WebSocket handshake.
-c, --connections N
Number of concurrent connections to open to the destinations. Default is 1.
--connect-rate Rate
Limit number of new connections per second. Default is 100 connections per second.
--connect-timeout Time
Limit time spent in a connection attempt. Default is 1 second.
--channel-lifetime Time
Shut down each connection after Time seconds.
--channel-bandwidth-upstream Bandwidth
Limit single connection bandwidth in the outgoing direction.
--channel-bandwidth-downstream Bandwidth
Limit single connection bandwidth in the incoming direction.
-l, --listen-port port
Accept connections on the specified port.
--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.
-T, --duration Time
Exit and print final stats after the specified amount of time. Default is 10 seconds (-T10s).

-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.
-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-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.
-m, --message string
Repeatedly send the specified message to each destination. This option can be specified several times.
--message-stop string
Terminate tcpkali if the given string is encountered in the incoming byte stream.
-f, --message-file filename
Repeatedly send the message read from the file to each destination. This option can be specified several times.
-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.
-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.

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

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:

Expression Description
connection.uid Unique number incremented for each new connection.
connection.ptr Pointer to a connection structure. Don't use.
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.

tcpkali can measure TCP connect latency, time to first byte, and request-response latencies.
--latency-connect
Measure TCP connect latency.
--latency-first-byte
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 -m or -f) and the time the latency marker is observed in the downstream traffic (as set by --latency-marker).

--latency-marker string
Specify a per-message sequence of characters to look for in the data stream.
--latency-marker-skip N
Ignore the first N observations of a --latency-marker.
--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.
--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.

--statsd
Enable StatsD output. StatsD output is disabled by default.
--statsd-host host
StatsD host to send metrics data to. Default is localhost.
--statsd-port port
StatsD port to use. Default is 8125.
--statsd-namespace string
Metric namespace. Default is "tcpkali".
--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.

tcpkali recognizes a number of suffixes for numeric values.
Placeholder Recognized unit suffixes
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.

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

tcpkali -c10k -r42 -em 'GET / HTTP/1.0\r\n\r\n' nonexistent.com:80

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

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

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

tcpkali --connect-rate=1 --channel-lifetime=0.1 -vvv nonexistent.org:smtp

...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

•
On TIME-WAIT state and its reuse:

http://vincent.bernat.im/en/blog/2014-tcp-time-wait-state-linux.html

•
On netfliter settings:

http://serverfault.com/questions/482480/

Lev Walkin <lwalkin@machinezone.com>.
2017-01-20 TCPKali user manual
Search for    or go to Top of page |  Section 1 |  Main Index

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