X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=utilities%2Fovs-vsctl.8.in;h=309ea0af7dc2e66c70aa609c02d9f5f812ea7174;hb=09eda55c4a3ef0215fea797c73cc2ba5778af8ca;hp=281756c90c885131e351452276beed23bef58960;hpb=bad973d7ae0ca5273b46c79b4bd9007e607f277c;p=openvswitch diff --git a/utilities/ovs-vsctl.8.in b/utilities/ovs-vsctl.8.in index 281756c9..309ea0af 100644 --- 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 -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 @@ -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. +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. @@ -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.) . +.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 @@ -145,13 +153,16 @@ Any successful \fBovs\-vsctl\fR command automatically initializes the Open vSwitch database if it is empty. This command is provided to initialize the database without executing any other command. . +.IP "\fBshow\fR" +Prints a brief overview of the database contents. +. .IP "\fBemer\-reset\fR" Reset the configuration into a clean state. It deconfigures OpenFlow controllers, OVSDB servers, and SSL, and deletes port mirroring, -NetFlow, and sFlow configuration. This command also removes all -\fBother\-config\fR keys from all database records, except that -\fBother\-config:hwaddr\fR is preserved if it is present in a Bridge -record. Other networking configuration is left as-is. +\fBfail_mode\fR, NetFlow, and sFlow configuration. This command also +removes all \fBother\-config\fR keys from all database records, except +that \fBother\-config:hwaddr\fR is preserved if it is present in a +Bridge record. Other networking configuration is left as-is. . .SS "Bridge Commands" These commands examine and manipulate Open vSwitch bridges. @@ -161,8 +172,8 @@ Creates a new bridge named \fIbridge\fR. Initially the bridge will have no ports (other than \fIbridge\fR itself). .IP Without \fB\-\-may\-exist\fR, attempting to create a bridge that -exists is an error. With \fB\-\-may\-exist\fR, \fIbridge\fR may -already exist (but it must be a real bridge, not a VLAN bridge). +exists is an error. With \fB\-\-may\-exist\fR, this command does +nothing if \fIbridge\fR already exists as a real bridge. . .IP "[\fB\-\-may\-exist\fR] \fBadd\-br \fIbridge parent vlan\fR" Creates a ``fake bridge'' named \fIbridge\fR within the existing Open @@ -172,9 +183,9 @@ itself be a fake bridge. The new fake bridge will be on 802.1Q VLAN \fIbridge\fR will have no ports (other than \fIbridge\fR itself). .IP Without \fB\-\-may\-exist\fR, attempting to create a bridge that -exists is an error. With \fB\-\-may\-exist\fR, \fIbridge\fR may -already exist (but it must have the specified \fIvlan\fR and -\fIparent\fR). +exists is an error. With \fB\-\-may\-exist\fR, this command does +nothing if \fIbridge\fR already exists as a VLAN bridge under +\fIparent\fR for \fIvlan\fR. . .IP "[\fB\-\-if\-exists\fR] \fBdel\-br \fIbridge\fR" Deletes \fIbridge\fR and all of its ports. If \fIbridge\fR is a real @@ -250,8 +261,8 @@ port for VLAN 9. The syntax is the same as that for the \fBset\fR command (see \fBDatabase Commands\fR below). .IP Without \fB\-\-may\-exist\fR, attempting to create a port that exists -is an error. With \fB\-\-may\-exist\fR, \fIport\fR may already exist -(but it must be on \fIbridge\fR and not be a bonded port). +is an error. With \fB\-\-may\-exist\fR, this command does nothing if +\fIport\fR already exists on \fIbridge\fR and is not a bonded port. . .IP "[\fB\-\-fake\-iface\fR] \fBadd\-bond \fIbridge port iface\fR\&... [\fIcolumn\fR[\fB:\fIkey\fR]\fR=\fIvalue\fR]\&...\fR" Creates on \fIbridge\fR a new port named \fIport\fR that bonds @@ -267,9 +278,9 @@ created. This should only be used for compatibility with legacy software that requires it. .IP Without \fB\-\-may\-exist\fR, attempting to create a port that exists -is an error. With \fB\-\-may\-exist\fR, \fIport\fR may already exist -(but it must be on \fIbridge\fR and bond together exactly the -specified interface). +is an error. With \fB\-\-may\-exist\fR, this command does nothing if +\fIport\fR already exists on \fIbridge\fR and bonds together exactly +the specified interfaces. . .IP "[\fB\-\-if\-exists\fR] \fBdel\-port \fR[\fIbridge\fR] \fIport\fR" Deletes \fIport\fR. If \fIbridge\fR is omitted, \fIport\fR is removed @@ -360,21 +371,45 @@ Deletes the configured failure mode. .IP "\fBset\-fail\-mode\fR \fIbridge\fR \fBstandalone\fR|\fBsecure\fR" Sets the configured failure mode. . +.SS "Manager Connectivity" +. +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" +Prints the configured manager(s). +. +.IP "\fBdel\-manager\fR" +Deletes the configured manager(s). +. +.IP "\fBset\-manager\fR \fItarget\fR\&..." +Sets the configured manager target or targets. Each \fItarget\fR may +use any of the following forms: +. +.RS +.so ovsdb/remote-active.man +.so ovsdb/remote-passive.man +.RE +. .SS "SSL Configuration" 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 -\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 -\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 @@ -397,7 +432,8 @@ below. .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 @@ -444,12 +480,21 @@ 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 "\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 "\fBMirror\fR" A port mirroring configuration attached to a bridge. Records may be identified by mirror name. .IP "\fBController\fR" Configuration for an OpenFlow controller. A controller attached to a particular bridge may be identified by the bridge's name. +.IP "\fBManager\fR" +Configuration for an OVSDB connection. Records may be identified +by target (e.g. \fBtcp:1.2.3.4\fR). .IP "\fBNetFlow\fR" A NetFlow configuration attached to a bridge. Records may be identified by bridge name. @@ -511,10 +556,27 @@ as \fB{}\fR, and curly braces may be optionally enclose non-empty maps 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 +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. . @@ -532,6 +594,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. +.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 @@ -575,10 +642,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. +.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 +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 @@ -606,6 +694,9 @@ initially connects to the database. Consider specifying \fB\-\-timeout=0\fR along with \fB\-\-wait\-until\fR, to prevent \fBovs\-vsctl\fR from terminating after waiting only at most 5 seconds. +.IP "\fBcomment \fR[\fIarg\fR]..." +This command has no effect on behavior, but any database log record +created by the command will include the command and its arguments. .SH "EXAMPLES" Create a new bridge named br0 and add port eth0 to it: .IP @@ -658,10 +749,10 @@ ignored): .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 -.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 @@ -682,7 +773,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 -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 @@ -690,6 +782,15 @@ then delete the QoS record: database. To delete them, use "\fBovs\-vsctl list Queue\fR" to find their UUIDs, then "\fBovs\-vsctl destroy Queue \fIuuid1\fR \fIuuid2\fR" to destroy each of them.) +.SS "Connectivity Monitoring" +.PP +Monitor connectivity to a remote maintenance point on eth0. +.IP +.B "ovs\-vsctl set Interface eth0 cfm_mpid=1 cfm_remote_mpid=2" +.PP +Deconfigure connectivity monitoring from above: +.IP +.B "ovs\-vsctl clear Interface eth0 cfm_mpid cfm_remote_mpid" .SS "NetFlow" .PP Configure bridge \fBbr0\fR to send NetFlow records to UDP port 5566 on @@ -704,10 +805,10 @@ instead use an active timeout of 60 seconds: .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 -.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 @@ -718,10 +819,10 @@ with specific sampling parameters: .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 -.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. @@ -734,4 +835,3 @@ bridge that does not exist. . .BR ovsdb\-server (1), .BR ovs\-vswitchd (8). -\