X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=utilities%2Fovs-vsctl.8.in;h=ee76b83215b7d867da88cb0f9a3904788603f1f1;hb=9cb8d24da006b562fecd17d34971822e3f6d1a78;hp=cfb911483b3a6d80134e2836fad0319783069d0d;hpb=aed133bf9bce8f35b666c3052907f525c803c83b;p=openvswitch diff --git a/utilities/ovs-vsctl.8.in b/utilities/ovs-vsctl.8.in index cfb91148..ee76b832 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 @@ -148,10 +156,10 @@ initialize the database without executing any other command. .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. @@ -360,21 +368,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 +429,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 +477,26 @@ 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 "\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 "\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 +558,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. . @@ -575,10 +639,30 @@ 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 +It is often unnecessary to specify explicit \fBdestroy\fR commands, +because (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 means that deleting the +last reference to a record is sufficient for deleting the record +itself. 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 @@ -631,7 +715,113 @@ 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 +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" +.IP +.B "\-\- \-\-id=@mp3 create Maintenance_Point mpid=3" +.PP +Deconfigure the Monitor record from above: +.IP +.B "ovs\-vsctl clear Interface eth0 Monitor" +.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. @@ -644,4 +834,3 @@ bridge that does not exist. . .BR ovsdb\-server (1), .BR ovs\-vswitchd (8). -\