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