[ovs-dev] [PATCH ovn 1/3] ovn-nbctl: Improve manpage.
Mark Michelson
mmichels at redhat.com
Mon Mar 29 23:42:47 UTC 2021
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 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>
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>
>
More information about the dev
mailing list