Documentation: Convert multiple manpages to ReST.

Tested-by: Numan Siddique <numans@ovn.org>
Acked-by: Numan Siddique <numans@ovn.org>
Signed-off-by: Ben Pfaff <blp@ovn.org>

8 files changed, 1351 insertions, 28 deletions

diff --git a/Documentation/ref/index.rst b/Documentation/ref/index.rst
index 83f031c4f..274dacbeb 100644
--- a/Documentation/ref/index.rst
+++ b/Documentation/ref/index.rst
@@ -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>`__
diff --git a/Documentation/ref/ovs-appctl.8.rst b/Documentation/ref/ovs-appctl.8.rst
new file mode 100644
index 000000000..a488d9f48
--- /dev/null
+++ b/Documentation/ref/ovs-appctl.8.rst
@@ -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)``.
diff --git a/Documentation/ref/ovs-ctl.8.rst b/Documentation/ref/ovs-ctl.8.rst
new file mode 100644
index 000000000..7cfc41322
--- /dev/null
+++ b/Documentation/ref/ovs-ctl.8.rst
@@ -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)``.
diff --git a/Documentation/ref/ovs-l3ping.8.rst b/Documentation/ref/ovs-l3ping.8.rst
new file mode 100644
index 000000000..f9c88fcd6
--- /dev/null
+++ b/Documentation/ref/ovs-l3ping.8.rst
@@ -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)``.
diff --git a/Documentation/ref/ovs-parse-backtrace.8.rst b/Documentation/ref/ovs-parse-backtrace.8.rst
new file mode 100644
index 000000000..27270c612
--- /dev/null
+++ b/Documentation/ref/ovs-parse-backtrace.8.rst
@@ -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.
diff --git a/Documentation/ref/ovs-pki.8.rst b/Documentation/ref/ovs-pki.8.rst
new file mode 100644
index 000000000..517d272fb
--- /dev/null
+++ b/Documentation/ref/ovs-pki.8.rst
@@ -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.
diff --git a/Documentation/ref/ovs-tcpdump.8.rst b/Documentation/ref/ovs-tcpdump.8.rst
new file mode 100644
index 000000000..048b70f23
--- /dev/null
+++ b/Documentation/ref/ovs-tcpdump.8.rst
@@ -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)``.
diff --git a/Documentation/ref/ovs-tcpundump.1.rst b/Documentation/ref/ovs-tcpundump.1.rst
new file mode 100644
index 000000000..27710226f
--- /dev/null
+++ b/Documentation/ref/ovs-tcpundump.1.rst
@@ -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)``.