unification of netdev&netdev_dev in pltap&tunnel
[sliver-openvswitch.git] / utilities / ovs-ofctl.8.in
index be71f18..061982b 100644 (file)
@@ -4,7 +4,7 @@
 .  ns
 .  IP "\\$1"
 ..
 .  ns
 .  IP "\\$1"
 ..
-.TH ovs\-ofctl 8 "January 2011" "Open vSwitch" "Open vSwitch Manual"
+.TH ovs\-ofctl 8 "@VERSION@" "Open vSwitch" "Open vSwitch Manual"
 .ds PN ovs\-ofctl
 .
 .SH NAME
 .ds PN ovs\-ofctl
 .
 .SH NAME
@@ -20,6 +20,7 @@ The
 program is a command line tool for monitoring and administering
 OpenFlow switches.  It can also show the current state of an OpenFlow
 switch, including features, configuration, and table entries.
 program is a command line tool for monitoring and administering
 OpenFlow switches.  It can also show the current state of an OpenFlow
 switch, including features, configuration, and table entries.
+It should work with any OpenFlow switch, not just Open vSwitch.
 .
 .SS "OpenFlow Switch Management Commands"
 .PP
 .
 .SS "OpenFlow Switch Management Commands"
 .PP
@@ -392,8 +393,8 @@ flows not in normal form.
 The following field assignments describe how a flow matches a packet.
 If any of these assignments is omitted from the flow syntax, the field
 is treated as a wildcard; thus, if all of them are omitted, the
 The following field assignments describe how a flow matches a packet.
 If any of these assignments is omitted from the flow syntax, the field
 is treated as a wildcard; thus, if all of them are omitted, the
-resulting flow matches all packets.  The string \fB*\fR or \fBANY\fR
-may be specified to explicitly mark any of these fields as a wildcard.  
+resulting flow matches all packets.  The string \fB*\fR may be specified
+to explicitly mark any of these fields as a wildcard.
 (\fB*\fR should be quoted to protect it from shell expansion.)
 .
 .IP \fBin_port=\fIport\fR
 (\fB*\fR should be quoted to protect it from shell expansion.)
 .
 .IP \fBin_port=\fIport\fR
@@ -468,8 +469,12 @@ 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
 \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 ignored
+When \fBdl_type=0x8035\fR or \fBrarp\fR is specified, matches the
+\fBar_spa\fR or \fBar_tpa\fR field, respectively, in RARP packets for
+IPv4 and Ethernet.
+.IP
+When \fBdl_type\fR is wildcarded or set to a value other than 0x0800,
+0x0806, or 0x8035, the values of \fBnw_src\fR and \fBnw_dst\fR are ignored
 (see \fBFlow Syntax\fR above).
 .
 .IP \fBnw_proto=\fIproto\fR
 (see \fBFlow Syntax\fR above).
 .
 .IP \fBnw_proto=\fIproto\fR
@@ -488,9 +493,13 @@ 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
 8 bits of the ARP opcode.  ARP opcodes greater than 255 are treated as
 0.
 .IP
+When \fBrarp\fR or \fBdl_type=0x8035\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,
 When \fBdl_type\fR is wildcarded or set to a value other than 0x0800,
-0x0806, or 0x86dd, the value of \fBnw_proto\fR is ignored (see \fBFlow
-Syntax\fR above).
+0x0806, 0x8035 or 0x86dd, the value of \fBnw_proto\fR is ignored (see
+\fBFlow Syntax\fR above).
 .
 .IP \fBnw_tos=\fItos\fR
 Matches IP ToS/DSCP or IPv6 traffic class field \fItos\fR, which is
 .
 .IP \fBnw_tos=\fItos\fR
 Matches IP ToS/DSCP or IPv6 traffic class field \fItos\fR, which is
@@ -645,6 +654,9 @@ Same as \fBdl_type=0x0800,nw_proto=17\fR.
 .IP \fBarp\fR
 Same as \fBdl_type=0x0806\fR.
 .
 .IP \fBarp\fR
 Same as \fBdl_type=0x0806\fR.
 .
+.IP \fBrarp\fR
+Same as \fBdl_type=0x8035\fR.
+.
 .PP
 The following field assignments require support for the NXM (Nicira
 Extended Match) extension to OpenFlow.  When one of these is specified,
 .PP
 The following field assignments require support for the NXM (Nicira
 Extended Match) extension to OpenFlow.  When one of these is specified,
