datapath: Check that netdev vport is fully initialized.

[openvswitch] / utilities / ovs-vsctl.8.in

diff --git a/utilities/ovs-vsctl.8.in b/utilities/ovs-vsctl.8.in
index 5e3ab39ee4d1fd64a3ee3780eb6e3bf0c753e3da..fcfec024654661a70c024c5fd37a8e8dec1fe2b9 100644 (file)
--- a/utilities/ovs-vsctl.8.in
+++ b/utilities/ovs-vsctl.8.in
@@ -104,7 +104,7 @@ By default, \fBovs\-vsctl\fR logs its arguments and the details of any
 changes that it makes to the system log.  This option disables this
 logging.
 .IP
 changes that it makes to the system log.  This option disables this
 logging.
 .IP

-This option is equivalent to \fB\-\-verbose=vvsctl:syslog:warn\fR.
+This option is equivalent to \fB\-\-verbose=vsctl:syslog:warn\fR.

 .
 .IP "\fB\-\-oneline\fR"
 Modifies the output format so that the output for each command is printed
 .
 .IP "\fB\-\-oneline\fR"
 Modifies the output format so that the output for each command is printed


@@ -112,6 +112,9 @@ 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.
 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
+\fBlist\fR or \fBfind\fR commands; see \fBTable Formatting Options\fR
+below.

 .
 .IP "\fB\-\-dry\-run\fR"
 Prevents \fBovs\-vsctl\fR from actually modifying the database.
 .
 .IP "\fB\-\-dry\-run\fR"
 Prevents \fBovs\-vsctl\fR from actually modifying the database.


@@ -125,6 +128,11 @@ to approximately \fIsecs\fR seconds.  If the timeout expires,
 would normally happen only if the database cannot be contacted, or if
 the system is overloaded.)
 .
 would normally happen only if the database cannot be contacted, or if
 the system is overloaded.)
 .

+.SS "Table Formatting Options"
+These options control the format of output from the \fBlist\fR and
+\fBfind\fR commands.
+.so lib/table.man
+.

 .SS "Public Key Infrastructure Options"
 .so lib/ssl.man
 .so lib/ssl-bootstrap.man
 .SS "Public Key Infrastructure Options"
 .so lib/ssl.man
 .so lib/ssl-bootstrap.man


@@ -362,11 +370,11 @@ Sets the configured failure mode.
 .
 .SS "Manager Connectivity"
 .
 .
 .SS "Manager Connectivity"
 .

-These commands manipulate the \fBmanagers\fR and \fBmanager_options\fR columns
-in the \fBOpen_vSwitch\fR table and rows in the \fBManagers\fR table.  When
-\fBovsdb\-server\fR is configured to use those rows and columns for OVSDB
-connections, as described in \fBINSTALL.Linux\fR and in the startup scripts
-provided with Open vSwitch, this allows the administrator to use
+These commands manipulate the \fBmanager_options\fR column in the
+\fBOpen_vSwitch\fR table and rows in the \fBManagers\fR table.  When
+\fBovsdb\-server\fR is configured to use the \fBmanager_options\fR column for
+OVSDB connections (as described in \fBINSTALL.Linux\fR and in the startup
+scripts provided with Open vSwitch), this allows the administrator to use

 \fBovs\-vsctl\fR to configure database connections.
 .
 .IP "\fBget\-manager\fR"
 \fBovs\-vsctl\fR to configure database connections.
 .
 .IP "\fBget\-manager\fR"


@@ -388,17 +396,17 @@ use any of the following forms:
 When \fBovs\-vswitchd\fR is configured to connect over SSL for management or
 controller connectivity, the following parameters are required:
 .TP
 When \fBovs\-vswitchd\fR is configured to connect over SSL for management or
 controller connectivity, the following parameters are required:
 .TP

-\fBprivate\-key\fR
+\fIprivate-key\fR

 Specifies a PEM file containing the private key used as the virtual
 switch's identity for SSL connections to the controller.
 .TP
 Specifies a PEM file containing the private key used as the virtual
 switch's identity for SSL connections to the controller.
 .TP

-\fBcertificate\fR
+\fIcertificate\fR

 Specifies a PEM file containing a certificate, signed by the
 certificate authority (CA) used by the controller and manager, that
 certifies the virtual switch's private key, identifying a trustworthy
 switch.
 .TP
 Specifies a PEM file containing a certificate, signed by the
 certificate authority (CA) used by the controller and manager, that
 certifies the virtual switch's private key, identifying a trustworthy
 switch.
 .TP

