ovs-vsctl: Make "ovs-vsctl get <table> <record> _uuid" work.

[openvswitch] / utilities / ovs-ofctl.8.in

diff --git a/utilities/ovs-ofctl.8.in b/utilities/ovs-ofctl.8.in
index 29e5bc76e5cb7cbf1d716a5f422bc60cea6e3cc5..8d48d98a323e64e76f10dbd0e413b4a96ffdebd4 100644 (file)
--- a/utilities/ovs-ofctl.8.in
+++ b/utilities/ovs-ofctl.8.in
@@ -143,8 +143,32 @@ omitted and the \fB--strict\fR option is not used, all flows in the
 switch's tables are removed.  See \fBFlow Syntax\fR, below, for the 
 syntax of \fIflows\fR.
 .
 switch's tables are removed.  See \fBFlow Syntax\fR, below, for the 
 syntax of \fIflows\fR.
 .

-.TP
-\fBmonitor \fIswitch\fR [\fImiss-len\fR]
+.IP "\fBsnoop \fIswitch\fR"
+Connects to \fIswitch\fR and prints to the console all OpenFlow
+messages received.  Unlike other \fBovs\-ofctl\fR commands, if
+\fIswitch\fR is the name of a bridge, then the \fBsnoop\fR command
+connects to a Unix domain socket named
+\fB@RUNDIR@/\fIbridge\fB.snoop\fR.  \fBovs\-vswitchd\fR listens on
+such a socket for each bridge and sends to it all of the OpenFlow
+messages sent to or received from its configured OpenFlow controller.
+Thus, this command can be used to view OpenFlow protocol activity
+between a switch and its controller.
+.IP
+When a switch has more than one controller configured, only the
+traffic to and from a single controller is output.  If none of the
+controllers is configured as a master or a slave (using a Nicira
+extension to OpenFlow), then a controller is chosen arbitrarily among
+them.  If there is a master controller, it is chosen; otherwise, if
+there are any controllers that are not masters or slaves, one is
+chosen arbitrarily; otherwise, a slave controller is chosen
+arbitrarily.  This choice is made once at connection time and does not
+change as controllers reconfigure their roles.
+.IP
+If a switch has no controller configured, or if
+the configured controller is disconnected, no traffic is sent, so
+monitoring will not show any traffic.
+.
+.IQ "\fBmonitor \fIswitch\fR [\fImiss-len\fR]"

 Connects to \fIswitch\fR and prints to the console all OpenFlow
 messages received.  Usually, \fIswitch\fR should specify a connection
 named on \fBovs\-openflowd\fR(8)'s \fB-l\fR or \fB--listen\fR command line
 Connects to \fIswitch\fR and prints to the console all OpenFlow
 messages received.  Usually, \fIswitch\fR should specify a connection
 named on \fBovs\-openflowd\fR(8)'s \fB-l\fR or \fB--listen\fR command line


@@ -152,10 +176,11 @@ option.
 .IP
 If \fImiss-len\fR is provided, \fBovs\-ofctl\fR sends an OpenFlow ``set
 configuration'' message at connection setup time that requests
 .IP
 If \fImiss-len\fR is provided, \fBovs\-ofctl\fR sends an OpenFlow ``set
 configuration'' message at connection setup time that requests

-\fImiss-len\fR bytes of each packet that misses the flow table.  The
-OpenFlow reference implementation does not send these messages to the
+\fImiss-len\fR bytes of each packet that misses the flow table.  Open vSwitch
+does not send these and other asynchronous messages to an

 \fBovs\-ofctl monitor\fR client connection unless a nonzero value is
 \fBovs\-ofctl monitor\fR client connection unless a nonzero value is

-specified on this argument.
+specified on this argument.  (Thus, if \fImiss\-len\fR is not
+specified, very little traffic will ordinarily be printed.)

 .IP
 This command may be useful for debugging switch or controller
 implementations.
 .IP
 This command may be useful for debugging switch or controller
 implementations.


@@ -220,11 +245,12 @@ Matches IEEE 802.1q Priority Code Point (PCP) \fIpriority\fR, which is
 specified as a value between 0 and 7, inclusive.  A higher value
 indicates a higher frame priority level.
 .
 specified as a value between 0 and 7, inclusive.  A higher value
 indicates a higher frame priority level.
 .

