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


Manual Reference Pages  -  TCPKALI (1)

NAME

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

CONTENTS

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

SYNOPSIS

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

DESCRIPTION

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

OPTIONS

    GENERAL OPTIONS

-h, --help Print a help screen, then exit.
--version
  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-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 I]all] connections.
--write-combine=off
  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.

    NETWORK STACK SETTINGS

--nagle=on|off
  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.

    TEST RUN OPTIONS

--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.
--listen-mode=silent|active
  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]).

    TRAFFIC CONTENT OPTIONS

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

    LATENCY MEASUREMENT OPTIONS

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

    STATSD OPTIONS

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

VARIABLE UNITS

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.

EXAMPLES

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] nonexistent.com:80

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 nonexistent.org:smtp

SEE ALSO

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

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

[bu] On TIME-WAIT state and its reuse:
http://vincent.bernat.im/en/blog/2014-tcp-time-wait-state-linux.html
[bu] On netfliter settings:
http://serverfault.com/questions/482480/

AUTHORS

Lev Walkin <lwalkin@machinezone.com>.
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.