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

Ben Pfaff blp at ovn.org
Thu Mar 25 23:26:06 UTC 2021


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 at 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>
+
+    <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>
+      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).
 
 </manpage>
-- 
2.29.2



More information about the dev mailing list