path: root/utilities/ovs-benchmark.1.in

.\" -*- nroff -*-
.so lib/ovs.tmac
.TH ovs\-benchmark 1 "@VERSION@" "Open vSwitch" "Open vSwitch Manual"
.
.SH NAME
ovs\-benchmark \- flow setup benchmark utility for Open vSwitch
.
.SH SYNOPSIS
.
.SY ovs\-benchmark\ latency
\fB\-\-remote \fIip\fR[\fB:\fIports\fR]
.OP \-\-sockets nsocks
.OP \-\-batches nbatches
.OP \-\-local \fR[\fIip\fR][\fB:\fIports\fR]
.YS
.
.SY ovs\-benchmark\ rate
\fB\-\-remote \fIip\fR[\fB:\fIports\fR]
.OP \-\-max\-rate rate
.OP \-\-timeout maxsecs
.OP \-\-sockets nsocks
.OP \-\-batches nbatches
.OP \-\-local \fR[\fIip\fR][\fB:\fIports\fR]
.YS
.
.SY ovs\-benchmark\ listen
.OP \-\-local \fR[\fIip\fR]\fB:\fIports
.YS
.
.SY ovs\-benchmark\ help
.YS
.
.SH DESCRIPTION
\fBovs\-benchmark\fR tests the performance of Open vSwitch flow setup
by setting up a number of TCP connections and measuring the time
required.  It can also be used with the Linux bridge or without any
bridging software, which allows one to measure the bandwidth and
latency cost of bridging.
.PP
Each \fBovs\-benchmark\fR command is described separately below.
.
.SH "The ``latency'' command"
.
.PP
This command initiates \fInsocks\fR TCP connections (by default, 100)
as quickly as possible, waits for each one to complete with success or
failure, and prints a bar chart of completion times on standard
output, followed by a summary line.  Each line in the bar chart lists
a time to connection completion in milliseconds followed by a number
of \fB.\fR or \fB!\fR symbols, one for each TCP connection that
completed in that many milliseconds.  A successful connection prints a
\fB.\fR, and an unsuccessful connection (e.g. to a port on which no
process is listening) prints a \fB!\fR.
.
.PP
If \fInbatches\fR is given, the entire procedure is repeated the
specified number of times.  Only a single summary line is printed at
the end.
.
.PP
Results vary widely based on the number of sockets and whether the
remote host is listening for connections on the specified ports.  With
a small number of sockets, all connection times typically remain
within a handful of milliseconds.  As the number of sockets increases,
the distribution of connection times clusters around the sending TCP
stack's SYN retransmission interval.  (This pattern occurs with or
without Open vSwitch on the network path.)
.
.SH "The ``rate'' command"
.
.PP
This command initiates \fInsocks\fR TCP connections (by default, 100)
as quickly as possible (limited by \fImaxrate\fR, if
\fB\-\-max\-rate\fR is specified).  Each time a connection completes
with success or failure, it closes that connection and initiates a new
one.  It continues to do so either forever or, if \fB\-\-timeout\fR is
specified, until \fImaxsecs\fR seconds have elapsed.  During the test,
it prints statistics about time elapsed, successful and unsuccessful
connections, and the average number of completed (succeeded or failed)
connections per second over the run.
.
.PP
Without \fB\-\-max\-rate\fR, the \fBrate\fR command measures the
maximum sustained flow setup rate for an Open vSwitch instance.  This
naturally tends to drive \fBovs\-vswitchd\fR CPU usage to 100% on the
host receiving the traffic.
.
.PP
When \fB\-\-max\-rate\fR is specified with a value below the maximum
rate that an Open vSwitch instance can handle, then \fBrate\fR can
also be used to measure the kernel and userspace CPU cost of flow
setups at specific flow rates.
.
.PP
Results tend to fluctuate greatly for the first few seconds of a run,
then settle down.  The displayed average is calculated over the entire
run and so tends to converge asymptotically on the ``correct'' value.
To converge more quickly, try running for 5 to 10 seconds, then
killing and restarting the run.
.
.SH "The ``listen'' command"
.
.PP
This command listens on one or more TCP ports for incoming
connections.  It accepts connections and immediately closes them.  It
can be paired with the \fBrate\fR or \fBlatency\fR commands for
observing effects of successful vs. unsuccessful TCP connections.
.
.PP
It is easier to reproduce and interpret \fBovs\-benchmark\fR results
when there is no listener (see \fBNOTES\fR below).
.
.SH "The ``help'' command"
.
.PP
Prints a usage message and exits successfully.
.
.SH OPTIONS
.
.IP "\fB\-r \fIip\fR[\fB:\fIports\fR]"
.IQ "\fB\-\-remote \fIip\fR[\fB:\fIports\fR]"
This option, required on \fBlatency\fR and \fBrate\fR commands,
minimally specifies the remote host to connect to (as an IP address or
DNS name) as \fIip\fR.
.
.IP
A TCP port or range of ports (separated by \fB\-\fR) may also be
specified.  If a range is specified then each port in the range is
used in round-robin order.  The default port is 6630 if none is
specified.
.
.IP "\fB\-l \fR[\fIip\fR][\fB:\fIports\fR]"
.IQ "\fB\-\-local \fR[\fIip\fR][\fB:\fIports\fR]"
On the \fBlatency\fR and \fBrate\fR, without this option, outgoing
connections will not bind a specific TCP port.  The local TCP stack
will pick a local TCP port to bind.  When this option is specified,
the specified port or range of ports will be used in turn.  (If a port
range is specified on both \fB\-\-local\fR and \fB\-\-remote\fR, then
each local port in its range will be used before the remote port is
incremented to the next port in its range.)
.
.IP
On the \fBlisten\fR command, this option specifies the local port or
ports and IP addresses on which to listen.  If it is omitted, port
6630 on any IP address is used.
.
.IP "\fB\-s \fInsocks\fR"
.IQ "\fB\-\-sockets \fInsocks\fR"
For \fBlatency\fR, sets the number of connections to initiate per
batch.  For \fBrate\fR, sets the number of outstanding connections
attempts to maintain at any given time.  The default is 100.
.
.IP "\fB\-b \fInbatches\fR"
.IQ "\fB\-\-batches \fInbatches\fR"
For \fBlatency\fR, sets the number of times to initiate and wait for
all of the connections to complete.  The default is 1.
.
.IP "\fB\-c \fImaxrate\fR"
.IQ "\fB\-\-max\-rate \fImaxrate\fR"
For \fBrate\fR, caps the maximum rate at which connections will be
attempted to \fImaxrate\fR connections per second.  By default there
is no limit.
.
.IP "\fB\-T \fImaxsecs\fR"
.IQ "\fB\-\-timeout \fImaxsecs\fR"
For \fBrate\fR, stops the benchmark after \fImaxsecs\fR seconds have
elapsed.  By default, the benchmark continues until interrupted by a
signal.
.
.SH NOTES
.PP
\fBovs\-benchmark\fR uses standard POSIX socket calls for network
access, so it shares the strengths and limitations of TCP/IP and its
implementations in the local and remote TCP/IP stacks.  Particularly,
TCP and its implementations limit the number of successfully completed
and then closed TCP connections.  This means that \fBovs\-benchmark\fR
tests tend to slow down if run for long intervals or with large
numbers of sockets or batches, if the remote system is listening on
the port or ports being contacted.  The problem does not occur when
the remote system is not listening.  \fBovs\-benchmark\fR results are
therefore much more reliable and repeatable when the remote system is
not listening on the port or ports being contacted.  Even a single
listening socket (e.g. range of ports 8000 to 9000 with one listener
on port 8080) can cause anomalies in results.
.
.PP
Be sure that the remote TCP/IP stack's firewall allows the benchmark's
traffic to be processed.  For Open vSwitch benchmarking purposes, you
might want to disable the firewall with, e.g., \fBiptables \-F\fR.
.
.PP
\fBovs\-benchmark\fR is single-threaded.  A multithreaded process
might be able to initiate connections more quickly.
.
.PP
A TCP connection consists of two flows (one in each direction), so
multiply the TCP connection statistics that \fBovs\-benchmark\fR
reports by 2 to get flow statistics.