X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=utilities%2Fovs-vsctl.8.in;h=890e144784eb5bce97e7d81e9ce6c6b065172fd9;hb=6c88547dd0f75a29e6d1c0cd3c76d9678fa4752f;hp=aacb19a7cdb4aadde5189df2eacdb919575f3af9;hpb=b31bcf60cf4fbabca0182196c97b3004e42f53e5;p=sliver-openvswitch.git diff --git a/utilities/ovs-vsctl.8.in b/utilities/ovs-vsctl.8.in index aacb19a7c..890e14478 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 @@ -342,7 +353,7 @@ If the value is \fBstandalone\fR, or if neither of these settings is set, \fBovs\-vswitchd\fR will take over responsibility for setting up flows when no message has been received from the controller for three -times the inactivity probe interval (xxx needs to be exposed). In this mode, +times the inactivity probe interval. In this mode, \fBovs\-vswitchd\fR causes the datapath to act like an ordinary MAC-learning switch. \fBovs\-vswitchd\fR will continue to retry connecting to the controller in the background and, when the connection succeeds, @@ -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,6 +480,12 @@ 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. @@ -463,11 +505,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 "\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, @@ -519,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. . @@ -540,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 @@ -583,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 @@ -614,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 @@ -666,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 @@ -690,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 @@ -700,19 +784,13 @@ their UUIDs, then "\fBovs\-vsctl destroy Queue \fIuuid1\fR \fIuuid2\fR" to destroy each of them.) .SS "Connectivity Monitoring" .PP -Create a Monitor which manages a couple of remote Maintenance Points on eth0. -.IP -.B "ovs\-vsctl \-\- set Interface eth0 Monitor=@newmon \(rs" -.IP -.B "\-\- \-\-id=@newmon create Monitor mpid=1 remote_mps=@mp2,@mp3 \(rs" -.IP -.B "\-\- \-\-id=@mp2 create Maintenance_Point mpid=2 \(rs" +Monitor connectivity to a remote maintenance point on eth0. .IP -.B "\-\- \-\-id=@mp3 create Maintenance_Point mpid=3" +.B "ovs\-vsctl set Interface eth0 cfm_mpid=1 cfm_remote_mpid=2" .PP -Deconfigure the Monitor record from above: +Deconfigure connectivity monitoring from above: .IP -.B "ovs\-vsctl clear Interface eth0 Monitor" +.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 @@ -727,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 @@ -741,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. @@ -757,4 +835,3 @@ bridge that does not exist. . .BR ovsdb\-server (1), .BR ovs\-vswitchd (8). -\