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:host[:port]
27 tcp:host[:port]
28 The specified port on the given host, which can be
29 expressed either as a DNS name (if built with unbound
30 library) or an IP address in IPv4 or IPv6 address format.
31 Wrap IPv6 addresses in square brackets, e.g.
32 tcp:[::1]:6653. On Linux, use %device to designate a
33 scope for IPv6 link-level addresses, e.g.
34 tcp:[fe80::1234%eth0]:6653. For ssl, the --private-key,
35 --certificate, and --ca-cert options are mandatory.
36 If port is not specified, it defaults to 6653.
38 unix:file
40 On POSIX, a Unix domain server socket named file.
41 On Windows, connect to a local named pipe that is repre‐
43 sented by a file created in the path file to mimic the
44 behavior of a Unix domain socket.
45 file This is short for unix:file, as long as file does not
47 contain a colon.
48 bridge This is short for unix:/var/run/openvswitch/bridge.mgmt,
50 as long as bridge does not contain a colon.
51 [type@]dp
53 Attempts to look up the bridge associated with dp and
54 open as above. If type is given, it specifies the data‐
55 path provider of dp, otherwise the default provider sys‐
56 tem is assumed.
57 show switch
59 Prints to the console information on switch, including informa‐
60 tion on its flow tables and ports.
61 dump-tables switch
63 Prints to the console statistics for each of the flow tables
64 used by switch.
65 dump-table-features switch
67 Prints to the console features for each of the flow tables used
68 by switch.
69 dump-table-desc switch
71 Prints to the console configuration for each of the flow tables
72 used by switch for OpenFlow 1.4+.
73 mod-table switch table setting
75 This command configures flow table settings in switch for Open‐
76 Flow table table, which may be expressed as a number or (unless
77 --no-names is specified) a name.
78 The available settings depend on the OpenFlow version in use.
80 In OpenFlow 1.1 and 1.2 (which must be enabled with the -O
81 option) only, mod-table configures behavior when no flow is
82 found when a packet is looked up in a flow table. The following
83 setting values are available:
84 drop Drop the packet.
86 continue
88 Continue to the next table in the pipeline. (This is how
89 an OpenFlow 1.0 switch always handles packets that do not
90 match any flow, in tables other than the last one.)
91 controller
93 Send to controller. (This is how an OpenFlow 1.0 switch
94 always handles packets that do not match any flow in the
95 last table.)
96 In OpenFlow 1.4 and later (which must be enabled with the -O
98 option) only, mod-table configures the behavior when a con‐
99 troller attempts to add a flow to a flow table that is full.
100 The following setting values are available:
101 evict Delete some existing flow from the flow table, according
103 to the algorithm described for the Flow_Table table in
104 ovs-vswitchd.conf.db(5).
105 noevict
107 Refuse to add the new flow. (Eviction might still be
108 enabled through the overflow_policy column in the
109 Flow_Table table documented in ovs-vswitchd.conf.db(5).)
110 vacancy:low,high
112 Enables sending vacancy events to controllers using TA‐
113 BLE_STATUS messages, based on percentage thresholds low
114 and high.
115 novacancy
117 Disables vacancy events.
118 dump-ports switch [netdev]
120 Prints to the console statistics for network devices associated
121 with switch. If netdev is specified, only the statistics asso‐
122 ciated with that device will be printed. netdev can be an Open‐
123 Flow assigned port number or device name, e.g. eth0.
124 dump-ports-desc switch [port]
126 Prints to the console detailed information about network devices
127 associated with switch. To dump only a specific port, specify
128 its number as port. Otherwise, if port is omitted, or if it is
129 specified as ANY, then all ports are printed. This is a subset
130 of the information provided by the show command.
131 If the connection to switch negotiates OpenFlow 1.0, 1.2, or
133 1.2, this command uses an OpenFlow extension only implemented in
134 Open vSwitch (version 1.7 and later).
135 Only OpenFlow 1.5 and later support dumping a specific port.
137 Earlier versions of OpenFlow always dump all ports.
138 mod-port switch port action
140 Modify characteristics of port port in switch. port may be an
141 OpenFlow port number or name (unless --no-names is specified) or
142 the keyword LOCAL (the preferred way to refer to the OpenFlow
143 local port). The action may be any one of the following:
144 up
145 down Enable or disable the interface. This is equivalent to
146 ip link set up or ip link set down on a Unix system.
147 stp
149 no-stp Enable or disable 802.1D spanning tree protocol (STP) on
150 the interface. OpenFlow implementations that don't sup‐
151 port STP will refuse to enable it.
152 receive
154 no-receive
155 receive-stp
156 no-receive-stp
157 Enable or disable OpenFlow processing of packets received
158 on this interface. When packet processing is disabled,
159 packets will be dropped instead of being processed
160 through the OpenFlow table. The receive or no-receive
161 setting applies to all packets except 802.1D spanning
162 tree packets, which are separately controlled by
163 receive-stp or no-receive-stp.
164 forward
166 no-forward
167 Allow or disallow forwarding of traffic to this inter‐
168 face. By default, forwarding is enabled.
169 flood
171 no-flood
172 Controls whether an OpenFlow flood action will send traf‐
173 fic out this interface. By default, flooding is enabled.
174 Disabling flooding is primarily useful to prevent loops
175 when a spanning tree protocol is not in use.
176 packet-in
178 no-packet-in
179 Controls whether packets received on this interface that
180 do not match a flow table entry generate a ``packet in''
181 message to the OpenFlow controller. By default, ``packet
182 in'' messages are enabled.
183 The show command displays (among other information) the configu‐
185 ration that mod-port changes.
186 get-frags switch
188 Prints switch's fragment handling mode. See set-frags, below,
189 for a description of each fragment handling mode.
190 The show command also prints the fragment handling mode among
192 its other output.
193 set-frags switch frag_mode
195 Configures switch's treatment of IPv4 and IPv6 fragments. The
196 choices for frag_mode are:
197 normal Fragments pass through the flow table like non-fragmented
199 packets. The TCP ports, UDP ports, and ICMP type and
200 code fields are always set to 0, even for fragments where
201 that information would otherwise be available (fragments
202 with offset 0). This is the default fragment handling
203 mode for an OpenFlow switch.
204 drop Fragments are dropped without passing through the flow
206 table.
207 reassemble
209 The switch reassembles fragments into full IP packets
210 before passing them through the flow table. Open vSwitch
211 does not implement this fragment handling mode.
212 nx-match
214 Fragments pass through the flow table like non-fragmented
215 packets. The TCP ports, UDP ports, and ICMP type and
216 code fields are available for matching for fragments with
217 offset 0, and set to 0 in fragments with nonzero offset.
218 This mode is a Nicira extension.
219 See the description of ip_frag, below, for a way to match on
221 whether a packet is a fragment and on its fragment offset.
222 dump-flows switch [flows]
224 Prints to the console all flow entries in switch's tables that
225 match flows. If flows is omitted, all flows in the switch are
226 retrieved. See Flow Syntax, below, for the syntax of flows.
227 The output format is described in Table Entry Output.
228 By default, ovs-ofctl prints flow entries in the same order that
230 the switch sends them, which is unlikely to be intuitive or con‐
231 sistent. Use --sort and --rsort to control display order. The
232 --names/--no-names and --stats/--no-stats options also affect
233 output formatting. See the descriptions of these options, under
234 OPTIONS below, for more information
235 dump-aggregate switch [flows]
237 Prints to the console aggregate statistics for flows in switch's
238 tables that match flows. If flows is omitted, the statistics
239 are aggregated across all flows in the switch's flow tables.
240 See Flow Syntax, below, for the syntax of flows. The output
241 format is described in Table Entry Output.
242 queue-stats switch [port [queue]]
244 Prints to the console statistics for the specified queue on port
245 within switch. port can be an OpenFlow port number or name, the
246 keyword LOCAL (the preferred way to refer to the OpenFlow local
247 port), or the keyword ALL. Either of port or queue or both may
248 be omitted (or equivalently the keyword ALL). If both are omit‐
249 ted, statistics are printed for all queues on all ports. If
250 only queue is omitted, then statistics are printed for all
251 queues on port; if only port is omitted, then statistics are
252 printed for queue on every port where it exists.
253 queue-get-config switch [port [queue]]
255 Prints to the console the configuration of queue on port in
256 switch. If port is omitted or ANY, reports queues for all port.
257 If queue is omitted or ANY, reports all queues. For OpenFlow
258 1.3 and earlier, the output always includes all queues, ignoring
259 queue if specified.
260 This command has limited usefulness, because ports often have no
262 configured queues and because the OpenFlow protocol provides
263 only very limited information about the configuration of a
264 queue.
265 dump-ipfix-bridge switch
267 Prints to the console the statistics of bridge IPFIX for switch.
268 If bridge IPFIX is configured on the switch, IPFIX statistics
269 can be retrieved. Otherwise, error message will be printed.
270 This command uses an Open vSwitch extension that is only in Open
272 vSwitch 2.6 and later.
273 dump-ipfix-flow switch
275 Prints to the console the statistics of flow-based IPFIX for
276 switch. If flow-based IPFIX is configured on the switch, sta‐
277 tistics of all the collector set ids on the switch will be
278 printed. Otherwise, print error message.
279 Refer to ovs-vswitchd.conf.db(5) for more details on configuring
281 flow based IPFIX and collector set ids.
282 This command uses an Open vSwitch extension that is only in Open
284 vSwitch 2.6 and later.
285 ct-flush-zone switch zone
287 Flushes the connection tracking entries in zone on switch.
288 This command uses an Open vSwitch extension that is only in Open
290 vSwitch 2.6 and later.
291 OpenFlow Switch Flow Table Commands
293 These commands manage the flow table in an OpenFlow switch. In each
294 case, flow specifies a flow entry in the format described in Flow Syn‐
295 tax, below, file is a text file that contains zero or more flows in the
296 same syntax, one per line, and the optional --bundle option operates
297 the command as a single atomic transation, see option --bundle, below.
298 [--bundle] add-flow switch flow
300 [--bundle] add-flow switch - < file
301 [--bundle] add-flows switch file
302 Add each flow entry to switch's tables. Each flow specification
303 (e.g., each line in file) may start with add, modify, delete,
304 modify_strict, or delete_strict keyword to specify whether a
305 flow is to be added, modified, or deleted, and whether the mod‐
306 ify or delete is strict or not. For backwards compatibility a
307 flow specification without one of these keywords is treated as a
308 flow add. All flow mods are executed in the order specified.
309 [--bundle] [--strict] mod-flows switch flow
311 [--bundle] [--strict] mod-flows switch - < file
312 Modify the actions in entries from switch's tables that match
313 the specified flows. With --strict, wildcards are not treated
314 as active for matching purposes.
315 [--bundle] del-flows switch
317 [--bundle] [--strict] del-flows switch [flow]
318 [--bundle] [--strict] del-flows switch - < file
319 Deletes entries from switch's flow table. With only a switch
320 argument, deletes all flows. Otherwise, deletes flow entries
321 that match the specified flows. With --strict, wildcards are
322 not treated as active for matching purposes.
323 [--bundle] [--readd] replace-flows switch file
325 Reads flow entries from file (or stdin if file is -) and queries
326 the flow table from switch. Then it fixes up any differences,
327 adding flows from flow that are missing on switch, deleting
328 flows from switch that are not in file, and updating flows in
329 switch whose actions, cookie, or timeouts differ in file.
330 With --readd, ovs-ofctl adds all the flows from file, even those
332 that exist with the same actions, cookie, and timeout in switch.
333 In OpenFlow 1.0 and 1.1, re-adding a flow always resets the
334 flow's packet and byte counters to 0, and in OpenFlow 1.2 and
335 later, it does so only if the reset_counts flag is set.
336 diff-flows source1 source2
338 Reads flow entries from source1 and source2 and prints the dif‐
339 ferences. A flow that is in source1 but not in source2 is
340 printed preceded by a -, and a flow that is in source2 but not
341 in source1 is printed preceded by a +. If a flow exists in both
342 source1 and source2 with different actions, cookie, or timeouts,
343 then both versions are printed preceded by - and +, respec‐
344 tively.
345 source1 and source2 may each name a file or a switch. If a name
347 begins with / or ., then it is considered to be a file name. A
348 name that contains : is considered to be a switch. Otherwise,
349 it is a file if a file by that name exists, a switch if not.
350 For this command, an exit status of 0 means that no differences
352 were found, 1 means that an error occurred, and 2 means that
353 some differences were found.
354 packet-out switch packet-out
356 Connects to switch and instructs it to execute the packet-out
357 OpenFlow message, specified as defined in Packet-Out Syntax sec‐
358 tion.
359 Group Table Commands
361 These commands manage the group table in an OpenFlow switch. In each
362 case, group specifies a group entry in the format described in Group
363 Syntax, below, and file is a text file that contains zero or more
364 groups in the same syntax, one per line, and the optional --bundle
365 option operates the command as a single atomic transation, see option
366 --bundle, below.
367 The group commands work only with switches that support OpenFlow 1.1 or
369 later or the Open vSwitch group extensions to OpenFlow 1.0 (added in
370 Open vSwitch 2.9.90). For OpenFlow 1.1 or later, it is necessary to
371 explicitly enable these protocol versions in ovs-ofctl (using -O). For
372 more information, see ``Q: What versions of OpenFlow does Open vSwitch
373 support?'' in the Open vSwitch FAQ.
374 [--bundle] add-group switch group
376 [--bundle] add-group switch - < file
377 [--bundle] add-groups switch file
378 Add each group entry to switch's tables. Each group specifica‐
379 tion (e.g., each line in file) may start with add, modify,
380 add_or_mod, delete, insert_bucket, or remove_bucket keyword to
381 specify whether a flow is to be added, modified, or deleted, or
382 whether a group bucket is to be added or removed. For backwards
383 compatibility a group specification without one of these key‐
384 words is treated as a group add. All group mods are executed in
385 the order specified.
386 [--bundle] [--may-create] mod-group switch group
388 [--bundle] [--may-create] mod-group switch - < file
389 Modify the action buckets in entries from switch's tables for
390 each group entry. If a specified group does not already exist,
391 then without --may-create, this command has no effect; with
392 --may-create, it creates a new group. The --may-create option
393 uses an Open vSwitch extension to OpenFlow only implemented in
394 Open vSwitch 2.6 and later.
395 [--bundle] del-groups switch
397 [--bundle] del-groups switch [group]
398 [--bundle] del-groups switch - < file
399 Deletes entries from switch's group table. With only a switch
400 argument, deletes all groups. Otherwise, deletes the group for
401 each group entry.
402 [--bundle] insert-buckets switch group
404 [--bundle] insert-buckets switch - < file
405 Add buckets to an existing group present in the switch's group
406 table. If no command_bucket_id is present in the group specifi‐
407 cation then all buckets of the group are removed.
408 [--bundle] remove-buckets switch group
410 [--bundle] remove-buckets switch - < file
411 Remove buckets to an existing group present in the switch's
412 group table. If no command_bucket_id is present in the group
413 specification then all buckets of the group are removed.
414 dump-groups switch [group]
416 Prints group entries in switch's tables to console. To dump
417 only a specific group, specify its number as group. Otherwise,
418 if group is omitted, or if it is specified as ALL, then all
419 groups are printed.
420 Only OpenFlow 1.5 and later support dumping a specific group.
422 Earlier versions of OpenFlow always dump all groups.
423 dump-group-features switch
425 Prints to the console the group features of the switch.
426 dump-group-stats switch [group]
428 Prints to the console statistics for the specified group in
429 switch's tables. If group is omitted then statistics for all
430 groups are printed.
431 OpenFlow 1.3+ Switch Meter Table Commands
433 These commands manage the meter table in an OpenFlow switch. In each
434 case, meter specifies a meter entry in the format described in Meter
435 Syntax, below.
436 OpenFlow 1.3 introduced support for meters, so these commands only work
438 with switches that support OpenFlow 1.3 or later. It is necessary to
439 explicitly enable these protocol versions in ovs-ofctl (using -O) and
440 in the switch itself (with the protocols column in the Bridge table).
441 For more information, see ``Q: What versions of OpenFlow does Open
442 vSwitch support?'' in the Open vSwitch FAQ.
443 add-meter switch meter
445 Add a meter entry to switch's tables. The meter syntax is
446 described in section Meter Syntax, below.
447 mod-meter switch meter
449 Modify an existing meter.
450 del-meters switch [meter]
452 Delete entries from switch's meter table. To delete only a spe‐
453 cific meter, specify its number as meter. Otherwise, if meter
454 is omitted, or if it is specified as all, then all meters are
455 deleted.
456 dump-meters switch [meter]
458 Print entries from switch's meter table. To print only a spe‐
459 cific meter, specify its number as meter. Otherwise, if meter
460 is omitted, or if it is specified as all, then all meters are
461 printed.
462 meter-stats switch [meter]
464 Print meter statistics. meter can specify a single meter with
465 syntax meter=id, or all meters with syntax meter=all.
466 meter-features switch
468 Print meter features.
469 OpenFlow Switch Bundle Command
471 Transactional updates to both flow and group tables can be made with
472 the bundle command. file is a text file that contains zero or more
473 flow mods, group mods, or packet-outs in Flow Syntax, Group Syntax, or
474 Packet-Out Syntax, each line preceded by flow, group, or packet-out
475 keyword, correspondingly. The flow keyword may be optionally followed
476 by one of the keywords add, modify, modify_strict, delete, or
477 delete_strict, of which the add is assumed if a bare flow is given.
478 Similarly, the group keyword may be optionally followed by one of the
479 keywords add, modify, add_or_mod, delete, insert_bucket, or
480 remove_bucket, of which the add is assumed if a bare group is given.
481 bundle switch file
483 Execute all flow and group mods in file as a single atomic
484 transaction against switch's tables. All bundled mods are exe‐
485 cuted in the order specified.
486 OpenFlow Switch Tunnel TLV Table Commands
488 Open vSwitch maintains a mapping table between tunnel option TLVs
489 (defined by <class, type, length>) and NXM fields tun_metadatan, where
490 n ranges from 0 to 63, that can be operated on for the purposes of
491 matches, actions, etc. This TLV table can be used for Geneve option
492 TLVs or other protocols with options in same TLV format as Geneve
493 options. This mapping must be explicitly specified by the user through
494 the following commands.
495 A TLV mapping is specified with the syntax
497 {class=class,type=type,len=length}->tun_metadatan. When an option map‐
498 ping exists for a given tun_metadatan, matching on the defined field
499 becomes possible, e.g.:
500 ovs-ofctl add-tlv-map br0
502 "{class=0xffff,type=0,len=4}->tun_metadata0"
503 ovs-ofctl add-flow br0 tun_metadata0=1234,actions=controller
505 A mapping should not be changed while it is in active use by a flow.
507 The result of doing so is undefined.
508 These commands are Nicira extensions to OpenFlow and require Open
510 vSwitch 2.5 or later.
511 add-tlv-map switch option[,option]...
514 Add each option to switch's tables. Duplicate fields are
515 rejected.
516 del-tlv-map switch [option[,option]]...
518 Delete each option from switch's table, or all option TLV map‐
519 ping if no option is specified. Fields that aren't mapped are
520 ignored.
521 dump-tlv-map switch
523 Show the currently mapped fields in the switch's option table as
524 well as switch capabilities.
525 OpenFlow Switch Monitoring Commands
527 snoop switch
528 Connects to switch and prints to the console all OpenFlow mes‐
529 sages received. Unlike other ovs-ofctl commands, if switch is
530 the name of a bridge, then the snoop command connects to a Unix
531 domain socket named /var/run/openvswitch/switch.snoop.
532 ovs-vswitchd listens on such a socket for each bridge and sends
533 to it all of the OpenFlow messages sent to or received from its
534 configured OpenFlow controller. Thus, this command can be used
535 to view OpenFlow protocol activity between a switch and its con‐
536 troller.
537 When a switch has more than one controller configured, only the
539 traffic to and from a single controller is output. If none of
540 the controllers is configured as a master or a slave (using a
541 Nicira extension to OpenFlow 1.0 or 1.1, or a standard request
542 in OpenFlow 1.2 or later), then a controller is chosen arbitrar‐
543 ily among them. If there is a master controller, it is chosen;
544 otherwise, if there are any controllers that are not masters or
545 slaves, one is chosen arbitrarily; otherwise, a slave controller
546 is chosen arbitrarily. This choice is made once at connection
547 time and does not change as controllers reconfigure their roles.
548 If a switch has no controller configured, or if the configured
550 controller is disconnected, no traffic is sent, so monitoring
551 will not show any traffic.
552 monitor switch [miss-len] [invalid_ttl] [watch:[spec...]]
554 Connects to switch and prints to the console all OpenFlow mes‐
555 sages received. Usually, switch should specify the name of a
556 bridge in the ovs-vswitchd database.
557 If miss-len is provided, ovs-ofctl sends an OpenFlow ``set con‐
559 figuration'' message at connection setup time that requests
560 miss-len bytes of each packet that misses the flow table. Open
561 vSwitch does not send these and other asynchronous messages to
562 an ovs-ofctl monitor client connection unless a nonzero value is
563 specified on this argument. (Thus, if miss-len is not speci‐
564 fied, very little traffic will ordinarily be printed.)
565 If invalid_ttl is passed, ovs-ofctl sends an OpenFlow ``set con‐
567 figuration'' message at connection setup time that requests
568 INVALID_TTL_TO_CONTROLLER, so that ovs-ofctl monitor can receive
569 ``packet-in'' messages when TTL reaches zero on dec_ttl action.
570 Only OpenFlow 1.1 and 1.2 support invalid_ttl; Open vSwitch also
571 implements it for OpenFlow 1.0 as an extension.
572 watch:[spec...] causes ovs-ofctl to send a ``monitor request''
574 Nicira extension message to the switch at connection setup time.
575 This message causes the switch to send information about flow
576 table changes as they occur. The following comma-separated spec
577 syntax is available:
578 !initial
580 Do not report the switch's initial flow table contents.
581 !add Do not report newly added flows.
583 !delete
585 Do not report deleted flows.
586 !modify
588 Do not report modifications to existing flows.
589 !own Abbreviate changes made to the flow table by ovs-ofctl's
591 own connection to the switch. (These could only occur
592 using the ofctl/send command described below under RUN‐
593 TIME MANAGEMENT COMMANDS.)
594 !actions
596 Do not report actions as part of flow updates.
597 table=table
599 Limits the monitoring to the table with the given table,
600 which may be expressed as a number between 0 and 254 or
601 (unless --no-names is specified) a name. By default, all
602 tables are monitored.
603 out_port=port
605 If set, only flows that output to port are monitored.
606 The port may be an OpenFlow port number or keyword (e.g.
607 LOCAL).
608 field=value
610 Monitors only flows that have field specified as the
611 given value. Any syntax valid for matching on dump-flows
612 may be used.
613 This command may be useful for debugging switch or controller
615 implementations. With watch:, it is particularly useful for
616 observing how a controller updates flow tables.
617 OpenFlow Switch and Controller Commands
619 The following commands, like those in the previous section, may be
620 applied to OpenFlow switches, using any of the connection methods
621 described in that section. Unlike those commands, these may also be
622 applied to OpenFlow controllers.
623 probe target
625 Sends a single OpenFlow echo-request message to target and waits
626 for the response. With the -t or --timeout option, this command
627 can test whether an OpenFlow switch or controller is up and run‐
628 ning.
629 ping target [n]
631 Sends a series of 10 echo request packets to target and times
632 each reply. The echo request packets consist of an OpenFlow
633 header plus n bytes (default: 64) of randomly generated payload.
634 This measures the latency of individual requests.
635 benchmark target n count
637 Sends count echo request packets that each consist of an Open‐
638 Flow header plus n bytes of payload and waits for each response.
639 Reports the total time required. This is a measure of the maxi‐
640 mum bandwidth to target for round-trips of n-byte messages.
641 Other Commands
643 ofp-parse file
644 Reads file (or stdin if file is -) as a series of OpenFlow mes‐
645 sages in the binary format used on an OpenFlow connection, and
646 prints them to the console. This can be useful for printing
647 OpenFlow messages captured from a TCP stream.
648 ofp-parse-pcap file [port...]
650 Reads file, which must be in the PCAP format used by network
651 capture tools such as tcpdump or wireshark, extracts all the TCP
652 streams for OpenFlow connections, and prints the OpenFlow mes‐
653 sages in those connections in human-readable format on stdout.
654 OpenFlow connections are distinguished by TCP port number. Non-
656 OpenFlow packets are ignored. By default, data on TCP ports
657 6633 and 6653 are considered to be OpenFlow. Specify one or
658 more port arguments to override the default.
659 This command cannot usefully print SSL encrypted traffic. It
661 does not understand IPv6.
662 Flow Syntax
664 Some ovs-ofctl commands accept an argument that describes a flow or
665 flows. Such flow descriptions comprise a series of field=value assign‐
666 ments, separated by commas or white space. (Embedding spaces into a
667 flow description normally requires quoting to prevent the shell from
668 breaking the description into multiple arguments.)
669 Flow descriptions should be in normal form. This means that a flow may
671 only specify a value for an L3 field if it also specifies a particular
672 L2 protocol, and that a flow may only specify an L4 field if it also
673 specifies particular L2 and L3 protocol types. For example, if the L2
674 protocol type dl_type is wildcarded, then L3 fields nw_src, nw_dst, and
675 nw_proto must also be wildcarded. Similarly, if dl_type or nw_proto
676 (the L3 protocol type) is wildcarded, so must be the L4 fields tcp_dst
677 and tcp_src. ovs-ofctl will warn about flows not in normal form.
678 ovs-fields(7) describes the supported fields and how to match them. In
680 addition to match fields, commands that operate on flows accept a few
681 additional key-value pairs:
682 table=table
684 For flow dump commands, limits the flows dumped to those in ta‐
685 ble, which may be expressed as a number between 0 and 255 or
686 (unless --no-names is specified) a name. If not specified (or
687 if 255 is specified as table), then flows in all tables are
688 dumped.
689 For flow table modification commands, behavior varies based on
691 the OpenFlow version used to connect to the switch:
692 OpenFlow 1.0
694 OpenFlow 1.0 does not support table for modifying flows.
695 ovs-ofctl will exit with an error if table (other than
696 table=255) is specified for a switch that only supports
697 OpenFlow 1.0.
698 In OpenFlow 1.0, the switch chooses the table into which
700 to insert a new flow. The Open vSwitch software switch
701 always chooses table 0. Other Open vSwitch datapaths and
702 other OpenFlow implementations may choose different
703 tables.
704 The OpenFlow 1.0 behavior in Open vSwitch for modifying
706 or removing flows depends on whether --strict is used.
707 Without --strict, the command applies to matching flows
708 in all tables. With --strict, the command will operate
709 on any single matching flow in any table; it will do
710 nothing if there are matches in more than one table.
711 (The distinction between these behaviors only matters if
712 non-OpenFlow 1.0 commands were also used, because Open‐
713 Flow 1.0 alone cannot add flows with the same matching
714 criteria to multiple tables.)
715 OpenFlow 1.0 with table_id extension
717 Open vSwitch implements an OpenFlow extension that allows
718 the controller to specify the table on which to operate.
719 ovs-ofctl automatically enables the extension when table
720 is specified and OpenFlow 1.0 is used. ovs-ofctl auto‐
721 matically detects whether the switch supports the exten‐
722 sion. As of this writing, this extension is only known
723 to be implemented by Open vSwitch.
724 With this extension, ovs-ofctl operates on the requested
726 table when table is specified, and acts as described for
727 OpenFlow 1.0 above when no table is specified (or for ta‐
728 ble=255).
729 OpenFlow 1.1
731 OpenFlow 1.1 requires flow table modification commands to
732 specify a table. When table is not specified (or ta‐
733 ble=255 is specified), ovs-ofctl defaults to table 0.
734 OpenFlow 1.2 and later
736 OpenFlow 1.2 and later allow flow deletion commands, but
737 not other flow table modification commands, to operate on
738 all flow tables, with the behavior described above for
739 OpenFlow 1.0.
740 duration=...
742 n_packet=...
743 n_bytes=...
744 ovs-ofctl ignores assignments to these ``fields'' to allow out‐
745 put from the dump-flows command to be used as input for other
746 commands that parse flows.
747 The add-flow, add-flows, and mod-flows commands require an additional
749 field, which must be the final field specified:
750 actions=[action][,action...]
752 Specifies a comma-separated list of actions to take on a packet
753 when the flow entry matches. If no action is specified, then
754 packets matching the flow are dropped. The following forms of
755 action are supported:
756 port
758 output:port
759 Outputs the packet to OpenFlow port number port. If port
760 is the packet's input port, the packet is not output.
761 output:src[start..end]
763 Outputs the packet to the OpenFlow port number read from
764 src, which may be an NXM field name, as described above,
765 or a match field name. output:reg0[16..31] outputs to
766 the OpenFlow port number written in the upper half of
767 register 0. If the port number is the packet's input
768 port, the packet is not output.
769 This form of output was added in Open vSwitch 1.3.0.
771 This form of output uses an OpenFlow extension that is
772 not supported by standard OpenFlow switches.
773 output(port=port,max_len=nbytes)
775 Outputs the packet to the OpenFlow port number read from
776 port, with maximum packet size set to nbytes. port may
777 be OpenFlow port number, local, or in_port. Patch port
778 is not supported. Packets larger than nbytes will be
779 trimmed to nbytes while packets smaller than nbytes
780 remains the original size.
781 group:group_id
783 Outputs the packet to the OpenFlow group group_id. Open‐
784 Flow 1.1 introduced support for groups; Open vSwitch 2.6
785 and later also supports output to groups as an extension
786 to OpenFlow 1.0. See Group Syntax for more details.
787 normal Subjects the packet to the device's normal L2/L3 process‐
789 ing. (This action is not implemented by all OpenFlow
790 switches.)
791 flood Outputs the packet on all switch physical ports other
793 than the port on which it was received and any ports on
794 which flooding is disabled (typically, these would be
795 ports disabled by the IEEE 802.1D spanning tree proto‐
796 col).
797 all Outputs the packet on all switch physical ports other
799 than the port on which it was received.
800 local Outputs the packet on the ``local port,'' which corre‐
802 sponds to the network device that has the same name as
803 the bridge.
804 in_port
806 Outputs the packet on the port from which it was
807 received.
808 controller(key=value...)
810 Sends the packet and its metadata to the OpenFlow con‐
811 troller as a ``packet in'' message. The supported key-
812 value pairs are:
813 max_len=nbytes
815 Limit to nbytes the number of bytes of the packet
816 to send to the controller. By default the entire
817 packet is sent.
818 reason=reason
820 Specify reason as the reason for sending the mes‐
821 sage in the ``packet in'' message. The supported
822 reasons are action (the default), no_match, and
823 invalid_ttl.
824 id=controller-id
826 Specify controller-id, a 16-bit integer, as the
827 connection ID of the OpenFlow controller or con‐
828 trollers to which the ``packet in'' message should
829 be sent. The default is zero. Zero is also the
830 default connection ID for each controller connec‐
831 tion, and a given controller connection will only
832 have a nonzero connection ID if its controller
833 uses the NXT_SET_CONTROLLER_ID Nicira extension to
834 OpenFlow.
835 userdata=hh...
837 Supplies the bytes represented as hex digits hh as
838 additional data to the controller in the packet-in
839 message. Pairs of hex digits may be separated by
840 periods for readability.
841 pause Causes the switch to freeze the packet's trip
843 through Open vSwitch flow tables and serializes
844 that state into the packet-in message as a ``con‐
845 tinuation,'' an additional property in the
846 NXT_PACKET_IN2 message. The controller can later
847 send the continuation back to the switch in an
848 NXT_RESUME message, which will restart the
849 packet's traversal from the point where it was
850 interrupted. This permits an OpenFlow controller
851 to interpose on a packet midway through processing
852 in Open vSwitch.
853 meter_id=id
855 Use meter id to rate-limit the OpenFlow packet-in
856 messages that this action sends to the controller.
857 By default, packets sent to the controller are
858 associated with the "controller" virtual meter, if
859 one was configured.
860 If any reason other than action or any nonzero con‐
862 troller-id is supplied, Open vSwitch extension NXAST_CON‐
863 TROLLER, supported by Open vSwitch 1.6 and later, is
864 used. If userdata is supplied, then NXAST_CONTROLLER2,
865 supported by Open vSwitch 2.6 and later, is used.
866 controller
868 controller[:nbytes]
869 Shorthand for controller() or controller(max_len=nbytes),
870 respectively.
871 enqueue(port,queue)
873 Enqueues the packet on the specified queue within port
874 port, which must be an OpenFlow port number or keyword
875 (e.g. LOCAL). The number of supported queues depends on
876 the switch; some OpenFlow implementations do not support
877 queuing at all.
878 drop Discards the packet, so no further processing or forward‐
880 ing takes place. If a drop action is used, no other
881 actions may be specified.
882 mod_vlan_vid:vlan_vid
884 Modifies the VLAN id on a packet. The VLAN tag is added
885 or modified as necessary to match the value specified.
886 If the VLAN tag is added, a priority of zero is used (see
887 the mod_vlan_pcp action to set this).
888 mod_vlan_pcp:vlan_pcp
890 Modifies the VLAN priority on a packet. The VLAN tag is
891 added or modified as necessary to match the value speci‐
892 fied. Valid values are between 0 (lowest) and 7 (high‐
893 est). If the VLAN tag is added, a vid of zero is used
894 (see the mod_vlan_vid action to set this).
895 strip_vlan
897 Strips the VLAN tag from a packet if it is present.
898 push_vlan:ethertype
900 Push a new VLAN tag onto the packet. Ethertype is used
901 as the Ethertype for the tag. Only ethertype 0x8100
902 should be used. (0x88a8 which the spec allows isn't sup‐
903 ported at the moment.) A priority of zero and the tag of
904 zero are used for the new tag.
905 push_mpls:ethertype
907 Changes the packet's Ethertype to ethertype, which must
908 be either 0x8847 or 0x8848, and pushes an MPLS LSE.
909 If the packet does not already contain any MPLS labels
911 then an initial label stack entry is pushed. The label
912 stack entry's label is 2 if the packet contains IPv6 and
913 0 otherwise, its default traffic control value is the low
914 3 bits of the packet's DSCP value (0 if the packet is not
915 IP), and its TTL is copied from the IP TTL (64 if the
916 packet is not IP).
917 If the packet does already contain an MPLS label, pushes
919 a new outermost label as a copy of the existing outermost
920 label.
921 A limitation of the implementation is that processing of
923 actions will stop if push_mpls follows another push_mpls
924 unless there is a pop_mpls in between.
925 pop_mpls:ethertype
927 Strips the outermost MPLS label stack entry. Currently
928 the implementation restricts ethertype to a non-MPLS
929 Ethertype and thus pop_mpls should only be applied to
930 packets with an MPLS label stack depth of one. A further
931 limitation is that processing of actions will stop if
932 pop_mpls follows another pop_mpls unless there is a
933 push_mpls in between.
934 mod_dl_src:mac
936 Sets the source Ethernet address to mac.
937 mod_dl_dst:mac
939 Sets the destination Ethernet address to mac.
940 mod_nw_src:ip
942 Sets the IPv4 source address to ip.
943 mod_nw_dst:ip
945 Sets the IPv4 destination address to ip.
946 mod_tp_src:port
948 Sets the TCP or UDP or SCTP source port to port.
949 mod_tp_dst:port
951 Sets the TCP or UDP or SCTP destination port to port.
952 mod_nw_tos:tos
954 Sets the DSCP bits in the IPv4 ToS/DSCP or IPv6 traffic
955 class field to tos, which must be a multiple of 4 between
956 0 and 255. This action does not modify the two least
957 significant bits of the ToS field (the ECN bits).
958 mod_nw_ecn:ecn
960 Sets the ECN bits in the IPv4 ToS or IPv6 traffic class
961 field to ecn, which must be a value between 0 and 3,
962 inclusive. This action does not modify the six most sig‐
963 nificant bits of the field (the DSCP bits).
964 Requires OpenFlow 1.1 or later.
966 mod_nw_ttl:ttl
968 Sets the IPv4 TTL or IPv6 hop limit field to ttl, which
969 is specified as a decimal number between 0 and 255,
970 inclusive. Switch behavior when setting ttl to zero is
971 not well specified, though.
972 Requires OpenFlow 1.1 or later.
974 The following actions are Nicira vendor extensions that, as of
976 this writing, are only known to be implemented by Open vSwitch:
977 resubmit:port
979 resubmit([port],[table])
980 resubmit([port],[table],ct)
981 Re-searches this OpenFlow flow table (or table table, if
982 specified) with the in_port field replaced by port (if
983 port is specified) and the packet 5-tuple fields swapped
984 with the corresponding conntrack original direction tuple
985 fields (if ct is specified, see ct_nw_src above), and
986 executes the actions found, if any, in addition to any
987 other actions in this flow entry. The in_port and
988 swapped 5-tuple fields are restored immediately after the
989 search, before any actions are executed.
990 The table may be expressed as a number between 0 and 254
992 or (unless --no-names is specified) a name.
993 The ct option requires a valid connection tracking state
995 as a match prerequisite in the flow where this action is
996 placed. Examples of valid connection tracking state
997 matches include ct_state=+new, ct_state=+est,
998 ct_state=+rel, and ct_state=+trk-inv.
999 Recursive resubmit actions are obeyed up to implementa‐
1001 tion-defined limits:
1002 · Open vSwitch 1.0.1 and earlier did not support
1004 recursion.
1005 · Open vSwitch 1.0.2 and 1.0.3 limited recursion to
1007 8 levels.
1008 · Open vSwitch 1.1 and 1.2 limited recursion to 16
1010 levels.
1011 · Open vSwitch 1.2 through 1.8 limited recursion to
1013 32 levels.
1014 · Open vSwitch 1.9 through 2.0 limited recursion to
1016 64 levels.
1017 · Open vSwitch 2.1 through 2.5 limited recursion to
1019 64 levels and impose a total limit of 4,096 resub‐
1020 mits per flow translation (earlier versions did
1021 not impose any total limit).
1022 · Open vSwitch 2.6 and later imposes the same limits
1024 as 2.5, with one exception: resubmit from table x
1025 to any table y > x does not count against the
1026 recursion limit.
1027 Open vSwitch before 1.2.90 did not support table. Open
1029 vSwitch before 2.7 did not support ct.
1030 set_tunnel:id
1032 set_tunnel64:id
1033 If outputting to a port that encapsulates the packet in a
1034 tunnel and supports an identifier (such as GRE), sets the
1035 identifier to id. If the set_tunnel form is used and id
1036 fits in 32 bits, then this uses an action extension that
1037 is supported by Open vSwitch 1.0 and later. Otherwise,
1038 if id is a 64-bit value, it requires Open vSwitch 1.1 or
1039 later.
1040 set_queue:queue
1042 Sets the queue that should be used to queue when packets
1043 are output. The number of supported queues depends on
1044 the switch; some OpenFlow implementations do not support
1045 queuing at all.
1046 pop_queue
1048 Restores the queue to the value it was before any
1049 set_queue actions were applied.
1050 ct
1052 ct([argument][,argument...])
1053 Send the packet through the connection tracker. Refer to
1054 the ct_state documentation above for possible packet and
1055 connection states. A ct action always sets the packet to
1056 an untracked state and clears out the ct_state fields for
1057 the current processing path. Those fields are only
1058 available for the processing path pointed to by the table
1059 argument. The following arguments are supported:
1060 commit
1062 Commit the connection to the connection tracking
1063 module. Information about the connection will be
1064 stored beyond the lifetime of the packet in the
1065 pipeline. Some ct_state flags are only available
1066 for committed connections.
1067 force
1069 A committed connection always has the directional‐
1070 ity of the packet that caused the connection to be
1071 committed in the first place. This is the ``orig‐
1072 inal direction'' of the connection, and the oppo‐
1073 site direction is the ``reply direction''. If a
1074 connection is already committed, but it is in the
1075 wrong direction, force flag may be used in addi‐
1076 tion to commit flag to effectively terminate the
1077 existing connection and start a new one in the
1078 current direction. This flag has no effect if the
1079 original direction of the connection is already
1080 the same as that of the current packet.
1081 table=table
1083 Fork pipeline processing in two. The original
1084 instance of the packet will continue processing
1085 the current actions list as an untracked packet.
1086 An additional instance of the packet will be sent
1087 to the connection tracker, which will be re-
1088 injected into the OpenFlow pipeline to resume pro‐
1089 cessing in table number (which may be specified as
1090 a number between 0 and 254 or, unless --no-names
1091 is specified, a name), with the ct_state and other
1092 ct match fields set. If table is not specified,
1093 then the packet which is submitted to the connec‐
1094 tion tracker is not re-injected into the OpenFlow
1095 pipeline. It is strongly recommended to specify a
1096 table later than the current table to prevent
1097 loops.
1098 zone=value
1100 zone=src[start..end]
1101 A 16-bit context id that can be used to isolate
1102 connections into separate domains, allowing over‐
1103 lapping network addresses in different zones. If a
1104 zone is not provided, then the default is to use
1105 zone zero. The zone may be specified either as an
1106 immediate 16-bit value, or may be provided from an
1107 NXM field src. The start and end pair are inclu‐
1108 sive, and must specify a 16-bit range within the
1109 field. This value is copied to the ct_zone match
1110 field for packets which are re-injected into the
1111 pipeline using the table option.
1112 exec([action][,action...])
1114 Perform actions within the context of connection
1115 tracking. This is a restricted set of actions
1116 which are in the same format as their specifica‐
1117 tions as part of a flow. Only actions which modify
1118 the ct_mark or ct_label fields are accepted within
1119 the exec action, and these fields may only be mod‐
1120 ified with this option. For example:
1121 set_field:value[/mask]->ct_mark
1123 Store a 32-bit metadata value with the con‐
1124 nection. Subsequent lookups for packets in
1125 this connection will populate the ct_mark
1126 flow field when the packet is sent to the
1127 connection tracker with the table speci‐
1128 fied.
1129 set_field:value[/mask]->ct_label
1131 Store a 128-bit metadata value with the
1132 connection. Subsequent lookups for packets
1133 in this connection will populate the
1134 ct_label flow field when the packet is sent
1135 to the connection tracker with the table
1136 specified.
1137 The commit parameter must be specified to use
1139 exec(...).
1140 alg=alg
1142 Specify application layer gateway alg to track
1143 specific connection types. If subsequent related
1144 connections are sent through the ct action, then
1145 the rel flag in the ct_state field will be set.
1146 Supported types include:
1147 ftp Look for negotiation of FTP data connec‐
1149 tions. Specify this option for FTP control
1150 connections to detect related data connec‐
1151 tions and populate the rel flag for the
1152 data connections.
1153 tftp Look for negotiation of TFTP data connec‐
1155 tions. Specify this option for TFTP control
1156 connections to detect related data connec‐
1157 tions and populate the rel flag for the
1158 data connections.
1159 The commit parameter must be specified to use
1161 alg=alg.
1162 When committing related connections, the ct_mark
1164 for that connection is inherited from the current
1165 ct_mark stored with the original connection (ie,
1166 the connection created by ct(alg=...)).
1167 Note that with the Linux datapath, global sysctl
1169 options affect the usage of the ct action. In par‐
1170 ticular, if net.netfilter.nf_conntrack_helper is
1171 enabled then application layer gateway helpers may
1172 be executed even if the alg option is not speci‐
1173 fied. This is the default setting until Linux 4.7.
1174 For security reasons, the netfilter team recom‐
1175 mends users to disable this option. See this blog
1176 post for further details: http://www.netfil‐
1177 ter.org/news.html#2012-04-03
1178 nat[((src|dst)=addr1[-addr2][:port1[-port2]][,flags])]
1180 Specify address and port translation for the con‐
1181 nection being tracked. For new connections either
1182 src or dst argument must be provided to set up
1183 either source address/port translation (SNAT) or
1184 destination address/port translation (DNAT),
1185 respectively. Setting up address translation for
1186 a new connection takes effect only if the commit
1187 flag is also provided for the enclosing ct action.
1188 A bare nat action will only translate the packet
1189 being processed in the way the connection has been
1190 set up with an earlier ct action. Also a nat
1191 action with src or dst, when applied to a packet
1192 belonging to an established (rather than new) con‐
1193 nection, will behave the same as a bare nat.
1194 src and dst options take the following arguments:
1196 addr1[-addr2]
1198 The address range from which the translated
1199 address should be selected. If only one
1200 address is given, then that address will
1201 always be selected, otherwise the address
1202 selection can be informed by the optional
1203 persistent flag as described below. Either
1204 IPv4 or IPv6 addresses can be provided, but
1205 both addresses must be of the same type,
1206 and the datapath behavior is undefined in
1207 case of providing IPv4 address range for an
1208 IPv6 packet, or IPv6 address range for an
1209 IPv4 packet. IPv6 addresses must be brack‐
1210 eted with '[' and ']' if a port range is
1211 also given.
1212 port1[-port2]
1214 The port range from which the translated
1215 port should be selected. If only one port
1216 number is provided, then that should be
1217 selected. In case of a mapping conflict
1218 the datapath may choose any other non-con‐
1219 flicting port number instead, even when no
1220 port range is specified. The port number
1221 selection can be informed by the optional
1222 random and hash flags as described below.
1223 The optional flags are:
1225 random The selection of the port from the given
1227 range should be done using a fresh random
1228 number. This flag is mutually exclusive
1229 with hash.
1230 hash The selection of the port from the given
1232 range should be done using a datapath spe‐
1233 cific hash of the packet's IP addresses and
1234 the other, non-mapped port number. This
1235 flag is mutually exclusive with random.
1236 persistent
1238 The selection of the IP address from the
1239 given range should be done so that the same
1240 mapping can be provided after the system
1241 restarts.
1242 If an alg is specified for the committing ct
1244 action that also includes nat with a src or dst
1245 attribute, then the datapath tries to set up the
1246 helper to be NAT aware. This functionality is
1247 datapath specific and may not be supported by all
1248 datapaths.
1249 nat was introduced in Open vSwitch 2.6. The first
1251 datapath that implements ct nat support is the one
1252 that ships with Linux 4.6.
1253 The ct action may be used as a primitive to construct
1255 stateful firewalls by selectively committing some traf‐
1256 fic, then matching the ct_state to allow established con‐
1257 nections while denying new connections. The following
1258 flows provide an example of how to implement a simple
1259 firewall that allows new connections from port 1 to port
1260 2, and only allows established connections to send traf‐
1261 fic from port 2 to port 1:
1262 table=0,priority=1,action=drop
1263 table=0,priority=10,arp,action=normal
1264 table=0,priority=100,ip,ct_state=-trk,action=ct(ta‐
1265 ble=1)
1266 table=1,in_port=1,ip,ct_state=+trk+new,action=ct(com‐
1267 mit),2
1268 table=1,in_port=1,ip,ct_state=+trk+est,action=2
1269 table=1,in_port=2,ip,ct_state=+trk+new,action=drop
1270 table=1,in_port=2,ip,ct_state=+trk+est,action=1
1271 If ct is executed on IP (or IPv6) fragments, then the
1273 message is implicitly reassembled before sending to the
1274 connection tracker and refragmented upon output, to the
1275 original maximum received fragment size. Reassembly
1276 occurs within the context of the zone, meaning that IP
1277 fragments in different zones are not assembled together.
1278 Pipeline processing for the initial fragments is halted;
1279 When the final fragment is received, the message is
1280 assembled and pipeline processing will continue for that
1281 flow. Because packet ordering is not guaranteed by IP
1282 protocols, it is not possible to determine which IP frag‐
1283 ment will cause message reassembly (and therefore con‐
1284 tinue pipeline processing). As such, it is strongly rec‐
1285 ommended that multiple flows should not execute ct to
1286 reassemble fragments from the same IP message.
1287 The ct action was introduced in Open vSwitch 2.5.
1289 ct_clear
1291 Clears connection tracking state from the flow, zeroing
1292 ct_state, ct_zone, ct_mark, and ct_label.
1293 This action was introduced in Open vSwitch 2.6.90.
1295 dec_ttl
1297 dec_ttl(id1[,id2]...)
1298 Decrement TTL of IPv4 packet or hop limit of IPv6 packet.
1299 If the TTL or hop limit is initially zero or decrementing
1300 would make it so, no decrement occurs, as packets reach‐
1301 ing TTL zero must be rejected. Instead, a ``packet-in''
1302 message with reason code OFPR_INVALID_TTL is sent to each
1303 connected controller that has enabled receiving them, if
1304 any. Processing the current set of actions then stops.
1305 However, if the current set of actions was reached
1306 through ``resubmit'' then remaining actions in outer lev‐
1307 els resume processing.
1308 This action also optionally supports the ability to spec‐
1310 ify a list of valid controller ids. Each of the con‐
1311 trollers in the list will receive the ``packet_in'' mes‐
1312 sage only if they have registered to receive the invalid
1313 ttl packets. If controller ids are not specified, the
1314 ``packet_in'' message will be sent only to the con‐
1315 trollers having controller id zero which have registered
1316 for the invalid ttl packets.
1317 set_mpls_label:label
1319 Set the label of the outer MPLS label stack entry of a
1320 packet. label should be a 20-bit value that is decimal
1321 by default; use a 0x prefix to specify them in hexadeci‐
1322 mal.
1323 set_mpls_tc:tc
1325 Set the traffic-class of the outer MPLS label stack entry
1326 of a packet. tc should be a in the range 0 to 7 inclu‐
1327 sive.
1328 set_mpls_ttl:ttl
1330 Set the TTL of the outer MPLS label stack entry of a
1331 packet. ttl should be in the range 0 to 255 inclusive.
1332 dec_mpls_ttl
1334 Decrement TTL of the outer MPLS label stack entry of a
1335 packet. If the TTL is initially zero or decrementing
1336 would make it so, no decrement occurs. Instead, a
1337 ``packet-in'' message with reason code OFPR_INVALID_TTL
1338 is sent to the main controller (id zero), if it has
1339 enabled receiving them. Processing the current set of
1340 actions then stops. However, if the current set of
1341 actions was reached through ``resubmit'' then remaining
1342 actions in outer levels resume processing.
1343 dec_nsh_ttl
1345 Decrement TTL of the outer NSH header of a packet. If
1346 the TTL is initially zero or decrementing would make it
1347 so, no decrement occurs. Instead, a ``packet-in'' mes‐
1348 sage with reason code OFPR_INVALID_TTL is sent to the
1349 main controller (id zero), if it has enabled receiving
1350 them. Processing the current set of actions then stops.
1351 However, if the current set of actions was reached
1352 through ``resubmit'' then remaining actions in outer lev‐
1353 els resume processing.
1354 note:[hh]...
1356 Does nothing at all. Any number of bytes represented as
1357 hex digits hh may be included. Pairs of hex digits may
1358 be separated by periods for readability. The note
1359 action's format doesn't include an exact length for its
1360 payload, so the provided bytes will be padded on the
1361 right by enough bytes with value 0 to make the total num‐
1362 ber 6 more than a multiple of 8.
1363 move:src[start..end]->dst[start..end]
1365 Copies the named bits from field src to field dst. src
1366 and dst may be NXM field names as defined in
1367 nicira-ext.h, e.g. NXM_OF_UDP_SRC or NXM_NX_REG0, or a
1368 match field name, e.g. reg0. Each start and end pair,
1369 which are inclusive, must specify the same number of bits
1370 and must fit within its respective field. Shorthands for
1371 [start..end] exist: use [bit] to specify a single bit or
1372 [] to specify an entire field (in the latter case the
1373 brackets can also be left off).
1374 Examples: move:NXM_NX_REG0[0..5]->NXM_NX_REG1[26..31]
1376 copies the six bits numbered 0 through 5, inclusive, in
1377 register 0 into bits 26 through 31, inclusive;
1378 move:reg0[0..15]->vlan_tci copies the least significant
1379 16 bits of register 0 into the VLAN TCI field.
1380 In OpenFlow 1.0 through 1.4, move ordinarily uses an Open
1382 vSwitch extension to OpenFlow. In OpenFlow 1.5, move
1383 uses the OpenFlow 1.5 standard copy_field action. The
1384 ONF has also made copy_field available as an extension to
1385 OpenFlow 1.3. Open vSwitch 2.4 and later understands
1386 this extension and uses it if a controller uses it, but
1387 for backward compatibility with older versions of Open
1388 vSwitch, ovs-ofctl does not use it.
1389 set_field:value[/mask]->dst
1391 load:value->dst[start..end]
1392 Loads a literal value into a field or part of a field.
1393 With set_field, value and the optional mask are given in
1394 the customary syntax for field dst, which is expressed as
1395 a field name. For example,
1396 set_field:00:11:22:33:44:55->eth_src sets the Ethernet
1397 source address to 00:11:22:33:44:55. With load, value
1398 must be an integer value (in decimal or prefixed by 0x
1399 for hexadecimal) and dst can also be the NXM or OXM name
1400 for the field. For example,
1401 load:0x001122334455->OXM_OF_ETH_SRC[] has the same effect
1402 as the prior set_field example.
1403 The two forms exist for historical reasons. Open vSwitch
1405 1.1 introduced NXAST_REG_LOAD as a Nicira extension to
1406 OpenFlow 1.0 and used load to express it. Later, Open‐
1407 Flow 1.2 introduced a standard OFPAT_SET_FIELD action
1408 that was restricted to loading entire fields, so Open
1409 vSwitch added the form set_field with this restriction.
1410 OpenFlow 1.5 extended OFPAT_SET_FIELD to the point that
1411 it became a superset of NXAST_REG_LOAD. Open vSwitch
1412 translates either syntax as necessary for the OpenFlow
1413 version in use: in OpenFlow 1.0 and 1.1, NXAST_REG_LOAD;
1414 in OpenFlow 1.2, 1.3, and 1.4, NXAST_REG_LOAD for load or
1415 for loading a subfield, OFPAT_SET_FIELD otherwise; and
1416 OpenFlow 1.5 and later, OFPAT_SET_FIELD.
1417 push:src[start..end]
1419 pop:dst[start..end]
1420 These Open vSwitch extension actions act on bits start to
1421 end, inclusive, in the named field, pushing or popping
1422 the bits on a general-purpose stack of fields or sub‐
1423 fields. Controllers can use this stack for saving and
1424 restoring data or metadata around resubmit actions, for
1425 swapping or rearranging data and metadata, or for other
1426 purposes. Any data or metadata field, or part of one,
1427 may be pushed, and any modifiable field or subfield may
1428 be popped.
1429 The number of bits pushed in a stack entry do not have to
1431 match the number of bits later popped from that entry.
1432 If more bits are popped from an entry than were pushed,
1433 then the entry is conceptually left-padded with 0-bits as
1434 needed. If fewer bits are popped than pushed, then bits
1435 are conceptually trimmed from the left side of the entry.
1436 The stack's size is intended to have a large enough limit
1438 that ``normal'' use will not pose problems. Stack over‐
1439 flow or underflow is an error that causes action execu‐
1440 tion to stop.
1441 Example: push:NXM_NX_REG2[0..5] or push:reg2[0..5] push
1443 the value stored in register 2 bits 0 through 5, inclu‐
1444 sive, on the internal stack, and pop:NXM_NX_REG2[0..5] or
1445 pop:reg2[0..5] pops the value from top of the stack and
1446 sets register 2 bits 0 through 5, inclusive, based on
1447 bits 0 through 5 from the value just popped.
1448 multipath(fields, basis, algorithm, n_links, arg,
1450 dst[start..end])
1451 Hashes fields using basis as a universal hash parameter,
1452 then the applies multipath link selection algorithm (with
1453 parameter arg) to choose one of n_links output links num‐
1454 bered 0 through n_links minus 1, and stores the link into
1455 dst[start..end], which must be an NXM field as described
1456 above.
1457 fields must be one of the following:
1459 eth_src
1461 Hashes Ethernet source address only.
1462 symmetric_l4
1464 Hashes Ethernet source, destination, and type,
1465 VLAN ID, IPv4/IPv6 source, destination, and proto‐
1466 col, and TCP or SCTP (but not UDP) ports. The
1467 hash is computed so that pairs of corresponding
1468 flows in each direction hash to the same value, in
1469 environments where L2 paths are the same in each
1470 direction. UDP ports are not included in the hash
1471 to support protocols such as VXLAN that use asym‐
1472 metric ports in each direction.
1473 symmetric_l3l4
1475 Hashes IPv4/IPv6 source, destination, and proto‐
1476 col, and TCP or SCTP (but not UDP) ports. Like
1477 symmetric_l4, this is a symmetric hash, but by
1478 excluding L2 headers it is more effective in envi‐
1479 ronments with asymmetric L2 paths (e.g. paths
1480 involving VRRP IP addresses on a router). Not an
1481 effective hash function for protocols other than
1482 IPv4 and IPv6, which hash to a constant zero.
1483 symmetric_l3l4+udp
1485 Like symmetric_l3l4+udp, but UDP ports are
1486 included in the hash. This is a more effective
1487 hash when asymmetric UDP protocols such as VXLAN
1488 are not a consideration.
1489 nw_src Hashes Network source address only.
1491 nw_dst Hashes Network destination address only.
1493 algorithm must be one of modulo_n, hash_threshold, hrw,
1495 and iter_hash. Only the iter_hash algorithm uses arg.
1496 Refer to nicira-ext.h for more details.
1498 bundle(fields, basis, algorithm, slave_type, slaves:[s1, s2,
1500 ...])
1501 Hashes fields using basis as a universal hash parameter,
1502 then applies the bundle link selection algorithm to
1503 choose one of the listed slaves represented as
1504 slave_type. Currently the only supported slave_type is
1505 ofport. Thus, each s1 through sN should be an OpenFlow
1506 port number. Outputs to the selected slave.
1507 Currently, fields must be either eth_src, symmetric_l4,
1509 symmetric_l3l4, symmetric_l3l4+udp, nw_src, or nw_dst,
1510 and algorithm must be one of hrw and active_backup.
1511 Example: bundle(eth_src,0,hrw,ofport,slaves:4,8) uses an
1513 Ethernet source hash with basis 0, to select between
1514 OpenFlow ports 4 and 8 using the Highest Random Weight
1515 algorithm.
1516 Refer to nicira-ext.h for more details.
1518 bundle_load(fields, basis, algorithm, slave_type,
1520 dst[start..end], slaves:[s1, s2, ...])
1521 Has the same behavior as the bundle action, with one
1522 exception. Instead of outputting to the selected slave,
1523 it writes its selection to dst[start..end], which must be
1524 an NXM field as described above.
1525 Example: bundle_load(eth_src, 0, hrw, ofport,
1527 NXM_NX_REG0[], slaves:4, 8) uses an Ethernet source hash
1528 with basis 0, to select between OpenFlow ports 4 and 8
1529 using the Highest Random Weight algorithm, and writes the
1530 selection to NXM_NX_REG0[]. Also the match field name
1531 can be used, for example, instead of 'NXM_NX_REG0' the
1532 name 'reg0' can be used. When the while field is indi‐
1533 cated the empty brackets can also be left off.
1534 Refer to nicira-ext.h for more details.
1536 learn(argument[,argument]...)
1538 This action adds or modifies a flow in an OpenFlow table,
1539 similar to ovs-ofctl --strict mod-flows. The arguments
1540 specify the flow's match fields, actions, and other prop‐
1541 erties, as follows. At least one match criterion and one
1542 action argument should ordinarily be specified.
1543 idle_timeout=seconds
1545 hard_timeout=seconds
1546 priority=value
1547 cookie=value
1548 send_flow_rem
1549 These arguments have the same meaning as in the
1550 usual ovs-ofctl flow syntax.
1551 fin_idle_timeout=seconds
1553 fin_hard_timeout=seconds
1554 Adds a fin_timeout action with the specified argu‐
1555 ments to the new flow. This feature was added in
1556 Open vSwitch 1.5.90.
1557 table=table
1559 The table in which the new flow should be
1560 inserted. Specify a decimal number between 0 and
1561 254 or (unless --no-names is specified) a name.
1562 The default, if table is unspecified, is table 1.
1563 delete_learned
1565 This flag enables deletion of the learned flows
1566 when the flow with the learn action is removed.
1567 Specifically, when the last learn action with this
1568 flag and particular table and cookie values is
1569 removed, the switch deletes all of the flows in
1570 the specified table with the specified cookie.
1571 This flag was added in Open vSwitch 2.4.
1573 limit=number
1575 If the number of flows in table table with cookie
1576 id cookie exceeds number, a new flow will not be
1577 learned by this action. By default there's no
1578 limit. limit=0 is a long-hand for no limit.
1579 This flag was added in Open vSwitch 2.8.
1581 result_dst=field[bit]
1583 If learning failed (because the number of flows
1584 exceeds limit), the action sets field[bit] to 0,
1585 otherwise it will be set to 1. field[bit] must be
1586 a single bit.
1587 This flag was added in Open vSwitch 2.8.
1589 field=value
1591 field[start..end]=src[start..end]
1592 field[start..end]
1593 Adds a match criterion to the new flow.
1594 The first form specifies that field must match the
1596 literal value, e.g. dl_type=0x0800. All of the
1597 fields and values for ovs-ofctl flow syntax are
1598 available with their usual meanings. Shorthand
1599 notation matchers (e.g. ip in place of
1600 dl_type=0x0800) are not currently implemented.
1601 The second form specifies that field[start..end]
1603 in the new flow must match src[start..end] taken
1604 from the flow currently being processed. For
1605 example, NXM_OF_UDP_DST[]=NXM_OF_UDP_SRC[] on a
1606 TCP packet for which the UDP src port is 53, cre‐
1607 ates a flow which matches NXM_OF_UDP_DST[]=53.
1608 The third form is a shorthand for the second form.
1610 It specifies that field[start..end] in the new
1611 flow must match the same field[start..end] taken
1612 from the flow currently being processed. For
1613 example, NXM_OF_TCP_DST[] on a TCP packet for
1614 which the TCP dst port is 80, creates a flow which
1615 matches NXM_OF_TCP_DST[]=80.
1616 load:value->dst[start..end]
1618 load:src[start..end]->dst[start..end]
1619 Adds a load action to the new flow.
1620 The first form loads the literal value into bits
1622 start through end, inclusive, in field dst. Its
1623 syntax is the same as the load action described
1624 earlier in this section.
1625 The second form loads src[start..end], a value
1627 from the flow currently being processed, into bits
1628 start through end, inclusive, in field dst.
1629 output:field[start..end]
1631 Add an output action to the new flow's actions,
1632 that outputs to the OpenFlow port taken from
1633 field[start..end], which must be an NXM field as
1634 described above.
1635 clear_actions
1637 Clears all the actions in the action set immediately.
1638 write_actions([action][,action...])
1640 Add the specific actions to the action set. The syntax
1641 of actions is the same as in the actions= field. The
1642 action set is carried between flow tables and then exe‐
1643 cuted at the end of the pipeline.
1644 The actions in the action set are applied in the follow‐
1646 ing order, as required by the OpenFlow specification,
1647 regardless of the order in which they were added to the
1648 action set. Except as specified otherwise below, the
1649 action set only holds at most a single action of each
1650 type. When more than one action of a single type is
1651 written to the action set, the one written later replaces
1652 the earlier action:
1653 1. strip_vlan
1655 pop_mpls
1656 2. decap
1658 3. encap
1660 4. push_mpls
1662 5. push_vlan
1664 6. dec_ttl
1666 dec_mpls_ttl
1667 dec_nsh_ttl
1668 7. load
1670 move
1671 mod_dl_dst
1672 mod_dl_src
1673 mod_nw_dst
1674 mod_nw_src
1675 mod_nw_tos
1676 mod_nw_ecn
1677 mod_nw_ttl
1678 mod_tp_dst
1679 mod_tp_src
1680 mod_vlan_pcp
1681 mod_vlan_vid
1682 set_field
1683 set_tunnel
1684 set_tunnel64
1685 The action set can contain any number of these
1686 actions, with cumulative effect. They will be
1687 applied in the order as added. That is, when mul‐
1688 tiple actions modify the same part of a field, the
1689 later modification takes effect, and when they
1690 modify different parts of a field (or different
1691 fields), then both modifications are applied.
1692 8. set_queue
1694 9. group
1696 output
1697 resubmit
1698 If more than one of these actions is present, then
1699 the one listed earliest above is executed and the
1700 others are ignored, regardless of the order in
1701 which they were added to the action set. (If none
1702 of these actions is present, the action set has no
1703 real effect, because the modified packet is not
1704 sent anywhere and thus the modifications are not
1705 visible.)
1706 Only the actions listed above may be written to the
1708 action set. encap, decap and dec_nsh_ttl actions are
1709 nonstandard.
1710 write_metadata:value[/mask]
1712 Updates the metadata field for the flow. If mask is omit‐
1713 ted, the metadata field is set exactly to value; if mask
1714 is specified, then a 1-bit in mask indicates that the
1715 corresponding bit in the metadata field will be replaced
1716 with the corresponding bit from value. Both value and
1717 mask are 64-bit values that are decimal by default; use a
1718 0x prefix to specify them in hexadecimal.
1719 meter:meter_id
1721 Apply the meter_id before any other actions. If a meter
1722 band rate is exceeded, the packet may be dropped, or mod‐
1723 ified, depending on the meter band type. See the descrip‐
1724 tion of the Meter Table Commands, above, for more
1725 details.
1726 goto_table:table
1728 Jumps to table as the next table in the process pipeline.
1729 The table may be a number between 0 and 254 or (unless
1730 --no-names is specified) a name.
1731 fin_timeout(argument[,argument])
1733 This action changes the idle timeout or hard timeout, or
1734 both, of this OpenFlow rule when the rule matches a TCP
1735 packet with the FIN or RST flag. When such a packet is
1736 observed, the action reduces the rule's timeouts to those
1737 specified on the action. If the rule's existing timeout
1738 is already shorter than the one that the action speci‐
1739 fies, then that timeout is unaffected.
1740 argument takes the following forms:
1742 idle_timeout=seconds
1744 Causes the flow to expire after the given number
1745 of seconds of inactivity.
1746 hard_timeout=seconds
1748 Causes the flow to expire after the given number
1749 of seconds, regardless of activity. (seconds
1750 specifies time since the flow's creation, not
1751 since the receipt of the FIN or RST.)
1752 This action was added in Open vSwitch 1.5.90.
1754 sample(argument[,argument]...)
1756 Samples packets and sends one sample for every sampled
1757 packet.
1758 argument takes the following forms:
1760 probability=packets
1762 The number of sampled packets out of 65535. Must
1763 be greater or equal to 1.
1764 collector_set_id=id
1766 The unsigned 32-bit integer identifier of the set
1767 of sample collectors to send sampled packets to.
1768 Defaults to 0.
1769 obs_domain_id=id
1771 When sending samples to IPFIX collectors, the
1772 unsigned 32-bit integer Observation Domain ID sent
1773 in every IPFIX flow record. Defaults to 0.
1774 obs_point_id=id
1776 When sending samples to IPFIX collectors, the
1777 unsigned 32-bit integer Observation Point ID sent
1778 in every IPFIX flow record. Defaults to 0.
1779 sampling_port=port
1781 Sample packets on port, which should be the
1782 ingress or egress port. This option, which was
1783 added in Open vSwitch 2.5.90, allows the IPFIX
1784 implementation to export egress tunnel informa‐
1785 tion.
1786 ingress
1788 egress Specifies explicitly that the packet is being sam‐
1789 pled on ingress to or egress from the switch.
1790 IPFIX reports sent by Open vSwitch before version
1791 2.5.90 did not include a direction. From 2.5.90
1792 until 2.6.90, IPFIX reports inferred a direction
1793 from sampling_port: if it was the packet's output
1794 port, then the direction was reported as egress,
1795 otherwise as ingress. Open vSwitch 2.6.90 intro‐
1796 duced these options, which allow the inferred
1797 direction to be overridden. This is particularly
1798 useful when the ingress (or egress) port is not a
1799 tunnel.
1800 Refer to ovs-vswitchd.conf.db(5) for more details on con‐
1802 figuring sample collector sets.
1803 This action was added in Open vSwitch 1.10.90.
1805 exit This action causes Open vSwitch to immediately halt exe‐
1807 cution of further actions. Those actions which have
1808 already been executed are unaffected. Any further
1809 actions, including those which may be in other tables, or
1810 different levels of the resubmit call stack, are ignored.
1811 Actions in the action set is still executed (specify
1812 clear_actions before exit to discard them).
1813 conjunction(id, k/n)
1815 This action allows for sophisticated ``conjunctive
1816 match'' flows. Refer to CONJUNCTIVE MATCH FIELDS in
1817 ovs-fields(7) for details.
1818 The conjunction action and conj_id field were introduced
1820 in Open vSwitch 2.4.
1821 clone([action][,action...])
1823 Executes each nested action, saving much of the packet
1824 and pipeline state beforehand and then restoring it
1825 afterward. The state that is saved and restored includes
1826 all flow data and metadata (including, for example,
1827 ct_state), the stack accessed by push and pop actions,
1828 and the OpenFlow action set.
1829 This action was added in Open vSwitch 2.6.90.
1831 encap(header[(prop=value,tlv(class,type,value),...)])
1833 Encapsulates the packet with a new packet header, e.g.,
1834 ethernet or nsh.
1835 header Used to specify encapsulation header type.
1837 prop=value
1839 Used to specify the initial value for the property
1840 in the encapsulation header.
1841 tlv(class,type,value)
1843 Used to specify the initial value for the TLV
1844 (Type Length Value) in the encapsulation header.
1845 For example, encap(ethernet) will encapsulate the L3
1847 packet with Ethernet header.
1848 encap(nsh(md_type=1)) will encapsulate the packet with
1850 nsh header and nsh metadata type 1.
1851 encap(nsh(md_type=2,tlv(0x1000,10,0x12345678))) will
1853 encapsulate the packet with nsh header and nsh metadata
1854 type 2, and the nsh TLV with class 0x1000 and type 10 is
1855 set to 0x12345678.
1856 prop=value is just used to set some necessary fields for
1858 encapsulation header initialization. Other fields in the
1859 encapsulation header must be set by set_field action. New
1860 encapsulation header implementation must add new match
1861 fields and corresponding set action in order that
1862 set_field action can change the fields in the encapsula‐
1863 tion header on demand.
1864 encap(nsh(md_type=1)),
1866 set_field:0x1234->nsh_spi,set_field:0x11223344->nsh_c1 is
1867 an example to encapsulate nsh header and set nsh spi and
1868 c1.
1869 This action was added in Open vSwitch 2.8.
1871 decap([packet_type(ns=namespace,type=type)])
1873 Decapsulates the outer packet header.
1874 packet_type(ns=namespace,type=type)
1876 It is optional and used to specify the outer
1877 header type of the decapsulated packet. namespace
1878 is 0 for Ethernet packet, 1 for L3 packet, type is
1879 L3 protocol type, e.g., 0x894f for nsh, 0x0 for
1880 Ethernet.
1881 By default, decap() will decapsulate the outer packet
1883 header according to the packet header type, if
1884 packet_type(ns=namespace,type=type) is given, it will
1885 decapsulate the given packet header, it will fail if the
1886 actual outer packet header type is not of
1887 packet_type(ns=namespace,type=type).
1888 This action was added in Open vSwitch 2.8.
1890 An opaque identifier called a cookie can be used as a handle to iden‐
1892 tify a set of flows:
1893 cookie=value
1895 A cookie can be associated with a flow using the add-flow,
1896 add-flows, and mod-flows commands. value can be any 64-bit num‐
1897 ber and need not be unique among flows. If this field is omit‐
1898 ted, a default cookie value of 0 is used.
1899 cookie=value/mask
1901 When using NXM, the cookie can be used as a handle for querying,
1902 modifying, and deleting flows. value and mask may be supplied
1903 for the del-flows, mod-flows, dump-flows, and dump-aggregate
1904 commands to limit matching cookies. A 1-bit in mask indicates
1905 that the corresponding bit in cookie must match exactly, and a
1906 0-bit wildcards that bit. A mask of -1 may be used to exactly
1907 match a cookie.
1908 The mod-flows command can update the cookies of flows that match
1910 a cookie by specifying the cookie field twice (once with a mask
1911 for matching and once without to indicate the new value):
1912 ovs-ofctl mod-flows br0 cookie=1,actions=normal
1914 Change all flows' cookies to 1 and change their actions
1915 to normal.
1916 ovs-ofctl mod-flows br0 cookie=1/-1,cookie=2,actions=normal
1918 Update cookies with a value of 1 to 2 and change their
1919 actions to normal.
1920 The ability to match on cookies was added in Open vSwitch 1.5.0.
1922 The following additional field sets the priority for flows added by the
1924 add-flow and add-flows commands. For mod-flows and del-flows when
1925 --strict is specified, priority must match along with the rest of the
1926 flow specification. For mod-flows without --strict, priority is only
1927 significant if the command creates a new flow, that is, non-strict
1928 mod-flows does not match on priority and will not change the priority
1929 of existing flows. Other commands do not allow priority to be speci‐
1930 fied.
1931 priority=value
1933 The priority at which a wildcarded entry will match in compari‐
1934 son to others. value is a number between 0 and 65535, inclu‐
1935 sive. A higher value will match before a lower one. An exact-
1936 match entry will always have priority over an entry containing
1937 wildcards, so it has an implicit priority value of 65535. When
1938 adding a flow, if the field is not specified, the flow's prior‐
1939 ity will default to 32768.
1940 OpenFlow leaves behavior undefined when two or more flows with
1942 the same priority can match a single packet. Some users expect
1943 ``sensible'' behavior, such as more specific flows taking prece‐
1944 dence over less specific flows, but OpenFlow does not specify
1945 this and Open vSwitch does not implement it. Users should
1946 therefore take care to use priorities to ensure the behavior
1947 that they expect.
1948 The add-flow, add-flows, and mod-flows commands support the following
1950 additional options. These options affect only new flows. Thus, for
1951 add-flow and add-flows, these options are always significant, but for
1952 mod-flows they are significant only if the command creates a new flow,
1953 that is, their values do not update or affect existing flows.
1954 idle_timeout=seconds
1956 Causes the flow to expire after the given number of seconds of
1957 inactivity. A value of 0 (the default) prevents a flow from
1958 expiring due to inactivity.
1959 hard_timeout=seconds
1961 Causes the flow to expire after the given number of seconds,
1962 regardless of activity. A value of 0 (the default) gives the
1963 flow no hard expiration deadline.
1964 importance=value
1966 Sets the importance of a flow. The flow entry eviction mecha‐
1967 nism can use importance as a factor in deciding which flow to
1968 evict. A value of 0 (the default) makes the flow non-evictable
1969 on the basis of importance. Specify a value between 0 and
1970 65535.
1971 Only OpenFlow 1.4 and later support importance.
1973 send_flow_rem
1975 Marks the flow with a flag that causes the switch to generate a
1976 ``flow removed'' message and send it to interested controllers
1977 when the flow later expires or is removed.
1978 check_overlap
1980 Forces the switch to check that the flow match does not overlap
1981 that of any different flow with the same priority in the same
1982 table. (This check is expensive so it is best to avoid it.)
1983 reset_counts
1985 When this flag is specified on a flow being added to a switch,
1986 and the switch already has a flow with an identical match, an
1987 OpenFlow 1.2 (or later) switch resets the flow's packet and byte
1988 counters to 0. Without the flag, the packet and byte counters
1989 are preserved.
1990 OpenFlow 1.0 and 1.1 switches always reset counters in this sit‐
1992 uation, as if reset_counts were always specified.
1993 Open vSwitch 1.10 added support for reset_counts.
1995 no_packet_counts
1997 no_byte_counts
1998 Adding these flags to a flow advises an OpenFlow 1.3 (or later)
1999 switch that the controller does not need packet or byte coun‐
2000 ters, respectively, for the flow. Some switch implementations
2001 might achieve higher performance or reduce resource consumption
2002 when these flags are used. These flags provide no benefit to
2003 the Open vSwitch software switch implementation.
2004 OpenFlow 1.2 and earlier do not support these flags.
2006 Open vSwitch 1.10 added support for no_packet_counts and
2008 no_byte_counts.
2009 The dump-flows, dump-aggregate, del-flow and del-flows commands support
2011 these additional optional fields:
2012 out_port=port
2014 If set, a matching flow must include an output action to port,
2015 which must be an OpenFlow port number or name (e.g. local).
2016 out_group=port
2018 If set, a matching flow must include an group action naming
2019 group, which must be an OpenFlow group number. This field is
2020 supported in Open vSwitch 2.5 and later and requires OpenFlow
2021 1.1 or later.
2022 Table Entry Output
2024 The dump-tables and dump-aggregate commands print information about the
2025 entries in a datapath's tables. Each line of output is a flow entry as
2026 described in Flow Syntax, above, plus some additional fields:
2027 duration=secs
2029 The time, in seconds, that the entry has been in the table.
2030 secs includes as much precision as the switch provides, possibly
2031 to nanosecond resolution.
2032 n_packets
2034 The number of packets that have matched the entry.
2035 n_bytes
2037 The total number of bytes from packets that have matched the
2038 entry.
2039 The following additional fields are included only if the switch is Open
2041 vSwitch 1.6 or later and the NXM flow format is used to dump the flow
2042 (see the description of the --flow-format option below). The values of
2043 these additional fields are approximations only and in particular
2044 idle_age will sometimes become nonzero even for busy flows.
2045 hard_age=secs
2047 The integer number of seconds since the flow was added or modi‐
2048 fied. hard_age is displayed only if it differs from the integer
2049 part of duration. (This is separate from duration because
2050 mod-flows restarts the hard_timeout timer without zeroing dura‐
2051 tion.)
2052 idle_age=secs
2054 The integer number of seconds that have passed without any pack‐
2055 ets passing through the flow.
2056 Packet-Out Syntax
2058 ovs-ofctl bundle command accepts packet-outs to be specified in the
2059 bundle file. Each packet-out comprises of a series of field=value
2060 assignments, separated by commas or white space. (Embedding spaces
2061 into a packet-out description normally requires quoting to prevent the
2062 shell from breaking the description into multiple arguments.). Unless
2063 noted otherwise only the last instance of each field is honoured. This
2064 same syntax is also supported by the ovs-ofctl packet-out command.
2065 in_port=port
2067 The port number to be considered the in_port when processing
2068 actions. This can be any valid OpenFlow port number, or any of
2069 the LOCAL, CONTROLLER, or NONE. This field is required.
2070 pipeline_field=value
2073 Optionally, user can specify a list of pipeline fields for a
2074 packet-out message. The supported pipeline fields includes tun‐
2075 nel fields and register fields as defined in ovs-fields(7).
2076 packet=hex-string
2079 The actual packet to send, expressed as a string of hexadecimal
2080 bytes. This field is required.
2081 actions=[action][,action...]
2084 The syntax of actions are identical to the actions= field
2085 described in Flow Syntax above. Specifying actions= is
2086 optional, but omitting actions is interpreted as a drop, so the
2087 packet will not be sent anywhere from the switch. actions must
2088 be specified at the end of each line, like for flow mods.
2089 Group Syntax
2091 Some ovs-ofctl commands accept an argument that describes a group or
2092 groups. Such flow descriptions comprise a series field=value assign‐
2093 ments, separated by commas or white space. (Embedding spaces into a
2094 group description normally requires quoting to prevent the shell from
2095 breaking the description into multiple arguments.). Unless noted other‐
2096 wise only the last instance of each field is honoured.
2097 group_id=id
2099 The integer group id of group. When this field is specified in
2100 del-groups or dump-groups, the keyword "all" may be used to des‐
2101 ignate all groups. This field is required.
2102 type=type
2106 The type of the group. The add-group, add-groups and mod-groups
2107 commands require this field. It is prohibited for other com‐
2108 mands. The following keywords designated the allowed types:
2109 all Execute all buckets in the group.
2111 select Execute one bucket in the group, balancing across the
2113 buckets according to their weights. To select a bucket,
2114 for each live bucket, Open vSwitch hashes flow data with
2115 the bucket ID and multiplies by the bucket weight to
2116 obtain a ``score,'' and then selects the bucket with the
2117 highest score. Use selection_method to control the flow
2118 data used for selection.
2119 indirect
2121 Executes the one bucket in the group.
2122 ff
2124 fast_failover
2125 Executes the first live bucket in the group which is
2126 associated with a live port or group.
2127 command_bucket_id=id
2130 The bucket to operate on. The insert-buckets and remove-buckets
2131 commands require this field. It is prohibited for other com‐
2132 mands. id may be an integer or one of the following keywords:
2133 all Operate on all buckets in the group. Only valid when
2135 used with the remove-buckets command in which case the
2136 effect is to remove all buckets from the group.
2137 first Operate on the first bucket present in the group. In the
2139 case of the insert-buckets command the effect is to
2140 insert new bucets just before the first bucket already
2141 present in the group; or to replace the buckets of the
2142 group if there are no buckets already present in the
2143 group. In the case of the remove-buckets command the
2144 effect is to remove the first bucket of the group; or do
2145 nothing if there are no buckets present in the group.
2146 last Operate on the last bucket present in the group. In the
2148 case of the insert-buckets command the effect is to
2149 insert new bucets just after the last bucket already
2150 present in the group; or to replace the buckets of the
2151 group if there are no buckets already present in the
2152 group. In the case of the remove-buckets command the
2153 effect is to remove the last bucket of the group; or do
2154 nothing if there are no buckets present in the group.
2155 If id is an integer then it should correspond to the bucket_id
2157 of a bucket present in the group. In case of the insert-buckets
2158 command the effect is to insert buckets just before the bucket
2159 in the group whose bucket_id is id. In case of the iremove-
2160 buckets command the effect is to remove the in the group whose
2161 bucket_id is id. It is an error if there is no bucket persent
2162 group in whose bucket_id is id.
2163 selection_method=method
2166 The selection method used to select a bucket for a select group.
2167 This is a string of 1 to 15 bytes in length known to lower lay‐
2168 ers. This field is optional for add-group, add-groups and
2169 mod-group commands on groups of type select. Prohibited other‐
2170 wise. If no selection method is specified, Open vSwitch up to
2171 release 2.9 applies the hash method with default fields. From
2172 2.10 onwards Open vSwitch defaults to the dp_hash method with
2173 symmetric L3/L4 hash algorithm, unless the weighted group buck‐
2174 ets cannot be mapped to a maximum of 64 dp_hash values with suf‐
2175 ficient accuracy. In those rare cases Open vSwitch 2.10 and
2176 later fall back to the hash method with the default set of hash
2177 fields.
2178 dp_hash
2180 Use a datapath computed hash value. The hash algorithm
2181 varies accross different datapath implementations.
2182 dp_hash uses the upper 32 bits of the selec‐
2183 tion_method_param as the datapath hash algorithm selec‐
2184 tor. The supported values are 0 (corresponding to hash
2185 computation over the IP 5-tuple) and 1 (corresponding to
2186 a symmetric hash computation over the IP 5-tuple).
2187 Selecting specific fields with the fields option is not
2188 supported with dp_hash). The lower 32 bits are used as
2189 the hash basis.
2190 Using dp_hash has the advantage that it does not require
2192 the generated datapath flows to exact match any addi‐
2193 tional packet header fields. For example, even if multi‐
2194 ple TCP connections thus hashed to different select group
2195 buckets have different source port numbers, generally all
2196 of them would be handled with a small set of already
2197 established datapath flows, resulting in less latency for
2198 TCP SYN packets. The downside is that the shared data‐
2199 path flows must match each packet twice, as the datapath
2200 hash value calculation happens only when needed, and a
2201 second match is required to match some bits of its value.
2202 This double-matching incurs a small additional latency
2203 cost for each packet, but this latency is orders of mag‐
2204 nitude less than the latency of creating new datapath
2205 flows for new TCP connections.
2206 hash Use a hash computed over the fields specified with the
2208 fields option, see below. If no hash fields are speci‐
2209 fied, hash defaults to a symmetric hash over the combina‐
2210 tion of MAC addresses, VLAN tags, Ether type, IP
2211 addresses and L4 port numbers. hash uses the selec‐
2212 tion_method_param as the hash basis.
2213 Note that the hashed fields become exact matched by the
2215 datapath flows. For example, if the TCP source port is
2216 hashed, the created datapath flows will match the spe‐
2217 cific TCP source port value present in the packet
2218 received. Since each TCP connection generally has a dif‐
2219 ferent source port value, a separate datapath flow will
2220 be need to be inserted for each TCP connection thus
2221 hashed to a select group bucket.
2222 This option uses a Netronome OpenFlow extension which is only
2224 supported when using Open vSwitch 2.4 and later with OpenFlow
2225 1.5 and later.
2226 selection_method_param=param
2229 64-bit integer parameter to the selection method selected by the
2230 selection_method field. The parameter's use is defined by the
2231 lower-layer that implements the selection_method. It is
2232 optional if the selection_method field is specified as a non-
2233 empty string. Prohibited otherwise. The default value is zero.
2234 This option uses a Netronome OpenFlow extension which is only
2236 supported when using Open vSwitch 2.4 and later with OpenFlow
2237 1.5 and later.
2238 fields=field
2241 fields(field[=mask]...)
2242 The field parameters to selection method selected by the selec‐
2243 tion_method field. The syntax is described in Flow Syntax with
2244 the additional restrictions that if a value is provided it is
2245 treated as a wildcard mask and wildcard masks following a slash
2246 are prohibited. The pre-requisites of fields must be provided by
2247 any flows that output to the group. The use of the fields is
2248 defined by the lower-layer that implements the selection_method.
2249 They are optional if the selection_method field is specified as
2250 ``hash', prohibited otherwise. The default is no fields.
2251 This option will use a Netronome OpenFlow extension which is
2253 only supported when using Open vSwitch 2.4 and later with Open‐
2254 Flow 1.5 and later.
2255 bucket=bucket_parameters
2258 The add-group, add-groups and mod-group commands require at
2259 least one bucket field. Bucket fields must appear after all
2260 other fields. Multiple bucket fields to specify multiple buck‐
2261 ets. The order in which buckets are specified corresponds to
2262 their order in the group. If the type of the group is "indirect"
2263 then only one group may be specified. bucket_parameters con‐
2264 sists of a list of field=value assignments, separated by commas
2265 or white space followed by a comma-separated list of actions.
2266 The fields for bucket_parameters are:
2267 bucket_id=id
2269 The 32-bit integer group id of the bucket. Values
2270 greater than 0xffffff00 are reserved. This field was
2271 added in Open vSwitch 2.4 to conform with the OpenFlow
2272 1.5 specification. It is not supported when earlier ver‐
2273 sions of OpenFlow are used. Open vSwitch will automati‐
2274 cally allocate bucket ids when they are not specified.
2275 actions=[action][,action...]
2277 The syntax of actions are identical to the actions= field
2278 described in Flow Syntax above. Specifying actions= is
2279 optional, any unknown bucket parameter will be inter‐
2280 preted as an action.
2281 weight=value
2283 The relative weight of the bucket as an integer. This may
2284 be used by the switch during bucket select for groups
2285 whose type is select.
2286 watch_port=port
2288 Port used to determine liveness of group. This or the
2289 watch_group field is required for groups whose type is ff
2290 or fast_failover.
2291 watch_group=group_id
2293 Group identifier of group used to determine liveness of
2294 group. This or the watch_port field is required for
2295 groups whose type is ff or fast_failover.
2296 Meter Syntax
2298 The meter table commands accept an argument that describes a meter.
2299 Such meter descriptions comprise a series field=value assignments, sep‐
2300 arated by commas or white space. (Embedding spaces into a group
2301 description normally requires quoting to prevent the shell from break‐
2302 ing the description into multiple arguments.). Unless noted otherwise
2303 only the last instance of each field is honoured.
2304 meter=id
2306 The identifier for the meter. An integer is used to specify a
2307 user-defined meter. In addition, the keywords "all", "con‐
2308 troller", and "slowpath", are also supported as virtual meters.
2309 The "controller" and "slowpath" virtual meters apply to packets
2310 sent to the controller and to the OVS userspace, respectively.
2311 When this field is specified in del-meter, dump-meter, or meter-
2313 stats, the keyword "all" may be used to designate all meters.
2314 This field is required, except for meter-stats, which dumps all
2315 stats when this field is not specified.
2316 kbps
2318 pktps The unit for the rate and burst_size band parameters. kbps
2319 specifies kilobits per second, and pktps specifies packets per
2320 second. A unit is required for the add-meter and mod-meter com‐
2321 mands.
2322 burst If set, enables burst support for meter bands through the
2325 burst_size parameter.
2326 stats If set, enables the collection of meter and band statistics.
2329 bands=band_parameters
2332 The add-meter and mod-meter commands require at least one band
2333 specification. Bands must appear after all other fields.
2334 type=type
2336 The type of the meter band. This keyword starts a new
2337 band specification. Each band specifies a rate above
2338 which the band is to take some action. The action depends
2339 on the band type. If multiple bands' rate is exceeded,
2340 then the band with the highest rate among the exceeded
2341 bands is selected. The following keywords designate the
2342 allowed meter band types:
2343 drop Drop packets exceeding the band's rate limit.
2345 The other band_parameters are:
2347 rate=value
2349 The relative rate limit for this band, in kilobits per
2350 second or packets per second, depending on whether kbps
2351 or pktps was specified.
2352 burst_size=size
2354 If burst is specified for the meter entry, configures the
2355 maximum burst allowed for the band in kilobits or pack‐
2356 ets, depending on whether kbps or pktps was specified.
2357 If unspecified, the switch is free to select some reason‐
2358 able value depending on its configuration.
2359
2361 --strict
2362 Uses strict matching when running flow modification commands.
2363 --names
2365 --no-names
2366 Every OpenFlow port has a name and a number, and every OpenFlow
2367 flow table has a number and sometimes a name. By default,
2368 ovs-ofctl commands accept both port and table names and numbers,
2369 and they display port and table names if ovs-ofctl is running on
2370 an interactive console, numbers otherwise. With --names,
2371 ovs-ofctl commands both accept and display port and table names;
2372 with --no-names, commands neither accept nor display port and
2373 table names.
2374 If a port or table name contains special characters or might be
2376 confused with a keyword within a flow, it may be enclosed in
2377 double quotes (escaped from the shell). If necessary, JSON-
2378 style escape sequences may be used inside quotes, as specified
2379 in RFC 7159. When it displays port and table names, ovs-ofctl
2380 quotes any name that does not start with a letter followed by
2381 letters or digits.
2382 Open vSwitch added support for port names and these options.
2384 Open vSwitch 2.10 added support for table names. Earlier ver‐
2385 sions always behaved as if --no-names were specified.
2386 Open vSwitch does not place its own limit on the length of port
2388 names, but OpenFlow 1.0 to 1.5 limit port names to 15 bytes and
2389 OpenFlow 1.6 limits them to 63 bytes. Because ovs-ofctl uses
2390 OpenFlow to retrieve the mapping between port names and numbers,
2391 names longer than this limit will be truncated for both display
2392 and acceptance. Truncation can also cause long names that are
2393 different to appear to be the same; when a switch has two ports
2394 with the same (truncated) name, ovs-ofctl refuses to display or
2395 accept the name, using the number instead.
2396 OpenFlow and Open vSwitch limit table names to 32 bytes.
2398 --stats
2400 --no-stats
2401 The dump-flows command by default, or with --stats, includes
2402 flow duration, packet and byte counts, and idle and hard age in
2403 its output. With --no-stats, it omits all of these, as well as
2404 cookie values and table IDs if they are zero.
2405 --read-only
2407 Do not execute read/write commands.
2408 --bundle
2410 Execute flow mods as an OpenFlow 1.4 atomic bundle transaction.
2411 · Within a bundle, all flow mods are processed in the order
2413 they appear and as a single atomic transaction, meaning
2414 that if one of them fails, the whole transaction fails
2415 and none of the changes are made to the switch's flow ta‐
2416 ble, and that each given datapath packet traversing the
2417 OpenFlow tables sees the flow tables either as before the
2418 transaction, or after all the flow mods in the bundle
2419 have been successfully applied.
2420 · The beginning and the end of the flow table modification
2422 commands in a bundle are delimited with OpenFlow 1.4 bun‐
2423 dle control messages, which makes it possible to stream
2424 the included commands without explicit OpenFlow barriers,
2425 which are otherwise used after each flow table modifica‐
2426 tion command. This may make large modifications execute
2427 faster as a bundle.
2428 · Bundles require OpenFlow 1.4 or higher. An explicit -O
2430 OpenFlow14 option is not needed, but you may need to
2431 enable OpenFlow 1.4 support for OVS by setting the OVSDB
2432 protocols column in the bridge table.
2433 -O [version[,version]...]
2435 --protocols=[version[,version]...]
2436 Sets the OpenFlow protocol versions that are allowed when estab‐
2437 lishing an OpenFlow session.
2438 These protocol versions are enabled by default:
2440 · OpenFlow10, for OpenFlow 1.0.
2442 The following protocol versions are generally supported, but for com‐
2443 patibility with older versions of Open vSwitch they are not enabled by
2444 default:
2445 · OpenFlow11, for OpenFlow 1.1.
2447 · OpenFlow12, for OpenFlow 1.2.
2449 · OpenFlow13, for OpenFlow 1.3.
2451 · OpenFlow14, for OpenFlow 1.4.
2453 Support for the following protocol versions is provided for
2455 testing and development purposes. They are not enabled by
2456 default:
2457 · OpenFlow15, for OpenFlow 1.5.
2459 · OpenFlow16, for OpenFlow 1.6.
2461 -F format[,format...]
2463 --flow-format=format[,format...]
2464 ovs-ofctl supports the following individual flow formats, any
2465 number of which may be listed as format:
2466 OpenFlow10-table_id
2468 This is the standard OpenFlow 1.0 flow format. All Open‐
2469 Flow switches and all versions of Open vSwitch support
2470 this flow format.
2471 OpenFlow10+table_id
2473 This is the standard OpenFlow 1.0 flow format plus a
2474 Nicira extension that allows ovs-ofctl to specify the
2475 flow table in which a particular flow should be placed.
2476 Open vSwitch 1.2 and later supports this flow format.
2477 NXM-table_id (Nicira Extended Match)
2479 This Nicira extension to OpenFlow is flexible and exten‐
2480 sible. It supports all of the Nicira flow extensions,
2481 such as tun_id and registers. Open vSwitch 1.1 and later
2482 supports this flow format.
2483 NXM+table_id (Nicira Extended Match)
2485 This combines Nicira Extended match with the ability to
2486 place a flow in a specific table. Open vSwitch 1.2 and
2487 later supports this flow format.
2488 OXM-OpenFlow12
2490 OXM-OpenFlow13
2491 OXM-OpenFlow14
2492 OXM-OpenFlow15
2493 OXM-OpenFlow16
2494 These are the standard OXM (OpenFlow Extensible Match)
2495 flow format in OpenFlow 1.2 and later.
2496 ovs-ofctl also supports the following abbreviations for collec‐
2498 tions of flow formats:
2499 any Any supported flow format.
2501 OpenFlow10
2503 OpenFlow10-table_id or OpenFlow10+table_id.
2504 NXM NXM-table_id or NXM+table_id.
2506 OXM OXM-OpenFlow12, OXM-OpenFlow13, or OXM-OpenFlow14.
2508 For commands that modify the flow table, ovs-ofctl by default
2510 negotiates the most widely supported flow format that supports
2511 the flows being added. For commands that query the flow table,
2512 ovs-ofctl by default uses the most advanced format supported by
2513 the switch.
2514 This option, where format is a comma-separated list of one or
2516 more of the formats listed above, limits ovs-ofctl's choice of
2517 flow format. If a command cannot work as requested using one of
2518 the specified flow formats, ovs-ofctl will report a fatal error.
2519 -P format
2521 --packet-in-format=format
2522 ovs-ofctl supports the following ``packet-in'' formats, in order
2523 of increasing capability:
2524 standard
2526 This uses the OFPT_PACKET_IN message, the standard
2527 ``packet-in'' message for any given OpenFlow version.
2528 Every OpenFlow switch that supports a given OpenFlow ver‐
2529 sion supports this format.
2530 nxt_packet_in
2532 This uses the NXT_PACKET_IN message, which adds many of
2533 the capabilities of the OpenFlow 1.1 and later ``packet-
2534 in'' messages before those OpenFlow versions were avail‐
2535 able in Open vSwitch. Open vSwitch 1.1 and later support
2536 this format. Only Open vSwitch 2.6 and later, however,
2537 support it for OpenFlow 1.1 and later (but there is lit‐
2538 tle reason to use it with those versions of OpenFlow).
2539 nxt_packet_in2
2541 This uses the NXT_PACKET_IN2 message, which is extensible
2542 and should avoid the need to define new formats later.
2543 In particular, this format supports passing arbitrary
2544 user-provided data to a controller using the userdata
2545 option on the controller action. Open vSwitch 2.6 and
2546 later support this format.
2547 Without this option, ovs-ofctl prefers nxt_packet_in2 if the
2549 switch supports it. Otherwise, if OpenFlow 1.0 is in use,
2550 ovs-ofctl prefers nxt_packet_in if the switch supports it. Oth‐
2551 erwise, ovs-ofctl falls back to the standard packet-in format.
2552 When this option is specified, ovs-ofctl insists on the selected
2553 format. If the switch does not support the requested format,
2554 ovs-ofctl will report a fatal error.
2555 Before version 2.6, Open vSwitch called standard format open‐
2557 flow10 and nxt_packet_in format nxm, and ovs-ofctl still accepts
2558 these names as synonyms. (The name openflow10 was a misnomer
2559 because this format actually varies from one OpenFlow version to
2560 another; it is not consistently OpenFlow 1.0 format. Similarly,
2561 when nxt_packet_in2 was introduced, the name nxm became confus‐
2562 ing because it also uses OXM/NXM.)
2563 This option affects only the monitor command.
2565 --timestamp
2567 Print a timestamp before each received packet. This option only
2568 affects the monitor, snoop, and ofp-parse-pcap commands.
2569 -m
2571 --more Increases the verbosity of OpenFlow messages printed and logged
2572 by ovs-ofctl commands. Specify this option more than once to
2573 increase verbosity further.
2574 --sort[=field]
2576 --rsort[=field]
2577 Display output sorted by flow field in ascending (--sort) or
2578 descending (--rsort) order, where field is any of the fields
2579 that are allowed for matching or priority to sort by priority.
2580 When field is omitted, the output is sorted by priority. Spec‐
2581 ify these options multiple times to sort by multiple fields.
2582 Any given flow will not necessarily specify a value for a given
2584 field. This requires special treatement:
2585 · A flow that does not specify any part of a field that is
2587 used for sorting is sorted after all the flows that do
2588 specify the field. For example, --sort=tcp_src will sort
2589 all the flows that specify a TCP source port in ascending
2590 order, followed by the flows that do not specify a TCP
2591 source port at all.
2592 · A flow that only specifies some bits in a field is sorted
2594 as if the wildcarded bits were zero. For example,
2595 --sort=nw_src would sort a flow that specifies
2596 nw_src=192.168.0.0/24 the same as nw_src=192.168.0.0.
2597 These options currently affect only dump-flows output.
2599 Daemon Options
2601 The following options are valid on POSIX based platforms.
2602 --pidfile[=pidfile]
2604 Causes a file (by default, ovs-ofctl.pid) to be created indicat‐
2605 ing the PID of the running process. If the pidfile argument is
2606 not specified, or if it does not begin with /, then it is cre‐
2607 ated in /var/run/openvswitch.
2608 If --pidfile is not specified, no pidfile is created.
2610 --overwrite-pidfile
2612 By default, when --pidfile is specified and the specified pid‐
2613 file already exists and is locked by a running process,
2614 ovs-ofctl refuses to start. Specify --overwrite-pidfile to
2615 cause it to instead overwrite the pidfile.
2616 When --pidfile is not specified, this option has no effect.
2618 --detach
2620 Runs ovs-ofctl as a background process. The process forks, and
2621 in the child it starts a new session, closes the standard file
2622 descriptors (which has the side effect of disabling logging to
2623 the console), and changes its current directory to the root
2624 (unless --no-chdir is specified). After the child completes its
2625 initialization, the parent exits. ovs-ofctl detaches only when
2626 executing the monitor or snoop commands.
2627 --monitor
2629 Creates an additional process to monitor the ovs-ofctl daemon.
2630 If the daemon dies due to a signal that indicates a programming
2631 error (SIGABRT, SIGALRM, SIGBUS, SIGFPE, SIGILL, SIGPIPE,
2632 SIGSEGV, SIGXCPU, or SIGXFSZ) then the monitor process starts a
2633 new copy of it. If the daemon dies or exits for another reason,
2634 the monitor process exits.
2635 This option is normally used with --detach, but it also func‐
2637 tions without it.
2638 --no-chdir
2640 By default, when --detach is specified, ovs-ofctl changes its
2641 current working directory to the root directory after it
2642 detaches. Otherwise, invoking ovs-ofctl from a carelessly cho‐
2643 sen directory would prevent the administrator from unmounting
2644 the file system that holds that directory.
2645 Specifying --no-chdir suppresses this behavior, preventing
2647 ovs-ofctl from changing its current working directory. This may
2648 be useful for collecting core files, since it is common behavior
2649 to write core dumps into the current working directory and the
2650 root directory is not a good directory to use.
2651 This option has no effect when --detach is not specified.
2653 --no-self-confinement
2655 By default daemon will try to self-confine itself to work with
2656 files under well-know, at build-time whitelisted directories.
2657 It is better to stick with this default behavior and not to use
2658 this flag unless some other Access Control is used to confine
2659 daemon. Note that in contrast to other access control implemen‐
2660 tations that are typically enforced from kernel-space (e.g. DAC
2661 or MAC), self-confinement is imposed from the user-space daemon
2662 itself and hence should not be considered as a full confinement
2663 strategy, but instead should be viewed as an additional layer of
2664 security.
2665 --user Causes ovs-ofctl to run as a different user specified in
2667 "user:group", thus dropping most of the root privileges. Short
2668 forms "user" and ":group" are also allowed, with current user or
2669 group are assumed respectively. Only daemons started by the root
2670 user accepts this argument.
2671 On Linux, daemons will be granted CAP_IPC_LOCK and
2673 CAP_NET_BIND_SERVICES before dropping root privileges. Daemons
2674 that interact with a datapath, such as ovs-vswitchd, will be
2675 granted three additional capabilities, namely CAP_NET_ADMIN,
2676 CAP_NET_BROADCAST and CAP_NET_RAW. The capability change will
2677 apply even if the new user is root.
2678 On Windows, this option is not currently supported. For security
2680 reasons, specifying this option will cause the daemon process
2681 not to start.
2682 --unixctl=socket
2684 Sets the name of the control socket on which ovs-ofctl listens
2685 for runtime management commands (see RUNTIME MANAGEMENT COM‐
2686 MANDS, below). If socket does not begin with /, it is inter‐
2687 preted as relative to /var/run/openvswitch. If --unixctl is not
2688 used at all, the default socket is /var/run/open‐
2689 vswitch/ovs-ofctl.pid.ctl, where pid is ovs-ofctl's process ID.
2690 On Windows a local named pipe is used to listen for runtime man‐
2692 agement commands. A file is created in the absolute path as
2693 pointed by socket or if --unixctl is not used at all, a file is
2694 created as ovs-ofctl.ctl in the configured OVS_RUNDIR directory.
2695 The file exists just to mimic the behavior of a Unix domain
2696 socket.
2697 Specifying none for socket disables the control socket feature.
2699 Public Key Infrastructure Options
2701 -p privkey.pem
2702 --private-key=privkey.pem
2703 Specifies a PEM file containing the private key used as
2704 ovs-ofctl's identity for outgoing SSL connections.
2705 -c cert.pem
2707 --certificate=cert.pem
2708 Specifies a PEM file containing a certificate that certifies the
2709 private key specified on -p or --private-key to be trustworthy.
2710 The certificate must be signed by the certificate authority (CA)
2711 that the peer in SSL connections will use to verify it.
2712 -C cacert.pem
2714 --ca-cert=cacert.pem
2715 Specifies a PEM file containing the CA certificate that
2716 ovs-ofctl should use to verify certificates presented to it by
2717 SSL peers. (This may be the same certificate that SSL peers use
2718 to verify the certificate specified on -c or --certificate, or
2719 it may be a different one, depending on the PKI design in use.)
2720 -C none
2722 --ca-cert=none
2723 Disables verification of certificates presented by SSL peers.
2724 This introduces a security risk, because it means that certifi‐
2725 cates cannot be verified to be those of known trusted hosts.
2726 -v[spec]
2728 --verbose=[spec]
2729 Sets logging levels. Without any spec, sets the log level for
2730 every module and destination to dbg. Otherwise, spec is a list
2731 of words separated by spaces or commas or colons, up to one from
2732 each category below:
2733 · A valid module name, as displayed by the vlog/list com‐
2735 mand on ovs-appctl(8), limits the log level change to the
2736 specified module.
2737 · syslog, console, or file, to limit the log level change
2739 to only to the system log, to the console, or to a file,
2740 respectively. (If --detach is specified, ovs-ofctl
2741 closes its standard file descriptors, so logging to the
2742 console will have no effect.)
2743 On Windows platform, syslog is accepted as a word and is
2745 only useful along with the --syslog-target option (the
2746 word has no effect otherwise).
2747 · off, emer, err, warn, info, or dbg, to control the log
2749 level. Messages of the given severity or higher will be
2750 logged, and messages of lower severity will be filtered
2751 out. off filters out all messages. See ovs-appctl(8)
2752 for a definition of each log level.
2753 Case is not significant within spec.
2755 Regardless of the log levels set for file, logging to a file
2757 will not take place unless --log-file is also specified (see
2758 below).
2759 For compatibility with older versions of OVS, any is accepted as
2761 a word but has no effect.
2762 -v
2764 --verbose
2765 Sets the maximum logging verbosity level, equivalent to --ver‐
2766 bose=dbg.
2767 -vPATTERN:destination:pattern
2769 --verbose=PATTERN:destination:pattern
2770 Sets the log pattern for destination to pattern. Refer to
2771 ovs-appctl(8) for a description of the valid syntax for pattern.
2772 -vFACILITY:facility
2774 --verbose=FACILITY:facility
2775 Sets the RFC5424 facility of the log message. facility can be
2776 one of kern, user, mail, daemon, auth, syslog, lpr, news, uucp,
2777 clock, ftp, ntp, audit, alert, clock2, local0, local1, local2,
2778 local3, local4, local5, local6 or local7. If this option is not
2779 specified, daemon is used as the default for the local system
2780 syslog and local0 is used while sending a message to the target
2781 provided via the --syslog-target option.
2782 --log-file[=file]
2784 Enables logging to a file. If file is specified, then it is
2785 used as the exact name for the log file. The default log file
2786 name used if file is omitted is /var/log/open‐
2787 vswitch/ovs-ofctl.log.
2788 --syslog-target=host:port
2790 Send syslog messages to UDP port on host, in addition to the
2791 system syslog. The host must be a numerical IP address, not a
2792 hostname.
2793 --syslog-method=method
2795 Specify method how syslog messages should be sent to syslog dae‐
2796 mon. Following forms are supported:
2797 · libc, use libc syslog() function. This is the default
2799 behavior. Downside of using this options is that libc
2800 adds fixed prefix to every message before it is actually
2801 sent to the syslog daemon over /dev/log UNIX domain
2802 socket.
2803 · unix:file, use UNIX domain socket directly. It is possi‐
2805 ble to specify arbitrary message format with this option.
2806 However, rsyslogd 8.9 and older versions use hard coded
2807 parser function anyway that limits UNIX domain socket
2808 use. If you want to use arbitrary message format with
2809 older rsyslogd versions, then use UDP socket to localhost
2810 IP address instead.
2811 · udp:ip:port, use UDP socket. With this method it is pos‐
2813 sible to use arbitrary message format also with older
2814 rsyslogd. When sending syslog messages over UDP socket
2815 extra precaution needs to be taken into account, for
2816 example, syslog daemon needs to be configured to listen
2817 on the specified UDP port, accidental iptables rules
2818 could be interfering with local syslog traffic and there
2819 are some security considerations that apply to UDP sock‐
2820 ets, but do not apply to UNIX domain sockets.
2821 --color[=when]
2823 Colorize the output (for some commands); when can be never,
2824 always, or auto (the default).
2825 Only some commands support output coloring. Color names and
2827 default colors may change in future releases.
2828 The environment variable OVS_COLORS can be used to specify user-
2830 defined colors and other attributes used to highlight various
2831 parts of the output. If set, its value is a colon-separated list
2832 of capabilities that defaults to
2833 ac:01;31:dr=34:le=31:pm=36:pr=35:sp=33:vl=32. Supported capabil‐
2834 ities were initially designed for coloring flows from ovs-ofctl
2835 dump-flows switch command, and they are as follows.
2836 ac=01;31
2838 SGR substring for actions= keyword in a flow. The
2839 default is a bold red text foreground.
2840 dr=34 SGR substring for drop keyword. The default is a
2842 dark blue text foreground.
2843 le=31 SGR substring for learn= keyword in a flow. The
2845 default is a red text foreground.
2846 pm=36 SGR substring for flow match attribute names. The
2848 default is a cyan text foreground.
2849 pr=35 SGR substring for keywords in a flow that are fol‐
2851 lowed by arguments inside parenthesis. The
2852 default is a magenta text foreground.
2853 sp=33 SGR substring for some special keywords in a flow,
2855 notably: table=, priority=, load:, output:, move:,
2856 group:, CONTROLLER:, set_field:, resubmit:, exit.
2857 The default is a yellow text foreground.
2858 vl=32 SGR substring for a lone flow match attribute with
2860 no field name. The default is a green text fore‐
2861 ground.
2862 See the Select Graphic Rendition (SGR) section in the documenta‐
2864 tion of the text terminal that is used for permitted values and
2865 their meaning as character attributes.
2866 -h
2868 --help Prints a brief help message to the console.
2869 -V
2871 --version
2872 Prints version information to the console.
2873
2875 ovs-appctl(8) can send commands to a running ovs-ofctl process. The
2876 supported commands are listed below.
2877 exit Causes ovs-ofctl to gracefully terminate. This command applies
2879 only when executing the monitor or snoop commands.
2880 ofctl/set-output-file file
2882 Causes all subsequent output to go to file instead of stderr.
2883 This command applies only when executing the monitor or snoop
2884 commands.
2885 ofctl/send ofmsg...
2887 Sends each ofmsg, specified as a sequence of hex digits that
2888 express an OpenFlow message, on the OpenFlow connection. This
2889 command is useful only when executing the monitor command.
2890 ofctl/packet-out packet-out
2892 Sends an OpenFlow PACKET_OUT message specified in Packet-Out
2893 Syntax, on the OpenFlow connection. See Packet-Out Syntax sec‐
2894 tion for more information. This command is useful only when
2895 executing the monitor command.
2896 ofctl/barrier
2898 Sends an OpenFlow barrier request on the OpenFlow connection and
2899 waits for a reply. This command is useful only for the monitor
2900 command.
2901
2903 The following examples assume that ovs-vswitchd has a bridge named br0
2904 configured.
2905 ovs-ofctl dump-tables br0
2907 Prints out the switch's table stats. (This is more interesting
2908 after some traffic has passed through.)
2909 ovs-ofctl dump-flows br0
2911 Prints the flow entries in the switch.
2912 ovs-ofctl add-flow table=0 actions=learn(table=1,hard_timeout=10,
2914 NXM_OF_VLAN_TCI[0..11],output:NXM_OF_IN_PORT[]), resubmit(,1)
2915 ovs-ofctl add-flow table=1 priority=0 actions=flood Implements
2916 a level 2 MAC learning switch using the learn.
2917 ovs-ofctl add-flow br0 'table=0,priority=0
2919 actions=load:3->NXM_NX_REG0[0..15],learn(table=0,priority=1,idle_time‐
2920 out=10,NXM_OF_ETH_SRC[],NXM_OF_VLAN_TCI[0..11],out‐
2921 put:NXM_NX_REG0[0..15]),output:2
2922 In this use of a learn action, the first packet from each source
2923 MAC will be sent to port 2. Subsequent packets will be output to
2924 port 3, with an idle timeout of 10 seconds. NXM field names and
2925 match field names are both accepted, e.g. NXM_NX_REG0 or reg0
2926 for the first register, and empty brackets may be omitted.
2927 Additional examples may be found documented as part of related
2929 sections.
2930
2932 ovs-fields(7), ovs-appctl(8), ovs-vswitchd(8), ovs-vswitchd.conf.db(8)
2933Open vSwitch 2.10.0 ovs-ofctl(8)