removed warnings

[sliver-openvswitch.git] / utilities / ovs-vsctl.8.in

diff --git a/utilities/ovs-vsctl.8.in b/utilities/ovs-vsctl.8.in
index 309ea0a..57f76d5 100644 (file)
--- a/utilities/ovs-vsctl.8.in
+++ b/utilities/ovs-vsctl.8.in
@@ -69,7 +69,8 @@ When such a ``fake bridge'' is active, \fBovs\-vsctl\fR will treat it
 much like a bridge separate from its ``parent bridge,'' but the actual
 implementation in Open vSwitch uses only a single bridge, with ports on
 the fake bridge assigned the implicit VLAN of the fake bridge of which
 much like a bridge separate from its ``parent bridge,'' but the actual
 implementation in Open vSwitch uses only a single bridge, with ports on
 the fake bridge assigned the implicit VLAN of the fake bridge of which

-they are members.
+they are members.  (A fake bridge for VLAN 0 receives packets that
+have no 802.1Q tag or a tag with VLAN 0.)

 .
 .SH OPTIONS
 .
 .
 .SH OPTIONS
 .


@@ -179,7 +180,7 @@ nothing if \fIbridge\fR already exists as a real bridge.
 Creates a ``fake bridge'' named \fIbridge\fR within the existing Open
 vSwitch bridge \fIparent\fR, which must already exist and must not
 itself be a fake bridge.  The new fake bridge will be on 802.1Q VLAN
 Creates a ``fake bridge'' named \fIbridge\fR within the existing Open
 vSwitch bridge \fIparent\fR, which must already exist and must not
 itself be a fake bridge.  The new fake bridge will be on 802.1Q VLAN

-\fIvlan\fR, which must be an integer between 1 and 4095.  Initially
+\fIvlan\fR, which must be an integer between 0 and 4095.  Initially

 \fIbridge\fR will have no ports (other than \fIbridge\fR itself).
 .IP
 Without \fB\-\-may\-exist\fR, attempting to create a bridge that
 \fIbridge\fR will have no ports (other than \fIbridge\fR itself).
 .IP
 Without \fB\-\-may\-exist\fR, attempting to create a bridge that


@@ -324,8 +325,13 @@ output.
 .SS "OpenFlow Controller Connectivity"
 .
 \fBovs\-vswitchd\fR can perform all configured bridging and switching
 .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.
 .
 .IP "\fBget\-controller\fR \fIbridge\fR"
 Prints the configured controller target.


@@ -339,6 +345,7 @@ use any of the following forms:
 .
 .RS
 .so lib/vconn-active.man
 .
 .RS
 .so lib/vconn-active.man

+.so lib/vconn-passive.man

 .RE
 .
 .ST "Controller Failure Settings"
 .RE
 .
 .ST "Controller Failure Settings"


@@ -353,7 +360,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
 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,
 \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,


@@ -480,6 +487,9 @@ 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 "\fBInterface\fR"
 A network device attached to a port.  Records may be identified by
 name.

+.IP "\fBFlow_Table\fR"
+Configuration for a particular OpenFlow flow table.  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 "\fBQoS\fR"
 Quality-of-service configuration for a \fBPort\fR.  Records may be
 identified by port name.


@@ -552,8 +562,10 @@ follow the syntax for the column's key type and value type,
 respectively.  When multiple pairs are present (separated by spaces or
 a comma), duplicate keys are not allowed, and again the order is not
 important.  Duplicate values are allowed.  An empty map is represented
 respectively.  When multiple pairs are present (separated by spaces or
 a comma), duplicate keys are not allowed, and again the order is not
 important.  Duplicate values are allowed.  An empty map is represented

-as \fB{}\fR, and curly braces may be optionally enclose non-empty maps
-as well.
+as \fB{}\fR.  Curly braces may optionally enclose non-empty maps as
+well (but use quotes to prevent the shell from expanding
+\fBother-config={0=x,1=y}\fR into \fBother-config=0=x
+other-config=1=y\fR, which may not have the desired effect).

 .
 .ST "Database Command Syntax"
 .IP "[\fB\-\-columns=\fIcolumn\fR[\fB,\fIcolumn\fR]...] \fBlist \fItable \fR[\fIrecord\fR]..."
 .
 .ST "Database Command Syntax"
 .IP "[\fB\-\-columns=\fIcolumn\fR[\fB,\fIcolumn\fR]...] \fBlist \fItable \fR[\fIrecord\fR]..."


@@ -567,11 +579,56 @@ 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
 .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.)
