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 <[email protected]> --- 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 03d47dba5b72..39f9381fdaae 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.31.1 _______________________________________________ dev mailing list [email protected] https://mail.openvswitch.org/mailman/listinfo/ovs-dev
