[ovs-dev,1/3] ovn-nbctl: Improve manpage.

This rearranges the manpage into a more logical order, documents some
options that weren't documented, adds some sections such as
Environment and Exit Status that a manpage should have, puts the
headings at reasonable levels instead of all at the top level, and adds
a little more explanatory text in a few places.

Signed-off-by: Ben Pfaff <blp@ovn.org>
---
 utilities/ovn-nbctl.8.xml | 670 ++++++++++++++++++++++----------------
 1 file changed, 392 insertions(+), 278 deletions(-)

On 3/25/21 7:26 PM, Ben Pfaff wrote:
> This rearranges the manpage into a more logical order, documents some
> options that weren't documented, adds some sections such as
> Environment and Exit Status that a manpage should have, puts the
> headings at reasonable levels instead of all at the top level, and adds
> a little more explanatory text in a few places.
> 
> Signed-off-by: Ben Pfaff <blp@ovn.org>
> ---
>   utilities/ovn-nbctl.8.xml | 670 ++++++++++++++++++++++----------------
>   1 file changed, 392 insertions(+), 278 deletions(-)
> 
> diff --git a/utilities/ovn-nbctl.8.xml b/utilities/ovn-nbctl.8.xml
> index 2cab592ce347..51fc986dcf9a 100644
> --- a/utilities/ovn-nbctl.8.xml
> +++ b/utilities/ovn-nbctl.8.xml
> @@ -7,9 +7,327 @@
>       <p><code>ovn-nbctl</code> [<var>options</var>] <var>command</var> [<var>arg</var>...]</p>
>   
>       <h1>Description</h1>
> -    <p>This utility can be used to manage the OVN northbound database.</p>
>   
> -    <h1>General Commands</h1>
> +    <p>
> +      The <code>ovn-nbctl</code> program configures the
> +      <code>OVN_Northbound</code> database by providing a high-level interface
> +      to its configuration database.  See <code>ovn-nb</code>(5) for
> +      comprehensive documentation of the database schema.
> +    </p>
> +
> +    <p>
> +      <code>ovn-nbctl</code> connects to an <code>ovsdb-server</code> process
> +      that maintains an OVN_Northbound configuration database.  Using this
> +      connection, it queries and possibly applies changes to the database,
> +      depending on the supplied commands.
> +    </p>
> +
> +    <p>
> +      <code>ovn-nbctl</code> can perform any number of commands in a single
> +      run, implemented as a single atomic transaction against the database.
> +    </p>
> +
> +    <p>
> +      The <code>ovn-nbctl</code> command line begins with global options (see
> +      <code>OPTIONS</code> below for details).  The global options are followed
> +      by one or more commands.  Each command should begin with <code>--</code>
> +      by itself as a command-line argument, to separate it from the following
> +      commands.  (The <code>--</code> before the first command is optional.)
> +      The command itself starts with command-specific options, if any, followed
> +      by the command name and any arguments.
> +    </p>
> +
> +    <h1>Daemon Mode</h1>
> +
> +    <p>
> +      When it is invoked in the most ordinary way, <code>ovn-nbctl</code>
> +      connects to an OVSDB server that hosts the northbound database, retrieves
> +      a partial copy of the database that is complete enough to do its work,
> +      sends a transaction request to the server, and receives and processes the
> +      server's reply.  In common interactive use, this is fine, but if the
> +      database is large, the step in which <code>ovn-nbctl</code> retrieves a
> +      partial copy of the database can take a long time, which yields poor
> +      performance overall.
> +    </p>
> +
> +    <p>
> +      To improve performance in such a case, <code>ovn-nbctl</code> offers a
> +      "daemon mode," in which the user first starts <code>ovn-nbctl</code>
> +      running in the background and afterward uses the daemon to execute
> +      operations.  Over several <code>ovn-nbctl</code> command invocations,
> +      this performs better overall because it retrieves a copy of the database
> +      only once at the beginning, not once per program run.
> +    </p>
> +
> +    <p>
> +      Use the <code>--detach</code> option to start an <code>ovn-nbctl</code>
> +      daemon.  With this option, <code>ovn-nbctl</code> prints the name of a
> +      control socket to stdout.  The client should save this name in
> +      environment variable <env>OVN_NB_DAEMON</env>.  Under the Bourne shell
> +      this might be done like this:
> +    </p>
> +
> +    <pre fixed="yes">
> +      export OVN_NB_DAEMON=$(ovn-nbctl --pidfile --detach)
> +    </pre>
> +
> +    <p>
> +      When <env>OVN_NB_DAEMON</env> is set, <code>ovn-nbctl</code>
> +      automatically and transparently uses the daemon to execute its commands.
> +    </p>
> +
> +    <p>
> +      When the daemon is no longer needed, kill it and unset the environment
> +      variable, e.g.:
> +    </p>
> +
> +    <pre fixed="yes">
> +      kill $(cat $OVN_RUNDIR/ovn-nbctl.pid)
> +      unset OVN_NB_DAEMON
> +    </pre>
> +
> +    <p>
> +      When using daemon mode, an alternative to the <env>OVN_NB_DAEMON</env>
> +      environment variable is to specify a path for the Unix socket. When
> +      starting the ovn-nbctl daemon, specify the <code>-u</code> option with a
> +      full path to the location of the socket file. Here is an exmple:
> +    </p>
> +
> +    <pre fixed="yes">
> +      ovn-nbctl --detach -u /tmp/mysock.ctl
> +    </pre>
> +
> +    <p>
> +      Then to connect to the running daemon, use the <code>-u</code> option
> +      with the full path to the socket created when the daemon was started:
> +    </p>
> +
> +    <pre fixed="yes">
> +      ovn-nbctl -u /tmp/mysock.ctl show
> +    </pre>
> +
> +    <p>
> +      Daemon mode is experimental.
> +    </p>

