mirror of
https://github.com/openvswitch/ovs
synced 2025-09-01 06:45:17 +00:00
doc: Convert ovs-vlan-test to rST
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 <stephen@that.guru> Signed-off-by: Ben Pfaff <blp@ovn.org>
This commit is contained in:
Stephen Finucane
committed by
Ben Pfaff
Ben Pfaff
parent
717dbe617e
commit
fd0837a76f
@@ -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))
|
||||
FLAKE8_PYFILES += Documentation/conf.py
|
||||
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
|
||||
|
||||
@@ -331,8 +331,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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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::
|
||||
|
||||
|
||||
115
Documentation/ref/ovs-vlan-test.8.rst
Normal file
115
Documentation/ref/ovs-vlan-test.8.rst
Normal file
@@ -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)`
|
||||
1
debian/openvswitch-switch.manpages
vendored
1
debian/openvswitch-switch.manpages
vendored
@@ -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
|
||||
|
||||
10
manpages.mk
10
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 \
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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)
|
||||
Reference in New Issue
Block a user