-.IP \fBdl_src=\fImac\fR
-Matches Ethernet source address \fImac\fR, which is specified as 6 pairs 
-of hexadecimal digits delimited by colons (e.g. \fB00:0A:E4:25:6B:B0\fR).
-.IP \fBdl_dst=\fImac\fR
-Matches Ethernet destination address \fImac\fR.
+.IP \fBdl_src=\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fR
+.IQ \fBdl_dst=\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fR
+Matches an Ethernet source (or destination) address specified as 6
+pairs of hexadecimal digits delimited by colons
+(e.g. \fB00:0A:E4:25:6B:B0\fR).
+.

 .IP \fBdl_type=\fIethertype\fR
 Matches Ethernet protocol type \fIethertype\fR, which is specified as an
 integer between 0 and 65535, inclusive, either in decimal or as a 
 .IP \fBdl_type=\fIethertype\fR
 Matches Ethernet protocol type \fIethertype\fR, which is specified as an
 integer between 0 and 65535, inclusive, either in decimal or as a 


@@ -232,37 +258,65 @@ hexadecimal number prefixed by \fB0x\fR (e.g. \fB0x0806\fR to match ARP
 packets).
 .
 .IP \fBnw_src=\fIip\fR[\fB/\fInetmask\fR]
 packets).
 .
 .IP \fBnw_src=\fIip\fR[\fB/\fInetmask\fR]

-Matches IPv4 source address \fIip\fR, which may be specified as an
-IP address or host name (e.g. \fB192.168.1.1\fR or
-\fBwww.example.com\fR).  The optional \fInetmask\fR allows restricting a
-match to an IPv4 address prefix.  The netmask may be specified as a dotted 
-quad (e.g. \fB192.168.1.0/255.255.255.0\fR) or as a CIDR block 
+.IQ \fBnw_dst=\fIip\fR[\fB/\fInetmask\fR]
+When \fBdl_type\fR is 0x0800 (possibly via shorthand, e.g. \fBip\fR
+or \fBtcp\fR), matches IPv4 source (or destination) address \fIip\fR,
+which may be specified as an IP address or host name
+(e.g. \fB192.168.1.1\fR or \fBwww.example.com\fR).  The optional
+\fInetmask\fR allows restricting a match to an IPv4 address prefix.
+The netmask may be specified as a dotted quad
+(e.g. \fB192.168.1.0/255.255.255.0\fR) or as a CIDR block

 (e.g. \fB192.168.1.0/24\fR).
 (e.g. \fB192.168.1.0/24\fR).

+.IP
+When \fBdl_type=0x0806\fR or \fBarp\fR is specified, matches the
+\fBar_spa\fR or \fBar_tpa\fR field, respectively, in ARP packets for
+IPv4 and Ethernet.
+.IP
+When \fBdl_type\fR is wildcarded or set to a value other than 0x0800
+or 0x0806, the values of \fBnw_src\fR and \fBnw_dst\fR are silently
+ignored.

 .
 .

-.IP \fBnw_dst=\fIip\fR[\fB/\fInetmask\fR]
-Matches IPv4 destination address \fIip\fR.

 .IP \fBnw_proto=\fIproto\fR
 .IP \fBnw_proto=\fIproto\fR

+When \fBip\fR or \fBdl_type=0x0800\fR is specified, matches IP
+protocol type \fIproto\fR, which is specified as a decimal number
+between 0 and 255, inclusive (e.g. 6 to match TCP packets).
+.IP
+When \fBarp\fR or \fBdl_type=0x0806\fR is specified, matches the lower
+8 bits of the ARP opcode.  ARP opcodes greater than 255 are treated as
+0.
+.IP
+When \fBdl_type\fR is wildcarded or set to a value other than 0x0800
+or 0x0806, the value of \fBnw_proto\fR is silently ignored.

 .
 .

-Matches IP protocol type \fIproto\fR, which is specified as a decimal 
-number between 0 and 255, inclusive (e.g. 6 to match TCP packets).

 .IP \fBnw_tos=\fItos\fR
 Matches IP ToS/DSCP field \fItos\fR, which is specified as a decimal 
 number between 0 and 255, inclusive.  Note that the two lower reserved
 bits are ignored for matching purposes.
 .IP \fBnw_tos=\fItos\fR
 Matches IP ToS/DSCP field \fItos\fR, which is specified as a decimal 
 number between 0 and 255, inclusive.  Note that the two lower reserved
 bits are ignored for matching purposes.

+.IP
+The value of \fBnw_proto\fR is silently ignored unless
+\fBdl_type=0x0800\fR, \fBip\fR, \fBicmp\fR, \fBtcp\fR, or \fBudp\fR is
+also specified.

 .
 .IP \fBtp_src=\fIport\fR
 .
 .IP \fBtp_src=\fIport\fR