Is daemon mode really still experimental? For ovn-nbctl, it's been 
around a couple of years at this point and was used heavily by 
ovn-kubernetes with no issues.

> +
> +    <h3>Daemon Commands</h3>
> +
> +    <p>
> +      Daemon mode is internally implemented using the same mechanism used by
> +      <code>ovs-appctl</code>.  One may also use <code>ovs-appctl</code>

I believe you should replace "ovs-appctl" above with "ovn-appctl". I'm 
aware this was just copied from text that had previously been in the 
manpage, but the original text was wrong as well.

This same mention is made in patch 3 for the ovn-sbctl daemon and should 
probably be amended there too.

> +      directly with the following commands:
> +    </p>
> +
> +    <dl>
> +      <dt>
> +        <code>run</code> [<var>options</var>] <var>command</var>
> +        [<var>arg</var>...] [<code>--</code> [<var>options</var>]
> +        <var>command</var> [<var>arg</var>...] ...]
> +      </dt>
> +      <dd>
> +        Instructs the daemon process to run one or more <code>ovn-nbctl</code>
> +        commands described above and reply with the results of running these
> +        commands. Accepts the <code>--no-wait</code>, <code>--wait</code>,
> +        <code>--timeout</code>, <code>--dry-run</code>, <code>--oneline</code>,
> +        and the options described under <code>Table Formatting Options</code>
> +        in addition to the the command-specific options.
> +      </dd>
> +
> +      <dt><code>exit</code></dt>
> +      <dd>Causes <code>ovn-nbctl</code> to gracefully terminate.</dd>
> +    </dl>
> +
> +    <h1>Options</h1>
> +
> +    <p>
> +      The options listed below affect the behavior of <code>ovn-nbctl</code> as
> +      a whole.  Some individual commands also accept their own options, which
> +      are given just before the command name.  If the first command on the
> +      command line has options, then those options must be separated from the
> +      global options by <code>--</code>.
> +    </p>
> +
> +    <p>
> +      <code>ovn-nbctl</code> also accepts options from the
> +      <env>OVN_NBCTL_OPTIONS</env> environment variable, in the same format as
> +      on the command line.  Options from the command line override those in the
> +      environment.
> +    </p>
> +
> +    <dl>
> +      <dt><code>--no-wait</code> | <code>--wait=none</code></dt>
> +      <dt><code>--wait=sb</code></dt>
> +      <dt><code>--wait=hv</code></dt>
> +
> +      <dd>
> +        <p>
> +          These options control whether and how <code>ovn-nbctl</code> waits
> +          for the OVN system to become up-to-date with changes made in an
> +          <code>ovn-nbctl</code> invocation.
> +        </p>
> +
> +        <p>
> +          By default, or if <code>--no-wait</code> or <code>--wait=none</code>,
> +          <code>ovn-nbctl</code> exits immediately after confirming that
> +          changes have been committed to the northbound database, without
> +          waiting.
> +        </p>
> +
> +        <p>
> +          With <code>--wait=sb</code>, before <code>ovn-nbctl</code> exits, it
> +          waits for <code>ovn-northd</code> to bring the southbound database
> +          up-to-date with the northbound database updates.
> +        </p>
> +
> +        <p>
> +          With <code>--wait=hv</code>, before <code>ovn-nbctl</code> exits, it
> +          additionally waits for all OVN chassis (hypervisors and gateways) to
> +          become up-to-date with the northbound database updates.  (This can
> +          become an indefinite wait if any chassis is malfunctioning.)
> +        </p>
> +
> +        <p>
> +          Ordinarily, <code>--wait=sb</code> or <code>--wait=hv</code> only
> +          waits for changes by the current <code>ovn-nbctl</code> invocation to
> +          take effect.  This means that, if none of the commands supplied to
> +          <code>ovn-nbctl</code> change the database, then the command does not
> +          wait at all.  Use the <code>sync</code> command to override this
> +          behavior.
> +        </p>
> +      </dd>
> +
> +      <dt><code>--db</code> <var>database</var></dt>
> +      <dd>
> +        The OVSDB database remote to contact.  If the <env>OVN_NB_DB</env>
> +        environment variable is set, its value is used as the default.
> +        Otherwise, the default is <code>unix:@RUNDIR@/ovnnb_db.sock</code>, but
> +        this default is unlikely to be useful outside of single-machine OVN
> +        test environments.
> +      </dd>
> +
> +      <dt><code>--leader-only</code></dt>
> +      <dt><code>--no-leader-only</code></dt>
> +      <dd>
> +        By default, or with <code>--leader-only</code>, when the database
> +        server is a clustered database, <code>ovn-nbctl</code> will avoid
> +        servers other than the cluster leader.  This ensures that any data that
> +        <code>ovn-nbctl</code> reads and reports is up-to-date.  With
> +        <code>--no-leader-only</code>, <code>ovn-nbctl</code> will use any
> +        server in the cluster, which means that for read-only transactions it
> +        can report and act on stale data (transactions that modify the database
> +        are always serialized even with <code>--no-leader-only</code>).  Refer
> +        to <code>Understanding Cluster Consistency</code> in
> +        <code>ovsdb</code>(7) for more information.
> +      </dd>
> +
> +      <dt><code>--shuffle-remotes</code></dt>
> +      <dt><code>--no-shuffle-remotes</code></dt>
> +      <dd>
> +        By default, or with <code>--shuffle-remotes</code>, when there are
> +        multiple remotes specified in the OVSDB connection string specified by
> +        <code>--db</code> or the <env>OVN_NB_DB</env> environment variable, the
> +        order of the remotes will be shuffled before the client tries to
> +        connect.  The remotes will be shuffled only once to a new order before
> +        the first connection attempt.  The following retries, if any, will
> +        follow the same new order.  The default behavior is to make sure
> +        clients of a clustered database can distribute evenly to all memembers
> +        of the cluster.  With <code>--no-shuffle-remotes</code>,
> +        <code>ovn-nbctl</code> will use the original order specified in the
> +        connection string to connect.  This allows user to specify the
> +        preferred order, which is particularly useful for testing.
> +      </dd>
> +
> +      <dt><code>--no-syslog</code></dt>
> +      <dd>
> +        <p>
> +          By default, <code>ovn-nbctl</code> logs its arguments and the details
> +          of any changes that it makes to the system log.  This option disables
> +          this logging.
> +        </p>
> +
> +        <p>
> +          This option is equivalent to
> +          <code>--verbose=nbctl:syslog:warn</code>.
> +        </p>
> +      </dd>
> +
> +      <dt><code>--oneline</code></dt>
> +      <dd>
> +        Modifies the output format so that the output for each command is
> +        printed on a single line.  New-line characters that would otherwise
> +        separate lines are printed as \fB\\n\fR, and any instances of \fB\\\fR
> +        that would otherwise appear in the output are doubled.  Prints a blank
> +        line for each command that has no output.  This option does not affect
> +        the formatting of output from the <code>list</code> or
> +        <code>find</code> commands; see <code>Table Formatting Options</code>
> +        below.
> +      </dd>
> +
> +      <dt><code>--dry-run</code></dt>
> +      <dd>
> +        Prevents <code>ovn-nbctl</code> from actually modifying the database.
> +      </dd>
> +
> +      <dt><code>-t <var>secs</var></code></dt>
> +      <dt><code>--timeout=<var>secs</var></code></dt>
> +      <dd>
> +        By default, or with a <var>secs</var> of <code>0</code>,
> +        <code>ovn-nbctl</code> waits forever for a response from the database.
> +        This option limits runtime to approximately <var>secs</var> seconds.
> +        If the timeout expires, <code>ovn-nbctl</code> will exit with a
> +        <code>SIGALRM</code> signal.  (A timeout would normally happen only if
> +        the database cannot be contacted, or if the system is overloaded.)
> +      </dd>
> +
> +      <dt><code>--print-wait-time</code></dt>
> +      <dd>
> +        When <code>--wait</code> is specified, the option
> +        <code>--print-wait-time</code> can be used to print the time spent on
> +        waiting, depending on the value specified in <code> --wait</code>
> +        option.  If <code>--wait=sb</code> is specified, it prints "ovn-northd
> +        delay before processing", which is the time between the Northbound DB
> +        update by the command and the moment when <code> ovn-northd</code>
> +        starts processing the update, and "ovn-northd completion", which is the
> +        time between the Northbound DB update and the moment when
> +        <code>ovn-northd</code> completes the Southbound DB updating
> +        successfully. If <code>--wait=hv</code> is specified, in addition to
> +        the above information, it also prints "ovn-controller(s) completion",
> +        which is the time between the Northbound DB update and the moment when
> +        the slowest hypervisor finishes processing the update.
> +      </dd>
> +    </dl>
> +
> +    <h2>Daemon Options</h2>
> +    <xi:include href="lib/daemon.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
> +
> +    <h2>Logging options</h2>
> +    <xi:include href="lib/vlog.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
> +
> +    <h2>Table Formatting Options</h2>
> +    These options control the format of output from the <code>list</code> and
> +    <code>find</code> commands.
> +    <xi:include href="lib/table.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
> +
> +    <h2>PKI Options</h2>
> +    <p>
> +      PKI configuration is required to use SSL for the connection to the
> +      database.
> +    </p>
> +    <xi:include href="lib/ssl.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
> +    <xi:include href="lib/ssl-bootstrap.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
> +
> +    <h2>Other Options</h2>
> +
> +    <xi:include href="lib/common.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
> +
> +    <h1>Commands</h1>
> +
> +    <p>
> +      The following sections describe the commands that <code>ovn-nbctl</code>
> +      supports.
> +    </p>
> +
> +    <h2>General Commands</h2>
>   
>       <dl>
>         <dt><code>init</code></dt>
> @@ -28,7 +346,7 @@
>         </dd>
>       </dl>
>   
> -    <h1>Logical Switch Commands</h1>
> +    <h2>Logical Switch Commands</h2>
>   
>       <dl>
>         <dt><code>ls-add</code></dt>
> @@ -74,7 +392,7 @@
>         </dd>
>       </dl>
>   
> -    <h1>ACL Commands</h1>
> +    <h2>ACL Commands</h2>
>       <p>
>         These commands operates on ACL objects for a given <var>entity</var>.
>         The <var>entity</var> can be either a logical switch or a port group.
> @@ -127,7 +445,7 @@
>         </dd>
>       </dl>
>   
> -    <h1>Logical Switch QoS Rule Commands</h1>
> +    <h2>Logical Switch QoS Rule Commands</h2>
>       <dl>
>         <dt>[<code>--may-exist</code>] <code>qos-add</code> <var>switch</var> <var>direction</var> <var>priority</var> <var>match</var> [<code>dscp=</code><var>dscp</var>] [<code>rate=</code><var>rate</var> [<code>burst=</code><var>burst</var>]]</dt>
>         <dd>
> @@ -181,7 +499,7 @@
>         </dd>
>       </dl>
>   
> -    <h1>Meter Commands</h1>
> +    <h2>Meter Commands</h2>
>       <dl>
>           <dt><code>meter-add</code> <var>name</var> <var>action</var> <var>rate</var> <var>unit</var> [<var>burst</var>]</dt>
>         <dd>
> @@ -234,7 +552,7 @@
>         </dd>
>       </dl>
>   
> -    <h1>Logical Switch Port Commands</h1>
> +    <h2>Logical Switch Port Commands</h2>
>       <dl>
>         <dt>[<code>--may-exist</code>] <code>lsp-add</code> <var>switch</var> <var>port</var></dt>
>         <dd>
> @@ -490,7 +808,7 @@
>   
>       </dl>
>   
> -    <h1>Forwarding Group Commands</h1>
> +    <h2>Forwarding Group Commands</h2>
>   
>       <dl>
>         <dt>[<code>--liveness</code>]<code>fwd-group-add</code> <var>group</var> <var>switch</var> <var>vip</var> <var>vmac</var> <var>ports</var></dt>
> @@ -528,7 +846,7 @@
>           be listed.
>         </dd>
>       </dl>
> -    <h1>Logical Router Commands</h1>
> +    <h2>Logical Router Commands</h2>
>   
>       <dl>
>         <dt><code>lr-add</code></dt>
> @@ -574,7 +892,7 @@
>         </dd>
>       </dl>
>   
> -    <h1>Logical Router Port Commands</h1>
> +    <h2>Logical Router Port Commands</h2>
>   
>       <dl>
>         <dt>[<code>--may-exist</code>] <code>lrp-add</code> <var>router</var> <var>port</var> <var>mac</var> <var>network</var>... [<code>peer=</code><var>peer</var>]</dt>
> @@ -654,7 +972,7 @@
>         </dd>
>       </dl>
>   
> -    <h1>Logical Router Static Route Commands</h1>
> +    <h2>Logical Router Static Route Commands</h2>
>   
>       <dl>
>         <dt>[<code>--may-exist</code>] [<code>--policy</code>=<var>POLICY</var>]
> @@ -745,7 +1063,7 @@
>         </dd>
>       </dl>
>   
> -    <h1>Logical Router Policy Commands</h1>
> +    <h2>Logical Router Policy Commands</h2>
>   
>       <dl>
>         <dt>[<code>--may-exist</code>]<code>lr-policy-add</code>
> @@ -817,7 +1135,7 @@
>         </dd>
>       </dl>
>   
> -    <h1>NAT Commands</h1>
> +    <h2>NAT Commands</h2>
>   
>       <dl>
>         <dt>[<code>--may-exist</code>] [<code>--stateless</code>]<code>lr-nat-add</code> <var>router</var> <var>type</var> <var>external_ip</var> <var>logical_ip</var> [<var>logical_port</var> <var>external_mac</var>]</dt>
> @@ -914,7 +1232,7 @@
>         </dd>
>       </dl>
>   
> -    <h1>Load Balancer Commands</h1>
> +    <h2>Load Balancer Commands</h2>
>       <dl>
>           <dt>[<code>--may-exist</code> | <code>--add-duplicate</code> | <code>--reject</code> | <code>--event</code>] <code>lb-add</code> <var>lb</var> <var>vip</var> <var>ips</var> [<var>protocol</var>]</dt>
>         <dd>
> @@ -1038,7 +1356,7 @@
>       </dl>
>   
>   
> -    <h1>DHCP Options commands</h1>
> +    <h2>DHCP Options commands</h2>
>   
>       <dl>
>         <dt><code>dhcp-options-create</code> <var>cidr</var> [<var>key=value</var>]</dt>
> @@ -1068,7 +1386,7 @@
>         </dd>
>       </dl>
>   
> -    <h1>Port Group commands</h1>
> +    <h2>Port Group commands</h2>
>   
>       <dl>
>         <dt><code>pg-add</code> <var>group</var> [<var>port</var>]...</dt>
> @@ -1090,7 +1408,7 @@
>         </dd>
>       </dl>
>   
> -    <h1> HA Chassis Group commands</h1>
> +    <h2> HA Chassis Group commands</h2>
>   
>       <dl>
>         <dt><code>ha-chassis-group-add</code> <var>group</var></dt>
> @@ -1131,38 +1449,7 @@
>         </dd>
>       </dl>
>   
> -    <h1>Database Commands</h1>
> -    <p>These commands query and modify the contents of <code>ovsdb</code> tables.
> -    They are a slight abstraction of the <code>ovsdb</code> interface and
> -    as such they operate at a lower level than other <code>ovn-nbctl</code> commands.</p>
> -    <p><var>Identifying Tables, Records, and Columns</var></p>
> -    <p>Each of these commands has a <var>table</var> parameter to identify a table
> -    within the database.  Many of them also take a <var>record</var> parameter
> -    that identifies a particular record within a table.  The <var>record</var>
> -    parameter may be the UUID for a record, which may be abbreviated to its
> -    first 4 (or more) hex digits, as long as that is unique.  Many tables offer
> -    additional ways to identify records.  Some commands also take
> -    <var>column</var> parameters that identify a particular field within the
> -    records in a table.</p>
> -
> -    <p>
> -      For a list of tables and their columns, see <code>ovn-nb</code>(5) or
> -      see the table listing from the <code>--help</code> option.
> -    </p>
> -
> -    <p>
> -      Record names must be specified in full and with correct capitalization,
> -      except that UUIDs may be abbreviated to their first 4 (or more) hex
> -      digits, as long as that is unique within the table.  Names of tables and
> -      columns are not case-sensitive, and <code>-</code> and <code>_</code> are
> -      treated interchangeably.  Unique abbreviations of table and column names
> -      are acceptable, e.g. <code>d</code> or <code>dhcp</code> is sufficient
> -      to identify the <code>DHCP_Options</code> table.
> -    </p>
> -
> -    <xi:include href="lib/db-ctl-base.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
> -
> -    <h1>Synchronization Commands</h1>
> +    <h2>Synchronization Commands</h2>
>   
>       <dl>
>         <dt>sync</dt>
> @@ -1178,7 +1465,15 @@
>         </dd>
>       </dl>
>   
> -    <h1>Remote Connectivity Commands</h1>
> +    <h2>Remote Connectivity Commands</h2>
> +    <p>
> +      These commands manipulate the <code>connections</code> column in the
> +      <code>NB_Global</code> table and rows in the <code>Connection</code>
> +      table.  When <code>ovsdb-server</code> is configured to use the
> +      <code>connections</code> column for OVSDB connections, this allows the
> +      administrator to use <code>ovn-nbctl</code> to configure database
> +      connections.
> +    </p>
>       <dl>
>         <dt><code>get-connection</code></dt>
>         <dd>
> @@ -1198,7 +1493,7 @@
>         </dd>
>       </dl>
>   
> -    <h1>SSL Configuration Commands</h1>
> +    <h2>SSL Configuration Commands</h2>
>       <dl>
>         <dt><code>get-ssl</code></dt>
>         <dd>
> @@ -1218,258 +1513,77 @@
>         </dd>
>       </dl>
>   
> -    <h1>Daemon Mode</h1>
> -
> -    <p>
> -      When it is invoked in the most ordinary way, <code>ovn-nbctl</code>
> -      connects to an OVSDB server that hosts the northbound database, retrieves
> -      a partial copy of the database that is complete enough to do its work,
> -      sends a transaction request to the server, and receives and processes the
> -      server's reply.  In common interactive use, this is fine, but if the
> -      database is large, the step in which <code>ovn-nbctl</code> retrieves a
> -      partial copy of the database can take a long time, which yields poor
> -      performance overall.
> -    </p>
> -
> -    <p>
> -      To improve performance in such a case, <code>ovn-nbctl</code> offers a
> -      "daemon mode," in which the user first starts <code>ovn-nbctl</code>
> -      running in the background and afterward uses the daemon to execute
> -      operations.  Over several <code>ovn-nbctl</code> command invocations,
> -      this performs better overall because it retrieves a copy of the database
> -      only once at the beginning, not once per program run.
> -    </p>
> -
> +    <h2>Database Commands</h2>
>       <p>
> -      Use the <code>--detach</code> option to start an <code>ovn-nbctl</code>
> -      daemon.  With this option, <code>ovn-nbctl</code> prints the name of a
> -      control socket to stdout.  The client should save this name in
> -      environment variable <env>OVN_NB_DAEMON</env>.  Under the Bourne shell
> -      this might be done like this:
> +      These commands query and modify the contents of <code>ovsdb</code>
> +      tables.  They are a slight abstraction of the <code>ovsdb</code>
> +      interface and as such they operate at a lower level than other
> +      <code>ovn-nbctl</code> commands.
>       </p>
>   
> -    <pre fixed="yes">
> -      export OVN_NB_DAEMON=$(ovn-nbctl --pidfile --detach)
> -    </pre>
> -
> -    <p>
> -      When <env>OVN_NB_DAEMON</env> is set, <code>ovn-nbctl</code>
> -      automatically and transparently uses the daemon to execute its commands.
> -    </p>
> +    <p><var>Identifying Tables, Records, and Columns</var></p>
>   
>       <p>
> -      When the daemon is no longer needed, kill it and unset the environment
> -      variable, e.g.:
> +      Each of these commands has a <var>table</var> parameter to identify a
> +      table within the database.  Many of them also take a <var>record</var>
> +      parameter that identifies a particular record within a table.  The
> +      <var>record</var> parameter may be the UUID for a record, which may be
> +      abbreviated to its first 4 (or more) hex digits, as long as that is
> +      unique.  Many tables offer additional ways to identify records.  Some
> +      commands also take <var>column</var> parameters that identify a
> +      particular field within the records in a table.
>       </p>
>   
> -    <pre fixed="yes">
> -      kill $(cat $OVN_RUNDIR/ovn-nbctl.pid)
> -      unset OVN_NB_DAEMON
> -    </pre>
> -
>       <p>
> -      When using daemon mode, an alternative to the OVN_NB_DAEMON environment
> -      variable is to specify a path for the Unix socket. When starting the
> -      ovn-nbctl daemon, specify the <code>-u</code> option with a full path to
> -      the location of the socket file. Here is an exmple:
> +      For a list of tables and their columns, see <code>ovn-nb</code>(5) or
> +      see the table listing from the <code>--help</code> option.
>       </p>
>   
> -    <pre fixed="yes">
> -      ovn-nbctl --detach -u /tmp/mysock.ctl
> -    </pre>
> -
>       <p>
> -      Then to connect to the running daemon, use the <code>-u</code> option
> -      with the full path to the socket created when the daemon was started:
> -    </p>
> -
> -    <pre fixed="yes">
> -      ovn-nbctl -u /tmp/mysock.ctl show
> -    </pre>
> -
> -    <p>
> -      Daemon mode is experimental.
> +      Record names must be specified in full and with correct capitalization,
> +      except that UUIDs may be abbreviated to their first 4 (or more) hex
> +      digits, as long as that is unique within the table.  Names of tables and
> +      columns are not case-sensitive, and <code>-</code> and <code>_</code> are
> +      treated interchangeably.  Unique abbreviations of table and column names
> +      are acceptable, e.g. <code>d</code> or <code>dhcp</code> is sufficient
> +      to identify the <code>DHCP_Options</code> table.
>       </p>
>   
> -    <h2>Daemon Commands</h2>
> +    <xi:include href="lib/db-ctl-base.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
>   
> -    <p>
> -      Daemon mode is internally implemented using the same mechanism used by
> -      <code>ovs-appctl</code>.  One may also use <code>ovs-appctl</code>
> -      directly with the following commands:
> -    </p>
> +    <h1>Environment</h1>
>   
>       <dl>
> -      <dt>
> -        <code>run</code> [<var>options</var>] <var>command</var>
> -        [<var>arg</var>...] [<code>--</code> [<var>options</var>]
> -        <var>command</var> [<var>arg</var>...] ...]
> -      </dt>
> +      <dt><env>OVN_NB_DAEMON</env></dt>
>         <dd>
> -        Instructs the daemon process to run one or more <code>ovn-nbctl</code>
> -        commands described above and reply with the results of running these
> -        commands. Accepts the <code>--no-wait</code>, <code>--wait</code>,
> -        <code>--timeout</code>, <code>--dry-run</code>, <code>--oneline</code>,
> -        and the options described under <code>Table Formatting Options</code>
> -        in addition to the the command-specific options.
> +        If set, this should name the Unix domain socket for an
> +        <code>ovn-nbctl</code> server process.  See <code>Daemon Mode</code>,
> +        above, for more information.
>         </dd>
>   
> -      <dt><code>exit</code></dt>
> -      <dd>Causes <code>ovn-nbctl</code> to gracefully terminate.</dd>
> -    </dl>
> -
> -    <h1>Options</h1>
> -
> -    <dl>
> -      <dt><code>--no-wait</code> | <code>--wait=none</code></dt>
> -      <dt><code>--wait=sb</code></dt>
> -      <dt><code>--wait=hv</code></dt>
> -
> +      <dt><env>OVN_NBCTL_OPTIONS</env></dt>
>         <dd>
> -        <p>
> -          These options control whether and how <code>ovn-nbctl</code> waits
> -          for the OVN system to become up-to-date with changes made in an
> -          <code>ovn-nbctl</code> invocation.
> -        </p>
> -
> -        <p>
> -          By default, or if <code>--no-wait</code> or <code>--wait=none</code>,
> -          <code>ovn-nbctl</code> exits immediately after confirming that
> -          changes have been committed to the northbound database, without
> -          waiting.
> -        </p>
> -
> -        <p>
> -          With <code>--wait=sb</code>, before <code>ovn-nbctl</code> exits, it
> -          waits for <code>ovn-northd</code> to bring the southbound database
> -          up-to-date with the northbound database updates.
> -        </p>
> -
> -        <p>
> -          With <code>--wait=hv</code>, before <code>ovn-nbctl</code> exits, it
> -          additionally waits for all OVN chassis (hypervisors and gateways) to
> -          become up-to-date with the northbound database updates.  (This can
> -          become an indefinite wait if any chassis is malfunctioning.)
> -        </p>
> -
> -        <p>
> -          Ordinarily, <code>--wait=sb</code> or <code>--wait=hv</code> only
> -          waits for changes by the current <code>ovn-nbctl</code> invocation to
> -          take effect.  This means that, if none of the commands supplied to
> -          <code>ovn-nbctl</code> change the database, then the command does not
> -          wait at all.  Use the <code>sync</code> command to override this
> -          behavior.
> -        </p>
> +        If set, a set of options for <code>ovn-nbctl</code> to apply
> +        automatically, in the same form as on the command line.
>         </dd>
>   
> -    <dt><code>--print-wait-time</code></dt>
> -    <dd>
> -      When <code>--wait</code> is specified, the option
> -      <code>--print-wait-time</code> can be used to print the time spent on
> -      waiting, depending on the value specified in <code> --wait</code> option.
> -      If <code>--wait=sb</code> is specified, it prints "ovn-northd delay
> -      before processing", which is the time between the Northbound DB update by
> -      the command and the moment when <code> ovn-northd</code> starts
> -      processing the update, and "ovn-northd completion", which is the time
> -      between the Northbound DB update and the moment when
> -      <code>ovn-northd</code> completes the Southbound DB updating
> -      successfully. If <code>--wait=hv</code> is specified, in addition to the
> -      above information, it also prints "ovn-controller(s) completion", which
> -      is the time between the Northbound DB update and the moment when the
> -      slowest hypervisor finishes processing the update.
> -    </dd>
> -
> -    <dt><code>--db</code> <var>database</var></dt>
> -    <dd>
> -      The OVSDB database remote to contact.  If the <env>OVN_NB_DB</env>
> -      environment variable is set, its value is used as the default.
> -      Otherwise, the default is <code>unix:@RUNDIR@/ovnnb_db.sock</code>, but this
> -      default is unlikely to be useful outside of single-machine OVN test
> -      environments.
> -    </dd>
> -
> -    <dt><code>--leader-only</code></dt>
> -    <dt><code>--no-leader-only</code></dt>
> -    <dd>
> -      By default, or with <code>--leader-only</code>, when the database server
> -      is a clustered database, <code>ovn-nbctl</code> will avoid servers other
> -      than the cluster leader.  This ensures that any data that
> -      <code>ovn-nbctl</code> reads and reports is up-to-date.  With
> -      <code>--no-leader-only</code>, <code>ovn-nbctl</code> will use any server
> -      in the cluster, which means that for read-only transactions it can report
> -      and act on stale data (transactions that modify the database are always
> -      serialized even with <code>--no-leader-only</code>).  Refer to
> -      <code>Understanding Cluster Consistency</code> in <code>ovsdb</code>(7)
> -      for more information.
> -    </dd>
> -
> -    <dt><code>--shuffle-remotes</code></dt>
> -    <dt><code>--no-shuffle-remotes</code></dt>
> -    <dd>
> -      By default, or with <code>--shuffle-remotes</code>, when there are
> -      multiple remotes specified in the OVSDB connection string specified by
> -      <code>--db</code> or the <env>OVN_NB_DB</env> environment variable,
> -      the order of the remotes will be shuffled before the client tries to
> -      connect.  The remotes will be shuffled only once to a new order before
> -      the first connection attempt.  The following retries, if any, will
> -      follow the same new order.  The default behavior is to make sure
> -      clients of a clustered database can distribute evenly to all memembers
> -      of the cluster.  With <code>--no-shuffle-remotes</code>,
> -      <code>ovn-nbctl</code> will use the original order specified in the
> -      connection string to connect.  This allows user to specify the
> -      preferred order, which is particularly useful for testing.
> -    </dd>
> -
> -    <dt><code>OVN_NBCTL_OPTIONS</code></dt>
> -    <dd>
> -        <p>
> -          User can set one or more <env>OVN_NBCTL_OPTIONS</env> options in
> -          environment variable. Under the Bourne shell this might be
> -          done like this:
> -        </p>
> -
> -        <pre fixed="yes">
> -          OVN_NBCTL_OPTIONS="--db=unix:nb1.ovsdb --no-leader-only"
> -        </pre>
> -
> -        <p>
> -          When <env>OVN_NBCTL_OPTIONS</env> is set, <code>ovn-nbctl</code>
> -          automatically and transparently uses the environment variable to
> -          execute its commands. However user can still over-ride environment
> -          options by passing different in cli.
> -        </p>
> -
> -        <p>
> -          When the environment variable is no longer needed, unset it, e.g.:
> -        </p>
> -
> -        <pre fixed="yes">
> -          unset OVN_NBCTL_OPTIONS
> -        </pre>
> -    </dd>
> +      <dt><env>OVN_NB_DB</env></dt>
> +      <dd>
> +        If set, the default database to contact when the <code>--db</code>
> +        option is not used.
> +      </dd>
>       </dl>
>   
> -    <h2>Daemon Options</h2>
> -    <xi:include href="lib/daemon.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
> -
> -    <h1>Logging options</h1>
> -    <xi:include href="lib/vlog.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
> -
> -    <h1>Table Formatting Options</h1>
> -    These options control the format of output from the <code>list</code> and
> -    <code>find</code> commands.
> -    <xi:include href="lib/table.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
> -
> -    <h2>PKI Options</h2>
> -    <p>
> -      PKI configuration is required to use SSL for the connection to the
> -      database.
> -    </p>
> -    <xi:include href="lib/ssl.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
> -    <xi:include href="lib/ssl-bootstrap.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
> +    <h1>Exit Status</h1>
> +    <dl>
> +      <dt>0</dt>
> +      <dd>Successful program execution.</dd>
>   
> -    <h2>Other Options</h2>
> +      <dt>1</dt>
> +      <dd>Usage, syntax, or network error.</dd>
> +    </dl>
>   
> -    <xi:include href="lib/common.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
> +    <h1>See Also</h1>
> +    <code>ovn-nb</code>(5).