+a \fIkey\fR with the specified \fIvalue\fR.  The following operators
+may be used where \fB=\fR is written in the syntax summary:
+.RS
+.IP "\fB= != < > <= >=\fR"
+Selects records in which \fIcolumn\fR[\fB:\fIkey\fR] equals, does not
+equal, is less than, is greater than, is less than or equal to, or is
+greater than or equal to \fIvalue\fR, respectively.
+.IP
+Consider \fIcolumn\fR[\fB:\fIkey\fR] and \fIvalue\fR as sets of
+elements.  Identical sets are considered equal.  Otherwise, if the
+sets have different numbers of elements, then the set with more
+elements is considered to be larger.  Otherwise, consider a element
+from each set pairwise, in increasing order within each set.  The
+first pair that differs determines the result.  (For a column that
+contains key-value pairs, first all the keys are compared, and values
+are considered only if the two sets contain identical keys.)
+.IP "\fB{=} {!=}\fR"
+Test for set equality or inequality, respectively.
+.IP "\fB{<=}\fR"
+Selects records in which \fIcolumn\fR[\fB:\fIkey\fR] is a subset of
+\fIvalue\fR.  For example, \fBflood-vlans{<=}1,2\fR selects records in
+which the \fBflood-vlans\fR column is the empty set or contains 1 or 2
+or both.
+.IP "\fB{<}\fR"
+Selects records in which \fIcolumn\fR[\fB:\fIkey\fR] is a proper
+subset of \fIvalue\fR.  For example, \fBflood-vlans{<}1,2\fR selects
+records in which the \fBflood-vlans\fR column is the empty set or
+contains 1 or 2 but not both.
+.IP "\fB{>=} {>}\fR"
+Same as \fB{<=}\fR and \fB{<}\fR, respectively, except that the
+relationship is reversed.  For example, \fBflood-vlans{>=}1,2\fR
+selects records in which the \fBflood-vlans\fR column contains both 1
+and 2.
+.RE
+.IP
+For arithmetic operators (\fB= != < > <= >=\fR), when \fIkey\fR is
+specified but a particular record's \fIcolumn\fR does not contain
+\fIkey\fR, the record is always omitted from the results.  Thus, the
+condition \fBother-config:mtu!=1500\fR matches records that have a
+\fBmtu\fR key whose value is not 1500, but not those that lack an
+\fBmtu\fR key.
+.IP
+For the set operators, when \fIkey\fR is specified but a particular
+record's \fIcolumn\fR does not contain \fIkey\fR, the comparison is
+done against an empty set.  Thus, the condition
+\fBother-config:mtu{!=}1500\fR matches records that have a \fBmtu\fR
+key whose value is not 1500 and those that lack an \fBmtu\fR key.
+.IP
+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
 .IP
 If \fB\-\-columns\fR is specified, only the requested columns are
 listed, in the specified order.  Otherwise all columns are listed, in


@@ -732,6 +789,12 @@ access port for VLAN 10, and configure it with an IP address:
 .IP
 .B "ifconfig vlan10 192.168.0.123"
 .
 .IP
 .B "ifconfig vlan10 192.168.0.123"
 .

+.PP
+Add a GRE tunnel port \fBgre0\fR to remote IP address 1.2.3.4 to
+bridge \fBbr0\fR:
+.IP
+.B "ovs\-vsctl add\-port br0 gre0 \-\- set Interface gre0 type=gre options:remote_ip=1.2.3.4"
+.

 .SS "Port Mirroring"
 .PP
 Mirror all packets received or sent on \fBeth0\fR or \fBeth1\fR onto
 .SS "Port Mirroring"
 .PP
 Mirror all packets received or sent on \fBeth0\fR or \fBeth1\fR onto


@@ -786,11 +849,11 @@ their UUIDs, then "\fBovs\-vsctl destroy Queue \fIuuid1\fR
 .PP
 Monitor connectivity to a remote maintenance point on eth0.
 .IP
 .PP
 Monitor connectivity to a remote maintenance point on eth0.
 .IP

-.B "ovs\-vsctl set Interface eth0 cfm_mpid=1 cfm_remote_mpid=2"
+.B "ovs\-vsctl set Interface eth0 cfm_mpid=1"

 .PP
 Deconfigure connectivity monitoring from above:
 .IP
 .PP
 Deconfigure connectivity monitoring from above:
 .IP

-.B "ovs\-vsctl clear Interface eth0 cfm_mpid cfm_remote_mpid"
+.B "ovs\-vsctl clear Interface eth0 cfm_mpid"

 .SS "NetFlow"
 .PP
 Configure bridge \fBbr0\fR to send NetFlow records to UDP port 5566 on
 .SS "NetFlow"
 .PP
 Configure bridge \fBbr0\fR to send NetFlow records to UDP port 5566 on


@@ -819,10 +882,28 @@ with specific sampling parameters:
 .IP
 .B "\-\- set Bridge br0 sflow=@s"
 .PP
 .IP
 .B "\-\- set Bridge br0 sflow=@s"
 .PP

-Deconfigure sFlow from br0, which also destroys the sFlow record
+Deconfigure sFlow from \fBbr0\fR, which also destroys the sFlow record

 (since it is now unreferenced):
 .IP
 .B "ovs\-vsctl \-\- clear Bridge br0 sflow"
 (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 clear Bridge br0 stp_enable"
+.PP

 .SH "EXIT STATUS"
 .IP "0"
 Successful program execution.
 .SH "EXIT STATUS"
 .IP "0"
 Successful program execution.