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 ex‐
29 pressed either as a DNS name (if built with unbound li‐
30 brary) 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 op‐
81 tion) only, mod-table configures behavior when no flow is found
82 when a packet is looked up in a flow table. The following set‐
83 ting 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.3 and later (which must be enabled with the -O op‐
98 tion) and Open vSwitch 2.11 and later only, mod-table can change
99 the name of a table:
100 name:new-name
102 Changes the name of the table to new-name. Use an empty
103 new-name to clear the name. (This will be ineffective if
104 the name is set via the name column in the Flow_Table ta‐
105 ble in the Open_vSwitch database as described in
106 ovs-vswitchd.conf.db(5).)
107 In OpenFlow 1.4 and later (which must be enabled with the -O op‐
109 tion) only, mod-table configures the behavior when a controller
110 attempts to add a flow to a flow table that is full. The fol‐
111 lowing setting values are available:
112 evict Delete some existing flow from the flow table, according
114 to the algorithm described for the Flow_Table table in
115 ovs-vswitchd.conf.db(5).
116 noevict
118 Refuse to add the new flow. (Eviction might still be en‐
119 abled through the overflow_policy column in the Flow_Ta‐
120 ble table documented in ovs-vswitchd.conf.db(5).)
121 vacancy:low,high
123 Enables sending vacancy events to controllers using TA‐
124 BLE_STATUS messages, based on percentage thresholds low
125 and high.
126 novacancy
128 Disables vacancy events.
129 dump-ports switch [netdev]
131 Prints to the console statistics for network devices associated
132 with switch. If netdev is specified, only the statistics asso‐
133 ciated with that device will be printed. netdev can be an Open‐
134 Flow assigned port number or device name, e.g. eth0.
135 dump-ports-desc switch [port]
137 Prints to the console detailed information about network devices
138 associated with switch. To dump only a specific port, specify
139 its number as port. Otherwise, if port is omitted, or if it is
140 specified as ANY, then all ports are printed. This is a subset
141 of the information provided by the show command.
142 If the connection to switch negotiates OpenFlow 1.0, 1.2, or
144 1.2, this command uses an OpenFlow extension only implemented in
145 Open vSwitch (version 1.7 and later).
146 Only OpenFlow 1.5 and later support dumping a specific port.
148 Earlier versions of OpenFlow always dump all ports.
149 mod-port switch port action
151 Modify characteristics of port port in switch. port may be an
152 OpenFlow port number or name (unless --no-names is specified) or
153 the keyword LOCAL (the preferred way to refer to the OpenFlow
154 local port). The action may be any one of the following:
155 up
156 down Enable or disable the interface. This is equivalent to
157 ip link set up or ip link set down on a Unix system.
158 stp
160 no-stp Enable or disable 802.1D spanning tree protocol (STP) on
161 the interface. OpenFlow implementations that don't sup‐
162 port STP will refuse to enable it.
163 receive
165 no-receive
166 receive-stp
167 no-receive-stp
168 Enable or disable OpenFlow processing of packets received
169 on this interface. When packet processing is disabled,
170 packets will be dropped instead of being processed
171 through the OpenFlow table. The receive or no-receive
172 setting applies to all packets except 802.1D spanning
173 tree packets, which are separately controlled by re‐
174 ceive-stp or no-receive-stp.
175 forward
177 no-forward
178 Allow or disallow forwarding of traffic to this inter‐
179 face. By default, forwarding is enabled.
180 flood
182 no-flood
183 Controls whether an OpenFlow flood action will send traf‐
184 fic out this interface. By default, flooding is enabled.
185 Disabling flooding is primarily useful to prevent loops
186 when a spanning tree protocol is not in use.
187 packet-in
189 no-packet-in
190 Controls whether packets received on this interface that
191 do not match a flow table entry generate a ``packet in''
192 message to the OpenFlow controller. By default, ``packet
193 in'' messages are enabled.
194 The show command displays (among other information) the configu‐
196 ration that mod-port changes.
197 get-frags switch
199 Prints switch's fragment handling mode. See set-frags, below,
200 for a description of each fragment handling mode.
201 The show command also prints the fragment handling mode among
203 its other output.
204 set-frags switch frag_mode
206 Configures switch's treatment of IPv4 and IPv6 fragments. The
207 choices for frag_mode are:
208 normal Fragments pass through the flow table like non-fragmented
210 packets. The TCP ports, UDP ports, and ICMP type and
211 code fields are always set to 0, even for fragments where
212 that information would otherwise be available (fragments
213 with offset 0). This is the default fragment handling
214 mode for an OpenFlow switch.
215 drop Fragments are dropped without passing through the flow
217 table.
218 reassemble
220 The switch reassembles fragments into full IP packets be‐
221 fore passing them through the flow table. Open vSwitch
222 does not implement this fragment handling mode.
223 nx-match
225 Fragments pass through the flow table like non-fragmented
226 packets. The TCP ports, UDP ports, and ICMP type and
227 code fields are available for matching for fragments with
228 offset 0, and set to 0 in fragments with nonzero offset.
229 This mode is a Nicira extension.
230 See the description of ip_frag, in ovs-fields(7), for a way to
232 match on whether a packet is a fragment and on its fragment off‐
233 set.
234 dump-flows switch [flows]
236 Prints to the console all flow entries in switch's tables that
237 match flows. If flows is omitted, all flows in the switch are
238 retrieved. See Flow Syntax, below, for the syntax of flows.
239 The output format is described in Table Entry Output.
240 By default, ovs-ofctl prints flow entries in the same order that
242 the switch sends them, which is unlikely to be intuitive or con‐
243 sistent. Use --sort and --rsort to control display order. The
244 --names/--no-names and --stats/--no-stats options also affect
245 output formatting. See the descriptions of these options, under
246 OPTIONS below, for more information
247 dump-aggregate switch [flows]
249 Prints to the console aggregate statistics for flows in switch's
250 tables that match flows. If flows is omitted, the statistics
251 are aggregated across all flows in the switch's flow tables.
252 See Flow Syntax, below, for the syntax of flows. The output
253 format is described in Table Entry Output.
254 queue-stats switch [port [queue]]
256 Prints to the console statistics for the specified queue on port
257 within switch. port can be an OpenFlow port number or name, the
258 keyword LOCAL (the preferred way to refer to the OpenFlow local
259 port), or the keyword ALL. Either of port or queue or both may
260 be omitted (or equivalently the keyword ALL). If both are omit‐
261 ted, statistics are printed for all queues on all ports. If
262 only queue is omitted, then statistics are printed for all
263 queues on port; if only port is omitted, then statistics are
264 printed for queue on every port where it exists.
265 queue-get-config switch [port [queue]]
267 Prints to the console the configuration of queue on port in
268 switch. If port is omitted or ANY, reports queues for all port.
269 If queue is omitted or ANY, reports all queues. For OpenFlow
270 1.3 and earlier, the output always includes all queues, ignoring
271 queue if specified.
272 This command has limited usefulness, because ports often have no
274 configured queues and because the OpenFlow protocol provides
275 only very limited information about the configuration of a
276 queue.
277 dump-ipfix-bridge switch
279 Prints to the console the statistics of bridge IPFIX for switch.
280 If bridge IPFIX is configured on the switch, IPFIX statistics
281 can be retrieved. Otherwise, error message will be printed.
282 This command uses an Open vSwitch extension that is only in Open
284 vSwitch 2.6 and later.
285 dump-ipfix-flow switch
287 Prints to the console the statistics of flow-based IPFIX for
288 switch. If flow-based IPFIX is configured on the switch, sta‐
289 tistics of all the collector set ids on the switch will be
290 printed. Otherwise, print error message.
291 Refer to ovs-vswitchd.conf.db(5) for more details on configuring
293 flow based IPFIX and collector set ids.
294 This command uses an Open vSwitch extension that is only in Open
296 vSwitch 2.6 and later.
297 ct-flush-zone switch zone
299 Flushes the connection tracking entries in zone on switch.
300 This command uses an Open vSwitch extension that is only in Open
302 vSwitch 2.6 and later.
303 ct-flush switch [zone=N] [ct-orig-tuple [ct-reply-tuple]]
305 Flushes the connection entries on switch based on zone and con‐
306 nection tracking tuples ct-[orig|reply]-tuple.
307 If ct-[orig|reply]-tuple is not provided, flushes all the con‐
309 nection entries. If zone is specified, only flushes the connec‐
310 tions in zone.
311 If ct-[orig|reply]-tuple is provided, flushes the connection en‐
313 try specified by ct-[orig|reply]-tuple in zone. The zone de‐
314 faults to 0 if it is not provided. The userspace connection
315 tracker requires flushing with the original pre-NATed tuple and
316 a warning log will be otherwise generated. The tuple can be
317 partial and will remove all connections that are matching on the
318 specified fields. In order to specify only ct-reply-tuple, pro‐
319 vide empty string as ct-orig-tuple.
320 Note: Currently there is limitation for matching on ICMP, in or‐
322 der to partially match on ICMP parameters the ct-[orig|re‐
323 ply]-tuple has to include either source or destination IP.
324 An example of an IPv4 ICMP ct-[orig|reply]-tuple:
326 "ct_nw_src=10.1.1.1,ct_nw_dst=10.1.1.2,ct_nw_proto=1,icmp_type=8,icmp_code=0,icmp_id=10"
328 An example of an IPv6 TCP ct-[orig|reply]-tuple:
330 "ct_ipv6_src=fc00::1,ct_ipv6_dst=fc00::2,ct_nw_proto=6,ct_tp_src=1,ct_tp_dst=2"
332 This command uses an Open vSwitch extension that is only in Open
334 vSwitch 3.1 and later.
335 OpenFlow Switch Flow Table Commands
337 These commands manage the flow table in an OpenFlow switch. In each
338 case, flow specifies a flow entry in the format described in Flow Syn‐
339 tax, below, file is a text file that contains zero or more flows in the
340 same syntax, one per line, and the optional --bundle option operates
341 the command as a single atomic transaction, see option --bundle, below.
342 [--bundle] add-flow switch flow
344 [--bundle] add-flow switch - < file
345 [--bundle] add-flows switch file
346 Add each flow entry to switch's tables. Each flow specification
347 (e.g., each line in file) may start with add, modify, delete,
348 modify_strict, or delete_strict keyword to specify whether a
349 flow is to be added, modified, or deleted, and whether the mod‐
350 ify or delete is strict or not. For backwards compatibility a
351 flow specification without one of these keywords is treated as a
352 flow add. All flow mods are executed in the order specified.
353 [--bundle] [--strict] mod-flows switch flow
355 [--bundle] [--strict] mod-flows switch - < file
356 Modify the actions in entries from switch's tables that match
357 the specified flows. With --strict, wildcards are not treated
358 as active for matching purposes.
359 [--bundle] del-flows switch
361 [--bundle] [--strict] del-flows switch [flow]
362 [--bundle] [--strict] del-flows switch - < file
363 Deletes entries from switch's flow table. With only a switch
364 argument, deletes all flows. Otherwise, deletes flow entries
365 that match the specified flows. With --strict, wildcards are
366 not treated as active for matching purposes.
367 [--bundle] [--readd] replace-flows switch file
369 Reads flow entries from file (or stdin if file is -) and queries
370 the flow table from switch. Then it fixes up any differences,
371 adding flows from flow that are missing on switch, deleting
372 flows from switch that are not in file, and updating flows in
373 switch whose actions, cookie, or timeouts differ in file.
374 With --readd, ovs-ofctl adds all the flows from file, even those
376 that exist with the same actions, cookie, and timeout in switch.
377 In OpenFlow 1.0 and 1.1, re-adding a flow always resets the
378 flow's packet and byte counters to 0, and in OpenFlow 1.2 and
379 later, it does so only if the reset_counts flag is set.
380 diff-flows source1 source2
382 Reads flow entries from source1 and source2 and prints the dif‐
383 ferences. A flow that is in source1 but not in source2 is
384 printed preceded by a -, and a flow that is in source2 but not
385 in source1 is printed preceded by a +. If a flow exists in both
386 source1 and source2 with different actions, cookie, or timeouts,
387 then both versions are printed preceded by - and +, respec‐
388 tively.
389 source1 and source2 may each name a file or a switch. If a name
391 begins with / or ., then it is considered to be a file name. A
392 name that contains : is considered to be a switch. Otherwise,
393 it is a file if a file by that name exists, a switch if not.
394 For this command, an exit status of 0 means that no differences
396 were found, 1 means that an error occurred, and 2 means that
397 some differences were found.
398 packet-out switch packet-out
400 Connects to switch and instructs it to execute the packet-out
401 OpenFlow message, specified as defined in Packet-Out Syntax sec‐
402 tion.
403 Group Table Commands
405 These commands manage the group table in an OpenFlow switch. In each
406 case, group specifies a group entry in the format described in Group
407 Syntax, below, and file is a text file that contains zero or more
408 groups in the same syntax, one per line, and the optional --bundle op‐
409 tion operates the command as a single atomic transaction, see option
410 --bundle, below.
411 The group commands work only with switches that support OpenFlow 1.1 or
413 later or the Open vSwitch group extensions to OpenFlow 1.0 (added in
414 Open vSwitch 2.9.90). For OpenFlow 1.1 or later, it is necessary to
415 explicitly enable these protocol versions in ovs-ofctl (using -O). For
416 more information, see ``Q: What versions of OpenFlow does Open vSwitch
417 support?'' in the Open vSwitch FAQ.
418 [--bundle] add-group switch group
420 [--bundle] add-group switch - < file
421 [--bundle] add-groups switch file
422 Add each group entry to switch's tables. Each group specifica‐
423 tion (e.g., each line in file) may start with add, modify,
424 add_or_mod, delete, insert_bucket, or remove_bucket keyword to
425 specify whether a flow is to be added, modified, or deleted, or
426 whether a group bucket is to be added or removed. For backwards
427 compatibility a group specification without one of these key‐
428 words is treated as a group add. All group mods are executed in
429 the order specified.
430 [--bundle] [--may-create] mod-group switch group
432 [--bundle] [--may-create] mod-group switch - < file
433 Modify the action buckets in entries from switch's tables for
434 each group entry. If a specified group does not already exist,
435 then without --may-create, this command has no effect; with
436 --may-create, it creates a new group. The --may-create option
437 uses an Open vSwitch extension to OpenFlow only implemented in
438 Open vSwitch 2.6 and later.
439 [--bundle] del-groups switch
441 [--bundle] del-groups switch [group]
442 [--bundle] del-groups switch - < file
443 Deletes entries from switch's group table. With only a switch
444 argument, deletes all groups. Otherwise, deletes the group for
445 each group entry.
446 [--bundle] insert-buckets switch group
448 [--bundle] insert-buckets switch - < file
449 Add buckets to an existing group present in the switch's group
450 table. If no command_bucket_id is present in the group specifi‐
451 cation then all buckets of the group are removed.
452 [--bundle] remove-buckets switch group
454 [--bundle] remove-buckets switch - < file
455 Remove buckets to an existing group present in the switch's
456 group table. If no command_bucket_id is present in the group
457 specification then all buckets of the group are removed.
458 dump-groups switch [group]
460 Prints group entries in switch's tables to console. To dump
461 only a specific group, specify its number as group. Otherwise,
462 if group is omitted, or if it is specified as ALL, then all
463 groups are printed.
464 Only OpenFlow 1.5 and later support dumping a specific group.
466 Earlier versions of OpenFlow always dump all groups.
467 dump-group-features switch
469 Prints to the console the group features of the switch.
470 dump-group-stats switch [group]
472 Prints to the console statistics for the specified group in
473 switch's tables. If group is omitted then statistics for all
474 groups are printed.
475 OpenFlow 1.3+ Switch Meter Table Commands
477 These commands manage the meter table in an OpenFlow switch. In each
478 case, meter specifies a meter entry in the format described in Meter
479 Syntax, below.
480 OpenFlow 1.3 introduced support for meters, so these commands only work
482 with switches that support OpenFlow 1.3 or later. It is necessary to
483 explicitly enable these protocol versions in ovs-ofctl (using -O) and
484 in the switch itself (with the protocols column in the Bridge table).
485 For more information, see ``Q: What versions of OpenFlow does Open
486 vSwitch support?'' in the Open vSwitch FAQ.
487 add-meter switch meter
489 Add a meter entry to switch's tables. The meter syntax is de‐
490 scribed in section Meter Syntax, below.
491 mod-meter switch meter
493 Modify an existing meter.
494 del-meters switch [meter]
496 Delete entries from switch's meter table. To delete only a spe‐
497 cific meter, specify its number as meter. Otherwise, if meter
498 is omitted, or if it is specified as all, then all meters are
499 deleted.
500 dump-meters switch [meter]
502 Print entries from switch's meter table. To print only a spe‐
503 cific meter, specify its number as meter. Otherwise, if meter
504 is omitted, or if it is specified as all, then all meters are
505 printed.
506 meter-stats switch [meter]
508 Print meter statistics. meter can specify a single meter with
509 syntax meter=id, or all meters with syntax meter=all.
510 meter-features switch
512 Print meter features.
513 OpenFlow Switch Bundle Command
515 Transactional updates to both flow and group tables can be made with
516 the bundle command. file is a text file that contains zero or more
517 flow mods, group mods, or packet-outs in Flow Syntax, Group Syntax, or
518 Packet-Out Syntax, each line preceded by flow, group, or packet-out
519 keyword, correspondingly. The flow keyword may be optionally followed
520 by one of the keywords add, modify, modify_strict, delete, or
521 delete_strict, of which the add is assumed if a bare flow is given.
522 Similarly, the group keyword may be optionally followed by one of the
523 keywords add, modify, add_or_mod, delete, insert_bucket, or re‐
524 move_bucket, of which the add is assumed if a bare group is given.
525 bundle switch file
527 Execute all flow and group mods in file as a single atomic
528 transaction against switch's tables. All bundled mods are exe‐
529 cuted in the order specified.
530 OpenFlow Switch Tunnel TLV Table Commands
532 Open vSwitch maintains a mapping table between tunnel option TLVs (de‐
533 fined by <class, type, length>) and NXM fields tun_metadatan, where n
534 ranges from 0 to 63, that can be operated on for the purposes of
535 matches, actions, etc. This TLV table can be used for Geneve option
536 TLVs or other protocols with options in same TLV format as Geneve op‐
537 tions. This mapping must be explicitly specified by the user through
538 the following commands.
539 A TLV mapping is specified with the syntax
541 {class=class,type=type,len=length}->tun_metadatan. When an option map‐
542 ping exists for a given tun_metadatan, matching on the defined field
543 becomes possible, e.g.:
544 ovs-ofctl add-tlv-map br0
546 "{class=0xffff,type=0,len=4}->tun_metadata0"
547 ovs-ofctl add-flow br0 tun_metadata0=1234,actions=controller
549 A mapping should not be changed while it is in active use by a flow.
551 The result of doing so is undefined.
552 These commands are Nicira extensions to OpenFlow and require Open
554 vSwitch 2.5 or later.
555 add-tlv-map switch option[,option]...
558 Add each option to switch's tables. Duplicate fields are re‐
559 jected.
560 del-tlv-map switch [option[,option]]...
562 Delete each option from switch's table, or all option TLV map‐
563 ping if no option is specified. Fields that aren't mapped are
564 ignored.
565 dump-tlv-map switch
567 Show the currently mapped fields in the switch's option table as
568 well as switch capabilities.
569 OpenFlow Switch Monitoring Commands
571 snoop switch
572 Connects to switch and prints to the console all OpenFlow mes‐
573 sages received. Unlike other ovs-ofctl commands, if switch is
574 the name of a bridge, then the snoop command connects to a Unix
575 domain socket named /var/run/openvswitch/switch.snoop.
576 ovs-vswitchd listens on such a socket for each bridge and sends
577 to it all of the OpenFlow messages sent to or received from its
578 configured OpenFlow controller. Thus, this command can be used
579 to view OpenFlow protocol activity between a switch and its con‐
580 troller.
581 When a switch has more than one controller configured, only the
583 traffic to and from a single controller is output. If none of
584 the controllers is configured as a primary or a secondary (using
585 a Nicira extension to OpenFlow 1.0 or 1.1, or a standard request
586 in OpenFlow 1.2 or later), then a controller is chosen arbitrar‐
587 ily among them. If there is a primary controller, it is chosen;
588 otherwise, if there are any controllers that are not primaries
589 or secondaries, one is chosen arbitrarily; otherwise, a sec‐
590 ondary controller is chosen arbitrarily. This choice is made
591 once at connection time and does not change as controllers re‐
592 configure their roles.
593 If a switch has no controller configured, or if the configured
595 controller is disconnected, no traffic is sent, so monitoring
596 will not show any traffic.
597 monitor switch [miss-len] [invalid_ttl] [watch:[spec...]]
599 Connects to switch and prints to the console all OpenFlow mes‐
600 sages received. Usually, switch should specify the name of a
601 bridge in the ovs-vswitchd database. This is available only in
602 OpenFlow 1.0 as Nicira extension.
603 If miss-len is provided, ovs-ofctl sends an OpenFlow ``set con‐
605 figuration'' message at connection setup time that requests
606 miss-len bytes of each packet that misses the flow table. Open
607 vSwitch does not send these and other asynchronous messages to
608 an ovs-ofctl monitor client connection unless a nonzero value is
609 specified on this argument. (Thus, if miss-len is not speci‐
610 fied, very little traffic will ordinarily be printed.)
611 If invalid_ttl is passed, ovs-ofctl sends an OpenFlow ``set con‐
613 figuration'' message at connection setup time that requests IN‐
614 VALID_TTL_TO_CONTROLLER, so that ovs-ofctl monitor can receive
615 ``packet-in'' messages when TTL reaches zero on dec_ttl action.
616 Only OpenFlow 1.1 and 1.2 support invalid_ttl; Open vSwitch also
617 implements it for OpenFlow 1.0 as an extension.
618 watch:[spec...] causes ovs-ofctl to send a ``monitor request''
620 Nicira extension message to the switch at connection setup time.
621 This message causes the switch to send information about flow
622 table changes as they occur. The following comma-separated spec
623 syntax is available:
624 !initial
626 Do not report the switch's initial flow table contents.
627 !add Do not report newly added flows.
629 !delete
631 Do not report deleted flows.
632 !modify
634 Do not report modifications to existing flows.
635 !own Abbreviate changes made to the flow table by ovs-ofctl's
637 own connection to the switch. (These could only occur
638 using the ofctl/send command described below under RUN‐
639 TIME MANAGEMENT COMMANDS.)
640 !actions
642 Do not report actions as part of flow updates.
643 table=table
645 Limits the monitoring to the table with the given table,
646 which may be expressed as a number between 0 and 254 or
647 (unless --no-names is specified) a name. By default, all
648 tables are monitored.
649 out_port=port
651 If set, only flows that output to port are monitored.
652 The port may be an OpenFlow port number or keyword (e.g.
653 LOCAL).
654 out_group=group
656 If set, only flows that output to group number are moni‐
657 tored. This field requires OpenFlow 1.4 (-OOpenFlow14)
658 or later.
659 field=value
661 Monitors only flows that have field specified as the
662 given value. Any syntax valid for matching on dump-flows
663 may be used.
664 This command may be useful for debugging switch or controller
666 implementations. With watch:, it is particularly useful for ob‐
667 serving how a controller updates flow tables.
668 OpenFlow Switch and Controller Commands
670 The following commands, like those in the previous section, may be ap‐
671 plied to OpenFlow switches, using any of the connection methods de‐
672 scribed in that section. Unlike those commands, these may also be ap‐
673 plied to OpenFlow controllers.
674 probe target
676 Sends a single OpenFlow echo-request message to target and waits
677 for the response. With the -t or --timeout option, this command
678 can test whether an OpenFlow switch or controller is up and run‐
679 ning.
680 ping target [n]
682 Sends a series of 10 echo request packets to target and times
683 each reply. The echo request packets consist of an OpenFlow
684 header plus n bytes (default: 64) of randomly generated payload.
685 This measures the latency of individual requests.
686 benchmark target n count
688 Sends count echo request packets that each consist of an Open‐
689 Flow header plus n bytes of payload and waits for each response.
690 Reports the total time required. This is a measure of the maxi‐
691 mum bandwidth to target for round-trips of n-byte messages.
692 Other Commands
694 ofp-parse file
695 Reads file (or stdin if file is -) as a series of OpenFlow mes‐
696 sages in the binary format used on an OpenFlow connection, and
697 prints them to the console. This can be useful for printing
698 OpenFlow messages captured from a TCP stream.
699 ofp-parse-pcap file [port...]
701 Reads file, which must be in the PCAP format used by network
702 capture tools such as tcpdump or wireshark, extracts all the TCP
703 streams for OpenFlow connections, and prints the OpenFlow mes‐
704 sages in those connections in human-readable format on stdout.
705 OpenFlow connections are distinguished by TCP port number. Non-
707 OpenFlow packets are ignored. By default, data on TCP ports
708 6633 and 6653 are considered to be OpenFlow. Specify one or
709 more port arguments to override the default.
710 This command cannot usefully print SSL encrypted traffic. It
712 does not understand IPv6.
713 Flow Syntax
715 Some ovs-ofctl commands accept an argument that describes a flow or
716 flows. Such flow descriptions comprise a series of field=value assign‐
717 ments, separated by commas or white space. (Embedding spaces into a
718 flow description normally requires quoting to prevent the shell from
719 breaking the description into multiple arguments.)
720 Flow descriptions should be in normal form. This means that a flow may
722 only specify a value for an L3 field if it also specifies a particular
723 L2 protocol, and that a flow may only specify an L4 field if it also
724 specifies particular L2 and L3 protocol types. For example, if the L2
725 protocol type dl_type is wildcarded, then L3 fields nw_src, nw_dst, and
726 nw_proto must also be wildcarded. Similarly, if dl_type or nw_proto
727 (the L3 protocol type) is wildcarded, so must be the L4 fields tcp_dst
728 and tcp_src. ovs-ofctl will warn about flows not in normal form.
729 ovs-fields(7) describes the supported fields and how to match them. In
731 addition to match fields, commands that operate on flows accept a few
732 additional key-value pairs:
733 table=table
735 For flow dump commands, limits the flows dumped to those in ta‐
736 ble, which may be expressed as a number between 0 and 255 or
737 (unless --no-names is specified) a name. If not specified (or
738 if 255 is specified as table), then flows in all tables are
739 dumped.
740 For flow table modification commands, behavior varies based on
742 the OpenFlow version used to connect to the switch:
743 OpenFlow 1.0
745 OpenFlow 1.0 does not support table for modifying flows.
746 ovs-ofctl will exit with an error if table (other than
747 table=255) is specified for a switch that only supports
748 OpenFlow 1.0.
749 In OpenFlow 1.0, the switch chooses the table into which
751 to insert a new flow. The Open vSwitch software switch
752 always chooses table 0. Other Open vSwitch datapaths and
753 other OpenFlow implementations may choose different ta‐
754 bles.
755 The OpenFlow 1.0 behavior in Open vSwitch for modifying
757 or removing flows depends on whether --strict is used.
758 Without --strict, the command applies to matching flows
759 in all tables. With --strict, the command will operate
760 on any single matching flow in any table; it will do
761 nothing if there are matches in more than one table.
762 (The distinction between these behaviors only matters if
763 non-OpenFlow 1.0 commands were also used, because Open‐
764 Flow 1.0 alone cannot add flows with the same matching
765 criteria to multiple tables.)
766 OpenFlow 1.0 with table_id extension
768 Open vSwitch implements an OpenFlow extension that allows
769 the controller to specify the table on which to operate.
770 ovs-ofctl automatically enables the extension when table
771 is specified and OpenFlow 1.0 is used. ovs-ofctl auto‐
772 matically detects whether the switch supports the exten‐
773 sion. As of this writing, this extension is only known
774 to be implemented by Open vSwitch.
775 With this extension, ovs-ofctl operates on the requested
777 table when table is specified, and acts as described for
778 OpenFlow 1.0 above when no table is specified (or for ta‐
779 ble=255).
780 OpenFlow 1.1
782 OpenFlow 1.1 requires flow table modification commands to
783 specify a table. When table is not specified (or ta‐
784 ble=255 is specified), ovs-ofctl defaults to table 0.
785 OpenFlow 1.2 and later
787 OpenFlow 1.2 and later allow flow deletion commands, but
788 not other flow table modification commands, to operate on
789 all flow tables, with the behavior described above for
790 OpenFlow 1.0.
791 duration=...
793 n_packet=...
794 n_bytes=...
795 ovs-ofctl ignores assignments to these ``fields'' to allow out‐
796 put from the dump-flows command to be used as input for other
797 commands that parse flows.
798 The add-flow, add-flows, and mod-flows commands require an additional
800 field, which must be the final field specified:
801 actions=[action][,action...]
803 Specifies a comma-separated list of actions to take on a packet
804 when the flow entry matches. If no action is specified, then
805 packets matching the flow are dropped. See ovs-actions(7) for
806 details on the syntax and semantics of actions. K
807 An opaque identifier called a cookie can be used as a handle to iden‐
809 tify a set of flows:
810 cookie=value
812 A cookie can be associated with a flow using the add-flow,
813 add-flows, and mod-flows commands. value can be any 64-bit num‐
814 ber and need not be unique among flows. If this field is omit‐
815 ted, a default cookie value of 0 is used.
816 cookie=value/mask
818 When using NXM, the cookie can be used as a handle for querying,
819 modifying, and deleting flows. value and mask may be supplied
820 for the del-flows, mod-flows, dump-flows, and dump-aggregate
821 commands to limit matching cookies. A 1-bit in mask indicates
822 that the corresponding bit in cookie must match exactly, and a
823 0-bit wildcards that bit. A mask of -1 may be used to exactly
824 match a cookie.
825 The mod-flows command can update the cookies of flows that match
827 a cookie by specifying the cookie field twice (once with a mask
828 for matching and once without to indicate the new value):
829 ovs-ofctl mod-flows br0 cookie=1,actions=normal
831 Change all flows' cookies to 1 and change their actions
832 to normal.
833 ovs-ofctl mod-flows br0 cookie=1/-1,cookie=2,actions=normal
835 Update cookies with a value of 1 to 2 and change their
836 actions to normal.
837 The ability to match on cookies was added in Open vSwitch 1.5.0.
839 The following additional field sets the priority for flows added by the
841 add-flow and add-flows commands. For mod-flows and del-flows when
842 --strict is specified, priority must match along with the rest of the
843 flow specification. For mod-flows without --strict, priority is only
844 significant if the command creates a new flow, that is, non-strict
845 mod-flows does not match on priority and will not change the priority
846 of existing flows. Other commands do not allow priority to be speci‐
847 fied.
848 priority=value
850 The priority at which a wildcarded entry will match in compari‐
851 son to others. value is a number between 0 and 65535, inclu‐
852 sive. A higher value will match before a lower one. An exact-
853 match entry will always have priority over an entry containing
854 wildcards, so it has an implicit priority value of 65535. When
855 adding a flow, if the field is not specified, the flow's prior‐
856 ity will default to 32768.
857 OpenFlow leaves behavior undefined when two or more flows with
859 the same priority can match a single packet. Some users expect
860 ``sensible'' behavior, such as more specific flows taking prece‐
861 dence over less specific flows, but OpenFlow does not specify
862 this and Open vSwitch does not implement it. Users should
863 therefore take care to use priorities to ensure the behavior
864 that they expect.
865 The add-flow, add-flows, and mod-flows commands support the following
867 additional options. These options affect only new flows. Thus, for
868 add-flow and add-flows, these options are always significant, but for
869 mod-flows they are significant only if the command creates a new flow,
870 that is, their values do not update or affect existing flows.
871 idle_timeout=seconds
873 Causes the flow to expire after the given number of seconds of
874 inactivity. A value of 0 (the default) prevents a flow from ex‐
875 piring due to inactivity.
876 hard_timeout=seconds
878 Causes the flow to expire after the given number of seconds, re‐
879 gardless of activity. A value of 0 (the default) gives the flow
880 no hard expiration deadline.
881 importance=value
883 Sets the importance of a flow. The flow entry eviction mecha‐
884 nism can use importance as a factor in deciding which flow to
885 evict. A value of 0 (the default) makes the flow non-evictable
886 on the basis of importance. Specify a value between 0 and
887 65535.
888 Only OpenFlow 1.4 and later support importance.
890 send_flow_rem
892 Marks the flow with a flag that causes the switch to generate a
893 ``flow removed'' message and send it to interested controllers
894 when the flow later expires or is removed.
895 check_overlap
897 Forces the switch to check that the flow match does not overlap
898 that of any different flow with the same priority in the same
899 table. (This check is expensive so it is best to avoid it.)
900 reset_counts
902 When this flag is specified on a flow being added to a switch,
903 and the switch already has a flow with an identical match, an
904 OpenFlow 1.2 (or later) switch resets the flow's packet and byte
905 counters to 0. Without the flag, the packet and byte counters
906 are preserved.
907 OpenFlow 1.0 and 1.1 switches always reset counters in this sit‐
909 uation, as if reset_counts were always specified.
910 Open vSwitch 1.10 added support for reset_counts.
912 no_packet_counts
914 no_byte_counts
915 Adding these flags to a flow advises an OpenFlow 1.3 (or later)
916 switch that the controller does not need packet or byte coun‐
917 ters, respectively, for the flow. Some switch implementations
918 might achieve higher performance or reduce resource consumption
919 when these flags are used. These flags provide no benefit to
920 the Open vSwitch software switch implementation.
921 OpenFlow 1.2 and earlier do not support these flags.
923 Open vSwitch 1.10 added support for no_packet_counts and
925 no_byte_counts.
926 The dump-flows, dump-aggregate, del-flow and del-flows commands support
928 these additional optional fields:
929 out_port=port
931 If set, a matching flow must include an output action to port,
932 which must be an OpenFlow port number or name (e.g. local).
933 out_group=group
935 If set, a matching flow must include an group action naming
936 group, which must be an OpenFlow group number. This field is
937 supported in Open vSwitch 2.5 and later and requires OpenFlow
938 1.1 or later.
939 Table Entry Output
941 The dump-tables and dump-aggregate commands print information about the
942 entries in a datapath's tables. Each line of output is a flow entry as
943 described in Flow Syntax, above, plus some additional fields:
944 duration=secs
946 The time, in seconds, that the entry has been in the table.
947 secs includes as much precision as the switch provides, possibly
948 to nanosecond resolution.
949 n_packets
951 The number of packets that have matched the entry.
952 n_bytes
954 The total number of bytes from packets that have matched the en‐
955 try.
956 The following additional fields are included only if the switch is Open
958 vSwitch 1.6 or later and the NXM flow format is used to dump the flow
959 (see the description of the --flow-format option below). The values of
960 these additional fields are approximations only and in particular
961 idle_age will sometimes become nonzero even for busy flows.
962 hard_age=secs
964 The integer number of seconds since the flow was added or modi‐
965 fied. hard_age is displayed only if it differs from the integer
966 part of duration. (This is separate from duration because
967 mod-flows restarts the hard_timeout timer without zeroing dura‐
968 tion.)
969 idle_age=secs
971 The integer number of seconds that have passed without any pack‐
972 ets passing through the flow.
973 Packet-Out Syntax
975 ovs-ofctl bundle command accepts packet-outs to be specified in the
976 bundle file. Each packet-out comprises of a series of field=value as‐
977 signments, separated by commas or white space. (Embedding spaces into
978 a packet-out description normally requires quoting to prevent the shell
979 from breaking the description into multiple arguments.). Unless noted
980 otherwise only the last instance of each field is honoured. This same
981 syntax is also supported by the ovs-ofctl packet-out command.
982 in_port=port
984 The port number to be considered the in_port when processing ac‐
985 tions. This can be any valid OpenFlow port number, or any of
986 the LOCAL, CONTROLLER, or NONE. This field is required.
987 pipeline_field=value
990 Optionally, user can specify a list of pipeline fields for a
991 packet-out message. The supported pipeline fields includes tun‐
992 nel fields and register fields as defined in ovs-fields(7).
993 packet=hex-string
996 The actual packet to send, expressed as a string of hexadecimal
997 bytes. This field is required.
998 actions=[action][,action...]
1001 The syntax of actions are identical to the actions= field de‐
1002 scribed in Flow Syntax above. Specifying actions= is optional,
1003 but omitting actions is interpreted as a drop, so the packet
1004 will not be sent anywhere from the switch. actions must be
1005 specified at the end of each line, like for flow mods.
1006 Group Syntax
1008 Some ovs-ofctl commands accept an argument that describes a group or
1009 groups. Such flow descriptions comprise a series field=value assign‐
1010 ments, separated by commas or white space. (Embedding spaces into a
1011 group description normally requires quoting to prevent the shell from
1012 breaking the description into multiple arguments.). Unless noted other‐
1013 wise only the last instance of each field is honoured.
1014 group_id=id
1016 The integer group id of group. When this field is specified in
1017 del-groups or dump-groups, the keyword "all" may be used to des‐
1018 ignate all groups. This field is required.
1019 type=type
1023 The type of the group. The add-group, add-groups and mod-groups
1024 commands require this field. It is prohibited for other com‐
1025 mands. The following keywords designated the allowed types:
1026 all Execute all buckets in the group.
1028 select Execute one bucket in the group, balancing across the
1030 buckets according to their weights. To select a bucket,
1031 for each live bucket, Open vSwitch hashes flow data with
1032 the bucket ID and multiplies by the bucket weight to ob‐
1033 tain a ``score,'' and then selects the bucket with the
1034 highest score. Use selection_method to control the flow
1035 data used for selection.
1036 indirect
1038 Executes the one bucket in the group.
1039 ff
1041 fast_failover
1042 Executes the first live bucket in the group which is as‐
1043 sociated with a live port or group.
1044 command_bucket_id=id
1047 The bucket to operate on. The insert-buckets and remove-buckets
1048 commands require this field. It is prohibited for other com‐
1049 mands. id may be an integer or one of the following keywords:
1050 all Operate on all buckets in the group. Only valid when
1052 used with the remove-buckets command in which case the
1053 effect is to remove all buckets from the group.
1054 first Operate on the first bucket present in the group. In the
1056 case of the insert-buckets command the effect is to in‐
1057 sert new bucets just before the first bucket already
1058 present in the group; or to replace the buckets of the
1059 group if there are no buckets already present in the
1060 group. In the case of the remove-buckets command the ef‐
1061 fect is to remove the first bucket of the group; or do
1062 nothing if there are no buckets present in the group.
1063 last Operate on the last bucket present in the group. In the
1065 case of the insert-buckets command the effect is to in‐
1066 sert new bucets just after the last bucket already
1067 present in the group; or to replace the buckets of the
1068 group if there are no buckets already present in the
1069 group. In the case of the remove-buckets command the ef‐
1070 fect is to remove the last bucket of the group; or do
1071 nothing if there are no buckets present in the group.
1072 If id is an integer then it should correspond to the bucket_id
1074 of a bucket present in the group. In case of the insert-buckets
1075 command the effect is to insert buckets just before the bucket
1076 in the group whose bucket_id is id. In case of the iremove-
1077 buckets command the effect is to remove the in the group whose
1078 bucket_id is id. It is an error if there is no bucket persent
1079 group in whose bucket_id is id.
1080 selection_method=method
1083 The selection method used to select a bucket for a select group.
1084 This is a string of 1 to 15 bytes in length known to lower lay‐
1085 ers. This field is optional for add-group, add-groups and
1086 mod-group commands on groups of type select. Prohibited other‐
1087 wise. If no selection method is specified, Open vSwitch up to
1088 release 2.9 applies the hash method with default fields. From
1089 2.10 onwards Open vSwitch defaults to the dp_hash method with
1090 symmetric L3/L4 hash algorithm, as long as the weighted group
1091 buckets can be mapped to dp_hash values with sufficient accu‐
1092 racy. In 2.10 this was restricted to a maximum of 64 buckets,
1093 and in 2.17 the limit was raised to 256 buckets. In those rare
1094 cases Open vSwitch 2.10 and later fall back to the hash method
1095 with the default set of hash fields.
1096 dp_hash
1098 Use a datapath computed hash value. The hash algorithm
1099 varies across different datapath implementations.
1100 dp_hash uses the upper 32 bits of the selec‐
1101 tion_method_param as the datapath hash algorithm selec‐
1102 tor. The supported values are 0 (corresponding to hash
1103 computation over the IP 5-tuple) and 1 (corresponding to
1104 a symmetric hash computation over the IP 5-tuple). Se‐
1105 lecting specific fields with the fields option is not
1106 supported with dp_hash). The lower 32 bits are used as
1107 the hash basis.
1108 Using dp_hash has the advantage that it does not require
1110 the generated datapath flows to exact match any addi‐
1111 tional packet header fields. For example, even if multi‐
1112 ple TCP connections thus hashed to different select group
1113 buckets have different source port numbers, generally all
1114 of them would be handled with a small set of already es‐
1115 tablished datapath flows, resulting in less latency for
1116 TCP SYN packets. The downside is that the shared data‐
1117 path flows must match each packet twice, as the datapath
1118 hash value calculation happens only when needed, and a
1119 second match is required to match some bits of its value.
1120 This double-matching incurs a small additional latency
1121 cost for each packet, but this latency is orders of mag‐
1122 nitude less than the latency of creating new datapath
1123 flows for new TCP connections.
1124 hash Use a hash computed over the fields specified with the
1126 fields option, see below. If no hash fields are speci‐
1127 fied, hash defaults to a symmetric hash over the combina‐
1128 tion of MAC addresses, VLAN tags, Ether type, IP ad‐
1129 dresses and L4 port numbers. hash uses the selec‐
1130 tion_method_param as the hash basis.
1131 Note that the hashed fields become exact matched by the
1133 datapath flows. For example, if the TCP source port is
1134 hashed, the created datapath flows will match the spe‐
1135 cific TCP source port value present in the packet re‐
1136 ceived. Since each TCP connection generally has a dif‐
1137 ferent source port value, a separate datapath flow will
1138 be need to be inserted for each TCP connection thus
1139 hashed to a select group bucket.
1140 This option uses a Netronome OpenFlow extension which is only
1142 supported when using Open vSwitch 2.4 and later with OpenFlow
1143 1.5 and later.
1144 selection_method_param=param
1147 64-bit integer parameter to the selection method selected by the
1148 selection_method field. The parameter's use is defined by the
1149 lower-layer that implements the selection_method. It is op‐
1150 tional if the selection_method field is specified as a non-empty
1151 string. Prohibited otherwise. The default value is zero.
1152 This option uses a Netronome OpenFlow extension which is only
1154 supported when using Open vSwitch 2.4 and later with OpenFlow
1155 1.5 and later.
1156 fields=field
1159 fields(field[=mask]...)
1160 The field parameters to selection method selected by the selec‐
1161 tion_method field. The syntax is described in Flow Syntax with
1162 the additional restrictions that if a value is provided it is
1163 treated as a wildcard mask and wildcard masks following a slash
1164 are prohibited. The pre-requisites of fields must be provided by
1165 any flows that output to the group. The use of the fields is
1166 defined by the lower-layer that implements the selection_method.
1167 They are optional if the selection_method field is specified as
1168 ``hash', prohibited otherwise. The default is no fields.
1169 This option will use a Netronome OpenFlow extension which is
1171 only supported when using Open vSwitch 2.4 and later with Open‐
1172 Flow 1.5 and later.
1173 bucket=bucket_parameters
1176 The add-group, add-groups and mod-group commands require at
1177 least one bucket field. Bucket fields must appear after all
1178 other fields. Multiple bucket fields to specify multiple buck‐
1179 ets. The order in which buckets are specified corresponds to
1180 their order in the group. If the type of the group is "indirect"
1181 then only one group may be specified. bucket_parameters con‐
1182 sists of a list of field=value assignments, separated by commas
1183 or white space followed by a comma-separated list of actions.
1184 The fields for bucket_parameters are:
1185 bucket_id=id
1187 The 32-bit integer group id of the bucket. Values
1188 greater than 0xffffff00 are reserved. This field was
1189 added in Open vSwitch 2.4 to conform with the OpenFlow
1190 1.5 specification. It is not supported when earlier ver‐
1191 sions of OpenFlow are used. Open vSwitch will automati‐
1192 cally allocate bucket ids when they are not specified.
1193 actions=[action][,action...]
1195 The syntax of actions are identical to the actions= field
1196 described in Flow Syntax above. Specifying actions= is
1197 optional, any unknown bucket parameter will be inter‐
1198 preted as an action.
1199 weight=value
1201 The relative weight of the bucket as an integer. This may
1202 be used by the switch during bucket select for groups
1203 whose type is select.
1204 watch_port=port
1206 Port used to determine liveness of group. This or the
1207 watch_group field is required for groups whose type is ff
1208 or fast_failover. This or the watch_group field can also
1209 be used for groups whose type is select.
1210 watch_group=group_id
1212 Group identifier of group used to determine liveness of
1213 group. This or the watch_port field is required for
1214 groups whose type is ff or fast_failover. This or the
1215 watch_port field can also be used for groups whose type
1216 is select.
1217 Meter Syntax
1219 The meter table commands accept an argument that describes a meter.
1220 Such meter descriptions comprise a series field=value assignments, sep‐
1221 arated by commas or white space. (Embedding spaces into a group de‐
1222 scription normally requires quoting to prevent the shell from breaking
1223 the description into multiple arguments.). Unless noted otherwise only
1224 the last instance of each field is honoured.
1225 meter=id
1227 The identifier for the meter. An integer is used to specify a
1228 user-defined meter. In addition, the keywords "all", "con‐
1229 troller", and "slowpath", are also supported as virtual meters.
1230 The "controller" and "slowpath" virtual meters apply to packets
1231 sent to the controller and to the OVS userspace, respectively.
1232 When this field is specified in del-meter, dump-meter, or meter-
1234 stats, the keyword "all" may be used to designate all meters.
1235 This field is required, except for meter-stats, which dumps all
1236 stats when this field is not specified.
1237 kbps
1239 pktps The unit for the rate and burst_size band parameters. kbps
1240 specifies kilobits per second, and pktps specifies packets per
1241 second. A unit is required for the add-meter and mod-meter com‐
1242 mands.
1243 burst If set, enables burst support for meter bands through the
1246 burst_size parameter.
1247 stats If set, enables the collection of meter and band statistics.
1250 bands=band_parameters
1253 The add-meter and mod-meter commands require at least one band
1254 specification. Bands must appear after all other fields.
1255 type=type
1257 The type of the meter band. This keyword starts a new
1258 band specification. Each band specifies a rate above
1259 which the band is to take some action. The action depends
1260 on the band type. If multiple bands' rate is exceeded,
1261 then the band with the highest rate among the exceeded
1262 bands is selected. The following keywords designate the
1263 allowed meter band types:
1264 drop Drop packets exceeding the band's rate limit.
1266 The other band_parameters are:
1268 rate=value
1270 The relative rate limit for this band, in kilobits per
1271 second or packets per second, depending on whether kbps
1272 or pktps was specified.
1273 burst_size=size
1275 If burst is specified for the meter entry, configures the
1276 maximum burst allowed for the band in kilobits or pack‐
1277 ets, depending on whether kbps or pktps was specified.
1278 If unspecified, the switch is free to select some reason‐
1279 able value depending on its configuration.
1280
1282 --strict
1283 Uses strict matching when running flow modification commands.
1284 --names
1286 --no-names
1287 Every OpenFlow port has a name and a number, and every OpenFlow
1288 flow table has a number and sometimes a name. By default,
1289 ovs-ofctl commands accept both port and table names and numbers,
1290 and they display port and table names if ovs-ofctl is running on
1291 an interactive console, numbers otherwise. With --names,
1292 ovs-ofctl commands both accept and display port and table names;
1293 with --no-names, commands neither accept nor display port and
1294 table names.
1295 If a port or table name contains special characters or might be
1297 confused with a keyword within a flow, it may be enclosed in
1298 double quotes (escaped from the shell). If necessary, JSON-
1299 style escape sequences may be used inside quotes, as specified
1300 in RFC 7159. When it displays port and table names, ovs-ofctl
1301 quotes any name that does not start with a letter followed by
1302 letters or digits.
1303 Open vSwitch added support for port names and these options.
1305 Open vSwitch 2.10 added support for table names. Earlier ver‐
1306 sions always behaved as if --no-names were specified.
1307 Open vSwitch does not place its own limit on the length of port
1309 names, but OpenFlow limits port names to 15 bytes. Because
1310 ovs-ofctl uses OpenFlow to retrieve the mapping between port
1311 names and numbers, names longer than this limit will be trun‐
1312 cated for both display and acceptance. Truncation can also
1313 cause long names that are different to appear to be the same;
1314 when a switch has two ports with the same (truncated) name,
1315 ovs-ofctl refuses to display or accept the name, using the num‐
1316 ber instead.
1317 OpenFlow and Open vSwitch limit table names to 32 bytes.
1319 --stats
1321 --no-stats
1322 The dump-flows command by default, or with --stats, includes
1323 flow duration, packet and byte counts, and idle and hard age in
1324 its output. With --no-stats, it omits all of these, as well as
1325 cookie values and table IDs if they are zero.
1326 --read-only
1328 Do not execute read/write commands.
1329 --bundle
1331 Execute flow mods as an OpenFlow 1.4 atomic bundle transaction.
1332 • Within a bundle, all flow mods are processed in the order
1334 they appear and as a single atomic transaction, meaning
1335 that if one of them fails, the whole transaction fails
1336 and none of the changes are made to the switch's flow ta‐
1337 ble, and that each given datapath packet traversing the
1338 OpenFlow tables sees the flow tables either as before the
1339 transaction, or after all the flow mods in the bundle
1340 have been successfully applied.
1341 • The beginning and the end of the flow table modification
1343 commands in a bundle are delimited with OpenFlow 1.4 bun‐
1344 dle control messages, which makes it possible to stream
1345 the included commands without explicit OpenFlow barriers,
1346 which are otherwise used after each flow table modifica‐
1347 tion command. This may make large modifications execute
1348 faster as a bundle.
1349 • Bundles require OpenFlow 1.4 or higher. An explicit -O
1351 OpenFlow14 option is not needed, but you may need to en‐
1352 able OpenFlow 1.4 support for OVS by setting the OVSDB
1353 protocols column in the bridge table.
1354 -O [version[,version]...]
1356 --protocols=[version[,version]...]
1357 Sets the OpenFlow protocol versions that are allowed when estab‐
1358 lishing an OpenFlow session.
1359 These protocol versions are enabled by default:
1361 • OpenFlow10, for OpenFlow 1.0.
1363 The following protocol versions are generally supported, but for com‐
1364 patibility with older versions of Open vSwitch they are not enabled by
1365 default:
1366 • OpenFlow11, for OpenFlow 1.1.
1368 • OpenFlow12, for OpenFlow 1.2.
1370 • OpenFlow13, for OpenFlow 1.3.
1372 • OpenFlow14, for OpenFlow 1.4.
1374 • OpenFlow15, for OpenFlow 1.5.
1376 -F format[,format...]
1378 --flow-format=format[,format...]
1379 ovs-ofctl supports the following individual flow formats, any
1380 number of which may be listed as format:
1381 OpenFlow10-table_id
1383 This is the standard OpenFlow 1.0 flow format. All Open‐
1384 Flow switches and all versions of Open vSwitch support
1385 this flow format.
1386 OpenFlow10+table_id
1388 This is the standard OpenFlow 1.0 flow format plus a
1389 Nicira extension that allows ovs-ofctl to specify the
1390 flow table in which a particular flow should be placed.
1391 Open vSwitch 1.2 and later supports this flow format.
1392 NXM-table_id (Nicira Extended Match)
1394 This Nicira extension to OpenFlow is flexible and exten‐
1395 sible. It supports all of the Nicira flow extensions,
1396 such as tun_id and registers. Open vSwitch 1.1 and later
1397 supports this flow format.
1398 NXM+table_id (Nicira Extended Match)
1400 This combines Nicira Extended match with the ability to
1401 place a flow in a specific table. Open vSwitch 1.2 and
1402 later supports this flow format.
1403 OXM-OpenFlow12
1405 OXM-OpenFlow13
1406 OXM-OpenFlow14
1407 OXM-OpenFlow15
1408 These are the standard OXM (OpenFlow Extensible Match)
1409 flow format in OpenFlow 1.2 and later.
1410 ovs-ofctl also supports the following abbreviations for collec‐
1412 tions of flow formats:
1413 any Any supported flow format.
1415 OpenFlow10
1417 OpenFlow10-table_id or OpenFlow10+table_id.
1418 NXM NXM-table_id or NXM+table_id.
1420 OXM OXM-OpenFlow12, OXM-OpenFlow13, or OXM-OpenFlow14.
1422 For commands that modify the flow table, ovs-ofctl by default
1424 negotiates the most widely supported flow format that supports
1425 the flows being added. For commands that query the flow table,
1426 ovs-ofctl by default uses the most advanced format supported by
1427 the switch.
1428 This option, where format is a comma-separated list of one or
1430 more of the formats listed above, limits ovs-ofctl's choice of
1431 flow format. If a command cannot work as requested using one of
1432 the specified flow formats, ovs-ofctl will report a fatal error.
1433 -P format
1435 --packet-in-format=format
1436 ovs-ofctl supports the following ``packet-in'' formats, in order
1437 of increasing capability:
1438 standard
1440 This uses the OFPT_PACKET_IN message, the standard
1441 ``packet-in'' message for any given OpenFlow version.
1442 Every OpenFlow switch that supports a given OpenFlow ver‐
1443 sion supports this format.
1444 nxt_packet_in
1446 This uses the NXT_PACKET_IN message, which adds many of
1447 the capabilities of the OpenFlow 1.1 and later ``packet-
1448 in'' messages before those OpenFlow versions were avail‐
1449 able in Open vSwitch. Open vSwitch 1.1 and later support
1450 this format. Only Open vSwitch 2.6 and later, however,
1451 support it for OpenFlow 1.1 and later (but there is lit‐
1452 tle reason to use it with those versions of OpenFlow).
1453 nxt_packet_in2
1455 This uses the NXT_PACKET_IN2 message, which is extensible
1456 and should avoid the need to define new formats later.
1457 In particular, this format supports passing arbitrary
1458 user-provided data to a controller using the userdata op‐
1459 tion on the controller action. Open vSwitch 2.6 and
1460 later support this format.
1461 Without this option, ovs-ofctl prefers nxt_packet_in2 if the
1463 switch supports it. Otherwise, if OpenFlow 1.0 is in use,
1464 ovs-ofctl prefers nxt_packet_in if the switch supports it. Oth‐
1465 erwise, ovs-ofctl falls back to the standard packet-in format.
1466 When this option is specified, ovs-ofctl insists on the selected
1467 format. If the switch does not support the requested format,
1468 ovs-ofctl will report a fatal error.
1469 Before version 2.6, Open vSwitch called standard format open‐
1471 flow10 and nxt_packet_in format nxm, and ovs-ofctl still accepts
1472 these names as synonyms. (The name openflow10 was a misnomer
1473 because this format actually varies from one OpenFlow version to
1474 another; it is not consistently OpenFlow 1.0 format. Similarly,
1475 when nxt_packet_in2 was introduced, the name nxm became confus‐
1476 ing because it also uses OXM/NXM.)
1477 This option affects only the monitor command.
1479 --timestamp
1481 Print a timestamp before each received packet. This option only
1482 affects the monitor, snoop, and ofp-parse-pcap commands.
1483 -m
1485 --more Increases the verbosity of OpenFlow messages printed and logged
1486 by ovs-ofctl commands. Specify this option more than once to
1487 increase verbosity further.
1488 --sort[=field]
1490 --rsort[=field]
1491 Display output sorted by flow field in ascending (--sort) or de‐
1492 scending (--rsort) order, where field is any of the fields that
1493 are allowed for matching or priority to sort by priority. When
1494 field is omitted, the output is sorted by priority. Specify
1495 these options multiple times to sort by multiple fields.
1496 Any given flow will not necessarily specify a value for a given
1498 field. This requires special treatement:
1499 • A flow that does not specify any part of a field that is
1501 used for sorting is sorted after all the flows that do
1502 specify the field. For example, --sort=tcp_src will sort
1503 all the flows that specify a TCP source port in ascending
1504 order, followed by the flows that do not specify a TCP
1505 source port at all.
1506 • A flow that only specifies some bits in a field is sorted
1508 as if the wildcarded bits were zero. For example,
1509 --sort=nw_src would sort a flow that specifies
1510 nw_src=192.168.0.0/24 the same as nw_src=192.168.0.0.
1511 These options currently affect only dump-flows output.
1513 Daemon Options
1515 The following options are valid on POSIX based platforms.
1516 --pidfile[=pidfile]
1518 Causes a file (by default, ovs-ofctl.pid) to be created indicat‐
1519 ing the PID of the running process. If the pidfile argument is
1520 not specified, or if it does not begin with /, then it is cre‐
1521 ated in /var/run/openvswitch.
1522 If --pidfile is not specified, no pidfile is created.
1524 --overwrite-pidfile
1526 By default, when --pidfile is specified and the specified pid‐
1527 file already exists and is locked by a running process,
1528 ovs-ofctl refuses to start. Specify --overwrite-pidfile to
1529 cause it to instead overwrite the pidfile.
1530 When --pidfile is not specified, this option has no effect.
1532 --detach
1534 Runs ovs-ofctl as a background process. The process forks, and
1535 in the child it starts a new session, closes the standard file
1536 descriptors (which has the side effect of disabling logging to
1537 the console), and changes its current directory to the root (un‐
1538 less --no-chdir is specified). After the child completes its
1539 initialization, the parent exits. ovs-ofctl detaches only when
1540 executing the monitor or snoop commands.
1541 --monitor
1543 Creates an additional process to monitor the ovs-ofctl daemon.
1544 If the daemon dies due to a signal that indicates a programming
1545 error (SIGABRT, SIGALRM, SIGBUS, SIGFPE, SIGILL, SIGPIPE,
1546 SIGSEGV, SIGXCPU, or SIGXFSZ) then the monitor process starts a
1547 new copy of it. If the daemon dies or exits for another reason,
1548 the monitor process exits.
1549 This option is normally used with --detach, but it also func‐
1551 tions without it.
1552 --no-chdir
1554 By default, when --detach is specified, ovs-ofctl changes its
1555 current working directory to the root directory after it de‐
1556 taches. Otherwise, invoking ovs-ofctl from a carelessly chosen
1557 directory would prevent the administrator from unmounting the
1558 file system that holds that directory.
1559 Specifying --no-chdir suppresses this behavior, preventing
1561 ovs-ofctl from changing its current working directory. This may
1562 be useful for collecting core files, since it is common behavior
1563 to write core dumps into the current working directory and the
1564 root directory is not a good directory to use.
1565 This option has no effect when --detach is not specified.
1567 --no-self-confinement
1569 By default daemon will try to self-confine itself to work with
1570 files under well-known directories determined during build. It
1571 is better to stick with this default behavior and not to use
1572 this flag unless some other Access Control is used to confine
1573 daemon. Note that in contrast to other access control implemen‐
1574 tations that are typically enforced from kernel-space (e.g. DAC
1575 or MAC), self-confinement is imposed from the user-space daemon
1576 itself and hence should not be considered as a full confinement
1577 strategy, but instead should be viewed as an additional layer of
1578 security.
1579 --user Causes ovs-ofctl to run as a different user specified in
1581 "user:group", thus dropping most of the root privileges. Short
1582 forms "user" and ":group" are also allowed, with current user or
1583 group are assumed respectively. Only daemons started by the root
1584 user accepts this argument.
1585 On Linux, daemons will be granted CAP_IPC_LOCK and
1587 CAP_NET_BIND_SERVICES before dropping root privileges. Daemons
1588 that interact with a datapath, such as ovs-vswitchd, will be
1589 granted three additional capabilities, namely CAP_NET_ADMIN,
1590 CAP_NET_BROADCAST and CAP_NET_RAW. The capability change will
1591 apply even if the new user is root.
1592 On Windows, this option is not currently supported. For security
1594 reasons, specifying this option will cause the daemon process
1595 not to start.
1596 --unixctl=socket
1598 Sets the name of the control socket on which ovs-ofctl listens
1599 for runtime management commands (see RUNTIME MANAGEMENT COM‐
1600 MANDS, below). If socket does not begin with /, it is inter‐
1601 preted as relative to /var/run/openvswitch. If --unixctl is not
1602 used at all, the default socket is /var/run/open‐
1603 vswitch/ovs-ofctl.pid.ctl, where pid is ovs-ofctl's process ID.
1604 On Windows a local named pipe is used to listen for runtime man‐
1606 agement commands. A file is created in the absolute path as
1607 pointed by socket or if --unixctl is not used at all, a file is
1608 created as ovs-ofctl.ctl in the configured OVS_RUNDIR directory.
1609 The file exists just to mimic the behavior of a Unix domain
1610 socket.
1611 Specifying none for socket disables the control socket feature.
1613 Public Key Infrastructure Options
1615 -p privkey.pem
1616 --private-key=privkey.pem
1617 Specifies a PEM file containing the private key used as
1618 ovs-ofctl's identity for outgoing SSL connections.
1619 -c cert.pem
1621 --certificate=cert.pem
1622 Specifies a PEM file containing a certificate that certifies the
1623 private key specified on -p or --private-key to be trustworthy.
1624 The certificate must be signed by the certificate authority (CA)
1625 that the peer in SSL connections will use to verify it.
1626 -C cacert.pem
1628 --ca-cert=cacert.pem
1629 Specifies a PEM file containing the CA certificate that
1630 ovs-ofctl should use to verify certificates presented to it by
1631 SSL peers. (This may be the same certificate that SSL peers use
1632 to verify the certificate specified on -c or --certificate, or
1633 it may be a different one, depending on the PKI design in use.)
1634 -C none
1636 --ca-cert=none
1637 Disables verification of certificates presented by SSL peers.
1638 This introduces a security risk, because it means that certifi‐
1639 cates cannot be verified to be those of known trusted hosts.
1640 -v[spec]
1642 --verbose=[spec]
1643 Sets logging levels. Without any spec, sets the log level for
1644 every module and destination to dbg. Otherwise, spec is a list
1645 of words separated by spaces or commas or colons, up to one from
1646 each category below:
1647 • A valid module name, as displayed by the vlog/list com‐
1649 mand on ovs-appctl(8), limits the log level change to the
1650 specified module.
1651 • syslog, console, or file, to limit the log level change
1653 to only to the system log, to the console, or to a file,
1654 respectively. (If --detach is specified, ovs-ofctl
1655 closes its standard file descriptors, so logging to the
1656 console will have no effect.)
1657 On Windows platform, syslog is accepted as a word and is
1659 only useful along with the --syslog-target option (the
1660 word has no effect otherwise).
1661 • off, emer, err, warn, info, or dbg, to control the log
1663 level. Messages of the given severity or higher will be
1664 logged, and messages of lower severity will be filtered
1665 out. off filters out all messages. See ovs-appctl(8)
1666 for a definition of each log level.
1667 Case is not significant within spec.
1669 Regardless of the log levels set for file, logging to a file
1671 will not take place unless --log-file is also specified (see be‐
1672 low).
1673 For compatibility with older versions of OVS, any is accepted as
1675 a word but has no effect.
1676 -v
1678 --verbose
1679 Sets the maximum logging verbosity level, equivalent to --ver‐
1680 bose=dbg.
1681 -vPATTERN:destination:pattern
1683 --verbose=PATTERN:destination:pattern
1684 Sets the log pattern for destination to pattern. Refer to
1685 ovs-appctl(8) for a description of the valid syntax for pattern.
1686 -vFACILITY:facility
1688 --verbose=FACILITY:facility
1689 Sets the RFC5424 facility of the log message. facility can be
1690 one of kern, user, mail, daemon, auth, syslog, lpr, news, uucp,
1691 clock, ftp, ntp, audit, alert, clock2, local0, local1, local2,
1692 local3, local4, local5, local6 or local7. If this option is not
1693 specified, daemon is used as the default for the local system
1694 syslog and local0 is used while sending a message to the target
1695 provided via the --syslog-target option.
1696 --log-file[=file]
1698 Enables logging to a file. If file is specified, then it is
1699 used as the exact name for the log file. The default log file
1700 name used if file is omitted is /var/log/open‐
1701 vswitch/ovs-ofctl.log.
1702 --syslog-target=host:port
1704 Send syslog messages to UDP port on host, in addition to the
1705 system syslog. The host must be a numerical IP address, not a
1706 hostname.
1707 --syslog-method=method
1709 Specify method how syslog messages should be sent to syslog dae‐
1710 mon. Following forms are supported:
1711 • libc, use libc syslog() function. Downside of using this
1713 options is that libc adds fixed prefix to every message
1714 before it is actually sent to the syslog daemon over
1715 /dev/log UNIX domain socket.
1716 • unix:file, use UNIX domain socket directly. It is possi‐
1718 ble to specify arbitrary message format with this option.
1719 However, rsyslogd 8.9 and older versions use hard coded
1720 parser function anyway that limits UNIX domain socket
1721 use. If you want to use arbitrary message format with
1722 older rsyslogd versions, then use UDP socket to localhost
1723 IP address instead.
1724 • udp:ip:port, use UDP socket. With this method it is pos‐
1726 sible to use arbitrary message format also with older
1727 rsyslogd. When sending syslog messages over UDP socket
1728 extra precaution needs to be taken into account, for ex‐
1729 ample, syslog daemon needs to be configured to listen on
1730 the specified UDP port, accidental iptables rules could
1731 be interfering with local syslog traffic and there are
1732 some security considerations that apply to UDP sockets,
1733 but do not apply to UNIX domain sockets.
1734 • null, discards all messages logged to syslog.
1736 The default is taken from the OVS_SYSLOG_METHOD environment
1738 variable; if it is unset, the default is libc.
1739 --color[=when]
1741 Colorize the output (for some commands); when can be never, al‐
1742 ways, or auto (the default).
1743 Only some commands support output coloring. Color names and de‐
1745 fault colors may change in future releases.
1746 The environment variable OVS_COLORS can be used to specify user-
1748 defined colors and other attributes used to highlight various
1749 parts of the output. If set, its value is a colon-separated list
1750 of capabilities that defaults to
1751 ac:01;31:dr=34:le=31:pm=36:pr=35:sp=33:vl=32. Supported capabil‐
1752 ities were initially designed for coloring flows from ovs-ofctl
1753 dump-flows switch command, and they are as follows.
1754 ac=01;31
1756 SGR substring for actions= keyword in a flow. The
1757 default is a bold red text foreground.
1758 dr=34 SGR substring for drop keyword. The default is a
1760 dark blue text foreground.
1761 le=31 SGR substring for learn= keyword in a flow. The
1763 default is a red text foreground.
1764 pm=36 SGR substring for flow match attribute names. The
1766 default is a cyan text foreground.
1767 pr=35 SGR substring for keywords in a flow that are fol‐
1769 lowed by arguments inside parenthesis. The de‐
1770 fault is a magenta text foreground.
1771 sp=33 SGR substring for some special keywords in a flow,
1773 notably: table=, priority=, load:, output:, move:,
1774 group:, CONTROLLER:, set_field:, resubmit:, exit.
1775 The default is a yellow text foreground.
1776 vl=32 SGR substring for a lone flow match attribute with
1778 no field name. The default is a green text fore‐
1779 ground.
1780 See the Select Graphic Rendition (SGR) section in the documenta‐
1782 tion of the text terminal that is used for permitted values and
1783 their meaning as character attributes.
1784 -h
1786 --help Prints a brief help message to the console.
1787 -V
1789 --version
1790 Prints version information to the console.
1791
1793 ovs-appctl(8) can send commands to a running ovs-ofctl process. The
1794 supported commands are listed below.
1795 exit Causes ovs-ofctl to gracefully terminate. This command applies
1797 only when executing the monitor or snoop commands.
1798 ofctl/set-output-file file
1800 Causes all subsequent output to go to file instead of stderr.
1801 This command applies only when executing the monitor or snoop
1802 commands.
1803 ofctl/send ofmsg...
1805 Sends each ofmsg, specified as a sequence of hex digits that ex‐
1806 press an OpenFlow message, on the OpenFlow connection. This
1807 command is useful only when executing the monitor command.
1808 ofctl/packet-out packet-out
1810 Sends an OpenFlow PACKET_OUT message specified in Packet-Out
1811 Syntax, on the OpenFlow connection. See Packet-Out Syntax sec‐
1812 tion for more information. This command is useful only when ex‐
1813 ecuting the monitor command.
1814 ofctl/barrier
1816 Sends an OpenFlow barrier request on the OpenFlow connection and
1817 waits for a reply. This command is useful only for the monitor
1818 command.
1819
1821 The following examples assume that ovs-vswitchd has a bridge named br0
1822 configured.
1823 ovs-ofctl dump-tables br0
1825 Prints out the switch's table stats. (This is more interesting
1826 after some traffic has passed through.)
1827 ovs-ofctl dump-flows br0
1829 Prints the flow entries in the switch.
1830 ovs-ofctl add-flow table=0 actions=learn(table=1,hard_timeout=10,
1832 NXM_OF_VLAN_TCI[0..11],output:NXM_OF_IN_PORT[]), resubmit(,1)
1833 ovs-ofctl add-flow table=1 priority=0 actions=flood Implements
1834 a level 2 MAC learning switch using the learn.
1835 ovs-ofctl add-flow br0 'table=0,priority=0 ac‐
1837 tions=load:3->NXM_NX_REG0[0..15],learn(table=0,priority=1,idle_time‐
1838 out=10,NXM_OF_ETH_SRC[],NXM_OF_VLAN_TCI[0..11],out‐
1839 put:NXM_NX_REG0[0..15]),output:2
1840 In this use of a learn action, the first packet from each source
1841 MAC will be sent to port 2. Subsequent packets will be output to
1842 port 3, with an idle timeout of 10 seconds. NXM field names and
1843 match field names are both accepted, e.g. NXM_NX_REG0 or reg0
1844 for the first register, and empty brackets may be omitted.
1845 Additional examples may be found documented as part of related
1847 sections.
1848
1850 ovs-fields(7), ovs-actions(7), ovs-appctl(8), ovs-vswitchd(8),
1851 ovs-vswitchd.conf.db(8)
1852Open vSwitch 3.1.1 ovs-ofctl(8)