From patchwork Wed Jun 12 07:19:11 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Numan Siddique X-Patchwork-Id: 1114325 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (mailfrom) smtp.mailfrom=openvswitch.org (client-ip=140.211.169.12; helo=mail.linuxfoundation.org; envelope-from=ovs-dev-bounces@openvswitch.org; receiver=) Authentication-Results: ozlabs.org; dmarc=fail (p=none dis=none) header.from=redhat.com Received: from mail.linuxfoundation.org (mail.linuxfoundation.org [140.211.169.12]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 45Nywl5DH5z9s9y for ; Wed, 12 Jun 2019 17:21:43 +1000 (AEST) Received: from mail.linux-foundation.org (localhost [127.0.0.1]) by mail.linuxfoundation.org (Postfix) with ESMTP id 88A84160D; Wed, 12 Jun 2019 07:20:51 +0000 (UTC) X-Original-To: dev@openvswitch.org Delivered-To: ovs-dev@mail.linuxfoundation.org Received: from smtp1.linuxfoundation.org (smtp1.linux-foundation.org [172.17.192.35]) by mail.linuxfoundation.org (Postfix) with ESMTPS id E18A915EA for ; Wed, 12 Jun 2019 07:19:22 +0000 (UTC) X-Greylist: domain auto-whitelisted by SQLgrey-1.7.6 Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) by smtp1.linuxfoundation.org (Postfix) with ESMTPS id 1E7A37F8 for ; Wed, 12 Jun 2019 07:19:21 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.phx2.redhat.com [10.5.11.22]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 6BBEB7FDF0 for ; Wed, 12 Jun 2019 07:19:20 +0000 (UTC) Received: from nusiddiq.mac (unknown [10.74.10.39]) by smtp.corp.redhat.com (Postfix) with ESMTP id DA6611001B03 for ; Wed, 12 Jun 2019 07:19:18 +0000 (UTC) From: nusiddiq@redhat.com To: dev@openvswitch.org Date: Wed, 12 Jun 2019 12:49:11 +0530 Message-Id: <20190612071911.24340-1-nusiddiq@redhat.com> In-Reply-To: <20190612071822.24182-1-nusiddiq@redhat.com> References: <20190612071822.24182-1-nusiddiq@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.5.11.22 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.27]); Wed, 12 Jun 2019 07:19:20 +0000 (UTC) X-Spam-Status: No, score=-6.9 required=5.0 tests=BAYES_00,RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on smtp1.linux-foundation.org Subject: [ovs-dev] [PATCH ovn 2/4] Documentation cleanup: ref section X-BeenThere: ovs-dev@openvswitch.org X-Mailman-Version: 2.1.12 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: ovs-dev-bounces@openvswitch.org Errors-To: ovs-dev-bounces@openvswitch.org From: Numan Siddique Signed-off-by: Numan Siddique Acked-by: Ben Pfaff --- Documentation/automake.mk | 2 - Documentation/conf.py | 4 - .../contributing/documentation-style.rst | 2 +- Documentation/ref/index.rst | 106 ------------ Documentation/ref/ovs-test.8.rst | 163 ------------------ Documentation/ref/ovs-vlan-test.8.rst | 113 ------------ 6 files changed, 1 insertion(+), 389 deletions(-) delete mode 100644 Documentation/ref/ovs-test.8.rst delete mode 100644 Documentation/ref/ovs-vlan-test.8.rst diff --git a/Documentation/automake.mk b/Documentation/automake.mk index 181a69cab..c3b0949bd 100644 --- a/Documentation/automake.mk +++ b/Documentation/automake.mk @@ -107,8 +107,6 @@ endif # rST formatted manpages under Documentation/ref. RST_MANPAGES = \ - ovs-test.8.rst \ - ovs-vlan-test.8.rst \ ovsdb-server.7.rst \ ovsdb.5.rst \ ovsdb.7.rst diff --git a/Documentation/conf.py b/Documentation/conf.py index 0a61dc3f3..6bf528bde 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -116,10 +116,6 @@ html_static_path = ['_static'] _man_pages = [ ('ovs-sim.1', u'Open vSwitch simulator environment'), - ('ovs-test.8', - u'Check Linux drivers for performance, vlan and L3 tunneling problems'), - ('ovs-vlan-test.8', - u'Check Linux drivers for problems with vlan traffic'), ('ovsdb-server.7', u'Open vSwitch Database Server Protocol'), ('ovsdb.5', diff --git a/Documentation/internals/contributing/documentation-style.rst b/Documentation/internals/contributing/documentation-style.rst index deb07d9f5..0b67ae2aa 100644 --- a/Documentation/internals/contributing/documentation-style.rst +++ b/Documentation/internals/contributing/documentation-style.rst @@ -347,7 +347,7 @@ In addition to the above, man pages have some specific requirements: - The man page must be included in the list of man page documents found in `conf.py`__ -Refer to existing man pages, such as :doc:`/ref/ovs-vlan-test.8` for a worked +Refer to existing man pages, such as :doc:`/ref/ovsdb-server.7` for a worked example. __ http://www.sphinx-doc.org/en/stable/domains.html#directive-program diff --git a/Documentation/ref/index.rst b/Documentation/ref/index.rst index 0a80a5f41..f85b13991 100644 --- a/Documentation/ref/index.rst +++ b/Documentation/ref/index.rst @@ -40,8 +40,6 @@ time: :maxdepth: 3 ovs-sim.1 - ovs-test.8 - ovs-vlan-test.8 ovsdb-server.7 ovsdb.5 ovsdb.7 @@ -50,10 +48,6 @@ The remainder are still in roff format can be found below: .. list-table:: - * - ovs-actions(7) - - `(pdf) `__ - - `(html) `__ - - `(plain text) `__ * - ovn-architecture(7) - `(pdf) `__ - `(html) `__ @@ -94,103 +88,3 @@ The remainder are still in roff format can be found below: - `(pdf) `__ - `(html) `__ - `(plain text) `__ - * - ovs-appctl(8) - - `(pdf) `__ - - `(html) `__ - - `(plain text) `__ - * - ovs-bugtool(8) - - `(pdf) `__ - - `(html) `__ - - `(plain text) `__ - * - ovs-ctl(8) - - `(pdf) `__ - - `(html) `__ - - `(plain text) `__ - * - ovsdb-client(1) - - `(pdf) `__ - - `(html) `__ - - `(plain text) `__ - * - ovsdb-server(1) - - `(pdf) `__ - - `(html) `__ - - `(plain text) `__ - * - ovsdb-tool(1) - - `(pdf) `__ - - `(html) `__ - - `(plain text) `__ - * - ovs-dpctl(8) - - `(pdf) `__ - - `(html) `__ - - `(plain text) `__ - * - ovs-dpctl-top(8) - - `(pdf) `__ - - `(html) `__ - - `(plain text) `__ - * - ovs-fields(7) - - `(pdf) `__ - - `(html) `__ - - `(plain text) `__ - * - ovs-l3ping(8) - - `(pdf) `__ - - `(html) `__ - - `(plain text) `__ - * - ovs-ofctl(8) - - `(pdf) `__ - - `(html) `__ - - `(plain text) `__ - * - ovs-parse-backtrace(8) - - `(pdf) `__ - - `(html) `__ - - `(plain text) `__ - * - ovs-pcap(1) - - `(pdf) `__ - - `(html) `__ - - `(plain text) `__ - * - ovs-pki(8) - - `(pdf) `__ - - `(html) `__ - - `(plain text) `__ - * - ovs-tcpdump(8) - - `(pdf) `__ - - `(html) `__ - - `(plain text) `__ - * - ovs-tcpundump(1) - - `(pdf) `__ - - `(html) `__ - - `(plain text) `__ - * - ovs-test(8) - - `(pdf) `__ - - `(html) `__ - - `(plain text) `__ - * - ovs-testcontroller(8) - - `(pdf) `__ - - `(html) `__ - - `(plain text) `__ - * - ovs-vlan-bug-workaround(8) - - `(pdf) `__ - - `(html) `__ - - `(plain text) `__ - * - ovs-vlan-test(8) - - `(pdf) `__ - - `(html) `__ - - `(plain text) `__ - * - ovs-vsctl(8) - - `(pdf) `__ - - `(html) `__ - - `(plain text) `__ - * - ovs-vswitchd(8) - - `(pdf) `__ - - `(html) `__ - - `(plain text) `__ - * - ovs-vswitchd.conf.db(5) - - `(pdf) `__ - - `(html) `__ - - `(plain text) `__ - * - vtep(5) - - `(pdf) `__ - - `(html) `__ - - `(plain text) `__ - * - vtep-ctl(8) - - `(pdf) `__ - - `(html) `__ - - `(plain text) `__ diff --git a/Documentation/ref/ovs-test.8.rst b/Documentation/ref/ovs-test.8.rst deleted file mode 100644 index f902d9c3b..000000000 --- a/Documentation/ref/ovs-test.8.rst +++ /dev/null @@ -1,163 +0,0 @@ -======== -ovs-test -======== - -Synopsis -======== - -**ovs-test** -s *port* - -**ovs-test** -c *server1* *server2* [**-b** *targetbandwidth*] [**-i** *testinterval*] [**-d**] - [**-l** *vlantag*] [**-t** *tunnelmodes*] - -Description -=========== - -The :program:`ovs-test` program may be used to check for problems sending -802.1Q or GRE traffic that Open vSwitch may uncover. These problems, for -example, can occur when Open vSwitch is used to send 802.1Q traffic through -physical interfaces running certain drivers of certain Linux kernel versions. -To run a test, configure IP addresses on `server1` and `server2` for interfaces -you intended to test. These interfaces could also be already configured OVS -bridges that have a physical interface attached to them. Then, on one of the -nodes, run :program:`ovs-test` in server mode and on the other node run it in -client mode. The client will connect to :program:`ovs-test` server and schedule -tests between both of them. The :program:`ovs-test` client will perform UDP and -TCP tests. - -UDP tests can report packet loss and achieved bandwidth for various datagram -sizes. By default target bandwidth for UDP tests is 1Mbit/s. - -TCP tests report only achieved bandwidth, because kernel TCP stack takes care -of flow control and packet loss. TCP tests are essential to detect potential -TSO related issues. - -To determine whether Open vSwitch is encountering any problems, the user must -compare packet loss and achieved bandwidth in a setup where traffic is being -directly sent and in one where it is not. If in the 802.1Q or L3 tunneled tests -both :program:`ovs-test` processes are unable to communicate or the achieved -bandwidth is much lower compared to direct setup, then, most likely, Open -vSwitch has encountered a pre-existing kernel or driver bug. - -Some examples of the types of problems that may be encountered are: - -- When NICs use VLAN stripping on receive they must pass a pointer to a - `vlan_group` when reporting the stripped tag to the networking core. If no - `vlan_group` is in use then some drivers just drop the extracted tag. - Drivers are supposed to only enable stripping if a `vlan_group` is registered - but not all of them do that. - -- On receive, some drivers handle priority tagged packets specially and don't - pass the tag onto the network stack at all, so Open vSwitch never has a - chance to see it. - -- Some drivers size their receive buffers based on whether a `vlan_group` is - enabled, meaning that a maximum size packet with a VLAN tag will not fit if - no `vlan_group` is configured. - -- On transmit, some drivers expect that VLAN acceleration will be used if it is - available, which can only be done if a `vlan_group` is configured. In these - cases, the driver may fail to parse the packet and correctly setup checksum - offloading or TSO. - -Client Mode - An :program:`ovs-test` client will connect to two :program:`ovs-test` servers - and will ask them to exchange test traffic. It is also possible to spawn an - :program:`ovs-test` server automatically from the client. - -Server Mode - To conduct tests, two :program:`ovs-test` servers must be running on two - different hosts where the client can connect. The actual test traffic is - exchanged only between both :program:`ovs-test` servers. It is recommended - that both servers have their IP addresses in the same subnet, otherwise one - would have to make sure that routing is set up correctly. - -Options -======= - -.. program:: ovs-test - -.. option:: -s , --server - - Run in server mode and wait for the client to establish XML RPC Control - Connection on this TCP port. It is recommended to have `ethtool(8)` - installed on the server so that it could retrieve information about the NIC - driver. - -.. option:: -c , --client - - Run in client mode and schedule tests between `server1` and `server2`, - where each server must be given in the following format:: - - OuterIP[:OuterPort],InnerIP[/Mask][:InnerPort]. - - The `OuterIP` must be already assigned to the physical interface which is - going to be tested. This is the IP address where client will try to - establish XML RPC connection. If `OuterIP` is 127.0.0.1 then client will - automatically spawn a local instance of :program:`ovs-test` server. - OuterPort is TCP port where server is listening for incoming XML/RPC - control connections to schedule tests (by default it is 15531). The - :program:`ovs-test` will automatically assign `InnerIP[/Mask]` to the - interfaces that will be created on the fly for testing purposes. It is - important that `InnerIP[/Mask]` does not interfere with already existing IP - addresses on both :program:`ovs-test` servers and client. InnerPort is port - which will be used by server to listen for test traffic that will be - encapsulated (by default it is 15532). - -.. option:: -b , --bandwidth - - Target bandwidth for UDP tests. The targetbandwidth must be given in bits - per second. It is possible to use postfix `M` or `K` to alter the target - bandwidth magnitude. - -.. option:: -i , --interval - - How long each test should run. By default 5 seconds. - -.. option:: -h, --help - - Prints a brief help message to the console. - -.. option:: -V, --version - - Prints version information to the console. - -The following test modes are supported by :program:`ovs-test`. It is possible -to combine multiple of them in a single :program:`ovs-test` invocation. - -.. option:: -d, --direct - - Perform direct tests between both OuterIP addresses. These tests could be - used as a reference to compare 802.1Q or L3 tunneling test results. - -.. option:: -l , --vlan-tag - - Perform 802.1Q tests between both servers. These tests will create a - temporary OVS bridge, if necessary, and attach a VLAN tagged port to - it for testing purposes. - -.. option:: -t , --tunnel-modes - - Perform L3 tunneling tests. The given argument is a comma sepa‐ rated - string that specifies all the L3 tunnel modes that should be tested (e.g. - gre). The L3 tunnels are terminated on interface that has the OuterIP - address assigned. - -Examples -======== - -On host 1.2.3.4 start :program:`ovs-test` in server mode:: - - ovs-test -s 15531 - -On host 1.2.3.5 start :program:`ovs-test` in client mode and do direct, VLAN -and GRE tests between both nodes:: - - 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 - -See Also -======== - -`ovs-vswitchd(8)`, `ovs-ofctl(8)`, `ovs-vsctl(8)`, :program:`ovs-vlan-test`, -`ethtool(8)`, `uname(1)` diff --git a/Documentation/ref/ovs-vlan-test.8.rst b/Documentation/ref/ovs-vlan-test.8.rst deleted file mode 100644 index d4fbabbdf..000000000 --- a/Documentation/ref/ovs-vlan-test.8.rst +++ /dev/null @@ -1,113 +0,0 @@ -============= -ovs-vlan-test -============= - -Synopsis -======== - -**ovs-vlan-test** [**-s** | **--server**] *control_ip* *vlan_ip* - -Description -=========== - -The :program:`ovs-vlan-test` utility has some limitations, for example, it does -not use TCP in its tests. Also it does not take into account MTU to detect -potential edge cases. To overcome those limitations a new tool was developed - -:program:`ovs-test`. :program:`ovs-test` is currently supported only on Debian -so, if possible, try to use that on instead of :program:`ovs-vlan-test`. - -The :program:`ovs-vlan-test` program may be used to check for problems sending -802.1Q traffic which may occur when running Open vSwitch. These problems can -occur when Open vSwitch is used to send 802.1Q traffic through physical -interfaces running certain drivers of certain Linux kernel versions. To run a -test, configure Open vSwitch to tag traffic originating from `vlan_ip` and -forward it out the target interface. Then run the :program:`ovs-vlan-test` in -client mode connecting to an :program:`ovs-vlan-test` server. -:program:`ovs-vlan-test` will display "OK" if it did not detect problems. - -Some examples of the types of problems that may be encountered are: - -- When NICs use VLAN stripping on receive they must pass a pointer to a - `vlan_group` when reporting the stripped tag to the networking core. If no - `vlan_group` is in use then some drivers just drop the extracted tag. - Drivers are supposed to only enable stripping if a `vlan_group` is registered - but not all of them do that. - -- On receive, some drivers handle priority tagged packets specially and don't - pass the tag onto the network stack at all, so Open vSwitch never has a - chance to see it. - -- Some drivers size their receive buffers based on whether a `vlan_group` is - enabled, meaning that a maximum size packet with a VLAN tag will not fit if - no `vlan_group` is configured. - -- On transmit, some drivers expect that VLAN acceleration will be used if it is - available, which can only be done if a `vlan_group` is configured. In these - cases, the driver may fail to parse the packet and correctly setup checksum - offloading or TSO. - -Client Mode - An :program:`ovs-vlan-test` client may be run on a host to check for VLAN - connectivity problems. The client must be able to establish HTTP connections - with an :program:`ovs-vlan-test` server located at the specified `control_ip` - address. UDP traffic sourced at `vlan_ip` should be tagged and directed out - the interface whose connectivity is being tested. - -Server Mode - To conduct tests, an :program:`ovs-vlan-test` server must be running on a - host known not to have VLAN connectivity problems. The server must have a - `control_ip` on a non-VLAN network which clients can establish connectivity - with. It must also have a `vlan_ip` address on a VLAN network which clients - will use to test their VLAN connectivity. Multiple clients may test against a - single :program:`ovs-vlan-test` server concurrently. - -Options -======= - -.. program:: ovs-vlan-test - -.. option:: -s, --server - - Run in server mode. - -.. option:: -h, --help - - Prints a brief help message to the console. - -.. option:: -V, --version - - Prints version information to the console. - -Examples -======== - -Display the Linux kernel version and driver of `eth1`:: - - uname -r - ethtool -i eth1 - -Set up a bridge which forwards traffic originating from `1.2.3.4` out `eth1` -with VLAN tag 10:: - - ovs-vsctl -- add-br vlan-br \ - -- add-port vlan-br eth1 \ - -- add-port vlan-br vlan-br-tag tag=10 \ - -- set Interface vlan-br-tag type=internal - ip addr add 1.2.3.4/8 dev vlan-br-tag - ip link set vlan-br-tag up - -Run an :program:`ovs-vlan-test` server listening for client control traffic on -`172.16.0.142` port `8080` and VLAN traffic on the default port of `1.2.3.3`:: - - ovs-vlan-test -s 172.16.0.142:8080 1.2.3.3 - -Run an :program:`ovs-vlan-test` client with a control server located at -`172.16.0.142` port `8080` and a local VLAN IP of `1.2.3.4`:: - - ovs-vlan-test 172.16.0.142:8080 1.2.3.4 - -See Also -======== - -`ovs-vswitchd(8)`, `ovs-ofctl(8)`, `ovs-vsctl(8)`, :program:`ovs-test`, -`ethtool(8)`, `uname(1)`