Should ovn-appctl also be in the "See Also" section since it is 
mentioned by name earlier?

>   
>   </manpage>
>

On Mon, Mar 29, 2021 at 07:42:47PM -0400, Mark Michelson wrote:
> On 3/25/21 7:26 PM, Ben Pfaff wrote:
> > This rearranges the manpage into a more logical order, documents some
> > options that weren't documented, adds some sections such as
> > Environment and Exit Status that a manpage should have, puts the
> > headings at reasonable levels instead of all at the top level, and adds
> > a little more explanatory text in a few places.
> > 
> > Signed-off-by: Ben Pfaff <blp@ovn.org>

...

> > +    <p>
> > +      Daemon mode is experimental.
> > +    </p>
> 
> Is daemon mode really still experimental? For ovn-nbctl, it's been around a
> couple of years at this point and was used heavily by ovn-kubernetes with no
> issues.

OK, I'll add a patch.

> > +
> > +    <h3>Daemon Commands</h3>
> > +
> > +    <p>
> > +      Daemon mode is internally implemented using the same mechanism used by
> > +      <code>ovs-appctl</code>.  One may also use <code>ovs-appctl</code>
> 
> I believe you should replace "ovs-appctl" above with "ovn-appctl". I'm aware
> this was just copied from text that had previously been in the manpage, but
> the original text was wrong as well.
> 
> This same mention is made in patch 3 for the ovn-sbctl daemon and should
> probably be amended there too.

