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))
FLAKE8_PYFILES += Documentation/conf.py
EXTRA_DIST += $(DOC_SOURCE)
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
+\f
+# 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
# 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.
- 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
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.
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::
--- /dev/null
+=============
+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)`
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
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 \
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 += \
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
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
+++ /dev/null
-.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)