@@ -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>
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(-)