@@ -712,9 +724,9 @@ command, above, for more details.
 .
 .IP \fBarp_sha=\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fR
 .IQ \fBarp_tha=\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fR
 .
 .IP \fBarp_sha=\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fR
 .IQ \fBarp_tha=\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fR
-When \fBdl_type\fR specifies ARP, \fBarp_sha\fR and \fBarp_tha\fR match
-the source and target hardware address, respectively.  An address is
-specified as 6 pairs of hexadecimal digits delimited by colons.
+When \fBdl_type\fR specifies either ARP or RARP, \fBarp_sha\fR and
+\fBarp_tha\fR match the source and target hardware address, respectively.  An
+address is specified as 6 pairs of hexadecimal digits delimited by colons.
 .
 .IP \fBipv6_src=\fIipv6\fR[\fB/\fInetmask\fR]
 .IQ \fBipv6_dst=\fIipv6\fR[\fB/\fInetmask\fR]
 .
 .IP \fBipv6_src=\fIipv6\fR[\fB/\fInetmask\fR]
 .IQ \fBipv6_dst=\fIipv6\fR[\fB/\fInetmask\fR]
@@ -763,6 +775,17 @@ if \fImask\fR is specified, then a 1-bit in \fImask\fR indicates that the
 corresponding bit in \fItunnel-id\fR must match exactly, and a 0-bit
 wildcards that bit.
 .
 corresponding bit in \fItunnel-id\fR must match exactly, and a 0-bit
 wildcards that bit.
 .
+.IP \fBtun_src=\fIip\fR[\fB/\fInetmask\fR]
+.IQ \fBtun_dst=\fIip\fR[\fB/\fInetmask\fR]
+Matches tunnel IPv4 source (or destination) address \fIip\fR. Only packets
+that arrive over a tunnel will have nonzero tunnel addresses.
+The address 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 a masked IPv4 address.
+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).
+.
 .IP "\fBreg\fIidx\fB=\fIvalue\fR[\fB/\fImask\fR]"
 Matches \fIvalue\fR either exactly or with optional \fImask\fR in
 register number \fIidx\fR.  The valid range of \fIidx\fR depends on
 .IP "\fBreg\fIidx\fB=\fIvalue\fR[\fB/\fImask\fR]"
 Matches \fIvalue\fR either exactly or with optional \fImask\fR in
 register number \fIidx\fR.  The valid range of \fIidx\fR depends on
@@ -897,6 +920,40 @@ as necessary to match the value specified.  Valid values are between 0
 .IP \fBstrip_vlan\fR
 Strips the VLAN tag from a packet if it is present.
 .
 .IP \fBstrip_vlan\fR
 Strips the VLAN tag from a packet if it is present.
 .
