1ovs-ofctl(8) Open vSwitch Manual ovs-ofctl(8)
2
6 ovs-ofctl - administer OpenFlow switches
7
9 ovs-ofctl [options] command [switch] [args...]
10
12 The ovs-ofctl program is a command line tool for monitoring and admin‐
13 istering OpenFlow switches. It can also show the current state of an
14 OpenFlow switch, including features, configuration, and table entries.
15 It should work with any OpenFlow switch, not just Open vSwitch.
16 OpenFlow Switch Management Commands
18 These commands allow ovs-ofctl to monitor and administer an OpenFlow
19 switch. It is able to show the current state of a switch, including
20 features, configuration, and table entries.
21 Most of these commands take an argument that specifies the method for
23 connecting to an OpenFlow switch. The following connection methods are
24 supported:
25 ssl:ip[:port]
27 The specified SSL port (default: 6633) on the host at the
28 given ip, which must be expressed as an IP address (not a
29 DNS name). The --private-key, --certificate, and
30 --ca-cert options are mandatory when this form is used.
31 tcp:ip[:port]
33 The specified TCP port (default: 6633) on the host at the
34 given ip, which must be expressed as an IP address (not a
35 DNS name).
36 unix:file
38 The Unix domain server socket named file.
39 file This is short for unix:file, as long as file does not
41 contain a colon.
42 bridge This is short for unix:/var/run/openvswitch/bridge.mgmt,
44 as long as bridge does not contain a colon.
45 [type@]dp
47 Attempts to look up the bridge associated with dp and
48 open as above. If type is given, it specifies the data‐
49 path provider of dp, otherwise the default provider sys‐
50 tem is assumed.
51 show switch
53 Prints to the console information on switch, including informa‐
54 tion on its flow tables and ports.
55 dump-tables switch
57 Prints to the console statistics for each of the flow tables
58 used by switch.
59 dump-ports switch [netdev]
61 Prints to the console statistics for network devices associated
62 with switch. If netdev is specified, only the statistics asso‐
63 ciated with that device will be printed. netdev can be an Open‐
64 Flow assigned port number or device name, e.g. eth0.
65 dump-ports-desc switch
67 Prints to the console detailed information about network devices
68 associated with switch (version 1.7 or later). This is a subset
69 of the information provided by the show command.
70 mod-port switch port action
72 Modify characteristics of port port in switch. port may be an
73 OpenFlow port number or name or the keyword LOCAL (the preferred
74 way to refer to the OpenFlow local port). The action may be any
75 one of the following:
76 up
77 down Enable or disable the interface. This is equivalent to
78 ifconfig up or ifconfig down on a Unix system.
79 stp
81 no-stp Enable or disable 802.1D spanning tree protocol (STP) on
82 the interface. OpenFlow implementations that don't sup‐
83 port STP will refuse to enable it.
84 receive
86 no-receive
87 receive-stp
88 no-receive-stp
89 Enable or disable OpenFlow processing of packets received
90 on this interface. When packet processing is disabled,
91 packets will be dropped instead of being processed
92 through the OpenFlow table. The receive or no-receive
93 setting applies to all packets except 802.1D spanning
94 tree packets, which are separately controlled by
95 receive-stp or no-receive-stp.
96 forward
98 no-forward
99 Allow or disallow forwarding of traffic to this inter‐
100 face. By default, forwarding is enabled.
101 flood
103 no-flood
104 Controls whether an OpenFlow flood action will send traf‐
105 fic out this interface. By default, flooding is enabled.
106 Disabling flooding is primarily useful to prevent loops
107 when a spanning tree protocol is not in use.
108 packet-in
110 no-packet-in
111 Controls whether packets received on this interface that
112 do not match a flow table entry generate a ``packet in''
113 message to the OpenFlow controller. By default, ``packet
114 in'' messages are enabled.
115 The show command displays (among other information) the configu‐
117 ration that mod-port changes.
118 get-frags switch
120 Prints switch's fragment handling mode. See set-frags, below,
121 for a description of each fragment handling mode.
122 The show command also prints the fragment handling mode among
124 its other output.
125 set-frags switch frag_mode
127 Configures switch's treatment of IPv4 and IPv6 fragments. The
128 choices for frag_mode are:
129 normal Fragments pass through the flow table like non-fragmented
131 packets. The TCP ports, UDP ports, and ICMP type and
132 code fields are always set to 0, even for fragments where
133 that information would otherwise be available (fragments
134 with offset 0). This is the default fragment handling
135 mode for an OpenFlow switch.
136 drop Fragments are dropped without passing through the flow
138 table.
139 reassemble
141 The switch reassembles fragments into full IP packets
142 before passing them through the flow table. Open vSwitch
143 does not implement this fragment handling mode.
144 nx-match
146 Fragments pass through the flow table like non-fragmented
147 packets. The TCP ports, UDP ports, and ICMP type and
148 code fields are available for matching for fragments with
149 offset 0, and set to 0 in fragments with nonzero offset.
150 This mode is a Nicira extension.
151 See the description of ip_frag, below, for a way to match on
153 whether a packet is a fragment and on its fragment offset.
154 dump-flows switch [flows]
156 Prints to the console all flow entries in switch's tables that
157 match flows. If flows is omitted, all flows in the switch are
158 retrieved. See Flow Syntax, below, for the syntax of flows.
159 The output format is described in Table Entry Output.
160 By default, ovs-ofctl prints flow entries in the same order that
162 the switch sends them, which is unlikely to be intuitive or con‐
163 sistent. See the description of --sort and --rsort, under
164 OPTIONS below, to influence the display order.
165 dump-aggregate switch [flows]
167 Prints to the console aggregate statistics for flows in switch's
168 tables that match flows. If flows is omitted, the statistics
169 are aggregated across all flows in the switch's flow tables.
170 See Flow Syntax, below, for the syntax of flows. The output
171 format is described in Table Entry Output.
172 queue-stats switch [port [queue]]
174 Prints to the console statistics for the specified queue on port
175 within switch. port can be an OpenFlow port number or name, the
176 keyword LOCAL (the preferred way to refer to the OpenFlow local
177 port), or the keyword ALL. Either of port or queue or both may
178 be omitted (or equivalently the keyword ALL). If both are omit‐
179 ted, statistics are printed for all queues on all ports. If
180 only queue is omitted, then statistics are printed for all
181 queues on port; if only port is omitted, then statistics are
182 printed for queue on every port where it exists.
183 OpenFlow Switch Flow Table Commands
185 These commands manage the flow table in an OpenFlow switch. In each
186 case, flow specifies a flow entry in the format described in Flow Syn‐
187 tax, below, and file is a text file that contains zero or more flows in
188 the same syntax, one per line.
189 add-flow switch flow
191 add-flow switch - < file
192 add-flows switch file
193 Add each flow entry to switch's tables.
194 [--strict] mod-flows switch flow
196 [--strict] mod-flows switch - < file
197 Modify the actions in entries from switch's tables that match
198 the specified flows. With --strict, wildcards are not treated
199 as active for matching purposes.
200 del-flows switch
202 [--strict] del-flows switch [flow]
203 [--strict] del-flows switch - < file
204 Deletes entries from switch's flow table. With only a switch
205 argument, deletes all flows. Otherwise, deletes flow entries
206 that match the specified flows. With --strict, wildcards are
207 not treated as active for matching purposes.
208 [--readd] replace-flows switch file
210 Reads flow entries from file (or stdin if file is -) and queries
211 the flow table from switch. Then it fixes up any differences,
212 adding flows from flow that are missing on switch, deleting
213 flows from switch that are not in file, and updating flows in
214 switch whose actions, cookie, or timeouts differ in file.
215 With --readd, ovs-ofctl adds all the flows from file, even those
217 that exist with the same actions, cookie, and timeout in switch.
218 This resets all the flow packet and byte counters to 0, which
219 can be useful for debugging.
220 diff-flows source1 source2
222 Reads flow entries from source1 and source2 and prints the dif‐
223 ferences. A flow that is in source1 but not in source2 is
224 printed preceded by a -, and a flow that is in source2 but not
225 in source1 is printed preceded by a +. If a flow exists in both
226 source1 and source2 with different actions, cookie, or timeouts,
227 then both versions are printed preceded by - and +, respec‐
228 tively.
229 source1 and source2 may each name a file or a switch. If a name
231 begins with / or ., then it is considered to be a file name. A
232 name that contains : is considered to be a switch. Otherwise,
233 it is a file if a file by that name exists, a switch if not.
234 For this command, an exit status of 0 means that no differences
236 were found, 1 means that an error occurred, and 2 means that
237 some differences were found.
238 packet-out switch in_port actions packet...
240 Connects to switch and instructs it to execute the OpenFlow
241 actions on each packet. For the purpose of executing the
242 actions, the packets are considered to have arrived on in_port,
243 which may be an OpenFlow port number or name (e.g. eth0), the
244 keyword LOCAL (the preferred way to refer to the OpenFlow
245 ``local'' port), or the keyword NONE to indicate that the packet
246 was generated by the switch itself.
247 OpenFlow Switch Monitoring Commands
249 snoop switch
250 Connects to switch and prints to the console all OpenFlow mes‐
251 sages received. Unlike other ovs-ofctl commands, if switch is
252 the name of a bridge, then the snoop command connects to a Unix
253 domain socket named /var/run/openvswitch/bridge.snoop.
254 ovs-vswitchd listens on such a socket for each bridge and sends
255 to it all of the OpenFlow messages sent to or received from its
256 configured OpenFlow controller. Thus, this command can be used
257 to view OpenFlow protocol activity between a switch and its con‐
258 troller.
259 When a switch has more than one controller configured, only the
261 traffic to and from a single controller is output. If none of
262 the controllers is configured as a master or a slave (using a
263 Nicira extension to OpenFlow), then a controller is chosen arbi‐
264 trarily among them. If there is a master controller, it is cho‐
265 sen; otherwise, if there are any controllers that are not mas‐
266 ters or slaves, one is chosen arbitrarily; otherwise, a slave
267 controller is chosen arbitrarily. This choice is made once at
268 connection time and does not change as controllers reconfigure
269 their roles.
270 If a switch has no controller configured, or if the configured
272 controller is disconnected, no traffic is sent, so monitoring
273 will not show any traffic.
274 monitor switch [miss-len] [invalid_ttl] [watch:[spec...]]
276 Connects to switch and prints to the console all OpenFlow mes‐
277 sages received. Usually, switch should specify the name of a
278 bridge in the ovs-vswitchd database.
279 If miss-len is provided, ovs-ofctl sends an OpenFlow ``set con‐
281 figuration'' message at connection setup time that requests
282 miss-len bytes of each packet that misses the flow table. Open
283 vSwitch does not send these and other asynchronous messages to
284 an ovs-ofctl monitor client connection unless a nonzero value is
285 specified on this argument. (Thus, if miss-len is not speci‐
286 fied, very little traffic will ordinarily be printed.)
287 If invalid_ttl is passed, ovs-ofctl sends an OpenFlow ``set con‐
289 figuration'' message at connection setup time that requests
290 INVALID_TTL_TO_CONTROLLER, so that ovs-ofctl monitor can receive
291 ``packet-in'' messages when TTL reaches zero on dec_ttl action.
292 watch:[spec...] causes ovs-ofctl to send a ``monitor request''
294 Nicira extension message to the switch at connection setup time.
295 This message causes the switch to send information about flow
296 table changes as they occur. The following comma-separated spec
297 syntax is available:
298 !initial
300 Do not report the switch's initial flow table contents.
301 !add Do not report newly added flows.
303 !delete
305 Do not report deleted flows.
306 !modify
308 Do not report modifications to existing flows.
309 !own Abbreviate changes made to the flow table by ovs-ofctl's
311 own connection to the switch. (These could only occur
312 using the ofctl/send command described below under RUN‐
313 TIME MANAGEMENT COMMANDS.)
314 !actions
316 Do not report actions as part of flow updates.
317 table=number
319 Limits the monitoring to the table with the given number
320 between 0 and 254. By default, all tables are monitored.
321 out_port=port
323 If set, only flows that output to port are monitored.
324 The port may be an OpenFlow port number or keyword (e.g.
325 LOCAL).
326 field=value
328 Monitors only flows that have field specified as the
329 given value. Any syntax valid for matching on dump-flows
330 may be used.
331 This command may be useful for debugging switch or controller
333 implementations. With watch:, it is particularly useful for
334 observing how a controller updates flow tables.
335 OpenFlow Switch and Controller Commands
337 The following commands, like those in the previous section, may be
338 applied to OpenFlow switches, using any of the connection methods
339 described in that section. Unlike those commands, these may also be
340 applied to OpenFlow controllers.
341 probe target
343 Sends a single OpenFlow echo-request message to target and waits
344 for the response. With the -t or --timeout option, this command
345 can test whether an OpenFlow switch or controller is up and run‐
346 ning.
347 ping target [n]
349 Sends a series of 10 echo request packets to target and times
350 each reply. The echo request packets consist of an OpenFlow
351 header plus n bytes (default: 64) of randomly generated payload.
352 This measures the latency of individual requests.
353 benchmark target n count
355 Sends count echo request packets that each consist of an Open‐
356 Flow header plus n bytes of payload and waits for each response.
357 Reports the total time required. This is a measure of the maxi‐
358 mum bandwidth to target for round-trips of n-byte messages.
359 Other Commands
361 ofp-parse file
362 Reads file (or stdin if file is -) as a series of OpenFlow mes‐
363 sages in the binary format used on an OpenFlow connection, and
364 prints them to the console. This can be useful for printing
365 OpenFlow messages captured from a TCP stream.
366 Flow Syntax
368 Some ovs-ofctl commands accept an argument that describes a flow or
369 flows. Such flow descriptions comprise a series field=value assign‐
370 ments, separated by commas or white space. (Embedding spaces into a
371 flow description normally requires quoting to prevent the shell from
372 breaking the description into multiple arguments.)
373 Flow descriptions should be in normal form. This means that a flow may
375 only specify a value for an L3 field if it also specifies a particular
376 L2 protocol, and that a flow may only specify an L4 field if it also
377 specifies particular L2 and L3 protocol types. For example, if the L2
378 protocol type dl_type is wildcarded, then L3 fields nw_src, nw_dst, and
379 nw_proto must also be wildcarded. Similarly, if dl_type or nw_proto
380 (the L3 protocol type) is wildcarded, so must be tp_dst and tp_src,
381 which are L4 fields. ovs-ofctl will warn about flows not in normal
382 form.
383 The following field assignments describe how a flow matches a packet.
385 If any of these assignments is omitted from the flow syntax, the field
386 is treated as a wildcard; thus, if all of them are omitted, the result‐
387 ing flow matches all packets. The string * may be specified to explic‐
388 itly mark any of these fields as a wildcard. (* should be quoted to
389 protect it from shell expansion.)
390 in_port=port
392 Matches OpenFlow port port, which may be an OpenFlow port number
393 or keyword (e.g. LOCAL). ovs-ofctl show.
394 (The resubmit action can search OpenFlow flow tables with arbi‐
396 trary in_port values, so flows that match port numbers that do
397 not exist from an OpenFlow perspective can still potentially be
398 matched.)
399 dl_vlan=vlan
401 Matches IEEE 802.1q Virtual LAN tag vlan. Specify 0xffff as
402 vlan to match packets that are not tagged with a Virtual LAN;
403 otherwise, specify a number between 0 and 4095, inclusive, as
404 the 12-bit VLAN ID to match.
405 dl_vlan_pcp=priority
407 Matches IEEE 802.1q Priority Code Point (PCP) priority, which is
408 specified as a value between 0 and 7, inclusive. A higher value
409 indicates a higher frame priority level.
410 dl_src=xx:xx:xx:xx:xx:xx
412 dl_dst=xx:xx:xx:xx:xx:xx
413 Matches an Ethernet source (or destination) address specified as
414 6 pairs of hexadecimal digits delimited by colons (e.g.
415 00:0A:E4:25:6B:B0).
416 dl_src=xx:xx:xx:xx:xx:xx/xx:xx:xx:xx:xx:xx
418 dl_dst=xx:xx:xx:xx:xx:xx/xx:xx:xx:xx:xx:xx
419 Matches an Ethernet destination address specified as 6 pairs of
420 hexadecimal digits delimited by colons (e.g. 00:0A:E4:25:6B:B0),
421 with a wildcard mask following the slash. Open vSwitch 1.8 and
422 later support arbitrary masks for source and/or destination.
423 Earlier versions only support masking the destination with the
424 following masks:
425 01:00:00:00:00:00
427 Match only the multicast bit. Thus,
428 dl_dst=01:00:00:00:00:00/01:00:00:00:00:00 matches all
429 multicast (including broadcast) Ethernet packets, and
430 dl_dst=00:00:00:00:00:00/01:00:00:00:00:00 matches all
431 unicast Ethernet packets.
432 fe:ff:ff:ff:ff:ff
434 Match all bits except the multicast bit. This is proba‐
435 bly not useful.
436 ff:ff:ff:ff:ff:ff
438 Exact match (equivalent to omitting the mask).
439 00:00:00:00:00:00
441 Wildcard all bits (equivalent to dl_dst=*.)
442 dl_type=ethertype
444 Matches Ethernet protocol type ethertype, which is specified as
445 an integer between 0 and 65535, inclusive, either in decimal or
446 as a hexadecimal number prefixed by 0x (e.g. 0x0806 to match ARP
447 packets).
448 nw_src=ip[/netmask]
450 nw_dst=ip[/netmask]
451 When dl_type is 0x0800 (possibly via shorthand, e.g. ip or tcp),
452 matches IPv4 source (or destination) address ip, which may be
453 specified as an IP address or host name (e.g. 192.168.1.1 or
454 www.example.com). The optional netmask allows restricting a
455 match to an IPv4 address prefix. The netmask may be specified
456 as a dotted quad (e.g. 192.168.1.0/255.255.255.0) or as a CIDR
457 block (e.g. 192.168.1.0/24). Open vSwitch 1.8 and later support
458 arbitrary dotted quad masks; earlier versions support only CIDR
459 masks, that is, the dotted quads that are equivalent to some
460 CIDR block.
461 When dl_type=0x0806 or arp is specified, matches the ar_spa or
463 ar_tpa field, respectively, in ARP packets for IPv4 and Ether‐
464 net.
465 When dl_type=0x8035 or rarp is specified, matches the ar_spa or
467 ar_tpa field, respectively, in RARP packets for IPv4 and Ether‐
468 net.
469 When dl_type is wildcarded or set to a value other than 0x0800,
471 0x0806, or 0x8035, the values of nw_src and nw_dst are ignored
472 (see Flow Syntax above).
473 nw_proto=proto
475 When ip or dl_type=0x0800 is specified, matches IP protocol type
476 proto, which is specified as a decimal number between 0 and 255,
477 inclusive (e.g. 1 to match ICMP packets or 6 to match TCP pack‐
478 ets).
479 When ipv6 or dl_type=0x86dd is specified, matches IPv6 header
481 type proto, which is specified as a decimal number between 0 and
482 255, inclusive (e.g. 58 to match ICMPv6 packets or 6 to match
483 TCP). The header type is the terminal header as described in
484 the DESIGN document.
485 When arp or dl_type=0x0806 is specified, matches the lower 8
487 bits of the ARP opcode. ARP opcodes greater than 255 are
488 treated as 0.
489 When rarp or dl_type=0x8035 is specified, matches the lower 8
491 bits of the ARP opcode. ARP opcodes greater than 255 are
492 treated as 0.
493 When dl_type is wildcarded or set to a value other than 0x0800,
495 0x0806, 0x8035 or 0x86dd, the value of nw_proto is ignored (see
496 Flow Syntax above).
497 nw_tos=tos
499 Matches IP ToS/DSCP or IPv6 traffic class field tos, which is
500 specified as a decimal number between 0 and 255, inclusive.
501 Note that the two lower reserved bits are ignored for matching
502 purposes.
503 When dl_type is wildcarded or set to a value other than 0x0800
505 or 0x86dd, the value of nw_tos is ignored (see Flow Syntax
506 above).
507 nw_ecn=ecn
509 Matches ecn bits in IP ToS or IPv6 traffic class fields, which
510 is specified as a decimal number between 0 and 3, inclusive.
511 When dl_type is wildcarded or set to a value other than 0x0800
513 or 0x86dd, the value of nw_ecn is ignored (see Flow Syntax
514 above).
515 nw_ttl=ttl
517 Matches IP TTL or IPv6 hop limit value ttl, which is specified
518 as a decimal number between 0 and 255, inclusive.
519 When dl_type is wildcarded or set to a value other than 0x0800
521 or 0x86dd, the value of nw_ttl is ignored (see Flow Syntax
522 above).
523 tp_src=port
525 tp_dst=port
526 When dl_type and nw_proto specify TCP or UDP or SCTP, tp_src and
527 tp_dst match the UDP or TCP or SCTP source or destination port
528 port, respectively, which is specified as a decimal number
529 between 0 and 65535, inclusive (e.g. 80 to match packets origi‐
530 nating from a HTTP server).
531 When dl_type and nw_proto take other values, the values of these
533 settings are ignored (see Flow Syntax above).
534 tp_src=port/mask
536 tp_dst=port/mask
537 Bitwise match on TCP (or UDP or SCTP) source or destination
538 port, respectively. The port and mask are 16-bit numbers writ‐
539 ten in decimal or in hexadecimal prefixed by 0x. Each 1-bit in
540 mask requires that the corresponding bit in port must match.
541 Each 0-bit in mask causes the corresponding bit to be ignored.
542 Bitwise matches on transport ports are rarely useful in isola‐
544 tion, but a group of them can be used to reduce the number of
545 flows required to match on a range of transport ports. For
546 example, suppose that the goal is to match TCP source ports 1000
547 to 1999, inclusive. One way is to insert 1000 flows, each of
548 which matches on a single source port. Another way is to look
549 at the binary representations of 1000 and 1999, as follows:
550 01111101000
551 11111001111
552 and then to transform those into a series of bitwise matches
553 that accomplish the same results:
554 01111101xxx
555 0111111xxxx
556 10xxxxxxxxx
557 110xxxxxxxx
558 1110xxxxxxx
559 11110xxxxxx
560 1111100xxxx
561 which become the following when written in the syntax required
562 by ovs-ofctl:
563 tcp,tp_src=0x03e8/0xfff8
564 tcp,tp_src=0x03f0/0xfff0
565 tcp,tp_src=0x0400/0xfe00
566 tcp,tp_src=0x0600/0xff00
567 tcp,tp_src=0x0700/0xff80
568 tcp,tp_src=0x0780/0xffc0
569 tcp,tp_src=0x07c0/0xfff0
570 Only Open vSwitch 1.6 and later supports bitwise matching on
572 transport ports.
573 Like the exact-match forms of tp_src and tp_dst described above,
575 the bitwise match forms apply only when dl_type and nw_proto
576 specify TCP or UDP or SCTP.
577 icmp_type=type
579 icmp_code=code
580 When dl_type and nw_proto specify ICMP or ICMPv6, type matches
581 the ICMP type and code matches the ICMP code. Each is specified
582 as a decimal number between 0 and 255, inclusive.
583 When dl_type and nw_proto take other values, the values of these
585 settings are ignored (see Flow Syntax above).
586 table=number
588 If specified, limits the flow manipulation and flow dump com‐
589 mands to only apply to the table with the given number between 0
590 and 254. Behavior varies if table is not specified (equivalent
591 to specifying 255 as number). For flow table modification com‐
592 mands without --strict, the switch will choose the table for
593 these commands to operate on. For flow table modification com‐
594 mands with --strict, the command will operate on any single
595 matching flow in any table; it will do nothing if there are
596 matches in more than one table. The dump-flows and dump-aggre‐
597 gate commands will gather statistics about flows from all
598 tables.
599 When this field is specified in add-flow, add-flows, mod-flows
601 and del-flows commands, it activates a Nicira extension to Open‐
602 Flow, which as of this writing is only known to be implemented
603 by Open vSwitch.
604 metadata=value[/mask]
606 Matches value either exactly or with optional mask in the meta‐
607 data field. value and mask are 64-bit integers, by default in
608 decimal (use a 0x prefix to specify hexadecimal). Arbitrary mask
609 values are allowed: a 1-bit in mask indicates that the corre‐
610 sponding bit in value must match exactly, and a 0-bit wildcards
611 that bit. Matching on metadata was added in Open vSwitch 1.8.
612 The following shorthand notations are also available:
614 ip Same as dl_type=0x0800.
616 icmp Same as dl_type=0x0800,nw_proto=1.
618 tcp Same as dl_type=0x0800,nw_proto=6.
620 udp Same as dl_type=0x0800,nw_proto=17.
622 sctp Same as dl_type=0x0800,nw_proto=132.
624 arp Same as dl_type=0x0806.
626 rarp Same as dl_type=0x8035.
628 The following field assignments require support for the NXM (Nicira
630 Extended Match) extension to OpenFlow. When one of these is specified,
631 ovs-ofctl will automatically attempt to negotiate use of this exten‐
632 sion. If the switch does not support NXM, then ovs-ofctl will report a
633 fatal error.
634 vlan_tci=tci[/mask]
636 Matches modified VLAN TCI tci. If mask is omitted, tci is the
637 exact VLAN TCI to match; if mask is specified, then a 1-bit in
638 mask indicates that the corresponding bit in tci must match
639 exactly, and a 0-bit wildcards that bit. Both tci and mask are
640 16-bit values that are decimal by default; use a 0x prefix to
641 specify them in hexadecimal.
642 The value that vlan_tci matches against is 0 for a packet that
644 has no 802.1Q header. Otherwise, it is the TCI value from the
645 802.1Q header with the CFI bit (with value 0x1000) forced to 1.
646 Examples:
648 vlan_tci=0
650 Match only packets without an 802.1Q header.
651 vlan_tci=0xf123
653 Match packets tagged with priority 7 in VLAN 0x123.
654 vlan_tci=0x1123/0x1fff
656 Match packets tagged with VLAN 0x123 (and any priority).
657 vlan_tci=0x5000/0xf000
659 Match packets tagged with priority 2 (in any VLAN).
660 vlan_tci=0/0xfff
662 Match packets with no 802.1Q header or tagged with VLAN 0
663 (and any priority).
664 vlan_tci=0x5000/0xe000
666 Match packets with no 802.1Q header or tagged with prior‐
667 ity 2 (in any VLAN).
668 vlan_tci=0/0xefff
670 Match packets with no 802.1Q header or tagged with VLAN 0
671 and priority 0.
672 Some of these matching possibilities can also be achieved with
674 dl_vlan and dl_vlan_pcp.
675 ip_frag=frag_type
677 When dl_type specifies IP or IPv6, frag_type specifies what kind
678 of IP fragments or non-fragments to match. The following values
679 of frag_type are supported:
680 no Matches only non-fragmented packets.
682 yes Matches all fragments.
684 first Matches only fragments with offset 0.
686 later Matches only fragments with nonzero offset.
688 not_later
690 Matches non-fragmented packets and fragments with zero
691 offset.
692 The ip_frag match type is likely to be most useful in nx-match
694 mode. See the description of the set-frags command, above, for
695 more details.
696 arp_sha=xx:xx:xx:xx:xx:xx
698 arp_tha=xx:xx:xx:xx:xx:xx
699 When dl_type specifies either ARP or RARP, arp_sha and arp_tha
700 match the source and target hardware address, respectively. An
701 address is specified as 6 pairs of hexadecimal digits delimited
702 by colons.
703 ipv6_src=ipv6[/netmask]
705 ipv6_dst=ipv6[/netmask]
706 When dl_type is 0x86dd (possibly via shorthand, e.g., ipv6 or
707 tcp6), matches IPv6 source (or destination) address ipv6, which
708 may be specified as defined in RFC 2373. The preferred format
709 is x:x:x:x:x:x:x:x, where x are the hexadecimal values of the
710 eight 16-bit pieces of the address. A single instance of :: may
711 be used to indicate multiple groups of 16-bits of zeros. The
712 optional netmask allows restricting a match to an IPv6 address
713 prefix. A netmask is specified as an IPv6 address (e.g.
714 2001:db8:3c4d:1::/ffff:ffff:ffff:ffff::) or a CIDR block (e.g.
715 2001:db8:3c4d:1::/64). Open vSwitch 1.8 and later support arbi‐
716 trary masks; earlier versions support only CIDR masks, that is,
717 CIDR block and IPv6 addresses that are equivalent to CIDR
718 blocks.
719 ipv6_label=label
721 When dl_type is 0x86dd (possibly via shorthand, e.g., ipv6 or
722 tcp6), matches IPv6 flow label label.
723 nd_target=ipv6[/netmask]
725 When dl_type, nw_proto, and icmp_type specify IPv6 Neighbor Dis‐
726 covery (ICMPv6 type 135 or 136), matches the target address
727 ipv6. ipv6 is in the same format described earlier for the
728 ipv6_src and ipv6_dst fields.
729 nd_sll=xx:xx:xx:xx:xx:xx
731 When dl_type, nw_proto, and icmp_type specify IPv6 Neighbor
732 Solicitation (ICMPv6 type 135), matches the source link-layer
733 address option. An address is specified as 6 pairs of hexadeci‐
734 mal digits delimited by colons.
735 nd_tll=xx:xx:xx:xx:xx:xx
737 When dl_type, nw_proto, and icmp_type specify IPv6 Neighbor
738 Advertisement (ICMPv6 type 136), matches the target link-layer
739 address option. An address is specified as 6 pairs of hexadeci‐
740 mal digits delimited by colons.
741 tun_id=tunnel-id[/mask]
743 Matches tunnel identifier tunnel-id. Only packets that arrive
744 over a tunnel that carries a key (e.g. GRE with the RFC 2890 key
745 extension and a nonzero key value) will have a nonzero tunnel
746 ID. If mask is omitted, tunnel-id is the exact tunnel ID to
747 match; if mask is specified, then a 1-bit in mask indicates that
748 the corresponding bit in tunnel-id must match exactly, and a
749 0-bit wildcards that bit.
750 tun_src=ip[/netmask]
752 tun_dst=ip[/netmask]
753 Matches tunnel IPv4 source (or destination) address ip. Only
754 packets that arrive over a tunnel will have nonzero tunnel
755 addresses. The address may be specified as an IP address or
756 host name (e.g. 192.168.1.1 or www.example.com). The optional
757 netmask allows restricting a match to a masked IPv4 address.
758 The netmask may be specified as a dotted quad (e.g.
759 192.168.1.0/255.255.255.0) or as a CIDR block (e.g.
760 192.168.1.0/24).
761 regidx=value[/mask]
763 Matches value either exactly or with optional mask in register
764 number idx. The valid range of idx depends on the switch.
765 value and mask are 32-bit integers, by default in decimal (use a
766 0x prefix to specify hexadecimal). Arbitrary mask values are
767 allowed: a 1-bit in mask indicates that the corresponding bit in
768 value must match exactly, and a 0-bit wildcards that bit.
769 When a packet enters an OpenFlow switch, all of the registers
771 are set to 0. Only explicit Nicira extension actions change
772 register values.
773 pkt_mark=value[/mask]
775 Matches packet metadata mark value either exactly or with
776 optional mask. The mark is associated data that may be passed
777 into other system components in order to facilitate interaction
778 between subsystems. On Linux this corresponds to the skb mark
779 but the exact implementation is platform-dependent.
780 Defining IPv6 flows (those with dl_type equal to 0x86dd) requires sup‐
782 port for NXM. The following shorthand notations are available for
783 IPv6-related flows:
784 ipv6 Same as dl_type=0x86dd.
786 tcp6 Same as dl_type=0x86dd,nw_proto=6.
788 udp6 Same as dl_type=0x86dd,nw_proto=17.
790 sctp6 Same as dl_type=0x86dd,nw_proto=132.
792 icmp6 Same as dl_type=0x86dd,nw_proto=58.
794 Finally, field assignments to duration, n_packets, or n_bytes are
796 ignored to allow output from the dump-flows command to be used as input
797 for other commands that parse flows.
798 The add-flow, add-flows, and mod-flows commands require an additional
800 field, which must be the final field specified:
801 actions=[target][,target...]
803 Specifies a comma-separated list of actions to take on a packet
804 when the flow entry matches. If no target is specified, then
805 packets matching the flow are dropped. The target may be an
806 OpenFlow port number designating the physical port on which to
807 output the packet, or one of the following keywords:
808 output:port
810 Outputs the packet to port, which must be an OpenFlow
811 port number or keyword (e.g. LOCAL).
812 output:src[start..end]
814 Outputs the packet to the OpenFlow port number read from
815 src, which must be an NXM field as described above. For
816 example, output:NXM_NX_REG0[16..31] outputs to the Open‐
817 Flow port number written in the upper half of register 0.
818 This form of output uses an OpenFlow extension that is
819 not supported by standard OpenFlow switches.
820 enqueue:port:queue
822 Enqueues the packet on the specified queue within port
823 port, which must be an OpenFlow port number or keyword
824 (e.g. LOCAL).. The number of supported queues depends on
825 the switch; some OpenFlow implementations do not support
826 queuing at all.
827 normal Subjects the packet to the device's normal L2/L3 process‐
829 ing. (This action is not implemented by all OpenFlow
830 switches.)
831 flood Outputs the packet on all switch physical ports other
833 than the port on which it was received and any ports on
834 which flooding is disabled (typically, these would be
835 ports disabled by the IEEE 802.1D spanning tree proto‐
836 col).
837 all Outputs the packet on all switch physical ports other
839 than the port on which it was received.
840 controller(key=value...)
842 Sends the packet to the OpenFlow controller as a ``packet
843 in'' message. The supported key-value pairs are:
844 max_len=nbytes
846 Limit to nbytes the number of bytes of the packet
847 to send to the controller. By default the entire
848 packet is sent.
849 reason=reason
851 Specify reason as the reason for sending the mes‐
852 sage in the ``packet in'' message. The supported
853 reasons are action (the default), no_match, and
854 invalid_ttl.
855 id=controller-id
857 Specify controller-id, a 16-bit integer, as the
858 connection ID of the OpenFlow controller or con‐
859 trollers to which the ``packet in'' message should
860 be sent. The default is zero. Zero is also the
861 default connection ID for each controller connec‐
862 tion, and a given controller connection will only
863 have a nonzero connection ID if its controller
864 uses the NXT_SET_CONTROLLER_ID Nicira extension to
865 OpenFlow.
866 Any reason other than action and any nonzero controller-id uses
867 a Nicira vendor extension that, as of this writing, is only
868 known to be implemented by Open vSwitch (version 1.6 or later).
869 controller
871 controller[:nbytes]
872 Shorthand for controller() or controller(max_len=nbytes),
873 respectively.
874 local Outputs the packet on the ``local port,'' which corre‐
876 sponds to the network device that has the same name as
877 the bridge.
878 in_port
880 Outputs the packet on the port from which it was
881 received.
882 drop Discards the packet, so no further processing or forward‐
884 ing takes place. If a drop action is used, no other
885 actions may be specified.
886 mod_vlan_vid:vlan_vid
888 Modifies the VLAN id on a packet. The VLAN tag is added
889 or modified as necessary to match the value specified.
890 If the VLAN tag is added, a priority of zero is used (see
891 the mod_vlan_pcp action to set this).
892 mod_vlan_pcp:vlan_pcp
894 Modifies the VLAN priority on a packet. The VLAN tag is
895 added or modified as necessary to match the value speci‐
896 fied. Valid values are between 0 (lowest) and 7 (high‐
897 est). If the VLAN tag is added, a vid of zero is used
898 (see the mod_vlan_vid action to set this).
899 strip_vlan
901 Strips the VLAN tag from a packet if it is present.
902 push_vlan:ethertype
904 Push a new VLAN tag onto the packet. Ethertype is used
905 as the the Ethertype for the tag. Only ethertype 0x8100
906 should be used. (0x88a8 which the spec allows isn't sup‐
907 ported at the moment.) A priority of zero and the tag of
908 zero are used for the new tag.
909 push_mpls:ethertype
911 If the packet does not already contain any MPLS labels,
912 changes the packet's Ethertype to ethertype, which must
913 be either the MPLS unicast Ethertype 0x8847 or the MPLS
914 multicast Ethertype 0x8848, and then pushes an initial
915 label stack entry. The label stack entry's default label
916 is 2 if the packet contains IPv6 and 0 otherwise, its
917 default traffic control value is the low 3 bits of the
918 packet's DSCP value (0 if the packet is not IP), and its
919 TTL is copied from the IP TTL (64 if the packet is not
920 IP).
921 If the packet does already contain an MPLS label, pushes
923 a new outermost label as a copy of the existing outermost
924 label.
925 There are some limitations in the implementation.
927 push_mpls followed by another push_mpls will result in
928 the first push_mpls being discarded.
929 pop_mpls:ethertype
931 Strips the outermost MPLS label stack entry. Currently
932 the implementation restricts ethertype to a non-MPLS
933 Ethertype and thus pop_mpls should only be applied to
934 packets with an MPLS label stack depth of one.
935 There are some limitations in the implementation.
937 pop_mpls followed by another push_mpls without an inter‐
938 mediate push_mpls will result in the first push_mpls
939 being discarded.
940 mod_dl_src:mac
942 Sets the source Ethernet address to mac.
943 mod_dl_dst:mac
945 Sets the destination Ethernet address to mac.
946 mod_nw_src:ip
948 Sets the IPv4 source address to ip.
949 mod_nw_dst:ip
951 Sets the IPv4 destination address to ip.
952 mod_tp_src:port
954 Sets the TCP or UDP or SCTP source port to port.
955 mod_tp_dst:port
957 Sets the TCP or UDP or SCTP destination port to port.
958 mod_nw_tos:tos
960 Sets the IPv4 ToS/DSCP field to tos, which must be a mul‐
961 tiple of 4 between 0 and 255. This action does not mod‐
962 ify the two least significant bits of the ToS field (the
963 ECN bits).
964 The following actions are Nicira vendor extensions that, as of
966 this writing, are only known to be implemented by Open vSwitch:
967 resubmit:port
969 resubmit([port],[table])
970 Re-searches this OpenFlow flow table (or the table whose
971 number is specified by table) with the in_port field
972 replaced by port (if port is specified) and executes the
973 actions found, if any, in addition to any other actions
974 in this flow entry.
975 Recursive resubmit actions are obeyed up to an implemen‐
977 tation-defined maximum depth. Open vSwitch 1.0.1 and
978 earlier did not support recursion; Open vSwitch before
979 1.2.90 did not support table.
980 set_tunnel:id
982 set_tunnel64:id
983 If outputting to a port that encapsulates the packet in a
984 tunnel and supports an identifier (such as GRE), sets the
985 identifier to id. If the set_tunnel form is used and id
986 fits in 32 bits, then this uses an action extension that
987 is supported by Open vSwitch 1.0 and later. Otherwise,
988 if id is a 64-bit value, it requires Open vSwitch 1.1 or
989 later.
990 set_queue:queue
992 Sets the queue that should be used to queue when packets
993 are output. The number of supported queues depends on
994 the switch; some OpenFlow implementations do not support
995 queuing at all.
996 pop_queue
998 Restores the queue to the value it was before any
999 set_queue actions were applied.
1000 dec_ttl
1002 dec_ttl[(id1,id2)]
1003 Decrement TTL of IPv4 packet or hop limit of IPv6 packet.
1004 If the TTL or hop limit is initially zero, no decrement
1005 occurs. Instead, a ``packet-in'' message with reason
1006 code OFPR_INVALID_TTL is sent to each connected con‐
1007 troller that has enabled receiving them, if any. Pro‐
1008 cessing the current set of actions then stops. However,
1009 if the current set of actions was reached through
1010 ``resubmit'' then remaining actions in outer levels
1011 resume processing. This action also optionally supports
1012 the ability to specify a list of valid controller ids.
1013 Each of controllers in the list will receive the
1014 ``packet_in'' message only if they have registered to
1015 receive the invalid ttl packets. If controller ids are
1016 not specified, the ``packet_in'' message will be sent
1017 only to the controllers having controller id zero which
1018 have registered for the invalid ttl packets.
1019 set_mpls_ttl:ttl
1021 Set the TTL of the outer MPLS label stack entry of a
1022 packet. ttl should be in the range 0 to 255 inclusive.
1023 dec_mpls_ttl
1025 Decrement TTL of the outer MPLS label stack entry of a
1026 packet. If the TTL is initially zero, no decrement
1027 occurs. Instead, a ``packet-in'' message with reason
1028 code OFPR_INVALID_TTL is sent to each connected con‐
1029 troller with controller id zer that has enabled receiving
1030 them. Processing the current set of actions then stops.
1031 However, if the current set of actions was reached
1032 through ``resubmit'' then remaining actions in outer lev‐
1033 els resume processing.
1034 note:[hh]...
1036 Does nothing at all. Any number of bytes represented as
1037 hex digits hh may be included. Pairs of hex digits may
1038 be separated by periods for readability. The note
1039 action's format doesn't include an exact length for its
1040 payload, so the provided bytes will be padded on the
1041 right by enough bytes with value 0 to make the total num‐
1042 ber 6 more than a multiple of 8.
1043 move:src[start..end]->dst[start..end]
1045 Copies the named bits from field src to field dst. src
1046 and dst must be NXM field names as defined in
1047 nicira-ext.h, e.g. NXM_OF_UDP_SRC or NXM_NX_REG0. Each
1048 start and end pair, which are inclusive, must specify the
1049 same number of bits and must fit within its respective
1050 field. Shorthands for [start..end] exist: use [bit] to
1051 specify a single bit or [] to specify an entire field.
1052 Examples: move:NXM_NX_REG0[0..5]->NXM_NX_REG1[26..31]
1054 copies the six bits numbered 0 through 5, inclusive, in
1055 register 0 into bits 26 through 31, inclusive;
1056 move:NXM_NX_REG0[0..15]->NXM_OF_VLAN_TCI[] copies the
1057 least significant 16 bits of register 0 into the VLAN TCI
1058 field.
1059 load:value->dst[start..end]
1061 Writes value to bits start through end, inclusive, in
1062 field dst.
1063 Example: load:55->NXM_NX_REG2[0..5] loads value 55 (bit
1065 pattern 110111) into bits 0 through 5, inclusive, in reg‐
1066 ister 2.
1067 push:src[start..end]
1069 Pushes start to end bits inclusive, in fields on top of
1070 the stack.
1071 Example: push:NXM_NX_REG2[0..5] push the value stored in
1073 register 2 bits 0 through 5, inclusive, on to the inter‐
1074 nal stack.
1075 pop:dst[start..end]
1077 Pops from the top of the stack, retrieves the start to
1078 end bits inclusive, from the value popped and store them
1079 into the corresponding bits in dst.
1080 Example: pop:NXM_NX_REG2[0..5] pops the value from top of
1082 the stack. Set register 2 bits 0 through 5, inclusive,
1083 based on bits 0 through 5 from the value just popped.
1084 set_field:value->dst
1086 Writes the literal value into the field dst, which should
1087 be specified as a name used for matching. (This is simi‐
1088 lar to load but more closely matches the set-field action
1089 defined in Open Flow 1.2 and above.)
1090 Example: set_field:00:11:22:33:44:55->eth_src.
1092 multipath(fields, basis, algorithm, n_links, arg,
1094 dst[start..end])
1095 Hashes fields using basis as a universal hash parameter,
1096 then the applies multipath link selection algorithm (with
1097 parameter arg) to choose one of n_links output links num‐
1098 bered 0 through n_links minus 1, and stores the link into
1099 dst[start..end], which must be an NXM field as described
1100 above.
1101 Currently, fields must be either eth_src or symmetric_l4
1103 and algorithm must be one of modulo_n, hash_threshold,
1104 hrw, and iter_hash. Only the iter_hash algorithm uses
1105 arg.
1106 Refer to nicira-ext.h for more details.
1108 bundle(fields, basis, algorithm, slave_type, slaves:[s1, s2,
1110 ...])
1111 Hashes fields using basis as a universal hash parameter,
1112 then applies the bundle link selection algorithm to
1113 choose one of the listed slaves represented as
1114 slave_type. Currently the only supported slave_type is
1115 ofport. Thus, each s1 through sN should be an OpenFlow
1116 port number. Outputs to the selected slave.
1117 Currently, fields must be either eth_src or symmetric_l4
1119 and algorithm must be one of hrw and active_backup.
1120 Example: bundle(eth_src,0,hrw,ofport,slaves:4,8) uses an
1122 Ethernet source hash with basis 0, to select between
1123 OpenFlow ports 4 and 8 using the Highest Random Weight
1124 algorithm.
1125 Refer to nicira-ext.h for more details.
1127 bundle_load(fields, basis, algorithm, slave_type,
1129 dst[start..end], slaves:[s1, s2, ...])
1130 Has the same behavior as the bundle action, with one
1131 exception. Instead of outputting to the selected slave,
1132 it writes its selection to dst[start..end], which must be
1133 an NXM field as described above.
1134 Example: bundle_load(eth_src, 0, hrw, ofport,
1136 NXM_NX_REG0[], slaves:4, 8) uses an Ethernet source hash
1137 with basis 0, to select between OpenFlow ports 4 and 8
1138 using the Highest Random Weight algorithm, and writes the
1139 selection to NXM_NX_REG0[].
1140 Refer to nicira-ext.h for more details.
1142 learn(argument[,argument]...)
1144 This action adds or modifies a flow in an OpenFlow table,
1145 similar to ovs-ofctl --strict mod-flows. The arguments
1146 specify the flow's match fields, actions, and other prop‐
1147 erties, as follows. At least one match criterion and one
1148 action argument should ordinarily be specified.
1149 idle_timeout=seconds
1151 hard_timeout=seconds
1152 priority=value
1153 These key-value pairs have the same meaning as in
1154 the usual ovs-ofctl flow syntax.
1155 fin_idle_timeout=seconds
1157 fin_hard_timeout=seconds
1158 Adds a fin_timeout action with the specified argu‐
1159 ments to the new flow. This feature was added in
1160 Open vSwitch 1.5.90.
1161 table=number
1163 The table in which the new flow should be
1164 inserted. Specify a decimal number between 0 and
1165 254. The default, if table is unspecified, is ta‐
1166 ble 1.
1167 field=value
1169 field[start..end]=src[start..end]
1170 field[start..end]
1171 Adds a match criterion to the new flow.
1172 The first form specifies that field must match the
1174 literal value, e.g. dl_type=0x0800. All of the
1175 fields and values for ovs-ofctl flow syntax are
1176 available with their usual meanings.
1177 The second form specifies that field[start..end]
1179 in the new flow must match src[start..end] taken
1180 from the flow currently being processed.
1181 The third form is a shorthand for the second form.
1183 It specifies that field[start..end] in the new
1184 flow must match field[start..end] taken from the
1185 flow currently being processed.
1186 load:value->dst[start..end]
1188 load:src[start..end]->dst[start..end]
1189 Adds a load action to the new flow.
1190 The first form loads the literal value into bits
1192 start through end, inclusive, in field dst. Its
1193 syntax is the same as the load action described
1194 earlier in this section.
1195 The second form loads src[start..end], a value
1197 from the flow currently being processed, into bits
1198 start through end, inclusive, in field dst.
1199 output:field[start..end]
1201 Add an output action to the new flow's actions,
1202 that outputs to the OpenFlow port taken from
1203 field[start..end], which must be an NXM field as
1204 described above.
1205 For best performance, segregate learned flows into a ta‐
1207 ble (using table=number) that is not used for any other
1208 flows except possibly for a lowest-priority ``catch-all''
1209 flow, that is, a flow with no match criteria. (This is
1210 why the default table is 1, to keep the learned flows
1211 separate from the primary flow table 0.)
1212 apply_actions([action][,action...])
1214 Applies the specific action(s) immediately. The syntax of
1215 actions are same to actions= field.
1216 clear_actions
1218 Clears all the actions in the action set immediately.
1219 write_metadata:value[/mask]
1221 Updates the metadata field for the flow. If mask is omit‐
1222 ted, the metadata field is set exactly to value; if mask
1223 is specified, then a 1-bit in mask indicates that the
1224 corresponding bit in the metadata field will be replaced
1225 with the corresponding bit from value. Both value and
1226 mask are 64-bit values that are decimal by default; use a
1227 0x prefix to specify them in hexadecimal.
1228 goto_table:table
1230 Indicates the next table in the process pipeline.
1231 fin_timeout(argument[,argument])
1233 This action changes the idle timeout or hard timeout, or
1234 both, of this OpenFlow rule when the rule matches a TCP
1235 packet with the FIN or RST flag. When such a packet is
1236 observed, the action reduces the rule's timeouts to those
1237 specified on the action. If the rule's existing timeout
1238 is already shorter than the one that the action speci‐
1239 fies, then that timeout is unaffected.
1240 argument takes the following forms:
1242 idle_timeout=seconds
1244 Causes the flow to expire after the given number
1245 of seconds of inactivity.
1246 hard_timeout=seconds
1248 Causes the flow to expire after the given number
1249 of seconds, regardless of activity. (seconds
1250 specifies time since the flow's creation, not
1251 since the receipt of the FIN or RST.)
1252 This action was added in Open vSwitch 1.5.90.
1254 sample(argument[,argument]...)
1256 Samples packets and sends one sample for every sampled
1257 packet.
1258 argument takes the following forms:
1260 probability=packets
1262 The number of sampled packets out of 65535. Must
1263 be greater or equal to 1.
1264 collector_set_id=id
1266 The unsigned 32-bit integer identifier of the set
1267 of sample collectors to send sampled packets to.
1268 Defaults to 0.
1269 obs_domain_id=id
1271 When sending samples to IPFIX collectors, the
1272 unsigned 32-bit integer Observation Domain ID sent
1273 in every IPFIX flow record. Defaults to 0.
1274 obs_point_id=id
1276 When sending samples to IPFIX collectors, the
1277 unsigned 32-bit integer Observation Point ID sent
1278 in every IPFIX flow record. Defaults to 0.
1279 Refer to ovs-vswitchd.conf.db(8) for more details on con‐
1281 figuring sample collector sets.
1282 This action was added in Open vSwitch 1.10.90.
1284 exit This action causes Open vSwitch to immediately halt exe‐
1286 cution of further actions. Those actions which have
1287 already been executed are unaffected. Any further
1288 actions, including those which may be in other tables, or
1289 different levels of the resubmit call stack, are ignored.
1290 An opaque identifier called a cookie can be used as a handle to iden‐
1292 tify a set of flows:
1293 cookie=value
1295 A cookie can be associated with a flow using the add-flow,
1296 add-flows, and mod-flows commands. value can be any 64-bit num‐
1297 ber and need not be unique among flows. If this field is omit‐
1298 ted, a default cookie value of 0 is used.
1299 cookie=value/mask
1301 When using NXM, the cookie can be used as a handle for querying,
1302 modifying, and deleting flows. value and mask may be supplied
1303 for the del-flows, mod-flows, dump-flows, and dump-aggregate
1304 commands to limit matching cookies. A 1-bit in mask indicates
1305 that the corresponding bit in cookie must match exactly, and a
1306 0-bit wildcards that bit. A mask of -1 may be used to exactly
1307 match a cookie.
1308 The mod-flows command can update the cookies of flows that match
1310 a cookie by specifying the cookie field twice (once with a mask
1311 for matching and once without to indicate the new value):
1312 ovs-ofctl mod-flows br0 cookie=1,actions=normal
1314 Change all flows' cookies to 1 and change their actions
1315 to normal.
1316 ovs-ofctl mod-flows br0 cookie=1/-1,cookie=2,actions=normal
1318 Update cookies with a value of 1 to 2 and change their
1319 actions to normal.
1320 The ability to match on cookies was added in Open vSwitch 1.5.0.
1322 The following additional field sets the priority for flows added by the
1324 add-flow and add-flows commands. For mod-flows and del-flows when
1325 --strict is specified, priority must match along with the rest of the
1326 flow specification. For mod-flows without --strict, priority is only
1327 significant if the command creates a new flow, that is, non-strict
1328 mod-flows does not match on priority and will not change the priority
1329 of existing flows. Other commands do not allow priority to be speci‐
1330 fied.
1331 priority=value
1333 The priority at which a wildcarded entry will match in compari‐
1334 son to others. value is a number between 0 and 65535, inclu‐
1335 sive. A higher value will match before a lower one. An exact-
1336 match entry will always have priority over an entry containing
1337 wildcards, so it has an implicit priority value of 65535. When
1338 adding a flow, if the field is not specified, the flow's prior‐
1339 ity will default to 32768.
1340 OpenFlow leaves behavior undefined when two or more flows with
1342 the same priority can match a single packet. Some users expect
1343 ``sensible'' behavior, such as more specific flows taking prece‐
1344 dence over less specific flows, but OpenFlow does not specify
1345 this and Open vSwitch does not implement it. Users should
1346 therefore take care to use priorities to ensure the behavior
1347 that they expect.
1348 The add-flow, add-flows, and mod-flows commands support the following
1350 additional options. These options affect only new flows. Thus, for
1351 add-flow and add-flows, these options are always significant, but for
1352 mod-flows they are significant only if the command creates a new flow,
1353 that is, their values do not update or affect existing flows.
1354 idle_timeout=seconds
1356 Causes the flow to expire after the given number of seconds of
1357 inactivity. A value of 0 (the default) prevents a flow from
1358 expiring due to inactivity.
1359 hard_timeout=seconds
1361 Causes the flow to expire after the given number of seconds,
1362 regardless of activity. A value of 0 (the default) gives the
1363 flow no hard expiration deadline.
1364 send_flow_rem
1366 Marks the flow with a flag that causes the switch to generate a
1367 ``flow removed'' message and send it to interested controllers
1368 when the flow later expires or is removed.
1369 check_overlap
1371 Forces the switch to check that the flow match does not overlap
1372 that of any different flow with the same priority in the same
1373 table. (This check is expensive so it is best to avoid it.)
1374 The dump-flows, dump-aggregate, del-flow and del-flows commands support
1376 one additional optional field:
1377 out_port=port
1379 If set, a matching flow must include an output action to port,
1380 which must an OpenFlow port number or name (e.g. local).
1381 Table Entry Output
1383 The dump-tables and dump-aggregate commands print information about the
1384 entries in a datapath's tables. Each line of output is a flow entry as
1385 described in Flow Syntax, above, plus some additional fields:
1386 duration=secs
1388 The time, in seconds, that the entry has been in the table.
1389 secs includes as much precision as the switch provides, possibly
1390 to nanosecond resolution.
1391 n_packets
1393 The number of packets that have matched the entry.
1394 n_bytes
1396 The total number of bytes from packets that have matched the
1397 entry.
1398 The following additional fields are included only if the switch is Open
1400 vSwitch 1.6 or later and the NXM flow format is used to dump the flow
1401 (see the description of the --flow-format option below). The values of
1402 these additional fields are approximations only and in particular
1403 idle_age will sometimes become nonzero even for busy flows.
1404 hard_age=secs
1406 The integer number of seconds since the flow was added or modi‐
1407 fied. hard_age is displayed only if it differs from the integer
1408 part of duration. (This is separate from duration because
1409 mod-flows restarts the hard_timeout timer without zeroing dura‐
1410 tion.)
1411 idle_age=secs
1413 The integer number of seconds that have passed without any pack‐
1414 ets passing through the flow.
1415
1417 --strict
1418 Uses strict matching when running flow modification commands.
1419 -O [version[,version]...]
1421 --protocols=[version[,version]...]
1422 Sets the OpenFlow protocol versions that are allowed when estab‐
1423 lishing an OpenFlow session.
1424 The following versions are considered to be ready for general
1426 use. These protocol versions are enabled by default:
1427 · OpenFlow10, for OpenFlow 1.0.
1429 Support for the following protocol versions is provided for
1431 testing and development purposes. They are not enabled by
1432 default:
1433 · OpenFlow11, for OpenFlow 1.1.
1435 · OpenFlow12, for OpenFlow 1.2.
1437 · OpenFlow13, for OpenFlow 1.3.
1439 -F format[,format...]
1441 --flow-format=format[,format...]
1442 ovs-ofctl supports the following individual flow formats, any
1443 number of which may be listed as format:
1444 OpenFlow10-table_id
1446 This is the standard OpenFlow 1.0 flow format. All Open‐
1447 Flow switches and all versions of Open vSwitch support
1448 this flow format.
1449 OpenFlow10+table_id
1451 This is the standard OpenFlow 1.0 flow format plus a
1452 Nicira extension that allows ovs-ofctl to specify the
1453 flow table in which a particular flow should be placed.
1454 Open vSwitch 1.2 and later supports this flow format.
1455 NXM-table_id (Nicira Extended Match)
1457 This Nicira extension to OpenFlow is flexible and exten‐
1458 sible. It supports all of the Nicira flow extensions,
1459 such as tun_id and registers. Open vSwitch 1.1 and later
1460 supports this flow format.
1461 NXM+table_id (Nicira Extended Match)
1463 This combines Nicira Extended match with the ability to
1464 place a flow in a specific table. Open vSwitch 1.2 and
1465 later supports this flow format.
1466 OXM-OpenFlow12
1468 OXM-OpenFlow13
1469 These are the standard OXM (OpenFlow Extensible Match)
1470 flow format in OpenFlow 1.2 and 1.3, respectively.
1471 ovs-ofctl also supports the following abbreviations for collec‐
1473 tions of flow formats:
1474 any Any supported flow format.
1476 OpenFlow10
1478 OpenFlow10-table_id or OpenFlow10+table_id.
1479 NXM NXM-table_id or NXM+table_id.
1481 OXM OXM-OpenFlow12 or OXM-OpenFlow13.
1483 For commands that modify the flow table, ovs-ofctl by default
1485 negotiates the most widely supported flow format that supports
1486 the flows being added. For commands that query the flow table,
1487 ovs-ofctl by default uses the most advanced format supported by
1488 the switch.
1489 This option, where format is a comma-separated list of one or
1491 more of the formats listed above, limits ovs-ofctl's choice of
1492 flow format. If a command cannot work as requested using one of
1493 the specified flow formats, ovs-ofctl will report a fatal error.
1494 -P format
1496 --packet-in-format=format
1497 ovs-ofctl supports the following packet_in formats, in order of
1498 increasing capability:
1499 openflow10
1501 This is the standard OpenFlow 1.0 packet in format. It
1502 should be supported by all OpenFlow switches.
1503 nxm (Nicira Extended Match)
1505 This packet_in format includes flow metadata encoded
1506 using the NXM format.
1507 Usually, ovs-ofctl prefers the nxm packet_in format, but will
1509 allow the switch to choose its default if nxm is unsupported.
1510 When format is one of the formats listed in the above table,
1511 ovs-ofctl will insist on the selected format. If the switch
1512 does not support the requested format, ovs-ofctl will report a
1513 fatal error. This option only affects the monitor command.
1514 --timestamp
1516 Print a timestamp before each received packet. This option only
1517 affects the monitor and snoop commands.
1518 -m
1520 --more Increases the verbosity of OpenFlow messages printed and logged
1521 by ovs-ofctl commands. Specify this option more than once to
1522 increase verbosity further.
1523 --sort[=field]
1525 --rsort[=field]
1526 Display output sorted by flow field in ascending (--sort) or
1527 descending (--rsort) order, where field is any of the fields
1528 that are allowed for matching or priority to sort by priority.
1529 When field is omitted, the output is sorted by priority. Spec‐
1530 ify these options multiple times to sort by multiple fields.
1531 Any given flow will not necessarily specify a value for a given
1533 field. This requires special treatement:
1534 · A flow that does not specify any part of a field that is
1536 used for sorting is sorted after all the flows that do
1537 specify the field. For example, --sort=tcp_src will sort
1538 all the flows that specify a TCP source port in ascending
1539 order, followed by the flows that do not specify a TCP
1540 source port at all.
1541 · A flow that only specifies some bits in a field is sorted
1543 as if the wildcarded bits were zero. For example,
1544 --sort=nw_src would sort a flow that specifies
1545 nw_src=192.168.0.0/24 the same as nw_src=192.168.0.0.
1546 These options currently affect only dump-flows output.
1548 --pidfile[=pidfile]
1550 Causes a file (by default, ovs-ofctl.pid) to be created indicat‐
1551 ing the PID of the running process. If the pidfile argument is
1552 not specified, or if it does not begin with /, then it is cre‐
1553 ated in /var/run/openvswitch.
1554 If --pidfile is not specified, no pidfile is created.
1556 --overwrite-pidfile
1558 By default, when --pidfile is specified and the specified pid‐
1559 file already exists and is locked by a running process,
1560 ovs-ofctl refuses to start. Specify --overwrite-pidfile to
1561 cause it to instead overwrite the pidfile.
1562 When --pidfile is not specified, this option has no effect.
1564 --detach
1566 Causes ovs-ofctl to detach itself from the foreground session
1567 and run as a background process. ovs-ofctl detaches only when
1568 executing the monitor or snoop commands.
1569 --monitor
1571 Creates an additional process to monitor the ovs-ofctl daemon.
1572 If the daemon dies due to a signal that indicates a programming
1573 error (e.g. SIGSEGV, SIGABRT), then the monitor process starts a
1574 new copy of it. If the daemon die or exits for another reason,
1575 the monitor process exits.
1576 This option is normally used with --detach, but it also func‐
1578 tions without it.
1579 --no-chdir
1581 By default, when --detach is specified, ovs-ofctl changes its
1582 current working directory to the root directory after it
1583 detaches. Otherwise, invoking ovs-ofctl from a carelessly cho‐
1584 sen directory would prevent the administrator from unmounting
1585 the file system that holds that directory.
1586 Specifying --no-chdir suppresses this behavior, preventing
1588 ovs-ofctl from changing its current working directory. This may
1589 be useful for collecting core files, since it is common behavior
1590 to write core dumps into the current working directory and the
1591 root directory is not a good directory to use.
1592 This option has no effect when --detach is not specified.
1594 Public Key Infrastructure Options
1596 -p privkey.pem
1597 --private-key=privkey.pem
1598 Specifies a PEM file containing the private key used as
1599 ovs-ofctl's identity for outgoing SSL connections.
1600 -c cert.pem
1602 --certificate=cert.pem
1603 Specifies a PEM file containing a certificate that certifies the
1604 private key specified on -p or --private-key to be trustworthy.
1605 The certificate must be signed by the certificate authority (CA)
1606 that the peer in SSL connections will use to verify it.
1607 -C cacert.pem
1609 --ca-cert=cacert.pem
1610 Specifies a PEM file containing the CA certificate that
1611 ovs-ofctl should use to verify certificates presented to it by
1612 SSL peers. (This may be the same certificate that SSL peers use
1613 to verify the certificate specified on -c or --certificate, or
1614 it may be a different one, depending on the PKI design in use.)
1615 -C none
1617 --ca-cert=none
1618 Disables verification of certificates presented by SSL peers.
1619 This introduces a security risk, because it means that certifi‐
1620 cates cannot be verified to be those of known trusted hosts.
1621 -v[spec]
1623 --verbose=[spec]
1624 Sets logging levels. Without any spec, sets the log level for
1625 every module and facility to dbg. Otherwise, spec is a list of
1626 words separated by spaces or commas or colons, up to one from
1627 each category below:
1628 · A valid module name, as displayed by the vlog/list com‐
1630 mand on ovs-appctl(8), limits the log level change to the
1631 specified module.
1632 · syslog, console, or file, to limit the log level change
1634 to only to the system log, to the console, or to a file,
1635 respectively.
1636 · off, emer, err, warn, info, or dbg, to control the log
1638 level. Messages of the given severity or higher will be
1639 logged, and messages of lower severity will be filtered
1640 out. off filters out all messages. See ovs-appctl(8)
1641 for a definition of each log level.
1642 Case is not significant within spec.
1644 Regardless of the log levels set for file, logging to a file
1646 will not take place unless --log-file is also specified (see
1647 below).
1648 For compatibility with older versions of OVS, any is accepted as
1650 a word but has no effect.
1651 -v
1653 --verbose
1654 Sets the maximum logging verbosity level, equivalent to --ver‐
1655 bose=dbg.
1656 --log-file[=file]
1658 Enables logging to a file. If file is specified, then it is
1659 used as the exact name for the log file. The default log file
1660 name used if file is omitted is /var/log/open‐
1661 vswitch/ovs-ofctl.log.
1662 -h
1664 --help Prints a brief help message to the console.
1665 -V
1667 --version
1668 Prints version information to the console.
1669
1671 ovs-appctl(8) can send commands to a running ovs-ofctl process. The
1672 supported commands are listed below.
1673 exit Causes ovs-ofctl to gracefully terminate. This command applies
1675 only when executing the monitor or snoop commands.
1676 ofctl/set-output-file file
1678 Causes all subsequent output to go to file instead of stderr.
1679 This command applies only when executing the monitor or snoop
1680 commands.
1681 ofctl/send ofmsg...
1683 Sends each ofmsg, specified as a sequence of hex digits that
1684 express an OpenFlow message, on the OpenFlow connection. This
1685 command is useful only when executing the monitor command.
1686 ofctl/barrier
1688 Sends an OpenFlow barrier request on the OpenFlow connection and
1689 waits for a reply. This command is useful only for the monitor
1690 command.
1691
1693 The following examples assume that ovs-vswitchd has a bridge named br0
1694 configured.
1695 ovs-ofctl dump-tables br0
1697 Prints out the switch's table stats. (This is more interesting
1698 after some traffic has passed through.)
1699 ovs-ofctl dump-flows br0
1701 Prints the flow entries in the switch.
1702
1704 ovs-appctl(8), ovs-controller(8), ovs-vswitchd(8)
1705 ovs-vswitchd.conf.db(8)
1706Open vSwitch 2.0.0 ovs-ofctl(8)