ovs-benchmark(1)						Open vSwitch Manual						  ovs-benchmark(1)

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,  suc-
       cessful 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  incre-
	      mented 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  sig-
	      nal.

NOTES

       ovs-benchmark uses standard POSIX socket calls for network access, so it shares the strengths and limitations of TCP/IP and its implementa-
       tions 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 anom-
       alies 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							     July 2011							  ovs-benchmark(1)