utilities/ovs-ofctl.8.in

   1 .\" -*- nroff -*-
   2 .de IQ
   3 .  br
   4 .  ns
   5 .  IP "\\$1"
   6 ..
   7 .TH ovs\-ofctl 8 "January 2011" "Open vSwitch" "Open vSwitch Manual"
   8 .ds PN ovs\-ofctl
   9 .
  10 .SH NAME
  11 ovs\-ofctl \- administer OpenFlow switches
  12 .
  13 .SH SYNOPSIS
  14 .B ovs\-ofctl
  15 [\fIoptions\fR] \fIcommand \fR[\fIswitch\fR] [\fIargs\fR\&...]
  16 .
  17 .SH DESCRIPTION
  18 The
  19 .B ovs\-ofctl
  20 program is a command line tool for monitoring and administering
  21 OpenFlow switches.  It can also show the current state of an OpenFlow
  22 switch, including features, configuration, and table entries.
  23 .
  24 .SS "OpenFlow Switch Management Commands"
  25 .PP
  26 These commands allow \fBovs\-ofctl\fR to monitor and administer an OpenFlow
  27 switch.  It is able to show the current state of a switch, including
  28 features, configuration, and table entries.
  29 .PP
  30 Most of these commands take an argument that specifies the method for
  31 connecting to an OpenFlow switch.  The following connection methods
  32 are supported:
  33 .
  34 .RS
  35 .so lib/vconn-active.man
  36 .
  37 .IP "\fIfile\fR"
  38 This is short for \fBunix:\fIfile\fR, as long as \fIfile\fR does not
  39 contain a colon.
  40 .
  41 .IP \fIbridge\fR
  42 This is short for \fBunix:@RUNDIR@/\fIbridge\fB.mgmt\fR, as long as
  43 \fIbridge\fR does not contain a colon.
  44 .
  45 .IP [\fItype\fB@\fR]\fIdp\fR
  46 Attempts to look up the bridge associated with \fIdp\fR and open as
  47 above.  If \fItype\fR is given, it specifies the datapath provider of
  48 \fIdp\fR, otherwise the default provider \fBsystem\fR is assumed.
  49 .RE
  50 .
  51 .TP
  52 \fBshow \fIswitch\fR
  53 Prints to the console information on \fIswitch\fR, including
  54 information on its flow tables and ports.
  55 .
  56 .TP
  57 \fBdump\-tables \fIswitch\fR
  58 Prints to the console statistics for each of the flow tables used by
  59 \fIswitch\fR.
  60 .
  61 .TP
  62 \fBdump\-ports \fIswitch\fR [\fInetdev\fR]
  63 Prints to the console statistics for network devices associated with
  64 \fIswitch\fR.  If \fInetdev\fR is specified, only the statistics
  65 associated with that device will be printed.  \fInetdev\fR can be an
  66 OpenFlow assigned port number or device name, e.g. \fBeth0\fR.
  67 .
  68 .TP
  69 \fBmod\-port \fIswitch\fR \fInetdev\fR \fIaction\fR
  70 Modify characteristics of an interface monitored by \fIswitch\fR.
  71 \fInetdev\fR can be referred to by its OpenFlow assigned port number or
  72 the device name, e.g. \fBeth0\fR.  The \fIaction\fR may be any one of the
  73 following:
  74 .
  75 .RS
  76 .IP \fBup\fR
  77 Enables the interface.  This is equivalent to ``ifconfig up'' on a Unix
  78 system.
  79 .
  80 .IP \fBdown\fR
  81 Disables the interface.  This is equivalent to ``ifconfig down'' on a Unix
  82 system.
  83 .
  84 .IP \fBflood\fR
  85 When a \fIflood\fR action is specified, traffic will be sent out this
  86 interface.  This is the default posture for monitored ports.
  87 .
  88 .IP \fBnoflood\fR
  89 When a \fIflood\fR action is specified, traffic will not be sent out
  90 this interface.  This is primarily useful to prevent loops when a
  91 spanning tree protocol is not in use.
  92 .
  93 .RE
  94 .
  95 .TP
  96 \fBdump\-flows \fIswitch \fR[\fIflows\fR]
  97 Prints to the console all flow entries in \fIswitch\fR's
  98 tables that match \fIflows\fR.  If \fIflows\fR is omitted, all flows
  99 in the switch are retrieved.  See \fBFlow Syntax\fR, below, for the
 100 syntax of \fIflows\fR.  The output format is described in
 101 \fBTable Entry Output\fR.
 102 .
 103 .TP
 104 \fBdump\-aggregate \fIswitch \fR[\fIflows\fR]
 105 Prints to the console aggregate statistics for flows in
 106 \fIswitch\fR's tables that match \fIflows\fR.  If \fIflows\fR is omitted,
 107 the statistics are aggregated across all flows in the switch's flow
 108 tables.  See \fBFlow Syntax\fR, below, for the syntax of \fIflows\fR.
 109 The output format is descrbed in \fBTable Entry Output\fR.
 110 .
 111 .IP "\fBqueue\-stats \fIswitch \fR[\fIport \fR[\fIqueue\fR]]"
 112 Prints to the console statistics for the specified \fIqueue\fR on
 113 \fIport\fR within \fIswitch\fR.  Either of \fIport\fR or \fIqueue\fR
 114 or both may be omitted (or equivalently specified as \fBALL\fR).  If
 115 both are omitted, statistics are printed for all queues on all ports.
 116 If only \fIqueue\fR is omitted, then statistics are printed for all
 117 queues on \fIport\fR; if only \fIport\fR is omitted, then statistics
 118 are printed for \fIqueue\fR on every port where it exists.
 119 .
 120 .TP
 121 \fBadd\-flow \fIswitch flow\fR
 122 Add the flow entry as described by \fIflow\fR to the \fIswitch\fR's
 123 tables.  The flow entry is in the format described in \fBFlow Syntax\fR,
 124 below.
 125 .
 126 .TP
 127 \fBadd\-flows \fIswitch file\fR
 128 Add the flow entries listed in \fIfile\fR, or supplied on \fBstdin\fR
 129 if \fIfile\fR is \fB\-\fR, to \fIswitch\fR's
 130 tables.  Each line in \fIfile\fR is a flow entry in the format
 131 described in \fBFlow Syntax\fR, below.
 132 .
 133 .TP
 134 \fBmod\-flows \fIswitch flow\fR
 135 Modify the actions in entries from the \fIswitch\fR's tables
 136 that match \fIflow\fR.  When invoked with the \fB\-\-strict\fR option,
 137 wildcards are not treated as active for matching purposes.  See
 138 \fBFlow Syntax\fR, below, for the syntax of \fIflows\fR.
 139 .
 140 .TP
 141 \fBdel\-flows \fIswitch \fR[\fIflow\fR]
 142 Deletes entries from the \fIswitch\fR's tables that match
 143 \fIflow\fR.  When invoked with the \fB\-\-strict\fR option, wildcards are
 144 not treated as active for matching purposes.  If \fIflow\fR is
 145 omitted and the \fB\-\-strict\fR option is not used, all flows in the
 146 switch's tables are removed.  See \fBFlow Syntax\fR, below, for the
 147 syntax of \fIflows\fR.
 148 .
 149 .IP "\fBsnoop \fIswitch\fR"
 150 Connects to \fIswitch\fR and prints to the console all OpenFlow
 151 messages received.  Unlike other \fBovs\-ofctl\fR commands, if
 152 \fIswitch\fR is the name of a bridge, then the \fBsnoop\fR command
 153 connects to a Unix domain socket named
 154 \fB@RUNDIR@/\fIbridge\fB.snoop\fR.  \fBovs\-vswitchd\fR listens on
 155 such a socket for each bridge and sends to it all of the OpenFlow
 156 messages sent to or received from its configured OpenFlow controller.
 157 Thus, this command can be used to view OpenFlow protocol activity
 158 between a switch and its controller.
 159 .IP
 160 When a switch has more than one controller configured, only the
 161 traffic to and from a single controller is output.  If none of the
 162 controllers is configured as a master or a slave (using a Nicira
 163 extension to OpenFlow), then a controller is chosen arbitrarily among
 164 them.  If there is a master controller, it is chosen; otherwise, if
 165 there are any controllers that are not masters or slaves, one is
 166 chosen arbitrarily; otherwise, a slave controller is chosen
 167 arbitrarily.  This choice is made once at connection time and does not
 168 change as controllers reconfigure their roles.
 169 .IP
 170 If a switch has no controller configured, or if
 171 the configured controller is disconnected, no traffic is sent, so
 172 monitoring will not show any traffic.
 173 .
 174 .IQ "\fBmonitor \fIswitch\fR [\fImiss-len\fR]"
 175 Connects to \fIswitch\fR and prints to the console all OpenFlow
 176 messages received.  Usually, \fIswitch\fR should specify a connection
 177 named on \fBovs\-openflowd\fR(8)'s \fB\-l\fR or \fB\-\-listen\fR command line
 178 option.
 179 .IP
 180 If \fImiss-len\fR is provided, \fBovs\-ofctl\fR sends an OpenFlow ``set
 181 configuration'' message at connection setup time that requests
 182 \fImiss-len\fR bytes of each packet that misses the flow table.  Open vSwitch
 183 does not send these and other asynchronous messages to an
 184 \fBovs\-ofctl monitor\fR client connection unless a nonzero value is
 185 specified on this argument.  (Thus, if \fImiss\-len\fR is not
 186 specified, very little traffic will ordinarily be printed.)
 187 .IP
 188 This command may be useful for debugging switch or controller
 189 implementations.
 190 .
 191 .SS "OpenFlow Switch and Controller Commands"
 192 .
 193 The following commands, like those in the previous section, may be
 194 applied to OpenFlow switches, using any of the connection methods
 195 described in that section.  Unlike those commands, these may also be
 196 applied to OpenFlow controllers.
 197 .
 198 .TP
 199 \fBprobe \fItarget\fR
 200 Sends a single OpenFlow echo-request message to \fItarget\fR and waits
 201 for the response.  With the \fB\-t\fR or \fB\-\-timeout\fR option, this
 202 command can test whether an OpenFlow switch or controller is up and
 203 running.
 204 .
 205 .TP
 206 \fBping \fItarget \fR[\fIn\fR]
 207 Sends a series of 10 echo request packets to \fItarget\fR and times
 208 each reply.  The echo request packets consist of an OpenFlow header
 209 plus \fIn\fR bytes (default: 64) of randomly generated payload.  This
 210 measures the latency of individual requests.
 211 .
 212 .TP
 213 \fBbenchmark \fItarget n count\fR
 214 Sends \fIcount\fR echo request packets that each consist of an
 215 OpenFlow header plus \fIn\fR bytes of payload and waits for each
 216 response.  Reports the total time required.  This is a measure of the
 217 maximum bandwidth to \fItarget\fR for round-trips of \fIn\fR-byte
 218 messages.
 219 .
 220 .SS "Flow Syntax"
 221 .PP
 222 Some \fBovs\-ofctl\fR commands accept an argument that describes a flow or
 223 flows.  Such flow descriptions comprise a series
 224 \fIfield\fB=\fIvalue\fR assignments, separated by commas or white
 225 space.  (Embedding spaces into a flow description normally requires
 226 quoting to prevent the shell from breaking the description into
 227 multiple arguments.)
 228 .PP
 229 Flow descriptions should be in \fBnormal form\fR.  This means that a
 230 flow may only specify a value for an L3 field if it also specifies a
 231 particular L2 protocol, and that a flow may only specify an L4 field
 232 if it also specifies particular L2 and L3 protocol types.  For
 233 example, if the L2 protocol type \fBdl_type\fR is wildcarded, then L3
 234 fields \fBnw_src\fR, \fBnw_dst\fR, and \fBnw_proto\fR must also be
 235 wildcarded.  Similarly, if \fBdl_type\fR or \fBnw_proto\fR (the L3
 236 protocol type) is wildcarded, so must be \fBtp_dst\fR and
 237 \fBtp_src\fR, which are L4 fields.  \fBovs\-ofctl\fR will warn about
 238 flows not in normal form.
 239 .PP
 240 The following field assignments describe how a flow matches a packet.
 241 If any of these assignments is omitted from the flow syntax, the field
 242 is treated as a wildcard; thus, if all of them are omitted, the
 243 resulting flow matches all packets.  The string \fB*\fR or \fBANY\fR
 244 may be specified to explicitly mark any of these fields as a wildcard.
 245 (\fB*\fR should be quoted to protect it from shell expansion.)
 246 .
 247 .IP \fBin_port=\fIport_no\fR
 248 Matches physical port \fIport_no\fR.  Switch ports are numbered as
 249 displayed by \fBovs\-ofctl show\fR.
 250 .
 251 .IP \fBdl_vlan=\fIvlan\fR
 252 Matches IEEE 802.1q Virtual LAN tag \fIvlan\fR.  Specify \fB0xffff\fR
 253 as \fIvlan\fR to match packets that are not tagged with a Virtual LAN;
 254 otherwise, specify a number between 0 and 4095, inclusive, as the
 255 12-bit VLAN ID to match.
 256 .
 257 .IP \fBdl_vlan_pcp=\fIpriority\fR
 258 Matches IEEE 802.1q Priority Code Point (PCP) \fIpriority\fR, which is
 259 specified as a value between 0 and 7, inclusive.  A higher value
 260 indicates a higher frame priority level.
 261 .
 262 .IP \fBdl_src=\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fR
 263 .IQ \fBdl_dst=\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fR
 264 Matches an Ethernet source (or destination) address specified as 6
 265 pairs of hexadecimal digits delimited by colons
 266 (e.g. \fB00:0A:E4:25:6B:B0\fR).
 267 .
 268 .IP \fBdl_type=\fIethertype\fR
 269 Matches Ethernet protocol type \fIethertype\fR, which is specified as an
 270 integer between 0 and 65535, inclusive, either in decimal or as a
 271 hexadecimal number prefixed by \fB0x\fR (e.g. \fB0x0806\fR to match ARP
 272 packets).
 273 .
 274 .IP \fBnw_src=\fIip\fR[\fB/\fInetmask\fR]
 275 .IQ \fBnw_dst=\fIip\fR[\fB/\fInetmask\fR]
 276 When \fBdl_type\fR is 0x0800 (possibly via shorthand, e.g. \fBip\fR
 277 or \fBtcp\fR), matches IPv4 source (or destination) address \fIip\fR,
 278 which may be specified as an IP address or host name
 279 (e.g. \fB192.168.1.1\fR or \fBwww.example.com\fR).  The optional
 280 \fInetmask\fR allows restricting a match to an IPv4 address prefix.
 281 The netmask may be specified as a dotted quad
 282 (e.g. \fB192.168.1.0/255.255.255.0\fR) or as a CIDR block
 283 (e.g. \fB192.168.1.0/24\fR).
 284 .IP
 285 When \fBdl_type=0x0806\fR or \fBarp\fR is specified, matches the
 286 \fBar_spa\fR or \fBar_tpa\fR field, respectively, in ARP packets for
 287 IPv4 and Ethernet.
 288 .IP
 289 When \fBdl_type\fR is wildcarded or set to a value other than 0x0800
 290 or 0x0806, the values of \fBnw_src\fR and \fBnw_dst\fR are ignored
 291 (see \fBFlow Syntax\fR above).
 292 .
 293 .IP \fBnw_proto=\fIproto\fR
 294 When \fBip\fR or \fBdl_type=0x0800\fR is specified, matches IP
 295 protocol type \fIproto\fR, which is specified as a decimal number
 296 between 0 and 255, inclusive (e.g. 1 to match ICMP packets or 6 to match
 297 TCP packets).
 298 .IP
 299 When \fBipv6\fR or \fBdl_type=0x86dd\fR is specified, matches IPv6
 300 header type \fIproto\fR, which is specified as a decimal number between
 301 0 and 255, inclusive (e.g. 58 to match ICMPv6 packets or 6 to match
 302 TCP).  The header type is the terminal header as described in the
 303 \fBDESIGN\fR document.
 304 .IP
 305 When \fBarp\fR or \fBdl_type=0x0806\fR is specified, matches the lower
 306 8 bits of the ARP opcode.  ARP opcodes greater than 255 are treated as
 307 0.
 308 .IP
 309 When \fBdl_type\fR is wildcarded or set to a value other than 0x0800,
 310 0x0806, or 0x86dd, the value of \fBnw_proto\fR is ignored (see \fBFlow
 311 Syntax\fR above).
 312 .
 313 .IP \fBnw_tos=\fItos\fR
 314 Matches IP ToS/DSCP or IPv6 traffic class field \fItos\fR, which is
 315 specified as a decimal number between 0 and 255, inclusive.  Note that
 316 the two lower reserved bits are ignored for matching purposes.
 317 .IP
 318 When \fBdl_type\fR is wildcarded or set to a value other than 0x0800,
 319 0x0806, or 0x86dd, the value of \fBnw_tos\fR is ignored (see \fBFlow
 320 Syntax\fR above).
 321 .
 322 .IP \fBtp_src=\fIport\fR
 323 .IQ \fBtp_dst=\fIport\fR
 324 When \fBdl_type\fR and \fBnw_proto\fR specify TCP or UDP, \fBtp_src\fR
 325 and \fBtp_dst\fR match the UDP or TCP source or destination port
 326 \fIport\fR, respectively. which is specified as a decimal number
 327 between 0 and 65535, inclusive (e.g. 80 to match packets originating
 328 from a HTTP server).
 329 .IP
 330 When \fBdl_type\fR and \fBnw_proto\fR take other values, the values of
 331 these settings are ignored (see \fBFlow Syntax\fR above).
 332 .
 333 .IP \fBicmp_type=\fItype\fR
 334 .IQ \fBicmp_code=\fIcode\fR
 335 When \fBdl_type\fR and \fBnw_proto\fR specify ICMP or ICMPv6, \fItype\fR
 336 matches the ICMP type and \fIcode\fR matches the ICMP code.  Each is
 337 specified as a decimal number between 0 and 255, inclusive.
 338 .IP
 339 When \fBdl_type\fR and \fBnw_proto\fR take other values, the values of
 340 these settings are ignored (see \fBFlow Syntax\fR above).
 341 .
 342 .PP
 343 The following shorthand notations are also available:
 344 .
 345 .IP \fBip\fR
 346 Same as \fBdl_type=0x0800\fR.
 347 .
 348 .IP \fBicmp\fR
 349 Same as \fBdl_type=0x0800,nw_proto=1\fR.
 350 .
 351 .IP \fBtcp\fR
 352 Same as \fBdl_type=0x0800,nw_proto=6\fR.
 353 .
 354 .IP \fBudp\fR
 355 Same as \fBdl_type=0x0800,nw_proto=17\fR.
 356 .
 357 .IP \fBarp\fR
 358 Same as \fBdl_type=0x0806\fR.
 359 .
 360 .PP
 361 The following field assignments require support for the NXM (Nicira
 362 Extended Match) extension to OpenFlow.  When one of these is specified,
 363 \fBovs\-ofctl\fR will automatically attempt to negotiate use of this
 364 extension.  If the switch does not support NXM, then \fBovs\-ofctl\fR
 365 will report a fatal error.
 366 .
 367 .IP \fBarp_sha=\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fR
 368 .IQ \fBarp_tha=\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fR
 369 When \fBdl_type\fR specifies ARP, \fBarp_sha\fR and \fBarp_tha\fR match
 370 the source and target hardware address, respectively.  An address is
 371 specified as 6 pairs of hexadecimal digits delimited by colons.
 372 .
 373 .IP \fBipv6_src=\fIipv6\fR[\fB/\fInetmask\fR]
 374 .IQ \fBipv6_dst=\fIipv6\fR[\fB/\fInetmask\fR]
 375 When \fBdl_type\fR is 0x86dd (possibly via shorthand, e.g., \fBipv6\fR
 376 or \fBtcp6\fR), matches IPv6 source (or destination) address \fIipv6\fR,
 377 which may be specified as defined in RFC 2373.  The preferred format is
 378 \fIx\fB:\fIx\fB:\fIx\fB:\fIx\fB:\fIx\fB:\fIx\fB:\fIx\fB:\fIx\fR, where
 379 \fIx\fR are the hexadecimal values of the eight 16-bit pieces of the
 380 address.  A single instance of \fB::\fR may be used to indicate multiple
 381 groups of 16-bits of zeros.  The optional \fInetmask\fR allows
 382 restricting a match to an IPv6 address prefix.  A netmask is specified
 383 as a CIDR block (e.g. \fB2001:db8:3c4d:1::/64\fR).
 384 .
 385 .IP \fBnd_target=\fIipv6\fR
 386 When \fBdl_type\fR, \fBnw_proto\fR, and \fBicmp_type\fR specify
 387 IPv6 Neighbor Discovery (ICMPv6 type 135 or 136), matches the target address
 388 \fIipv6\fR.  \fIipv6\fR is in the same format described earlier for the
 389 \fBipv6_src\fR and \fBipv6_dst\fR fields.
 390 .
 391 .IP \fBnd_sll=\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fR
 392 When \fBdl_type\fR, \fBnw_proto\fR, and \fBicmp_type\fR specify IPv6
 393 Neighbor Solicitation (ICMPv6 type 135), matches the source link\-layer
 394 address option.  An address is specified as 6 pairs of hexadecimal
 395 digits delimited by colons.
 396 .
 397 .IP \fBnd_tll=\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fR
 398 When \fBdl_type\fR, \fBnw_proto\fR, and \fBicmp_type\fR specify IPv6
 399 Neighbor Advertisement (ICMPv6 type 136), matches the target link\-layer
 400 address option.  An address is specified as 6 pairs of hexadecimal
 401 digits delimited by colons.
 402 .
 403 .IP \fBtun_id=\fItunnel-id\fR[\fB/\fImask\fR]
 404 Matches tunnel identifier \fItunnel-id\fR.  Only packets that arrive
 405 over a tunnel that carries a key (e.g. GRE with the RFC 2890 key
 406 extension) will have a nonzero tunnel ID.  If \fImask\fR is omitted,
 407 \fItunnel-id\fR is the exact tunnel ID to match; if \fImask\fR is
 408 specified, then a 1-bit in \fImask\fR indicates that the corresponding
 409 bit in \fItunnel-id\fR must match exactly, and a 0-bit wildcards that
 410 bit.
 411 .IP
 412 In an attempt to be compatible with more switches, \fBovs\-ofctl\fR will
 413 prefer to use the ``tunnel ID from cookie'' Nicira extension to NXM.
 414 The use of this extension comes with three caveats: the top 32 bits of
 415 the \fBcookie\fR (see below) are used for \fItunnel-id\fR and thus
 416 unavailable for other use, specifying \fBtun_id\fR on \fBdump\-flows\fR
 417 or \fBdump\-aggregate\fR has no effect, and \fImask\fR is not supported.
 418 If any of these caveats apply, \fBovs-ofctl\fR will use NXM.
 419 .
 420 .IP "\fBreg\fIidx\fB=\fIvalue\fR[\fB/\fImask\fR]"
 421 Matches \fIvalue\fR either exactly or with optional \fImask\fR in
 422 register number \fIidx\fR.  The valid range of \fIidx\fR depends on
 423 the switch.  \fIvalue\fR and \fImask\fR are 32-bit integers, by
 424 default in decimal (use a \fB0x\fR prefix to specify hexadecimal).
 425 Arbitrary \fImask\fR values are allowed: a 1-bit in \fImask\fR
 426 indicates that the corresponding bit in \fIvalue\fR must match
 427 exactly, and a 0-bit wildcards that bit.
 428 .IP
 429 When a packet enters an OpenFlow switch, all of the registers are set
 430 to 0.  Only explicit Nicira extension actions change register values.
 431 .
 432 .PP
 433 Defining IPv6 flows (those with \fBdl_type\fR equal to 0x86dd) requires
 434 support for NXM.  The following shorthand notations are available for
 435 IPv6-related flows:
 436 .
 437 .IP \fBipv6\fR
 438 Same as \fBdl_type=0x86dd\fR.
 439 .
 440 .IP \fBtcp6\fR
 441 Same as \fBdl_type=0x86dd,nw_proto=6\fR.
 442 .
 443 .IP \fBudp6\fR
 444 Same as \fBdl_type=0x86dd,nw_proto=17\fR.
 445 .
 446 .IP \fBicmp6\fR
 447 Same as \fBdl_type=0x86dd,nw_proto=58\fR.
 448 .
 449 .PP
 450 The \fBadd\-flow\fR and \fBadd\-flows\fR commands require an additional
 451 field, which must be the final field specified:
 452 .
 453 .IP \fBactions=\fR[\fItarget\fR][\fB,\fItarget\fR...]\fR
 454 Specifies a comma-separated list of actions to take on a packet when the
 455 flow entry matches.  If no \fItarget\fR is specified, then packets
 456 matching the flow are dropped.  The \fItarget\fR may be a decimal port
 457 number designating the physical port on which to output the packet, or one
 458 of the following keywords:
 459 .
 460 .RS
 461 .IP \fBoutput\fR:\fIport\fR
 462 Outputs the packet on the port specified by \fIport\fR.
 463 .
 464 .IP \fBenqueue\fR:\fIport\fB:\fIqueue\fR
 465 Enqueues the packet on the specified \fIqueue\fR within port
 466 \fIport\fR.  The number of supported queues depends on the switch;
 467 some OpenFlow implementations do not support queuing at all.
 468 .
 469 .IP \fBnormal\fR
 470 Subjects the packet to the device's normal L2/L3 processing.  (This
 471 action is not implemented by all OpenFlow switches.)
 472 .
 473 .IP \fBflood\fR
 474 Outputs the packet on all switch physical ports other than the port on
 475 which it was received and any ports on which flooding is disabled
 476 (typically, these would be ports disabled by the IEEE 802.1D spanning
 477 tree protocol).
 478 .
 479 .IP \fBall\fR
 480 Outputs the packet on all switch physical ports other than the port on
 481 which it was received.
 482 .
 483 .IP \fBcontroller\fR:\fImax_len\fR
 484 Sends the packet to the OpenFlow controller as a ``packet in''
 485 message.  If \fImax_len\fR is a number, then it specifies the maximum
 486 number of bytes that should be sent.  If \fImax_len\fR is \fBALL\fR or
 487 omitted, then the entire packet is sent.
 488 .
 489 .IP \fBlocal\fR
 490 Outputs the packet on the ``local port,'' which corresponds to the
 491 \fBof\fIn\fR network device (see \fBCONTACTING THE CONTROLLER\fR in
 492 \fBovs\-openflowd\fR(8) for information on the \fBof\fIn\fR network device).
 493 .
 494 .IP \fBdrop\fR
 495 Discards the packet, so no further processing or forwarding takes place.
 496 If a drop action is used, no other actions may be specified.
 497 .
 498 .IP \fBmod_vlan_vid\fR:\fIvlan_vid\fR
 499 Modifies the VLAN id on a packet.  The VLAN tag is added or modified
 500 as necessary to match the value specified.  If the VLAN tag is added,
 501 a priority of zero is used (see the \fBmod_vlan_pcp\fR action to set
 502 this).
 503 .
 504 .IP \fBmod_vlan_pcp\fR:\fIvlan_pcp\fR
 505 Modifies the VLAN priority on a packet.  The VLAN tag is added or modified
 506 as necessary to match the value specified.  Valid values are between 0
 507 (lowest) and 7 (highest).  If the VLAN tag is added, a vid of zero is used
 508 (see the \fBmod_vlan_vid\fR action to set this).
 509 .
 510 .IP \fBstrip_vlan\fR
 511 Strips the VLAN tag from a packet if it is present.
 512 .
 513 .IP \fBmod_dl_src\fB:\fImac\fR
 514 Sets the source Ethernet address to \fImac\fR.
 515 .
 516 .IP \fBmod_dl_dst\fB:\fImac\fR
 517 Sets the destination Ethernet address to \fImac\fR.
 518 .
 519 .IP \fBmod_nw_src\fB:\fIip\fR
 520 Sets the IPv4 source address to \fIip\fR.
 521 .
 522 .IP \fBmod_nw_dst\fB:\fIip\fR
 523 Sets the IPv4 destination address to \fIip\fR.
 524 .
 525 .IP \fBmod_tp_src\fB:\fIport\fR
 526 Sets the TCP or UDP source port to \fIport\fR.
 527 .
 528 .IP \fBmod_tp_dst\fB:\fIport\fR
 529 Sets the TCP or UDP destination port to \fIport\fR.
 530 .
 531 .IP \fBmod_nw_tos\fB:\fItos\fR
 532 Sets the IP ToS/DSCP field to \fItos\fR.  Valid values are between 0 and
 533 255, inclusive.  Note that the two lower reserved bits are never
 534 modified.
 535 .
 536 .RE
 537 .IP
 538 The following actions are Nicira vendor extensions that, as of this writing, are
 539 only known to be implemented by Open vSwitch:
 540 .
 541 .RS
 542 .
 543 .IP \fBresubmit\fB:\fIport\fR
 544 Re-searches the OpenFlow flow table with the \fBin_port\fR field
 545 replaced by \fIport\fR and executes the actions found, if any, in
 546 addition to any other actions in this flow entry.  Recursive
 547 \fBresubmit\fR actions are ignored.
 548 .
 549 .IP \fBset_tunnel\fB:\fIid\fR
 550 .IQ \fBset_tunnel64\fB:\fIid\fR
 551 If outputting to a port that encapsulates the packet in a tunnel and
 552 supports an identifier (such as GRE), sets the identifier to \fBid\fR.
 553 If the \fBset_tunnel\fR form is used and \fIid\fR fits in 32 bits,
 554 then this uses an action extension that is supported by Open vSwitch
 555 1.0 and later.  Otherwise, if \fIid\fR is a 64-bit value, it requires
 556 Open vSwitch 1.1 or later.
 557 .
 558 .IP \fBdrop_spoofed_arp\fR
 559 Stops processing further actions, if the packet being processed is an
 560 Ethernet+IPv4 ARP packet for which the source Ethernet address inside
 561 the ARP packet differs from the source Ethernet address in the
 562 Ethernet header.
 563 .IP
 564 This action is deprecated in favor of defining flows using the
 565 \fBarp_sha\fR match field described earlier and will likely be removed
 566 in a future version of Open vSwitch.
 567 .
 568 .IP \fBset_queue\fB:\fIqueue\fR
 569 Sets the queue that should be used to \fIqueue\fR when packets are
 570 output.  The number of supported queues depends on the switch; some
 571 OpenFlow implementations do not support queuing at all.
 572 .
 573 .IP \fBpop_queue\fR
 574 Restores the queue to the value it was before any \fBset_queue\fR
 575 actions were applied.
 576 .
 577 .IP \fBnote:\fR[\fIhh\fR]...
 578 Does nothing at all.  Any number of bytes represented as hex digits
 579 \fIhh\fR may be included.  Pairs of hex digits may be separated by
 580 periods for readability.
 581 .
 582 .IP "\fBmove:\fIsrc\fB[\fIstart\fB..\fIend\fB]->\fIdst\fB[\fIstart\fB..\fIend\fB]\fR"
 583 Copies the named bits from field \fIsrc\fR to field \fIdst\fR.
 584 \fIsrc\fR and \fIdst\fR must be NXM field names as defined in
 585 \fBnicira\-ext.h\fR, e.g. \fBNXM_OF_UDP_SRC\fR or \fBNXM_NX_REG0\fR.
 586 Each \fIstart\fR and \fIend\fR pair, which are inclusive, must specify
 587 the same number of bits and must fit within its respective field.
 588 Shorthands for \fB[\fIstart\fB..\fIend\fB]\fR exist: use
 589 \fB[\fIbit\fB]\fR to specify a single bit or \fB[]\fR to specify an
 590 entire field.
 591 .IP
 592 Examples: \fBmove:NXM_NX_REG0[0..5]\->NXM_NX_REG1[26..31]\fR copies the
 593 six bits numbered 0 through 5, inclusive, in register 0 into bits 26
 594 through 31, inclusive;
 595 \fBmove:NXM_NX_REG0[0..15]->NXM_OF_VLAN_TCI[]\fR copies the least
 596 significant 16 bits of register 0 into the VLAN TCI field.
 597 .
 598 .IP "\fBload:\fIvalue\fB\->\fIdst\fB[\fIstart\fB..\fIend\fB]"
 599 Writes \fIvalue\fR to bits \fIstart\fR through \fIend\fR, inclusive,
 600 in field \fBdst\fR.
 601 .IP
 602 Example: \fBload:55\->NXM_NX_REG2[0..5]\fR loads value 55 (bit pattern
 603 \fB110111\fR) into bits 0 through 5, inclusive, in register 2.
 604 .
 605 .IP "\fBmultipath(\fIfields\fB, \fIbasis\fB, \fIalgorithm\fB, \fIn_links\fB, \fIarg\fB, \fIdst\fB[\fIstart\fB..\fIend\fB])\fR"
 606 Hashes \fIfields\fR using \fIbasis\fR as a universal hash parameter,
 607 then the applies multipath link selection \fIalgorithm\fR (with
 608 parameter \fIarg\fR) to choose one of \fIn_links\fR output links
 609 numbered 0 through \fIn_links\fR minus 1, and stores the link into
 610 \fIdst\fB[\fIstart\fB..\fIend\fB]\fR, which must be an NXM register as
 611 described above.
 612 .IP
 613 Currently, \fIfields\fR must be either \fBeth_src\fR or
 614 \fBsymmetric_l4\fR and \fIalgorithm\fR must be one of \fBmodulo_n\fR,
 615 \fBhash_threshold\fR, \fBhrw\fR, and \fBiter_hash\fR.  Only
 616 the \fBiter_hash\fR algorithm uses \fIarg\fR.
 617 .IP
 618 Refer to \fBnicira\-ext.h\fR for more details.
 619 .RE
 620 .
 621 .IP
 622 (The OpenFlow protocol supports other actions that \fBovs\-ofctl\fR does
 623 not yet expose to the user.)
 624 .
 625 .PP
 626 The \fBadd\-flow\fR, \fBadd\-flows\fR, and \fBmod\-flows\fR commands
 627 support an additional optional field:
 628 .
 629 .IP \fBcookie=\fIvalue\fR
 630 .
 631 A cookie is an opaque identifier that can be associated with the flow.
 632 \fIvalue\fR can be any 64-bit number and need not be unique among
 633 flows.
 634 .
 635 .PP
 636 The following additional field sets the priority for flows added by
 637 the \fBadd\-flow\fR and \fBadd\-flows\fR commands.  For
 638 \fBmod\-flows\fR and \fBdel\-flows\fR when \fB\-\-strict\fR is
 639 specified, priority must match along with the rest of the flow
 640 specification.  Other commands ignore the priority value.
 641 .
 642 .IP \fBpriority=\fIvalue\fR
 643 The priority at which a wildcarded entry will match in comparison to
 644 others.  \fIvalue\fR is a number between 0 and 65535, inclusive.  A higher
 645 \fIvalue\fR will match before a lower one.  An exact-match entry will always
 646 have priority over an entry containing wildcards, so it has an implicit
 647 priority value of 65535.  When adding a flow, if the field is not specified,
 648 the flow's priority will default to 32768.
 649 .
 650 .PP
 651 The \fBadd\-flow\fR and \fBadd\-flows\fR commands support additional
 652 optional fields:
 653 .
 654 .TP
 655 \fBidle_timeout=\fIseconds\fR
 656 Causes the flow to expire after the given number of seconds of
 657 inactivity.  A value of 0 (the default) prevents a flow from expiring due to
 658 inactivity.
 659 .
 660 .IP \fBhard_timeout=\fIseconds\fR
 661 Causes the flow to expire after the given number of seconds,
 662 regardless of activity.  A value of 0 (the default) gives the flow no
 663 hard expiration deadline.
 664 .
 665 .PP
 666 The \fBdump\-flows\fR, \fBdump\-aggregate\fR, \fBdel\-flow\fR
 667 and \fBdel\-flows\fR commands support one additional optional field:
 668 .
 669 .TP
 670 \fBout_port=\fIport\fR
 671 If set, a matching flow must include an output action to \fIport\fR.
 672 .
 673 .PP
 674 The \fBdump\-flows\fR and \fBdump\-aggregate\fR commands support an
 675 additional optional field:
 676 .
 677 .IP \fBtable=\fInumber\fR
 678 If specified, limits the flows about which statistics are gathered to
 679 those in the table with the given \fInumber\fR.  Tables are numbered
 680 as shown by the \fBdump\-tables\fR command.
 681 .
 682 If this field is not specified, or if \fInumber\fR is given as
 683 \fB255\fR, statistics are gathered about flows from all tables.
 684 .
 685 .SS "Table Entry Output"
 686 .
 687 The \fBdump\-tables\fR and \fBdump\-aggregate\fR commands print information
 688 about the entries in a datapath's tables.  Each line of output is a
 689 unique flow entry, which begins with some common information:
 690 .
 691 .IP \fBduration\fR
 692 The number of seconds the entry has been in the table.
 693 .
 694 .IP \fBtable_id\fR
 695 The table that contains the flow.  When a packet arrives, the switch
 696 begins searching for an entry at the lowest numbered table.  Tables are
 697 numbered as shown by the \fBdump\-tables\fR command.
 698 .
 699 .IP \fBpriority\fR
 700 The priority of the entry in relation to other entries within the same
 701 table.  A higher value will match before a lower one.
 702 .
 703 .IP \fBn_packets\fR
 704 The number of packets that have matched the entry.
 705 .
 706 .IP \fBn_bytes\fR
 707 The total number of bytes from packets that have matched the entry.
 708 .
 709 .PP
 710 The rest of the line consists of a description of the flow entry as
 711 described in \fBFlow Syntax\fR, above.
 712 .
 713 .
 714 .SH OPTIONS
 715 .TP
 716 \fB\-\-strict\fR
 717 Uses strict matching when running flow modification commands.
 718 .
 719 .IP "\fB\-F \fIformat\fR"
 720 .IQ "\fB\-\-flow\-format=\fIformat\fR"
 721 \fBovs\-ofctl\fR supports the following flow formats, in order of
 722 increasing capability:
 723 .RS
 724 .IP "\fBopenflow10\fR"
 725 This is the standard OpenFlow 1.0 flow format.  It should be supported
 726 by all OpenFlow switches.
 727 .
 728 .IP "\fBtun_id_from_cookie\fR"
 729 This Nicira extension to OpenFlow adds minimal and limited support for
 730 \fBtun_id\fR, but it does not support any other Nicira flow
 731 extensions.  (This flow format is deprecated.)
 732 .
 733 .IP "\fBnxm\fR (Nicira Extended Match)"
 734 This Nicira extension to OpenFlow is flexible and extensible.  It
 735 supports all of the Nicira flow extensions, such as \fBtun_id\fR and
 736 registers.
 737 .RE
 738 .IP
 739 Usually, \fBovs\-ofctl\fR picks the correct format automatically.  For
 740 commands that modify the flow table, \fBovs\-ofctl\fR by default uses
 741 the most widely supported flow format that supports the flows being
 742 added.  For commands that query the flow table, \fBovs\-ofctl\fR by
 743 default queries and uses the most advanced format supported by the
 744 switch.
 745 .IP
 746 This option, where \fIformat\fR is one of the formats listed in the
 747 above table, overrides \fBovs\-ofctl\fR's default choice of flow
 748 format.  If a command cannot work as requested using the requested
 749 flow format, \fBovs\-ofctl\fR will report a fatal error.
 750 .
 751 .IP "\fB\-m\fR"
 752 .IQ "\fB\-\-more\fR"
 753 Increases the verbosity of OpenFlow messages printed and logged by
 754 \fBovs\-ofctl\fR commands.  Specify this option more than once to
 755 increase verbosity further.
 756 .SS "Public Key Infrastructure Options"
 757 .so lib/ssl.man
 758 .so lib/vlog.man
 759 .so lib/common.man
 760 .
 761 .SH EXAMPLES
 762 .
 763 The following examples assume that an OpenFlow switch on the local
 764 host has been configured to listen for management connections on a
 765 Unix domain socket named \fB@RUNDIR@/openflow.sock\fR, e.g. by
 766 specifying \fB\-\-listen=punix:@RUNDIR@/openflow.sock\fR on the
 767 \fBovs\-openflowd\fR(8) command line.
 768 .
 769 .TP
 770 \fBovs\-ofctl dump\-tables unix:@RUNDIR@/openflow.sock\fR
 771 Prints out the switch's table stats.  (This is more interesting after
 772 some traffic has passed through.)
 773 .
 774 .TP
 775 \fBovs\-ofctl dump\-flows unix:@RUNDIR@/openflow.sock\fR
 776 Prints the flow entries in the switch.
 777 .
 778 .SH "SEE ALSO"
 779 .
 780 .BR ovs\-appctl (8),
 781 .BR ovs\-controller (8),
 782 .BR ovs\-vswitchd (8)