-Matches UDP or TCP source port \fIport\fR, which is specified as a decimal 
-number between 0 and 65535, inclusive (e.g. 80 to match packets originating 
+.IQ \fBtp_dst=\fIport\fR
+When \fBdl_type\fR and \fBnw_proto\fR specify TCP or UDP, \fBtp_src\fR
+and \fBtp_dst\fR match the UDP or TCP source or destination port
+\fIport\fR, respectively. which is specified as a decimal number
+between 0 and 65535, inclusive (e.g. 80 to match packets originating

 from a HTTP server).
 from a HTTP server).

+.IP
+When \fBdl_type\fR and \fBnw_proto\fR take other values, the values of
+these settings are silently ignored.

 .
 .

-.IP \fBtp_dst=\fIport\fR
-Matches UDP or TCP destination port \fIport\fR.

 .IP \fBicmp_type=\fItype\fR
 .IP \fBicmp_type=\fItype\fR

+.IQ \fBicmp_code=\fIcode\fR
+When \fBdl_type\fR and \fBnw_proto\fR specify ICMP, \fItype\fR matches
+the ICMP type and \fIcode\fR matches the ICMP code.  Each is specified
+as a decimal number between 0 and 255, inclusive.
+.IP
+When \fBdl_type\fR and \fBnw_proto\fR take other values, the values of
+these settings are silently ignored.

 .
 .

-Matches ICMP message with \fItype\fR, which is specified as a decimal 
-number between 0 and 255, inclusive.
-.IP \fBicmp_code=\fIcode\fR
-Matches ICMP messages with \fIcode\fR.

 .PP
 The following shorthand notations are also available:
 .
 .PP
 The following shorthand notations are also available:
 .


@@ -282,7 +336,8 @@ Same as \fBdl_type=0x0800,nw_proto=17\fR.
 Same as \fBdl_type=0x0806\fR.
 .
 .PP
 Same as \fBdl_type=0x0806\fR.
 .
 .PP

-The \fBadd-flow\fR and \fBadd-flows\fR commands require an additional field:
+The \fBadd-flow\fR and \fBadd-flows\fR commands require an additional
+field, which must be the final field specified:

 .
 .IP \fBactions=\fR[\fItarget\fR][\fB,\fItarget\fR...]\fR
 Specifies a comma-separated list of actions to take on a packet when the 
 .
 .IP \fBactions=\fR[\fItarget\fR][\fB,\fItarget\fR...]\fR
 Specifies a comma-separated list of actions to take on a packet when the 


@@ -363,12 +418,39 @@ Sets the IP ToS/DSCP field to \fItos\fR.  Valid values are between 0 and
 modified.
 .
 .RE
 modified.
 .
 .RE

+.IP
+The following actions are Nicira vendor extensions that, as of this writing, are
+only known to be implemented by Open vSwitch:
+.
+.RS
+.
+.IP \fBresubmit\fB:\fIport\fR
+Re-searches the OpenFlow flow table with the \fBin_port\fR field
+replaced by \fIport\fR and executes the actions found, if any, in
+addition to any other actions in this flow entry.  Recursive
+\fBresubmit\fR actions are ignored.
+.
+.IP \fBset_tunnel\fB:\fIid\fR
+If outputting to a port that encapsulates the packet in a tunnel and supports
+an identifier (such as GRE), sets the identifier to \fBid\fR.
+.
+.RE

 .
 .IP
 (The OpenFlow protocol supports other actions that \fBovs\-ofctl\fR does
 not yet expose to the user.)
 .
 .PP
 .
 .IP
 (The OpenFlow protocol supports other actions that \fBovs\-ofctl\fR does
 not yet expose to the user.)
 .
 .PP

+The \fBadd\-flow\fR, \fBadd\-flows\fR, and \fBmod\-flows\fR commands
+support an additional optional field:
+.
+.IP \fBcookie=\fIvalue\fR
+.
+A cookie is an opaque identifier that can be associated with the flow.
+\fIvalue\fR can be any 64-bit number and need not be unique among
+flows.
+.
+.PP

 The \fBadd-flow\fR, \fBadd-flows\fR, and \fBdel-flows\fR commands
 support an additional optional field:
 .
 The \fBadd-flow\fR, \fBadd-flows\fR, and \fBdel-flows\fR commands
 support an additional optional field:
 .


@@ -449,6 +531,7 @@ described in \fBFlow Syntax\fR, above.
 \fB--strict\fR
 Uses strict matching when running flow modification commands.
 .
 \fB--strict\fR
 Uses strict matching when running flow modification commands.
 .

+.SS "Public Key Infrastructure Options"

 .so lib/ssl.man
 .so lib/vlog.man
 .so lib/common.man
 .so lib/ssl.man
 .so lib/vlog.man
 .so lib/common.man