From patchwork Fri Apr 14 04:43:17 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Ben Pfaff X-Patchwork-Id: 750729 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org 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 3w44q34VCpz9sNW for ; Fri, 14 Apr 2017 14:45:51 +1000 (AEST) Received: from mail.linux-foundation.org (localhost [127.0.0.1]) by mail.linuxfoundation.org (Postfix) with ESMTP id BC72BBC4; Fri, 14 Apr 2017 04:43:44 +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 C29E8B93 for ; Fri, 14 Apr 2017 04:43:42 +0000 (UTC) X-Greylist: domain auto-whitelisted by SQLgrey-1.7.6 Received: from relay2-d.mail.gandi.net (relay2-d.mail.gandi.net [217.70.183.194]) by smtp1.linuxfoundation.org (Postfix) with ESMTPS id D9667176 for ; Fri, 14 Apr 2017 04:43:40 +0000 (UTC) Received: from mfilter11-d.gandi.net (mfilter11-d.gandi.net [217.70.178.131]) by relay2-d.mail.gandi.net (Postfix) with ESMTP id A92A4C5A55; Fri, 14 Apr 2017 06:43:39 +0200 (CEST) X-Virus-Scanned: Debian amavisd-new at mfilter11-d.gandi.net Received: from relay2-d.mail.gandi.net ([IPv6:::ffff:217.70.183.194]) by mfilter11-d.gandi.net (mfilter11-d.gandi.net [::ffff:10.0.15.180]) (amavisd-new, port 10024) with ESMTP id AUBwwLiXhUKO; Fri, 14 Apr 2017 06:43:37 +0200 (CEST) X-Originating-IP: 173.228.112.23 Received: from sigabrt.gateway.sonic.net (173-228-112-23.dsl.dynamic.fusionbroadband.com [173.228.112.23]) (Authenticated sender: blp@ovn.org) by relay2-d.mail.gandi.net (Postfix) with ESMTPSA id B952FC5A67; Fri, 14 Apr 2017 06:43:34 +0200 (CEST) From: Ben Pfaff To: dev@openvswitch.org Date: Thu, 13 Apr 2017 21:43:17 -0700 Message-Id: <20170414044319.11074-5-blp@ovn.org> X-Mailer: git-send-email 2.10.2 In-Reply-To: <20170414044319.11074-1-blp@ovn.org> References: <20170414044319.11074-1-blp@ovn.org> X-Spam-Status: No, score=-2.1 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_LOW, RCVD_IN_SORBS_SPAM autolearn=ham version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on smtp1.linux-foundation.org Cc: Ben Pfaff Subject: [ovs-dev] [PATCH 4/6] doc: Convert ovs-vlan-test to rST 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: , MIME-Version: 1.0 Sender: ovs-dev-bounces@openvswitch.org Errors-To: ovs-dev-bounces@openvswitch.org From: Stephen Finucane Let's start with a simple one that lets us focus on setting up most of the required "infrastructure" for building man pages using Sphinx. This changes the 'check-htmldocs' target to 'check-docs' as its now responsible for building man page docs too. Other than that, hurrah for (mostly) legible syntaxes. [1] http://www.tldp.org/HOWTO/Man-Page/q2.html Signed-off-by: Stephen Finucane Signed-off-by: Ben Pfaff Acked-by: Stephen Finucane --- Documentation/automake.mk | 84 +++++++++++++-- Documentation/conf.py | 5 +- .../internals/contributing/documentation-style.rst | 3 +- Documentation/intro/install/documentation.rst | 4 +- Documentation/ref/index.rst | 16 ++- Documentation/ref/ovs-vlan-test.8.rst | 115 +++++++++++++++++++++ debian/openvswitch-switch.manpages | 1 - manpages.mk | 10 -- utilities/automake.mk | 3 - utilities/ovs-vlan-test.8.in | 96 ----------------- 10 files changed, 211 insertions(+), 126 deletions(-) create mode 100644 Documentation/ref/ovs-vlan-test.8.rst delete mode 100644 utilities/ovs-vlan-test.8.in diff --git a/Documentation/automake.mk b/Documentation/automake.mk index 9911668c1ca9..762255277102 100644 --- a/Documentation/automake.mk +++ b/Documentation/automake.mk @@ -90,7 +90,8 @@ DOC_SOURCE = \ Documentation/internals/contributing/documentation-style.rst \ Documentation/internals/contributing/libopenvswitch-abi.rst \ Documentation/internals/contributing/submitting-patches.rst \ - Documentation/requirements.txt + Documentation/requirements.txt \ + $(addprefix Documentation/ref/,$(RST_MANPAGES)) EXTRA_DIST += $(DOC_SOURCE) @@ -110,20 +111,89 @@ sphinx_verbose_ = $(sphinx_verbose_@AM_DEFAULT_V@) sphinx_verbose_0 = -q if HAVE_SPHINX -htmldocs-check: $(DOC_SOURCE) +docs-check: $(DOC_SOURCE) $(AM_V_GEN)$(SPHINXBUILD) $(sphinx_verbose) -b html $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/html && touch $@ -ALL_LOCAL += htmldocs-check -CLEANFILES += htmldocs-check + $(AM_V_GEN)$(SPHINXBUILD) $(sphinx_verbose) -b man $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/man && touch $@ +ALL_LOCAL += docs-check +CLEANFILES += docs-check check-docs: $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/linkcheck clean-docs: - rm -rf $(SPHINXBUILDDIR)/doctrees - rm -rf $(SPHINXBUILDDIR)/html - rm -rf $(SPHINXBUILDDIR)/linkcheck + rm -rf $(SPHINXBUILDDIR) rm -f docs-check CLEAN_LOCAL += clean-docs endif .PHONY: check-docs .PHONY: clean-docs + +# Installing manpages based on rST. +# +# The docs-check target converts the rST files listed in RST_MANPAGES +# into nroff manpages in Documentation/_build/man. The easiest way to +# get these installed by "make install" is to write our own helper +# rules. + +# rST formatted manpages under Documentation/ref. +RST_MANPAGES = \ + ovs-vlan-test.8.rst + +# The GNU standards say that these variables should control +# installation directories for manpages in each section. Automake +# will define them for us only if it sees that a manpage in the +# appropriate section is to be installed through its built-in feature. +# Since we're working independently, for best safety, we need to +# define them ourselves. +man1dir = $(mandir)/man1 +man2dir = $(mandir)/man2 +man3dir = $(mandir)/man3 +man4dir = $(mandir)/man4 +man5dir = $(mandir)/man5 +man6dir = $(mandir)/man6 +man7dir = $(mandir)/man7 +man8dir = $(mandir)/man8 +man9dir = $(mandir)/man9 + +# Set a shell variable for each manpage directory. +set_mandirs = \ + man1dir='$(man1dir)' \ + man2dir='$(man2dir)' \ + man3dir='$(man3dir)' \ + man4dir='$(man4dir)' \ + man5dir='$(man5dir)' \ + man6dir='$(man6dir)' \ + man7dir='$(man7dir)' \ + man8dir='$(man8dir)' \ + man9dir='$(man9dir)' + +# Given an $rst of "ovs-vlan-test.8.rst", sets $stem to +# "ovs-vlan-test", $section to "8", and $mandir to $man8dir. +extract_stem_and_section = \ + stem=`echo "$$rst" | sed -n 's/^\(.*\)\.\([0-9]\).rst$$/\1/p'`; \ + section=`echo "$$rst" | sed -n 's/^\(.*\)\.\([0-9]\).rst$$/\2/p'`; \ + test -n "$$section" || { echo "$$rst: cannot infer manpage section from filename" 2>&1; continue; }; \ + eval "mandir=\$$man$${section}dir"; \ + test -n "$$mandir" || { echo "unknown directory for manpage section $$section"; continue; } + +if HAVE_SPHINX +INSTALL_DATA_LOCAL += install-man-rst +install-man-rst: docs-check + @$(set_mandirs); \ + for rst in $(RST_MANPAGES); do \ + $(extract_stem_and_section); \ + echo " $(MKDIR_P) '$(DESTDIR)'\"$$mandir\""; \ + $(MKDIR_P) '$(DESTDIR)'"$$mandir"; \ + echo " $(INSTALL_DATA) $(SPHINXBUILDDIR)/man/$$stem.$$section '$(DESTDIR)'\"$$mandir/$$stem.$$section\""; \ + $(INSTALL_DATA) $(SPHINXBUILDDIR)/man/$$stem.$$section '$(DESTDIR)'"$$mandir/$$stem.$$section"; \ + done +endif + +UNINSTALL_LOCAL += uninstall-man-rst +uninstall-man-rst: + @$(set_mandirs); \ + for rst in $(RST_MANPAGES); do \ + $(extract_stem_and_section); \ + echo "rm -f '$(DESTDIR)'\"$$mandir/$$stem.$$section\""; \ + rm -f '$(DESTDIR)'"$$mandir/$$stem.$$section"; \ + done diff --git a/Documentation/conf.py b/Documentation/conf.py index bfd7f33d88ba..8671a097d17e 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -328,8 +328,9 @@ latex_documents = [ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - (master_doc, 'openvswitch', u'Open vSwitch Documentation', - [author], 1) + ('ref/ovs-vlan-test.8', 'ovs-vlan-test', + u'Check Linux drivers for problems with vlan traffic', + [author], 8) ] # If true, show URL addresses after external links. diff --git a/Documentation/internals/contributing/documentation-style.rst b/Documentation/internals/contributing/documentation-style.rst index 0ba5e544f14e..0e561ec23f10 100644 --- a/Documentation/internals/contributing/documentation-style.rst +++ b/Documentation/internals/contributing/documentation-style.rst @@ -347,7 +347,8 @@ 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 for worked examples. +Refer to existing man pages, such as :doc:`/ref/ovs-vlan-test.8` for a worked +example. __ http://www.sphinx-doc.org/en/stable/domains.html#directive-program __ http://www.sphinx-doc.org/en/stable/domains.html#directive-option diff --git a/Documentation/intro/install/documentation.rst b/Documentation/intro/install/documentation.rst index 94af950afc3e..0eeeab15226f 100644 --- a/Documentation/intro/install/documentation.rst +++ b/Documentation/intro/install/documentation.rst @@ -74,11 +74,11 @@ Building Once Sphinx installed, the documentation can be built using the provided Makefile targets:: - $ make htmldocs-check + $ make docs-check .. important:: - The ``htmldocs-check`` target will fail if there are any syntax errors. + The ``docs-check`` target will fail if there are any syntax errors. However, it won't catch more succint issues such as style or grammar issues. As a result, you should always inspect changes visually to ensure the result is as intended. diff --git a/Documentation/ref/index.rst b/Documentation/ref/index.rst index 49121b7599fd..6b368809c11b 100644 --- a/Documentation/ref/index.rst +++ b/Documentation/ref/index.rst @@ -30,10 +30,18 @@ Reference Guide Man Pages --------- -.. TODO(stephenfin): Investigate some way to get the manpages into rST format. - The most viable option seems to be writing them all in rST, converting them - to roff format and storing both the rST and roff formatted docs in version - control. +.. TODO(stephenfin): Remove the below notice once everything is converted to + rST + +The following man pages are written in rST and converted to roff at compile +time: + +.. toctree:: + :maxdepth: 3 + + ovs-vlan-test.8 + +The remainder are still in roff format can be found below: .. list-table:: diff --git a/Documentation/ref/ovs-vlan-test.8.rst b/Documentation/ref/ovs-vlan-test.8.rst new file mode 100644 index 000000000000..c3066917f00d --- /dev/null +++ b/Documentation/ref/ovs-vlan-test.8.rst @@ -0,0 +1,115 @@ +============= +ovs-vlan-test +============= + +Synopsis +======== + +**ovs-vlan-test** [**-s** | **--server**] *control_ip* *vlan_ip* + +Description +=========== + +.. TODO(stephenfin): Add the `:program:` prefixes to `ovs-test` once that doc + is converted + +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 - +`ovs-test`. `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 + ifconfig vlan-br-tag up 1.2.3.4 + +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)`, `ovs-test(8)`, `ethtool(8)`, +`uname(1)` diff --git a/debian/openvswitch-switch.manpages b/debian/openvswitch-switch.manpages index a3aae642d8d1..a2f661a3e58c 100644 --- a/debian/openvswitch-switch.manpages +++ b/debian/openvswitch-switch.manpages @@ -5,7 +5,6 @@ utilities/ovs-dpctl.8 utilities/ovs-pcap.1 utilities/ovs-tcpdump.8 utilities/ovs-tcpundump.1 -utilities/ovs-vlan-test.8 utilities/ovs-vsctl.8 vswitchd/ovs-vswitchd.8 vswitchd/ovs-vswitchd.conf.db.5 diff --git a/manpages.mk b/manpages.mk index 742bd66cdc32..372d06cad0a4 100644 --- a/manpages.mk +++ b/manpages.mk @@ -244,16 +244,6 @@ utilities/ovs-vlan-bug-workaround.8.in: lib/common.man: utilities/ovs-vlan-bugs.man: -utilities/ovs-vlan-test.8: \ - utilities/ovs-vlan-test.8.in \ - lib/common-syn.man \ - lib/common.man \ - utilities/ovs-vlan-bugs.man -utilities/ovs-vlan-test.8.in: -lib/common-syn.man: -lib/common.man: -utilities/ovs-vlan-bugs.man: - utilities/ovs-vsctl.8: \ utilities/ovs-vsctl.8.in \ lib/common.man \ diff --git a/utilities/automake.mk b/utilities/automake.mk index 169388fda5ec..02531f6dd3d6 100644 --- a/utilities/automake.mk +++ b/utilities/automake.mk @@ -72,7 +72,6 @@ MAN_ROOTS += \ utilities/ovs-tcpundump.1.in \ utilities/ovs-vlan-bug-workaround.8.in \ utilities/ovs-test.8.in \ - utilities/ovs-vlan-test.8.in \ utilities/ovs-vsctl.8.in MAN_FRAGMENTS += utilities/ovs-vlan-bugs.man CLEANFILES += \ @@ -101,7 +100,6 @@ CLEANFILES += \ utilities/ovs-test \ utilities/ovs-test.8 \ utilities/ovs-vlan-test \ - utilities/ovs-vlan-test.8 \ utilities/ovs-vlan-bug-workaround.8 \ utilities/ovs-vsctl.8 @@ -120,7 +118,6 @@ man_MANS += \ utilities/ovs-tcpundump.1 \ utilities/ovs-vlan-bug-workaround.8 \ utilities/ovs-test.8 \ - utilities/ovs-vlan-test.8 \ utilities/ovs-vsctl.8 utilities_ovs_appctl_SOURCES = utilities/ovs-appctl.c diff --git a/utilities/ovs-vlan-test.8.in b/utilities/ovs-vlan-test.8.in deleted file mode 100644 index 2cdeff832104..000000000000 --- a/utilities/ovs-vlan-test.8.in +++ /dev/null @@ -1,96 +0,0 @@ -.de IQ -. br -. ns -. IP "\\$1" -.. -.TH ovs\-vlan\-test 1 "@VERSION@" "Open vSwitch" "Open vSwitch Manual" -. -.SH NAME -\fBovs\-vlan\-test\fR \- check Linux drivers for problems with vlan traffic -. -.SH SYNOPSIS -\fBovs\-vlan\-test\fR [\fB\-s\fR | \fB\-\-server\fR] \fIcontrol_ip\fR \fIvlan_ip\fR -.so lib/common-syn.man -. -.SH DESCRIPTION -The \fBovs\-vlan\-test\fR 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 \- \fBovs\-test\fR. \fBovs\-test\fR is currently supported only -on Debian so, if possible try to use that on instead of \fBovs\-vlan\-test\fR. -.PP -The \fBovs\-vlan\-test\fR 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 \fIvlan_ip\fR and -forward it out the target interface. Then run the \fBovs\-vlan\-test\fR in -client mode connecting to an \fBovs\-vlan\-test\fR server. -\fBovs\-vlan\-test\fR will display "OK" if it did not detect problems. -.PP -Some examples of the types of problems that may be encountered are: -.so utilities/ovs-vlan-bugs.man -. -.SS "Client Mode" -An \fBovs\-vlan\-test\fR client may be run on a host to check for VLAN -connectivity problems. The client must be able to establish HTTP connections -with an \fBovs\-vlan\-test\fR server located at the specified \fIcontrol_ip\fR -address. UDP traffic sourced at \fIvlan_ip\fR should be tagged and directed out -the interface whose connectivity is being tested. -. -.SS "Server Mode" -To conduct tests, an \fBovs\-vlan\-test\fR server must be running on a host -known not to have VLAN connectivity problems. The server must have a -\fIcontrol_ip\fR on a non\-VLAN network which clients can establish -connectivity with. It must also have a \fIvlan_ip\fR address on a VLAN network -which clients will use to test their VLAN connectivity. Multiple clients may -test against a single \fBovs\-vlan\-test\fR server concurrently. -. -.SH OPTIONS -. -.IP "\fB\-s\fR" -.IQ "\fB\-\-server\fR" -Run in server mode. -. -.so lib/common.man -.SH EXAMPLES -Display the Linux kernel version and driver of \fBeth1\fR. -.IP -.B uname \-r -.IP -.B ethtool \-i eth1 -. -.PP -Set up a bridge which forwards traffic originating from \fB1.2.3.4\fR out -\fBeth1\fR with VLAN tag 10. -.IP -.B ovs\-vsctl \-\- add\-br vlan\-br \(rs -.IP -.B \-\- add\-port vlan\-br eth1 \(rs -.IP -.B \-\- add\-port vlan\-br vlan\-br\-tag tag=10 \(rs -.IP -.B \-\- set Interface vlan\-br\-tag type=internal -.IP -.B ifconfig vlan\-br\-tag up 1.2.3.4 -. -.PP -Run an \fBovs\-vlan\-test\fR 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. -.IP -.B ovs\-vlan\-test \-s 172.16.0.142:8080 1.2.3.3 -. -.PP -Run an \fBovs\-vlan\-test\fR client with a control server located at -172.16.0.142 port 8080 and a local VLAN ip of 1.2.3.4. -.IP -.B ovs\-vlan\-test 172.16.0.142:8080 1.2.3.4 -. -.SH SEE ALSO -. -.BR ovs\-vswitchd (8), -.BR ovs\-ofctl (8), -.BR ovs\-vsctl (8), -.BR ovs\-test (8), -.BR ethtool (8), -.BR uname (1)