X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=utilities%2Fovs-vsctl.8.in;h=64255b578350d5ed38fe02150a13f3506af9dfd5;hb=ea131871e4c8793ff90f60cfb5f45947d6a2c10b;hp=3b35179ab55e80ed2e6e2ad2b24dd1cf4363029f;hpb=71abd20a1789fb10a7a346ca1a029a76e3f10041;p=openvswitch

diff --git a/utilities/ovs-vsctl.8.in b/utilities/ovs-vsctl.8.in
index 3b35179a..64255b57 100644
--- a/utilities/ovs-vsctl.8.in
+++ b/utilities/ovs-vsctl.8.in
@@ -153,6 +153,9 @@ 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,
@@ -169,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
@@ -180,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
@@ -258,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
@@ -275,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
@@ -321,8 +324,13 @@ output.
 .SS "OpenFlow Controller Connectivity"
 .
 \fBovs\-vswitchd\fR can perform all configured bridging and switching
-locally, or it can be configured to connect a given bridge to one or
-more external OpenFlow controllers, such as NOX.
+locally, or it can be configured to communicate with one or more
+external OpenFlow controllers.  The switch is typically configured to
+connect to a primary controller that takes charge of the bridge's flow
+table to implement a network policy.  In addition, the switch can be
+configured to listen to connections from service controllers.  Service
+controllers are typically used for occasional support and maintenance,
+e.g. with \fBovs\-ofctl\fR.
 .
 .IP "\fBget\-controller\fR \fIbridge\fR"
 Prints the configured controller target.
@@ -336,6 +344,7 @@ use any of the following forms:
 .
 .RS
 .so lib/vconn-active.man
+.so lib/vconn-passive.man
 .RE
 .
 .ST "Controller Failure Settings"
@@ -350,7 +359,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,
@@ -478,14 +487,11 @@ A bridge port.  Records may be identified by port name.
 A network device attached to a port.  Records may be identified by
 name.
 .IP "\fBQoS\fR"
-Quality-of-service configuration for an \fBInterface\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.
-.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.
+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.
@@ -594,6 +600,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
@@ -637,10 +648,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
@@ -668,6 +700,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
@@ -720,10 +755,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
@@ -744,7 +779,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
@@ -754,19 +790,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.
+Monitor connectivity to a remote maintenance point 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"
+.B "ovs\-vsctl set Interface eth0 cfm_mpid=1"
 .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"
 .SS "NetFlow"
 .PP
 Configure bridge \fBbr0\fR to send NetFlow records to UDP port 5566 on
@@ -781,10 +811,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
@@ -795,10 +825,28 @@ 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 \fBbr0\fR, which also destroys the sFlow record
+(since it is now unreferenced):
+.IP
+.B "ovs\-vsctl \-\- clear Bridge br0 sflow"
+.SS "802.1D Spanning Tree Protocol (STP)"
+.PP
+Configure bridge \fBbr0\fR to participate in an 802.1D spanning tree:
+.IP
+.B "ovs\-vsctl set Bridge br0 stp_enable=true"
+.PP
+Set the bridge priority of \fBbr0\fR to 0x7800:
+.IP
+.B "ovs\-vsctl set Bridge br0 other_config:stp-priority=0x7800"
+.PP
+Set the path cost of port \fBeth0\fR to 10:
+.IP
+.B "ovs\-vsctl set Port eth0 other_config:stp-path-cost=10"
+.PP
+Deconfigure STP from above:
 .IP
-.B "ovs\-vsctl \-\- destroy sFlow br0 \-\- clear Bridge br0 sflow"
+.B "ovs\-vsctl clear Bridge br0 stp_enable"
+.PP
 .SH "EXIT STATUS"
 .IP "0"
 Successful program execution.