+.IP \fBpush_vlan\fR:\fIethertype\fR
+Push a new VLAN tag onto the packet.  Ethertype is used as the the Ethertype
+for the tag. Only ethertype 0x8100 should be used. (0x88a8 which the spec
+allows isn't supported at the moment.)
+A priority of zero and the tag of zero are used for the new tag.
+.
+.IP \fBpush_mpls\fR:\fIethertype\fR
+If the packet does not already contain any MPLS labels, changes the
+packet's Ethertype to \fIethertype\fR, which must be either the MPLS
+unicast Ethertype \fB0x8847\fR or the MPLS multicast Ethertype
+\fB0x8848\fR, and then pushes an initial label stack entry.  The label
+stack entry's default label is 2 if the packet contains IPv6 and 0
+otherwise, its default traffic control value is the low 3 bits of the
+packet's DSCP value (0 if the packet is not IP), and its TTL is copied
+from the IP TTL (64 if the packet is not IP).
+.IP
+If the packet does already contain an MPLS label, pushes a new
+outermost label as a copy of the existing outermost label.
+.IP
+There are some limitations in the implementation.  \fBpush_mpls\fR
+followed by another \fBpush_mpls\fR will result in the first
+\fBpush_mpls\fR being discarded.
+.
+.IP \fBpop_mpls\fR:\fIethertype\fR
+Strips the outermost MPLS label stack entry.  If the MPLS label
+stripped was the only one, changes the ethertype of a packet to
+\fIethertype\fR, which should not ordinarily be an MPLS Ethertype.
+.
+.IP
+There are some limitations in the implementation.  \fBpop_mpls\fR
+followed by another \fBpush_mpls\fR without an intermediate
+\fBpush_mpls\fR will result in the first \fBpush_mpls\fR being
+discarded.
+.
 .IP \fBmod_dl_src\fB:\fImac\fR
 Sets the source Ethernet address to \fImac\fR.
 .
 .IP \fBmod_dl_src\fB:\fImac\fR
 Sets the source Ethernet address to \fImac\fR.
 .
@@ -916,10 +973,9 @@ Sets the TCP or UDP source port to \fIport\fR.
 Sets the TCP or UDP destination port to \fIport\fR.
 .
 .IP \fBmod_nw_tos\fB:\fItos\fR
 Sets the TCP or UDP destination port to \fIport\fR.
 .
 .IP \fBmod_nw_tos\fB:\fItos\fR
-Sets the IPv4 ToS/DSCP field to \fItos\fR.  Valid values are between 0 and
-255, inclusive.  Note that the two lower reserved bits are never
-modified.
-.
+Sets the IPv4 ToS/DSCP field to \fItos\fR, which must be a multiple of
+4 between 0 and 255.  This action does not modify the two least
+significant bits of the ToS field (the ECN bits).
 .RE
 .IP
 The following actions are Nicira vendor extensions that, as of this writing, are
 .RE
 .IP
 The following actions are Nicira vendor extensions that, as of this writing, are
@@ -973,6 +1029,19 @@ invalid ttl packets.  If controller ids are not specified, the
 ``packet_in'' message will be sent only to the controllers having
 controller id zero which have registered for the invalid ttl packets.
 .
 ``packet_in'' message will be sent only to the controllers having
 controller id zero which have registered for the invalid ttl packets.
 .
+.IP \fBset_mpls_ttl\fR:\fIttl\fR
+Set the TTL of the outer MPLS label stack entry of a packet.
+\fIttl\fR should be in the range 0 to 255 inclusive.
+.
+.IP \fBdec_mpls_ttl\fR
+Decrement TTL of the outer MPLS label stack entry of a packet.  If the TTL
+is initially zero, no decrement occurs.  Instead, a ``packet-in'' message
+with reason code \fBOFPR_INVALID_TTL\fR is sent to each connected
+controller with controller id zer that has enabled receiving them.
+Processing the current set of actions then stops.  However, if the current
+set of actions was reached through ``resubmit'' then remaining actions in
+outer levels resume processing.
+.
 .IP \fBnote:\fR[\fIhh\fR]...
 Does nothing at all.  Any number of bytes represented as hex digits
 \fIhh\fR may be included.  Pairs of hex digits may be separated by
 .IP \fBnote:\fR[\fIhh\fR]...
 Does nothing at all.  Any number of bytes represented as hex digits
 \fIhh\fR may be included.  Pairs of hex digits may be separated by
@@ -1005,6 +1074,32 @@ in field \fIdst\fR.
 Example: \fBload:55\->NXM_NX_REG2[0..5]\fR loads value 55 (bit pattern
 \fB110111\fR) into bits 0 through 5, inclusive, in register 2.
 .
 Example: \fBload:55\->NXM_NX_REG2[0..5]\fR loads value 55 (bit pattern
 \fB110111\fR) into bits 0 through 5, inclusive, in register 2.
 .
+.IP "\fBpush:\fIsrc\fB[\fIstart\fB..\fIend\fB]"
+Pushes \fIstart\fR to \fIend\fR bits inclusive, in fields
+on top of the stack.
+.IP
+Example: \fBpush:NXM_NX_REG2[0..5]\fR push the value stored in register
+2 bits 0 through 5, inclusive, on to the internal stack.
+.
+.IP "\fBpop:\fIdst\fB[\fIstart\fB..\fIend\fB]"
+Pops from the top of the stack, retrieves the \fIstart\fR to \fIend\fR bits
+inclusive, from the value popped and store them into the corresponding
+bits in \fIdst\fR.
+.
+.IP
+Example: \fBpop:NXM_NX_REG2[0..5]\fR pops the value from top of the stack.
+Set register 2 bits 0 through 5, inclusive, based on bits 0 through 5 from the
+value just popped.
+.
+.IP "\fBset_field:\fIvalue\fB\->\fIdst"
+Writes the literal \fIvalue\fR into the field \fIdst\fR, which should
+be specified as a name used for matching.  (This is similar to
+\fBload\fR but more closely matches the set-field action defined in
+Open Flow 1.2 and above.)
+.
+.IP
+Example: \fBset_field:fe80:0123:4567:890a:a6ba:dbff:fefe:59fa\->ipv6_src\fR
+.
 .IP "\fBmultipath(\fIfields\fB, \fIbasis\fB, \fIalgorithm\fB, \fIn_links\fB, \fIarg\fB, \fIdst\fB[\fIstart\fB..\fIend\fB])\fR"
 Hashes \fIfields\fR using \fIbasis\fR as a universal hash parameter,
 then the applies multipath link selection \fIalgorithm\fR (with
 .IP "\fBmultipath(\fIfields\fB, \fIbasis\fB, \fIalgorithm\fB, \fIn_links\fB, \fIarg\fB, \fIdst\fB[\fIstart\fB..\fIend\fB])\fR"
 Hashes \fIfields\fR using \fIbasis\fR as a universal hash parameter,
 then the applies multipath link selection \fIalgorithm\fR (with
@@ -1020,21 +1115,6 @@ the \fBiter_hash\fR algorithm uses \fIarg\fR.
 .IP
 Refer to \fBnicira\-ext.h\fR for more details.
 .
 .IP
 Refer to \fBnicira\-ext.h\fR for more details.
 .
-.IP "\fBautopath(\fIid\fB, \fIdst\fB[\fIstart\fB..\fIend\fB])\fR"
-Deprecated and slated for removal in Feburary 2013.
-.IP
-Given \fIid\fR, chooses an OpenFlow port and populates it in
-\fIdst\fB[\fIstart\fB..\fIend\fB]\fR, which must be an NXM field as
-described above.
-.IP
-Currently, \fIid\fR should be the OpenFlow port number of an interface on the
-bridge.  If it isn't then \fIdst\fB[\fIstart\fB..\fIend\fB]\fR will be
-populated with the OpenFlow port "none".  If \fIid\fR is a member of a bond,
-the normal bond selection logic will be used to choose the destination port.
-Otherwise, the register will be populated with \fIid\fR itself.
-.IP
-Refer to \fBnicira\-ext.h\fR for more details.
-.
 .IP "\fBbundle(\fIfields\fB, \fIbasis\fB, \fIalgorithm\fB, \fIslave_type\fB, slaves:[\fIs1\fB, \fIs2\fB, ...])\fR"
 Hashes \fIfields\fR using \fIbasis\fR as a universal hash parameter, then
 applies the bundle link selection \fIalgorithm\fR to choose one of the listed
 .IP "\fBbundle(\fIfields\fB, \fIbasis\fB, \fIalgorithm\fB, \fIslave_type\fB, slaves:[\fIs1\fB, \fIs2\fB, ...])\fR"
 Hashes \fIfields\fR using \fIbasis\fR as a universal hash parameter, then
 applies the bundle link selection \fIalgorithm\fR to choose one of the listed
@@ -1131,6 +1211,26 @@ possibly for a lowest-priority ``catch-all'' flow, that is, a flow
 with no match criteria.  (This is why the default \fBtable\fR is 1, to
 keep the learned flows separate from the primary flow table 0.)
 .
 with no match criteria.  (This is why the default \fBtable\fR is 1, to
 keep the learned flows separate from the primary flow table 0.)
 .
+.RS
+.IP \fBapply_actions(\fR[\fIaction\fR][\fB,\fIaction\fR...]\fB)
+Applies the specific action(s) immediately. The syntax of actions are same
+to \fBactions=\fR field.
+.
+.IP \fBclear_actions\fR
+Clears all the actions in the action set immediately.
+.
+.IP \fBwrite_metadata\fB:\fIvalue\fR[/\fImask\fR]
+Updates the metadata field for the flow. If \fImask\fR is omitted, the
+metadata field is set exactly to \fIvalue\fR; if \fImask\fR is specified, then
+a 1-bit in \fImask\fR indicates that the corresponding bit in the metadata
+field will be replaced with the corresponding bit from \fIvalue\fR. Both
+\fIvalue\fR and \fImask\fR are 64-bit values that are decimal by default; use
+a \fB0x\fR prefix to specify them in hexadecimal.
+.
+.IP \fBgoto_table\fR:\fItable\fR
+Indicates the next table in the process pipeline.
+.RE
+.
 .IP "\fBfin_timeout(\fIargument\fR[\fB,\fIargument\fR]\fB)"
 This action changes the idle timeout or hard timeout, or both, of this
 OpenFlow rule when the rule matches a TCP packet with the FIN or RST
 .IP "\fBfin_timeout(\fIargument\fR[\fB,\fIargument\fR]\fB)"
 This action changes the idle timeout or hard timeout, or both, of this
 OpenFlow rule when the rule matches a TCP packet with the FIN or RST
@@ -1152,6 +1252,30 @@ flow's creation, not since the receipt of the FIN or RST.)
 .RE
 .IP
 This action was added in Open vSwitch 1.5.90.
 .RE
 .IP
 This action was added in Open vSwitch 1.5.90.
+.
+.IP "\fBsample(\fIargument\fR[\fB,\fIargument\fR]...\fB)\fR"
+Samples packets and sends one sample for every sampled packet.
+.IP
+\fIargument\fR takes the following forms:
+.RS
+.IP "\fBprobability=\fIpackets\fR"
+The number of sampled packets out of 65535.  Must be greater or equal to 1.
+.IP "\fBcollector_set_id=\fIid\fR"
+The unsigned 32-bit integer identifier of the set of sample collectors
+to send sampled packets to.  Defaults to 0.
+.IP "\fBobs_domain_id=\fIid\fR"
+When sending samples to IPFIX collectors, the unsigned 32-bit integer
+Observation Domain ID sent in every IPFIX flow record.  Defaults to 0.
+.IP "\fBobs_point_id=\fIid\fR"
+When sending samples to IPFIX collectors, the unsigned 32-bit integer
+Observation Point ID sent in every IPFIX flow record.  Defaults to 0.
+.RE
+.IP
+Refer to \fBovs\-vswitchd.conf.db\fR(8) for more details on
+configuring sample collector sets.
+.IP
+This action was added in Open vSwitch 1.10.90.
+.
 .IP "\fBexit\fR"
 This action causes Open vSwitch to immediately halt execution of further
 actions.  Those actions which have already been executed are unaffected.  Any
 .IP "\fBexit\fR"
 This action causes Open vSwitch to immediately halt execution of further
 actions.  Those actions which have already been executed are unaffected.  Any
@@ -1298,6 +1422,8 @@ passing through the flow.
 \fB\-\-strict\fR
 Uses strict matching when running flow modification commands.
 .
 \fB\-\-strict\fR
 Uses strict matching when running flow modification commands.
 .
+.so lib/ofp-version.man
+.
 .IP "\fB\-F \fIformat\fR[\fB,\fIformat\fR...]"
 .IQ "\fB\-\-flow\-format=\fIformat\fR[\fB,\fIformat\fR...]"
 \fBovs\-ofctl\fR supports the following individual flow formats, any
 .IP "\fB\-F \fIformat\fR[\fB,\fIformat\fR...]"
 .IQ "\fB\-\-flow\-format=\fIformat\fR[\fB,\fIformat\fR...]"
 \fBovs\-ofctl\fR supports the following individual flow formats, any
@@ -1322,6 +1448,11 @@ registers.  Open vSwitch 1.1 and later supports this flow format.
 This combines Nicira Extended match with the ability to place a flow
 in a specific table.  Open vSwitch 1.2 and later supports this flow
 format.
 This combines Nicira Extended match with the ability to place a flow
 in a specific table.  Open vSwitch 1.2 and later supports this flow
 format.
+.
+.IP "\fBOXM-OpenFlow12\fR"
+.IQ "\fBOXM-OpenFlow13\fR"
+These are the standard OXM (OpenFlow Extensible Match) flow format in
+OpenFlow 1.2 and 1.3, respectively.
 .RE
 .
 .IP
 .RE
 .
 .IP
@@ -1334,6 +1465,8 @@ Any supported flow format.
 \fBOpenFlow10\-table_id\fR or \fBOpenFlow10+table_id\fR.
 .IP "\fBNXM\fR"
 \fBNXM\-table_id\fR or \fBNXM+table_id\fR.
 \fBOpenFlow10\-table_id\fR or \fBOpenFlow10+table_id\fR.
 .IP "\fBNXM\fR"
 \fBNXM\-table_id\fR or \fBNXM+table_id\fR.
+.IP "\fBOXM\fR"
+\fBOXM-OpenFlow12\fR or \fBOXM-OpenFlow13\fR.
 .RE
 .
 .IP
 .RE
 .
 .IP
@@ -1457,3 +1590,4 @@ Prints the flow entries in the switch.
 .BR ovs\-appctl (8),
 .BR ovs\-controller (8),
 .BR ovs\-vswitchd (8)
 .BR ovs\-appctl (8),
 .BR ovs\-controller (8),
 .BR ovs\-vswitchd (8)
+.BR ovs\-vswitchd.conf.db (8)