-\fBca\-cert\fR
+\fIca-cert\fR

 Specifies a PEM file containing the CA certificate used to verify that
 the virtual switch is connected to a trustworthy controller.
 .PP
 Specifies a PEM file containing the CA certificate used to verify that
 the virtual switch is connected to a trustworthy controller.
 .PP


@@ -421,7 +429,8 @@ below.
 .ST "CA Certificate Bootstrap"
 .PP
 Ordinarily, all of the files named in the SSL configuration must exist
 .ST "CA Certificate Bootstrap"
 .PP
 Ordinarily, all of the files named in the SSL configuration must exist

-when \fBovs\-vswitchd\fR starts.  However, if the \fB\-\-bootstrap\fR 
+when \fBovs\-vswitchd\fR starts.  However, if the \fIca-cert\fR file
+does not exist and the \fB\-\-bootstrap\fR

 option is given, then \fBovs\-vswitchd\fR will attempt to obtain the
 CA certificate from the controller on its first SSL connection and
 save it to the named PEM file.  If it is successful, it will
 option is given, then \fBovs\-vswitchd\fR will attempt to obtain the
 CA certificate from the controller on its first SSL connection and
 save it to the named PEM file.  If it is successful, it will


@@ -468,6 +477,17 @@ A bridge port.  Records may be identified by port name.
 .IP "\fBInterface\fR"
 A network device attached to a port.  Records may be identified by
 name.
 .IP "\fBInterface\fR"
 A network device attached to a port.  Records may be identified by
 name.

+.IP "\fBQoS\fR"
+Quality-of-service configuration for a \fBPort\fR.  Records may be
+identified by port name.
+.IP "\fBQueue\fR"
+Configuration for one queue within a \fBQoS\fR configuration.  Records
+may only be identified by UUID.
+.IP "\fBMonitor\fR"
+Connectivity Monitoring attached to an \fBInterface\fR.  Records may be
+identified by \fBInterface\fR name.
+.IP "\fBMaintenance_Point\fR"
+Maintenance Point managed by a \fBMonitor\fR.

 .IP "\fBMirror\fR"
 A port mirroring configuration attached to a bridge.  Records may be
 identified by mirror name.
 .IP "\fBMirror\fR"
 A port mirroring configuration attached to a bridge.  Records may be
 identified by mirror name.


@@ -487,11 +507,6 @@ specifying \fB.\fR as the record name.
 .IP "\fBsFlow\fR"
 An sFlow configuration attached to a bridge.  Records may be
 identified by bridge name.
 .IP "\fBsFlow\fR"
 An sFlow configuration attached to a bridge.  Records may be
 identified by bridge name.

-.IP "\fBMonitor\fR"
-Connectivity Monitoring attached to an interface.  Records may be
-identified by interface name.
-.IP "\fBMaintenance_Point\fR"
-Maintenance Point managed by a Monitor.

 .PP
 Record names must be specified in full and with correct
 capitalization.  Names of tables and columns are not case-sensitive,
 .PP
 Record names must be specified in full and with correct
 capitalization.  Names of tables and columns are not case-sensitive,


@@ -543,10 +558,27 @@ as \fB{}\fR, and curly braces may be optionally enclose non-empty maps
 as well.
 .
 .ST "Database Command Syntax"
 as well.
 .
 .ST "Database Command Syntax"

-.IP "\fBlist \fItable \fR[\fIrecord\fR]..."
-List the values of all columns of each specified \fIrecord\fR.  If no
+.IP "[\fB\-\-columns=\fIcolumn\fR[\fB,\fIcolumn\fR]...] \fBlist \fItable \fR[\fIrecord\fR]..."
+Lists the data in each specified \fIrecord\fR.  If no

 records are specified, lists all the records in \fItable\fR.
 .IP
 records are specified, lists all the records in \fItable\fR.
 .IP

