--- /dev/null
+.\" -*- nroff -*-
+.de IQ
+. br
+. ns
+. IP "\\$1"
+..
+.TH ovs\-benchmark 1 "July 2011" "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.
git://git.onelab.eu / sliver-openvswitch.git / blobdiff