1ovs-ofctl(8) Open vSwitch Manual ovs-ofctl(8)
2
6 ovs-ofctl - administer OpenFlow switches
7
9 ovs-ofctl [options] command [switch] [args...]
10
12 The ovs-ofctl program is a command line tool for monitoring and admin‐
13 istering OpenFlow switches. It can also show the current state of an
14 OpenFlow switch, including features, configuration, and table entries.
15 It should work with any OpenFlow switch, not just Open vSwitch.
16 OpenFlow Switch Management Commands
18 These commands allow ovs-ofctl to monitor and administer an OpenFlow
19 switch. It is able to show the current state of a switch, including
20 features, configuration, and table entries.
21 Most of these commands take an argument that specifies the method for
23 connecting to an OpenFlow switch. The following connection methods are
24 supported:
25 ssl:host[:port]
27 tcp:host[:port]
28 The specified port on the given host, which can be
29 expressed either as a DNS name (if built with unbound
30 library) or an IP address in IPv4 or IPv6 address format.
31 Wrap IPv6 addresses in square brackets, e.g.
32 tcp:[::1]:6653. On Linux, use %device to designate a
33 scope for IPv6 link-level addresses, e.g.
34 tcp:[fe80::1234%eth0]:6653. For ssl, the --private-key,
35 --certificate, and --ca-cert options are mandatory.
36 If port is not specified, it defaults to 6653.
38 unix:file
40 On POSIX, a Unix domain server socket named file.
41 On Windows, connect to a local named pipe that is repre‐
43 sented by a file created in the path file to mimic the
44 behavior of a Unix domain socket.
45 file This is short for unix:file, as long as file does not
47 contain a colon.
48 bridge This is short for unix:/var/run/openvswitch/bridge.mgmt,
50 as long as bridge does not contain a colon.
51 [type@]dp
53 Attempts to look up the bridge associated with dp and
54 open as above. If type is given, it specifies the data‐
55 path provider of dp, otherwise the default provider sys‐
56 tem is assumed.
57 show switch
59 Prints to the console information on switch, including informa‐
60 tion on its flow tables and ports.
61 dump-tables switch
63 Prints to the console statistics for each of the flow tables
64 used by switch.
65 dump-table-features switch
67 Prints to the console features for each of the flow tables used
68 by switch.
69 dump-table-desc switch
71 Prints to the console configuration for each of the flow tables
72 used by switch for OpenFlow 1.4+.
73 mod-table switch table setting
75 This command configures flow table settings in switch for Open‐
76 Flow table table, which may be expressed as a number or (unless
77 --no-names is specified) a name.
78 The available settings depend on the OpenFlow version in use.
80 In OpenFlow 1.1 and 1.2 (which must be enabled with the -O
81 option) only, mod-table configures behavior when no flow is
82 found when a packet is looked up in a flow table. The following
83 setting values are available:
84 drop Drop the packet.
86 continue
88 Continue to the next table in the pipeline. (This is how
89 an OpenFlow 1.0 switch always handles packets that do not
90 match any flow, in tables other than the last one.)
91 controller
93 Send to controller. (This is how an OpenFlow 1.0 switch
94 always handles packets that do not match any flow in the
95 last table.)
96 In OpenFlow 1.3 and later (which must be enabled with the -O
98 option) and Open vSwitch 2.11 and later only, mod-table can
99 change 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
109 option) only, mod-table configures the behavior when a con‐
110 troller attempts to add a flow to a flow table that is full.
111 The following 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
119 enabled through the overflow_policy column in the
120 Flow_Table 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
174 receive-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
221 before 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
377 option 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
458 described 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
492 remove_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
501 (defined by <class, type, length>) and NXM fields tun_metadatan, where
502 n 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
505 options. 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
527 rejected.
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 master or a slave (using a
553 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 master controller, it is chosen;
556 otherwise, if there are any controllers that are not masters or
557 slaves, one is chosen arbitrarily; otherwise, a slave controller
558 is chosen arbitrarily. This choice is made once at connection
559 time and does not change as controllers reconfigure their roles.
560 If a switch has no controller configured, or if the configured
562 controller is disconnected, no traffic is sent, so monitoring
563 will not show any traffic.
564 monitor switch [miss-len] [invalid_ttl] [watch:[spec...]]
566 Connects to switch and prints to the console all OpenFlow mes‐
567 sages received. Usually, switch should specify the name of a
568 bridge in the ovs-vswitchd database.
569 If miss-len is provided, ovs-ofctl sends an OpenFlow ``set con‐
571 figuration'' message at connection setup time that requests
572 miss-len bytes of each packet that misses the flow table. Open
573 vSwitch does not send these and other asynchronous messages to
574 an ovs-ofctl monitor client connection unless a nonzero value is
575 specified on this argument. (Thus, if miss-len is not speci‐
576 fied, very little traffic will ordinarily be printed.)
577 If invalid_ttl is passed, ovs-ofctl sends an OpenFlow ``set con‐
579 figuration'' message at connection setup time that requests
580 INVALID_TTL_TO_CONTROLLER, so that ovs-ofctl monitor can receive
581 ``packet-in'' messages when TTL reaches zero on dec_ttl action.
582 Only OpenFlow 1.1 and 1.2 support invalid_ttl; Open vSwitch also
583 implements it for OpenFlow 1.0 as an extension.
584 watch:[spec...] causes ovs-ofctl to send a ``monitor request''
586 Nicira extension message to the switch at connection setup time.
587 This message causes the switch to send information about flow
588 table changes as they occur. The following comma-separated spec
589 syntax is available:
590 !initial
592 Do not report the switch's initial flow table contents.
593 !add Do not report newly added flows.
595 !delete
597 Do not report deleted flows.
598 !modify
600 Do not report modifications to existing flows.
601 !own Abbreviate changes made to the flow table by ovs-ofctl's
603 own connection to the switch. (These could only occur
604 using the ofctl/send command described below under RUN‐
605 TIME MANAGEMENT COMMANDS.)
606 !actions
608 Do not report actions as part of flow updates.
609 table=table
611 Limits the monitoring to the table with the given table,
612 which may be expressed as a number between 0 and 254 or
613 (unless --no-names is specified) a name. By default, all
614 tables are monitored.
615 out_port=port
617 If set, only flows that output to port are monitored.
618 The port may be an OpenFlow port number or keyword (e.g.
619 LOCAL).
620 field=value
622 Monitors only flows that have field specified as the
623 given value. Any syntax valid for matching on dump-flows
624 may be used.
625 This command may be useful for debugging switch or controller
627 implementations. With watch:, it is particularly useful for
628 observing how a controller updates flow tables.
629 OpenFlow Switch and Controller Commands
631 The following commands, like those in the previous section, may be
632 applied to OpenFlow switches, using any of the connection methods
633 described in that section. Unlike those commands, these may also be
634 applied to OpenFlow controllers.
635 probe target
637 Sends a single OpenFlow echo-request message to target and waits
638 for the response. With the -t or --timeout option, this command
639 can test whether an OpenFlow switch or controller is up and run‐
640 ning.
641 ping target [n]
643 Sends a series of 10 echo request packets to target and times
644 each reply. The echo request packets consist of an OpenFlow
645 header plus n bytes (default: 64) of randomly generated payload.
646 This measures the latency of individual requests.
647 benchmark target n count
649 Sends count echo request packets that each consist of an Open‐
650 Flow header plus n bytes of payload and waits for each response.
651 Reports the total time required. This is a measure of the maxi‐
652 mum bandwidth to target for round-trips of n-byte messages.
653 Other Commands
655 ofp-parse file
656 Reads file (or stdin if file is -) as a series of OpenFlow mes‐
657 sages in the binary format used on an OpenFlow connection, and
658 prints them to the console. This can be useful for printing
659 OpenFlow messages captured from a TCP stream.
660 ofp-parse-pcap file [port...]
662 Reads file, which must be in the PCAP format used by network
663 capture tools such as tcpdump or wireshark, extracts all the TCP
664 streams for OpenFlow connections, and prints the OpenFlow mes‐
665 sages in those connections in human-readable format on stdout.
666 OpenFlow connections are distinguished by TCP port number. Non-
668 OpenFlow packets are ignored. By default, data on TCP ports
669 6633 and 6653 are considered to be OpenFlow. Specify one or
670 more port arguments to override the default.
671 This command cannot usefully print SSL encrypted traffic. It
673 does not understand IPv6.
674 Flow Syntax
676 Some ovs-ofctl commands accept an argument that describes a flow or
677 flows. Such flow descriptions comprise a series of field=value assign‐
678 ments, separated by commas or white space. (Embedding spaces into a
679 flow description normally requires quoting to prevent the shell from
680 breaking the description into multiple arguments.)
681 Flow descriptions should be in normal form. This means that a flow may
683 only specify a value for an L3 field if it also specifies a particular
684 L2 protocol, and that a flow may only specify an L4 field if it also
685 specifies particular L2 and L3 protocol types. For example, if the L2
686 protocol type dl_type is wildcarded, then L3 fields nw_src, nw_dst, and
687 nw_proto must also be wildcarded. Similarly, if dl_type or nw_proto
688 (the L3 protocol type) is wildcarded, so must be the L4 fields tcp_dst
689 and tcp_src. ovs-ofctl will warn about flows not in normal form.
690 ovs-fields(7) describes the supported fields and how to match them. In
692 addition to match fields, commands that operate on flows accept a few
693 additional key-value pairs:
694 table=table
696 For flow dump commands, limits the flows dumped to those in ta‐
697 ble, which may be expressed as a number between 0 and 255 or
698 (unless --no-names is specified) a name. If not specified (or
699 if 255 is specified as table), then flows in all tables are
700 dumped.
701 For flow table modification commands, behavior varies based on
703 the OpenFlow version used to connect to the switch:
704 OpenFlow 1.0
706 OpenFlow 1.0 does not support table for modifying flows.
707 ovs-ofctl will exit with an error if table (other than
708 table=255) is specified for a switch that only supports
709 OpenFlow 1.0.
710 In OpenFlow 1.0, the switch chooses the table into which
712 to insert a new flow. The Open vSwitch software switch
713 always chooses table 0. Other Open vSwitch datapaths and
714 other OpenFlow implementations may choose different
715 tables.
716 The OpenFlow 1.0 behavior in Open vSwitch for modifying
718 or removing flows depends on whether --strict is used.
719 Without --strict, the command applies to matching flows
720 in all tables. With --strict, the command will operate
721 on any single matching flow in any table; it will do
722 nothing if there are matches in more than one table.
723 (The distinction between these behaviors only matters if
724 non-OpenFlow 1.0 commands were also used, because Open‐
725 Flow 1.0 alone cannot add flows with the same matching
726 criteria to multiple tables.)
727 OpenFlow 1.0 with table_id extension
729 Open vSwitch implements an OpenFlow extension that allows
730 the controller to specify the table on which to operate.
731 ovs-ofctl automatically enables the extension when table
732 is specified and OpenFlow 1.0 is used. ovs-ofctl auto‐
733 matically detects whether the switch supports the exten‐
734 sion. As of this writing, this extension is only known
735 to be implemented by Open vSwitch.
736 With this extension, ovs-ofctl operates on the requested
738 table when table is specified, and acts as described for
739 OpenFlow 1.0 above when no table is specified (or for ta‐
740 ble=255).
741 OpenFlow 1.1
743 OpenFlow 1.1 requires flow table modification commands to
744 specify a table. When table is not specified (or ta‐
745 ble=255 is specified), ovs-ofctl defaults to table 0.
746 OpenFlow 1.2 and later
748 OpenFlow 1.2 and later allow flow deletion commands, but
749 not other flow table modification commands, to operate on
750 all flow tables, with the behavior described above for
751 OpenFlow 1.0.
752 duration=...
754 n_packet=...
755 n_bytes=...
756 ovs-ofctl ignores assignments to these ``fields'' to allow out‐
757 put from the dump-flows command to be used as input for other
758 commands that parse flows.
759 The add-flow, add-flows, and mod-flows commands require an additional
761 field, which must be the final field specified:
762 actions=[action][,action...]
764 Specifies a comma-separated list of actions to take on a packet
765 when the flow entry matches. If no action is specified, then
766 packets matching the flow are dropped. See ovs-actions(7) for
767 details on the syntax and semantics of actions. K
768 An opaque identifier called a cookie can be used as a handle to iden‐
770 tify a set of flows:
771 cookie=value
773 A cookie can be associated with a flow using the add-flow,
774 add-flows, and mod-flows commands. value can be any 64-bit num‐
775 ber and need not be unique among flows. If this field is omit‐
776 ted, a default cookie value of 0 is used.
777 cookie=value/mask
779 When using NXM, the cookie can be used as a handle for querying,
780 modifying, and deleting flows. value and mask may be supplied
781 for the del-flows, mod-flows, dump-flows, and dump-aggregate
782 commands to limit matching cookies. A 1-bit in mask indicates
783 that the corresponding bit in cookie must match exactly, and a
784 0-bit wildcards that bit. A mask of -1 may be used to exactly
785 match a cookie.
786 The mod-flows command can update the cookies of flows that match
788 a cookie by specifying the cookie field twice (once with a mask
789 for matching and once without to indicate the new value):
790 ovs-ofctl mod-flows br0 cookie=1,actions=normal
792 Change all flows' cookies to 1 and change their actions
793 to normal.
794 ovs-ofctl mod-flows br0 cookie=1/-1,cookie=2,actions=normal
796 Update cookies with a value of 1 to 2 and change their
797 actions to normal.
798 The ability to match on cookies was added in Open vSwitch 1.5.0.
800 The following additional field sets the priority for flows added by the
802 add-flow and add-flows commands. For mod-flows and del-flows when
803 --strict is specified, priority must match along with the rest of the
804 flow specification. For mod-flows without --strict, priority is only
805 significant if the command creates a new flow, that is, non-strict
806 mod-flows does not match on priority and will not change the priority
807 of existing flows. Other commands do not allow priority to be speci‐
808 fied.
809 priority=value
811 The priority at which a wildcarded entry will match in compari‐
812 son to others. value is a number between 0 and 65535, inclu‐
813 sive. A higher value will match before a lower one. An exact-
814 match entry will always have priority over an entry containing
815 wildcards, so it has an implicit priority value of 65535. When
816 adding a flow, if the field is not specified, the flow's prior‐
817 ity will default to 32768.
818 OpenFlow leaves behavior undefined when two or more flows with
820 the same priority can match a single packet. Some users expect
821 ``sensible'' behavior, such as more specific flows taking prece‐
822 dence over less specific flows, but OpenFlow does not specify
823 this and Open vSwitch does not implement it. Users should
824 therefore take care to use priorities to ensure the behavior
825 that they expect.
826 The add-flow, add-flows, and mod-flows commands support the following
828 additional options. These options affect only new flows. Thus, for
829 add-flow and add-flows, these options are always significant, but for
830 mod-flows they are significant only if the command creates a new flow,
831 that is, their values do not update or affect existing flows.
832 idle_timeout=seconds
834 Causes the flow to expire after the given number of seconds of
835 inactivity. A value of 0 (the default) prevents a flow from
836 expiring due to inactivity.
837 hard_timeout=seconds
839 Causes the flow to expire after the given number of seconds,
840 regardless of activity. A value of 0 (the default) gives the
841 flow no hard expiration deadline.
842 importance=value
844 Sets the importance of a flow. The flow entry eviction mecha‐
845 nism can use importance as a factor in deciding which flow to
846 evict. A value of 0 (the default) makes the flow non-evictable
847 on the basis of importance. Specify a value between 0 and
848 65535.
849 Only OpenFlow 1.4 and later support importance.
851 send_flow_rem
853 Marks the flow with a flag that causes the switch to generate a
854 ``flow removed'' message and send it to interested controllers
855 when the flow later expires or is removed.
856 check_overlap
858 Forces the switch to check that the flow match does not overlap
859 that of any different flow with the same priority in the same
860 table. (This check is expensive so it is best to avoid it.)
861 reset_counts
863 When this flag is specified on a flow being added to a switch,
864 and the switch already has a flow with an identical match, an
865 OpenFlow 1.2 (or later) switch resets the flow's packet and byte
866 counters to 0. Without the flag, the packet and byte counters
867 are preserved.
868 OpenFlow 1.0 and 1.1 switches always reset counters in this sit‐
870 uation, as if reset_counts were always specified.
871 Open vSwitch 1.10 added support for reset_counts.
873 no_packet_counts
875 no_byte_counts
876 Adding these flags to a flow advises an OpenFlow 1.3 (or later)
877 switch that the controller does not need packet or byte coun‐
878 ters, respectively, for the flow. Some switch implementations
879 might achieve higher performance or reduce resource consumption
880 when these flags are used. These flags provide no benefit to
881 the Open vSwitch software switch implementation.
882 OpenFlow 1.2 and earlier do not support these flags.
884 Open vSwitch 1.10 added support for no_packet_counts and
886 no_byte_counts.
887 The dump-flows, dump-aggregate, del-flow and del-flows commands support
889 these additional optional fields:
890 out_port=port
892 If set, a matching flow must include an output action to port,
893 which must be an OpenFlow port number or name (e.g. local).
894 out_group=group
896 If set, a matching flow must include an group action naming
897 group, which must be an OpenFlow group number. This field is
898 supported in Open vSwitch 2.5 and later and requires OpenFlow
899 1.1 or later.
900 Table Entry Output
902 The dump-tables and dump-aggregate commands print information about the
903 entries in a datapath's tables. Each line of output is a flow entry as
904 described in Flow Syntax, above, plus some additional fields:
905 duration=secs
907 The time, in seconds, that the entry has been in the table.
908 secs includes as much precision as the switch provides, possibly
909 to nanosecond resolution.
910 n_packets
912 The number of packets that have matched the entry.
913 n_bytes
915 The total number of bytes from packets that have matched the
916 entry.
917 The following additional fields are included only if the switch is Open
919 vSwitch 1.6 or later and the NXM flow format is used to dump the flow
920 (see the description of the --flow-format option below). The values of
921 these additional fields are approximations only and in particular
922 idle_age will sometimes become nonzero even for busy flows.
923 hard_age=secs
925 The integer number of seconds since the flow was added or modi‐
926 fied. hard_age is displayed only if it differs from the integer
927 part of duration. (This is separate from duration because
928 mod-flows restarts the hard_timeout timer without zeroing dura‐
929 tion.)
930 idle_age=secs
932 The integer number of seconds that have passed without any pack‐
933 ets passing through the flow.
934 Packet-Out Syntax
936 ovs-ofctl bundle command accepts packet-outs to be specified in the
937 bundle file. Each packet-out comprises of a series of field=value
938 assignments, separated by commas or white space. (Embedding spaces
939 into a packet-out description normally requires quoting to prevent the
940 shell from breaking the description into multiple arguments.). Unless
941 noted otherwise only the last instance of each field is honoured. This
942 same syntax is also supported by the ovs-ofctl packet-out command.
943 in_port=port
945 The port number to be considered the in_port when processing
946 actions. This can be any valid OpenFlow port number, or any of
947 the LOCAL, CONTROLLER, or NONE. This field is required.
948 pipeline_field=value
951 Optionally, user can specify a list of pipeline fields for a
952 packet-out message. The supported pipeline fields includes tun‐
953 nel fields and register fields as defined in ovs-fields(7).
954 packet=hex-string
957 The actual packet to send, expressed as a string of hexadecimal
958 bytes. This field is required.
959 actions=[action][,action...]
962 The syntax of actions are identical to the actions= field
963 described in Flow Syntax above. Specifying actions= is
964 optional, but omitting actions is interpreted as a drop, so the
965 packet will not be sent anywhere from the switch. actions must
966 be specified at the end of each line, like for flow mods.
967 Group Syntax
969 Some ovs-ofctl commands accept an argument that describes a group or
970 groups. Such flow descriptions comprise a series field=value assign‐
971 ments, separated by commas or white space. (Embedding spaces into a
972 group description normally requires quoting to prevent the shell from
973 breaking the description into multiple arguments.). Unless noted other‐
974 wise only the last instance of each field is honoured.
975 group_id=id
977 The integer group id of group. When this field is specified in
978 del-groups or dump-groups, the keyword "all" may be used to des‐
979 ignate all groups. This field is required.
980 type=type
984 The type of the group. The add-group, add-groups and mod-groups
985 commands require this field. It is prohibited for other com‐
986 mands. The following keywords designated the allowed types:
987 all Execute all buckets in the group.
989 select Execute one bucket in the group, balancing across the
991 buckets according to their weights. To select a bucket,
992 for each live bucket, Open vSwitch hashes flow data with
993 the bucket ID and multiplies by the bucket weight to
994 obtain a ``score,'' and then selects the bucket with the
995 highest score. Use selection_method to control the flow
996 data used for selection.
997 indirect
999 Executes the one bucket in the group.
1000 ff
1002 fast_failover
1003 Executes the first live bucket in the group which is
1004 associated with a live port or group.
1005 command_bucket_id=id
1008 The bucket to operate on. The insert-buckets and remove-buckets
1009 commands require this field. It is prohibited for other com‐
1010 mands. id may be an integer or one of the following keywords:
1011 all Operate on all buckets in the group. Only valid when
1013 used with the remove-buckets command in which case the
1014 effect is to remove all buckets from the group.
1015 first Operate on the first bucket present in the group. In the
1017 case of the insert-buckets command the effect is to
1018 insert new bucets just before the first bucket already
1019 present in the group; or to replace the buckets of the
1020 group if there are no buckets already present in the
1021 group. In the case of the remove-buckets command the
1022 effect is to remove the first bucket of the group; or do
1023 nothing if there are no buckets present in the group.
1024 last Operate on the last bucket present in the group. In the
1026 case of the insert-buckets command the effect is to
1027 insert new bucets just after the last bucket already
1028 present in the group; or to replace the buckets of the
1029 group if there are no buckets already present in the
1030 group. In the case of the remove-buckets command the
1031 effect is to remove the last bucket of the group; or do
1032 nothing if there are no buckets present in the group.
1033 If id is an integer then it should correspond to the bucket_id
1035 of a bucket present in the group. In case of the insert-buckets
1036 command the effect is to insert buckets just before the bucket
1037 in the group whose bucket_id is id. In case of the iremove-
1038 buckets command the effect is to remove the in the group whose
1039 bucket_id is id. It is an error if there is no bucket persent
1040 group in whose bucket_id is id.
1041 selection_method=method
1044 The selection method used to select a bucket for a select group.
1045 This is a string of 1 to 15 bytes in length known to lower lay‐
1046 ers. This field is optional for add-group, add-groups and
1047 mod-group commands on groups of type select. Prohibited other‐
1048 wise. If no selection method is specified, Open vSwitch up to
1049 release 2.9 applies the hash method with default fields. From
1050 2.10 onwards Open vSwitch defaults to the dp_hash method with
1051 symmetric L3/L4 hash algorithm, unless the weighted group buck‐
1052 ets cannot be mapped to a maximum of 64 dp_hash values with suf‐
1053 ficient accuracy. In those rare cases Open vSwitch 2.10 and
1054 later fall back to the hash method with the default set of hash
1055 fields.
1056 dp_hash
1058 Use a datapath computed hash value. The hash algorithm
1059 varies accross different datapath implementations.
1060 dp_hash uses the upper 32 bits of the selec‐
1061 tion_method_param as the datapath hash algorithm selec‐
1062 tor. The supported values are 0 (corresponding to hash
1063 computation over the IP 5-tuple) and 1 (corresponding to
1064 a symmetric hash computation over the IP 5-tuple).
1065 Selecting specific fields with the fields option is not
1066 supported with dp_hash). The lower 32 bits are used as
1067 the hash basis.
1068 Using dp_hash has the advantage that it does not require
1070 the generated datapath flows to exact match any addi‐
1071 tional packet header fields. For example, even if multi‐
1072 ple TCP connections thus hashed to different select group
1073 buckets have different source port numbers, generally all
1074 of them would be handled with a small set of already
1075 established datapath flows, resulting in less latency for
1076 TCP SYN packets. The downside is that the shared data‐
1077 path flows must match each packet twice, as the datapath
1078 hash value calculation happens only when needed, and a
1079 second match is required to match some bits of its value.
1080 This double-matching incurs a small additional latency
1081 cost for each packet, but this latency is orders of mag‐
1082 nitude less than the latency of creating new datapath
1083 flows for new TCP connections.
1084 hash Use a hash computed over the fields specified with the
1086 fields option, see below. If no hash fields are speci‐
1087 fied, hash defaults to a symmetric hash over the combina‐
1088 tion of MAC addresses, VLAN tags, Ether type, IP
1089 addresses and L4 port numbers. hash uses the selec‐
1090 tion_method_param as the hash basis.
1091 Note that the hashed fields become exact matched by the
1093 datapath flows. For example, if the TCP source port is
1094 hashed, the created datapath flows will match the spe‐
1095 cific TCP source port value present in the packet
1096 received. Since each TCP connection generally has a dif‐
1097 ferent source port value, a separate datapath flow will
1098 be need to be inserted for each TCP connection thus
1099 hashed to a select group bucket.
1100 This option uses a Netronome OpenFlow extension which is only
1102 supported when using Open vSwitch 2.4 and later with OpenFlow
1103 1.5 and later.
1104 selection_method_param=param
1107 64-bit integer parameter to the selection method selected by the
1108 selection_method field. The parameter's use is defined by the
1109 lower-layer that implements the selection_method. It is
1110 optional if the selection_method field is specified as a non-
1111 empty string. Prohibited otherwise. The default value is zero.
1112 This option uses a Netronome OpenFlow extension which is only
1114 supported when using Open vSwitch 2.4 and later with OpenFlow
1115 1.5 and later.
1116 fields=field
1119 fields(field[=mask]...)
1120 The field parameters to selection method selected by the selec‐
1121 tion_method field. The syntax is described in Flow Syntax with
1122 the additional restrictions that if a value is provided it is
1123 treated as a wildcard mask and wildcard masks following a slash
1124 are prohibited. The pre-requisites of fields must be provided by
1125 any flows that output to the group. The use of the fields is
1126 defined by the lower-layer that implements the selection_method.
1127 They are optional if the selection_method field is specified as
1128 ``hash', prohibited otherwise. The default is no fields.
1129 This option will use a Netronome OpenFlow extension which is
1131 only supported when using Open vSwitch 2.4 and later with Open‐
1132 Flow 1.5 and later.
1133 bucket=bucket_parameters
1136 The add-group, add-groups and mod-group commands require at
1137 least one bucket field. Bucket fields must appear after all
1138 other fields. Multiple bucket fields to specify multiple buck‐
1139 ets. The order in which buckets are specified corresponds to
1140 their order in the group. If the type of the group is "indirect"
1141 then only one group may be specified. bucket_parameters con‐
1142 sists of a list of field=value assignments, separated by commas
1143 or white space followed by a comma-separated list of actions.
1144 The fields for bucket_parameters are:
1145 bucket_id=id
1147 The 32-bit integer group id of the bucket. Values
1148 greater than 0xffffff00 are reserved. This field was
1149 added in Open vSwitch 2.4 to conform with the OpenFlow
1150 1.5 specification. It is not supported when earlier ver‐
1151 sions of OpenFlow are used. Open vSwitch will automati‐
1152 cally allocate bucket ids when they are not specified.
1153 actions=[action][,action...]
1155 The syntax of actions are identical to the actions= field
1156 described in Flow Syntax above. Specifying actions= is
1157 optional, any unknown bucket parameter will be inter‐
1158 preted as an action.
1159 weight=value
1161 The relative weight of the bucket as an integer. This may
1162 be used by the switch during bucket select for groups
1163 whose type is select.
1164 watch_port=port
1166 Port used to determine liveness of group. This or the
1167 watch_group field is required for groups whose type is ff
1168 or fast_failover. This or the watch_group field can also
1169 be used for groups whose type is select.
1170 watch_group=group_id
1172 Group identifier of group used to determine liveness of
1173 group. This or the watch_port field is required for
1174 groups whose type is ff or fast_failover. This or the
1175 watch_port field can also be used for groups whose type
1176 is select.
1177 Meter Syntax
1179 The meter table commands accept an argument that describes a meter.
1180 Such meter descriptions comprise a series field=value assignments, sep‐
1181 arated by commas or white space. (Embedding spaces into a group
1182 description normally requires quoting to prevent the shell from break‐
1183 ing the description into multiple arguments.). Unless noted otherwise
1184 only the last instance of each field is honoured.
1185 meter=id
1187 The identifier for the meter. An integer is used to specify a
1188 user-defined meter. In addition, the keywords "all", "con‐
1189 troller", and "slowpath", are also supported as virtual meters.
1190 The "controller" and "slowpath" virtual meters apply to packets
1191 sent to the controller and to the OVS userspace, respectively.
1192 When this field is specified in del-meter, dump-meter, or meter-
1194 stats, the keyword "all" may be used to designate all meters.
1195 This field is required, except for meter-stats, which dumps all
1196 stats when this field is not specified.
1197 kbps
1199 pktps The unit for the rate and burst_size band parameters. kbps
1200 specifies kilobits per second, and pktps specifies packets per
1201 second. A unit is required for the add-meter and mod-meter com‐
1202 mands.
1203 burst If set, enables burst support for meter bands through the
1206 burst_size parameter.
1207 stats If set, enables the collection of meter and band statistics.
1210 bands=band_parameters
1213 The add-meter and mod-meter commands require at least one band
1214 specification. Bands must appear after all other fields.
1215 type=type
1217 The type of the meter band. This keyword starts a new
1218 band specification. Each band specifies a rate above
1219 which the band is to take some action. The action depends
1220 on the band type. If multiple bands' rate is exceeded,
1221 then the band with the highest rate among the exceeded
1222 bands is selected. The following keywords designate the
1223 allowed meter band types:
1224 drop Drop packets exceeding the band's rate limit.
1226 The other band_parameters are:
1228 rate=value
1230 The relative rate limit for this band, in kilobits per
1231 second or packets per second, depending on whether kbps
1232 or pktps was specified.
1233 burst_size=size
1235 If burst is specified for the meter entry, configures the
1236 maximum burst allowed for the band in kilobits or pack‐
1237 ets, depending on whether kbps or pktps was specified.
1238 If unspecified, the switch is free to select some reason‐
1239 able value depending on its configuration.
1240
1242 --strict
1243 Uses strict matching when running flow modification commands.
1244 --names
1246 --no-names
1247 Every OpenFlow port has a name and a number, and every OpenFlow
1248 flow table has a number and sometimes a name. By default,
1249 ovs-ofctl commands accept both port and table names and numbers,
1250 and they display port and table names if ovs-ofctl is running on
1251 an interactive console, numbers otherwise. With --names,
1252 ovs-ofctl commands both accept and display port and table names;
1253 with --no-names, commands neither accept nor display port and
1254 table names.
1255 If a port or table name contains special characters or might be
1257 confused with a keyword within a flow, it may be enclosed in
1258 double quotes (escaped from the shell). If necessary, JSON-
1259 style escape sequences may be used inside quotes, as specified
1260 in RFC 7159. When it displays port and table names, ovs-ofctl
1261 quotes any name that does not start with a letter followed by
1262 letters or digits.
1263 Open vSwitch added support for port names and these options.
1265 Open vSwitch 2.10 added support for table names. Earlier ver‐
1266 sions always behaved as if --no-names were specified.
1267 Open vSwitch does not place its own limit on the length of port
1269 names, but OpenFlow limits port names to 15 bytes. Because
1270 ovs-ofctl uses OpenFlow to retrieve the mapping between port
1271 names and numbers, names longer than this limit will be trun‐
1272 cated for both display and acceptance. Truncation can also
1273 cause long names that are different to appear to be the same;
1274 when a switch has two ports with the same (truncated) name,
1275 ovs-ofctl refuses to display or accept the name, using the num‐
1276 ber instead.
1277 OpenFlow and Open vSwitch limit table names to 32 bytes.
1279 --stats
1281 --no-stats
1282 The dump-flows command by default, or with --stats, includes
1283 flow duration, packet and byte counts, and idle and hard age in
1284 its output. With --no-stats, it omits all of these, as well as
1285 cookie values and table IDs if they are zero.
1286 --read-only
1288 Do not execute read/write commands.
1289 --bundle
1291 Execute flow mods as an OpenFlow 1.4 atomic bundle transaction.
1292 · Within a bundle, all flow mods are processed in the order
1294 they appear and as a single atomic transaction, meaning
1295 that if one of them fails, the whole transaction fails
1296 and none of the changes are made to the switch's flow ta‐
1297 ble, and that each given datapath packet traversing the
1298 OpenFlow tables sees the flow tables either as before the
1299 transaction, or after all the flow mods in the bundle
1300 have been successfully applied.
1301 · The beginning and the end of the flow table modification
1303 commands in a bundle are delimited with OpenFlow 1.4 bun‐
1304 dle control messages, which makes it possible to stream
1305 the included commands without explicit OpenFlow barriers,
1306 which are otherwise used after each flow table modifica‐
1307 tion command. This may make large modifications execute
1308 faster as a bundle.
1309 · Bundles require OpenFlow 1.4 or higher. An explicit -O
1311 OpenFlow14 option is not needed, but you may need to
1312 enable OpenFlow 1.4 support for OVS by setting the OVSDB
1313 protocols column in the bridge table.
1314 -O [version[,version]...]
1316 --protocols=[version[,version]...]
1317 Sets the OpenFlow protocol versions that are allowed when estab‐
1318 lishing an OpenFlow session.
1319 These protocol versions are enabled by default:
1321 · OpenFlow10, for OpenFlow 1.0.
1323 The following protocol versions are generally supported, but for com‐
1324 patibility with older versions of Open vSwitch they are not enabled by
1325 default:
1326 · OpenFlow11, for OpenFlow 1.1.
1328 · OpenFlow12, for OpenFlow 1.2.
1330 · OpenFlow13, for OpenFlow 1.3.
1332 · OpenFlow14, for OpenFlow 1.4.
1334 · OpenFlow15, for OpenFlow 1.5.
1336 -F format[,format...]
1338 --flow-format=format[,format...]
1339 ovs-ofctl supports the following individual flow formats, any
1340 number of which may be listed as format:
1341 OpenFlow10-table_id
1343 This is the standard OpenFlow 1.0 flow format. All Open‐
1344 Flow switches and all versions of Open vSwitch support
1345 this flow format.
1346 OpenFlow10+table_id
1348 This is the standard OpenFlow 1.0 flow format plus a
1349 Nicira extension that allows ovs-ofctl to specify the
1350 flow table in which a particular flow should be placed.
1351 Open vSwitch 1.2 and later supports this flow format.
1352 NXM-table_id (Nicira Extended Match)
1354 This Nicira extension to OpenFlow is flexible and exten‐
1355 sible. It supports all of the Nicira flow extensions,
1356 such as tun_id and registers. Open vSwitch 1.1 and later
1357 supports this flow format.
1358 NXM+table_id (Nicira Extended Match)
1360 This combines Nicira Extended match with the ability to
1361 place a flow in a specific table. Open vSwitch 1.2 and
1362 later supports this flow format.
1363 OXM-OpenFlow12
1365 OXM-OpenFlow13
1366 OXM-OpenFlow14
1367 OXM-OpenFlow15
1368 These are the standard OXM (OpenFlow Extensible Match)
1369 flow format in OpenFlow 1.2 and later.
1370 ovs-ofctl also supports the following abbreviations for collec‐
1372 tions of flow formats:
1373 any Any supported flow format.
1375 OpenFlow10
1377 OpenFlow10-table_id or OpenFlow10+table_id.
1378 NXM NXM-table_id or NXM+table_id.
1380 OXM OXM-OpenFlow12, OXM-OpenFlow13, or OXM-OpenFlow14.
1382 For commands that modify the flow table, ovs-ofctl by default
1384 negotiates the most widely supported flow format that supports
1385 the flows being added. For commands that query the flow table,
1386 ovs-ofctl by default uses the most advanced format supported by
1387 the switch.
1388 This option, where format is a comma-separated list of one or
1390 more of the formats listed above, limits ovs-ofctl's choice of
1391 flow format. If a command cannot work as requested using one of
1392 the specified flow formats, ovs-ofctl will report a fatal error.
1393 -P format
1395 --packet-in-format=format
1396 ovs-ofctl supports the following ``packet-in'' formats, in order
1397 of increasing capability:
1398 standard
1400 This uses the OFPT_PACKET_IN message, the standard
1401 ``packet-in'' message for any given OpenFlow version.
1402 Every OpenFlow switch that supports a given OpenFlow ver‐
1403 sion supports this format.
1404 nxt_packet_in
1406 This uses the NXT_PACKET_IN message, which adds many of
1407 the capabilities of the OpenFlow 1.1 and later ``packet-
1408 in'' messages before those OpenFlow versions were avail‐
1409 able in Open vSwitch. Open vSwitch 1.1 and later support
1410 this format. Only Open vSwitch 2.6 and later, however,
1411 support it for OpenFlow 1.1 and later (but there is lit‐
1412 tle reason to use it with those versions of OpenFlow).
1413 nxt_packet_in2
1415 This uses the NXT_PACKET_IN2 message, which is extensible
1416 and should avoid the need to define new formats later.
1417 In particular, this format supports passing arbitrary
1418 user-provided data to a controller using the userdata
1419 option on the controller action. Open vSwitch 2.6 and
1420 later support this format.
1421 Without this option, ovs-ofctl prefers nxt_packet_in2 if the
1423 switch supports it. Otherwise, if OpenFlow 1.0 is in use,
1424 ovs-ofctl prefers nxt_packet_in if the switch supports it. Oth‐
1425 erwise, ovs-ofctl falls back to the standard packet-in format.
1426 When this option is specified, ovs-ofctl insists on the selected
1427 format. If the switch does not support the requested format,
1428 ovs-ofctl will report a fatal error.
1429 Before version 2.6, Open vSwitch called standard format open‐
1431 flow10 and nxt_packet_in format nxm, and ovs-ofctl still accepts
1432 these names as synonyms. (The name openflow10 was a misnomer
1433 because this format actually varies from one OpenFlow version to
1434 another; it is not consistently OpenFlow 1.0 format. Similarly,
1435 when nxt_packet_in2 was introduced, the name nxm became confus‐
1436 ing because it also uses OXM/NXM.)
1437 This option affects only the monitor command.
1439 --timestamp
1441 Print a timestamp before each received packet. This option only
1442 affects the monitor, snoop, and ofp-parse-pcap commands.
1443 -m
1445 --more Increases the verbosity of OpenFlow messages printed and logged
1446 by ovs-ofctl commands. Specify this option more than once to
1447 increase verbosity further.
1448 --sort[=field]
1450 --rsort[=field]
1451 Display output sorted by flow field in ascending (--sort) or
1452 descending (--rsort) order, where field is any of the fields
1453 that are allowed for matching or priority to sort by priority.
1454 When field is omitted, the output is sorted by priority. Spec‐
1455 ify these options multiple times to sort by multiple fields.
1456 Any given flow will not necessarily specify a value for a given
1458 field. This requires special treatement:
1459 · A flow that does not specify any part of a field that is
1461 used for sorting is sorted after all the flows that do
1462 specify the field. For example, --sort=tcp_src will sort
1463 all the flows that specify a TCP source port in ascending
1464 order, followed by the flows that do not specify a TCP
1465 source port at all.
1466 · A flow that only specifies some bits in a field is sorted
1468 as if the wildcarded bits were zero. For example,
1469 --sort=nw_src would sort a flow that specifies
1470 nw_src=192.168.0.0/24 the same as nw_src=192.168.0.0.
1471 These options currently affect only dump-flows output.
1473 Daemon Options
1475 The following options are valid on POSIX based platforms.
1476 --pidfile[=pidfile]
1478 Causes a file (by default, ovs-ofctl.pid) to be created indicat‐
1479 ing the PID of the running process. If the pidfile argument is
1480 not specified, or if it does not begin with /, then it is cre‐
1481 ated in /var/run/openvswitch.
1482 If --pidfile is not specified, no pidfile is created.
1484 --overwrite-pidfile
1486 By default, when --pidfile is specified and the specified pid‐
1487 file already exists and is locked by a running process,
1488 ovs-ofctl refuses to start. Specify --overwrite-pidfile to
1489 cause it to instead overwrite the pidfile.
1490 When --pidfile is not specified, this option has no effect.
1492 --detach
1494 Runs ovs-ofctl as a background process. The process forks, and
1495 in the child it starts a new session, closes the standard file
1496 descriptors (which has the side effect of disabling logging to
1497 the console), and changes its current directory to the root
1498 (unless --no-chdir is specified). After the child completes its
1499 initialization, the parent exits. ovs-ofctl detaches only when
1500 executing the monitor or snoop commands.
1501 --monitor
1503 Creates an additional process to monitor the ovs-ofctl daemon.
1504 If the daemon dies due to a signal that indicates a programming
1505 error (SIGABRT, SIGALRM, SIGBUS, SIGFPE, SIGILL, SIGPIPE,
1506 SIGSEGV, SIGXCPU, or SIGXFSZ) then the monitor process starts a
1507 new copy of it. If the daemon dies or exits for another reason,
1508 the monitor process exits.
1509 This option is normally used with --detach, but it also func‐
1511 tions without it.
1512 --no-chdir
1514 By default, when --detach is specified, ovs-ofctl changes its
1515 current working directory to the root directory after it
1516 detaches. Otherwise, invoking ovs-ofctl from a carelessly cho‐
1517 sen directory would prevent the administrator from unmounting
1518 the file system that holds that directory.
1519 Specifying --no-chdir suppresses this behavior, preventing
1521 ovs-ofctl from changing its current working directory. This may
1522 be useful for collecting core files, since it is common behavior
1523 to write core dumps into the current working directory and the
1524 root directory is not a good directory to use.
1525 This option has no effect when --detach is not specified.
1527 --no-self-confinement
1529 By default daemon will try to self-confine itself to work with
1530 files under well-know, at build-time whitelisted directories.
1531 It is better to stick with this default behavior and not to use
1532 this flag unless some other Access Control is used to confine
1533 daemon. Note that in contrast to other access control implemen‐
1534 tations that are typically enforced from kernel-space (e.g. DAC
1535 or MAC), self-confinement is imposed from the user-space daemon
1536 itself and hence should not be considered as a full confinement
1537 strategy, but instead should be viewed as an additional layer of
1538 security.
1539 --user Causes ovs-ofctl to run as a different user specified in
1541 "user:group", thus dropping most of the root privileges. Short
1542 forms "user" and ":group" are also allowed, with current user or
1543 group are assumed respectively. Only daemons started by the root
1544 user accepts this argument.
1545 On Linux, daemons will be granted CAP_IPC_LOCK and
1547 CAP_NET_BIND_SERVICES before dropping root privileges. Daemons
1548 that interact with a datapath, such as ovs-vswitchd, will be
1549 granted three additional capabilities, namely CAP_NET_ADMIN,
1550 CAP_NET_BROADCAST and CAP_NET_RAW. The capability change will
1551 apply even if the new user is root.
1552 On Windows, this option is not currently supported. For security
1554 reasons, specifying this option will cause the daemon process
1555 not to start.
1556 --unixctl=socket
1558 Sets the name of the control socket on which ovs-ofctl listens
1559 for runtime management commands (see RUNTIME MANAGEMENT COM‐
1560 MANDS, below). If socket does not begin with /, it is inter‐
1561 preted as relative to /var/run/openvswitch. If --unixctl is not
1562 used at all, the default socket is /var/run/open‐
1563 vswitch/ovs-ofctl.pid.ctl, where pid is ovs-ofctl's process ID.
1564 On Windows a local named pipe is used to listen for runtime man‐
1566 agement commands. A file is created in the absolute path as
1567 pointed by socket or if --unixctl is not used at all, a file is
1568 created as ovs-ofctl.ctl in the configured OVS_RUNDIR directory.
1569 The file exists just to mimic the behavior of a Unix domain
1570 socket.
1571 Specifying none for socket disables the control socket feature.
1573 Public Key Infrastructure Options
1575 -p privkey.pem
1576 --private-key=privkey.pem
1577 Specifies a PEM file containing the private key used as
1578 ovs-ofctl's identity for outgoing SSL connections.
1579 -c cert.pem
1581 --certificate=cert.pem
1582 Specifies a PEM file containing a certificate that certifies the
1583 private key specified on -p or --private-key to be trustworthy.
1584 The certificate must be signed by the certificate authority (CA)
1585 that the peer in SSL connections will use to verify it.
1586 -C cacert.pem
1588 --ca-cert=cacert.pem
1589 Specifies a PEM file containing the CA certificate that
1590 ovs-ofctl should use to verify certificates presented to it by
1591 SSL peers. (This may be the same certificate that SSL peers use
1592 to verify the certificate specified on -c or --certificate, or
1593 it may be a different one, depending on the PKI design in use.)
1594 -C none
1596 --ca-cert=none
1597 Disables verification of certificates presented by SSL peers.
1598 This introduces a security risk, because it means that certifi‐
1599 cates cannot be verified to be those of known trusted hosts.
1600 -v[spec]
1602 --verbose=[spec]
1603 Sets logging levels. Without any spec, sets the log level for
1604 every module and destination to dbg. Otherwise, spec is a list
1605 of words separated by spaces or commas or colons, up to one from
1606 each category below:
1607 · A valid module name, as displayed by the vlog/list com‐
1609 mand on ovs-appctl(8), limits the log level change to the
1610 specified module.
1611 · syslog, console, or file, to limit the log level change
1613 to only to the system log, to the console, or to a file,
1614 respectively. (If --detach is specified, ovs-ofctl
1615 closes its standard file descriptors, so logging to the
1616 console will have no effect.)
1617 On Windows platform, syslog is accepted as a word and is
1619 only useful along with the --syslog-target option (the
1620 word has no effect otherwise).
1621 · off, emer, err, warn, info, or dbg, to control the log
1623 level. Messages of the given severity or higher will be
1624 logged, and messages of lower severity will be filtered
1625 out. off filters out all messages. See ovs-appctl(8)
1626 for a definition of each log level.
1627 Case is not significant within spec.
1629 Regardless of the log levels set for file, logging to a file
1631 will not take place unless --log-file is also specified (see
1632 below).
1633 For compatibility with older versions of OVS, any is accepted as
1635 a word but has no effect.
1636 -v
1638 --verbose
1639 Sets the maximum logging verbosity level, equivalent to --ver‐
1640 bose=dbg.
1641 -vPATTERN:destination:pattern
1643 --verbose=PATTERN:destination:pattern
1644 Sets the log pattern for destination to pattern. Refer to
1645 ovs-appctl(8) for a description of the valid syntax for pattern.
1646 -vFACILITY:facility
1648 --verbose=FACILITY:facility
1649 Sets the RFC5424 facility of the log message. facility can be
1650 one of kern, user, mail, daemon, auth, syslog, lpr, news, uucp,
1651 clock, ftp, ntp, audit, alert, clock2, local0, local1, local2,
1652 local3, local4, local5, local6 or local7. If this option is not
1653 specified, daemon is used as the default for the local system
1654 syslog and local0 is used while sending a message to the target
1655 provided via the --syslog-target option.
1656 --log-file[=file]
1658 Enables logging to a file. If file is specified, then it is
1659 used as the exact name for the log file. The default log file
1660 name used if file is omitted is /var/log/open‐
1661 vswitch/ovs-ofctl.log.
1662 --syslog-target=host:port
1664 Send syslog messages to UDP port on host, in addition to the
1665 system syslog. The host must be a numerical IP address, not a
1666 hostname.
1667 --syslog-method=method
1669 Specify method how syslog messages should be sent to syslog dae‐
1670 mon. Following forms are supported:
1671 · libc, use libc syslog() function. Downside of using this
1673 options is that libc adds fixed prefix to every message
1674 before it is actually sent to the syslog daemon over
1675 /dev/log UNIX domain socket.
1676 · unix:file, use UNIX domain socket directly. It is possi‐
1678 ble to specify arbitrary message format with this option.
1679 However, rsyslogd 8.9 and older versions use hard coded
1680 parser function anyway that limits UNIX domain socket
1681 use. If you want to use arbitrary message format with
1682 older rsyslogd versions, then use UDP socket to localhost
1683 IP address instead.
1684 · udp:ip:port, use UDP socket. With this method it is pos‐
1686 sible to use arbitrary message format also with older
1687 rsyslogd. When sending syslog messages over UDP socket
1688 extra precaution needs to be taken into account, for
1689 example, syslog daemon needs to be configured to listen
1690 on the specified UDP port, accidental iptables rules
1691 could be interfering with local syslog traffic and there
1692 are some security considerations that apply to UDP sock‐
1693 ets, but do not apply to UNIX domain sockets.
1694 · null, discards all messages logged to syslog.
1696 The default is taken from the OVS_SYSLOG_METHOD environment
1698 variable; if it is unset, the default is libc.
1699 --color[=when]
1701 Colorize the output (for some commands); when can be never,
1702 always, or auto (the default).
1703 Only some commands support output coloring. Color names and
1705 default colors may change in future releases.
1706 The environment variable OVS_COLORS can be used to specify user-
1708 defined colors and other attributes used to highlight various
1709 parts of the output. If set, its value is a colon-separated list
1710 of capabilities that defaults to
1711 ac:01;31:dr=34:le=31:pm=36:pr=35:sp=33:vl=32. Supported capabil‐
1712 ities were initially designed for coloring flows from ovs-ofctl
1713 dump-flows switch command, and they are as follows.
1714 ac=01;31
1716 SGR substring for actions= keyword in a flow. The
1717 default is a bold red text foreground.
1718 dr=34 SGR substring for drop keyword. The default is a
1720 dark blue text foreground.
1721 le=31 SGR substring for learn= keyword in a flow. The
1723 default is a red text foreground.
1724 pm=36 SGR substring for flow match attribute names. The
1726 default is a cyan text foreground.
1727 pr=35 SGR substring for keywords in a flow that are fol‐
1729 lowed by arguments inside parenthesis. The
1730 default is a magenta text foreground.
1731 sp=33 SGR substring for some special keywords in a flow,
1733 notably: table=, priority=, load:, output:, move:,
1734 group:, CONTROLLER:, set_field:, resubmit:, exit.
1735 The default is a yellow text foreground.
1736 vl=32 SGR substring for a lone flow match attribute with
1738 no field name. The default is a green text fore‐
1739 ground.
1740 See the Select Graphic Rendition (SGR) section in the documenta‐
1742 tion of the text terminal that is used for permitted values and
1743 their meaning as character attributes.
1744 -h
1746 --help Prints a brief help message to the console.
1747 -V
1749 --version
1750 Prints version information to the console.
1751
1753 ovs-appctl(8) can send commands to a running ovs-ofctl process. The
1754 supported commands are listed below.
1755 exit Causes ovs-ofctl to gracefully terminate. This command applies
1757 only when executing the monitor or snoop commands.
1758 ofctl/set-output-file file
1760 Causes all subsequent output to go to file instead of stderr.
1761 This command applies only when executing the monitor or snoop
1762 commands.
1763 ofctl/send ofmsg...
1765 Sends each ofmsg, specified as a sequence of hex digits that
1766 express an OpenFlow message, on the OpenFlow connection. This
1767 command is useful only when executing the monitor command.
1768 ofctl/packet-out packet-out
1770 Sends an OpenFlow PACKET_OUT message specified in Packet-Out
1771 Syntax, on the OpenFlow connection. See Packet-Out Syntax sec‐
1772 tion for more information. This command is useful only when
1773 executing the monitor command.
1774 ofctl/barrier
1776 Sends an OpenFlow barrier request on the OpenFlow connection and
1777 waits for a reply. This command is useful only for the monitor
1778 command.
1779
1781 The following examples assume that ovs-vswitchd has a bridge named br0
1782 configured.
1783 ovs-ofctl dump-tables br0
1785 Prints out the switch's table stats. (This is more interesting
1786 after some traffic has passed through.)
1787 ovs-ofctl dump-flows br0
1789 Prints the flow entries in the switch.
1790 ovs-ofctl add-flow table=0 actions=learn(table=1,hard_timeout=10,
1792 NXM_OF_VLAN_TCI[0..11],output:NXM_OF_IN_PORT[]), resubmit(,1)
1793 ovs-ofctl add-flow table=1 priority=0 actions=flood Implements
1794 a level 2 MAC learning switch using the learn.
1795 ovs-ofctl add-flow br0 'table=0,priority=0
1797 actions=load:3->NXM_NX_REG0[0..15],learn(table=0,priority=1,idle_time‐
1798 out=10,NXM_OF_ETH_SRC[],NXM_OF_VLAN_TCI[0..11],out‐
1799 put:NXM_NX_REG0[0..15]),output:2
1800 In this use of a learn action, the first packet from each source
1801 MAC will be sent to port 2. Subsequent packets will be output to
1802 port 3, with an idle timeout of 10 seconds. NXM field names and
1803 match field names are both accepted, e.g. NXM_NX_REG0 or reg0
1804 for the first register, and empty brackets may be omitted.
1805 Additional examples may be found documented as part of related
1807 sections.
1808
1810 ovs-fields(7), ovs-actions(7), ovs-appctl(8), ovs-vswitchd(8),
1811 ovs-vswitchd.conf.db(8)
1812Open vSwitch 2.12.0 ovs-ofctl(8)