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