utilities/ovs-benchmark.1.in

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