From patchwork Thu Oct 10 21:29:42 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Ben Pfaff X-Patchwork-Id: 1174826 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (mailfrom) smtp.mailfrom=openvswitch.org (client-ip=140.211.169.12; helo=mail.linuxfoundation.org; envelope-from=ovs-dev-bounces@openvswitch.org; receiver=) Authentication-Results: ozlabs.org; dmarc=none (p=none dis=none) header.from=ovn.org Received: from mail.linuxfoundation.org (mail.linuxfoundation.org [140.211.169.12]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 46q6YQ5L1Yz9sN1 for ; Fri, 11 Oct 2019 10:22:02 +1100 (AEDT) Received: from mail.linux-foundation.org (localhost [127.0.0.1]) by mail.linuxfoundation.org (Postfix) with ESMTP id 9B253DB9; Thu, 10 Oct 2019 23:21:59 +0000 (UTC) X-Original-To: dev@openvswitch.org Delivered-To: ovs-dev@mail.linuxfoundation.org Received: from smtp1.linuxfoundation.org (smtp1.linux-foundation.org [172.17.192.35]) by mail.linuxfoundation.org (Postfix) with ESMTPS id C7CBEDA5 for ; Thu, 10 Oct 2019 23:21:58 +0000 (UTC) X-Greylist: domain auto-whitelisted by SQLgrey-1.7.6 Received: from relay4-d.mail.gandi.net (relay4-d.mail.gandi.net [217.70.183.196]) by smtp1.linuxfoundation.org (Postfix) with ESMTPS id 3AEA1604 for ; Thu, 10 Oct 2019 23:21:51 +0000 (UTC) X-Originating-IP: 66.170.99.95 Received: from localhost.localdomain (unknown [66.170.99.95]) (Authenticated sender: blp@ovn.org) by relay4-d.mail.gandi.net (Postfix) with ESMTPSA id A818BE0005; Thu, 10 Oct 2019 23:21:47 +0000 (UTC) From: Ben Pfaff To: dev@openvswitch.org Date: Thu, 10 Oct 2019 14:29:42 -0700 Message-Id: <20191010212942.32013-1-blp@ovn.org> X-Mailer: git-send-email 2.21.0 MIME-Version: 1.0 X-Spam-Status: No, score=-2.6 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_LOW autolearn=ham version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on smtp1.linux-foundation.org Cc: Ben Pfaff Subject: [ovs-dev] [PATCH] Documentation: Convert multiple manpages to ReST. X-BeenThere: ovs-dev@openvswitch.org X-Mailman-Version: 2.1.12 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: ovs-dev-bounces@openvswitch.org Errors-To: ovs-dev-bounces@openvswitch.org Signed-off-by: Ben Pfaff Tested-by: Numan Siddique Acked-by: Numan Siddique --- 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 diff --git a/Documentation/automake.mk b/Documentation/automake.mk index 5f7c3e07bbaf..f2ca17bad692 100644 --- a/Documentation/automake.mk +++ b/Documentation/automake.mk @@ -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 \ diff --git a/Documentation/conf.py b/Documentation/conf.py index 0a61dc3f336a..6bbfc02bdd09 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -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', diff --git a/Documentation/ref/index.rst b/Documentation/ref/index.rst index 0cb5ef571676..3d9b138540ae 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) `__ - `(html) `__ - `(plain text) `__ - * - ovs-appctl(8) - - `(pdf) `__ - - `(html) `__ - - `(plain text) `__ * - ovs-bugtool(8) - `(pdf) `__ - `(html) `__ - `(plain text) `__ - * - ovs-ctl(8) - - `(pdf) `__ - - `(html) `__ - - `(plain text) `__ * - ovsdb-client(1) - `(pdf) `__ - `(html) `__ @@ -90,34 +89,14 @@ The remainder are still in roff format can be found below: - `(pdf) `__ - `(html) `__ - `(plain text) `__ - * - ovs-l3ping(8) - - `(pdf) `__ - - `(html) `__ - - `(plain text) `__ * - ovs-ofctl(8) - `(pdf) `__ - `(html) `__ - `(plain text) `__ - * - ovs-parse-backtrace(8) - - `(pdf) `__ - - `(html) `__ - - `(plain text) `__ * - ovs-pcap(1) - `(pdf) `__ - `(html) `__ - `(plain text) `__ - * - ovs-pki(8) - - `(pdf) `__ - - `(html) `__ - - `(plain text) `__ - * - ovs-tcpdump(8) - - `(pdf) `__ - - `(html) `__ - - `(plain text) `__ - * - ovs-tcpundump(1) - - `(pdf) `__ - - `(html) `__ - - `(plain text) `__ * - ovs-test(8) - `(pdf) `__ - `(html) `__ diff --git a/Documentation/ref/ovs-appctl.8.rst b/Documentation/ref/ovs-appctl.8.rst new file mode 100644 index 000000000000..a488d9f48006 --- /dev/null +++ b/Documentation/ref/ovs-appctl.8.rst @@ -0,0 +1,332 @@ +========== +ovs-appctl +========== + +Synopsis +======== + +``ovs-appctl`` +[``--target=`` | ``-t`` ] +[``--timeout=`` | ``-T`` ] + [...] + +``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`` or ``--target`` + + Tells ``ovs-appctl`` which daemon to contact. + + If 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 ``..ctl``, where + is the program's name and 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 ``.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 + ``..ctl``, where 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, 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 + ``.ctl`` located inside the rundir. If is not an + absolute path, ``ovs-appctl`` looks in the rundir for a file named + ``.ctl``. The default target is ``ovs-vswitchd``. + +* ``-T `` or ``--timeout=`` + + By default, or with a of ``0``, ``ovs-appctl`` waits forever to + connect to the daemon and receive a response. This option limits + runtime to approximately 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`` [] + + Sets logging levels. Without any , sets the log level for + every module and destination to ``dbg``. Otherwise, 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 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 . + + 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 but it has no effect. + +* ``vlog/set PATTERN::`` + + Sets the log pattern for to . Each time a + message is logged to , determines the + message's formatting. Most characters in 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{}`` + + The current date and time in the specified , which takes + the same format as the