. 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
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
\fBdump\-tables \fIswitch\fR
Prints to the console statistics for each of the flow tables used by
\fIswitch\fR.
+.TP
+\fBdump\-table\-features \fIswitch\fR
+Prints to the console features for each of the flow tables used by
+\fIswitch\fR.
+.TP
+\fBdump\-table\-desc \fIswitch\fR
+Prints to the console configuration for each of the flow tables used
+by \fIswitch\fR for OpenFlow 1.4+.
+.IP "\fBmod\-table \fIswitch\fR \fItable_id\fR \fIsetting\fR"
+This command configures flow table settings for OpenFlow table
+\fItable_id\fR within \fIswitch\fR. The available settings depend on
+the OpenFlow version in use. In OpenFlow 1.1 and 1.2 (which must be
+enabled with the \fB\-O\fR option) only, \fBmod\-table\fR configures
+behavior when no flow is found when a packet is looked up in a flow
+table. The following \fIsetting\fR values are available:
+.RS
+.IP \fBdrop\fR
+Drop the packet.
+.IP \fBcontinue\fR
+Continue to the next table in the pipeline. (This is how an OpenFlow
+1.0 switch always handles packets that do not match any flow, in
+tables other than the last one.)
+.IP \fBcontroller\fR
+Send to controller. (This is how an OpenFlow 1.0 switch always
+handles packets that do not match any flow in the last table.)
+.RE
+.IP
+In OpenFlow 1.4 and later (which must be enabled with the \fB\-O\fR
+option) only, \fBmod\-table\fR configures the behavior when a
+controller attempts to add a flow to a flow table that is full. The
+following \fIsetting\fR values are available:
+.RS
+.IP \fBevict\fR
+Delete some existing flow from the flow table, according to the
+algorithm described for the \fBFlow_Table\fR table in
+\fBovs-vswitchd.conf.db\fR(5).
+.IP \fBnoevict\fR
+Refuse to add the new flow. (Eviction might still be enabled through
+the \fBoverflow_policy\fR oclumn in the \fBFlow_Table\fR table
+documented in \fBovs-vswitchd.conf.db\fR(5).)
+.RE
.
.TP
\fBdump\-ports \fIswitch\fR [\fInetdev\fR]
associated with that device will be printed. \fInetdev\fR can be an
OpenFlow assigned port number or device name, e.g. \fBeth0\fR.
.
-.TP
-\fBdump\-ports\-desc \fIswitch\fR
+.IP "\fBdump\-ports\-desc \fIswitch\fR [\fIport\fR]"
Prints to the console detailed information about network devices
-associated with \fIswitch\fR (version 1.7 or later). This is a subset
-of the information provided by the \fBshow\fR command.
+associated with \fIswitch\fR. To dump only a specific port, specify
+its number as \fIport\fR. Otherwise, if \fIport\fR is omitted, or if
+it is specified as \fBANY\fR, then all ports are printed. This is a
+subset of the information provided by the \fBshow\fR command.
+.IP
+If the connection to \fIswitch\fR negotiates OpenFlow 1.0, 1.2, or
+1.2, this command uses an OpenFlow extension only implemented in Open
+vSwitch (version 1.7 and later).
+.IP
+Only OpenFlow 1.5 and later support dumping a specific port. Earlier
+versions of OpenFlow always dump all ports.
.
-.TP
-\fBmod\-port \fIswitch\fR \fInetdev\fR \fIaction\fR
-Modify characteristics of an interface monitored by \fIswitch\fR.
-\fInetdev\fR can be referred to by its OpenFlow assigned port number or
-the device name, e.g. \fBeth0\fR. The \fIaction\fR may be any one of the
-following:
+.IP "\fBmod\-port \fIswitch\fR \fIport\fR \fIaction\fR"
+Modify characteristics of port \fBport\fR in \fIswitch\fR. \fIport\fR
+may be an OpenFlow port number or name or the keyword \fBLOCAL\fR (the
+preferred way to refer to the OpenFlow local port). The \fIaction\fR
+may be any one of the following:
.
.RS
.IQ \fBup\fR
.
.IP "\fBqueue\-stats \fIswitch \fR[\fIport \fR[\fIqueue\fR]]"
Prints to the console statistics for the specified \fIqueue\fR on
-\fIport\fR within \fIswitch\fR. Either of \fIport\fR or \fIqueue\fR
-or both may be omitted (or equivalently specified as \fBALL\fR). If
-both are omitted, statistics are printed for all queues on all ports.
-If only \fIqueue\fR is omitted, then statistics are printed for all
-queues on \fIport\fR; if only \fIport\fR is omitted, then statistics
-are printed for \fIqueue\fR on every port where it exists.
+\fIport\fR within \fIswitch\fR. \fIport\fR can be an OpenFlow port
+number or name, the keyword \fBLOCAL\fR (the preferred way to refer to
+the OpenFlow local port), or the keyword \fBALL\fR. Either of
+\fIport\fR or \fIqueue\fR or both may be omitted (or equivalently the
+keyword \fBALL\fR). If both are omitted, statistics are printed for
+all queues on all ports. If only \fIqueue\fR is omitted, then
+statistics are printed for all queues on \fIport\fR; if only
+\fIport\fR is omitted, then statistics are printed for \fIqueue\fR on
+every port where it exists.
+.
+.SS "OpenFlow 1.1+ Group Table Commands"
+.
+The following commands work only with switches that support OpenFlow
+1.1 or later. Because support for OpenFlow 1.1 and later is still
+experimental in Open vSwitch, it is necessary to explicitly enable
+these protocol versions in \fBovs\-ofctl\fR (using \fB\-O\fR) and in
+the switch itself (with the \fBprotocols\fR column in the \fBBridge\fR
+table). For more information, see ``Q: What versions of OpenFlow does
+Open vSwitch support?'' in the Open vSwitch FAQ.
+.
+.IP "\fBdump\-groups \fIswitch\fR [\fIgroup\fR]"
+Prints group entries in \fIswitch\fR's tables to console. To dump
+only a specific group, specify its number as \fIgroup\fR. Otherwise,
+if \fIgroup\fR is omitted, or if it is specified as \fBALL\fR, then
+all groups are printed. Each line of output is a group entry as
+described in \fBGroup Syntax\fR below.
+.IP
+Only OpenFlow 1.5 and later support dumping a specific group. Earlier
+versions of OpenFlow always dump all groups.
+.
+.IP "\fBdump\-group\-features \fIswitch"
+Prints to the console the group features of the \fIswitch\fR.
+.
+.IP "\fBdump\-group-stats \fIswitch \fR[\fIgroups\fR]"
+Prints to the console statistics for the specified \fIgroups in the
+\fIswitch\fR's tables. If \fIgroups\fR is omitted then statistics for all
+groups are printed. See \fBGroup Syntax\fR, below, for the syntax of
+\fIgroups\fR.
+.
+.SS "OpenFlow 1.3+ Switch Meter Table Commands"
+.
+These commands manage the meter table in an OpenFlow switch. In each
+case, \fImeter\fR specifies a meter entry in the format described in
+\fBMeter Syntax\fR, below.
+.
+.PP
+OpenFlow 1.3 introduced support for meters, so these commands only
+work with switches that support OpenFlow 1.3 or later. The caveats
+described for groups in the previous section also apply to meters.
+.
+.IP "\fBadd\-meter \fIswitch meter\fR"
+Add a meter entry to \fIswitch\fR's tables. The \fImeter\fR syntax is
+described in section \fBMeter Syntax\fR, below.
+.
+.IP "\fBmod\-meter \fIswitch meter\fR"
+Modify an existing meter.
+.
+.IP "\fBdel\-meters \fIswitch\fR"
+.IQ "\fBdel\-meter \fIswitch\fR [\fImeter\fR]"
+Delete entries from \fIswitch\fR's meter table. \fImeter\fR can specify
+a single meter with syntax \fBmeter=\fIid\fR, or all meters with syntax
+\fBmeter=all\fR.
+.
+.IP "\fBdump\-meters \fIswitch\fR"
+.IQ "\fBdump\-meter \fIswitch\fR [\fImeter\fR]"
+Print meter configuration. \fImeter\fR can specify a single meter with
+syntax \fBmeter=\fIid\fR, or all meters with syntax \fBmeter=all\fR.
+.
+.IP "\fBmeter\-stats \fIswitch\fR [\fImeter\fR]"
+Print meter statistics. \fImeter\fR can specify a single meter with
+syntax \fBmeter=\fIid\fR, or all meters with syntax \fBmeter=all\fR.
+.
+.IP "\fBmeter\-features \fIswitch\fR"
+Print meter features.
.
.SS "OpenFlow Switch Flow Table Commands"
.
These commands manage the flow table in an OpenFlow switch. In each
case, \fIflow\fR specifies a flow entry in the format described in
-\fBFlow Syntax\fR, below, and \fIfile\fR is a text file that contains
-zero or more flows in the same syntax, one per line.
-.
-.IP "\fBadd\-flow \fIswitch flow\fR"
-.IQ "\fBadd\-flow \fIswitch \fB\- < \fIfile\fR"
-.IQ "\fBadd\-flows \fIswitch file\fR"
+\fBFlow Syntax\fR, below, \fIfile\fR is a text file that contains zero
+or more flows in the same syntax, one per line, and the optional
+\fB\-\-bundle\fR option operates the command as a single atomic
+transation, see option \fB\-\-bundle\fR, below.
+.
+.IP "[\fB\-\-bundle\fR] \fBadd\-flow \fIswitch flow\fR"
+.IQ "[\fB\-\-bundle\fR] \fBadd\-flow \fIswitch \fB\- < \fIfile\fR"
+.IQ "[\fB\-\-bundle\fR] \fBadd\-flows \fIswitch file\fR"
Add each flow entry to \fIswitch\fR's tables.
.
-.IP "[\fB\-\-strict\fR] \fBmod\-flows \fIswitch flow\fR"
-.IQ "[\fB\-\-strict\fR] \fBmod\-flows \fIswitch \fB\- < \fIfile\fR"
+Each flow specification (e.g., each line in \fIfile\fR) may start with
+\fBadd\fR, \fBmodify\fR, \fBdelete\fR, \fBmodify_strict\fR, or
+\fBdelete_strict\fR keyword to specify whether a flow is to be added,
+modified, or deleted, and whether the modify or delete is strict or
+not. For backwards compatibility a flow specification without one of
+these keywords is treated as a flow add. All flow mods are executed
+in the order specified.
+.
+.IP "[\fB\-\-bundle\fR] [\fB\-\-strict\fR] \fBmod\-flows \fIswitch flow\fR"
+.IQ "[\fB\-\-bundle\fR] [\fB\-\-strict\fR] \fBmod\-flows \fIswitch \fB\- < \fIfile\fR"
Modify the actions in entries from \fIswitch\fR's tables that match
the specified flows. With \fB\-\-strict\fR, wildcards are not treated
as active for matching purposes.
.
-.IP "\fBdel\-flows \fIswitch\fR"
-.IQ "[\fB\-\-strict\fR] \fBdel\-flows \fIswitch \fR[\fIflow\fR]"
-.IQ "[\fB\-\-strict\fR] \fBdel\-flows \fIswitch \fB\- < \fIfile\fR"
+.IP "[\fB\-\-bundle\fR] \fBdel\-flows \fIswitch\fR"
+.IQ "[\fB\-\-bundle\fR] [\fB\-\-strict\fR] \fBdel\-flows \fIswitch \fR[\fIflow\fR]"
+.IQ "[\fB\-\-bundle\fR] [\fB\-\-strict\fR] \fBdel\-flows \fIswitch \fB\- < \fIfile\fR"
Deletes entries from \fIswitch\fR's flow table. With only a
\fIswitch\fR argument, deletes all flows. Otherwise, deletes flow
entries that match the specified flows. With \fB\-\-strict\fR,
wildcards are not treated as active for matching purposes.
.
-.IP "[\fB\-\-readd\fR] \fBreplace\-flows \fIswitch file\fR"
+.IP "[\fB\-\-bundle\fR] [\fB\-\-readd\fR] \fBreplace\-flows \fIswitch file\fR"
Reads flow entries from \fIfile\fR (or \fBstdin\fR if \fIfile\fR is
\fB\-\fR) and queries the flow table from \fIswitch\fR. Then it fixes
up any differences, adding flows from \fIflow\fR that are missing on
.
.IP "\fBpacket\-out \fIswitch in_port actions packet\fR..."
Connects to \fIswitch\fR and instructs it to execute the OpenFlow
-\fIactions\fR on each \fIpacket\fR. For the purpose of executing the
+\fIactions\fR on each \fIpacket\fR. Each \fBpacket\fR is specified as a
+series of hex digits. For the purpose of executing the
actions, the packets are considered to have arrived on \fIin_port\fR,
-which may be an OpenFlow assigned port number, an OpenFlow port name
-(e.g. \fBeth0\fR), the keyword \fBlocal\fR for the OpenFlow ``local''
-port \fBOFPP_LOCAL\fR, or the keyword \fBnone\fR to indicate that the
-packet was generated by the switch itself.
+which may be an OpenFlow port number or name (e.g. \fBeth0\fR), the
+keyword \fBLOCAL\fR (the preferred way to refer to the OpenFlow
+``local'' port), or the keyword \fBNONE\fR to indicate that the packet
+was generated by the switch itself.
+.
+.SS "OpenFlow Switch Group Table Commands"
+.
+These commands manage the group table in an OpenFlow switch. In each
+case, \fIgroup\fR specifies a group entry in the format described in
+\fBGroup Syntax\fR, below, and \fIfile\fR is a text file that contains
+zero or more groups in the same syntax, one per line.
+
+.IP "\fBadd\-group \fIswitch group\fR"
+.IQ "\fBadd\-group \fIswitch \fB\- < \fIfile\fR"
+.IQ "\fBadd\-groups \fIswitch file\fR"
+Add each group entry to \fIswitch\fR's tables.
+.
+.IP "\fBmod\-group \fIswitch group\fR"
+.IQ "\fBmod\-group \fIswitch \fB\- < \fIfile\fR"
+Modify the action buckets in entries from \fIswitch\fR's tables for
+each group entry.
+.
+.IP "\fBdel\-groups \fIswitch\fR"
+.IQ "\fBdel\-groups \fIswitch \fR[\fIgroup\fR]"
+.IQ "\fBdel\-groups \fIswitch \fB\- < \fIfile\fR"
+Deletes entries from \fIswitch\fR's group table. With only a
+\fIswitch\fR argument, deletes all groups. Otherwise, deletes the group
+for each group entry.
+.
+.IP "\fBinsert\-buckets \fIswitch group\fR"
+.IQ "\fBinsert\-buckets \fIswitch \fB\- < \fIfile\fR"
+Add buckets to an existing group present in the \fIswitch\fR's group table.
+If no \fIcommand_bucket_id\fR is present in the group specification then all
+buckets of the group are removed.
+.
+.IP "\fBremove\-buckets \fIswitch group\fR"
+.IQ "\fBremove\-buckets \fIswitch \fB\- < \fIfile\fR"
+Remove buckets to an existing group present in the \fIswitch\fR's group table.
+If no \fIcommand_bucket_id\fR is present in the group specification then all
+buckets of the group are removed.
+.
+.SS "OpenFlow Switch Geneve Option Table Commands"
+.
+In order to work with Geneve options, it is necessary to maintain a mapping
+table between an option (defined by <class, type, length>) and an NXM field
+that can be operated on for the purposes of matches, actions, etc. This
+mapping must be explicitly specified by the user through the following
+commands. The format for \fIoptions\fR is given in \fBOption Syntax\fR below.
+
+Note that a given mapping should not be changed while it is in active use by
+a flow. The result of doing so is undefined.
+
+Currently, the Geneve mapping table is shared between all OpenFlow
+switches in a given instance of Open vSwitch. This restriction will
+be lifted in the future to allow for easier management.
+
+These commands are Nicira extensions to OpenFlow and require Open vSwitch
+2.5 or later.
+
+.IP "\fBadd\-geneve\-map \fIswitch options\fR"
+Add each option entry to \fIswitch\fR's tables. Duplicate fields are
+rejected.
+.
+.IP "\fBdel\-geneve\-map \fIswitch \fR[\fIoptions\fR]"
+Delete each option entry in \fIswitch\fR's tables based on its field index.
+Fields that aren't already mapped will be ignored. If no options are
+specified then the entire table will be cleared.
+.
+.IP "\fBdump\-geneve\-map \fIswitch\fR"
+Show the currently mapped fields in the switch's option table as well
+as switch capabilities.
+.
+.IP "\fBOption Syntax\fR"
+\fB{class=\fIclass\fB,type=\fItype\fB,len=\fIlength\fB}->tun_metadata\fIn\fR
+
+An option can be specified in this form (repeating as necessary and
+separated by commas). For example, the follow is used to map a new option:
+
+.RS
+add-geneve-map br0 "{class=0xffff,type=0,len=4}->tun_metadata0"
+.RE
.
.SS "OpenFlow Switch Monitoring Commands"
.
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
+extension to OpenFlow 1.0 or 1.1, or a standard request in OpenFlow
+1.2 or later), 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
Limits the monitoring to the table with the given \fInumber\fR between
0 and 254. By default, all tables are monitored.
.IP "\fBout_port=\fIport\fR"
-If set, only flows that output to \fIport\fR are monitored.
+If set, only flows that output to \fIport\fR are monitored. The
+\fIport\fR may be an OpenFlow port number or keyword
+(e.g. \fBLOCAL\fR).
.IP "\fIfield\fB=\fIvalue\fR"
Monitors only flows that have \fIfield\fR specified as the given
\fIvalue\fR. Any syntax valid for matching on \fBdump\-flows\fR may
maximum bandwidth to \fItarget\fR for round-trips of \fIn\fR-byte
messages.
.
+.SS "Other Commands"
+.
+.IP "\fBofp\-parse\fR \fIfile\fR"
+Reads \fIfile\fR (or \fBstdin\fR if \fIfile\fR is \fB\-\fR) as a
+series of OpenFlow messages in the binary format used on an OpenFlow
+connection, and prints them to the console. This can be useful for
+printing OpenFlow messages captured from a TCP stream.
+.
+.IP "\fBofp\-parse\-pcap\fR \fIfile\fR [\fIport\fR...]"
+Reads \fIfile\fR, which must be in the PCAP format used by network
+capture tools such as \fBtcpdump\fR or \fBwireshark\fR, extracts all
+the TCP streams for OpenFlow connections, and prints the OpenFlow
+messages in those connections in human-readable format on
+\fBstdout\fR.
+.IP
+OpenFlow connections are distinguished by TCP port number.
+Non-OpenFlow packets are ignored. By default, data on TCP ports 6633
+and 6653 are considered to be OpenFlow. Specify one or more
+\fIport\fR arguments to override the default.
+.IP
+This command cannot usefully print SSL encrypted traffic. It does not
+understand IPv6.
+.
.SS "Flow Syntax"
.PP
Some \fBovs\-ofctl\fR commands accept an argument that describes a flow or
example, if the L2 protocol type \fBdl_type\fR is wildcarded, then L3
fields \fBnw_src\fR, \fBnw_dst\fR, and \fBnw_proto\fR must also be
wildcarded. Similarly, if \fBdl_type\fR or \fBnw_proto\fR (the L3
-protocol type) is wildcarded, so must be \fBtp_dst\fR and
-\fBtp_src\fR, which are L4 fields. \fBovs\-ofctl\fR will warn about
+protocol type) is wildcarded, so must be the L4 fields \fBtcp_dst\fR and
+\fBtcp_src\fR. \fBovs\-ofctl\fR will warn about
flows not in normal form.
.PP
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_no\fR
-Matches OpenFlow port \fIport_no\fR. Ports are numbered as
-displayed by \fBovs\-ofctl show\fR.
+.IP \fBin_port=\fIport\fR
+Matches OpenFlow port \fIport\fR, which may be an OpenFlow port number
+or keyword (e.g. \fBLOCAL\fR).
+\fBovs\-ofctl show\fR.
.IP
(The \fBresubmit\fR action can search OpenFlow flow tables with
arbitrary \fBin_port\fR values, so flows that match port numbers that
\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
+.IQ \fBip_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. 1 to match ICMP packets or 6 to match
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,
-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
0x86dd, the value of \fBnw_tos\fR is ignored (see \fBFlow Syntax\fR
above).
.
+.IP \fBip_dscp=\fIdscp\fR
+Matches IP ToS/DSCP or IPv6 traffic class field \fIdscp\fR, which is
+specified as a decimal number between 0 and 63, inclusive.
+.IP
+When \fBdl_type\fR is wildcarded or set to a value other than 0x0800 or
+0x86dd, the value of \fBip_dscp\fR is ignored (see \fBFlow Syntax\fR
+above).
+.
.IP \fBnw_ecn=\fIecn\fR
+.IQ \fBip_ecn=\fIecn\fR
Matches \fIecn\fR bits in IP ToS or IPv6 traffic class fields, which is
specified as a decimal number between 0 and 3, inclusive.
.IP
above).
.IP
.
-.IP \fBtp_src=\fIport\fR
-.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).
-.IP
-When \fBdl_type\fR and \fBnw_proto\fR take other values, the values of
-these settings are ignored (see \fBFlow Syntax\fR above).
-.
-.IP \fBtp_src=\fIport\fB/\fImask\fR
-.IQ \fBtp_dst=\fIport\fB/\fImask\fR
-Bitwise match on TCP (or UDP) source or destination port,
-respectively. The \fIport\fR and \fImask\fR are 16-bit numbers
+.IP \fBtcp_src=\fIport\fR
+.IQ \fBtcp_dst=\fIport\fR
+.IQ \fBudp_src=\fIport\fR
+.IQ \fBudp_dst=\fIport\fR
+.IQ \fBsctp_src=\fIport\fR
+.IQ \fBsctp_dst=\fIport\fR
+Matches a TCP, UDP, or SCTP source or destination port \fIport\fR,
+which is specified as a decimal number between 0 and 65535, inclusive.
+.IP
+When \fBdl_type\fR and \fBnw_proto\fR are wildcarded or set to values
+that do not indicate an appropriate protocol, the values of these
+settings are ignored (see \fBFlow Syntax\fR above).
+.
+.IP \fBtcp_src=\fIport\fB/\fImask\fR
+.IQ \fBtcp_dst=\fIport\fB/\fImask\fR
+.IQ \fBudp_src=\fIport\fB/\fImask\fR
+.IQ \fBudp_dst=\fIport\fB/\fImask\fR
+.IQ \fBsctp_src=\fIport\fB/\fImask\fR
+.IQ \fBsctp_dst=\fIport\fB/\fImask\fR
+Bitwise match on TCP (or UDP or SCTP) source or destination port.
+The \fIport\fR and \fImask\fR are 16-bit numbers
written in decimal or in hexadecimal prefixed by \fB0x\fR. Each 1-bit
in \fImask\fR requires that the corresponding bit in \fIport\fR must
match. Each 0-bit in \fImask\fR causes the corresponding bit to be
which become the following when written in the syntax required by
\fBovs\-ofctl\fR:
.br
-.B "tcp,tp_src=0x03e8/0xfff8"
+.B "tcp,tcp_src=0x03e8/0xfff8"
.br
-.B "tcp,tp_src=0x03f0/0xfff0"
+.B "tcp,tcp_src=0x03f0/0xfff0"
.br
-.B "tcp,tp_src=0x0400/0xfe00"
+.B "tcp,tcp_src=0x0400/0xfe00"
.br
-.B "tcp,tp_src=0x0600/0xff00"
+.B "tcp,tcp_src=0x0600/0xff00"
.br
-.B "tcp,tp_src=0x0700/0xff80"
+.B "tcp,tcp_src=0x0700/0xff80"
.br
-.B "tcp,tp_src=0x0780/0xffc0"
+.B "tcp,tcp_src=0x0780/0xffc0"
.br
-.B "tcp,tp_src=0x07c0/0xfff0"
+.B "tcp,tcp_src=0x07c0/0xfff0"
.IP
Only Open vSwitch 1.6 and later supports bitwise matching on transport
ports.
.IP
-Like the exact-match forms of \fBtp_src\fR and \fBtp_dst\fR described
+Like the exact-match forms described
above, the bitwise match forms apply only when \fBdl_type\fR and
-\fBnw_proto\fR specify TCP or UDP.
+\fBnw_proto\fR specify TCP or UDP or SCTP.
.
+.IP \fBtp_src=\fIport\fR
+.IQ \fBtp_dst=\fIport\fR
+These are deprecated generic forms of L4 port matches. In new code,
+please use the TCP-, UDP-, or SCTP-specific forms described above.
+.
+.IP \fBtcp_flags=\fIflags\fB/\fImask\fR
+.IQ \fBtcp_flags=\fR[\fB+\fIflag\fR...][\fB-\fIflag\fR...]
+Bitwise match on TCP flags. The \fIflags\fR and \fImask\fR are 16-bit
+numbers written in decimal or in hexadecimal prefixed by \fB0x\fR.
+Each 1-bit in \fImask\fR requires that the corresponding bit in
+\fIflags\fR must match. Each 0-bit in \fImask\fR causes the corresponding
+bit to be ignored.
+.IP
+Alternatively, the flags can be specified by their symbolic names
+(listed below), each preceded by either \fB+\fR for a flag that must
+be set, or \fB\-\fR for a flag that must be unset, without any other
+delimiters between the flags. Flags not mentioned are wildcarded.
+For example, \fBtcp,tcp_flags=+syn\-ack\fR matches TCP SYNs that are
+not ACKs.
+.IP
+TCP protocol currently defines 9 flag bits, and additional 3 bits are
+reserved (must be transmitted as zero), see RFCs 793, 3168, and 3540.
+The flag bits are, numbering from the least significant bit:
+.RS
+.IP "\fB0: fin\fR"
+No more data from sender.
+.IP "\fB1: syn\fR"
+Synchronize sequence numbers.
+.IP "\fB2: rst\fR"
+Reset the connection.
+.IP "\fB3: psh\fR"
+Push function.
+.IP "\fB4: ack\fR"
+Acknowledgement field significant.
+.IP "\fB5: urg\fR"
+Urgent pointer field significant.
+.IP "\fB6: ece\fR"
+ECN Echo.
+.IP "\fB7: cwr\fR"
+Congestion Windows Reduced.
+.IP "\fB8: ns\fR"
+Nonce Sum.
+.IP "\fB9-11:\fR"
+Reserved.
+.IP "\fB12-15:\fR"
+Not matchable, must be zero.
+.RE
.IP \fBicmp_type=\fItype\fR
.IQ \fBicmp_code=\fIcode\fR
When \fBdl_type\fR and \fBnw_proto\fR specify ICMP or ICMPv6, \fItype\fR
these settings are ignored (see \fBFlow Syntax\fR above).
.
.IP \fBtable=\fInumber\fR
-If specified, limits the flow manipulation and flow dump commands to
-only apply to the table with the given \fInumber\fR between 0 and 254.
-.
-Behavior varies if \fBtable\fR is not specified (equivalent to
-specifying 255 as \fInumber\fR). For flow table
-modification commands without \fB\-\-strict\fR, the switch will choose
-the table for these commands to operate on. For flow table
-modification commands with \fB\-\-strict\fR, the command will operate
-on any single matching flow in any table; it will do nothing if there
-are matches in more than one table. The \fBdump-flows\fR and
-\fBdump-aggregate\fR commands will gather statistics about flows from
-all tables.
-.IP
-When this field is specified in \fBadd-flow\fR, \fBadd-flows\fR,
-\fBmod-flows\fR and \fBdel-flows\fR commands, it activates a Nicira
-extension to OpenFlow, which as of this writing is only known to be
-implemented by Open vSwitch.
+For flow dump commands, limits the flows dumped to those in the table
+with the given \fInumber\fR between 0 and 254. If not specified (or if
+255 is specified as \fInumber\fR), then flows in all tables are
+dumped.
+.
+.IP
+For flow table modification commands, behavior varies based on the
+OpenFlow version used to connect to the switch:
+.
+.RS
+.IP "OpenFlow 1.0"
+OpenFlow 1.0 does not support \fBtable\fR for modifying flows.
+\fBovs\-ofctl\fR will exit with an error if \fBtable\fR (other than
+\fBtable=255\fR) is specified for a switch that only supports OpenFlow
+1.0.
+.IP
+In OpenFlow 1.0, the switch chooses the table into which to insert a
+new flow. The Open vSwitch software switch always chooses table 0.
+Other Open vSwitch datapaths and other OpenFlow implementations may
+choose different tables.
+.IP
+The OpenFlow 1.0 behavior in Open vSwitch for modifying or removing
+flows depends on whether \fB\-\-strict\fR is used. Without
+\fB\-\-strict\fR, the command applies to matching flows in all tables.
+With \fB\-\-strict\fR, the command will operate on any single matching
+flow in any table; it will do nothing if there are matches in more
+than one table. (The distinction between these behaviors only matters
+if non-OpenFlow 1.0 commands were also used, because OpenFlow 1.0
+alone cannot add flows with the same matching criteria to multiple
+tables.)
+.
+.IP "OpenFlow 1.0 with table_id extension"
+Open vSwitch implements an OpenFlow extension that allows the
+controller to specify the table on which to operate. \fBovs\-ofctl\fR
+automatically enables the extension when \fBtable\fR is specified and
+OpenFlow 1.0 is used. \fBovs\-ofctl\fR automatically detects whether
+the switch supports the extension. As of this writing, this extension
+is only known to be implemented by Open vSwitch.
+.
+.IP
+With this extension, \fBovs\-ofctl\fR operates on the requested table
+when \fBtable\fR is specified, and acts as described for OpenFlow 1.0
+above when no \fBtable\fR is specified (or for \fBtable=255\fR).
+.
+.IP "OpenFlow 1.1"
+OpenFlow 1.1 requires flow table modification commands to specify a
+table. When \fBtable\fR is not specified (or \fBtable=255\fR is
+specified), \fBovs\-ofctl\fR defaults to table 0.
+.
+.IP "OpenFlow 1.2 and later"
+OpenFlow 1.2 and later allow flow deletion commands, but not other
+flow table modification commands, to operate on all flow tables, with
+the behavior described above for OpenFlow 1.0.
+.RE
.
.IP \fBmetadata=\fIvalue\fR[\fB/\fImask\fR]
Matches \fIvalue\fR either exactly or with optional \fImask\fR in the metadata
.IP \fBudp\fR
Same as \fBdl_type=0x0800,nw_proto=17\fR.
.
+.IP \fBsctp\fR
+Same as \fBdl_type=0x0800,nw_proto=132\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,
\fBnx\-match\fR mode. See the description of the \fBset\-frags\fR
command, above, for more details.
.
+.IP \fBarp_spa=\fIip\fR[\fB/\fInetmask\fR]
+.IQ \fBarp_tpa=\fIip\fR[\fB/\fInetmask\fR]
+When \fBdl_type\fR specifies either ARP or RARP, \fBarp_spa\fR and
+\fBarp_tpa\fR match the source and target IPv4 address, respectively.
+An 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 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).
+.
.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
+(e.g. \fB00:0A:E4:25:6B:B0\fR).
.
+.IP \fBarp_sha=\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB/\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\fB/\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fR
+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
+(e.g. \fB00:0A:E4:25:6B:B0\fR), with a wildcard mask following the slash.
+.
+
.IP \fBipv6_src=\fIipv6\fR[\fB/\fInetmask\fR]
.IQ \fBipv6_dst=\fIipv6\fR[\fB/\fInetmask\fR]
When \fBdl_type\fR is 0x86dd (possibly via shorthand, e.g., \fBipv6\fR
address option. An address is specified as 6 pairs of hexadecimal
digits delimited by colons.
.
+.IP \fBmpls_bos=\fIbos\fR
+When \fBdl_type\fR is 0x8847 or 0x8848 (possibly via shorthand e.g.,
+\fBmpls\fR or \fBmplsm\fR), matches the bottom-of-stack bit of the
+outer-most MPLS label stack entry. Valid values are 0 and 1.
+.IP
+If 1 then for a packet with a well-formed MPLS label stack the
+bottom-of-stack bit indicates that the outer label stack entry is also
+the inner-most label stack entry and thus that is that there is only one
+label stack entry present. Conversely, if 0 then for a packet with a
+well-formed MPLS label stack the bottom-of-stack bit indicates that the
+outer label stack entry is not the inner-most label stack entry and
+thus there is more than one label stack entry present.
+.
+.IP \fBmpls_label=\fIlabel\fR
+When \fBdl_type\fR is 0x8847 or 0x8848 (possibly via shorthand e.g.,
+\fBmpls\fR or \fBmplsm\fR), matches the label of the outer
+MPLS label stack entry. The label is a 20-bit value that is decimal by default;
+use a \fB0x\fR prefix to specify them in hexadecimal.
+.
+.IP \fBmpls_tc=\fItc\fR
+When \fBdl_type\fR is 0x8847 or 0x8848 (possibly via shorthand e.g.,
+\fBmpls\fR or \fBmplsm\fR), matches the traffic-class of the outer
+MPLS label stack entry. Valid values are between 0 (lowest) and 7 (highest).
+.
.IP \fBtun_id=\fItunnel-id\fR[\fB/\fImask\fR]
+.IQ \fBtunnel_id=\fItunnel-id\fR[\fB/\fImask\fR]
Matches tunnel identifier \fItunnel-id\fR. Only packets that arrive
over a tunnel that carries a key (e.g. GRE with the RFC 2890 key
extension and a nonzero key value) will have a nonzero tunnel ID.
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 \fBtun_gbp_id=\fIvalue\fR[\fB/\fImask\fR]
+.IQ \fBtun_gbp_flags=\fIvalue\fR[\fB/\fImask\fR]
+Matches the group policy identifier and flags in the VXLAN header. Only
+packets that arrive over a VXLAN tunnel with the "gbp" extension
+enabled can have this field set. The fields may also be referred to by
+NXM_NX_TUN_GBP_ID[] (16 bits) and NXM_NX_TUN_GBP_FLAGS[] (8 bits) in
+the context of field manipulation actions. If these fields are set and
+the packet matched by the flow is encapsulated in a VXLAN-GBP tunnel,
+then the policy identifier and flags are transmitted to the destination
+VXLAN tunnel endpoint.
+.IP
+The \fBtun_gbp_flags\fR field has the following format:
+.IP
+.in +2
+\f(CR+-+-+-+-+-+-+-+-+\fR
+.br
+\f(CR|-|D|-|-|A|-|-|-|\fR
+.br
+\f(CR+-+-+-+-+-+-+-+-+\fR
+
+.B D :=
+Don't Learn bit. When set, this bit indicates that the egress
+tunnel endpoint MUST NOT learn the source address of the encapsulated
+frame.
+
+.B A :=
+Indicates that the group policy has already been applied to
+this packet. Policies MUST NOT be applied by devices when the A bit is
+set.
+.in -2
+.IP
+For more information, please see the corresponding IETF draft:
+https://tools.ietf.org/html/draft-smith-vxlan-group-policy
+.
+.IP "\fBtun_metadata\fIidx\fB=\fIvalue\fR[\fB/\fImask\fR]"
+Matches \fIvalue\fR either exactly or with optional \fImask\fR in
+tunnel metadata field number \fIidx\fR (numbered from 0 to 63).
+Tunnel metadata fields can be dynamically assigned onto the data
+contained in the options of Geneve packets using the commands
+described in the section \fBOpenFlow Switch Geneve Option Table
+Commands\fR. Once assigned, the length of the field is variable
+according to the size of the option. Before updating a mapping in
+the option table, flows with references to it should be removed,
+otherwise the result is non-deterministic.
+.IP
+These fields were introduced in Open vSwitch 2.5.
+.
.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
exactly, and a 0-bit wildcards that bit.
.IP
When a packet enters an OpenFlow switch, all of the registers are set
-to 0. Only explicit Nicira extension actions change register values.
+to 0. Only explicit actions change register values.
+.
+.IP "\fBxreg\fIidx\fB=\fIvalue\fR[\fB/\fImask\fR]"
+Matches \fIvalue\fR either exactly or with optional \fImask\fR in
+64-bit ``extended register'' number \fIidx\fR. Each of the 64-bit
+extended registers overlays two of the 32-bit registers: \fBxreg0\fR
+overlays \fBreg0\fR and \fBreg1\fR, with \fBreg0\fR supplying the
+most-significant bits of \fBxreg0\fR and \fBreg1\fR the
+least-significant. \fBxreg1\fR similarly overlays \fBreg2\fR and
+\fBreg3\fR, and so on.
+.IP
+These fields were added in Open vSwitch 2.3 to conform with the
+OpenFlow 1.5 specification. OpenFlow 1.5 calls these fields
+just the ``packet registers,'' but Open vSwitch already had 32-bit
+registers by that name, which is why Open vSwitch refers to the
+standard registers as ``extended registers''.
+.
+.IP \fBpkt_mark=\fIvalue\fR[\fB/\fImask\fR]
+Matches packet metadata mark \fIvalue\fR either exactly or with optional
+\fImask\fR. The mark is associated data that may be passed into other
+system components in order to facilitate interaction between subsystems.
+On Linux this corresponds to the skb mark but the exact implementation is
+platform-dependent.
+.
+.IP \fBactset_output=\fIport\fR
+Matches the output port currently in the OpenFlow action set, where
+\fIport\fR may be an OpenFlow port number or keyword
+(e.g. \fBLOCAL\fR). If there is no output port in the OpenFlow action
+set, or if the output port will be ignored (e.g. because there is an
+output group in the OpenFlow action set), then the value will be
+\fBUNSET\fR.
+.IP
+This field was introduced in Open vSwitch 2.4 to conform with the
+OpenFlow 1.5 specification.
+.
+.IP \fBconj_id=\fIvalue\fR
+Matches the given 32-bit \fIvalue\fR against the conjunction ID. This
+is used only with the \fBconjunction\fR action (see below).
+.IP
+This field was introduced in Open vSwitch 2.4.
.
.PP
Defining IPv6 flows (those with \fBdl_type\fR equal to 0x86dd) requires
.IP \fBudp6\fR
Same as \fBdl_type=0x86dd,nw_proto=17\fR.
.
+.IP \fBsctp6\fR
+Same as \fBdl_type=0x86dd,nw_proto=132\fR.
+.
.IP \fBicmp6\fR
Same as \fBdl_type=0x86dd,nw_proto=58\fR.
.
The \fBadd\-flow\fR, \fBadd\-flows\fR, and \fBmod\-flows\fR commands
require an additional field, which must be the final field specified:
.
-.IP \fBactions=\fR[\fItarget\fR][\fB,\fItarget\fR...]\fR
+.IP \fBactions=\fR[\fIaction\fR][\fB,\fIaction\fR...]\fR
Specifies a comma-separated list of actions to take on a packet when the
-flow entry matches. If no \fItarget\fR is specified, then packets
-matching the flow are dropped. The \fItarget\fR may be a decimal port
-number designating the physical port on which to output the packet, or one
-of the following keywords:
+flow entry matches. If no \fIaction\fR is specified, then packets
+matching the flow are dropped. The following forms of \fIaction\fR
+are supported:
.
.RS
-.IP \fBoutput\fR:\fIport\fR
-.IQ \fBoutput\fR:\fIsrc\fB[\fIstart\fB..\fIend\fB]
-Outputs the packet. If \fIport\fR is an OpenFlow port number, outputs directly
-to it. Otherwise, outputs to the OpenFlow port number read from \fIsrc\fR
-which must be an NXM field as described above. Outputting to an NXM field is
-an OpenFlow extension which is not supported by standard OpenFlow switches.
-.IP
-Example: \fBoutput:NXM_NX_REG0[16..31]\fR outputs to the OpenFlow port number
-written in the upper half of register 0.
-.
-.IP \fBenqueue\fR:\fIport\fB:\fIqueue\fR
-Enqueues the packet on the specified \fIqueue\fR within port
-\fIport\fR. The number of supported queues depends on the switch;
-some OpenFlow implementations do not support queuing at all.
+.IP \fIport\fR
+.IQ \fBoutput:\fIport\fR
+Outputs the packet to OpenFlow port number \fIport\fR. If \fIport\fR
+is the packet's input port, the packet is not output.
+.
+.IP \fBoutput:\fIsrc\fB[\fIstart\fB..\fIend\fB]
+Outputs the packet to the OpenFlow port number read from \fIsrc\fR,
+which must be an NXM field as described above. For example,
+\fBoutput:NXM_NX_REG0[16..31]\fR outputs to the OpenFlow port number
+written in the upper half of register 0. If the port number is the
+packet's input port, the packet is not output.
+.IP
+This form of \fBoutput\fR was added in Open vSwitch 1.3.0. This form
+of \fBoutput\fR uses an OpenFlow extension that is not supported by
+standard OpenFlow switches.
+.
+.IP \fBgroup:\fIgroup_id\fR
+Outputs the packet to the OpenFlow group \fIgroup_id\fR. Group tables
+are only supported in OpenFlow 1.1+. See Group Syntax for more details.
.
.IP \fBnormal\fR
Subjects the packet to the device's normal L2/L3 processing. (This
Outputs the packet on all switch physical ports other than the port on
which it was received.
.
+.IP \fBlocal\fR
+Outputs the packet on the ``local port,'' which corresponds to the
+network device that has the same name as the bridge.
+.
+.IP \fBin_port\fR
+Outputs the packet on the port from which it was received.
+.
.IP \fBcontroller(\fIkey\fB=\fIvalue\fR...\fB)
Sends the packet to the OpenFlow controller as a ``packet in''
message. The supported key-value pairs are:
controller uses the \fBNXT_SET_CONTROLLER_ID\fR Nicira extension to
OpenFlow.
.RE
+.IP
Any \fIreason\fR other than \fBaction\fR and any nonzero
\fIcontroller-id\fR uses a Nicira vendor extension that, as of this
writing, is only known to be implemented by Open vSwitch (version 1.6
Shorthand for \fBcontroller()\fR or
\fBcontroller(max_len=\fInbytes\fB)\fR, respectively.
.
-.IP \fBlocal\fR
-Outputs the packet on the ``local port,'' which corresponds to the
-network device that has the same name as the bridge.
-.
-.IP \fBin_port\fR
-Outputs the packet on the port from which it was received.
+.IP \fBenqueue(\fIport\fB,\fIqueue\fB)\fR
+Enqueues the packet on the specified \fIqueue\fR within port
+\fIport\fR, which must be an OpenFlow port number or keyword
+(e.g. \fBLOCAL\fR). The number of supported queues depends on the
+switch; some OpenFlow implementations do not support queuing at all.
.
.IP \fBdrop\fR
Discards the packet, so no further processing or forwarding takes place.
.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
+Changes the packet's Ethertype to \fIethertype\fR, which must be either
+\fB0x8847\fR or \fB0x8848\fR, and pushes an MPLS LSE.
+.IP
+If the packet does not already contain any MPLS labels then an initial
+label stack entry is pushed. The label stack entry's 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
+A limitation of the implementation is that processing of actions will stop
+if \fBpush_mpls\fR follows another \fBpush_mpls\fR unless there is a
+\fBpop_mpls\fR in between.
+.
+.IP \fBpop_mpls\fR:\fIethertype\fR
+Strips the outermost MPLS label stack entry.
+Currently the implementation restricts \fIethertype\fR to a non-MPLS Ethertype
+and thus \fBpop_mpls\fR should only be applied to packets with
+an MPLS label stack depth of one. A further limitation is that processing of
+actions will stop if \fBpop_mpls\fR follows another \fBpop_mpls\fR unless
+there is a \fBpush_mpls\fR in between.
+.
.IP \fBmod_dl_src\fB:\fImac\fR
Sets the source Ethernet address to \fImac\fR.
.
Sets the IPv4 destination address to \fIip\fR.
.
.IP \fBmod_tp_src\fB:\fIport\fR
-Sets the TCP or UDP source port to \fIport\fR.
+Sets the TCP or UDP or SCTP source port to \fIport\fR.
.
.IP \fBmod_tp_dst\fB:\fIport\fR
-Sets the TCP or UDP destination port to \fIport\fR.
+Sets the TCP or UDP or SCTP 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 DSCP bits in the IPv4 ToS/DSCP or IPv6 traffic class 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).
+.
+.IP \fBmod_nw_ecn\fB:\fIecn\fR
+Sets the ECN bits in the IPv4 ToS or IPv6 traffic class field to \fIecn\fR,
+which must be a value between 0 and 3, inclusive. This action does not modify
+the six most significant bits of the field (the DSCP bits).
+.IP
+Requires OpenFlow 1.1 or later.
.
+.IP \fBmod_nw_ttl\fB:\fIttl\fR
+Sets the IPv4 TTL or IPv6 hop limit field to \fIttl\fR, which is specified as
+a decimal number between 0 and 255, inclusive. Switch behavior when setting
+\fIttl\fR to zero is not well specified, though.
+.IP
+Requires OpenFlow 1.1 or later.
.RE
.IP
The following actions are Nicira vendor extensions that, as of this writing, are
.IP \fBdec_ttl\fR
.IQ \fBdec_ttl\fB[\fR(\fIid1,id2\fI)\fR]\fR
Decrement TTL of IPv4 packet or hop limit of IPv6 packet. If the
-TTL or hop limit is initially zero, no decrement occurs. Instead,
+TTL or hop limit is initially zero or decrementing would make it so, no
+decrement occurs, as packets reaching TTL zero must be rejected. Instead,
a ``packet-in'' message with reason code \fBOFPR_INVALID_TTL\fR is
sent to each connected controller that has enabled receiving them,
if any. Processing the current set of actions then stops. However,
``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_label\fR:\fIlabel\fR
+Set the label of the outer MPLS label stack entry of a packet.
+\fIlabel\fR should be a 20-bit value that is decimal by default;
+use a \fB0x\fR prefix to specify them in hexadecimal.
+.
+.IP \fBset_mpls_tc\fR:\fItc\fR
+Set the traffic-class of the outer MPLS label stack entry of a packet.
+\fItc\fR should be a in the range 0 to 7 inclusive.
+.
+.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 or decrementing would make it so, no decrement occurs.
+Instead, a ``packet-in'' message with reason code \fBOFPR_INVALID_TTL\fR
+is sent to the main controller (id zero), if it 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
through 31, inclusive;
\fBmove:NXM_NX_REG0[0..15]\->NXM_OF_VLAN_TCI[]\fR copies the least
significant 16 bits of register 0 into the VLAN TCI field.
-.
-.IP "\fBload:\fIvalue\fB\->\fIdst\fB[\fIstart\fB..\fIend\fB]"
-Writes \fIvalue\fR to bits \fIstart\fR through \fIend\fR, inclusive,
-in field \fIdst\fR.
.IP
-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.
+In OpenFlow 1.0 through 1.4, \fBmove\fR ordinarily uses an Open
+vSwitch extension to OpenFlow. In OpenFlow 1.5, \fBmove\fR uses the
+OpenFlow 1.5 standard \fBcopy_field\fR action. The ONF has
+also made \fBcopy_field\fR available as an extension to OpenFlow 1.3.
+Open vSwitch 2.4 and later understands this extension and uses it if a
+controller uses it, but for backward compatibility with older versions
+of Open vSwitch, \fBovs\-ofctl\fR does not use it.
+.
+.IP "\fBset_field:\fIvalue\fR[/\fImask\fR]\fB\->\fIdst"
+.IQ "\fBload:\fIvalue\fB\->\fIdst\fB[\fIstart\fB..\fIend\fB]"
+Loads a literal value into a field or part of a field. With
+\fBset_field\fR, \fBvalue\fR and the optional \fBmask\fR are given in
+the customary syntax for field \fIdst\fR, which is expressed as a
+field name. For example, \fBset_field:00:11:22:33:44:55->eth_src\fR
+sets the Ethernet source address to 00:11:22:33:44:55. With
+\fBload\fR, \fIvalue\fR must be an integer value (in decimal or
+prefixed by \fB0x\fR for hexadecimal) and \fIdst\fR is the NXM or OXM
+name for the field. For example,
+\fBload:0x001122334455->OXM_OF_ETH_DST[]\fR has the same effect as the
+prior \fBset_field\fR example.
+.IP
+The two forms exist for historical reasons. Open vSwitch 1.1
+introduced \fBNXAST_REG_LOAD\fR as a Nicira extension to OpenFlow 1.0
+and used \fBload\fR to express it. Later, OpenFlow 1.2 introduced a
+standard \fBOFPAT_SET_FIELD\fR action that was restricted to loading
+entire fields, so Open vSwitch added the form \fBset_field\fR with
+this restriction. OpenFlow 1.5 extended \fBOFPAT_SET_FIELD\fR to the
+point that it became a superset of \fBNXAST_REG_LOAD\fR. Open vSwitch
+translates either syntax as necessary for the OpenFlow version in use:
+in OpenFlow 1.0 and 1.1, \fBNXAST_REG_LOAD\fR; in OpenFlow 1.2, 1.3,
+and 1.4, \fBNXAST_REG_LOAD\fR for \fBload\fR or for loading a
+subfield, \fBOFPAT_SET_FIELD\fR otherwise; and OpenFlow 1.5 and later,
+\fBOFPAT_SET_FIELD\fR.
+.
+.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 "\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,
\fIdst\fB[\fIstart\fB..\fIend\fB]\fR, which must be an NXM field as
described above.
.IP
-Currently, \fIfields\fR must be either \fBeth_src\fR or
-\fBsymmetric_l4\fR and \fIalgorithm\fR must be one of \fBmodulo_n\fR,
+\fIfields\fR must be one of the following:
+.RS
+.IP \fBeth_src\fR
+Hashes Ethernet source address only.
+.IP \fBsymmetric_l4\fR
+Hashes Ethernet source, destination, and type, VLAN ID, IPv4/IPv6
+source, destination, and protocol, and TCP or SCTP (but not UDP)
+ports. The hash is computed so that pairs of corresponding flows in
+each direction hash to the same value, in environments where L2 paths
+are the same in each direction. UDP ports are not included in the
+hash to support protocols such as VXLAN that use asymmetric ports in
+each direction.
+.IP \fBsymmetric_l3l4\fR
+Hashes IPv4/IPv6 source, destination, and protocol, and TCP or SCTP
+(but not UDP) ports. Like \fBsymmetric_l4\fR, this is a symmetric
+hash, but by excluding L2 headers it is more effective in environments
+with asymmetric L2 paths (e.g. paths involving VRRP IP addresses on a
+router). Not an effective hash function for protocols other than IPv4
+and IPv6, which hash to a constant zero.
+.IP \fBsymmetric_l3l4+udp\fR
+Like \fBsymmetric_l3l4+udp\fR, but UDP ports are included in the hash.
+This is a more effective hash when asymmetric UDP protocols such as
+VXLAN are not a consideration.
+.RE
+.IP
+\fIalgorithm\fR must be one of \fBmodulo_n\fR,
\fBhash_threshold\fR, \fBhrw\fR, and \fBiter_hash\fR. Only
the \fBiter_hash\fR algorithm uses \fIarg\fR.
.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
\fIslave_type\fR is \fBofport\fR. Thus, each \fIs1\fR through \fIsN\fR should
be an OpenFlow port number. Outputs to the selected slave.
.IP
-Currently, \fIfields\fR must be either \fBeth_src\fR or \fBsymmetric_l4\fR and
-\fIalgorithm\fR must be one of \fBhrw\fR and \fBactive_backup\fR.
+Currently, \fIfields\fR must be either \fBeth_src\fR, \fBsymmetric_l4\fR, \fBsymmetric_l3l4\fR, or \fBsymmetric_l3l4+udp\fR,
+and \fIalgorithm\fR must be one of \fBhrw\fR and \fBactive_backup\fR.
.IP
Example: \fBbundle(eth_src,0,hrw,ofport,slaves:4,8)\fR uses an Ethernet source
hash with basis 0, to select between OpenFlow ports 4 and 8 using the Highest
.IP \fBidle_timeout=\fIseconds\fR
.IQ \fBhard_timeout=\fIseconds\fR
.IQ \fBpriority=\fIvalue\fR
-These key-value pairs have the same meaning as in the usual
-\fBovs\-ofctl\fR flow syntax.
+.IQ \fBcookie=\fIvalue\fR
+.IQ \fBsend_flow_rem\fR
+These arguments have the same meaning as in the usual \fBovs\-ofctl\fR
+flow syntax.
.
.IP \fBfin_idle_timeout=\fIseconds\fR
.IQ \fBfin_hard_timeout=\fIseconds\fR
number between 0 and 254. The default, if \fBtable\fR is unspecified,
is table 1.
.
+.IP \fBdelete_learned\fR
+This flag enables deletion of the learned flows when the flow with the
+\fBlearn\fR action is removed. Specifically, when the last
+\fBlearn\fR action with this flag and particular \fBtable\fR and
+\fBcookie\fR values is removed, the switch deletes all of the flows in
+the specified table with the specified cookie.
+.
+.IP
+This flag was added in Open vSwitch 2.4.
+.
.IP \fIfield\fB=\fIvalue\fR
.IQ \fIfield\fB[\fIstart\fB..\fIend\fB]=\fIsrc\fB[\fIstart\fB..\fIend\fB]\fR
.IQ \fIfield\fB[\fIstart\fB..\fIend\fB]\fR
keep the learned flows separate from the primary flow table 0.)
.RE
.
+.RS
+.
+.IP \fBclear_actions\fR
+Clears all the actions in the action set immediately.
+.
+.IP \fBwrite_actions(\fR[\fIaction\fR][\fB,\fIaction\fR...]\fB)
+Add the specific actions to the action set. The syntax of
+\fIactions\fR is the same as in the \fBactions=\fR field. The action
+set is carried between flow tables and then executed at the end of the
+pipeline.
+.
+.IP
+The actions in the action set are applied in the following order, as
+required by the OpenFlow specification, regardless of the order in
+which they were added to the action set. Except as specified
+otherwise below, the action set only holds at most a single action of
+each type. When more than one action of a single type is written to
+the action set, the one written later replaces the earlier action:
+.
+.RS
+.IP 1.
+\fBstrip_vlan\fR
+.IQ
+\fBpop_mpls\fR
+.
+.IP 2.
+\fBpush_mpls\fR
+.
+.IP 3.
+\fBpush_vlan\fR
+.
+.IP 4.
+\fBdec_ttl\fR
+.IQ
+\fBdec_mpls_ttl\fR
+.
+.IP 5.
+\fBload\fR
+.IQ
+\fBmove\fR
+.IQ
+\fBmod_dl_dst\fR
+.IQ
+\fBmod_dl_src\fR
+.IQ
+\fBmod_nw_dst\fR
+.IQ
+\fBmod_nw_src\fR
+.IQ
+\fBmod_nw_tos\fR
+.IQ
+\fBmod_nw_ecn\fR
+.IQ
+\fBmod_nw_ttl\fR
+.IQ
+\fBmod_tp_dst\fR
+.IQ
+\fBmod_tp_src\fR
+.IQ
+\fBmod_vlan_pcp\fR
+.IQ
+\fBmod_vlan_vid\fR
+.IQ
+\fBset_field\fR
+.IQ
+\fBset_tunnel\fR
+.IQ
+\fBset_tunnel64\fR
+.IQ
+The action set can contain any number of these actions, with
+cumulative effect. They will be applied in the order as added.
+That is, when multiple actions modify the same part of a field,
+the later modification takes effect, and when they modify
+different parts of a field (or different fields), then both
+modifications are applied.
+.
+.IP 6.
+\fBset_queue\fR
+.
+.IP 7.
+\fBgroup\fR
+.IQ
+\fBoutput\fR
+.IQ
+\fBresubmit\fR
+.IQ
+If more than one of these actions is present, then the one listed
+earliest above is executed and the others are ignored, regardless of
+the order in which they were added to the action set. (If none of these
+actions is present, the action set has no real effect, because the
+modified packet is not sent anywhere and thus the modifications are
+not visible.)
+.RE
+.IP
+Only the actions listed above may be written to the action set.
+.
+.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 \fBmeter\fR:\fImeter_id\fR
+Apply the \fImeter_id\fR before any other actions. If a meter band rate is
+exceeded, the packet may be dropped, or modified, depending on the meter
+band type. See the description of the \fBMeter Table Commands\fR, above,
+for more details.
+.
+.IP \fBgoto_table\fR:\fItable\fR
+Indicates the next table in the process pipeline.
+.
.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
.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
-further actions, including those which may be in other tables, or different
-levels of the \fBresubmit\fR call stack, are ignored.
+This action causes Open vSwitch to immediately halt execution of
+further actions. Those actions which have already been executed are
+unaffected. Any further actions, including those which may be in
+other tables, or different levels of the \fBresubmit\fR call stack,
+are ignored. Actions in the action set is still executed (specify
+\fBclear_actions\fR before \fBexit\fR to discard them).
+.
+.IP "\fBconjunction(\fIid\fB, \fIk\fB/\fIn\fR\fB)\fR"
+An individual OpenFlow flow can match only a single value for each
+field. However, situations often arise where one wants to match one
+of a set of values within a field or fields. For matching a single
+field against a set, it is straightforward and efficient to add
+multiple flows to the flow table, one for each value in the set. For
+example, one might use the following flows to send packets with IP
+source address \fIa\fR, \fIb\fR, \fIc\fR, or \fId\fR to the OpenFlow
+controller:
+.RS +1in
+.br
+\fBip,ip_src=\fIa\fB actions=controller\fR
+.br
+\fBip,ip_src=\fIb\fB actions=controller\fR
+.br
+\fBip,ip_src=\fIc\fB actions=controller\fR
+.br
+\fBip,ip_src=\fId\fB actions=controller\fR
+.br
+.RE
+.IP
+Similarly, these flows send packets with IP destination address
+\fIe\fR, \fIf\fR, \fIg\fR, or \fIh\fR to the OpenFlow controller:
+.RS +1in
+.br
+\fBip,ip_dst=\fIe\fB actions=controller\fR
+.br
+\fBip,ip_dst=\fIf\fB actions=controller\fR
+.br
+\fBip,ip_dst=\fIg\fB actions=controller\fR
+.br
+\fBip,ip_dst=\fIh\fB actions=controller\fR
+.br
+.RE
+.IP
+Installing all of the above flows in a single flow table yields a
+disjunctive effect: a packet is sent to the controller if \fBip_src\fR
+\[mo] {\fIa\fR,\fIb\fR,\fIc\fR,\fId\fR} or \fBip_dst\fR \[mo]
+{\fIe\fR,\fIf\fR,\fIg\fR,\fIh\fR} (or both). (Pedantically, if both
+of the above sets of flows are present in the flow table, they should
+have different priorities, because OpenFlow says that the results are
+undefined when two flows with same priority can both match a single
+packet.)
+.IP
+Suppose, on the other hand, one wishes to match conjunctively, that
+is, to send a packet to the controller only if both \fBip_src\fR \[mo]
+{\fIa\fR,\fIb\fR,\fIc\fR,\fId\fR} and \fBip_dst\fR \[mo]
+{\fIe\fR,\fIf\fR,\fIg\fR,\fIh\fR}. This requires 4 \[mu] 4 = 16
+flows, one for each possible pairing of \fBip_src\fR and \fBip_dst\fR.
+That is acceptable for our small example, but it does not gracefully
+extend to larger sets or greater numbers of dimensions.
+.IP
+The \fBconjunction\fR action is a solution for conjunctive matches
+that is built into Open vSwitch. A \fBconjunction\fR action ties
+groups of individual OpenFlow flows into higher-level ``conjunctive
+flows''. Each group corresponds to one dimension, and each flow
+within the group matches one possible value for the dimension. A
+packet that matches one flow from each group matches the conjunctive
+flow.
+.IP
+To implement a conjunctive flow with \fBconjunction\fR, assign the
+conjunctive flow a 32-bit \fIid\fR, which must be unique within an
+OpenFlow table. Assign each of the \fIn\fR \[>=] 2 dimensions a
+unique number from 1 to \fIn\fR; the ordering is unimportant. Add one
+flow to the OpenFlow flow table for each possible value of each
+dimension with \fBconjunction(\fIid, \fIk\fB/\fIn\fB)\fR as the flow's
+actions, where \fIk\fR is the number assigned to the flow's dimension.
+Together, these flows specify the conjunctive flow's match condition.
+When the conjunctive match condition is met, Open vSwitch looks up one
+more flow that specifies the conjunctive flow's actions and receives
+its statistics. This flow is found by setting \fBconj_id\fR to the
+specified \fIid\fR and then again searching the flow table.
+.IP
+The following flows provide an example. Whenever the IP source is one
+of the values in the flows that match on the IP source (dimension 1 of
+2), \fIand\fR the IP destination is one of the values in the flows
+that match on IP destination (dimension 2 of 2), Open vSwitch searches
+for a flow that matches \fBconj_id\fR against the conjunction ID
+(1234), finding the first flow listed below.
+.RS +1in
+.br
+.B "conj_id=1234 actions=controller"
+.br
+.B "ip,ip_src=10.0.0.1 actions=conjunction(1234, 1/2)"
+.br
+.B "ip,ip_src=10.0.0.4 actions=conjunction(1234, 1/2)"
+.br
+.B "ip,ip_src=10.0.0.6 actions=conjunction(1234, 1/2)"
+.br
+.B "ip,ip_src=10.0.0.7 actions=conjunction(1234, 1/2)"
+.br
+.B "ip,ip_dst=10.0.0.2 actions=conjunction(1234, 2/2)"
+.br
+.B "ip,ip_dst=10.0.0.5 actions=conjunction(1234, 2/2)"
+.br
+.B "ip,ip_dst=10.0.0.7 actions=conjunction(1234, 2/2)"
+.br
+.B "ip,ip_dst=10.0.0.8 actions=conjunction(1234, 2/2)"
+.RE
+.IP
+Many subtleties exist:
+.RS
+.IP \(bu
+In the example above, every flow in a single dimension has the same
+form, that is, dimension 1 matches on \fBip_src\fR, dimension 2 on
+\fBip_dst\fR, but this is not a requirement. Different flows within a
+dimension may match on different bits within a field (e.g. IP network
+prefixes of different lengths, or TCP/UDP port ranges as bitwise
+matches), or even on entirely different fields (e.g. to match packets
+for TCP source port 80 or TCP destination port 80).
+.IP \(bu
+The flows within a dimension can vary their matches across more than
+one field, e.g. to match only specific pairs of IP source and
+destination addresses or L4 port numbers.
+.IP \(bu
+A flow may have multiple \fBconjunction\fR actions, with different
+\fIid\fR values. This is useful for multiple conjunctive flows with
+overlapping sets. If one conjunctive flow matches packets with both
+\fBip_src\fR \[mo] {\fIa\fR,\fIb\fR} and \fBip_dst\fR \[mo]
+{\fId\fR,\fIe\fR} and a second conjunctive flow matches \fBip_src\fR
+\[mo] {\fIb\fR,\fIc\fR} and \fBip_dst\fR \[mo] {\fIf\fR,\fIg\fR}, for
+example, then the flow that matches \fBip_src=\fIb\fR would have two
+\fBconjunction\fR actions, one for each conjunctive flow. The order
+of \fBconjunction\fR actions within a list of actions is not
+significant.
+.IP \(bu
+A flow with \fBconjunction\fR actions may also include \fBnote\fR
+actions for annotations, but not any other kind of actions. (They
+would not be useful because they would never be executed.)
+.IP \(bu
+All of the flows that constitute a conjunctive flow with a given
+\fIid\fR must have the same priority. (Flows with the same \fIid\fR
+but different priorities are currently treated as different
+conjunctive flows, that is, currently \fIid\fR values need only be
+unique within an OpenFlow table at a given priority. This behavior
+isn't guaranteed to stay the same in later releases, so please use
+\fIid\fR values unique within an OpenFlow table.)
+.IP \(bu
+Conjunctive flows must not overlap with each other, at a given
+priority, that is, any given packet must be able to match at most one
+conjunctive flow at a given priority. Overlapping conjunctive flows
+yield unpredictable results.
+.IP \(bu
+Following a conjunctive flow match, the search for the flow with
+\fBconj_id=\fIid\fR is done in the same general-purpose way as other flow
+table searches, so one can use flows with \fBconj_id=\fIid\fR to act
+differently depending on circumstances. (One exception is that the
+search for the \fBconj_id=\fIid\fR flow itself ignores conjunctive flows,
+to avoid recursion.) If the search with \fBconj_id=\fIid\fR fails, Open
+vSwitch acts as if the conjunctive flow had not matched at all, and
+continues searching the flow table for other matching flows.
+.IP \(bu
+OpenFlow prerequisite checking occurs for the flow with
+\fBconj_id=\fIid\fR in the same way as any other flow, e.g. in an
+OpenFlow 1.1+ context, putting a \fBmod_nw_src\fR action into the
+example above would require adding an \fBip\fR match, like this:
+.RS +1in
+.br
+.B "conj_id=1234,ip actions=mod_nw_src:1.2.3.4,controller"
+.br
+.RE
+.IP \(bu
+OpenFlow prerequisite checking also occurs for the individual flows
+that comprise a conjunctive match in the same way as any other flow.
+.IP \(bu
+The flows that constitute a conjunctive flow do not have useful
+statistics. They are never updated with byte or packet counts, and so
+on. (For such a flow, therefore, the idle and hard timeouts work much
+the same way.)
+.IP \(bu
+Conjunctive flows can be a useful building block for negation, that
+is, inequality matches like \fBtcp_src\fR \[!=] 80. To implement an
+inequality match, convert it to a pair of range matches, e.g. 0 \[<=]
+\fBtcp_src\ < 80 and 80 < \fBtcp_src\fR \[<=] 65535, then convert each
+of the range matches into a collection of bitwise matches as explained
+above in the description of \fBtcp_src\fR.
+.IP \(bu
+Sometimes there is a choice of which flows include a particular match.
+For example, suppose that we added an extra constraint to our example,
+to match on \fBip_src\fR \[mo] {\fIa\fR,\fIb\fR,\fIc\fR,\fId\fR} and
+\fBip_dst\fR \[mo] {\fIe\fR,\fIf\fR,\fIg\fR,\fIh\fR} and \fBtcp_dst\fR
+= \fIi\fR. One way to implement this is to add the new constraint to
+the \fBconj_id\fR flow, like this:
+.RS +1in
+.br
+\fBconj_id=1234,tcp,tcp_dst=\fIi\fB actions=mod_nw_src:1.2.3.4,controller\fR
+.br
+.RE
+.IP
+\fIbut this is not recommended\fR because of the cost of the extra
+flow table lookup. Instead, add the constraint to the individual
+flows, either in one of the dimensions or (slightly better) all of
+them.
+.IP \(bu
+A conjunctive match must have \fIn\fR \[>=] 2 dimensions (otherwise a
+conjunctive match is not necessary). Open vSwitch enforces this.
+.IP \(bu
+Each dimension within a conjunctive match should ordinarily have more
+than one flow. Open vSwitch does not enforce this.
+.RE
+.IP
+The \fBconjunction\fR action and \fBconj_id\fR field were introduced
+in Open vSwitch 2.4.
+.RE
.
.PP
An opaque identifier called a cookie can be used as a handle to identify
regardless of activity. A value of 0 (the default) gives the flow no
hard expiration deadline.
.
+.IP "\fBimportance=\fIvalue\fR"
+Sets the importance of a flow. The flow entry eviction mechanism can
+use importance as a factor in deciding which flow to evict. A value
+of 0 (the default) makes the flow non-evictable on the basis of
+importance. Specify a value between 0 and 65535.
+.IP
+Only OpenFlow 1.4 and later support \fBimportance\fR.
+.
.IP "\fBsend_flow_rem\fR"
Marks the flow with a flag that causes the switch to generate a ``flow
removed'' message and send it to interested controllers when the flow
.
.TP
\fBout_port=\fIport\fR
-If set, a matching flow must include an output action to \fIport\fR.
+If set, a matching flow must include an output action to \fIport\fR,
+which must be an OpenFlow port number or name (e.g. \fBlocal\fR).
.
.SS "Table Entry Output"
.
The integer number of seconds that have passed without any packets
passing through the flow.
.
+.SS "Group Syntax"
+.PP
+Some \fBovs\-ofctl\fR commands accept an argument that describes a group or
+groups. Such flow descriptions comprise a series
+\fIfield\fB=\fIvalue\fR assignments, separated by commas or white
+space. (Embedding spaces into a group description normally requires
+quoting to prevent the shell from breaking the description into
+multiple arguments.). Unless noted otherwise only the last instance
+of each field is honoured.
+.PP
+.IP \fBgroup_id=\fIid\fR
+The integer group id of group.
+When this field is specified in \fBdel\-groups\fR or \fBdump\-groups\fR,
+the keyword "all" may be used to designate all groups.
+.
+This field is required.
+
+
+.IP \fBtype=\fItype\fR
+The type of the group. The \fBadd-group\fR, \fBadd-groups\fR and
+\fBmod-groups\fR commands require this field. It is prohibited for
+other commands. The following keywords designated the allowed types:
+.RS
+.IP \fBall\fR
+Execute all buckets in the group.
+.IP \fBselect\fR
+Execute one bucket in the group.
+The switch should select the bucket in such a way that should implement
+equal load sharing is achieved. The switch may optionally select the
+bucket based on bucket weights.
+.IP \fBindirect\fR
+Executes the one bucket in the group.
+.IP \fBff\fR
+.IQ \fBfast_failover\fR
+Executes the first live bucket in the group which is associated with
+a live port or group.
+.RE
+
+.IP \fBcommand_bucket_id=\fIid\fR
+The bucket to operate on. The \fBinsert-buckets\fR and \fBremove-buckets\fR
+commands require this field. It is prohibited for other commands.
+\fIid\fR may be an integer or one of the following keywords:
+.RS
+.IP \fBall\fR
+Operate on all buckets in the group.
+Only valid when used with the \fBremove-buckets\fR command in which
+case the effect is to remove all buckets from the group.
+.IP \fBfirst\fR
+Operate on the first bucket present in the group.
+In the case of the \fBinsert-buckets\fR command the effect is to
+insert new bucets just before the first bucket already present in the group;
+or to replace the buckets of the group if there are no buckets already present
+in the group.
+In the case of the \fBremove-buckets\fR command the effect is to
+remove the first bucket of the group; or do nothing if there are no
+buckets present in the group.
+.IP \fBlast\fR
+Operate on the last bucket present in the group.
+In the case of the \fBinsert-buckets\fR command the effect is to
+insert new bucets just after the last bucket already present in the group;
+or to replace the buckets of the group if there are no buckets already present
+in the group.
+In the case of the \fBremove-buckets\fR command the effect is to
+remove the last bucket of the group; or do nothing if there are no
+buckets present in the group.
+.RE
+.IP
+If \fIid\fR is an integer then it should correspond to the \fBbucket_id\fR
+of a bucket present in the group.
+In case of the \fBinsert-buckets\fR command the effect is to
+insert buckets just before the bucket in the group whose \fBbucket_id\fR is
+\fIid\fR.
+In case of the \fBiremove-buckets\fR command the effect is to
+remove the in the group whose \fBbucket_id\fR is \fIid\fR.
+It is an error if there is no bucket persent group in whose \fBbucket_id\fR is
+\fIid\fR.
+
+.IP \fBselection_method\fR=\fImethod\fR
+The selection method used to select a bucket for a select group.
+This is a string of 1 to 15 bytes in length known to lower layers.
+This field is optional for \fBadd\-group\fR, \fBadd\-groups\fR and
+\fBmod\-group\fR commands on groups of type \fBselect\fR. Prohibited
+otherwise. The default value is the empty string.
+.IP
+This option will use a Netronome OpenFlow extension which is only supported
+when using Open vSwitch 2.4 and later with OpenFlow 1.5 and later.
+
+.IP \fBselection_method_param\fR=\fIparam\fR
+64-bit integer parameter to the selection method selected by the
+\fBselection_method\fR field. The parameter's use is defined by the
+lower-layer that implements the \fBselection_method\fR. It is optional if
+the \fBselection_method\fR field is specified as a non-empty string.
+Prohibited otherwise. The default value is zero.
+.IP
+This option will use a Netronome OpenFlow extension which is only supported
+when using Open vSwitch 2.4 and later with OpenFlow 1.5 and later.
+
+.IP \fBfields\fR=\fIparam\fR
+The field parameters to selection method selected by the
+\fBselection_method\fR field. The syntax is described in \fBFlow Syntax\fR
+with the additional restrictions that if a value is provided it is
+treated as a wildcard mask and wildcard masks following a slash are
+prohibited. The pre-requisites of fields must be provided by any flows that
+output to the group. The use of the fields is defined by the lower-layer
+that implements the \fBselection_method\fR. They are optional if the
+\fBselection_method\fR field is specified as a non-empty string.
+Prohibited otherwise. The default is no fields.
+.IP
+This option will use a Netronome OpenFlow extension which is only supported
+when using Open vSwitch 2.4 and later with OpenFlow 1.5 and later.
+
+.IP \fBbucket\fR=\fIbucket_parameters\fR
+The \fBadd-group\fR, \fBadd-groups\fR and \fBmod-group\fR commands
+require at least one bucket field. Bucket fields must appear after
+all other fields.
+.
+Multiple bucket fields to specify multiple buckets.
+The order in which buckets are specified corresponds to their order in
+the group. If the type of the group is "indirect" then only one group may
+be specified.
+.
+\fIbucket_parameters\fR consists of a list of \fIfield\fB=\fIvalue\fR
+assignments, separated by commas or white space followed by a
+comma-separated list of actions.
+The fields for \fIbucket_parameters\fR are:
+.
+.RS
+.IP \fBbucket_id=\fIid\fR
+The 32-bit integer group id of the bucket. Values greater than
+0xffffff00 are reserved.
+.
+This field was added in Open vSwitch 2.4 to conform with the OpenFlow
+1.5 specification. It is not supported when earlier versions
+of OpenFlow are used. Open vSwitch will automatically allocate bucket
+ids when they are not specified.
+.IP \fBactions=\fR[\fIaction\fR][\fB,\fIaction\fR...]\fR
+The syntax of actions are identical to the \fBactions=\fR field described in
+\fBFlow Syntax\fR above. Specyfing \fBactions=\fR is optional, any unknown
+bucket parameter will be interpreted as an action.
+.IP \fBweight=\fIvalue\fR
+The relative weight of the bucket as an integer. This may be used by the switch
+during bucket select for groups whose \fBtype\fR is \fBselect\fR.
+.IP \fBwatch_port=\fIport\fR
+Port used to determine liveness of group.
+This or the \fBwatch_group\fR field is required
+for groups whose \fBtype\fR is \fBff\fR or \fBfast_failover\fR.
+.IP \fBwatch_group=\fIgroup_id\fR
+Group identifier of group used to determine liveness of group.
+This or the \fBwatch_port\fR field is required
+for groups whose \fBtype\fR is \fBff\fR or \fBfast_failover\fR.
+.RE
+.
+.SS "Meter Syntax"
+.PP
+The meter table commands accept an argument that describes a meter.
+Such meter descriptions comprise a series \fIfield\fB=\fIvalue\fR
+assignments, separated by commas or white space.
+(Embedding spaces into a group description normally requires
+quoting to prevent the shell from breaking the description into
+multiple arguments.). Unless noted otherwise only the last instance
+of each field is honoured.
+.PP
+.IP \fBmeter=\fIid\fR
+The integer meter id of the meter.
+When this field is specified in \fBdel-meter\fR, \fBdump-meter\fR, or
+\fBmeter-stats\fR, the keyword "all" may be used to designate all meters.
+.
+This field is required, exept for \fBmeter-stats\fR, which dumps all stats
+when this field is not specified.
+
+.IP \fBkbps\fR
+.IQ \fBpktps\fR
+The unit for the meter band rate parameters, either kilobits per second, or
+packets per second, respectively. One of these must be specified. The burst
+size unit corresponds to the rate unit by dropping the "per second", i.e.,
+burst is in units of kilobits or packets, respectively.
+
+.IP \fBburst\fR
+Specify burst size for all bands, or none of them, if this flag is not given.
+
+.IP \fBstats\fR
+Collect meter and band statistics.
+
+.IP \fBbands\fR=\fIband_parameters\fR
+The \fBadd-meter\fR and \fBmod-meter\fR commands require at least one
+band specification. Bands must appear after all other fields.
+.RS
+.IP \fBtype=\fItype\fR
+The type of the meter band. This keyword starts a new band specification.
+Each band specifies a rate above which the band is to take some action. The
+action depends on the band type. If multiple bands' rate is exceeded, then
+the band with the highest rate among the exceeded bands is selected.
+The following keywords designate the allowed
+meter band types:
+.RS
+.IP \fBdrop\fR
+Drop packets exceeding the band's rate limit.
+.RE
+.
+.IP "The other \fIband_parameters\fR are:"
+.IP \fBrate=\fIvalue\fR
+The relative rate limit for this band, in kilobits per second or packets per
+second, depending on the meter flags defined above.
+.IP \fBburst_size=\fIsize\fR
+The maximum burst allowed for the band. If \fBpktps\fR is specified,
+then \fIsize\fR is a packet count, otherwise it is in kilobits. If
+unspecified, the switch is free to select some reasonable value
+depending on its configuration.
+.RE
+.
.SH OPTIONS
.TP
\fB\-\-strict\fR
Uses strict matching when running flow modification commands.
.
+.IP "\fB\-\-bundle\fR"
+Execute flow mods as an OpenFlow 1.4 atomic bundle transaction.
+.RS
+.IP \(bu
+Within a bundle, all flow mods are processed in the order they appear
+and as a single atomic transaction, meaning that if one of them fails,
+the whole transaction fails and none of the changes are made to the
+\fIswitch\fR's flow table, and that each given datapath packet
+traversing the OpenFlow tables sees the flow tables either as before
+the transaction, or after all the flow mods in the bundle have been
+successfully applied.
+.IP \(bu
+The beginning and the end of the flow table modification commands in a
+bundle are delimited with OpenFlow 1.4 bundle control messages, which
+makes it possible to stream the included commands without explicit
+OpenFlow barriers, which are otherwise used after each flow table
+modification command. This may make large modifications execute
+faster as a bundle.
+.IP \(bu
+Bundles require OpenFlow 1.4 or higher. An explicit \fB-O
+OpenFlow14\fR option is not needed, but you may need to enable
+OpenFlow 1.4 support for OVS by setting the OVSDB \fIprotocols\fR
+column in the \fIbridge\fR table.
+.RE
+.
+.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
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"
+.IQ "\fBOXM-OpenFlow14\fR"
+These are the standard OXM (OpenFlow Extensible Match) flow format in
+OpenFlow 1.2, 1.3, and 1.4, respectively.
.RE
.
.IP
\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, \fBOXM-OpenFlow13\fR, or \fBOXM-OpenFlow14\fR.
.RE
.
.IP
.
.IP "\fB\-\-timestamp\fR"
Print a timestamp before each received packet. This option only
-affects the \fBmonitor\fR and \fBsnoop\fR commands.
+affects the \fBmonitor\fR, \fBsnoop\fR, and \fBofp\-parse\-pcap\fR
+commands.
.
.IP "\fB\-m\fR"
.IQ "\fB\-\-more\fR"
sorted after all the flows that do specify the field. For example,
\fB\-\-sort=tcp_src\fR will sort all the flows that specify a TCP
source port in ascending order, followed by the flows that do not
-specify a TCP source port at all.
+specify a TCP source port at all.
.IP \(bu
A flow that only specifies some bits in a field is sorted as if the
wildcarded bits were zero. For example, \fB\-\-sort=nw_src\fR would
\fBovs\-ofctl\fR detaches only when executing the \fBmonitor\fR or \
\fBsnoop\fR commands.
.so lib/daemon.man
+.so lib/unixctl.man
.SS "Public Key Infrastructure Options"
.so lib/ssl.man
.so lib/vlog.man
.SH "SEE ALSO"
.
.BR ovs\-appctl (8),
-.BR ovs\-controller (8),
.BR ovs\-vswitchd (8)
+.BR ovs\-vswitchd.conf.db (8)
projects / cascardo / ovs.git / blobdiff