NAME

       ovs-benchmark - flow setup benchmark utility for Open vSwitch

SYNOPSIS

       ovs-benchmark latency --remote ip[:ports] [--sockets nsocks] [--batches nbatches] [--local [ip][:ports]]

       ovs-benchmark rate --remote ip[:ports] [--max-rate rate] [--timeout maxsecs] [--sockets nsocks]
                          [--batches nbatches] [--local [ip][:ports]]

       ovs-benchmark listen [--local [ip]:ports]

       ovs-benchmark help

DESCRIPTION

       ovs-benchmark  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.

       Each ovs-benchmark command is described separately below.

The ``latency'' command

       This  command  initiates  nsocks 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 . or ! symbols, one for each TCP connection that completed  in  that
       many milliseconds.  A successful connection prints a ., and an unsuccessful connection (e.g. to a port on
       which no process is listening) prints a !.

       If  nbatches  is  given,  the  entire procedure is repeated the specified number of times.  Only a single
       summary line is printed at the end.

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

The ``rate'' command

       This command initiates nsocks TCP connections (by default,  100)  as  quickly  as  possible  (limited  by
       maxrate,  if  --max-rate  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 --timeout is
       specified, until maxsecs 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.

       Without  --max-rate,  the rate command measures the maximum sustained flow setup rate for an Open vSwitch
       instance.  This naturally tends to drive ovs-vswitchd CPU  usage  to  100%  on  the  host  receiving  the
       traffic.

       When  --max-rate  is  specified  with  a  value  below the maximum rate that an Open vSwitch instance can
       handle, then rate can also be used to measure the kernel  and  userspace  CPU  cost  of  flow  setups  at
       specific flow rates.

       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.

The ``listen'' command

       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 rate or latency commands  for  observing  effects  of
       successful vs. unsuccessful TCP connections.

       It  is  easier  to  reproduce  and  interpret  ovs-benchmark results when there is no listener (see NOTES
       below).

The ``help'' command

       Prints a usage message and exits successfully.

OPTIONS

       -r ip[:ports]
       --remote ip[:ports]
              This option, required on latency and rate commands, minimally specifies the remote host to connect
              to (as an IP address or DNS name) as ip.

              A TCP port or range of ports (separated by -) 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.

       -l [ip][:ports]
       --local [ip][:ports]
              On  the  latency  and rate, 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
              --local  and  --remote,  then  each local port in its range will be used before the remote port is
              incremented to the next port in its range.)

              On the listen 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.

       -s nsocks
       --sockets nsocks
              For  latency,  sets the number of connections to initiate per batch.  For rate, sets the number of
              outstanding connections attempts to maintain at any given time.  The default is 100.

       -b nbatches
       --batches nbatches
              For latency, sets the number of times to initiate and wait for all of the connections to complete.
              The default is 1.

       -c maxrate
       --max-rate maxrate
              For rate, caps the maximum rate at which connections will be attempted to maxrate connections  per
              second.  By default there is no limit.

       -T maxsecs
       --timeout maxsecs
              For  rate,  stops  the  benchmark  after  maxsecs seconds have elapsed.  By default, the benchmark
              continues until interrupted by a signal.

NOTES

       ovs-benchmark 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 ovs-benchmark 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.  ovs-benchmark 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.

       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., iptables -F.

       ovs-benchmark  is  single-threaded.   A  multithreaded process might be able to initiate connections more
       quickly.

       A TCP connection consists of two flows (one in each direction), so multiply the TCP connection statistics
       that ovs-benchmark reports by 2 to get flow statistics.

Open vSwitch                                          2.5.9                                     ovs-benchmark(1)