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 OpenFlow Switch Flow Table Commands
305 These commands manage the flow table in an OpenFlow switch. In each
306 case, flow specifies a flow entry in the format described in Flow Syn‐
307 tax, below, file is a text file that contains zero or more flows in the
308 same syntax, one per line, and the optional --bundle option operates
309 the command as a single atomic transation, see option --bundle, below.
310 [--bundle] add-flow switch flow
312 [--bundle] add-flow switch - < file
313 [--bundle] add-flows switch file
314 Add each flow entry to switch's tables. Each flow specification
315 (e.g., each line in file) may start with add, modify, delete,
316 modify_strict, or delete_strict keyword to specify whether a
317 flow is to be added, modified, or deleted, and whether the mod‐
318 ify or delete is strict or not. For backwards compatibility a
319 flow specification without one of these keywords is treated as a
320 flow add. All flow mods are executed in the order specified.
321 [--bundle] [--strict] mod-flows switch flow
323 [--bundle] [--strict] mod-flows switch - < file
324 Modify the actions in entries from switch's tables that match
325 the specified flows. With --strict, wildcards are not treated
326 as active for matching purposes.
327 [--bundle] del-flows switch
329 [--bundle] [--strict] del-flows switch [flow]
330 [--bundle] [--strict] del-flows switch - < file
331 Deletes entries from switch's flow table. With only a switch
332 argument, deletes all flows. Otherwise, deletes flow entries
333 that match the specified flows. With --strict, wildcards are
334 not treated as active for matching purposes.
335 [--bundle] [--readd] replace-flows switch file
337 Reads flow entries from file (or stdin if file is -) and queries
338 the flow table from switch. Then it fixes up any differences,
339 adding flows from flow that are missing on switch, deleting
340 flows from switch that are not in file, and updating flows in
341 switch whose actions, cookie, or timeouts differ in file.
342 With --readd, ovs-ofctl adds all the flows from file, even those
344 that exist with the same actions, cookie, and timeout in switch.
345 In OpenFlow 1.0 and 1.1, re-adding a flow always resets the
346 flow's packet and byte counters to 0, and in OpenFlow 1.2 and
347 later, it does so only if the reset_counts flag is set.
348 diff-flows source1 source2
350 Reads flow entries from source1 and source2 and prints the dif‐
351 ferences. A flow that is in source1 but not in source2 is
352 printed preceded by a -, and a flow that is in source2 but not
353 in source1 is printed preceded by a +. If a flow exists in both
354 source1 and source2 with different actions, cookie, or timeouts,
355 then both versions are printed preceded by - and +, respec‐
356 tively.
357 source1 and source2 may each name a file or a switch. If a name
359 begins with / or ., then it is considered to be a file name. A
360 name that contains : is considered to be a switch. Otherwise,
361 it is a file if a file by that name exists, a switch if not.
362 For this command, an exit status of 0 means that no differences
364 were found, 1 means that an error occurred, and 2 means that
365 some differences were found.
366 packet-out switch packet-out
368 Connects to switch and instructs it to execute the packet-out
369 OpenFlow message, specified as defined in Packet-Out Syntax sec‐
370 tion.
371 Group Table Commands
373 These commands manage the group table in an OpenFlow switch. In each
374 case, group specifies a group entry in the format described in Group
375 Syntax, below, and file is a text file that contains zero or more
376 groups in the same syntax, one per line, and the optional --bundle op‐
377 tion operates the command as a single atomic transation, see option
378 --bundle, below.
379 The group commands work only with switches that support OpenFlow 1.1 or
381 later or the Open vSwitch group extensions to OpenFlow 1.0 (added in
382 Open vSwitch 2.9.90). For OpenFlow 1.1 or later, it is necessary to
383 explicitly enable these protocol versions in ovs-ofctl (using -O). For
384 more information, see ``Q: What versions of OpenFlow does Open vSwitch
385 support?'' in the Open vSwitch FAQ.
386 [--bundle] add-group switch group
388 [--bundle] add-group switch - < file
389 [--bundle] add-groups switch file
390 Add each group entry to switch's tables. Each group specifica‐
391 tion (e.g., each line in file) may start with add, modify,
392 add_or_mod, delete, insert_bucket, or remove_bucket keyword to
393 specify whether a flow is to be added, modified, or deleted, or
394 whether a group bucket is to be added or removed. For backwards
395 compatibility a group specification without one of these key‐
396 words is treated as a group add. All group mods are executed in
397 the order specified.
398 [--bundle] [--may-create] mod-group switch group
400 [--bundle] [--may-create] mod-group switch - < file
401 Modify the action buckets in entries from switch's tables for
402 each group entry. If a specified group does not already exist,
403 then without --may-create, this command has no effect; with
404 --may-create, it creates a new group. The --may-create option
405 uses an Open vSwitch extension to OpenFlow only implemented in
406 Open vSwitch 2.6 and later.
407 [--bundle] del-groups switch
409 [--bundle] del-groups switch [group]
410 [--bundle] del-groups switch - < file
411 Deletes entries from switch's group table. With only a switch
412 argument, deletes all groups. Otherwise, deletes the group for
413 each group entry.
414 [--bundle] insert-buckets switch group
416 [--bundle] insert-buckets switch - < file
417 Add buckets to an existing group present in the switch's group
418 table. If no command_bucket_id is present in the group specifi‐
419 cation then all buckets of the group are removed.
420 [--bundle] remove-buckets switch group
422 [--bundle] remove-buckets switch - < file
423 Remove buckets to an existing group present in the switch's
424 group table. If no command_bucket_id is present in the group
425 specification then all buckets of the group are removed.
426 dump-groups switch [group]
428 Prints group entries in switch's tables to console. To dump
429 only a specific group, specify its number as group. Otherwise,
430 if group is omitted, or if it is specified as ALL, then all
431 groups are printed.
432 Only OpenFlow 1.5 and later support dumping a specific group.
434 Earlier versions of OpenFlow always dump all groups.
435 dump-group-features switch
437 Prints to the console the group features of the switch.
438 dump-group-stats switch [group]
440 Prints to the console statistics for the specified group in
441 switch's tables. If group is omitted then statistics for all
442 groups are printed.
443 OpenFlow 1.3+ Switch Meter Table Commands
445 These commands manage the meter table in an OpenFlow switch. In each
446 case, meter specifies a meter entry in the format described in Meter
447 Syntax, below.
448 OpenFlow 1.3 introduced support for meters, so these commands only work
450 with switches that support OpenFlow 1.3 or later. It is necessary to
451 explicitly enable these protocol versions in ovs-ofctl (using -O) and
452 in the switch itself (with the protocols column in the Bridge table).
453 For more information, see ``Q: What versions of OpenFlow does Open
454 vSwitch support?'' in the Open vSwitch FAQ.
455 add-meter switch meter
457 Add a meter entry to switch's tables. The meter syntax is de‐
458 scribed in section Meter Syntax, below.
459 mod-meter switch meter
461 Modify an existing meter.
462 del-meters switch [meter]
464 Delete entries from switch's meter table. To delete only a spe‐
465 cific meter, specify its number as meter. Otherwise, if meter
466 is omitted, or if it is specified as all, then all meters are
467 deleted.
468 dump-meters switch [meter]
470 Print entries from switch's meter table. To print only a spe‐
471 cific meter, specify its number as meter. Otherwise, if meter
472 is omitted, or if it is specified as all, then all meters are
473 printed.
474 meter-stats switch [meter]
476 Print meter statistics. meter can specify a single meter with
477 syntax meter=id, or all meters with syntax meter=all.
478 meter-features switch
480 Print meter features.
481 OpenFlow Switch Bundle Command
483 Transactional updates to both flow and group tables can be made with
484 the bundle command. file is a text file that contains zero or more
485 flow mods, group mods, or packet-outs in Flow Syntax, Group Syntax, or
486 Packet-Out Syntax, each line preceded by flow, group, or packet-out
487 keyword, correspondingly. The flow keyword may be optionally followed
488 by one of the keywords add, modify, modify_strict, delete, or
489 delete_strict, of which the add is assumed if a bare flow is given.
490 Similarly, the group keyword may be optionally followed by one of the
491 keywords add, modify, add_or_mod, delete, insert_bucket, or re‐
492 move_bucket, of which the add is assumed if a bare group is given.
493 bundle switch file
495 Execute all flow and group mods in file as a single atomic
496 transaction against switch's tables. All bundled mods are exe‐
497 cuted in the order specified.
498 OpenFlow Switch Tunnel TLV Table Commands
500 Open vSwitch maintains a mapping table between tunnel option TLVs (de‐
501 fined by <class, type, length>) and NXM fields tun_metadatan, where n
502 ranges from 0 to 63, that can be operated on for the purposes of
503 matches, actions, etc. This TLV table can be used for Geneve option
504 TLVs or other protocols with options in same TLV format as Geneve op‐
505 tions. This mapping must be explicitly specified by the user through
506 the following commands.
507 A TLV mapping is specified with the syntax
509 {class=class,type=type,len=length}->tun_metadatan. When an option map‐
510 ping exists for a given tun_metadatan, matching on the defined field
511 becomes possible, e.g.:
512 ovs-ofctl add-tlv-map br0
514 "{class=0xffff,type=0,len=4}->tun_metadata0"
515 ovs-ofctl add-flow br0 tun_metadata0=1234,actions=controller
517 A mapping should not be changed while it is in active use by a flow.
519 The result of doing so is undefined.
520 These commands are Nicira extensions to OpenFlow and require Open
522 vSwitch 2.5 or later.
523 add-tlv-map switch option[,option]...
526 Add each option to switch's tables. Duplicate fields are re‐
527 jected.
528 del-tlv-map switch [option[,option]]...
530 Delete each option from switch's table, or all option TLV map‐
531 ping if no option is specified. Fields that aren't mapped are
532 ignored.
533 dump-tlv-map switch
535 Show the currently mapped fields in the switch's option table as
536 well as switch capabilities.
537 OpenFlow Switch Monitoring Commands
539 snoop switch
540 Connects to switch and prints to the console all OpenFlow mes‐
541 sages received. Unlike other ovs-ofctl commands, if switch is
542 the name of a bridge, then the snoop command connects to a Unix
543 domain socket named /var/run/openvswitch/switch.snoop.
544 ovs-vswitchd listens on such a socket for each bridge and sends
545 to it all of the OpenFlow messages sent to or received from its
546 configured OpenFlow controller. Thus, this command can be used
547 to view OpenFlow protocol activity between a switch and its con‐
548 troller.
549 When a switch has more than one controller configured, only the
551 traffic to and from a single controller is output. If none of
552 the controllers is configured as a primary or a secondary (using
553 a Nicira extension to OpenFlow 1.0 or 1.1, or a standard request
554 in OpenFlow 1.2 or later), then a controller is chosen arbitrar‐
555 ily among them. If there is a primary controller, it is chosen;
556 otherwise, if there are any controllers that are not primaries
557 or secondaries, one is chosen arbitrarily; otherwise, a sec‐
558 ondary controller is chosen arbitrarily. This choice is made
559 once at connection time and does not change as controllers re‐
560 configure their roles.
561 If a switch has no controller configured, or if the configured
563 controller is disconnected, no traffic is sent, so monitoring
564 will not show any traffic.
565 monitor switch [miss-len] [invalid_ttl] [watch:[spec...]]
567 Connects to switch and prints to the console all OpenFlow mes‐
568 sages received. Usually, switch should specify the name of a
569 bridge in the ovs-vswitchd database. This is available only in
570 OpenFlow 1.0 as Nicira extension.
571 If miss-len is provided, ovs-ofctl sends an OpenFlow ``set con‐
573 figuration'' message at connection setup time that requests
574 miss-len bytes of each packet that misses the flow table. Open
575 vSwitch does not send these and other asynchronous messages to
576 an ovs-ofctl monitor client connection unless a nonzero value is
577 specified on this argument. (Thus, if miss-len is not speci‐
578 fied, very little traffic will ordinarily be printed.)
579 If invalid_ttl is passed, ovs-ofctl sends an OpenFlow ``set con‐
581 figuration'' message at connection setup time that requests IN‐
582 VALID_TTL_TO_CONTROLLER, so that ovs-ofctl monitor can receive
583 ``packet-in'' messages when TTL reaches zero on dec_ttl action.
584 Only OpenFlow 1.1 and 1.2 support invalid_ttl; Open vSwitch also
585 implements it for OpenFlow 1.0 as an extension.
586 watch:[spec...] causes ovs-ofctl to send a ``monitor request''
588 Nicira extension message to the switch at connection setup time.
589 This message causes the switch to send information about flow
590 table changes as they occur. The following comma-separated spec
591 syntax is available:
592 !initial
594 Do not report the switch's initial flow table contents.
595 !add Do not report newly added flows.
597 !delete
599 Do not report deleted flows.
600 !modify
602 Do not report modifications to existing flows.
603 !own Abbreviate changes made to the flow table by ovs-ofctl's
605 own connection to the switch. (These could only occur
606 using the ofctl/send command described below under RUN‐
607 TIME MANAGEMENT COMMANDS.)
608 !actions
610 Do not report actions as part of flow updates.
611 table=table
613 Limits the monitoring to the table with the given table,
614 which may be expressed as a number between 0 and 254 or
615 (unless --no-names is specified) a name. By default, all
616 tables are monitored.
617 out_port=port
619 If set, only flows that output to port are monitored.
620 The port may be an OpenFlow port number or keyword (e.g.
621 LOCAL).
622 field=value
624 Monitors only flows that have field specified as the
625 given value. Any syntax valid for matching on dump-flows
626 may be used.
627 This command may be useful for debugging switch or controller
629 implementations. With watch:, it is particularly useful for ob‐
630 serving how a controller updates flow tables.
631 OpenFlow Switch and Controller Commands
633 The following commands, like those in the previous section, may be ap‐
634 plied to OpenFlow switches, using any of the connection methods de‐
635 scribed in that section. Unlike those commands, these may also be ap‐
636 plied to OpenFlow controllers.
637 probe target
639 Sends a single OpenFlow echo-request message to target and waits
640 for the response. With the -t or --timeout option, this command
641 can test whether an OpenFlow switch or controller is up and run‐
642 ning.
643 ping target [n]
645 Sends a series of 10 echo request packets to target and times
646 each reply. The echo request packets consist of an OpenFlow
647 header plus n bytes (default: 64) of randomly generated payload.
648 This measures the latency of individual requests.
649 benchmark target n count
651 Sends count echo request packets that each consist of an Open‐
652 Flow header plus n bytes of payload and waits for each response.
653 Reports the total time required. This is a measure of the maxi‐
654 mum bandwidth to target for round-trips of n-byte messages.
655 Other Commands
657 ofp-parse file
658 Reads file (or stdin if file is -) as a series of OpenFlow mes‐
659 sages in the binary format used on an OpenFlow connection, and
660 prints them to the console. This can be useful for printing
661 OpenFlow messages captured from a TCP stream.
662 ofp-parse-pcap file [port...]
664 Reads file, which must be in the PCAP format used by network
665 capture tools such as tcpdump or wireshark, extracts all the TCP
666 streams for OpenFlow connections, and prints the OpenFlow mes‐
667 sages in those connections in human-readable format on stdout.
668 OpenFlow connections are distinguished by TCP port number. Non-
670 OpenFlow packets are ignored. By default, data on TCP ports
671 6633 and 6653 are considered to be OpenFlow. Specify one or
672 more port arguments to override the default.
673 This command cannot usefully print SSL encrypted traffic. It
675 does not understand IPv6.
676 Flow Syntax
678 Some ovs-ofctl commands accept an argument that describes a flow or
679 flows. Such flow descriptions comprise a series of field=value assign‐
680 ments, separated by commas or white space. (Embedding spaces into a
681 flow description normally requires quoting to prevent the shell from
682 breaking the description into multiple arguments.)
683 Flow descriptions should be in normal form. This means that a flow may
685 only specify a value for an L3 field if it also specifies a particular
686 L2 protocol, and that a flow may only specify an L4 field if it also
687 specifies particular L2 and L3 protocol types. For example, if the L2
688 protocol type dl_type is wildcarded, then L3 fields nw_src, nw_dst, and
689 nw_proto must also be wildcarded. Similarly, if dl_type or nw_proto
690 (the L3 protocol type) is wildcarded, so must be the L4 fields tcp_dst
691 and tcp_src. ovs-ofctl will warn about flows not in normal form.
692 ovs-fields(7) describes the supported fields and how to match them. In
694 addition to match fields, commands that operate on flows accept a few
695 additional key-value pairs:
696 table=table
698 For flow dump commands, limits the flows dumped to those in ta‐
699 ble, which may be expressed as a number between 0 and 255 or
700 (unless --no-names is specified) a name. If not specified (or
701 if 255 is specified as table), then flows in all tables are
702 dumped.
703 For flow table modification commands, behavior varies based on
705 the OpenFlow version used to connect to the switch:
706 OpenFlow 1.0
708 OpenFlow 1.0 does not support table for modifying flows.
709 ovs-ofctl will exit with an error if table (other than
710 table=255) is specified for a switch that only supports
711 OpenFlow 1.0.
712 In OpenFlow 1.0, the switch chooses the table into which
714 to insert a new flow. The Open vSwitch software switch
715 always chooses table 0. Other Open vSwitch datapaths and
716 other OpenFlow implementations may choose different ta‐
717 bles.
718 The OpenFlow 1.0 behavior in Open vSwitch for modifying
720 or removing flows depends on whether --strict is used.
721 Without --strict, the command applies to matching flows
722 in all tables. With --strict, the command will operate
723 on any single matching flow in any table; it will do
724 nothing if there are matches in more than one table.
725 (The distinction between these behaviors only matters if
726 non-OpenFlow 1.0 commands were also used, because Open‐
727 Flow 1.0 alone cannot add flows with the same matching
728 criteria to multiple tables.)
729 OpenFlow 1.0 with table_id extension
731 Open vSwitch implements an OpenFlow extension that allows
732 the controller to specify the table on which to operate.
733 ovs-ofctl automatically enables the extension when table
734 is specified and OpenFlow 1.0 is used. ovs-ofctl auto‐
735 matically detects whether the switch supports the exten‐
736 sion. As of this writing, this extension is only known
737 to be implemented by Open vSwitch.
738 With this extension, ovs-ofctl operates on the requested
740 table when table is specified, and acts as described for
741 OpenFlow 1.0 above when no table is specified (or for ta‐
742 ble=255).
743 OpenFlow 1.1
745 OpenFlow 1.1 requires flow table modification commands to
746 specify a table. When table is not specified (or ta‐
747 ble=255 is specified), ovs-ofctl defaults to table 0.
748 OpenFlow 1.2 and later
750 OpenFlow 1.2 and later allow flow deletion commands, but
751 not other flow table modification commands, to operate on
752 all flow tables, with the behavior described above for
753 OpenFlow 1.0.
754 duration=...
756 n_packet=...
757 n_bytes=...
758 ovs-ofctl ignores assignments to these ``fields'' to allow out‐
759 put from the dump-flows command to be used as input for other
760 commands that parse flows.
761 The add-flow, add-flows, and mod-flows commands require an additional
763 field, which must be the final field specified:
764 actions=[action][,action...]
766 Specifies a comma-separated list of actions to take on a packet
767 when the flow entry matches. If no action is specified, then
768 packets matching the flow are dropped. See ovs-actions(7) for
769 details on the syntax and semantics of actions. K
770 An opaque identifier called a cookie can be used as a handle to iden‐
772 tify a set of flows:
773 cookie=value
775 A cookie can be associated with a flow using the add-flow,
776 add-flows, and mod-flows commands. value can be any 64-bit num‐
777 ber and need not be unique among flows. If this field is omit‐
778 ted, a default cookie value of 0 is used.
779 cookie=value/mask
781 When using NXM, the cookie can be used as a handle for querying,
782 modifying, and deleting flows. value and mask may be supplied
783 for the del-flows, mod-flows, dump-flows, and dump-aggregate
784 commands to limit matching cookies. A 1-bit in mask indicates
785 that the corresponding bit in cookie must match exactly, and a
786 0-bit wildcards that bit. A mask of -1 may be used to exactly
787 match a cookie.
788 The mod-flows command can update the cookies of flows that match
790 a cookie by specifying the cookie field twice (once with a mask
791 for matching and once without to indicate the new value):
792 ovs-ofctl mod-flows br0 cookie=1,actions=normal
794 Change all flows' cookies to 1 and change their actions
795 to normal.
796 ovs-ofctl mod-flows br0 cookie=1/-1,cookie=2,actions=normal
798 Update cookies with a value of 1 to 2 and change their
799 actions to normal.
800 The ability to match on cookies was added in Open vSwitch 1.5.0.
802 The following additional field sets the priority for flows added by the
804 add-flow and add-flows commands. For mod-flows and del-flows when
805 --strict is specified, priority must match along with the rest of the
806 flow specification. For mod-flows without --strict, priority is only
807 significant if the command creates a new flow, that is, non-strict
808 mod-flows does not match on priority and will not change the priority
809 of existing flows. Other commands do not allow priority to be speci‐
810 fied.
811 priority=value
813 The priority at which a wildcarded entry will match in compari‐
814 son to others. value is a number between 0 and 65535, inclu‐
815 sive. A higher value will match before a lower one. An exact-
816 match entry will always have priority over an entry containing
817 wildcards, so it has an implicit priority value of 65535. When
818 adding a flow, if the field is not specified, the flow's prior‐
819 ity will default to 32768.
820 OpenFlow leaves behavior undefined when two or more flows with
822 the same priority can match a single packet. Some users expect
823 ``sensible'' behavior, such as more specific flows taking prece‐
824 dence over less specific flows, but OpenFlow does not specify
825 this and Open vSwitch does not implement it. Users should
826 therefore take care to use priorities to ensure the behavior
827 that they expect.
828 The add-flow, add-flows, and mod-flows commands support the following
830 additional options. These options affect only new flows. Thus, for
831 add-flow and add-flows, these options are always significant, but for
832 mod-flows they are significant only if the command creates a new flow,
833 that is, their values do not update or affect existing flows.
834 idle_timeout=seconds
836 Causes the flow to expire after the given number of seconds of
837 inactivity. A value of 0 (the default) prevents a flow from ex‐
838 piring due to inactivity.
839 hard_timeout=seconds
841 Causes the flow to expire after the given number of seconds, re‐
842 gardless of activity. A value of 0 (the default) gives the flow
843 no hard expiration deadline.
844 importance=value
846 Sets the importance of a flow. The flow entry eviction mecha‐
847 nism can use importance as a factor in deciding which flow to
848 evict. A value of 0 (the default) makes the flow non-evictable
849 on the basis of importance. Specify a value between 0 and
850 65535.
851 Only OpenFlow 1.4 and later support importance.
853 send_flow_rem
855 Marks the flow with a flag that causes the switch to generate a
856 ``flow removed'' message and send it to interested controllers
857 when the flow later expires or is removed.
858 check_overlap
860 Forces the switch to check that the flow match does not overlap
861 that of any different flow with the same priority in the same
862 table. (This check is expensive so it is best to avoid it.)
863 reset_counts
865 When this flag is specified on a flow being added to a switch,
866 and the switch already has a flow with an identical match, an
867 OpenFlow 1.2 (or later) switch resets the flow's packet and byte
868 counters to 0. Without the flag, the packet and byte counters
869 are preserved.
870 OpenFlow 1.0 and 1.1 switches always reset counters in this sit‐
872 uation, as if reset_counts were always specified.
873 Open vSwitch 1.10 added support for reset_counts.
875 no_packet_counts
877 no_byte_counts
878 Adding these flags to a flow advises an OpenFlow 1.3 (or later)
879 switch that the controller does not need packet or byte coun‐
880 ters, respectively, for the flow. Some switch implementations
881 might achieve higher performance or reduce resource consumption
882 when these flags are used. These flags provide no benefit to
883 the Open vSwitch software switch implementation.
884 OpenFlow 1.2 and earlier do not support these flags.
886 Open vSwitch 1.10 added support for no_packet_counts and
888 no_byte_counts.
889 The dump-flows, dump-aggregate, del-flow and del-flows commands support
891 these additional optional fields:
892 out_port=port
894 If set, a matching flow must include an output action to port,
895 which must be an OpenFlow port number or name (e.g. local).
896 out_group=group
898 If set, a matching flow must include an group action naming
899 group, which must be an OpenFlow group number. This field is
900 supported in Open vSwitch 2.5 and later and requires OpenFlow
901 1.1 or later.
902 Table Entry Output
904 The dump-tables and dump-aggregate commands print information about the
905 entries in a datapath's tables. Each line of output is a flow entry as
906 described in Flow Syntax, above, plus some additional fields:
907 duration=secs
909 The time, in seconds, that the entry has been in the table.
910 secs includes as much precision as the switch provides, possibly
911 to nanosecond resolution.
912 n_packets
914 The number of packets that have matched the entry.
915 n_bytes
917 The total number of bytes from packets that have matched the en‐
918 try.
919 The following additional fields are included only if the switch is Open
921 vSwitch 1.6 or later and the NXM flow format is used to dump the flow
922 (see the description of the --flow-format option below). The values of
923 these additional fields are approximations only and in particular
924 idle_age will sometimes become nonzero even for busy flows.
925 hard_age=secs
927 The integer number of seconds since the flow was added or modi‐
928 fied. hard_age is displayed only if it differs from the integer
929 part of duration. (This is separate from duration because
930 mod-flows restarts the hard_timeout timer without zeroing dura‐
931 tion.)
932 idle_age=secs
934 The integer number of seconds that have passed without any pack‐
935 ets passing through the flow.
936 Packet-Out Syntax
938 ovs-ofctl bundle command accepts packet-outs to be specified in the
939 bundle file. Each packet-out comprises of a series of field=value as‐
940 signments, separated by commas or white space. (Embedding spaces into
941 a packet-out description normally requires quoting to prevent the shell
942 from breaking the description into multiple arguments.). Unless noted
943 otherwise only the last instance of each field is honoured. This same
944 syntax is also supported by the ovs-ofctl packet-out command.
945 in_port=port
947 The port number to be considered the in_port when processing ac‐
948 tions. This can be any valid OpenFlow port number, or any of
949 the LOCAL, CONTROLLER, or NONE. This field is required.
950 pipeline_field=value
953 Optionally, user can specify a list of pipeline fields for a
954 packet-out message. The supported pipeline fields includes tun‐
955 nel fields and register fields as defined in ovs-fields(7).
956 packet=hex-string
959 The actual packet to send, expressed as a string of hexadecimal
960 bytes. This field is required.
961 actions=[action][,action...]
964 The syntax of actions are identical to the actions= field de‐
965 scribed in Flow Syntax above. Specifying actions= is optional,
966 but omitting actions is interpreted as a drop, so the packet
967 will not be sent anywhere from the switch. actions must be
968 specified at the end of each line, like for flow mods.
969 Group Syntax
971 Some ovs-ofctl commands accept an argument that describes a group or
972 groups. Such flow descriptions comprise a series field=value assign‐
973 ments, separated by commas or white space. (Embedding spaces into a
974 group description normally requires quoting to prevent the shell from
975 breaking the description into multiple arguments.). Unless noted other‐
976 wise only the last instance of each field is honoured.
977 group_id=id
979 The integer group id of group. When this field is specified in
980 del-groups or dump-groups, the keyword "all" may be used to des‐
981 ignate all groups. This field is required.
982 type=type
986 The type of the group. The add-group, add-groups and mod-groups
987 commands require this field. It is prohibited for other com‐
988 mands. The following keywords designated the allowed types:
989 all Execute all buckets in the group.
991 select Execute one bucket in the group, balancing across the
993 buckets according to their weights. To select a bucket,
994 for each live bucket, Open vSwitch hashes flow data with
995 the bucket ID and multiplies by the bucket weight to ob‐
996 tain a ``score,'' and then selects the bucket with the
997 highest score. Use selection_method to control the flow
998 data used for selection.
999 indirect
1001 Executes the one bucket in the group.
1002 ff
1004 fast_failover
1005 Executes the first live bucket in the group which is as‐
1006 sociated with a live port or group.
1007 command_bucket_id=id
1010 The bucket to operate on. The insert-buckets and remove-buckets
1011 commands require this field. It is prohibited for other com‐
1012 mands. id may be an integer or one of the following keywords:
1013 all Operate on all buckets in the group. Only valid when
1015 used with the remove-buckets command in which case the
1016 effect is to remove all buckets from the group.
1017 first Operate on the first bucket present in the group. In the
1019 case of the insert-buckets command the effect is to in‐
1020 sert new bucets just before the first bucket already
1021 present in the group; or to replace the buckets of the
1022 group if there are no buckets already present in the
1023 group. In the case of the remove-buckets command the ef‐
1024 fect is to remove the first bucket of the group; or do
1025 nothing if there are no buckets present in the group.
1026 last Operate on the last bucket present in the group. In the
1028 case of the insert-buckets command the effect is to in‐
1029 sert new bucets just after the last bucket already
1030 present in the group; or to replace the buckets of the
1031 group if there are no buckets already present in the
1032 group. In the case of the remove-buckets command the ef‐
1033 fect is to remove the last bucket of the group; or do
1034 nothing if there are no buckets present in the group.
1035 If id is an integer then it should correspond to the bucket_id
1037 of a bucket present in the group. In case of the insert-buckets
1038 command the effect is to insert buckets just before the bucket
1039 in the group whose bucket_id is id. In case of the iremove-
1040 buckets command the effect is to remove the in the group whose
1041 bucket_id is id. It is an error if there is no bucket persent
1042 group in whose bucket_id is id.
1043 selection_method=method
1046 The selection method used to select a bucket for a select group.
1047 This is a string of 1 to 15 bytes in length known to lower lay‐
1048 ers. This field is optional for add-group, add-groups and
1049 mod-group commands on groups of type select. Prohibited other‐
1050 wise. If no selection method is specified, Open vSwitch up to
1051 release 2.9 applies the hash method with default fields. From
1052 2.10 onwards Open vSwitch defaults to the dp_hash method with
1053 symmetric L3/L4 hash algorithm, as long as the weighted group
1054 buckets can be mapped to dp_hash values with sufficient accu‐
1055 racy. In 2.10 this was restricted to a maximum of 64 buckets,
1056 and in 2.17 the limit was raised to 256 buckets. In those rare
1057 cases Open vSwitch 2.10 and later fall back to the hash method
1058 with the default set of hash fields.
1059 dp_hash
1061 Use a datapath computed hash value. The hash algorithm
1062 varies accross different datapath implementations.
1063 dp_hash uses the upper 32 bits of the selec‐
1064 tion_method_param as the datapath hash algorithm selec‐
1065 tor. The supported values are 0 (corresponding to hash
1066 computation over the IP 5-tuple) and 1 (corresponding to
1067 a symmetric hash computation over the IP 5-tuple). Se‐
1068 lecting specific fields with the fields option is not
1069 supported with dp_hash). The lower 32 bits are used as
1070 the hash basis.
1071 Using dp_hash has the advantage that it does not require
1073 the generated datapath flows to exact match any addi‐
1074 tional packet header fields. For example, even if multi‐
1075 ple TCP connections thus hashed to different select group
1076 buckets have different source port numbers, generally all
1077 of them would be handled with a small set of already es‐
1078 tablished datapath flows, resulting in less latency for
1079 TCP SYN packets. The downside is that the shared data‐
1080 path flows must match each packet twice, as the datapath
1081 hash value calculation happens only when needed, and a
1082 second match is required to match some bits of its value.
1083 This double-matching incurs a small additional latency
1084 cost for each packet, but this latency is orders of mag‐
1085 nitude less than the latency of creating new datapath
1086 flows for new TCP connections.
1087 hash Use a hash computed over the fields specified with the
1089 fields option, see below. If no hash fields are speci‐
1090 fied, hash defaults to a symmetric hash over the combina‐
1091 tion of MAC addresses, VLAN tags, Ether type, IP ad‐
1092 dresses and L4 port numbers. hash uses the selec‐
1093 tion_method_param as the hash basis.
1094 Note that the hashed fields become exact matched by the
1096 datapath flows. For example, if the TCP source port is
1097 hashed, the created datapath flows will match the spe‐
1098 cific TCP source port value present in the packet re‐
1099 ceived. Since each TCP connection generally has a dif‐
1100 ferent source port value, a separate datapath flow will
1101 be need to be inserted for each TCP connection thus
1102 hashed to a select group bucket.
1103 This option uses a Netronome OpenFlow extension which is only
1105 supported when using Open vSwitch 2.4 and later with OpenFlow
1106 1.5 and later.
1107 selection_method_param=param
1110 64-bit integer parameter to the selection method selected by the
1111 selection_method field. The parameter's use is defined by the
1112 lower-layer that implements the selection_method. It is op‐
1113 tional if the selection_method field is specified as a non-empty
1114 string. Prohibited otherwise. The default value is zero.
1115 This option uses a Netronome OpenFlow extension which is only
1117 supported when using Open vSwitch 2.4 and later with OpenFlow
1118 1.5 and later.
1119 fields=field
1122 fields(field[=mask]...)
1123 The field parameters to selection method selected by the selec‐
1124 tion_method field. The syntax is described in Flow Syntax with
1125 the additional restrictions that if a value is provided it is
1126 treated as a wildcard mask and wildcard masks following a slash
1127 are prohibited. The pre-requisites of fields must be provided by
1128 any flows that output to the group. The use of the fields is
1129 defined by the lower-layer that implements the selection_method.
1130 They are optional if the selection_method field is specified as
1131 ``hash', prohibited otherwise. The default is no fields.
1132 This option will use a Netronome OpenFlow extension which is
1134 only supported when using Open vSwitch 2.4 and later with Open‐
1135 Flow 1.5 and later.
1136 bucket=bucket_parameters
1139 The add-group, add-groups and mod-group commands require at
1140 least one bucket field. Bucket fields must appear after all
1141 other fields. Multiple bucket fields to specify multiple buck‐
1142 ets. The order in which buckets are specified corresponds to
1143 their order in the group. If the type of the group is "indirect"
1144 then only one group may be specified. bucket_parameters con‐
1145 sists of a list of field=value assignments, separated by commas
1146 or white space followed by a comma-separated list of actions.
1147 The fields for bucket_parameters are:
1148 bucket_id=id
1150 The 32-bit integer group id of the bucket. Values
1151 greater than 0xffffff00 are reserved. This field was
1152 added in Open vSwitch 2.4 to conform with the OpenFlow
1153 1.5 specification. It is not supported when earlier ver‐
1154 sions of OpenFlow are used. Open vSwitch will automati‐
1155 cally allocate bucket ids when they are not specified.
1156 actions=[action][,action...]
1158 The syntax of actions are identical to the actions= field
1159 described in Flow Syntax above. Specifying actions= is
1160 optional, any unknown bucket parameter will be inter‐
1161 preted as an action.
1162 weight=value
1164 The relative weight of the bucket as an integer. This may
1165 be used by the switch during bucket select for groups
1166 whose type is select.
1167 watch_port=port
1169 Port used to determine liveness of group. This or the
1170 watch_group field is required for groups whose type is ff
1171 or fast_failover. This or the watch_group field can also
1172 be used for groups whose type is select.
1173 watch_group=group_id
1175 Group identifier of group used to determine liveness of
1176 group. This or the watch_port field is required for
1177 groups whose type is ff or fast_failover. This or the
1178 watch_port field can also be used for groups whose type
1179 is select.
1180 Meter Syntax
1182 The meter table commands accept an argument that describes a meter.
1183 Such meter descriptions comprise a series field=value assignments, sep‐
1184 arated by commas or white space. (Embedding spaces into a group de‐
1185 scription normally requires quoting to prevent the shell from breaking
1186 the description into multiple arguments.). Unless noted otherwise only
1187 the last instance of each field is honoured.
1188 meter=id
1190 The identifier for the meter. An integer is used to specify a
1191 user-defined meter. In addition, the keywords "all", "con‐
1192 troller", and "slowpath", are also supported as virtual meters.
1193 The "controller" and "slowpath" virtual meters apply to packets
1194 sent to the controller and to the OVS userspace, respectively.
1195 When this field is specified in del-meter, dump-meter, or meter-
1197 stats, the keyword "all" may be used to designate all meters.
1198 This field is required, except for meter-stats, which dumps all
1199 stats when this field is not specified.
1200 kbps
1202 pktps The unit for the rate and burst_size band parameters. kbps
1203 specifies kilobits per second, and pktps specifies packets per
1204 second. A unit is required for the add-meter and mod-meter com‐
1205 mands.
1206 burst If set, enables burst support for meter bands through the
1209 burst_size parameter.
1210 stats If set, enables the collection of meter and band statistics.
1213 bands=band_parameters
1216 The add-meter and mod-meter commands require at least one band
1217 specification. Bands must appear after all other fields.
1218 type=type
1220 The type of the meter band. This keyword starts a new
1221 band specification. Each band specifies a rate above
1222 which the band is to take some action. The action depends
1223 on the band type. If multiple bands' rate is exceeded,
1224 then the band with the highest rate among the exceeded
1225 bands is selected. The following keywords designate the
1226 allowed meter band types:
1227 drop Drop packets exceeding the band's rate limit.
1229 The other band_parameters are:
1231 rate=value
1233 The relative rate limit for this band, in kilobits per
1234 second or packets per second, depending on whether kbps
1235 or pktps was specified.
1236 burst_size=size
1238 If burst is specified for the meter entry, configures the
1239 maximum burst allowed for the band in kilobits or pack‐
1240 ets, depending on whether kbps or pktps was specified.
1241 If unspecified, the switch is free to select some reason‐
1242 able value depending on its configuration.
1243
1245 --strict
1246 Uses strict matching when running flow modification commands.
1247 --names
1249 --no-names
1250 Every OpenFlow port has a name and a number, and every OpenFlow
1251 flow table has a number and sometimes a name. By default,
1252 ovs-ofctl commands accept both port and table names and numbers,
1253 and they display port and table names if ovs-ofctl is running on
1254 an interactive console, numbers otherwise. With --names,
1255 ovs-ofctl commands both accept and display port and table names;
1256 with --no-names, commands neither accept nor display port and
1257 table names.
1258 If a port or table name contains special characters or might be
1260 confused with a keyword within a flow, it may be enclosed in
1261 double quotes (escaped from the shell). If necessary, JSON-
1262 style escape sequences may be used inside quotes, as specified
1263 in RFC 7159. When it displays port and table names, ovs-ofctl
1264 quotes any name that does not start with a letter followed by
1265 letters or digits.
1266 Open vSwitch added support for port names and these options.
1268 Open vSwitch 2.10 added support for table names. Earlier ver‐
1269 sions always behaved as if --no-names were specified.
1270 Open vSwitch does not place its own limit on the length of port
1272 names, but OpenFlow limits port names to 15 bytes. Because
1273 ovs-ofctl uses OpenFlow to retrieve the mapping between port
1274 names and numbers, names longer than this limit will be trun‐
1275 cated for both display and acceptance. Truncation can also
1276 cause long names that are different to appear to be the same;
1277 when a switch has two ports with the same (truncated) name,
1278 ovs-ofctl refuses to display or accept the name, using the num‐
1279 ber instead.
1280 OpenFlow and Open vSwitch limit table names to 32 bytes.
1282 --stats
1284 --no-stats
1285 The dump-flows command by default, or with --stats, includes
1286 flow duration, packet and byte counts, and idle and hard age in
1287 its output. With --no-stats, it omits all of these, as well as
1288 cookie values and table IDs if they are zero.
1289 --read-only
1291 Do not execute read/write commands.
1292 --bundle
1294 Execute flow mods as an OpenFlow 1.4 atomic bundle transaction.
1295 • Within a bundle, all flow mods are processed in the order
1297 they appear and as a single atomic transaction, meaning
1298 that if one of them fails, the whole transaction fails
1299 and none of the changes are made to the switch's flow ta‐
1300 ble, and that each given datapath packet traversing the
1301 OpenFlow tables sees the flow tables either as before the
1302 transaction, or after all the flow mods in the bundle
1303 have been successfully applied.
1304 • The beginning and the end of the flow table modification
1306 commands in a bundle are delimited with OpenFlow 1.4 bun‐
1307 dle control messages, which makes it possible to stream
1308 the included commands without explicit OpenFlow barriers,
1309 which are otherwise used after each flow table modifica‐
1310 tion command. This may make large modifications execute
1311 faster as a bundle.
1312 • Bundles require OpenFlow 1.4 or higher. An explicit -O
1314 OpenFlow14 option is not needed, but you may need to en‐
1315 able OpenFlow 1.4 support for OVS by setting the OVSDB
1316 protocols column in the bridge table.
1317 -O [version[,version]...]
1319 --protocols=[version[,version]...]
1320 Sets the OpenFlow protocol versions that are allowed when estab‐
1321 lishing an OpenFlow session.
1322 These protocol versions are enabled by default:
1324 • OpenFlow10, for OpenFlow 1.0.
1326 The following protocol versions are generally supported, but for com‐
1327 patibility with older versions of Open vSwitch they are not enabled by
1328 default:
1329 • OpenFlow11, for OpenFlow 1.1.
1331 • OpenFlow12, for OpenFlow 1.2.
1333 • OpenFlow13, for OpenFlow 1.3.
1335 • OpenFlow14, for OpenFlow 1.4.
1337 • OpenFlow15, for OpenFlow 1.5.
1339 -F format[,format...]
1341 --flow-format=format[,format...]
1342 ovs-ofctl supports the following individual flow formats, any
1343 number of which may be listed as format:
1344 OpenFlow10-table_id
1346 This is the standard OpenFlow 1.0 flow format. All Open‐
1347 Flow switches and all versions of Open vSwitch support
1348 this flow format.
1349 OpenFlow10+table_id
1351 This is the standard OpenFlow 1.0 flow format plus a
1352 Nicira extension that allows ovs-ofctl to specify the
1353 flow table in which a particular flow should be placed.
1354 Open vSwitch 1.2 and later supports this flow format.
1355 NXM-table_id (Nicira Extended Match)
1357 This Nicira extension to OpenFlow is flexible and exten‐
1358 sible. It supports all of the Nicira flow extensions,
1359 such as tun_id and registers. Open vSwitch 1.1 and later
1360 supports this flow format.
1361 NXM+table_id (Nicira Extended Match)
1363 This combines Nicira Extended match with the ability to
1364 place a flow in a specific table. Open vSwitch 1.2 and
1365 later supports this flow format.
1366 OXM-OpenFlow12
1368 OXM-OpenFlow13
1369 OXM-OpenFlow14
1370 OXM-OpenFlow15
1371 These are the standard OXM (OpenFlow Extensible Match)
1372 flow format in OpenFlow 1.2 and later.
1373 ovs-ofctl also supports the following abbreviations for collec‐
1375 tions of flow formats:
1376 any Any supported flow format.
1378 OpenFlow10
1380 OpenFlow10-table_id or OpenFlow10+table_id.
1381 NXM NXM-table_id or NXM+table_id.
1383 OXM OXM-OpenFlow12, OXM-OpenFlow13, or OXM-OpenFlow14.
1385 For commands that modify the flow table, ovs-ofctl by default
1387 negotiates the most widely supported flow format that supports
1388 the flows being added. For commands that query the flow table,
1389 ovs-ofctl by default uses the most advanced format supported by
1390 the switch.
1391 This option, where format is a comma-separated list of one or
1393 more of the formats listed above, limits ovs-ofctl's choice of
1394 flow format. If a command cannot work as requested using one of
1395 the specified flow formats, ovs-ofctl will report a fatal error.
1396 -P format
1398 --packet-in-format=format
1399 ovs-ofctl supports the following ``packet-in'' formats, in order
1400 of increasing capability:
1401 standard
1403 This uses the OFPT_PACKET_IN message, the standard
1404 ``packet-in'' message for any given OpenFlow version.
1405 Every OpenFlow switch that supports a given OpenFlow ver‐
1406 sion supports this format.
1407 nxt_packet_in
1409 This uses the NXT_PACKET_IN message, which adds many of
1410 the capabilities of the OpenFlow 1.1 and later ``packet-
1411 in'' messages before those OpenFlow versions were avail‐
1412 able in Open vSwitch. Open vSwitch 1.1 and later support
1413 this format. Only Open vSwitch 2.6 and later, however,
1414 support it for OpenFlow 1.1 and later (but there is lit‐
1415 tle reason to use it with those versions of OpenFlow).
1416 nxt_packet_in2
1418 This uses the NXT_PACKET_IN2 message, which is extensible
1419 and should avoid the need to define new formats later.
1420 In particular, this format supports passing arbitrary
1421 user-provided data to a controller using the userdata op‐
1422 tion on the controller action. Open vSwitch 2.6 and
1423 later support this format.
1424 Without this option, ovs-ofctl prefers nxt_packet_in2 if the
1426 switch supports it. Otherwise, if OpenFlow 1.0 is in use,
1427 ovs-ofctl prefers nxt_packet_in if the switch supports it. Oth‐
1428 erwise, ovs-ofctl falls back to the standard packet-in format.
1429 When this option is specified, ovs-ofctl insists on the selected
1430 format. If the switch does not support the requested format,
1431 ovs-ofctl will report a fatal error.
1432 Before version 2.6, Open vSwitch called standard format open‐
1434 flow10 and nxt_packet_in format nxm, and ovs-ofctl still accepts
1435 these names as synonyms. (The name openflow10 was a misnomer
1436 because this format actually varies from one OpenFlow version to
1437 another; it is not consistently OpenFlow 1.0 format. Similarly,
1438 when nxt_packet_in2 was introduced, the name nxm became confus‐
1439 ing because it also uses OXM/NXM.)
1440 This option affects only the monitor command.
1442 --timestamp
1444 Print a timestamp before each received packet. This option only
1445 affects the monitor, snoop, and ofp-parse-pcap commands.
1446 -m
1448 --more Increases the verbosity of OpenFlow messages printed and logged
1449 by ovs-ofctl commands. Specify this option more than once to
1450 increase verbosity further.
1451 --sort[=field]
1453 --rsort[=field]
1454 Display output sorted by flow field in ascending (--sort) or de‐
1455 scending (--rsort) order, where field is any of the fields that
1456 are allowed for matching or priority to sort by priority. When
1457 field is omitted, the output is sorted by priority. Specify
1458 these options multiple times to sort by multiple fields.
1459 Any given flow will not necessarily specify a value for a given
1461 field. This requires special treatement:
1462 • A flow that does not specify any part of a field that is
1464 used for sorting is sorted after all the flows that do
1465 specify the field. For example, --sort=tcp_src will sort
1466 all the flows that specify a TCP source port in ascending
1467 order, followed by the flows that do not specify a TCP
1468 source port at all.
1469 • A flow that only specifies some bits in a field is sorted
1471 as if the wildcarded bits were zero. For example,
1472 --sort=nw_src would sort a flow that specifies
1473 nw_src=192.168.0.0/24 the same as nw_src=192.168.0.0.
1474 These options currently affect only dump-flows output.
1476 Daemon Options
1478 The following options are valid on POSIX based platforms.
1479 --pidfile[=pidfile]
1481 Causes a file (by default, ovs-ofctl.pid) to be created indicat‐
1482 ing the PID of the running process. If the pidfile argument is
1483 not specified, or if it does not begin with /, then it is cre‐
1484 ated in /var/run/openvswitch.
1485 If --pidfile is not specified, no pidfile is created.
1487 --overwrite-pidfile
1489 By default, when --pidfile is specified and the specified pid‐
1490 file already exists and is locked by a running process,
1491 ovs-ofctl refuses to start. Specify --overwrite-pidfile to
1492 cause it to instead overwrite the pidfile.
1493 When --pidfile is not specified, this option has no effect.
1495 --detach
1497 Runs ovs-ofctl as a background process. The process forks, and
1498 in the child it starts a new session, closes the standard file
1499 descriptors (which has the side effect of disabling logging to
1500 the console), and changes its current directory to the root (un‐
1501 less --no-chdir is specified). After the child completes its
1502 initialization, the parent exits. ovs-ofctl detaches only when
1503 executing the monitor or snoop commands.
1504 --monitor
1506 Creates an additional process to monitor the ovs-ofctl daemon.
1507 If the daemon dies due to a signal that indicates a programming
1508 error (SIGABRT, SIGALRM, SIGBUS, SIGFPE, SIGILL, SIGPIPE,
1509 SIGSEGV, SIGXCPU, or SIGXFSZ) then the monitor process starts a
1510 new copy of it. If the daemon dies or exits for another reason,
1511 the monitor process exits.
1512 This option is normally used with --detach, but it also func‐
1514 tions without it.
1515 --no-chdir
1517 By default, when --detach is specified, ovs-ofctl changes its
1518 current working directory to the root directory after it de‐
1519 taches. Otherwise, invoking ovs-ofctl from a carelessly chosen
1520 directory would prevent the administrator from unmounting the
1521 file system that holds that directory.
1522 Specifying --no-chdir suppresses this behavior, preventing
1524 ovs-ofctl from changing its current working directory. This may
1525 be useful for collecting core files, since it is common behavior
1526 to write core dumps into the current working directory and the
1527 root directory is not a good directory to use.
1528 This option has no effect when --detach is not specified.
1530 --no-self-confinement
1532 By default daemon will try to self-confine itself to work with
1533 files under well-known directories determined during build. It
1534 is better to stick with this default behavior and not to use
1535 this flag unless some other Access Control is used to confine
1536 daemon. Note that in contrast to other access control implemen‐
1537 tations that are typically enforced from kernel-space (e.g. DAC
1538 or MAC), self-confinement is imposed from the user-space daemon
1539 itself and hence should not be considered as a full confinement
1540 strategy, but instead should be viewed as an additional layer of
1541 security.
1542 --user Causes ovs-ofctl to run as a different user specified in
1544 "user:group", thus dropping most of the root privileges. Short
1545 forms "user" and ":group" are also allowed, with current user or
1546 group are assumed respectively. Only daemons started by the root
1547 user accepts this argument.
1548 On Linux, daemons will be granted CAP_IPC_LOCK and
1550 CAP_NET_BIND_SERVICES before dropping root privileges. Daemons
1551 that interact with a datapath, such as ovs-vswitchd, will be
1552 granted three additional capabilities, namely CAP_NET_ADMIN,
1553 CAP_NET_BROADCAST and CAP_NET_RAW. The capability change will
1554 apply even if the new user is root.
1555 On Windows, this option is not currently supported. For security
1557 reasons, specifying this option will cause the daemon process
1558 not to start.
1559 --unixctl=socket
1561 Sets the name of the control socket on which ovs-ofctl listens
1562 for runtime management commands (see RUNTIME MANAGEMENT COM‐
1563 MANDS, below). If socket does not begin with /, it is inter‐
1564 preted as relative to /var/run/openvswitch. If --unixctl is not
1565 used at all, the default socket is /var/run/open‐
1566 vswitch/ovs-ofctl.pid.ctl, where pid is ovs-ofctl's process ID.
1567 On Windows a local named pipe is used to listen for runtime man‐
1569 agement commands. A file is created in the absolute path as
1570 pointed by socket or if --unixctl is not used at all, a file is
1571 created as ovs-ofctl.ctl in the configured OVS_RUNDIR directory.
1572 The file exists just to mimic the behavior of a Unix domain
1573 socket.
1574 Specifying none for socket disables the control socket feature.
1576 Public Key Infrastructure Options
1578 -p privkey.pem
1579 --private-key=privkey.pem
1580 Specifies a PEM file containing the private key used as
1581 ovs-ofctl's identity for outgoing SSL connections.
1582 -c cert.pem
1584 --certificate=cert.pem
1585 Specifies a PEM file containing a certificate that certifies the
1586 private key specified on -p or --private-key to be trustworthy.
1587 The certificate must be signed by the certificate authority (CA)
1588 that the peer in SSL connections will use to verify it.
1589 -C cacert.pem
1591 --ca-cert=cacert.pem
1592 Specifies a PEM file containing the CA certificate that
1593 ovs-ofctl should use to verify certificates presented to it by
1594 SSL peers. (This may be the same certificate that SSL peers use
1595 to verify the certificate specified on -c or --certificate, or
1596 it may be a different one, depending on the PKI design in use.)
1597 -C none
1599 --ca-cert=none
1600 Disables verification of certificates presented by SSL peers.
1601 This introduces a security risk, because it means that certifi‐
1602 cates cannot be verified to be those of known trusted hosts.
1603 -v[spec]
1605 --verbose=[spec]
1606 Sets logging levels. Without any spec, sets the log level for
1607 every module and destination to dbg. Otherwise, spec is a list
1608 of words separated by spaces or commas or colons, up to one from
1609 each category below:
1610 • A valid module name, as displayed by the vlog/list com‐
1612 mand on ovs-appctl(8), limits the log level change to the
1613 specified module.
1614 • syslog, console, or file, to limit the log level change
1616 to only to the system log, to the console, or to a file,
1617 respectively. (If --detach is specified, ovs-ofctl
1618 closes its standard file descriptors, so logging to the
1619 console will have no effect.)
1620 On Windows platform, syslog is accepted as a word and is
1622 only useful along with the --syslog-target option (the
1623 word has no effect otherwise).
1624 • off, emer, err, warn, info, or dbg, to control the log
1626 level. Messages of the given severity or higher will be
1627 logged, and messages of lower severity will be filtered
1628 out. off filters out all messages. See ovs-appctl(8)
1629 for a definition of each log level.
1630 Case is not significant within spec.
1632 Regardless of the log levels set for file, logging to a file
1634 will not take place unless --log-file is also specified (see be‐
1635 low).
1636 For compatibility with older versions of OVS, any is accepted as
1638 a word but has no effect.
1639 -v
1641 --verbose
1642 Sets the maximum logging verbosity level, equivalent to --ver‐
1643 bose=dbg.
1644 -vPATTERN:destination:pattern
1646 --verbose=PATTERN:destination:pattern
1647 Sets the log pattern for destination to pattern. Refer to
1648 ovs-appctl(8) for a description of the valid syntax for pattern.
1649 -vFACILITY:facility
1651 --verbose=FACILITY:facility
1652 Sets the RFC5424 facility of the log message. facility can be
1653 one of kern, user, mail, daemon, auth, syslog, lpr, news, uucp,
1654 clock, ftp, ntp, audit, alert, clock2, local0, local1, local2,
1655 local3, local4, local5, local6 or local7. If this option is not
1656 specified, daemon is used as the default for the local system
1657 syslog and local0 is used while sending a message to the target
1658 provided via the --syslog-target option.
1659 --log-file[=file]
1661 Enables logging to a file. If file is specified, then it is
1662 used as the exact name for the log file. The default log file
1663 name used if file is omitted is /var/log/open‐
1664 vswitch/ovs-ofctl.log.
1665 --syslog-target=host:port
1667 Send syslog messages to UDP port on host, in addition to the
1668 system syslog. The host must be a numerical IP address, not a
1669 hostname.
1670 --syslog-method=method
1672 Specify method how syslog messages should be sent to syslog dae‐
1673 mon. Following forms are supported:
1674 • libc, use libc syslog() function. Downside of using this
1676 options is that libc adds fixed prefix to every message
1677 before it is actually sent to the syslog daemon over
1678 /dev/log UNIX domain socket.
1679 • unix:file, use UNIX domain socket directly. It is possi‐
1681 ble to specify arbitrary message format with this option.
1682 However, rsyslogd 8.9 and older versions use hard coded
1683 parser function anyway that limits UNIX domain socket
1684 use. If you want to use arbitrary message format with
1685 older rsyslogd versions, then use UDP socket to localhost
1686 IP address instead.
1687 • udp:ip:port, use UDP socket. With this method it is pos‐
1689 sible to use arbitrary message format also with older
1690 rsyslogd. When sending syslog messages over UDP socket
1691 extra precaution needs to be taken into account, for ex‐
1692 ample, syslog daemon needs to be configured to listen on
1693 the specified UDP port, accidental iptables rules could
1694 be interfering with local syslog traffic and there are
1695 some security considerations that apply to UDP sockets,
1696 but do not apply to UNIX domain sockets.
1697 • null, discards all messages logged to syslog.
1699 The default is taken from the OVS_SYSLOG_METHOD environment
1701 variable; if it is unset, the default is libc.
1702 --color[=when]
1704 Colorize the output (for some commands); when can be never, al‐
1705 ways, or auto (the default).
1706 Only some commands support output coloring. Color names and de‐
1708 fault colors may change in future releases.
1709 The environment variable OVS_COLORS can be used to specify user-
1711 defined colors and other attributes used to highlight various
1712 parts of the output. If set, its value is a colon-separated list
1713 of capabilities that defaults to
1714 ac:01;31:dr=34:le=31:pm=36:pr=35:sp=33:vl=32. Supported capabil‐
1715 ities were initially designed for coloring flows from ovs-ofctl
1716 dump-flows switch command, and they are as follows.
1717 ac=01;31
1719 SGR substring for actions= keyword in a flow. The
1720 default is a bold red text foreground.
1721 dr=34 SGR substring for drop keyword. The default is a
1723 dark blue text foreground.
1724 le=31 SGR substring for learn= keyword in a flow. The
1726 default is a red text foreground.
1727 pm=36 SGR substring for flow match attribute names. The
1729 default is a cyan text foreground.
1730 pr=35 SGR substring for keywords in a flow that are fol‐
1732 lowed by arguments inside parenthesis. The de‐
1733 fault is a magenta text foreground.
1734 sp=33 SGR substring for some special keywords in a flow,
1736 notably: table=, priority=, load:, output:, move:,
1737 group:, CONTROLLER:, set_field:, resubmit:, exit.
1738 The default is a yellow text foreground.
1739 vl=32 SGR substring for a lone flow match attribute with
1741 no field name. The default is a green text fore‐
1742 ground.
1743 See the Select Graphic Rendition (SGR) section in the documenta‐
1745 tion of the text terminal that is used for permitted values and
1746 their meaning as character attributes.
1747 -h
1749 --help Prints a brief help message to the console.
1750 -V
1752 --version
1753 Prints version information to the console.
1754
1756 ovs-appctl(8) can send commands to a running ovs-ofctl process. The
1757 supported commands are listed below.
1758 exit Causes ovs-ofctl to gracefully terminate. This command applies
1760 only when executing the monitor or snoop commands.
1761 ofctl/set-output-file file
1763 Causes all subsequent output to go to file instead of stderr.
1764 This command applies only when executing the monitor or snoop
1765 commands.
1766 ofctl/send ofmsg...
1768 Sends each ofmsg, specified as a sequence of hex digits that ex‐
1769 press an OpenFlow message, on the OpenFlow connection. This
1770 command is useful only when executing the monitor command.
1771 ofctl/packet-out packet-out
1773 Sends an OpenFlow PACKET_OUT message specified in Packet-Out
1774 Syntax, on the OpenFlow connection. See Packet-Out Syntax sec‐
1775 tion for more information. This command is useful only when ex‐
1776 ecuting the monitor command.
1777 ofctl/barrier
1779 Sends an OpenFlow barrier request on the OpenFlow connection and
1780 waits for a reply. This command is useful only for the monitor
1781 command.
1782
1784 The following examples assume that ovs-vswitchd has a bridge named br0
1785 configured.
1786 ovs-ofctl dump-tables br0
1788 Prints out the switch's table stats. (This is more interesting
1789 after some traffic has passed through.)
1790 ovs-ofctl dump-flows br0
1792 Prints the flow entries in the switch.
1793 ovs-ofctl add-flow table=0 actions=learn(table=1,hard_timeout=10,
1795 NXM_OF_VLAN_TCI[0..11],output:NXM_OF_IN_PORT[]), resubmit(,1)
1796 ovs-ofctl add-flow table=1 priority=0 actions=flood Implements
1797 a level 2 MAC learning switch using the learn.
1798 ovs-ofctl add-flow br0 'table=0,priority=0 ac‐
1800 tions=load:3->NXM_NX_REG0[0..15],learn(table=0,priority=1,idle_time‐
1801 out=10,NXM_OF_ETH_SRC[],NXM_OF_VLAN_TCI[0..11],out‐
1802 put:NXM_NX_REG0[0..15]),output:2
1803 In this use of a learn action, the first packet from each source
1804 MAC will be sent to port 2. Subsequent packets will be output to
1805 port 3, with an idle timeout of 10 seconds. NXM field names and
1806 match field names are both accepted, e.g. NXM_NX_REG0 or reg0
1807 for the first register, and empty brackets may be omitted.
1808 Additional examples may be found documented as part of related
1810 sections.
1811
1813 ovs-fields(7), ovs-actions(7), ovs-appctl(8), ovs-vswitchd(8),
1814 ovs-vswitchd.conf.db(8)
1815Open vSwitch 2.17.0 ovs-ofctl(8)