utilities/ovs-benchmark.1.in

   1 .\" -*- nroff -*-
   2 .so lib/ovs.tmac
   3 .TH ovs\-benchmark 1 "@VERSION@" "Open vSwitch" "Open vSwitch Manual"
   4 .
   5 .SH NAME
   6 ovs\-benchmark \- flow setup benchmark utility for Open vSwitch
   7 .
   8 .SH SYNOPSIS
   9 .
  10 .SY ovs\-benchmark\ latency
  11 \fB\-\-remote \fIip\fR[\fB:\fIports\fR]
  12 .OP \-\-sockets nsocks
  13 .OP \-\-batches nbatches
  14 .OP \-\-local \fR[\fIip\fR][\fB:\fIports\fR]
  15 .YS
  16 .
  17 .SY ovs\-benchmark\ rate
  18 \fB\-\-remote \fIip\fR[\fB:\fIports\fR]
  19 .OP \-\-max\-rate rate
  20 .OP \-\-timeout maxsecs
  21 .OP \-\-sockets nsocks
  22 .OP \-\-batches nbatches
  23 .OP \-\-local \fR[\fIip\fR][\fB:\fIports\fR]
  24 .YS
  25 .
  26 .SY ovs\-benchmark\ listen
  27 .OP \-\-local \fR[\fIip\fR]\fB:\fIports
  28 .YS
  29 .
  30 .SY ovs\-benchmark\ help
  31 .YS
  32 .
  33 .SH DESCRIPTION
  34 \fBovs\-benchmark\fR tests the performance of Open vSwitch flow setup
  35 by setting up a number of TCP connections and measuring the time
  36 required.  It can also be used with the Linux bridge or without any
  37 bridging software, which allows one to measure the bandwidth and
  38 latency cost of bridging.
  39 .PP
  40 Each \fBovs\-benchmark\fR command is described separately below.
  41 .
  42 .SH "The ``latency'' command"
  43 .
  44 .PP
  45 This command initiates \fInsocks\fR TCP connections (by default, 100)
  46 as quickly as possible, waits for each one to complete with success or
  47 failure, and prints a bar chart of completion times on standard
  48 output, followed by a summary line.  Each line in the bar chart lists
  49 a time to connection completion in milliseconds followed by a number
  50 of \fB.\fR or \fB!\fR symbols, one for each TCP connection that
  51 completed in that many milliseconds.  A successful connection prints a
  52 \fB.\fR, and an unsuccessful connection (e.g. to a port on which no
  53 process is listening) prints a \fB!\fR.
  54 .
  55 .PP
  56 If \fInbatches\fR is given, the entire procedure is repeated the
  57 specified number of times.  Only a single summary line is printed at
  58 the end.
  59 .
  60 .PP
  61 Results vary widely based on the number of sockets and whether the
  62 remote host is listening for connections on the specified ports.  With
  63 a small number of sockets, all connection times typically remain
  64 within a handful of milliseconds.  As the number of sockets increases,
  65 the distribution of connection times clusters around the sending TCP
  66 stack's SYN retransmission interval.  (This pattern occurs with or
  67 without Open vSwitch on the network path.)
  68 .
  69 .SH "The ``rate'' command"
  70 .
  71 .PP
  72 This command initiates \fInsocks\fR TCP connections (by default, 100)
  73 as quickly as possible (limited by \fImaxrate\fR, if
  74 \fB\-\-max\-rate\fR is specified).  Each time a connection completes
  75 with success or failure, it closes that connection and initiates a new
  76 one.  It continues to do so either forever or, if \fB\-\-timeout\fR is
  77 specified, until \fImaxsecs\fR seconds have elapsed.  During the test,
  78 it prints statistics about time elapsed, successful and unsuccessful
  79 connections, and the average number of completed (succeeded or failed)
  80 connections per second over the run.
  81 .
  82 .PP
  83 Without \fB\-\-max\-rate\fR, the \fBrate\fR command measures the
  84 maximum sustained flow setup rate for an Open vSwitch instance.  This
  85 naturally tends to drive \fBovs\-vswitchd\fR CPU usage to 100% on the
  86 host receiving the traffic.
  87 .
  88 .PP
  89 When \fB\-\-max\-rate\fR is specified with a value below the maximum
  90 rate that an Open vSwitch instance can handle, then \fBrate\fR can
  91 also be used to measure the kernel and userspace CPU cost of flow
  92 setups at specific flow rates.
  93 .
  94 .PP
  95 Results tend to fluctuate greatly for the first few seconds of a run,
  96 then settle down.  The displayed average is calculated over the entire
  97 run and so tends to converge asymptotically on the ``correct'' value.
  98 To converge more quickly, try running for 5 to 10 seconds, then
  99 killing and restarting the run.
 100 .
 101 .SH "The ``listen'' command"
 102 .
 103 .PP
 104 This command listens on one or more TCP ports for incoming
 105 connections.  It accepts connections and immediately closes them.  It
 106 can be paired with the \fBrate\fR or \fBlatency\fR commands for
 107 observing effects of successful vs. unsuccessful TCP connections.
 108 .
 109 .PP
 110 It is easier to reproduce and interpret \fBovs\-benchmark\fR results
 111 when there is no listener (see \fBNOTES\fR below).
 112 .
 113 .SH "The ``help'' command"
 114 .
 115 .PP
 116 Prints a usage message and exits successfully.
 117 .
 118 .SH OPTIONS
 119 .
 120 .IP "\fB\-r \fIip\fR[\fB:\fIports\fR]"
 121 .IQ "\fB\-\-remote \fIip\fR[\fB:\fIports\fR]"
 122 This option, required on \fBlatency\fR and \fBrate\fR commands,
 123 minimally specifies the remote host to connect to (as an IP address or
 124 DNS name) as \fIip\fR.
 125 .
 126 .IP
 127 A TCP port or range of ports (separated by \fB\-\fR) may also be
 128 specified.  If a range is specified then each port in the range is
 129 used in round-robin order.  The default port is 6630 if none is
 130 specified.
 131 .
 132 .IP "\fB\-l \fR[\fIip\fR][\fB:\fIports\fR]"
 133 .IQ "\fB\-\-local \fR[\fIip\fR][\fB:\fIports\fR]"
 134 On the \fBlatency\fR and \fBrate\fR, without this option, outgoing
 135 connections will not bind a specific TCP port.  The local TCP stack
 136 will pick a local TCP port to bind.  When this option is specified,
 137 the specified port or range of ports will be used in turn.  (If a port
 138 range is specified on both \fB\-\-local\fR and \fB\-\-remote\fR, then
 139 each local port in its range will be used before the remote port is
 140 incremented to the next port in its range.)
 141 .
 142 .IP
 143 On the \fBlisten\fR command, this option specifies the local port or
 144 ports and IP addresses on which to listen.  If it is omitted, port
 145 6630 on any IP address is used.
 146 .
 147 .IP "\fB\-s \fInsocks\fR"
 148 .IQ "\fB\-\-sockets \fInsocks\fR"
 149 For \fBlatency\fR, sets the number of connections to initiate per
 150 batch.  For \fBrate\fR, sets the number of outstanding connections
 151 attempts to maintain at any given time.  The default is 100.
 152 .
 153 .IP "\fB\-b \fInbatches\fR"
 154 .IQ "\fB\-\-batches \fInbatches\fR"
 155 For \fBlatency\fR, sets the number of times to initiate and wait for
 156 all of the connections to complete.  The default is 1.
 157 .
 158 .IP "\fB\-c \fImaxrate\fR"
 159 .IQ "\fB\-\-max\-rate \fImaxrate\fR"
 160 For \fBrate\fR, caps the maximum rate at which connections will be
 161 attempted to \fImaxrate\fR connections per second.  By default there
 162 is no limit.
 163 .
 164 .IP "\fB\-T \fImaxsecs\fR"
 165 .IQ "\fB\-\-timeout \fImaxsecs\fR"
 166 For \fBrate\fR, stops the benchmark after \fImaxsecs\fR seconds have
 167 elapsed.  By default, the benchmark continues until interrupted by a
 168 signal.
 169 .
 170 .SH NOTES
 171 .PP
 172 \fBovs\-benchmark\fR uses standard POSIX socket calls for network
 173 access, so it shares the strengths and limitations of TCP/IP and its
 174 implementations in the local and remote TCP/IP stacks.  Particularly,
 175 TCP and its implementations limit the number of successfully completed
 176 and then closed TCP connections.  This means that \fBovs\-benchmark\fR
 177 tests tend to slow down if run for long intervals or with large
 178 numbers of sockets or batches, if the remote system is listening on
 179 the port or ports being contacted.  The problem does not occur when
 180 the remote system is not listening.  \fBovs\-benchmark\fR results are
 181 therefore much more reliable and repeatable when the remote system is
 182 not listening on the port or ports being contacted.  Even a single
 183 listening socket (e.g. range of ports 8000 to 9000 with one listener
 184 on port 8080) can cause anomalies in results.
 185 .
 186 .PP
 187 Be sure that the remote TCP/IP stack's firewall allows the benchmark's
 188 traffic to be processed.  For Open vSwitch benchmarking purposes, you
 189 might want to disable the firewall with, e.g., \fBiptables \-F\fR.
 190 .
 191 .PP
 192 \fBovs\-benchmark\fR is single-threaded.  A multithreaded process
 193 might be able to initiate connections more quickly.
 194 .
 195 .PP
 196 A TCP connection consists of two flows (one in each direction), so
 197 multiply the TCP connection statistics that \fBovs\-benchmark\fR
 198 reports by 2 to get flow statistics.