@@ -153,6 +153,13 @@ endif
# rST formatted manpages under Documentation/ref.
RST_MANPAGES = \
+ ovs-appctl.8.rst \
+ ovs-ctl.8.rst \
+ ovs-l3ping.8.rst \
+ ovs-parse-backtrace.8.rst \
+ ovs-pki.8.rst \
+ ovs-tcpdump.8.rst \
+ ovs-tcpundump.1.rst \
ovs-test.8.rst \
ovs-vlan-test.8.rst \
ovsdb-server.7.rst \
@@ -114,8 +114,22 @@ html_static_path = ['_static']
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
_man_pages = [
+ ('ovs-appctl.8',
+ u'utility for configuring running Open vSwitch daemons'),
+ ('ovs-ctl.8',
+ u'OVS startup helper script'),
+ ('ovs-l3ping.8',
+ u'check network deployment for L3 tunneling problems'),
+ ('ovs-parse-backtrace.8',
+ u'parses ovs-appctl backtrace output'),
+ ('ovs-pki.8',
+ u'OpenFlow public key infrastructure management utility'),
('ovs-sim.1',
u'Open vSwitch simulator environment'),
+ ('ovs-tcpdump.8',
+ u'Dump traffic from an Open vSwitch port using tcpdump'),
+ ('ovs-tcpundump.1',
+ u'convert "tcpdump -xx" output to hex strings'),
('ovs-test.8',
u'Check Linux drivers for performance, vlan and L3 tunneling problems'),
('ovs-vlan-test.8',
@@ -39,7 +39,14 @@ time:
.. toctree::
:maxdepth: 3
+ ovs-appctl.8
+ ovs-ctl.8
+ ovs-l3ping.8
+ ovs-pki.8
ovs-sim.1
+ ovs-parse-backtrace.8
+ ovs-tcpdump.8
+ ovs-tcpundump.1
ovs-test.8
ovs-vlan-test.8
ovsdb-server.7
@@ -54,18 +61,10 @@ The remainder are still in roff format can be found below:
- `(pdf) <http://www.openvswitch.org/support/dist-docs/ovs-actions.7.pdf>`__
- `(html) <http://www.openvswitch.org/support/dist-docs/ovs-actions.7.html>`__
- `(plain text) <http://www.openvswitch.org/support/dist-docs/ovs-actions.7.txt>`__
- * - ovs-appctl(8)
- - `(pdf) <http://www.openvswitch.org/support/dist-docs/ovs-appctl.8.pdf>`__
- - `(html) <http://www.openvswitch.org/support/dist-docs/ovs-appctl.8.html>`__
- - `(plain text) <http://www.openvswitch.org/support/dist-docs/ovs-appctl.8.txt>`__
* - ovs-bugtool(8)
- `(pdf) <http://www.openvswitch.org/support/dist-docs/ovs-bugtool.8.pdf>`__
- `(html) <http://www.openvswitch.org/support/dist-docs/ovs-bugtool.8.html>`__
- `(plain text) <http://www.openvswitch.org/support/dist-docs/ovs-bugtool.8.txt>`__
- * - ovs-ctl(8)
- - `(pdf) <http://www.openvswitch.org/support/dist-docs/ovs-ctl.8.pdf>`__
- - `(html) <http://www.openvswitch.org/support/dist-docs/ovs-ctl.8.html>`__
- - `(plain text) <http://www.openvswitch.org/support/dist-docs/ovs-ctl.8.txt>`__
* - ovsdb-client(1)
- `(pdf) <http://www.openvswitch.org/support/dist-docs/ovsdb-client.1.pdf>`__
- `(html) <http://www.openvswitch.org/support/dist-docs/ovsdb-client.1.html>`__
@@ -90,34 +89,14 @@ The remainder are still in roff format can be found below:
- `(pdf) <http://www.openvswitch.org/support/dist-docs/ovs-fields.7.pdf>`__
- `(html) <http://www.openvswitch.org/support/dist-docs/ovs-fields.7.html>`__
- `(plain text) <http://www.openvswitch.org/support/dist-docs/ovs-fields.7.txt>`__
- * - ovs-l3ping(8)
- - `(pdf) <http://www.openvswitch.org/support/dist-docs/ovs-l3ping.8.pdf>`__
- - `(html) <http://www.openvswitch.org/support/dist-docs/ovs-l3ping.8.html>`__
- - `(plain text) <http://www.openvswitch.org/support/dist-docs/ovs-l3ping.8.txt>`__
* - ovs-ofctl(8)
- `(pdf) <http://www.openvswitch.org/support/dist-docs/ovs-ofctl.8.pdf>`__
- `(html) <http://www.openvswitch.org/support/dist-docs/ovs-ofctl.8.html>`__
- `(plain text) <http://www.openvswitch.org/support/dist-docs/ovs-ofctl.8.txt>`__
- * - ovs-parse-backtrace(8)
- - `(pdf) <http://www.openvswitch.org/support/dist-docs/ovs-parse-backtrace.8.pdf>`__
- - `(html) <http://www.openvswitch.org/support/dist-docs/ovs-parse-backtrace.8.html>`__
- - `(plain text) <http://www.openvswitch.org/support/dist-docs/ovs-parse-backtrace.8.txt>`__
* - ovs-pcap(1)
- `(pdf) <http://www.openvswitch.org/support/dist-docs/ovs-pcap.1.pdf>`__
- `(html) <http://www.openvswitch.org/support/dist-docs/ovs-pcap.1.html>`__
- `(plain text) <http://www.openvswitch.org/support/dist-docs/ovs-pcap.1.txt>`__
- * - ovs-pki(8)
- - `(pdf) <http://www.openvswitch.org/support/dist-docs/ovs-pki.8.pdf>`__
- - `(html) <http://www.openvswitch.org/support/dist-docs/ovs-pki.8.html>`__
- - `(plain text) <http://www.openvswitch.org/support/dist-docs/ovs-pki.8.txt>`__
- * - ovs-tcpdump(8)
- - `(pdf) <http://www.openvswitch.org/support/dist-docs/ovs-tcpdump.8.pdf>`__
- - `(html) <http://www.openvswitch.org/support/dist-docs/ovs-tcpdump.8.html>`__
- - `(plain text) <http://www.openvswitch.org/support/dist-docs/ovs-tcpdump.8.txt>`__
- * - ovs-tcpundump(1)
- - `(pdf) <http://www.openvswitch.org/support/dist-docs/ovs-tcpundump.1.pdf>`__
- - `(html) <http://www.openvswitch.org/support/dist-docs/ovs-tcpundump.1.html>`__
- - `(plain text) <http://www.openvswitch.org/support/dist-docs/ovs-tcpundump.1.txt>`__
* - ovs-test(8)
- `(pdf) <http://www.openvswitch.org/support/dist-docs/ovs-test.8.pdf>`__
- `(html) <http://www.openvswitch.org/support/dist-docs/ovs-test.8.html>`__
new file mode 100644
@@ -0,0 +1,332 @@
+==========
+ovs-appctl
+==========
+
+Synopsis
+========
+
+``ovs-appctl``
+[``--target=``<target> | ``-t`` <target>]
+[``--timeout=``<secs> | ``-T`` <secs>]
+<command> [<arg>...]
+
+``ovs-appctl --help``
+
+``ovs-appctl --version``
+
+Description
+===========
+
+Open vSwitch daemons accept certain commands at runtime to control
+their behavior and query their settings. Every daemon accepts a
+common set of commands documented under `Common Commands`_ below.
+Some daemons support additional commands documented in their own
+manpages. ``ovs-vswitchd`` in particular accepts a number of
+additional commands documented in ``ovs-vswitchd(8)``.
+
+The ``ovs-appctl`` program provides a simple way to invoke these
+commands. The command to be sent is specified on ``ovs-appctl``'s
+command line as non-option arguments. ``ovs-appctl`` sends the
+command and prints the daemon's response on standard output.
+
+In normal use only a single option is accepted:
+
+* ``-t`` <target> or ``--target`` <target>
+
+ Tells ``ovs-appctl`` which daemon to contact.
+
+ If <target> begins with ``/`` it must name a Unix domain socket on
+ which an Open vSwitch daemon is listening for control channel
+ connections. By default, each daemon listens on a Unix domain socket
+ in the rundir (e.g. ``/run``) named ``<program>.<pid>.ctl``, where
+ <program> is the program's name and <pid> is its process ID. For
+ example, if ``ovs-vswitchd`` has PID 123, it would listen on
+ ``ovs-vswitchd.123.ctl``.
+
+ Otherwise, ``ovs-appctl`` looks in the rundir for a pidfile, that is,
+ a file whose contents are the process ID of a running process as a
+ decimal number, named ``<target>.pid``. (The ``--pidfile`` option
+ makes an Open vSwitch daemon create a pidfile.) ``ovs-appctl`` reads
+ the pidfile, then looks in the rundir for a Unix socket named
+ ``<target>.<pid>.ctl``, where <pid> is replaced by the process ID read
+ from the pidfile, and uses that file as if it had been specified
+ directly as the target.
+
+ On Windows, <target> can be an absolute path to a file that contains a
+ localhost TCP port on which an Open vSwitch daemon is listening for
+ control channel connections. By default, each daemon writes the TCP
+ port on which it is listening for control connection into the file
+ ``<program>.ctl`` located inside the rundir. If <target> is not an
+ absolute path, ``ovs-appctl`` looks in the rundir for a file named
+ ``<target>.ctl``. The default target is ``ovs-vswitchd``.
+
+* ``-T <secs>`` or ``--timeout=<secs>``
+
+ By default, or with a <secs> of ``0``, ``ovs-appctl`` waits forever to
+ connect to the daemon and receive a response. This option limits
+ runtime to approximately <secs> seconds. If the timeout expires,
+ ``ovs-appctl`` exits with a ``SIGALRM`` signal.
+
+Common Commands
+===============
+
+Every Open vSwitch daemon supports a common set of commands, which are
+documented in this section.
+
+General Commands
+----------------
+
+These commands display daemon-specific commands and the running version.
+Note that these commands are different from the ``--help`` and
+``--version`` options that return information about the
+``ovs-appctl`` utility itself.
+
+* ``list-commands``
+
+ Lists the commands supported by the target.
+
+* ``version``
+
+ Displays the version and compilation date of the target.
+
+Logging Commands
+----------------
+
+Open vSwitch has several log levels. The highest-severity log level is:
+
+* ``off``
+
+ No message is ever logged at this level, so setting a logging
+ destination's log level to ``off`` disables logging to that destination.
+
+The following log levels, in order of descending severity, are
+available:
+
+* ``emer``
+
+ A major failure forced a process to abort.
+
+* ``err``
+
+ A high-level operation or a subsystem failed. Attention is
+ warranted.
+
+* ``warn``
+
+ A low-level operation failed, but higher-level subsystems may be able
+ to recover.
+
+* ``info``
+
+ Information that may be useful in retrospect when investigating
+ a problem.
+
+* ``dbg``
+
+ Information useful only to someone with intricate knowledge of the
+ system, or that would commonly cause too-voluminous log output. Log
+ messages at this level are not logged by default.
+
+Every Open vSwitch daemon supports the following commands for examining
+and adjusting log levels:
+
+* ``vlog/list``
+
+ Lists the known logging modules and their current levels.
+
+* ``vlog/list-pattern``
+
+ Lists logging pattern used for each destination.
+
+* ``vlog/set`` [<spec>]
+
+ Sets logging levels. Without any <spec>, sets the log level for
+ every module and destination to ``dbg``. Otherwise, <spec> is a
+ list of words separated by spaces or commas or colons, up to one from
+ each category below:
+
+ * A valid module name, as displayed by the ``vlog/list`` command on
+ ``ovs-appctl(8)``, limits the log level change to the specified
+ module.
+
+ * ``syslog``, ``console``, or ``file``, to limit the log level
+ change to only to the system log, to the console, or to a file,
+ respectively.
+
+ On Windows platform, ``syslog`` is only useful if <target> was
+ started with the ``--syslog-target`` option (it has no effect
+ otherwise).
+
+ * ``off``, ``emer``, ``err``, ``warn``, ``info``, or ``dbg``, to
+ control the log level. Messages of the given severity or higher
+ will be logged, and messages of lower severity will be filtered out.
+ ``off`` filters out all messages.
+
+ Case is not significant within <spec>.
+
+ Regardless of the log levels set for ``file``, logging to a file
+ will not take place unless the target application was invoked with the
+ ``--log-file`` option.
+
+ For compatibility with older versions of OVS, ``any`` is accepted
+ within <spec> but it has no effect.
+
+* ``vlog/set PATTERN:<destination>:<pattern>``
+
+ Sets the log pattern for <destination> to <pattern>. Each time a
+ message is logged to <destination>, <pattern> determines the
+ message's formatting. Most characters in <pattern> are copied
+ literally to the log, but special escapes beginning with ``%`` are
+ expanded as follows:
+
+ * ``%A``
+
+ The name of the application logging the message, e.g. ``ovs-vswitchd``.
+
+ * ``%B``
+
+ The RFC5424 syslog PRI of the message.
+
+ * ``%c``
+
+ The name of the module (as shown by ``ovs-appctl --list``) logging
+ the message.
+
+ * ``%d``
+
+ The current date and time in ISO 8601 format (YYYY-MM-DD HH:MM:SS).
+
+ * ``%d{<format>}``
+
+ The current date and time in the specified <format>, which takes
+ the same format as the <template> argument to ``strftime(3)``. As
+ an extension, any ``#`` characters in <format> will be replaced by
+ fractional seconds, e.g. use ``%H:%M:%S.###`` for the time to the
+ nearest millisecond. Sub-second times are only approximate and
+ currently decimal places after the third will always be reported
+ as zero.
+
+ * ``%D``
+
+ The current UTC date and time in ISO 8601 format (YYYY-MM-DD
+ HH:MM:SS).
+
+ * ``%D{<format>}``
+
+ The current UTC date and time in the specified <format>, which
+ takes the same format as the <template> argument to
+ ``strftime``(3). Supports the same extension for sub-second
+ resolution as ``%d{...}``.
+
+ * ``%E``
+
+ The hostname of the node running the application.
+
+ * ``%m``
+
+ The message being logged.
+
+ * ``%N``
+
+ A serial number for this message within this run of the program,
+ as a decimal number. The first message a program logs has serial
+ number 1, the second one has serial number 2, and so on.
+
+ * ``%n``
+
+ A new-line.
+
+ * ``%p``
+
+ The level at which the message is logged, e.g. ``DBG``.
+
+ * ``%P``
+
+ The program's process ID (pid), as a decimal number.
+
+ * ``%r``
+
+ The number of milliseconds elapsed from the start of the
+ application to the time the message was logged.
+
+ * ``%t``
+
+ The subprogram name, that is, an identifying name for the process
+ or thread that emitted the log message, such as ``monitor`` for
+ the process used for ``--monitor`` or ``main`` for the primary
+ process or thread in a program.
+
+ * ``%T``
+
+ The subprogram name enclosed in parentheses, e.g. ``(monitor)``,
+ or the empty string for the primary process or thread in a
+ program.
+
+ * ``%%``
+
+ A literal ``%``.
+
+ A few options may appear between the ``%`` and the format specifier
+ character, in this order:
+
+ * ``-``
+
+ Left justify the escape's expansion within its field width. Right
+ justification is the default.
+
+ * ``0``
+
+ Pad the field to the field width with ``0`` characters. Padding
+ with spaces is the default.
+
+ * <width>
+
+ A number specifies the minimum field width. If the escape expands
+ to fewer characters than <width> then it is padded to fill the
+ field width. (A field wider than <width> is not truncated to
+ fit.)
+
+ The default pattern for console and file output is ``%D{%Y-%m-%dT
+ %H:%M:%SZ}|%05N|%c|%p|%m``; for syslog output, ``%05N|%c|%p|%m``.
+
+ Daemons written in Python (e.g. ``ovs-xapi-sync``) do not allow
+ control over the log pattern.
+
+* ``vlog/set FACILITY:<facility>``
+
+ Sets the RFC5424 facility of the log message. <facility> can be one
+ of ``kern``, ``user``, ``mail``, ``daemon``, ``auth``, ``syslog``,
+ ``lpr``, ``news``, ``uucp``, ``clock``, ``ftp``, ``ntp``, ``audit``,
+ ``alert``, ``clock2``, ``local0``, ``local1``, ``local2``,
+ ``local3``, ``local4``, ``local5``, ``local6`` or ``local7``.
+
+* ``vlog/close``
+
+ Causes the daemon to close its log file, if it is open. (Use
+ ``vlog/reopen`` to reopen it later.)
+
+* ``vlog/reopen``
+
+ Causes the daemon to close its log file, if it is open, and then
+ reopen it. (This is useful after rotating log files, to cause a new
+ log file to be used.)
+
+ This has no effect if the target application was not invoked with
+ the ``--log-file`` option.
+
+Options
+=======
+
+.. option:: -h, --help
+
+ Prints a brief help message to the console.
+
+.. option:: -V, --version
+
+ Prints version information to the console.
+
+See Also
+========
+
+``ovs-appctl`` can control all Open vSwitch daemons, including
+``ovs-vswitchd(8)`` and ``ovsdb-server(1)``.
new file mode 100644
@@ -0,0 +1,491 @@
+=======
+ovs-ctl
+=======
+
+Synopsis
+========
+
+``ovs-ctl --system-id=random|<uuid> [<options>] start``
+
+``ovs-ctl stop``
+
+``ovs-ctl --system-id=random|<uuid> [<options>] restart``
+
+``ovs-ctl status``
+
+``ovs-ctl version``
+
+``ovs-ctl [<options>] load-kmod``
+
+``ovs-ctl --system-id=random|<uuid> [<options>] force-reload-kmod``
+
+``ovs-ctl [--protocol=<protocol>] [--sport=<sport>] [--dport=<dport>]
+enable-protocol``
+
+``ovs-ctl delete-transient-ports``
+
+``ovs-ctl help | -h | --help``
+
+``ovs-ctl --version``
+
+Description
+===========
+
+The ``ovs-ctl`` program starts, stops, and checks the status of
+Open vSwitch daemons. It is not meant to be invoked directly by
+system administrators but to be called internally by system startup
+scripts.
+
+
+Each ``ovs-ctl`` command is described separately below.
+
+The ``start`` command
+---------------------
+
+The ``start`` command starts Open vSwitch. It performs the
+following tasks:
+
+1. Loads the Open vSwitch kernel module. If this fails, and the Linux
+ bridge module is loaded but no bridges exist, it tries to unload
+ the bridge module and tries loading the Open vSwitch kernel module
+ again. (This is because the Open vSwitch kernel module cannot
+ coexist with the Linux bridge module before 2.6.37.)
+
+The ``start`` command skips the following steps if ``ovsdb-server`` is
+already running:
+
+2. If the Open vSwitch database file does not exist, it creates it.
+ If the database does exist, but it has an obsolete version, it
+ upgrades it to the latest schema.
+
+3. Starts ``ovsdb-server``, unless the ``--no-ovsdb-server`` command
+ option is given.
+
+4. Initializes a few values inside the database.
+
+5. If the ``--delete-bridges`` option was used, deletes all of the
+ bridges from the database.
+
+6. If the ``--delete-transient-ports`` option was used, deletes all
+ ports that have ``other_config:transient`` set to true.
+
+The ``start`` command skips the following step if ``ovs-vswitchd`` is
+already running, or if the ``--no-ovs-vswitchd`` command option is
+given:
+
+7. Starts ``ovs-vswitchd``.
+
+Options
+~~~~~~~
+
+Several command-line options influence the ``start`` command's
+behavior. Some form of the following option should ordinarily be
+specified:
+
+* ``--system-id=<uuid>`` or ``--system-id=random``
+
+ This specifies a unique system identifier to store into
+ ``external-ids:system-id`` in the database's ``Open_vSwitch`` table.
+ Remote managers that talk to the Open vSwitch database server over
+ network protocols use this value to identify and distinguish Open
+ vSwitch instances, so it should be unique (at least) within OVS
+ instances that will connect to a single controller.
+
+ When ``random`` is specified, ``ovs-ctl`` will generate a random ID
+ that persists from one run to another (stored in a file). When
+ another string is specified ``ovs-ctl`` uses it literally.
+
+The following options should be specified if the defaults are not
+suitable:
+
+* ``--system-type=<type>`` or ``--system-version=<version>``
+
+ Sets the value to store in the ``system-type`` and
+ ``system-version`` columns, respectively, in the database's
+ ``Open_vSwitch`` table. Remote managers may use these values too
+ determine the kind of system to which they are connected (primarily
+ for display to human administrators).
+
+ When not specified, ``ovs-ctl`` uses values from the optional
+ ``system-type.conf`` and ``system-version.conf`` files (see
+ `Files`_) or it uses the ``lsb_release`` program, if present, to
+ provide reasonable defaults.
+
+The following options are also likely to be useful:
+
+* ``--external-id="<name>=<value>"``
+
+ Sets ``external-ids:<name>`` to <value> in the database's
+ ``Open_vSwitch`` table. Specifying this option multiple times adds
+ multiple key-value pairs.
+
+* ``--delete-bridges``
+
+ Ordinarily Open vSwitch bridges persist from one system boot to the
+ next, as long as the database is preserved. Some environments
+ instead expect to re-create all of the bridges and other
+ configuration state on every boot. This option supports that, by
+ deleting all Open vSwitch bridges after starting ``ovsdb-server``
+ but before starting ``ovs-vswitchd``.
+
+* ``--delete-transient-ports``
+
+ Deletes all ports that have ``other_config:transient`` set to
+ ``true``. This is important on certain environments where some
+ ports are going to be recreated after reboot, but other ports need
+ to be persisted in the database.
+
+* ``--ovs-user=user[:group]``
+
+ Ordinarily Open vSwitch daemons are started as the user invoking the
+ ovs-ctl command. Some system administrators would prefer to have
+ the various daemons spawn as different users in their environments.
+ This option allows passing the ``--user`` option to the
+ ``ovsdb-server`` and ``ovs-vswitchd`` daemons, allowing them to
+ change their privilege levels.
+
+The following options are less important:
+
+* ``--no-monitor``
+
+ By default ``ovs-ctl`` passes ``--monitor`` to ``ovs-vswitchd`` and
+ ``ovsdb-server``, requesting that it spawn a process monitor which
+ will restart the daemon if it crashes. This option suppresses that
+ behavior.
+
+* ``--daemon-cwd=<directory>``
+
+ Specifies the current working directory that the OVS daemons should
+ run from. The default is ``/`` (the root directory) if this option
+ is not specified. (This option is useful because most systems
+ create core files in a process's current working directory and
+ because a file system that is in use as a process's current working
+ directory cannot be unmounted.)
+
+* ``--no-force-corefiles``
+
+ By default, ``ovs-ctl`` enables core dumps for the OVS daemons.
+ This option disables that behavior.
+
+* ``--no-mlockall``
+
+ By default ``ovs-ctl`` passes ``--mlockall`` to ``ovs-vswitchd``,
+ requesting that it lock all of its virtual memory, preventing it
+ from being paged to disk. This option suppresses that behavior.
+
+* ``--no-self-confinement``
+
+ Disable self-confinement for ``ovs-vswitchd`` and ``ovsdb-server``
+ daemons. This flag may be used when, for example, OpenFlow
+ controller creates its Unix Domain Socket outside OVS run directory
+ and OVS needs to connect to it. It is better to stick with the
+ default behavior and not to use this flag, unless:
+
+ - You have Open vSwitch running under SELinux or AppArmor Mandatory
+ Access Control that would prevent OVS from messing with sockets
+ outside ordinary OVS directories.
+
+ - You believe that relying on protocol handshakes (e.g. OpenFlow) is
+ enough to prevent OVS to adversely interact with other daemons
+ running on your system.
+
+ - You don't have much worries of remote OVSDB exploits in the first
+ place, because, perhaps, OVSDB manager is running on the same host
+ as OVS and share similar attack vectors.
+
+* ``--ovsdb-server-priority=<niceness>`` or
+ ``--ovs-vswitchd-priority=<niceness>``
+
+ Sets the ``nice(1)`` level used for each daemon. All of them
+ default to ``-10``.
+
+* ``--ovsdb-server-wrapper=<wrapper>`` or
+ ``--ovs-vswitchd-wrapper=<wrapper>``
+
+ Configures the specified daemon to run under <wrapper>, which is one
+ of the following:
+
+ * ``valgrind``: Run the daemon under ``valgrind(1)``, if it is
+ installed, logging to ``<daemon>.valgrind.log.<pid>`` in the log
+ directory.
+
+ * ``strace``: Run the daemon under ``strace(1)``, if it is
+ installed, logging to ``<daemon>.strace.log.<pid>`` in the log
+ directory.
+
+ * ``glibc``: Enable GNU C library features designed to find memory
+ errors.
+
+ By default, no wrapper is used.
+
+ Each of the wrappers can expose bugs in Open vSwitch that lead to
+ incorrect operation, including crashes. The ``valgrind`` and
+ ``strace`` wrappers greatly slow daemon operations so they should
+ not be used in production. They also produce voluminous logs that
+ can quickly fill small disk partitions. The ``glibc`` wrapper is
+ less resource-intensive but still somewhat slows the daemons.
+
+The following options control file locations. They should only be
+used if the default locations cannot be used. See ``FILES``, below,
+for more information.
+
+* ``--db-file=<file>``
+
+ Overrides the file name for the OVS database.
+
+* ``--db-sock=<socket>``
+
+ Overrides the file name for the Unix domain socket used to connect
+ to ``ovsdb-server``.
+
+* ``--db-schema=<schema>``
+
+ Overrides the file name for the OVS database schema.
+
+* ``--extra-dbs=<file>``
+
+ Adds <file> as an extra database for ``ovsdb-server`` to serve out.
+ Multiple space-separated file names may also be specified. <file>
+ should begin with ``/``; if it does not, then it will be taken as
+ relative to <dbdir>.
+
+The ``stop`` command
+--------------------
+
+The ``stop`` command stops the ``ovs-vswitchd`` and ``ovsdb-server``
+daemons. It does not unload the Open vSwitch kernel modules. It can
+take the same ``--no-ovsdb-server`` and ``--no-ovs-vswitchd`` options
+as that of the ``start`` command.
+
+This command does nothing and finishes successfully if the OVS daemons
+aren't running.
+
+The ``restart`` command
+-----------------------
+
+The ``restart`` command performs a ``stop`` followed by a ``start``
+command. The command can take the same options as that of the
+``start`` command. In addition, it saves and restores OpenFlow flows
+for each individual bridge.
+
+The ``status`` command
+----------------------
+
+The ``status`` command checks whether the OVS daemons
+``ovs-vswitchd`` and ``ovsdb-server`` are running and prints
+messages with that information. It exits with status 0 if
+the daemons are running, 1 otherwise.
+
+The ``version`` command
+-----------------------
+
+The ``version`` command runs ``ovsdb-server --version`` and
+``ovs-vswitchd --version``.
+
+The ``force-reload-kmod`` command
+---------------------------------
+
+The ``force-reload-kmod`` command allows upgrading the Open vSwitch
+kernel module without rebooting. It performs the following tasks:
+
+1. Gets a list of OVS "internal" interfaces, that is, network
+ devices implemented by Open vSwitch. The most common examples of
+ these are bridge "local ports".
+
+2. Saves the OpenFlow flows of each bridge.
+
+3. Stops the Open vSwitch daemons, as if by a call to ``ovs-ctl
+ stop``.
+
+4. Saves the kernel configuration state of the OVS internal interfaces
+ listed in step 1, including IP and IPv6 addresses and routing table
+ entries.
+
+5. Unloads the Open vSwitch kernel module (including the bridge
+ compatibility module if it is loaded).
+
+6. Starts OVS back up, as if by a call to ``ovs-ctl start``. This
+ reloads the kernel module, restarts the OVS daemons and finally
+ restores the saved OpenFlow flows.
+
+7. Restores the kernel configuration state that was saved in step 4.
+
+8. Checks for daemons that may need to be restarted because they have
+ packet sockets that are listening on old instances of Open vSwitch
+ kernel interfaces and, if it finds any, prints a warning on stdout.
+ DHCP is a common example: if the ISC DHCP client is running on an
+ OVS internal interface, then it will have to be restarted after
+ completing the above procedure. (It would be nice if ``ovs-ctl``
+ could restart daemons automatically, but the details are far too
+ specific to a particular distribution and installation.)
+
+``force-kmod-reload`` internally stops and starts OVS, so it accepts
+all of the options accepted by the ``start`` command except for the
+``--no-ovs-vswitchd`` option.
+
+The ``load-kmod`` command
+-------------------------
+
+The ``load-kmod`` command loads the openvswitch kernel modules if they
+are not already loaded. This operation also occurs as part of the
+``start`` command. The motivation for providing the ``load-kmod``
+command is to allow errors when loading modules to be handled
+separately from other errors that may occur when running the
+``start`` command.
+
+By default the ``load-kmod`` command attempts to load the
+``openvswitch`` kernel module.
+
+The ``enable-protocol`` command
+-------------------------------
+
+The ``enable-protocol`` command checks for rules related to a
+specified protocol in the system's ``iptables(8)`` configuration. If
+there are no rules specifically related to that protocol, then it
+inserts a rule to accept the specified protocol.
+
+More specifically:
+
+* If ``iptables`` is not installed or not enabled, this command does
+ nothing, assuming that lack of filtering means that the protocol is
+ enabled.
+
+* If the ``INPUT`` chain has a rule that matches the specified
+ protocol, then this command does nothing, assuming that whatever
+ rule is installed reflects the system administrator's decisions.
+
+* Otherwise, this command installs a rule that accepts traffic of the
+ specified protocol.
+
+This command normally completes successfully, even if it does nothing.
+Only the failure of an attempt to insert a rule normally causes it to
+return an exit code other than 0.
+
+The following options control the protocol to be enabled:
+
+* ``--protocol=<protocol>``
+
+ The name of the IP protocol to be enabled, such as ``gre`` or
+ ``tcp``. The default is ``gre``.
+
+* ``--sport=<sport>`` or ``--dport=<dport>``
+
+ TCP or UDP source or destination port to match. These are optional
+ and allowed only with ``--protocol=tcp`` or ``--protocol=udp``.
+
+The ``delete-transient-ports`` command
+--------------------------------------
+
+Deletes all ports that have the ``other_config:transient`` value set to true.
+
+The ``help`` command
+--------------------
+
+Prints a usage message and exits successfully.
+
+Options
+=======
+
+In addition to the options listed for each command above, these
+options control the behavior of several ``ovs-ctl`` commands.
+
+By default, ``ovs-ctl`` controls the ``ovsdb-server`` and
+``ovs-vswitchd`` daemons. The following options restrict that control
+to exclude one or the other:
+
+* ``--no-ovsdb-server``
+
+ Specifies that the ``ovs-ctl`` commands ``start``, ``stop``, and
+ ``restart`` should not modify the running status of
+ ``ovsdb-server``.
+
+* ``--no-ovs-vswitchd``
+
+ Specifies that the ``ovs-ctl`` commands ``start``, ``stop``, and
+ ``restart`` should not modify the running status of
+ ``ovs-vswitchd``. It is an error to include this option with the
+ ``force-reload-kmod`` command.
+
+Exit Status
+===========
+
+``ovs-ctl`` exits with status 0 on success and nonzero on failure.
+The ``start`` command is considered to succeed if OVS is already
+started; the ``stop`` command is considered to succeed if OVS is
+already stopped.
+
+Environment
+===========
+
+The following environment variables affect ``ovs-ctl``:
+
+* ``PATH``
+
+ ``ovs-ctl`` does not hardcode the location of any of the programs
+ that it runs. ``ovs-ctl`` will add the <sbindir> and <bindir> that
+ were specified at ``configure`` time to ``PATH``, if they are not
+ already present.
+
+* ``OVS_LOGDIR``, ``OVS_RUNDIR``, ``OVS_DBDIR``, ``OVS_SYSCONFDIR``,
+ ``OVS_PKGDATADIR``, ``OVS_BINDIR``, ``OVS_SBINDIR``
+
+ Setting one of these variables in the environment overrides the
+ respective ``configure`` option, both for ``ovs-ctl`` itself and for
+ the other Open vSwitch programs that it runs.
+
+Files
+=====
+
+``ovs-ctl`` uses the following files:
+
+* ``ovs-lib``
+
+ Shell function library used internally by ``ovs-ctl``. It must be
+ installed in the same directory as ``ovs-ctl``.
+
+* ``<logdir>/<daemon>.log``
+
+ Per-daemon logfiles.
+
+* ``<rundir>/<daemon>.pid``
+
+ Per-daemon pidfiles to track whether a daemon is running and with
+ what process ID.
+
+* ``<pkgdatadir>/vswitch.ovsschema``
+
+ The OVS database schema used to initialize the database (use
+ ``--db-schema`` to override this location).
+
+* ``<dbdir>/conf.db``
+
+ The OVS database (use ``--db-file`` to override this location).
+
+* ``<rundir>/openvswitch/db.sock``
+
+ The Unix domain socket used for local communication with
+ ``ovsdb-server`` (use ``--db-sock`` to override this location).
+
+* ``<sysconfdir>/openvswitch/system-id.conf``
+
+ The persistent system UUID created and read by
+ ``--system-id=random``.
+
+* ``<sysconfdir>/openvswitch/system-type.conf`` and
+ ``<sysconfdir>/openvswitch/system-version.conf``
+
+ The ``system-type`` and ``system-version`` values stored in the
+ database's ``Open_vSwitch`` table when not specified as a
+ command-line option.
+
+Example
+=======
+
+The files ``debian/openvswitch-switch.init`` and
+``xenserver/etc_init.d_openvswitch`` in the Open vSwitch source
+distribution are good examples of how to use ``ovs-ctl``.
+
+See Also
+========
+
+``README.rst``, ``ovsdb-server(8)``, ``ovs-vswitchd(8)``.
new file mode 100644
@@ -0,0 +1,129 @@
+==========
+ovs-l3ping
+==========
+
+Synopsis
+========
+
+``ovs-l3ping -s <TunnelRemoteIP>,<InnerIP>[/<mask>] -t <tunnelmode>``
+
+``ovs-l3ping -s <TunnelRemoteIP>,<InnerIP>[/<mask>][:<ControlPort>] -t
+<tunnelmode>``
+
+``ovs-l3ping -c <TunnelRemoteIP>,<InnerIP>[/<mask>],<RemoteInnerIP> -t
+<tunnelmode>``
+
+``ovs-l3ping -c
+<TunnelRemoteIP>,<InnerIP>[/<mask>][:<ControlPort>[:<DataPort>]],<RemoteInnerIP>[:<ControlPort>[:<DataPort>]]
+[-b <targetbandwidth>] [-i <testinterval>]
+-t <tunnelmode>``
+
+``ovs-l3ping -h | --help``
+
+``ovs-l3ping -V | --version``
+
+Description
+===========
+
+The ``ovs-l3ping`` program may be used to check for problems that
+could be caused by invalid routing policy, misconfigured firewall in
+the tunnel path or a bad NIC driver. On one of the nodes, run
+``ovs-l3ping`` in server mode and on the other node run it in client
+mode. The client and server will establish L3 tunnel, over which
+client will give further testing instructions. The ``ovs-l3ping``
+client will perform UDP and TCP tests. This tool is different from
+``ovs-test`` that it encapsulates XML/RPC control connection over the
+tunnel, so there is no need to open special holes in firewall.
+
+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.
+
+Client Mode
+-----------
+
+An ``ovs-l3ping`` client will create a L3 tunnel and connect over it
+to the ``ovs-l3ping`` server to schedule the tests. <TunnelRemoteIP>
+is the peer's IP address, where tunnel will be terminated. <InnerIP>
+is the address that will be temporarily assigned during testing. All
+test traffic originating from this IP address to the <RemoteInnerIP>
+will be tunneled. It is possible to override default <ControlPort>
+and <DataPort>, if there is any other application that already listens
+on those two ports.
+
+Server Mode
+-----------
+
+To conduct tests, ``ovs-l3ping`` server must be running. It is
+required that both client and server <InnerIP> addresses are in the
+same subnet. It is possible to specify <InnerIP> with netmask in CIDR
+format.
+
+Options
+=======
+
+One of ``-s`` or ``-c`` is required. The ``-t`` option is
+also required.
+
+* ``-s <TunnelRemoteIP>,<InnerIP>[/<mask>][:<ControlPort>]`` or
+ ``--server <TunnelRemoteIP>,<InnerIP>[/<mask>][:<ControlPort>]``
+
+ Run in server mode and create L3 tunnel with the client that will be
+ accepting tunnel at <TunnelRemoteIP> address. The socket on
+ ``<InnerIP>[:<ControlPort>]`` will be used to receive further
+ instructions from the client.
+
+* ``-c
+ <TunnelRemoteIP>,<InnerIP>[/<mask>][:<ControlPort>[:<DataPort>]],<RemoteInnerIP>[:<ControlPort>[:<DataPort>]]``
+ or ``--client
+ <TunnelRemoteIP>,<InnerIP>[/<mask>][:<ControlPort>[:<DataPort>]],<RemoteInnerIP>[:<ControlPort>[:<DataPort>]]``
+
+ Run in client mode and create L3 tunnel with the server on
+ <TunnelRemoteIP>. The client will use <InnerIP> to generate test
+ traffic with the server's <RemoteInnerIP>.
+
+* ``-b <targetbandwidth>`` or ``--bandwidth <targetbandwidth>``
+
+ Target bandwidth for UDP tests. The <targetbandwidth> must be given
+ in bits per second. Use postfix M or K to alter the target
+ bandwidth magnitude.
+
+* ``-i <testinterval>`` or ``--interval <testinterval>``
+
+ How long each test should run. By default 5 seconds.
+
+* ``-t <tunnelmode>`` or ``--tunnel-mode <tunnelmode>``
+
+ Specify the tunnel type. This option must match on server and
+ client.
+
+* ``-h`` or ``--help``
+
+ Prints a brief help message to the console.
+
+* ``-V`` or ``--version``
+
+ Prints version information to the console.
+
+Examples
+========
+
+On host 192.168.122.220 start ``ovs-l3ping`` in server mode. This command
+will create a temporary GRE tunnel with the host 192.168.122.236 and assign
+10.1.1.1/28 as the inner IP address, where client will have to connect::
+
+ ovs-l3ping -s 192.168.122.236,10.1.1.1/28 -t gre
+
+On host 192.168.122.236 start ``ovs-l3ping`` in client mode. This command
+will use 10.1.1.2/28 as the local inner IP address and will connect over the
+L3 tunnel to the server's inner IP address at 10.1.1.1::
+
+ ovs-l3ping -c 192.168.122.220,10.1.1.2/28,10.1.1.1 -t gre
+
+See Also
+========
+
+``ovs-vswitchd(8)``, ``ovs-ofctl(8)``, ``ovs-vsctl(8)``,
+``ovs-vlan-test(8)``, ``ovs-test(8)``, ``ethtool(8)``, ``uname(1)``.
new file mode 100644
@@ -0,0 +1,34 @@
+===================
+ovs-parse-backtrace
+===================
+
+Synopsis
+========
+
+``ovs-appctl backtrace | ovs-parse-backtrace [<binary>]``
+
+``ovs-parse-backtrace [<binary>] < <backtrace>``
+
+Description
+===========
+
+In some configurations, many Open vSwitch daemons can produce a series of
+backtraces using the ``ovs-appctl backtrace`` command. Users can analyze
+these backtraces to figure out what the given Open vSwitch daemon may be
+spending most of its time doing. ``ovs-parse-backtrace`` makes this output
+easier to interpret.
+
+The ``ovs-appctl backtrace`` output must be supplied on standard input. The
+binary that produced the output should be supplied as the sole non-option
+argument. For best results, the binary should have debug symbols.
+
+Options
+=======
+
+* ``--help``
+
+ Prints a usage message and exits.
+
+* ``--version``
+
+ Prints the version and exits.
new file mode 100644
@@ -0,0 +1,251 @@
+=======
+ovs-pki
+=======
+
+Synopsis
+========
+
+Each command takes the form:
+
+``ovs-pki <options> <command> <args>...``
+
+The implemented commands and their arguments are:
+
+* ``ovs-pki init``
+
+* ``ovs-pki req <name>``
+
+* ``ovs-pki sign <name> [<type>]``
+
+* ``ovs-pki req+sign <name> [<type>]``
+
+* ``ovs-pki verify <name> [<type>]``
+
+* ``ovs-pki fingerprint <file>``
+
+* ``ovs-pki self-sign <name>``
+
+Each <type> above is a certificate type, either ``switch``
+(default) or ``controller``.
+
+The available options are:
+
+* ``-k <type>`` or ``--key=<type>``
+
+* ``-B <nbits>`` or ``--bits=<nbits>``
+
+* ``-D <file>`` or ``--dsaparam=<file>``
+
+* ``-b`` or ``--batch``
+
+* ``-f`` or ``--force``
+
+* ``-d <dir>`` or ``--dir=<dir>``
+
+* ``-l <file>`` or ``--log=<file>``
+
+* ``-u`` or ``--unique``
+
+* ``-h`` or ``--help``
+
+
+Description
+===========
+
+The ``ovs-pki`` program sets up and manages a public key
+infrastructure for use with OpenFlow. It is intended to be a simple
+interface for organizations that do not have an established public key
+infrastructure. Other PKI tools can substitute for or supplement the
+use of ``ovs-pki``.
+
+``ovs-pki`` uses ``openssl(1)`` for certificate management and key
+generation.
+
+Offline Commands
+================
+
+The following ``ovs-pki`` commands support manual PKI administration:
+
+* ``init``
+
+ Initializes a new PKI (by default in ``/var/lib/openvswitch/pki``,
+ although this default may be changed at Open vSwitch build time) and
+ populates it with a pair of certificate authorities for controllers
+ and switches.
+
+ This command should ideally be run on a high-security machine
+ separate from any OpenFlow controller or switch, called the CA
+ machine. The files ``pki/controllerca/cacert.pem`` and
+ ``pki/switchca/cacert.pem`` that it produces will need to be copied
+ over to the OpenFlow switches and controllers, respectively. Their
+ contents may safely be made public.
+
+ By default, ``ovs-pki`` generates 2048-bit RSA keys. The ``-B`` or
+ ``--bits`` option (see below) may be used to override the key
+ length. The ``-k dsa`` or ``--key=dsa`` option may be used to use
+ DSA in place of RSA. If DSA is selected, the ``dsaparam.pem`` file
+ generated in the new PKI hierarchy must be copied to any machine on
+ which the ``req`` command (see below) will be executed. Its
+ contents may safely be made public.
+
+ Other files generated by ``init`` may remain on the CA machine. The
+ files ``pki/controllerca/private/cakey.pem`` and
+ ``pki/switchca/private/cakey.pem`` have particularly sensitive
+ contents that should not be exposed.
+
+* ``req <name>``
+
+ Generates a new private key named ``<name>-privkey.pem`` and
+ corresponding certificate request named ``<name>-req.pem``.
+ The private key can be intended for use by a switch or a controller.
+
+ This command should ideally be run on the switch or controller that
+ will use the private key to identify itself. The file
+ ``<name>-req.pem`` must be copied to the CA machine for signing
+ with the ``sign`` command (below).
+
+ This command will output a fingerprint to stdout as its final step.
+ Write down the fingerprint and take it to the CA machine before
+ continuing with the ``sign`` step.
+
+ When RSA keys are in use (as is the default), ``req``, unlike the
+ rest of the ``ovs-pki`` commands, does not need access to a PKI
+ hierarchy created by ``ovs-pki init``. The ``-B`` or
+ ``--bits`` option (see below) may be used to specify the number of
+ bits in the generated RSA key.
+
+ When DSA keys are used (as specified with ``--key=dsa``), ``req``
+ needs access to the ``dsaparam.pem`` file created as part of the PKI
+ hierarchy (but not to other files in that tree). By default,
+ ``ovs-pki`` looks for this file in the PKI directory as
+ ``dsaparam.pem``, but the ``-D`` or ``--dsaparam`` option (see
+ below) may be used to specify an alternate location.
+
+ ``<name>-privkey.pem`` has sensitive contents that should not be
+ exposed. ``<name>-req.pem`` may be safely made public.
+
+* ``sign <name> [<type>]``
+
+ Signs the certificate request named ``<name>-req.pem`` that was
+ produced in the previous step, producing a certificate named
+ ``<name>-cert.pem``. <type>, either ``switch`` (default) or
+ ``controller``, indicates the use for which the key is being
+ certified.
+
+ This command must be run on the CA machine.
+
+ The command will output a fingerprint to stdout and request that you
+ verify that it is the same fingerprint output by the ``req``
+ command. This ensures that the request being signed is the same one
+ produced by ``req``. (The ``-b`` or ``--batch`` option
+ suppresses the verification step.)
+
+ The file ``<name>-cert.pem`` will need to be copied back to the
+ switch or controller for which it is intended. Its contents may
+ safely be made public.
+
+* ``req+sign <name> [<type>]``
+
+ Combines the ``req`` and ``sign`` commands into a single step,
+ outputting all the files produced by each. The
+ ``<name>-privkey.pem`` and ``<name>-cert.pem`` files must
+ be copied securely to the switch or controller.
+ ``<name>-privkey.pem`` has sensitive contents and must not be
+ exposed in transit. Afterward, it should be deleted from the CA
+ machine.
+
+ This combined method is, theoretically, less secure than the
+ individual steps performed separately on two different machines,
+ because there is additional potential for exposure of the private
+ key. However, it is also more convenient.
+
+* ``verify <name> [<type>]``
+
+ Verifies that ``<name>-cert.pem`` is a valid certificate for the
+ given <type> of use, either ``switch`` (default) or ``controller``.
+ If the certificate is valid for this use, it prints the message
+ ``<name>-cert.pem: OK``; otherwise, it prints an error message.
+
+* ``fingerprint <file>``
+
+ Prints the fingerprint for <file>. If <file> is a
+ certificate, then this is the SHA-1 digest of the DER encoded version
+ of the certificate; otherwise, it is the SHA-1 digest of the entire
+ file.
+
+* ``self-sign <name>``
+
+ Signs the certificate request named ``<name>-req.pem`` using the
+ private key ``<name>-privkey.pem``, producing a self-signed
+ certificate named ``<name>-cert.pem``. The input files should have
+ been produced with ``ovs-pki req``.
+
+ Some controllers accept such self-signed certificates.
+
+Options
+=======
+
+* ``-k <type>`` or ``--key=<type>``
+
+ For the ``init`` command, sets the public key algorithm to use for
+ the new PKI hierarchy. For the ``req`` and ``req+sign`` commands,
+ sets the public key algorithm to use for the key to be generated,
+ which must match the value specified on ``init``. With other
+ commands, the value has no effect.
+
+ The <type> may be ``rsa`` (the default) or ``dsa``.
+
+* ``-B <nbits>`` or ``--bits=<nbits>``
+
+ Sets the number of bits in the key to be generated. When RSA keys are
+ in use, this option affects only the ``init``, ``req``, and
+ ``req+sign`` commands, and the same value should be given each time.
+ With DSA keys are in use, this option affects only the ``init``
+ command.
+
+ The value must be at least 1024. The default is 2048.
+
+* ``-D <file>`` or ``--dsaparam=<file>``
+
+ Specifies an alternate location for the ``dsaparam.pem`` file
+ required by the ``req`` and ``req+sign`` commands. This option
+ affects only these commands, and only when DSA keys are used.
+
+ The default is ``dsaparam.pem`` under the PKI hierarchy.
+
+* ``-b`` or ``--batch``
+
+ Suppresses the interactive verification of fingerprints that the
+ ``sign`` command by default requires.
+
+* ``-d <dir>`` or ``--dir=<dir>``
+
+ Specifies the location of the PKI hierarchy to be used or created by
+ the command. All commands, except ``req``, need access to a PKI
+ hierarchy.
+
+ The default PKI hierarchy is ``/var/lib/openvswitch/pki``, although
+ this default may be changed at Open vSwitch build time
+
+* ``-f`` or ``--force``
+
+ By default, ``ovs-pki`` will not overwrite existing files or
+ directories. This option overrides this behavior.
+
+* ``-l <file>`` or ``--log=<file>``
+
+ Sets the log file to <file>. The default is ``ovs-pki.log`` in the
+ OVS log directory. The default OVS log directory is
+ ``/var/log/openvswitch``, although this default may be changed at
+ Open vSwitch build time.
+
+* ``-u`` or ``--unique``
+
+ Changes the format of the certificate's Common Name (CN) field. By
+ default, this field has the format ``<name> id:<uuid-or-date>``. This
+ option causes the provided name to be treated as unique and changes
+ the format of the CN field to be simply ``<name>``.
+
+* ``-h`` or ``--help``
+
+ Prints a help usage message and exits.
new file mode 100644
@@ -0,0 +1,68 @@
+===========
+ovs-tcpdump
+===========
+
+Synopsis
+========
+
+``ovs-tcpdump -i <port> tcpdump <options>...``
+
+Description
+===========
+
+``ovs-tcpdump`` creates switch mirror ports in the ``ovs-vswitchd``
+daemon and executes ``tcpdump`` to listen against those ports. When
+the ``tcpdump`` instance exits, it then cleans up the mirror port it
+created.
+
+``ovs-tcpdump`` will not allow multiple mirrors for the same port. It
+has some logic to parse the current configuration and prevent
+duplicate mirrors.
+
+The ``-i`` option may not appear multiple times.
+
+It is important to note that under Linux-based kernels, tap devices do
+not receive packets unless the specific tuntap device has been opened by an
+application. This requires ``CAP_NET_ADMIN`` privileges, so the
+``ovs-tcpdump`` command must be run as a user with such permissions (this
+is usually a super-user).
+
+Options
+=======
+
+* ``-h`` or ``--help``
+
+ Prints a brief help message to the console.
+
+* ``-V`` or ``--version``
+
+ Prints version information to the console.
+
+* ``--db-sock <socket>``
+
+ The Open vSwitch database socket connection string. The default is
+ ``unix:<rundir>/db.sock``.
+
+* ``--dump-cmd <command>``
+
+ The command to run instead of ``tcpdump``.
+
+* ``-i`` or ``--interface``
+
+ The interface for which a mirror port should be created, and packets
+ should be dumped.
+
+* ``--mirror-to``
+
+ The name of the interface which should be the destination of the mirrored
+ packets. The default is ``mi<port>``.
+
+* ``--span``
+
+ If specified, mirror all ports (optional).
+
+See Also
+========
+
+``ovs-appctl(8)``, ``ovs-vswitchd(8)``, ``ovs-pcap(1)``,
+``ovs-tcpundump(1)``, ``tcpdump(8)``, ``wireshark(8)``.
new file mode 100644
@@ -0,0 +1,39 @@
+=============
+ovs-tcpundump
+=============
+
+Synopsis
+========
+
+``ovs-tcpundump < <file>``
+
+``ovs-tcpundump -h | --help``
+
+``ovs-tcpundump -V | --version``
+
+The ``ovs-tcpundump`` program reads ``tcpdump -xx output`` from stdin,
+looking for hexadecimal packet data, and dumps each Ethernet as a
+single hexadecimal string on stdout. This format is suitable for use
+with the ``ofproto/trace`` command supported by ``ovs-vswitchd(8)``
+via ``ovs-appctl(8)``.
+
+At least two ``-x`` or ``-X`` options must be given, otherwise the
+output will omit the Ethernet header, which prevents the output from
+being used with ``ofproto/trace``.
+
+Options
+=======
+
+* ``-h`` or ``--help``
+
+ Prints a brief help message to the console.
+
+* ``-V`` or ``--version``
+
+ Prints version information to the console.
+
+See Also
+========
+
+``ovs-appctl(8)``, ``ovs-vswitchd(8)``, ``ovs-pcap(1)``,
+``tcpdump(8)``, ``wireshark(8)``.
@@ -1,23 +1,5 @@
# Generated automatically -- do not modify! -*- buffer-read-only: t -*-
-ovn/utilities/ovn-sbctl.8: \
- ovn/utilities/ovn-sbctl.8.in \
- lib/common.man \
- lib/db-ctl-base.man \
- lib/ovs.tmac \
- lib/ssl-bootstrap.man \
- lib/ssl.man \
- lib/table.man \
- lib/vlog.man
-ovn/utilities/ovn-sbctl.8.in:
-lib/common.man:
-lib/db-ctl-base.man:
-lib/ovs.tmac:
-lib/ssl-bootstrap.man:
-lib/ssl.man:
-lib/table.man:
-lib/vlog.man:
-
ovsdb/ovsdb-client.1: \
ovsdb/ovsdb-client.1.in \
lib/common-syn.man \
@@ -116,14 +98,13 @@ lib/vlog-syn.man:
lib/vlog.man:
ovsdb/ovsdb-schemas.man:
-utilities/ovs-appctl.8: \
- utilities/ovs-appctl.8.in \
- lib/common.man \
+utilities/bugtool/ovs-bugtool.8: \
+ utilities/bugtool/ovs-bugtool.8.in \
lib/ovs.tmac
-utilities/ovs-appctl.8.in:
-lib/common.man:
+utilities/bugtool/ovs-bugtool.8.in:
lib/ovs.tmac:
+
utilities/ovs-dpctl-top.8: \
utilities/ovs-dpctl-top.8.in \
lib/ovs.tmac
@@ -142,16 +123,6 @@ lib/dpctl.man:
lib/ovs.tmac:
lib/vlog.man:
-utilities/ovs-l3ping.8: \
- utilities/ovs-l3ping.8.in \
- lib/common-syn.man \
- lib/common.man \
- lib/ovs.tmac
-utilities/ovs-l3ping.8.in:
-lib/common-syn.man:
-lib/common.man:
-lib/ovs.tmac:
-
utilities/ovs-ofctl.8: \
utilities/ovs-ofctl.8.in \
lib/colors.man \
@@ -184,28 +155,6 @@ lib/common-syn.man:
lib/common.man:
lib/ovs.tmac:
-utilities/ovs-pki.8: \
- utilities/ovs-pki.8.in \
- lib/ovs.tmac
-utilities/ovs-pki.8.in:
-lib/ovs.tmac:
-
-utilities/ovs-tcpdump.8: \
- utilities/ovs-tcpdump.8.in \
- lib/common.man \
- lib/ovs.tmac
-utilities/ovs-tcpdump.8.in:
-lib/common.man:
-lib/ovs.tmac:
-
-utilities/ovs-tcpundump.1: \
- utilities/ovs-tcpundump.1.in \
- lib/common-syn.man \
- lib/common.man \
- lib/ovs.tmac
-utilities/ovs-tcpundump.1.in:
-lib/common-syn.man:
-lib/common.man:
lib/ovs.tmac:
utilities/ovs-testcontroller.8: \
@@ -63,24 +63,16 @@ EXTRA_DIST += \
utilities/docker/debian/Dockerfile \
utilities/docker/debian/build-kernel-modules.sh
MAN_ROOTS += \
- utilities/ovs-appctl.8.in \
utilities/ovs-testcontroller.8.in \
- utilities/ovs-ctl.8 \
utilities/ovs-dpctl.8.in \
utilities/ovs-dpctl-top.8.in \
utilities/ovs-kmod-ctl.8 \
- utilities/ovs-l3ping.8.in \
utilities/ovs-ofctl.8.in \
- utilities/ovs-parse-backtrace.8 \
utilities/ovs-pcap.1.in \
- utilities/ovs-pki.8.in \
- utilities/ovs-tcpdump.8.in \
- utilities/ovs-tcpundump.1.in \
utilities/ovs-vlan-bug-workaround.8.in \
utilities/ovs-vsctl.8.in
MAN_FRAGMENTS += utilities/ovs-vlan-bugs.man
CLEANFILES += \
- utilities/ovs-appctl.8 \
utilities/ovs-ctl \
utilities/ovs-check-dead-ifs \
utilities/ovs-testcontroller.8 \
@@ -89,38 +81,27 @@ CLEANFILES += \
utilities/ovs-dpctl-top.8 \
utilities/ovs-kmod-ctl \
utilities/ovs-l3ping \
- utilities/ovs-l3ping.8 \
utilities/ovs-lib \
utilities/ovs-ofctl.8 \
utilities/ovs-parse-backtrace \
utilities/ovs-pcap \
utilities/ovs-pcap.1 \
utilities/ovs-pki \
- utilities/ovs-pki.8 \
utilities/ovs-sim \
utilities/ovs-tcpdump \
- utilities/ovs-tcpdump.8 \
utilities/ovs-tcpundump \
- utilities/ovs-tcpundump.1 \
utilities/ovs-test \
utilities/ovs-vlan-test \
utilities/ovs-vlan-bug-workaround.8 \
utilities/ovs-vsctl.8
man_MANS += \
- utilities/ovs-appctl.8 \
- utilities/ovs-ctl.8 \
utilities/ovs-testcontroller.8 \
utilities/ovs-dpctl.8 \
utilities/ovs-dpctl-top.8 \
utilities/ovs-kmod-ctl.8 \
- utilities/ovs-l3ping.8 \
utilities/ovs-ofctl.8 \
- utilities/ovs-parse-backtrace.8 \
utilities/ovs-pcap.1 \
- utilities/ovs-pki.8 \
- utilities/ovs-tcpdump.8 \
- utilities/ovs-tcpundump.1 \
utilities/ovs-vlan-bug-workaround.8 \
utilities/ovs-vsctl.8
deleted file mode 100644
@@ -1,293 +0,0 @@
-.\" -*- nroff -*-
-.so lib/ovs.tmac
-.TH ovs\-appctl 8 "@VERSION@" "Open vSwitch" "Open vSwitch Manual"
-.ds PN ovs\-appctl
-.
-.SH NAME
-ovs\-appctl \- utility for configuring running Open vSwitch daemons
-.
-.SH SYNOPSIS
-\fBovs\-appctl\fR [\fB\-\-target=\fItarget\fR | \fB\-t\fR \fItarget\fR]
-[\fB\-T \fIsecs\fR | \fB\-\-timeout=\fIsecs\fR]
-\fIcommand \fR[\fIarg\fR...]
-.br
-\fBovs\-appctl \fB\-\-help\fR
-.br
-\fBovs\-appctl \fB\-\-version\fR
-.SH DESCRIPTION
-Open vSwitch daemons accept certain commands at runtime to control their
-behavior and query their settings. Every daemon accepts a common set of
-commands documented under \fBCOMMON COMMANDS\fR below. Some daemons
-support additional commands documented in their own manpages.
-\fBovs\-vswitchd\fR in particular accepts a number of additional
-commands documented in \fBovs\-vswitchd\fR(8).
-.PP
-The \fBovs\-appctl\fR program provides a simple way to invoke these
-commands. The command to be sent is specified on \fBovs\-appctl\fR's
-command line as non-option arguments. \fBovs\-appctl\fR sends the
-command and prints the daemon's response on standard output.
-.PP
-In normal use only a single option is accepted:
-.IP "\fB\-t \fItarget\fR"
-.IQ "\fB\-\-target=\fItarget\fR"
-Tells \fBovs\-appctl\fR which daemon to contact.
-.IP
-If \fItarget\fR begins with \fB/\fR it must name a Unix domain socket
-on which an Open vSwitch daemon is listening for control channel
-connections. By default, each daemon listens on a Unix domain socket
-named \fB@RUNDIR@/\fIprogram\fB.\fIpid\fB.ctl\fR, where \fIprogram\fR
-is the program's name and \fIpid\fR is its process ID. For example,
-if \fBovs\-vswitchd\fR has PID 123, it would listen on
-\fB@RUNDIR@/ovs\-vswitchd.123.ctl\fR.
-.IP
-Otherwise, \fBovs\-appctl\fR looks for a pidfile, that is, a file
-whose contents are the process ID of a running process as a decimal
-number, named \fB@RUNDIR@/\fItarget\fB.pid\fR. (The \fB\-\-pidfile\fR
-option makes an Open vSwitch daemon create a pidfile.)
-\fBovs\-appctl\fR reads the pidfile, then looks for a Unix socket
-named \fB@RUNDIR@/\fItarget\fB.\fIpid\fB.ctl\fR, where \fIpid\fR is
-replaced by the process ID read from the pidfile, and uses that file
-as if it had been specified directly as the target.
-.IP
-On Windows, \fItarget\fR can be an absolute path to a file that contains
-a localhost TCP port on which an Open vSwitch daemon is listening
-for control channel connections. By default, each daemon writes the
-TCP port on which it is listening for control connection into the file
-\fIprogram\fB.ctl\fR located inside the configured \fIOVS_RUNDIR\fR
-directory. If \fItarget\fR is not an absolute path, \fBovs\-appctl\fR
-looks for a file named \fItarget\fB.ctl\fR in the configured \fIOVS_RUNDIR\fR
-directory.
-.IP
-The default target is \fBovs\-vswitchd\fR.
-.
-.IP "\fB\-T \fIsecs\fR"
-.IQ "\fB\-\-timeout=\fIsecs\fR"
-By default, or with a \fIsecs\fR of \fB0\fR, \fBovs\-appctl\fR waits
-forever to connect to the daemon and receive a response. This option
-limits runtime to approximately \fIsecs\fR seconds. If the timeout
-expires, \fBovs\-appctl\fR exits with a \fBSIGALRM\fR signal.
-.
-.SH COMMON COMMANDS
-Every Open vSwitch daemon supports a common set of commands, which are
-documented in this section.
-.
-.SS GENERAL COMMANDS
-These commands display daemon-specific commands and the running version.
-Note that these commands are different from the \fB\-\-help\fR and
-\fB\-\-version\fR options that return information about the
-\fBovs\-appctl\fR utility itself.
-.
-.IP "\fBlist-commands\fR"
-Lists the commands supported by the target.
-.
-.IP "\fBversion\fR"
-Displays the version and compilation date of the target.
-.
-.SS LOGGING COMMANDS
-Open vSwitch has several log levels. The highest-severity log level is:
-.
-.IP "\fBoff\fR"
-No message is ever logged at this level, so setting a logging
-destination's log level to \fBoff\fR disables logging to that destination.
-.
-.PP
-The following log levels, in order of descending severity, are
-available:
-.
-.IP "\fBemer\fR"
-A major failure forced a process to abort.
-.IP "\fBerr\fR"
-A high-level operation or a subsystem failed. Attention is
-warranted.
-.IP "\fBwarn\fR"
-A low-level operation failed, but higher-level subsystems may be able
-to recover.
-.IP "\fBinfo\fR"
-Information that may be useful in retrospect when investigating
-a problem.
-.IP "\fBdbg\fR"
-Information useful only to someone with intricate knowledge of the
-system, or that would commonly cause too-voluminous log output. Log
-messages at this level are not logged by default.
-.
-.PP
-Every Open vSwitch daemon supports the following commands for examining
-and adjusting log levels.
-.IP "\fBvlog/list\fR"
-Lists the known logging modules and their current levels.
-.
-.IP "\fBvlog/list-pattern\fR"
-Lists logging pattern used for each destination.
-.
-.IP "\fBvlog/set\fR [\fIspec\fR]"
-Sets logging levels. Without any \fIspec\fR, sets the log level for
-every module and destination to \fBdbg\fR. Otherwise, \fIspec\fR is a
-list of words separated by spaces or commas or colons, up to one from
-each category below:
-.
-.RS
-.IP \(bu
-A valid module name, as displayed by the \fBvlog/list\fR command on
-\fBovs\-appctl\fR(8), limits the log level change to the specified
-module.
-.
-.IP \(bu
-\fBsyslog\fR, \fBconsole\fR, or \fBfile\fR, to limit the log level
-change to only to the system log, to the console, or to a file,
-respectively.
-.IP
-On Windows platform, \fBsyslog\fR is accepted as a word and
-is only useful if the \fItarget\fR was started with the
-\fB\-\-syslog\-target\fR option (the word has no effect otherwise).
-.
-.IP \(bu
-\fBoff\fR, \fBemer\fR, \fBerr\fR, \fBwarn\fR, \fBinfo\fR, or
-\fBdbg\fR, to control the log level. Messages of the given severity
-or higher will be logged, and messages of lower severity will be
-filtered out. \fBoff\fR filters out all messages.
-.RE
-.
-.IP
-Case is not significant within \fIspec\fR.
-.IP
-Regardless of the log levels set for \fBfile\fR, logging to a file
-will not take place unless the target application was invoked with the
-\fB\-\-log\-file\fR option.
-.IP
-For compatibility with older versions of OVS, \fBany\fR is accepted as
-a word but has no effect.
-.
-.IP "\fBvlog/set PATTERN:\fIdestination\fB:\fIpattern\fR"
-Sets the log pattern for \fIdestination\fR to \fIpattern\fR. Each time a
-message is logged to \fIdestination\fR, \fIpattern\fR determines the
-message's formatting. Most characters in \fIpattern\fR are copied
-literally to the log, but special escapes beginning with \fB%\fR are
-expanded as follows:
-.
-.RS
-.IP \fB%A\fR
-The name of the application logging the message, e.g. \fBovs\-vswitchd\fR.
-.
-.IP \fB%B\fR
-The RFC5424 syslog PRI of the message.
-.
-.IP \fB%c\fR
-The name of the module (as shown by \fBovs\-appctl \-\-list\fR) logging
-the message.
-.
-.IP \fB%d\fR
-The current date and time in ISO 8601 format (YYYY\-MM\-DD HH:MM:SS).
-.
-.IP \fB%d{\fIformat\fB}\fR
-The current date and time in the specified \fIformat\fR, which takes
-the same format as the \fItemplate\fR argument to \fBstrftime\fR(3).
-As an extension, any \fB#\fR characters in \fIformat\fR will be
-replaced by fractional seconds, e.g. use \fB%H:%M:%S.###\fR for the
-time to the nearest millisecond. Sub-second times are only
-approximate and currently decimal places after the third will always
-be reported as zero.
-.
-.IP \fB%D\fR
-The current UTC date and time in ISO 8601 format (YYYY\-MM\-DD HH:MM:SS).
-.
-.IP \fB%D{\fIformat\fB}\fR
-The current UTC date and time in the specified \fIformat\fR, which
-takes the same format as the \fItemplate\fR argument to
-\fBstrftime\fR(3). Supports the same extension for sub-second
-resolution as \fB%d{\fR...\fB}\fR.
-.
-.IP \fB%E\fR
-The hostname of the node running the application.
-.
-.IP \fB%m\fR
-The message being logged.
-.
-.IP \fB%N\fR
-A serial number for this message within this run of the program, as a
-decimal number. The first message a program logs has serial number 1,
-the second one has serial number 2, and so on.
-.
-.IP \fB%n\fR
-A new-line.
-.
-.IP \fB%p\fR
-The level at which the message is logged, e.g. \fBDBG\fR.
-.
-.IP \fB%P\fR
-The program's process ID (pid), as a decimal number.
-.
-.IP \fB%r\fR
-The number of milliseconds elapsed from the start of the application
-to the time the message was logged.
-.
-.IP \fB%t\fR
-The subprogram name, that is, an identifying name for the process or
-thread that emitted the log message, such as \fBmonitor\fR for the
-process used for \fB\-\-monitor\fR or \fBmain\fR for the primary
-process or thread in a program.
-.
-.IP \fB%T\fR
-The subprogram name enclosed in parentheses, e.g. \fB(monitor)\fR, or
-the empty string for the primary process or thread in a program.
-.
-.IP \fB%%\fR
-A literal \fB%\fR.
-.RE
-.
-.IP
-A few options may appear between the \fB%\fR and the format specifier
-character, in this order:
-.
-.RS
-.IP \fB\-\fR
-Left justify the escape's expansion within its field width. Right
-justification is the default.
-.
-.IP \fB0\fR
-Pad the field to the field width with \fB0\fRs. Padding with spaces
-is the default.
-.
-.IP \fIwidth\fR
-A number specifies the minimum field width. If the escape expands to
-fewer characters than \fIwidth\fR then it is padded to fill the field
-width. (A field wider than \fIwidth\fR is not truncated to fit.)
-.RE
-.
-.IP
-The default pattern for console and file output is \fB%D{%Y-%m-%dT
-%H:%M:%SZ}|%05N|%c|%p|%m\fR; for syslog output, \fB%05N|%c|%p|%m\fR.
-.
-.IP
-Daemons written in Python (e.g. \fBovs\-xapi\-sync\fR) do not allow
-control over the log pattern.
-.
-.IP "\fBvlog/set\fR FACILITY:\fIfacility\fR"
-Sets the RFC5424 facility of the log message. \fIfacility\fR can be one of
-\fBkern\fR, \fBuser\fR, \fBmail\fR, \fBdaemon\fR, \fBauth\fR, \fBsyslog\fR,
-\fBlpr\fR, \fBnews\fR, \fBuucp\fR, \fBclock\fR, \fBftp\fR, \fBntp\fR,
-\fBaudit\fR, \fBalert\fR, \fBclock2\fR, \fBlocal0\fR, \fBlocal1\fR,
-\fBlocal2\fR, \fBlocal3\fR, \fBlocal4\fR, \fBlocal5\fR, \fBlocal6\fR or
-\fBlocal7\fR.
-.
-.IP "\fBvlog/close\fR"
-Causes the daemon to close its log file, if it is open. (Use
-\fBvlog/reopen\fR to reopen it later.)
-.
-.IP "\fBvlog/reopen\fR"
-Causes the daemon to close its log file, if it is open, and then
-reopen it. (This is useful after rotating log files, to cause a new
-log file to be used.)
-.IP
-This has no effect if the target application was not invoked with the
-\fB\-\-log\-file\fR option.
-.
-.SH OPTIONS
-.
-.so lib/common.man
-.
-.SH "SEE ALSO"
-.
-\fBovs\-appctl\fR can control all Open vSwitch daemons, including:
-.BR ovs\-vswitchd (8),
-and
-.BR ovsdb\-server (8).
deleted file mode 100644
@@ -1,518 +0,0 @@
-.\" -*- nroff -*-
-.de IQ
-. br
-. ns
-. IP "\\$1"
-..
-.de ST
-. PP
-. RS -0.15in
-. I "\\$1"
-. RE
-..
-.TH ovs\-ctl 8 "June 2011" "Open vSwitch" "Open vSwitch Manual"
-.ds PN ovs\-ctl
-.
-.SH NAME
-ovs\-ctl \- OVS startup helper script
-.
-.SH SYNOPSIS
-\fBovs\-ctl\fR \fB\-\-system\-id=random\fR|\fIuuid\fR
-[\fIoptions\fR] \fBstart
-.br
-\fBovs\-ctl stop
-.br
-\fBovs\-ctl\fR \fB\-\-system\-id=random\fR|\fIuuid\fR
-[\fIoptions\fR] \fBrestart
-.br
-\fBovs\-ctl status
-.br
-\fBovs\-ctl version
-.br
-\fBovs\-ctl
-[\fIoptions\fR]
-\fBload\-kmod\fR
-.br
-\fBovs\-ctl
-\fB\-\-system\-id=random\fR|\fIuuid\fR
-[\fIoptions\fR]
-\fBforce\-reload\-kmod\fR
-.br
-\fBovs\-ctl
-\fR[\fB\-\-protocol=\fIprotocol\fR]
-[\fB\-\-sport=\fIsport\fR]
-[\fB\-\-dport=\fIdport\fR]
-\fBenable\-protocol\fR
-.br
-\fBovs\-ctl delete\-transient\-ports
-.br
-\fBovs\-ctl help \fR| \fB\-h \fR| \fB\-\-help
-.br
-\fBovs\-ctl \-\-version
-.
-.SH DESCRIPTION
-.
-.PP
-The \fBovs\-ctl\fR program starts, stops, and checks the status of
-Open vSwitch daemons. It is not meant to be invoked directly by
-system administrators but to be called internally by system startup
-scripts.
-.
-.PP
-Each of \fBovs\-ctl\fR's commands is described separately below.
-.
-.SH "The ``start'' command"
-.
-.PP
-The \fBstart\fR command starts Open vSwitch. It performs the
-following tasks:
-.
-.IP 1.
-Loads the Open vSwitch kernel module. If this fails, and the Linux
-bridge module is loaded but no bridges exist, it tries to unload the
-bridge module and tries loading the Open vSwitch kernel module again.
-(This is because the Open vSwitch kernel module cannot coexist with
-the Linux bridge module before 2.6.37.)
-.
-.PP
-The \fBstart\fR command skips the following steps if
-\fBovsdb\-server\fR is already running:
-.IP 2.
-If the Open vSwitch database file does not exist, it creates it.
-If the database does exist, but it has an obsolete version, it
-upgrades it to the latest schema.
-.
-.IP 3.
-Starts \fBovsdb-server\fR, unless the \fB\-\-no\-ovsdb\-server\fR command
-option is given.
-.
-.IP 4.
-Initializes a few values inside the database.
-.
-.IP 5.
-If the \fB\-\-delete\-bridges\fR option was used, deletes all of the
-bridges from the database.
-.
-.IP 6.
-If the \fB\-\-delete\-transient\-ports\fR option was used, deletes all ports
-that have \fBother_config:transient\fR set to true.
-.
-.PP
-The \fBstart\fR command skips the following step if
-\fBovs\-vswitchd\fR is already running, or if the \fB\-\-no\-ovs\-vswitchd\fR
-command option is given:
-.IP 7.
-Starts \fBovs\-vswitchd\fR.
-.
-.SS "Options"
-.PP
-Several command-line options influence the \fBstart\fR command's
-behavior. Some form of the following option should ordinarily be
-specified:
-.
-.IP "\fB\-\-system\-id=\fIuuid\fR"
-.IQ "\fB\-\-system\-id=random\fR"
-This specifies a unique system identifier to store into
-\fBexternal-ids:system-id\fR in the database's \fBOpen_vSwitch\fR
-table. Remote managers that talk to the Open vSwitch database server
-over network protocols use this value to identify and distinguish Open
-vSwitch instances, so it should be unique (at least) within OVS
-instances that will connect to a single controller.
-.IP
-When \fBrandom\fR is specified, \fBovs\-ctl\fR will generate a random
-ID that persists from one run to another (stored in a file). When
-another string is specified \fBovs\-ctl\fR uses it literally.
-.
-.PP
-The following options should be specified if the defaults are not
-suitable:
-.
-.IP "\fB\-\-system\-type=\fItype\fR"
-.IQ "\fB\-\-system\-version=\fIversion\fR"
-Sets the value to store in the \fBsystem-type\fR and
-\fBsystem-version\fR columns, respectively, in the database's
-\fBOpen_vSwitch\fR table. Remote managers may use these values to
-determine the kind of system to which they are connected (primarily
-for display to human administrators).
-.IP
-When not specified, \fBovs\-ctl\fR uses values from the optional
-\fBsystem\-type.conf\fR and \fBsystem\-version.conf\fR files(see section
-\fBFILES\fR) or it uses the \fBlsb_release\fR program, if present, to
-provide reasonable defaults.
-.
-.PP
-The following options are also likely to be useful:
-.
-.IP "\fB\-\-external\-id=\(dq\fIname\fB=\fIvalue\fB\(dq"
-Sets \fBexternal-ids:\fIname\fR to \fIvalue\fR in the database's
-\fBOpen_vSwitch\fR table. Specifying this option multiple times adds
-multiple key-value pairs.
-.
-.IP "\fB\-\-delete\-bridges\fR"
-Ordinarily Open vSwitch bridges persist from one system boot to the
-next, as long as the database is preserved. Some environments instead
-expect to re-create all of the bridges and other configuration state
-on every boot. This option supports that, by deleting all Open
-vSwitch bridges after starting \fBovsdb\-server\fR but before starting
-\fBovs\-vswitchd\fR.
-.
-.IP "\fB\-\-delete\-transient\-ports\fR"
-Deletes all ports that have the other_config:transient value set to true. This
-is important on certain environments where some ports are going to be recreated
-after reboot, but other ports need to be persisted in the database.
-.
-.IP "\fB\-\-ovs\-user=user[:group]\fR"
-Ordinarily Open vSwitch daemons are started as the user invoking the ovs-ctl
-command. Some system administrators would prefer to have the various daemons
-spawn as different users in their environments. This option allows passing the
-\fB\-\-user\fR option to the \fBovsdb\-server\fR and \fBovs\-vswitchd\fR
-daemons, allowing them to change their privilege levels.
-.
-.PP
-The following options are less important:
-.
-.IP "\fB\-\-no\-monitor\fR"
-By default \fBovs\-ctl\fR passes \fB\-\-monitor\fR to \fBovs\-vswitchd\fR and
-\fBovsdb\-server\fR, requesting that it spawn a process monitor which will
-restart the daemon if it crashes. This option suppresses that behavior.
-.
-.IP "\fB\-\-daemon-cwd=\fIdirectory\fR"
-Specifies the current working directory that the OVS daemons should
-run from. The default is \fB/\fR (the root directory) if this option
-is not specified. (This option is useful because most systems create
-core files in a process's current working directory and because a file
-system that is in use as a process's current working directory cannot
-be unmounted.)
-.
-.IP "\fB\-\-no\-force\-corefiles\fR"
-By default, \fBovs\-ctl\fR enables core dumps for the OVS daemons.
-This option disables that behavior.
-.
-.IP "\fB\-\-no\-mlockall\fR"
-By default \fBovs\-ctl\fR passes \fB\-\-mlockall\fR to
-\fBovs\-vswitchd\fR, requesting that it lock all of its virtual
-memory, preventing it from being paged to disk. This option
-suppresses that behavior.
-.
-.IP "\fB\-\-no\-self\-confinement\fR"
-Disable self-confinement for \fBovs-vswitchd\fR and \fBovsdb\-server\fR
-daemons. This flag may be used when, for example, OpenFlow controller
-creates its Unix Domain Socket outside OVS run directory and OVS needs
-to connect to it. It is better to stick with the default behavior and
-not to use this flag, unless:
-.
-.RS
-.IP \(bu
-You have Open vSwitch running under SELinux or AppArmor Mandatory
-Access Control that would prevent OVS from messing with sockets
-outside ordinary OVS directories.
-.
-.IP \(bu
-You believe that relying on protocol handshakes (e.g. OpenFlow)
-is enough to prevent OVS to adversely interact with other daemons
-running on your system.
-.
-.IP \(bu
-You don't have much worries of remote OVSDB exploits in the first
-place, because, perhaps, OVSDB manager is running on the same host
-as OVS and share similar attack vectors.
-.RE
-.
-.IP "\fB\-\-ovsdb\-server\-priority=\fIniceness\fR"
-.IQ "\fB\-\-ovs\-vswitchd\-priority=\fIniceness\fR"
-Sets the \fBnice\fR(1) level used for each daemon. All of them
-default to \fB\-10\fR.
-.
-.IP "\fB\-\-ovsdb\-server\-wrapper=\fIwrapper\fR"
-.IQ "\fB\-\-ovs\-vswitchd\-wrapper=\fIwrapper\fR"
-.
-Configures the specified daemon to run under \fIwrapper\fR, which is
-one of the following:
-.
-.RS
-.IP "\fBvalgrind\fR"
-Run the daemon under \fBvalgrind\fR(1), if it is installed, logging to
-\fIdaemon\fB.valgrind.log.\fIpid\fR in the log directory.
-.
-.IP "\fBstrace\fR"
-Run the daemon under \fBstrace\fR(1), if it is installed, logging to
-\fIdaemon\fB.strace.log.\fIpid\fR in the log directory.
-.
-.IP "\fBglibc\fR"
-Enable GNU C library features designed to find memory errors.
-.RE
-.
-.IP
-By default, no wrapper is used.
-.
-.IP
-Each of the wrappers can expose bugs in Open vSwitch that lead to
-incorrect operation, including crashes. The \fBvalgrind\fR and
-\fBstrace\fR wrappers greatly slow daemon operations so they should
-not be used in production. They also produce voluminous logs that can
-quickly fill small disk partitions. The \fBglibc\fR wrapper is less
-resource-intensive but still somewhat slows the daemons.
-.
-.PP
-The following options control file locations. They should only be
-used if the default locations cannot be used. See \fBFILES\fR, below,
-for more information.
-.
-.IP "\fB\-\-db\-file=\fIfile\fR"
-Overrides the file name for the OVS database.
-.
-.IP "\fB\-\-db\-sock=\fIsocket\fR"
-Overrides the file name for the Unix domain socket used to connect to
-\fBovsdb\-server\fR.
-.
-.IP "\fB\-\-db\-schema=\fIschema\fR"
-Overrides the file name for the OVS database schema.
-.
-.IP "\fB\-\-extra-dbs=\fIfile\fR"
-Adds \fIfile\fR as an extra database for \fBovsdb\-server\fR to serve
-out. Multiple space-separated file names may also be specified.
-\fIfile\fR should begin with \fB/\fR; if it does not, then it will be
-taken as relative to \fIdbdir\fR.
-.
-.SH "The ``stop'' command"
-.
-.PP
-The \fBstop\fR command does not unload the Open vSwitch kernel
-modules. It can take the same \fB\-\-no\-ovsdb\-server\fR and
-\fB\-\-no\-ovs\-vswitchd\fR options as that of the \fBstart\fR
-command.
-.
-.PP
-This command does nothing and finishes successfully if the OVS daemons
-aren't running.
-.
-.SH "The ``restart'' command"
-.
-.PP
-The \fBrestart\fR command performs a \fBstop\fR followed by a \fBstart\fR
-command. The command can take the same options as that of the \fBstart\fR
-command. In addition, it saves and restores OpenFlow flows for each
-individual bridge.
-.
-.SH "The ``status'' command"
-.
-.PP
-The \fBstatus\fR command checks whether the OVS daemons
-\fBovs-vswitchd\fR and \fBovsdb\-server\fR are running and prints
-messages with that information. It exits with status 0 if
-the daemons are running, 1 otherwise.
-.
-.SH "The ``version'' command"
-.
-.PP
-The \fBversion\fR command runs \fBovsdb\-server \-\-version\fR and
-\fBovs\-vswitchd \-\-version\fR.
-.
-.SH "The ``force\-reload\-kmod'' command"
-.
-.PP
-The \fBforce\-reload\-kmod\fR command allows upgrading the Open
-vSwitch kernel module without rebooting. It performs the following
-tasks:
-.
-.IP 1.
-Gets a list of OVS ``internal'' interfaces, that is, network devices
-implemented by Open vSwitch. The most common examples of these are
-bridge ``local ports''.
-.
-.IP 2.
-Saves the OpenFlow flows of each bridge.
-.
-.IP 3.
-Stops the Open vSwitch daemons, as if by a call to \fBovs\-ctl
-stop\fR.
-.
-.IP 4.
-Saves the kernel configuration state of the OVS internal interfaces
-listed in step 1, including IP and IPv6 addresses and routing table
-entries.
-.
-.IP 5.
-Unloads the Open vSwitch kernel module (including the bridge
-compatibility module if it is loaded).
-.
-.IP 6.
-Starts OVS back up, as if by a call to \fBovs\-ctl start\fR. This
-reloads the kernel module, restarts the OVS daemons and finally
-restores the saved OpenFlow flows.
-.
-.IP 7.
-Restores the kernel configuration state that was saved in step 4.
-.
-.IP 8.
-Checks for daemons that may need to be restarted because they have
-packet sockets that are listening on old instances of Open vSwitch
-kernel interfaces and, if it finds any, prints a warning on stdout.
-DHCP is a common example: if the ISC DHCP client is running on an OVS
-internal interface, then it will have to be restarted after completing
-the above procedure. (It would be nice if \fBovs\-ctl\fR could restart
-daemons automatically, but the details are far too specific to a
-particular distribution and installation.)
-.
-.PP
-\fBforce\-kmod\-reload\fR internally stops and starts OVS, so it
-accepts all of the options accepted by the \fBstart\fR command except
-for the \fB\-\-no\-ovs\-vswitchd\fR option.
-.
-.SH "The ``load\-kmod'' command"
-.
-.PP
-The \fBload\-kmod\fR command loads the openvswitch kernel modules if
-they are not already loaded. This operation also occurs as part of
-the \fBstart\fR command. The motivation for providing the \fBload\-kmod\fR
-command is to allow errors when loading modules to be handled separatetly
-from other errors that may occur when running the \fBstart\fR command.
-.
-.PP
-By default the \fBload\-kmod\fR command attempts to load the
-openvswitch kernel module.
-.
-.SH "The ``enable\-protocol'' command"
-.
-.PP
-The \fBenable\-protocol\fR command checks for rules related to a
-specified protocol in the system's \fBiptables\fR(8) configuration. If there
-are no rules specifically related to that protocol, then it inserts a
-rule to accept the specified protocol.
-.
-.PP
-More specifically:
-.
-.IP \(bu
-If \fBiptables\fR is not installed or not enabled, this command does
-nothing, assuming that lack of filtering means that the protocol is
-enabled.
-.
-.IP \(bu
-If the \fBINPUT\fR chain has a rule that matches the specified
-protocol, then this command does nothing, assuming that whatever rule
-is installed reflects the system administrator's decisions.
-.
-.IP \(bu
-Otherwise, this command installs a rule that accepts traffic of the
-specified protocol.
-.
-.PP
-This command normally completes successfully, even if it does
-nothing. Only the failure of an attempt to insert a rule normally
-causes it to return an exit code other than 0.
-.
-The following options control the protocol to be enabled:
-.
-.IP "\fB\-\-protocol=\fIprotocol\fR"
-The name of the IP protocol to be enabled, such as \fBgre\fR or
-\fBtcp\fR. The default is \fBgre\fR.
-.
-.IP "\fB\-\-sport=\fIsport\fR"
-.IQ "\fB\-\-dport=\fIdport\fR"
-TCP or UDP source or destination port to match. These are optional
-and allowed only with \fB\-\-protocol=tcp\fR or
-\fB\-\-protocol=udp\fR.
-.
-.SH "The ``delete\-transient\-ports'' command"
-.
-Deletes all ports that have the \fBother_config:transient\fR value set to true.
-.
-.SH "The ``help'' command"
-.
-Prints a usage message and exits successfully.
-.
-.SH "OPTIONS"
-.PP
-In addition to the options listed for each command above, these options
-control the behavior of several of \fBovs\-ctl\fR's commands.
-.
-.PP
-By default, \fBovs\-ctl\fR will control the \fBovsdb\-server\fR, and
-the \fBovs\-vswitchd\fR daemons. The following options restrict that control
-to exclude one or the other:
-.
-.IP "\fB\-\-no\-ovsdb-server\fR"
-Specifies that the \fBovs\-ctl\fR commands \fBstart\fR, \fBstop\fR, and
-\fBrestart\fR should not modify the running status of \fBovsdb\-server\fR.
-.
-.IP "\fB\-\-no\-ovs\-vswitchd\fR"
-Specifies that the \fBovs\-ctl\fR commands \fBstart\fR, \fBstop\fR, and
-\fBrestart\fR should not modify the running status of \fBovs\-vswitchd\fR.
-It is an error to include this option with the \fBforce\-reload\-kmod\fR
-command.
-.
-.SH "EXIT STATUS"
-.
-\fBovs\-ctl\fR exits with status 0 on success and nonzero on failure.
-The \fBstart\fR command is considered to succeed if OVS is already
-started; the \fBstop\fR command is considered to succeed if OVS is
-already stopped.
-.
-.SH "ENVIRONMENT"
-.
-The following environment variables affect \fBovs\-ctl\fR:
-.
-.IP "\fBPATH\fR"
-\fBovs\-ctl\fR does not hardcode the location of any of the programs
-that it runs. \fBovs\-ctl\fR will add the \fIsbindir\fR and
-\fIbindir\fR that were specified at \fBconfigure\fR time to
-\fBPATH\fR, if they are not already present.
-.
-.IP "\fBOVS_LOGDIR\fR"
-.IQ "\fBOVS_RUNDIR\fR"
-.IQ "\fBOVS_DBDIR\fR"
-.IQ "\fBOVS_SYSCONFDIR\fR"
-.IQ "\fBOVS_PKGDATADIR\fR"
-.IQ "\fBOVS_BINDIR\fR"
-.IQ "\fBOVS_SBINDIR\fR"
-Setting one of these variables in the environment overrides the
-respective \fBconfigure\fR option, both for \fBovs\-ctl\fR itself and
-for the other Open vSwitch programs that it runs.
-.
-.SH "FILES"
-.
-\fBovs\-ctl\fR uses the following files:
-.
-.IP "\fBovs\-lib"
-Shell function library used internally by \fBovs\-ctl\fR. It must be
-installed in the same directory as \fBovs\-ctl\fR.
-.
-.IP "\fIlogdir\fB/\fIdaemon\fB.log\fR"
-Per-daemon logfiles.
-.
-.IP "\fIrundir\fB/\fIdaemon\fB.pid\fR"
-Per-daemon pidfiles to track whether a daemon is running and with what
-process ID.
-.
-.IP "\fIpkgdatadir\fB/vswitch.ovsschema\fR"
-The OVS database schema used to initialize the database (use
-\fB\-\-db\-schema to override this location).
-.
-.IP "\fIdbdir\fB/conf.db\fR"
-The OVS database (use \fB\-\-db\-file\fR to override this location).
-.
-.IP "\fIrundir\fB/openvswitch/db.sock\fR"
-The Unix domain socket used for local communication with
-\fBovsdb\-server\fR (use \fB\-\-db\-sock\fR to override this
-location).
-.
-.IP "\fIsysconfdir\fB/openvswitch/system-id.conf\fR"
-The persistent system UUID created and read by
-\fB\-\-system\-id=random\fR.
-.
-.IP "\fIsysconfdir\fB/openvswitch/system\-type.conf\fR"
-.IQ "\fIsysconfdir\fB/openvswitch/system\-version.conf\fR"
-The \fBsystem\-type\fR and \fBsystem\-version\fR values stored in the database's
-\fBOpen_vSwitch\fR table when not specified as a command-line option.
-.
-.SH "EXAMPLE"
-.
-.PP
-The files \fBdebian/openvswitch\-switch.init\fR and
-\fBxenserver/etc_init.d_openvswitch\fR in the Open vSwitch source
-distribution are good examples of how to use \fBovs\-ctl\fR.
-.
-.SH "SEE ALSO"
-.
-\fBREADME.rst\fR, \fBovsdb\-server\fR(8), \fBovs\-vswitchd\fR(8).
deleted file mode 100644
@@ -1,110 +0,0 @@
-.so lib/ovs.tmac
-.TH ovs\-l3ping 1 "@VERSION@" "Open vSwitch" "Open vSwitch Manual"
-.
-.SH NAME
-\fBovs\-l3ping\fR \- check network deployment for L3 tunneling
-problems
-.
-.SH SYNOPSIS
-\fBovs\-l3ping\fR \fB\-s\fR \fITunnelRemoteIP,InnerIP[/mask]\fR \fB\-t\fR \fItunnelmode\fR
-.br
-\fBovs\-l3ping\fR \fB\-s\fR \fITunnelRemoteIP,InnerIP[/mask][:ControlPort]\fR \fB\-t\fR \fItunnelmode\fR
-.PP
-\fBovs\-l3ping\fR \fB\-c\fR \fITunnelRemoteIP,InnerIP[/mask],RemoteInnerIP\fR \fB\-t\fR \fItunnelmode\fR
-.br
-\fBovs\-l3ping\fR \fB\-c\fR \fITunnelRemoteIP,InnerIP[/mask][:ControlPort\
-[:DataPort]],RemoteInnerIP[:ControlPort[:DataPort]]\fR
-[\fB\-b\fR \fItargetbandwidth\fR] [\fB\-i\fR \fItestinterval\fR]
-\fB\-t\fR \fItunnelmode\fR
-.so lib/common-syn.man
-.
-.SH DESCRIPTION
-The \fBovs\-l3ping\fR program may be used to check for problems that could
-be caused by invalid routing policy, misconfigured firewall in the tunnel
-path or a bad NIC driver. On one of the nodes, run \fBovs\-l3ping\fR in
-server mode and on the other node run it in client mode. The client and
-server will establish L3 tunnel, over which client will give further testing
-instructions. The \fBovs\-l3ping\fR client will perform UDP and TCP tests.
-This tool is different from \fBovs\-test\fR that it encapsulates XML/RPC
-control connection over the tunnel, so there is no need to open special holes
-in firewall.
-.PP
-UDP tests can report packet loss and achieved bandwidth for various
-datagram sizes. By default target bandwidth for UDP tests is 1Mbit/s.
-.PP
-TCP tests report only achieved bandwidth, because kernel TCP stack
-takes care of flow control and packet loss.
-.
-.SS "Client Mode"
-An \fBovs\-l3ping\fR client will create a L3 tunnel and connect over it to the
-\fBovs\-l3ping\fR server to schedule the tests. \fITunnelRemoteIP\fR is the
-peer's IP address, where tunnel will be terminated. \fIInnerIP\fR is the
-address that will be temporarily assigned during testing. All test traffic
-originating from this IP address to the \fIRemoteInnerIP\fR will be tunneled.
-It is possible to override default \fIControlPort\fR and \fIDataPort\fR, if
-there is any other application that already listens on those two ports.
-.
-.SS "Server Mode"
-To conduct tests, \fBovs\-l3ping\fR server must be running. It is required
-that both client and server \fIInnerIP\fR addresses are in the same subnet.
-It is possible to specify \fIInnerIP\fR with netmask in CIDR format.
-.
-.SH OPTIONS
-One of \fB\-s\fR or \fB\-c\fR is required. The \fB\-t\fR option is
-also required.
-.
-.IP "\fB\-s \fITunnelRemoteIP,InnerIP[/mask][:ControlPort]\fR"
-.IQ "\fB\-\-server\fR \fITunnelRemoteIP,InnerIP[/mask][:ControlPort]\fR"
-Run in server mode and create L3 tunnel with the client that will be
-accepting tunnel at \fITunnelRemoteIP\fR address. The socket on
-\fIInnerIP[:ControlPort]\fR will be used to receive further instructions
-from the client.
-.
-.IP "\fB\-c \fITunnelRemoteIP,InnerIP[/mask][:ControlPort\
-[:DataPort]],RemoteInnerIP[:ControlPort[:DataPort]]\fR"
-.IQ "\fB\-\-client \fITunnelRemoteIP,InnerIP[/mask][:ControlPort\
-[:DataPort]],RemoteInnerIP[:ControlPort[:DataPort]]\fR"
-Run in client mode and create L3 tunnel with the server on
-\fITunnelRemoteIP\fR. The client will use \fIInnerIP\fR to generate test
-traffic with the server's \fIRemoteInnerIP\fR.
-.
-.IP "\fB\-b \fItargetbandwidth\fR"
-.IQ "\fB\-\-bandwidth\fR \fItargetbandwidth\fR"
-Target bandwidth for UDP tests. The \fItargetbandwidth\fR must be given in
-bits per second. It is possible to use postfix M or K to alter the target
-bandwidth magnitude.
-.
-.IP "\fB\-i \fItestinterval\fR"
-.IQ "\fB\-\-interval\fR \fItestinterval\fR"
-How long each test should run. By default 5 seconds.
-.
-.IP "\fB\-t \fItunnelmode\fR"
-.IQ "\fB\-\-tunnel\-mode\fR \fItunnelmode\fR"
-Specify the tunnel type. This option must match on server and client.
-.
-.so lib/common.man
-.
-.SH EXAMPLES
-.PP
-On host 192.168.122.220 start \fBovs\-l3ping\fR in server mode. This command
-will create a temporary GRE tunnel with the host 192.168.122.236 and assign
-10.1.1.1/28 as the inner IP address, where client will have to connect:
-.IP
-.B ovs\-l3ping -s 192.168.122.236,10.1.1.1/28 -t gre
-.
-.PP
-On host 192.168.122.236 start \fBovs\-l3ping\fR in client mode. This command
-will use 10.1.1.2/28 as the local inner IP address and will connect over the
-L3 tunnel to the server's inner IP address at 10.1.1.1.
-.IP
-.B ovs\-l3ping -c 192.168.122.220,10.1.1.2/28,10.1.1.1 -t gre
-.
-.SH SEE ALSO
-.
-.BR ovs\-vswitchd (8),
-.BR ovs\-ofctl (8),
-.BR ovs\-vsctl (8),
-.BR ovs\-vlan\-test (8),
-.BR ovs\-test (8),
-.BR ethtool (8),
-.BR uname (1)
deleted file mode 100644
@@ -1,28 +0,0 @@
-.TH ovs\-parse\-backtrace 8 "October 2012" "Open vSwitch" "Open vSwitch Manual"
-.
-.SH NAME
-ovs\-parse\-backtrace \- parses ovs-appctl backtrace output
-.
-.SH SYNOPSIS
-\fBovs\-appctl backtrace\fR | \fBovs\-parse\-backtrace\fR [\fIbinary\fR]
-.P
-\fBovs\-parse\-backtrace\fR [\fIbinary\fR] < \fIbacktrace\fR
-.
-.SH DESCRIPTION
-In some configurations, many Open vSwitch daemons can produce a series of
-backtraces using the \fBovs\-appctl backtrace\fR command. Users can analyze
-these backtraces to figure out what the given Open vSwitch daemon may be
-spending most of its time doing. \fBovs\-parse\-backtrace\fR makes this output
-easier to interpret.
-.PP
-The \fBovs\-appctl backtrace\fR output must be supplied on standard input. The
-binary that produced the output should be supplied as the sole non-option
-argument. For best results, the binary should have debug symbols.
-.
-.SH OPTIONS
-.TP
-\fB\-\-help\fR
-Prints a usage message and exits.
-.P
-\fB\-\-version\fR
-Prints the version and exits.
deleted file mode 100644
@@ -1,243 +0,0 @@
-.so lib/ovs.tmac
-.TH ovs\-pki 8 "@VERSION@" "Open vSwitch" "Open vSwitch Manual"
-
-.SH NAME
-ovs\-pki \- OpenFlow public key infrastructure management utility
-
-.SH SYNOPSIS
-Each command takes the form:
-.sp
-\fBovs\-pki\fR [\fIoptions\fR] \fIcommand\fR [\fIargs\fR]
-.sp
-The implemented commands and their arguments are:
-.br
-\fBovs\-pki\fR \fBinit\fR
-.br
-\fBovs\-pki\fR \fBreq\fR \fIname\fR
-.br
-\fBovs\-pki\fR \fBsign\fR \fIname\fR [\fItype\fR]
-.br
-\fBovs\-pki\fR \fBreq+sign\fR \fIname\fR [\fItype\fR]
-.br
-\fBovs\-pki\fR \fBverify\fR \fIname\fR [\fItype\fR]
-.br
-\fBovs\-pki\fR \fBfingerprint\fR \fIfile\fR
-.br
-\fBovs\-pki\fR \fBself\-sign\fR \fIname\fR
-.sp
-Each \fItype\fR above is a certificate type, either \fBswitch\fR
-(default) or \fBcontroller\fR.
-.sp
-The available options are:
-.br
-[\fB\-k\fR \fItype\fR | \fB\-\^\-key=\fItype\fR]
-.br
-[\fB\-B\fR \fInbits\fR | \fB\-\^\-bits=\fInbits\fR]
-.br
-[\fB\-D\fR \fIfile\fR | \fB\-\^\-dsaparam=\fIfile\fR]
-.br
-[\fB\-b\fR | \fB\-\^\-batch\fR]
-.br
-[\fB\-f\fR | \fB\-\^\-force\fR]
-.br
-[\fB\-d\fR \fIdir\fR | \fB\-\^\-dir=\fR\fIdir\fR]
-.br
-[\fB\-l\fR \fIfile\fR | \fB\-\^\-log=\fIfile\fR]
-.br
-[\fB\-u\fR | \fB\-\^\-unique\fR]
-.br
-[\fB\-h\fR | \fB\-\^\-help\fR]
-.sp
-Some options do not apply to every command.
-
-.SH DESCRIPTION
-The \fBovs\-pki\fR program sets up and manages a public key
-infrastructure for use with OpenFlow. It is intended to be a simple
-interface for organizations that do not have an established public key
-infrastructure. Other PKI tools can substitute for or supplement the
-use of \fBovs\-pki\fR.
-
-\fBovs\-pki\fR uses \fBopenssl\fR(1) for certificate management and key
-generation.
-
-.SH "OFFLINE COMMANDS"
-
-The following \fBovs\-pki\fR commands support manual PKI
-administration:
-
-.TP
-\fBinit\fR
-Initializes a new PKI (by default in directory \fB@PKIDIR@\fR) and populates
-it with a pair of certificate authorities for controllers and
-switches.
-
-This command should ideally be run on a high\-security machine separate
-from any OpenFlow controller or switch, called the CA machine. The
-files \fBpki/controllerca/cacert.pem\fR and
-\fBpki/switchca/cacert.pem\fR that it produces will need to be copied
-over to the OpenFlow switches and controllers, respectively. Their
-contents may safely be made public.
-
-By default, \fBovs\-pki\fR generates 2048\-bit RSA keys. The \fB\-B\fR
-or \fB\-\^\-bits\fR option (see below) may be used to override the key
-length. The \fB\-k dsa\fR or \fB\-\^\-key=dsa\fR option may be used to use
-DSA in place of RSA. If DSA is selected, the \fBdsaparam.pem\fR file
-generated in the new PKI hierarchy must be copied to any machine on
-which the \fBreq\fR command (see below) will be executed. Its
-contents may safely be made public.
-
-Other files generated by \fBinit\fR may remain on the CA machine.
-The files \fBpki/controllerca/private/cakey.pem\fR and
-\fBpki/switchca/private/cakey.pem\fR have particularly sensitive
-contents that should not be exposed.
-
-.TP
-\fBreq\fR \fIname\fR
-Generates a new private key named \fIname\fR\fB\-privkey.pem\fR and
-corresponding certificate request named \fIname\fR\fB\-req.pem\fR.
-The private key can be intended for use by a switch or a controller.
-
-This command should ideally be run on the switch or controller that
-will use the private key to identify itself. The file
-\fIname\fR\fB\-req.pem\fR must be copied to the CA machine for signing
-with the \fBsign\fR command (below).
-
-This command will output a fingerprint to stdout as its final step.
-Write down the fingerprint and take it to the CA machine before
-continuing with the \fBsign\fR step.
-
-When RSA keys are in use (as is the default), \fBreq\fR, unlike the
-rest of \fBovs\-pki\fR's commands, does not need access to a PKI
-hierarchy created by \fBovs\-pki init\fR. The \fB\-B\fR or
-\fB\-\^\-bits\fR option (see below) may be used to specify the number of
-bits in the generated RSA key.
-
-When DSA keys are used (as specified with \fB\-\^\-key=dsa\fR), \fBreq\fR
-needs access to the \fBdsaparam.pem\fR file created as part of the PKI
-hierarchy (but not to other files in that tree). By default,
-\fBovs\-pki\fR looks for this file in \fB@PKIDIR@/dsaparam.pem\fR, but
-the \fB\-D\fR or \fB\-\^\-dsaparam\fR option (see below) may be used to
-specify an alternate location.
-
-\fIname\fR\fB\-privkey.pem\fR has sensitive contents that should not be
-exposed. \fIname\fR\fB\-req.pem\fR may be safely made public.
-
-.TP
-\fBsign\fR \fIname\fR [\fItype\fR]
-Signs the certificate request named \fIname\fR\fB\-req.pem\fR that was
-produced in the previous step, producing a certificate named
-\fIname\fR\fB\-cert.pem\fR. \fItype\fR, either \fBswitch\fR (default) or
-\fBcontroller\fR, indicates the use for which the key is being
-certified.
-
-This command must be run on the CA machine.
-
-The command will output a fingerprint to stdout and request that you
-verify that it is the same fingerprint output by the \fBreq\fR
-command. This ensures that the request being signed is the same one
-produced by \fBreq\fR. (The \fB\-b\fR or \fB\-\^\-batch\fR option
-suppresses the verification step.)
-
-The file \fIname\fR\fB\-cert.pem\fR will need to be copied back to the
-switch or controller for which it is intended. Its contents may
-safely be made public.
-
-.TP
-\fBreq+sign\fR \fIname\fR [\fItype\fR]
-Combines the \fBreq\fR and \fBsign\fR commands into a single step,
-outputting all the files produced by each. The
-\fIname\fR\fB\-privkey.pem\fR and \fIname\fR\fB\-cert.pem\fR files must
-be copied securely to the switch or controller.
-\fIname\fR\fB\-privkey.pem\fR has sensitive contents and must not be
-exposed in transit. Afterward, it should be deleted from the CA
-machine.
-
-This combined method is, theoretically, less secure than the
-individual steps performed separately on two different machines,
-because there is additional potential for exposure of the private
-key. However, it is also more convenient.
-
-.TP
-\fBverify\fR \fIname\fR [\fItype\fR]
-Verifies that \fIname\fR\fB\-cert.pem\fR is a valid certificate for the
-given \fItype\fR of use, either \fBswitch\fR (default) or
-\fBcontroller\fR. If the certificate is valid for this use, it prints
-the message ``\fIname\fR\fB\-cert.pem\fR: OK''; otherwise, it prints an
-error message.
-
-.TP
-\fBfingerprint\fR \fIfile\fR
-Prints the fingerprint for \fIfile\fR. If \fIfile\fR is a
-certificate, then this is the SHA\-1 digest of the DER encoded version
-of the certificate; otherwise, it is the SHA\-1 digest of the entire
-file.
-
-.TP
-\fBself\-sign\fR \fIname\fR
-Signs the certificate request named \fIname\fB\-req.pem\fR using the
-private key \fIname\fB\-privkey.pem\fR, producing a self-signed
-certificate named \fIname\fB\-cert.pem\fR. The input files should have
-been produced with \fBovs\-pki req\fR.
-
-Some controllers accept such self-signed certificates.
-
-.SH OPTIONS
-.IP "\fB\-k\fR \fItype\fR"
-.IQ "\fB\-\^\-key=\fItype\fR"
-For the \fBinit\fR command, sets the public key algorithm to use for
-the new PKI hierarchy. For the \fBreq\fR and \fBreq+sign\fR commands,
-sets the public key algorithm to use for the key to be generated,
-which must match the value specified on \fBinit\fR. With other
-commands, the value has no effect.
-
-The \fItype\fR may be \fBrsa\fR (the default) or \fBdsa\fR.
-
-.IP "\fB\-B\fR \fInbits\fR"
-.IQ "\fB\-\^\-bits=\fInbits\fR"
-Sets the number of bits in the key to be generated. When RSA keys are
-in use, this option affects only the \fBinit\fR, \fBreq\fR, and
-\fBreq+sign\fR commands, and the same value should be given each time.
-With DSA keys are in use, this option affects only the \fBinit\fR
-command.
-
-The value must be at least 1024. The default is 2048.
-
-.IP "\fB\-D\fR \fIfile\fR"
-.IQ "\fB\-\^\-dsaparam=\fIfile\fR"
-Specifies an alternate location for the \fBdsaparam.pem\fR file
-required by the \fBreq\fR and \fBreq+sign\fR commands. This option
-affects only these commands, and only when DSA keys are used.
-
-The default is \fBdsaparam.pem\fR under the PKI hierarchy.
-
-.IP "\fB\-b\fR"
-.IQ "\fB\-\^\-batch\fR"
-Suppresses the interactive verification of fingerprints that the
-\fBsign\fR command by default requires.
-
-.IP "\fB\-d\fR \fIdir\fR"
-.IQ "\fB\-\^\-dir=\fR\fIdir\fR"
-Specifies the location of the PKI hierarchy to be used or created by
-the command (default: \fB@PKIDIR@\fR). All commands, except \fBreq\fR,
-need access to a PKI hierarchy.
-
-.IP "\fB\-f\fR"
-.IQ "\fB\-\^\-force\fR"
-By default, \fBovs\-pki\fR will not overwrite existing files or
-directories. This option overrides this behavior.
-
-.IP "\fB\-l\fR \fIfile\fR"
-.IQ "\fB\-\^\-log=\fIfile\fR"
-Sets the log file to \fIfile\fR. Default:
-\fB@LOGDIR@/ovs\-pki.log\fR.
-
-.IP "\fB\-u\fR"
-.IQ "\fB\-\^\-unique\fR"
-Changes the format of the certificate's Common Name (CN) field; by
-default, this field has the format "<name> id:<uuid-or-date>", this
-option causes the provided name to be treated as unique and changes
-the format of the CN field to be simply "<name>".
-
-.IP "\fB\-h\fR"
-.IQ "\fB\-\^\-help\fR"
-Prints a help usage message and exits.
deleted file mode 100644
@@ -1,55 +0,0 @@
-.so lib/ovs.tmac
-.TH ovs\-tcpdump 8 "@VERSION@" "Open vSwitch" "Open vSwitch Manual"
-.
-.SH NAME
-ovs\-tcpdump \- Dump traffic from an Open vSwitch port using \fBtcpdump\fR.
-.
-.SH SYNOPSIS
-\fBovs\-tcpdump\fR \fB\-i\fR \fIport\fR \fBtcpdump options...\fR
-.
-.SH DESCRIPTION
-\fBovs\-tcpdump\fR creates switch mirror ports in the \fBovs\-vswitchd\fR
-daemon and executes \fBtcpdump\fR to listen against those ports. When the
-\fBtcpdump\fR instance exits, it then cleans up the mirror port it created.
-.PP
-\fBovs\-tcpdump\fR will not allow multiple mirrors for the same port. It has
-some logic to parse the current configuration and prevent duplicate mirrors.
-.PP
-The \fB\-i\fR option may not appear multiple times.
-.PP
-It is important to note that under \fBLinux\fR based kernels, tap devices do
-not receive packets unless the specific tuntap device has been opened by an
-application. This requires \fBCAP_NET_ADMIN\fR privileges, so the
-\fBovs-tcpdump\fR command must be run as a user with such permissions (this
-is usually a super-user).
-.
-.SH "OPTIONS"
-.so lib/common.man
-.
-.IP "\fB\-\-db\-sock\fR"
-The Open vSwitch database socket connection string. The default is
-\fIunix:@RUNDIR@/db.sock\fR
-.
-.IP "\fB\-\-dump\-cmd\fR"
-The command to run instead of \fBtcpdump\fR.
-.
-.IP "\fB\-i\fR"
-.IQ "\fB\-\-interface\fR"
-The interface for which a mirror port should be created, and packets should
-be dumped.
-.
-.IP "\fB\-\-mirror\-to\fR"
-The name of the interface which should be the destination of the mirrored
-packets. The default is miINTERFACE
-.
-.IP "\fB\-\-span\fR"
-If specified, mirror all ports (optional).
-.
-.SH "SEE ALSO"
-.
-.BR ovs\-appctl (8),
-.BR ovs\-vswitchd (8),
-.BR ovs\-pcap (1),
-.BR ovs\-tcpundump (1),
-.BR tcpdump (8),
-.BR wireshark (8).
deleted file mode 100644
@@ -1,32 +0,0 @@
-.so lib/ovs.tmac
-.TH ovs\-tcpundump 1 "@VERSION@" "Open vSwitch" "Open vSwitch Manual"
-.
-.SH NAME
-ovs\-tcpundump \- convert ``tcpdump \-xx'' output to hex strings
-.
-.SH SYNOPSIS
-\fBovs\-tcpundump < \fIfile\fR
-.so lib/common-syn.man
-.
-.SH DESCRIPTION
-The \fBovs\-tcpundump\fR program reads \fBtcpdump \-xx\fR output on
-stdin, looking for hexadecimal packet data, and dumps each Ethernet as
-a single hexadecimal string on stdout. This format is suitable for
-use with the \fBofproto/trace\fR command supported by
-\fBovs\-vswitchd\fR(8)
-via \fBovs\-appctl\fR(8).
-.PP
-At least two \fB\-x\fR or \fB\-X\fR options must be given, otherwise
-the output will omit the Ethernet header, which prevents the output
-from being using with \fBofproto/trace\fR.
-.
-.SH "OPTIONS"
-.so lib/common.man
-.
-.SH "SEE ALSO"
-.
-.BR ovs\-appctl (8),
-.BR ovs\-vswitchd (8),
-.BR ovs\-pcap (1),
-.BR tcpdump (8),
-.BR wireshark (8).
Signed-off-by: Ben Pfaff <blp@ovn.org> --- Documentation/automake.mk | 7 + Documentation/conf.py | 14 + Documentation/ref/index.rst | 35 +- Documentation/ref/ovs-appctl.8.rst | 332 +++++++++++++ Documentation/ref/ovs-ctl.8.rst | 491 +++++++++++++++++++ Documentation/ref/ovs-l3ping.8.rst | 129 +++++ Documentation/ref/ovs-parse-backtrace.8.rst | 34 ++ Documentation/ref/ovs-pki.8.rst | 251 ++++++++++ Documentation/ref/ovs-tcpdump.8.rst | 68 +++ Documentation/ref/ovs-tcpundump.1.rst | 39 ++ manpages.mk | 59 +-- utilities/automake.mk | 19 - utilities/ovs-appctl.8.in | 293 ----------- utilities/ovs-ctl.8 | 518 -------------------- utilities/ovs-l3ping.8.in | 110 ----- utilities/ovs-parse-backtrace.8 | 28 -- utilities/ovs-pki.8.in | 243 --------- utilities/ovs-tcpdump.8.in | 55 --- utilities/ovs-tcpundump.1.in | 32 -- 19 files changed, 1376 insertions(+), 1381 deletions(-) create mode 100644 Documentation/ref/ovs-appctl.8.rst create mode 100644 Documentation/ref/ovs-ctl.8.rst create mode 100644 Documentation/ref/ovs-l3ping.8.rst create mode 100644 Documentation/ref/ovs-parse-backtrace.8.rst create mode 100644 Documentation/ref/ovs-pki.8.rst create mode 100644 Documentation/ref/ovs-tcpdump.8.rst create mode 100644 Documentation/ref/ovs-tcpundump.1.rst delete mode 100644 utilities/ovs-appctl.8.in delete mode 100644 utilities/ovs-ctl.8 delete mode 100644 utilities/ovs-l3ping.8.in delete mode 100644 utilities/ovs-parse-backtrace.8 delete mode 100644 utilities/ovs-pki.8.in delete mode 100644 utilities/ovs-tcpdump.8.in delete mode 100644 utilities/ovs-tcpundump.1.in