+If \fB\-\-columns\fR is specified, only the requested columns are
+listed, in the specified order.  Otherwise, all columns are listed, in
+alphabetical order by column name.
+.
+.IP "[\fB\-\-columns=\fIcolumn\fR[\fB,\fIcolumn\fR]...] \fBfind \fItable \fR[\fIcolumn\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR]..."
+Lists the data in each record in \fItable\fR whose \fIcolumn\fR equals
+\fIvalue\fR or, if \fIkey\fR is specified, whose \fIcolumn\fR contains
+a \fIkey\fR with the specified \fIvalue\fR.  Any of the operators
+\fB!=\fR, \fB<\fR, \fB>\fR, \fB<=\fR, or \fB>=\fR may be substituted
+for \fB=\fR to test for inequality, less than, greater than, less than
+or equal to, or greater than or equal to, respectively.  (Don't forget
+to escape \fB<\fR or \fB>\fR from interpretation by the shell.)
+.IP
+If \fB\-\-columns\fR is specified, only the requested columns are
+listed, in the specified order.  Otherwise all columns are listed, in
+alphabetical order by column name.
+.IP

 The UUIDs shown for rows created in the same \fBovs\-vsctl\fR
 invocation will be wrong.
 .
 The UUIDs shown for rows created in the same \fBovs\-vsctl\fR
 invocation will be wrong.
 .


@@ -564,6 +596,11 @@ For a map column, without \fB\-\-if\-exists\fR it is an error if
 If \fB@\fIname\fR is specified, then the UUID for \fIrecord\fR may be
 referred to by that name later in the same \fBovs\-vsctl\fR
 invocation in contexts where a UUID is expected.
 If \fB@\fIname\fR is specified, then the UUID for \fIrecord\fR may be
 referred to by that name later in the same \fBovs\-vsctl\fR
 invocation in contexts where a UUID is expected.

+.IP
+Both \fB\-\-id\fR and the \fIcolumn\fR arguments are optional, but
+usually at least one or the other should be specified.  If both are
+omitted, then \fBget\fR has no effect except to verify that
+\fIrecord\fR exists in \fItable\fR.

 .
 .IP "\fBset \fItable record column\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR..."
 Sets the value of each specified \fIcolumn\fR in the given
 .
 .IP "\fBset \fItable record column\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR..."
 Sets the value of each specified \fIcolumn\fR in the given


@@ -607,10 +644,31 @@ If \fB@\fIname\fR is specified, then the UUID for the new row may be
 referred to by that name elsewhere in the same \fBovs\-vsctl\fR
 invocation in contexts where a UUID is expected.  Such references may
 precede or follow the \fBcreate\fR command.
 referred to by that name elsewhere in the same \fBovs\-vsctl\fR
 invocation in contexts where a UUID is expected.  Such references may
 precede or follow the \fBcreate\fR command.

+.IP
+Records in the Open vSwitch database are significant only when they
+can be reached directly or indirectly from the \fBOpen_vSwitch\fR
+table.  Except for records in the \fBQoS\fR or \fBQueue\fR tables,
+records that are not reachable from the \fBOpen_vSwitch\fR table are
+automatically deleted from the database.  This deletion happens
+immediately, without waiting for additional \fBovs\-vsctl\fR commands
+or other database activity.  Thus, a \fBcreate\fR command must
+generally be accompanied by additional commands \fIwithin the same
+\fBovs\-vsctl\fI invocation\fR to add a chain of references to the
+newly created record from the top-level \fBOpen_vSwitch\fR record.
+The \fBEXAMPLES\fR section gives some examples that show how to do
+this.

 .
 .IP "\fR[\fB\-\-if\-exists\fR] \fBdestroy \fItable record\fR..."
 Deletes each specified \fIrecord\fR from \fItable\fR.  Unless
 \fB\-\-if\-exists\fR is specified, each \fIrecord\fRs must exist.
 .
 .IP "\fR[\fB\-\-if\-exists\fR] \fBdestroy \fItable record\fR..."
 Deletes each specified \fIrecord\fR from \fItable\fR.  Unless
 \fB\-\-if\-exists\fR is specified, each \fIrecord\fRs must exist.

+.IP
+The \fBdestroy\fR command is only useful for records in the \fBQoS\fR
+or \fBQueue\fR tables.  Records in other tables are automatically
+deleted from the database when they become unreachable from the
+\fBOpen_vSwitch\fR table.  This means that deleting the last reference
+to a record is sufficient for deleting the record itself.  For records
+in these tables, \fBdestroy\fR is silently ignored.  See the
+\fBEXAMPLES\fR section below for more information.

 .
 .IP "\fBwait\-until \fItable record \fR[\fIcolumn\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR]..."
 Waits until \fItable\fR contains a record named \fIrecord\fR whose
 .
 .IP "\fBwait\-until \fItable record \fR[\fIcolumn\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR]..."
 Waits until \fItable\fR contains a record named \fIrecord\fR whose


