utilities/ovs-test.8.in

   1 .de IQ
   2 .  br
   3 .  ns
   4 .  IP "\\$1"
   5 ..
   6 .TH ovs\-test 1 "@VERSION@" "Open vSwitch" "Open vSwitch Manual"
   7 .
   8 .SH NAME
   9 \fBovs\-test\fR \- check Linux drivers for performance, vlan and L3 tunneling
  10 problems
  11 .
  12 .SH SYNOPSIS
  13 \fBovs\-test\fR \fB\-s\fR \fIport\fR
  14 .PP
  15 \fBovs\-test\fR \fB\-c\fR \fIserver1\fR \fIserver2\fR
  16 [\fB\-b\fR \fItargetbandwidth\fR] [\fB\-i\fR \fItestinterval\fR]
  17 [\fB\-d\fR]
  18 [\fB\-l\fR \fIvlantag\fR]
  19 [\fB\-t\fR \fItunnelmodes\fR]
  20 .so lib/common-syn.man
  21 .
  22 .SH DESCRIPTION
  23 The \fBovs\-test\fR program may be used to check for problems sending
  24 802.1Q or GRE traffic that Open vSwitch may uncover. These problems,
  25 for example, can occur when Open vSwitch is used to send 802.1Q traffic
  26 through physical interfaces running certain drivers of certain Linux kernel
  27 versions. To run a test, configure IP addresses on \fIserver1\fR and
  28 \fIserver2\fR for interfaces you intended to test. These interfaces could
  29 also be already configured OVS bridges that have a physical interface attached
  30 to them. Then, on one of the nodes, run \fBovs\-test\fR in server mode and on
  31 the other node run it in client mode. The client will connect to
  32 \fBovs\-test\fR server and schedule tests between both of them. The
  33 \fBovs\-test\fR client will perform UDP and TCP tests.
  34 .PP
  35 UDP tests can report packet loss and achieved bandwidth for various
  36 datagram sizes. By default target bandwidth for UDP tests is 1Mbit/s.
  37 .PP
  38 TCP tests report only achieved bandwidth, because kernel TCP stack
  39 takes care of flow control and packet loss. TCP tests are essential to detect
  40 potential TSO related issues.
  41 .PP
  42 To determine whether Open vSwitch is encountering any problems,
  43 the user must compare packet loss and achieved bandwidth in a setup where
  44 traffic is being directly sent and in one where it is not. If in the
  45 802.1Q or L3 tunneled tests both \fBovs\-test\fR processes are unable to
  46 communicate or the achieved bandwidth is much lower compared to direct setup,
  47 then, most likely, Open vSwitch has encountered a pre-existing kernel or
  48 driver bug.
  49 .PP
  50 Some examples of the types of problems that may be encountered are:
  51 .so utilities/ovs-vlan-bugs.man
  52 .
  53 .SS "Client Mode"
  54 An \fBovs\-test\fR client will connect to two \fBovs\-test\fR servers and
  55 will ask them to exchange test traffic. It is also possible to spawn an
  56 \fBovs\-test\fR server automatically from the client.
  57 .
  58 .SS "Server Mode"
  59 To conduct tests, two \fBovs\-test\fR servers must be running on two different
  60 hosts where the client can connect. The actual test traffic is exchanged only
  61 between both \fBovs\-test\fR servers. It is recommended that both servers have
  62 their IP addresses in the same subnet, otherwise one would have to make sure
  63 that routing is set up correctly.
  64 .
  65 .SH OPTIONS
  66 .
  67 .IP "\fB\-s \fIport\fR"
  68 .IQ "\fB\-\-server\fR \fIport\fR"
  69 Run in server mode and wait for the client to establish XML RPC Control
  70 Connection on this TCP \fIport\fR. It is recommended to have \fBethtool\fR(8)
  71 installed on the server so that it could retrieve information about the NIC
  72 driver.
  73 .
  74 .IP "\fB\-c \fIserver1\fR \fIserver2\fR"
  75 .IQ "\fB\-\-client \fIserver1\fR \fIserver2\fR"
  76 Run in client mode and schedule tests between \fIserver1\fR and \fIserver2\fR,
  77 where each \fIserver\fR must be given in the following format -
  78 \fIOuterIP[:OuterPort],InnerIP[/Mask][:InnerPort]\fR. The \fIOuterIP\fR must
  79 be already assigned to the physical interface which is going to be tested.
  80 This is the IP address where client will try to establish XML RPC connection.
  81 If \fIOuterIP\fR is 127.0.0.1 then client will automatically spawn a local
  82 instance of \fBovs\-test\fR server. \fIOuterPort\fR is TCP port where server
  83 is listening for incoming XML/RPC control connections to schedule tests (by
  84 default it is 15531). The \fBovs\-test\fR will automatically assign
  85 \fIInnerIP[/Mask]\fR to the interfaces that will be created on the fly for
  86 testing purposes. It is important that \fIInnerIP[/Mask]\fR does not interfere
  87 with already existing IP addresses on both \fBovs\-test\fR servers and client.
  88 \fIInnerPort\fR is port which will be used by server to listen for test
  89 traffic that will be encapsulated (by default it is 15532).
  90 .
  91 .IP "\fB\-b \fItargetbandwidth\fR"
  92 .IQ "\fB\-\-bandwidth\fR \fItargetbandwidth\fR"
  93 Target bandwidth for UDP tests. The \fItargetbandwidth\fR must be given in
  94 bits per second. It is possible to use postfix M or K to alter the target
  95 bandwidth magnitude.
  96 .
  97 .IP "\fB\-i \fItestinterval\fR"
  98 .IQ "\fB\-\-interval\fR \fItestinterval\fR"
  99 How long each test should run. By default 5 seconds.
 100 .
 101 .so lib/common.man
 102 .
 103 .SH "Test Modes"
 104 The following test modes are supported by \fBovs\-test\fR. It is possible
 105 to combine multiple of them in a single \fBovs\-test\fR invocation.
 106 .
 107 .IP "\fB\-d \fR"
 108 .IQ "\fB\-\-direct\fR"
 109 Perform direct tests between both \fIOuterIP\fR addresses. These tests could
 110 be used as a reference to compare 802.1Q or L3 tunneling test results.
 111 .
 112 .IP "\fB\-l \fIvlantag\fR"
 113 .IQ "\fB\-\-vlan\-tag\fR \fIvlantag\fR"
 114 Perform 802.1Q tests between both servers. These tests will create a temporary
 115 OVS bridge, if necessary, and attach a VLAN tagged port to it for testing
 116 purposes.
 117 .
 118 .IP "\fB\-t \fItunnelmodes\fR"
 119 .IQ "\fB\-\-tunnel\-modes\fR \fItunnelmodes\fR"
 120 Perform L3 tunneling tests. The given argument is a comma separated string
 121 that specifies all the L3 tunnel modes that should be tested (e.g. gre). The L3
 122 tunnels are terminated on interface that has the \fIOuterIP\fR address
 123 assigned.
 124 .
 125 .SH EXAMPLES
 126 .PP
 127 On host 1.2.3.4 start \fBovs\-test\fR in server mode:
 128 .IP
 129 .B ovs\-test \-s 15531
 130 .
 131 .PP
 132 On host 1.2.3.5 start \fBovs\-test\fR in client mode and do direct, VLAN and
 133 GRE tests between both nodes:
 134 .IP
 135 .B ovs\-test \-c 127.0.0.1,1.1.1.1/30 1.2.3.4,1.1.1.2/30 -d -l 123 -t gre
 136 .
 137 .SH SEE ALSO
 138 .
 139 .BR ovs\-vswitchd (8),
 140 .BR ovs\-ofctl (8),
 141 .BR ovs\-vsctl (8),
 142 .BR ovs\-vlan\-test (8),
 143 .BR ethtool (8),
 144 .BR uname (1)