X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=utilities%2Fovs-vsctl.8.in;h=309ea0af7dc2e66c70aa609c02d9f5f812ea7174;hb=1b3a91b5a35e6ffdc85ec373896532d266a6b795;hp=408507997cd899c221a40220e812b5c63b76e05f;hpb=a946ed39420c86cd3cf98436f9b1005c85f9bb31;p=openvswitch diff --git a/utilities/ovs-vsctl.8.in b/utilities/ovs-vsctl.8.in index 40850799..309ea0af 100644 --- a/utilities/ovs-vsctl.8.in +++ b/utilities/ovs-vsctl.8.in @@ -11,7 +11,10 @@ . RE .. .TH ovs\-vsctl 8 "November 2009" "Open vSwitch" "Open vSwitch Manual" +.\" This program's name: .ds PN ovs\-vsctl +.\" SSL peer program's name: +.ds SN ovsdb\-server . .SH NAME ovs\-vsctl \- utility for querying and configuring \fBovs\-vswitchd\fR @@ -101,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 @@ -109,20 +112,31 @@ 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. . .IP "\fB\-t \fIsecs\fR" .IQ "\fB\-\-timeout=\fIsecs\fR" -Limits runtime to approximately \fIsecs\fR seconds. A value of -zero will cause \fBovs\-vsctl\fR to wait forever. If the timeout expires, -\fBovs\-vsctl\fR will exit with a \fBSIGALRM\fR signal. If this option is -not used, \fBovs\-vsctl\fR uses a timeout of five seconds. -(A timeout would normally happen only if the database cannot be contacted.) +By default, or with a \fIsecs\fR of \fB0\fR, \fBovs\-vsctl\fR waits +forever for a response from the database. This option limits runtime +to approximately \fIsecs\fR seconds. If the timeout expires, +\fBovs\-vsctl\fR will exit with a \fBSIGALRM\fR signal. (A timeout +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 +.so lib/ssl-peer-ca-cert.man .so lib/vlog.man . .SH COMMANDS @@ -139,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. @@ -155,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 @@ -166,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 @@ -244,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 @@ -261,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 @@ -354,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 @@ -391,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 @@ -438,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. @@ -484,7 +535,7 @@ pair of double quotes (\fB""\fR). .IP "UUID" Either a universally unique identifier in the style of RFC 4122, e.g. \fBf81d4fae\-7dec\-11d0\-a765\-00a0c91e6bf6\fR, or an \fB@\fIname\fR -defined by the \fBcreate\fR command within the same \fBovs\-vsctl\fR +defined by a \fBget\fR or \fBcreate\fR command within the same \fBovs\-vsctl\fR invocation. .PP Multiple values in a single column may be separated by spaces or a @@ -505,14 +556,31 @@ 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. . -.IP "[\fB\-\-if\-exists\fR] \fBget \fItable record column\fR[\fB:\fIkey\fR]..." +.IP "[\fB\-\-id=@\fIname\fR] [\fB\-\-if\-exists\fR] \fBget \fItable record \fR[\fIcolumn\fR[\fB:\fIkey\fR]]..." Prints the value of each specified \fIcolumn\fR in the given \fIrecord\fR in \fItable\fR. For map columns, a \fIkey\fR may optionally be specified, in which case the value associated with @@ -522,6 +590,15 @@ For a map column, without \fB\-\-if\-exists\fR it is an error if \fIkey\fR does not exist; with it, a blank line is printed. If \fIcolumn\fR is not a map column or if \fIkey\fR is not specified, \fB\-\-if\-exists\fR has no effect. +.IP +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 @@ -565,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 @@ -596,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 @@ -621,7 +722,107 @@ point to a new \fBQoS\fR record, which in turn points with its queue 0 to a new \fBQueue\fR record: .IP .B "ovs\-vsctl \-\- set port eth0 qos=@newqos \-\- \-\-id=@newqos create qos type=linux\-htb other\-config:max\-rate=1000000 queues:0=@newqueue \-\- \-\-id=@newqueue create queue other\-config:min\-rate=1000000 other\-config:max\-rate=1000000" +.SH "CONFIGURATION COOKBOOK" +.SS "Port Configuration" +.PP +Add an ``internal port'' \fBvlan10\fR to bridge \fBbr0\fR as a VLAN +access port for VLAN 10, and configure it with an IP address: +.IP +.B "ovs\-vsctl add\-port br0 vlan10 tag=10 \-\- set Interface vlan10 type=internal" +.IP +.B "ifconfig vlan10 192.168.0.123" . +.SS "Port Mirroring" +.PP +Mirror all packets received or sent on \fBeth0\fR or \fBeth1\fR onto +\fBeth2\fR, assuming that all of those ports exist on bridge \fBbr0\fR +(as a side-effect this causes any packets received on \fBeth2\fR to be +ignored): +.IP +.B "ovs\-vsctl \-\- set Bridge br0 mirrors=@m \(rs" +.IP +.B "\-\- \-\-id=@eth0 get Port eth0 \(rs" +.IP +.B "\-\- \-\-id=@eth1 get Port eth1 \(rs" +.IP +.B "\-\- \-\-id=@eth2 get Port eth2 \(rs" +.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, which also destroys +the Mirror record (since it is now unreferenced): +.IP +.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 +use it on \fBeth0\fR and \fBeth1\fR: +.IP +.B "ovs\-vsctl \-\- set Port eth0 qos=@newqos \(rs" +.IP +.B "\-\- set Port eth1 qos=@newqos \(rs" +.IP +.B "\-\- \-\-id=@newqos create QoS type=linux\-htb other\-config:max\-rate=1000000000 queues=0=@q0,1=@q1 \(rs" +.IP +.B "\-\- \-\-id=@q0 create Queue other\-config:min\-rate=100000000 other\-config:max\-rate=100000000 \(rs" +.IP +.B "\-\- \-\-id=@q1 create Queue other\-config:min\-rate=500000000" +.PP +Deconfigure the QoS record above from \fBeth1\fR only: +.IP +.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 (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 +(This command will leave two unreferenced Queue records in the +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 +host 192.168.0.34, with an active timeout of 30 seconds: +.IP +.B "ovs\-vsctl \-\- set Bridge br0 netflow=@nf \(rs" +.IP +.B "\-\- \-\-id=@nf create NetFlow targets=\(rs\(dq192.168.0.34:5566\(rs\(dq active\-timeout=30" +.PP +Update the NetFlow configuration created by the previous command to +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, which also destroys +the NetFlow record (since it is now unreferenced): +.IP +.B "ovs\-vsctl clear Bridge br0 netflow" +.SS "sFlow" +.PP +Configure bridge \fBbr0\fR to send sFlow records to a collector on +10.0.0.1 at port 6343, using \fBeth1\fR\'s IP address as the source, +with specific sampling parameters: +.IP +.B "ovs\-vsctl \-\- \-\-id=@s create sFlow agent=eth1 target=\(rs\(dq10.0.0.1:6343\(rs\(dq header=128 sampling=64 polling=10 \(rs" +.IP +.B "\-\- set Bridge br0 sflow=@s" +.PP +Deconfigure sFlow from br0, which also destroys the sFlow record +(since it is now unreferenced): +.IP +.B "ovs\-vsctl \-\- clear Bridge br0 sflow" .SH "EXIT STATUS" .IP "0" Successful program execution. @@ -634,4 +835,3 @@ bridge that does not exist. . .BR ovsdb\-server (1), .BR ovs\-vswitchd (8). -\