@@ -690,10 +748,10 @@ ignored):
 .IP
 .B "\-\- \-\-id=@m create Mirror name=mymirror select-dst-port=@eth0,@eth1 select-src-port=@eth0,@eth1 output-port=@eth2"
 .PP
 .IP
 .B "\-\- \-\-id=@m create Mirror name=mymirror select-dst-port=@eth0,@eth1 select-src-port=@eth0,@eth1 output-port=@eth2"
 .PP

-Remove the mirror created above from \fBbr0\fR and destroy the Mirror
-record (to avoid having an unreferenced record in the database):
+Remove the mirror created above from \fBbr0\fR, which also destroys
+the Mirror record (since it is now unreferenced):

 .IP
 .IP

-.B "ovs\-vsctl destroy Mirror mymirror \-\- clear Bridge br0 mirrors"
+.B "remove Bridge br0 mirrors mymirror"

 .SS "Quality of Service (QoS)"
 .PP
 Create a \fBlinux\-htb\fR QoS record that points to a few queues and
 .SS "Quality of Service (QoS)"
 .PP
 Create a \fBlinux\-htb\fR QoS record that points to a few queues and


@@ -714,7 +772,8 @@ Deconfigure the QoS record above from \fBeth1\fR only:
 .B "ovs\-vsctl clear Port eth1 qos"
 .PP
 To deconfigure the QoS record from both \fBeth0\fR and \fBeth1\fR and
 .B "ovs\-vsctl clear Port eth1 qos"
 .PP
 To deconfigure the QoS record from both \fBeth0\fR and \fBeth1\fR and

-then delete the QoS record:
+then delete the QoS record (which must be done explicitly because
+unreferenced QoS records are not automatically destroyed):

 .IP
 .B "ovs\-vsctl \-\- destroy QoS eth0 \-\- clear Port eth0 qos \-\- clear Port eth1 qos"
 .PP
 .IP
 .B "ovs\-vsctl \-\- destroy QoS eth0 \-\- clear Port eth0 qos \-\- clear Port eth1 qos"
 .PP


@@ -751,10 +810,10 @@ instead use an active timeout of 60 seconds:
 .IP
 .B "ovs\-vsctl set NetFlow br0 active_timeout=60"
 .PP
 .IP
 .B "ovs\-vsctl set NetFlow br0 active_timeout=60"
 .PP

-Deconfigure the NetFlow settings from \fBbr0\fR and delete the NetFlow
-record (to avoid having an unreferenced record in the database):
+Deconfigure the NetFlow settings from \fBbr0\fR, which also destroys
+the NetFlow record (since it is now unreferenced):

 .IP
 .IP

-.B "ovs\-vsctl destroy NetFlow br0 \-\- clear Bridge br0 netflow"
+.B "ovs\-vsctl clear Bridge br0 netflow"

 .SS "sFlow"
 .PP
 Configure bridge \fBbr0\fR to send sFlow records to a collector on
 .SS "sFlow"
 .PP
 Configure bridge \fBbr0\fR to send sFlow records to a collector on


@@ -765,10 +824,10 @@ with specific sampling parameters:
 .IP
 .B "\-\- set Bridge br0 sflow=@s"
 .PP
 .IP
 .B "\-\- set Bridge br0 sflow=@s"
 .PP

-Deconfigure sFlow from br0 and destroy the sFlow record (to avoid
-having an unreferenced record in the database):
+Deconfigure sFlow from br0, which also destroys the sFlow record
+(since it is now unreferenced):

 .IP
 .IP

-.B "ovs\-vsctl \-\- destroy sFlow br0 \-\- clear Bridge br0 sflow"
+.B "ovs\-vsctl \-\- clear Bridge br0 sflow"

 .SH "EXIT STATUS"
 .IP "0"
 Successful program execution.
 .SH "EXIT STATUS"
 .IP "0"
 Successful program execution.


@@ -781,4 +840,3 @@ bridge that does not exist.
 .
 .BR ovsdb\-server (1),
 .BR ovs\-vswitchd (8).
 .
 .BR ovsdb\-server (1),
 .BR ovs\-vswitchd (8).

-\