I was not previously aware that ovn-appctl existed.  Looking at a diff
between ovs-appctl.c and ovn-appctl.c didn't clear up why it exists.
They are exactly the same except for naming and changing the default
target from ovs-vswitchd to ovn-controller.  They will work exactly as
well for the purpose of this manpage.

So, OK, I made those changes.  Can't hurt.

> Should ovn-appctl also be in the "See Also" section since it is mentioned by
> name earlier?

OK, done for v2.

Thank you!

On 3/30/21 6:18 PM, Ben Pfaff wrote:
> On Mon, Mar 29, 2021 at 07:42:47PM -0400, Mark Michelson wrote:
>> On 3/25/21 7:26 PM, Ben Pfaff wrote:
>>> This rearranges the manpage into a more logical order, documents some
>>> options that weren't documented, adds some sections such as
>>> Environment and Exit Status that a manpage should have, puts the
>>> headings at reasonable levels instead of all at the top level, and adds
>>> a little more explanatory text in a few places.
>>>
>>> Signed-off-by: Ben Pfaff <blp@ovn.org>
> 
> ...
> 
>>> +    <p>
>>> +      Daemon mode is experimental.
>>> +    </p>
>>
>> Is daemon mode really still experimental? For ovn-nbctl, it's been around a
>> couple of years at this point and was used heavily by ovn-kubernetes with no
>> issues.
> 
> OK, I'll add a patch.
> 
>>> +
>>> +    <h3>Daemon Commands</h3>
>>> +
>>> +    <p>
>>> +      Daemon mode is internally implemented using the same mechanism used by
>>> +      <code>ovs-appctl</code>.  One may also use <code>ovs-appctl</code>
>>
>> I believe you should replace "ovs-appctl" above with "ovn-appctl". I'm aware
>> this was just copied from text that had previously been in the manpage, but
>> the original text was wrong as well.
>>
>> This same mention is made in patch 3 for the ovn-sbctl daemon and should
>> probably be amended there too.
> 
> I was not previously aware that ovn-appctl existed.  Looking at a diff
> between ovs-appctl.c and ovn-appctl.c didn't clear up why it exists.
> They are exactly the same except for naming and changing the default
> target from ovs-vswitchd to ovn-controller.  They will work exactly as
> well for the purpose of this manpage.

The other big difference is that ovn-appctl by default looks in 
ovn_rundir() instead of ovs_rundir() by default when searching for the 
target.

> 
> So, OK, I made those changes.  Can't hurt.
> 
>> Should ovn-appctl also be in the "See Also" section since it is mentioned by
>> name earlier?
> 
> OK, done for v2.
> 
> Thank you!
> 

And thanks for the improvements!