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 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
560 reconfigure 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
582 INVALID_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
630 observing how a controller updates flow tables.
631 OpenFlow Switch and Controller Commands
633 The following commands, like those in the previous section, may be
634 applied to OpenFlow switches, using any of the connection methods
635 described in that section. Unlike those commands, these may also be
636 applied 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
717 tables.
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
838 expiring due to inactivity.
839 hard_timeout=seconds
841 Causes the flow to expire after the given number of seconds,
842 regardless of activity. A value of 0 (the default) gives the
843 flow 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
918 entry.
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
940 assignments, separated by commas or white space. (Embedding spaces
941 into a packet-out description normally requires quoting to prevent the
942 shell from breaking the description into multiple arguments.). Unless
943 noted otherwise only the last instance of each field is honoured. This
944 same 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
948 actions. 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
965 described in Flow Syntax above. Specifying actions= is
966 optional, but omitting actions is interpreted as a drop, so the
967 packet will not be sent anywhere from the switch. actions must
968 be 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
996 obtain 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
1006 associated 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
1020 insert 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
1024 effect 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
1029 insert 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
1033 effect 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, unless the weighted group buck‐
1054 ets cannot be mapped to a maximum of 64 dp_hash values with suf‐
1055 ficient accuracy. In those rare cases Open vSwitch 2.10 and
1056 later fall back to the hash method with the default set of hash
1057 fields.
1058 dp_hash
1060 Use a datapath computed hash value. The hash algorithm
1061 varies accross different datapath implementations.
1062 dp_hash uses the upper 32 bits of the selec‐
1063 tion_method_param as the datapath hash algorithm selec‐
1064 tor. The supported values are 0 (corresponding to hash
1065 computation over the IP 5-tuple) and 1 (corresponding to
1066 a symmetric hash computation over the IP 5-tuple).
1067 Selecting specific fields with the fields option is not
1068 supported with dp_hash). The lower 32 bits are used as
1069 the hash basis.
1070 Using dp_hash has the advantage that it does not require
1072 the generated datapath flows to exact match any addi‐
1073 tional packet header fields. For example, even if multi‐
1074 ple TCP connections thus hashed to different select group
1075 buckets have different source port numbers, generally all
1076 of them would be handled with a small set of already
1077 established datapath flows, resulting in less latency for
1078 TCP SYN packets. The downside is that the shared data‐
1079 path flows must match each packet twice, as the datapath
1080 hash value calculation happens only when needed, and a
1081 second match is required to match some bits of its value.
1082 This double-matching incurs a small additional latency
1083 cost for each packet, but this latency is orders of mag‐
1084 nitude less than the latency of creating new datapath
1085 flows for new TCP connections.
1086 hash Use a hash computed over the fields specified with the
1088 fields option, see below. If no hash fields are speci‐
1089 fied, hash defaults to a symmetric hash over the combina‐
1090 tion of MAC addresses, VLAN tags, Ether type, IP
1091 addresses and L4 port numbers. hash uses the selec‐
1092 tion_method_param as the hash basis.
1093 Note that the hashed fields become exact matched by the
1095 datapath flows. For example, if the TCP source port is
1096 hashed, the created datapath flows will match the spe‐
1097 cific TCP source port value present in the packet
1098 received. Since each TCP connection generally has a dif‐
1099 ferent source port value, a separate datapath flow will
1100 be need to be inserted for each TCP connection thus
1101 hashed to a select group bucket.
1102 This option uses a Netronome OpenFlow extension which is only
1104 supported when using Open vSwitch 2.4 and later with OpenFlow
1105 1.5 and later.
1106 selection_method_param=param
1109 64-bit integer parameter to the selection method selected by the
1110 selection_method field. The parameter's use is defined by the
1111 lower-layer that implements the selection_method. It is
1112 optional if the selection_method field is specified as a non-
1113 empty string. Prohibited otherwise. The default value is zero.
1114 This option uses a Netronome OpenFlow extension which is only
1116 supported when using Open vSwitch 2.4 and later with OpenFlow
1117 1.5 and later.
1118 fields=field
1121 fields(field[=mask]...)
1122 The field parameters to selection method selected by the selec‐
1123 tion_method field. The syntax is described in Flow Syntax with
1124 the additional restrictions that if a value is provided it is
1125 treated as a wildcard mask and wildcard masks following a slash
1126 are prohibited. The pre-requisites of fields must be provided by
1127 any flows that output to the group. The use of the fields is
1128 defined by the lower-layer that implements the selection_method.
1129 They are optional if the selection_method field is specified as
1130 ``hash', prohibited otherwise. The default is no fields.
1131 This option will use a Netronome OpenFlow extension which is
1133 only supported when using Open vSwitch 2.4 and later with Open‐
1134 Flow 1.5 and later.
1135 bucket=bucket_parameters
1138 The add-group, add-groups and mod-group commands require at
1139 least one bucket field. Bucket fields must appear after all
1140 other fields. Multiple bucket fields to specify multiple buck‐
1141 ets. The order in which buckets are specified corresponds to
1142 their order in the group. If the type of the group is "indirect"
1143 then only one group may be specified. bucket_parameters con‐
1144 sists of a list of field=value assignments, separated by commas
1145 or white space followed by a comma-separated list of actions.
1146 The fields for bucket_parameters are:
1147 bucket_id=id
1149 The 32-bit integer group id of the bucket. Values
1150 greater than 0xffffff00 are reserved. This field was
1151 added in Open vSwitch 2.4 to conform with the OpenFlow
1152 1.5 specification. It is not supported when earlier ver‐
1153 sions of OpenFlow are used. Open vSwitch will automati‐
1154 cally allocate bucket ids when they are not specified.
1155 actions=[action][,action...]
1157 The syntax of actions are identical to the actions= field
1158 described in Flow Syntax above. Specifying actions= is
1159 optional, any unknown bucket parameter will be inter‐
1160 preted as an action.
1161 weight=value
1163 The relative weight of the bucket as an integer. This may
1164 be used by the switch during bucket select for groups
1165 whose type is select.
1166 watch_port=port
1168 Port used to determine liveness of group. This or the
1169 watch_group field is required for groups whose type is ff
1170 or fast_failover. This or the watch_group field can also
1171 be used for groups whose type is select.
1172 watch_group=group_id
1174 Group identifier of group used to determine liveness of
1175 group. This or the watch_port field is required for
1176 groups whose type is ff or fast_failover. This or the
1177 watch_port field can also be used for groups whose type
1178 is select.
1179 Meter Syntax
1181 The meter table commands accept an argument that describes a meter.
1182 Such meter descriptions comprise a series field=value assignments, sep‐
1183 arated by commas or white space. (Embedding spaces into a group
1184 description normally requires quoting to prevent the shell from break‐
1185 ing the description into multiple arguments.). Unless noted otherwise
1186 only the last instance of each field is honoured.
1187 meter=id
1189 The identifier for the meter. An integer is used to specify a
1190 user-defined meter. In addition, the keywords "all", "con‐
1191 troller", and "slowpath", are also supported as virtual meters.
1192 The "controller" and "slowpath" virtual meters apply to packets
1193 sent to the controller and to the OVS userspace, respectively.
1194 When this field is specified in del-meter, dump-meter, or meter-
1196 stats, the keyword "all" may be used to designate all meters.
1197 This field is required, except for meter-stats, which dumps all
1198 stats when this field is not specified.
1199 kbps
1201 pktps The unit for the rate and burst_size band parameters. kbps
1202 specifies kilobits per second, and pktps specifies packets per
1203 second. A unit is required for the add-meter and mod-meter com‐
1204 mands.
1205 burst If set, enables burst support for meter bands through the
1208 burst_size parameter.
1209 stats If set, enables the collection of meter and band statistics.
1212 bands=band_parameters
1215 The add-meter and mod-meter commands require at least one band
1216 specification. Bands must appear after all other fields.
1217 type=type
1219 The type of the meter band. This keyword starts a new
1220 band specification. Each band specifies a rate above
1221 which the band is to take some action. The action depends
1222 on the band type. If multiple bands' rate is exceeded,
1223 then the band with the highest rate among the exceeded
1224 bands is selected. The following keywords designate the
1225 allowed meter band types:
1226 drop Drop packets exceeding the band's rate limit.
1228 The other band_parameters are:
1230 rate=value
1232 The relative rate limit for this band, in kilobits per
1233 second or packets per second, depending on whether kbps
1234 or pktps was specified.
1235 burst_size=size
1237 If burst is specified for the meter entry, configures the
1238 maximum burst allowed for the band in kilobits or pack‐
1239 ets, depending on whether kbps or pktps was specified.
1240 If unspecified, the switch is free to select some reason‐
1241 able value depending on its configuration.
1242
1244 --strict
1245 Uses strict matching when running flow modification commands.
1246 --names
1248 --no-names
1249 Every OpenFlow port has a name and a number, and every OpenFlow
1250 flow table has a number and sometimes a name. By default,
1251 ovs-ofctl commands accept both port and table names and numbers,
1252 and they display port and table names if ovs-ofctl is running on
1253 an interactive console, numbers otherwise. With --names,
1254 ovs-ofctl commands both accept and display port and table names;
1255 with --no-names, commands neither accept nor display port and
1256 table names.
1257 If a port or table name contains special characters or might be
1259 confused with a keyword within a flow, it may be enclosed in
1260 double quotes (escaped from the shell). If necessary, JSON-
1261 style escape sequences may be used inside quotes, as specified
1262 in RFC 7159. When it displays port and table names, ovs-ofctl
1263 quotes any name that does not start with a letter followed by
1264 letters or digits.
1265 Open vSwitch added support for port names and these options.
1267 Open vSwitch 2.10 added support for table names. Earlier ver‐
1268 sions always behaved as if --no-names were specified.
1269 Open vSwitch does not place its own limit on the length of port
1271 names, but OpenFlow limits port names to 15 bytes. Because
1272 ovs-ofctl uses OpenFlow to retrieve the mapping between port
1273 names and numbers, names longer than this limit will be trun‐
1274 cated for both display and acceptance. Truncation can also
1275 cause long names that are different to appear to be the same;
1276 when a switch has two ports with the same (truncated) name,
1277 ovs-ofctl refuses to display or accept the name, using the num‐
1278 ber instead.
1279 OpenFlow and Open vSwitch limit table names to 32 bytes.
1281 --stats
1283 --no-stats
1284 The dump-flows command by default, or with --stats, includes
1285 flow duration, packet and byte counts, and idle and hard age in
1286 its output. With --no-stats, it omits all of these, as well as
1287 cookie values and table IDs if they are zero.
1288 --read-only
1290 Do not execute read/write commands.
1291 --bundle
1293 Execute flow mods as an OpenFlow 1.4 atomic bundle transaction.
1294 · Within a bundle, all flow mods are processed in the order
1296 they appear and as a single atomic transaction, meaning
1297 that if one of them fails, the whole transaction fails
1298 and none of the changes are made to the switch's flow ta‐
1299 ble, and that each given datapath packet traversing the
1300 OpenFlow tables sees the flow tables either as before the
1301 transaction, or after all the flow mods in the bundle
1302 have been successfully applied.
1303 · The beginning and the end of the flow table modification
1305 commands in a bundle are delimited with OpenFlow 1.4 bun‐
1306 dle control messages, which makes it possible to stream
1307 the included commands without explicit OpenFlow barriers,
1308 which are otherwise used after each flow table modifica‐
1309 tion command. This may make large modifications execute
1310 faster as a bundle.
1311 · Bundles require OpenFlow 1.4 or higher. An explicit -O
1313 OpenFlow14 option is not needed, but you may need to
1314 enable OpenFlow 1.4 support for OVS by setting the OVSDB
1315 protocols column in the bridge table.
1316 -O [version[,version]...]
1318 --protocols=[version[,version]...]
1319 Sets the OpenFlow protocol versions that are allowed when estab‐
1320 lishing an OpenFlow session.
1321 These protocol versions are enabled by default:
1323 · OpenFlow10, for OpenFlow 1.0.
1325 The following protocol versions are generally supported, but for com‐
1326 patibility with older versions of Open vSwitch they are not enabled by
1327 default:
1328 · OpenFlow11, for OpenFlow 1.1.
1330 · OpenFlow12, for OpenFlow 1.2.
1332 · OpenFlow13, for OpenFlow 1.3.
1334 · OpenFlow14, for OpenFlow 1.4.
1336 · OpenFlow15, for OpenFlow 1.5.
1338 -F format[,format...]
1340 --flow-format=format[,format...]
1341 ovs-ofctl supports the following individual flow formats, any
1342 number of which may be listed as format:
1343 OpenFlow10-table_id
1345 This is the standard OpenFlow 1.0 flow format. All Open‐
1346 Flow switches and all versions of Open vSwitch support
1347 this flow format.
1348 OpenFlow10+table_id
1350 This is the standard OpenFlow 1.0 flow format plus a
1351 Nicira extension that allows ovs-ofctl to specify the
1352 flow table in which a particular flow should be placed.
1353 Open vSwitch 1.2 and later supports this flow format.
1354 NXM-table_id (Nicira Extended Match)
1356 This Nicira extension to OpenFlow is flexible and exten‐
1357 sible. It supports all of the Nicira flow extensions,
1358 such as tun_id and registers. Open vSwitch 1.1 and later
1359 supports this flow format.
1360 NXM+table_id (Nicira Extended Match)
1362 This combines Nicira Extended match with the ability to
1363 place a flow in a specific table. Open vSwitch 1.2 and
1364 later supports this flow format.
1365 OXM-OpenFlow12
1367 OXM-OpenFlow13
1368 OXM-OpenFlow14
1369 OXM-OpenFlow15
1370 These are the standard OXM (OpenFlow Extensible Match)
1371 flow format in OpenFlow 1.2 and later.
1372 ovs-ofctl also supports the following abbreviations for collec‐
1374 tions of flow formats:
1375 any Any supported flow format.
1377 OpenFlow10
1379 OpenFlow10-table_id or OpenFlow10+table_id.
1380 NXM NXM-table_id or NXM+table_id.
1382 OXM OXM-OpenFlow12, OXM-OpenFlow13, or OXM-OpenFlow14.
1384 For commands that modify the flow table, ovs-ofctl by default
1386 negotiates the most widely supported flow format that supports
1387 the flows being added. For commands that query the flow table,
1388 ovs-ofctl by default uses the most advanced format supported by
1389 the switch.
1390 This option, where format is a comma-separated list of one or
1392 more of the formats listed above, limits ovs-ofctl's choice of
1393 flow format. If a command cannot work as requested using one of
1394 the specified flow formats, ovs-ofctl will report a fatal error.
1395 -P format
1397 --packet-in-format=format
1398 ovs-ofctl supports the following ``packet-in'' formats, in order
1399 of increasing capability:
1400 standard
1402 This uses the OFPT_PACKET_IN message, the standard
1403 ``packet-in'' message for any given OpenFlow version.
1404 Every OpenFlow switch that supports a given OpenFlow ver‐
1405 sion supports this format.
1406 nxt_packet_in
1408 This uses the NXT_PACKET_IN message, which adds many of
1409 the capabilities of the OpenFlow 1.1 and later ``packet-
1410 in'' messages before those OpenFlow versions were avail‐
1411 able in Open vSwitch. Open vSwitch 1.1 and later support
1412 this format. Only Open vSwitch 2.6 and later, however,
1413 support it for OpenFlow 1.1 and later (but there is lit‐
1414 tle reason to use it with those versions of OpenFlow).
1415 nxt_packet_in2
1417 This uses the NXT_PACKET_IN2 message, which is extensible
1418 and should avoid the need to define new formats later.
1419 In particular, this format supports passing arbitrary
1420 user-provided data to a controller using the userdata
1421 option on the controller action. Open vSwitch 2.6 and
1422 later support this format.
1423 Without this option, ovs-ofctl prefers nxt_packet_in2 if the
1425 switch supports it. Otherwise, if OpenFlow 1.0 is in use,
1426 ovs-ofctl prefers nxt_packet_in if the switch supports it. Oth‐
1427 erwise, ovs-ofctl falls back to the standard packet-in format.
1428 When this option is specified, ovs-ofctl insists on the selected
1429 format. If the switch does not support the requested format,
1430 ovs-ofctl will report a fatal error.
1431 Before version 2.6, Open vSwitch called standard format open‐
1433 flow10 and nxt_packet_in format nxm, and ovs-ofctl still accepts
1434 these names as synonyms. (The name openflow10 was a misnomer
1435 because this format actually varies from one OpenFlow version to
1436 another; it is not consistently OpenFlow 1.0 format. Similarly,
1437 when nxt_packet_in2 was introduced, the name nxm became confus‐
1438 ing because it also uses OXM/NXM.)
1439 This option affects only the monitor command.
1441 --timestamp
1443 Print a timestamp before each received packet. This option only
1444 affects the monitor, snoop, and ofp-parse-pcap commands.
1445 -m
1447 --more Increases the verbosity of OpenFlow messages printed and logged
1448 by ovs-ofctl commands. Specify this option more than once to
1449 increase verbosity further.
1450 --sort[=field]
1452 --rsort[=field]
1453 Display output sorted by flow field in ascending (--sort) or
1454 descending (--rsort) order, where field is any of the fields
1455 that are allowed for matching or priority to sort by priority.
1456 When field is omitted, the output is sorted by priority. Spec‐
1457 ify these options multiple times to sort by multiple fields.
1458 Any given flow will not necessarily specify a value for a given
1460 field. This requires special treatement:
1461 · A flow that does not specify any part of a field that is
1463 used for sorting is sorted after all the flows that do
1464 specify the field. For example, --sort=tcp_src will sort
1465 all the flows that specify a TCP source port in ascending
1466 order, followed by the flows that do not specify a TCP
1467 source port at all.
1468 · A flow that only specifies some bits in a field is sorted
1470 as if the wildcarded bits were zero. For example,
1471 --sort=nw_src would sort a flow that specifies
1472 nw_src=192.168.0.0/24 the same as nw_src=192.168.0.0.
1473 These options currently affect only dump-flows output.
1475 Daemon Options
1477 The following options are valid on POSIX based platforms.
1478 --pidfile[=pidfile]
1480 Causes a file (by default, ovs-ofctl.pid) to be created indicat‐
1481 ing the PID of the running process. If the pidfile argument is
1482 not specified, or if it does not begin with /, then it is cre‐
1483 ated in /var/run/openvswitch.
1484 If --pidfile is not specified, no pidfile is created.
1486 --overwrite-pidfile
1488 By default, when --pidfile is specified and the specified pid‐
1489 file already exists and is locked by a running process,
1490 ovs-ofctl refuses to start. Specify --overwrite-pidfile to
1491 cause it to instead overwrite the pidfile.
1492 When --pidfile is not specified, this option has no effect.
1494 --detach
1496 Runs ovs-ofctl as a background process. The process forks, and
1497 in the child it starts a new session, closes the standard file
1498 descriptors (which has the side effect of disabling logging to
1499 the console), and changes its current directory to the root
1500 (unless --no-chdir is specified). After the child completes its
1501 initialization, the parent exits. ovs-ofctl detaches only when
1502 executing the monitor or snoop commands.
1503 --monitor
1505 Creates an additional process to monitor the ovs-ofctl daemon.
1506 If the daemon dies due to a signal that indicates a programming
1507 error (SIGABRT, SIGALRM, SIGBUS, SIGFPE, SIGILL, SIGPIPE,
1508 SIGSEGV, SIGXCPU, or SIGXFSZ) then the monitor process starts a
1509 new copy of it. If the daemon dies or exits for another reason,
1510 the monitor process exits.
1511 This option is normally used with --detach, but it also func‐
1513 tions without it.
1514 --no-chdir
1516 By default, when --detach is specified, ovs-ofctl changes its
1517 current working directory to the root directory after it
1518 detaches. Otherwise, invoking ovs-ofctl from a carelessly cho‐
1519 sen directory would prevent the administrator from unmounting
1520 the file system that holds that directory.
1521 Specifying --no-chdir suppresses this behavior, preventing
1523 ovs-ofctl from changing its current working directory. This may
1524 be useful for collecting core files, since it is common behavior
1525 to write core dumps into the current working directory and the
1526 root directory is not a good directory to use.
1527 This option has no effect when --detach is not specified.
1529 --no-self-confinement
1531 By default daemon will try to self-confine itself to work with
1532 files under well-known directories determined during build. It
1533 is better to stick with this default behavior and not to use
1534 this flag unless some other Access Control is used to confine
1535 daemon. Note that in contrast to other access control implemen‐
1536 tations that are typically enforced from kernel-space (e.g. DAC
1537 or MAC), self-confinement is imposed from the user-space daemon
1538 itself and hence should not be considered as a full confinement
1539 strategy, but instead should be viewed as an additional layer of
1540 security.
1541 --user Causes ovs-ofctl to run as a different user specified in
1543 "user:group", thus dropping most of the root privileges. Short
1544 forms "user" and ":group" are also allowed, with current user or
1545 group are assumed respectively. Only daemons started by the root
1546 user accepts this argument.
1547 On Linux, daemons will be granted CAP_IPC_LOCK and
1549 CAP_NET_BIND_SERVICES before dropping root privileges. Daemons
1550 that interact with a datapath, such as ovs-vswitchd, will be
1551 granted three additional capabilities, namely CAP_NET_ADMIN,
1552 CAP_NET_BROADCAST and CAP_NET_RAW. The capability change will
1553 apply even if the new user is root.
1554 On Windows, this option is not currently supported. For security
1556 reasons, specifying this option will cause the daemon process
1557 not to start.
1558 --unixctl=socket
1560 Sets the name of the control socket on which ovs-ofctl listens
1561 for runtime management commands (see RUNTIME MANAGEMENT COM‐
1562 MANDS, below). If socket does not begin with /, it is inter‐
1563 preted as relative to /var/run/openvswitch. If --unixctl is not
1564 used at all, the default socket is /var/run/open‐
1565 vswitch/ovs-ofctl.pid.ctl, where pid is ovs-ofctl's process ID.
1566 On Windows a local named pipe is used to listen for runtime man‐
1568 agement commands. A file is created in the absolute path as
1569 pointed by socket or if --unixctl is not used at all, a file is
1570 created as ovs-ofctl.ctl in the configured OVS_RUNDIR directory.
1571 The file exists just to mimic the behavior of a Unix domain
1572 socket.
1573 Specifying none for socket disables the control socket feature.
1575 Public Key Infrastructure Options
1577 -p privkey.pem
1578 --private-key=privkey.pem
1579 Specifies a PEM file containing the private key used as
1580 ovs-ofctl's identity for outgoing SSL connections.
1581 -c cert.pem
1583 --certificate=cert.pem
1584 Specifies a PEM file containing a certificate that certifies the
1585 private key specified on -p or --private-key to be trustworthy.
1586 The certificate must be signed by the certificate authority (CA)
1587 that the peer in SSL connections will use to verify it.
1588 -C cacert.pem
1590 --ca-cert=cacert.pem
1591 Specifies a PEM file containing the CA certificate that
1592 ovs-ofctl should use to verify certificates presented to it by
1593 SSL peers. (This may be the same certificate that SSL peers use
1594 to verify the certificate specified on -c or --certificate, or
1595 it may be a different one, depending on the PKI design in use.)
1596 -C none
1598 --ca-cert=none
1599 Disables verification of certificates presented by SSL peers.
1600 This introduces a security risk, because it means that certifi‐
1601 cates cannot be verified to be those of known trusted hosts.
1602 -v[spec]
1604 --verbose=[spec]
1605 Sets logging levels. Without any spec, sets the log level for
1606 every module and destination to dbg. Otherwise, spec is a list
1607 of words separated by spaces or commas or colons, up to one from
1608 each category below:
1609 · A valid module name, as displayed by the vlog/list com‐
1611 mand on ovs-appctl(8), limits the log level change to the
1612 specified module.
1613 · syslog, console, or file, to limit the log level change
1615 to only to the system log, to the console, or to a file,
1616 respectively. (If --detach is specified, ovs-ofctl
1617 closes its standard file descriptors, so logging to the
1618 console will have no effect.)
1619 On Windows platform, syslog is accepted as a word and is
1621 only useful along with the --syslog-target option (the
1622 word has no effect otherwise).
1623 · off, emer, err, warn, info, or dbg, to control the log
1625 level. Messages of the given severity or higher will be
1626 logged, and messages of lower severity will be filtered
1627 out. off filters out all messages. See ovs-appctl(8)
1628 for a definition of each log level.
1629 Case is not significant within spec.
1631 Regardless of the log levels set for file, logging to a file
1633 will not take place unless --log-file is also specified (see
1634 below).
1635 For compatibility with older versions of OVS, any is accepted as
1637 a word but has no effect.
1638 -v
1640 --verbose
1641 Sets the maximum logging verbosity level, equivalent to --ver‐
1642 bose=dbg.
1643 -vPATTERN:destination:pattern
1645 --verbose=PATTERN:destination:pattern
1646 Sets the log pattern for destination to pattern. Refer to
1647 ovs-appctl(8) for a description of the valid syntax for pattern.
1648 -vFACILITY:facility
1650 --verbose=FACILITY:facility
1651 Sets the RFC5424 facility of the log message. facility can be
1652 one of kern, user, mail, daemon, auth, syslog, lpr, news, uucp,
1653 clock, ftp, ntp, audit, alert, clock2, local0, local1, local2,
1654 local3, local4, local5, local6 or local7. If this option is not
1655 specified, daemon is used as the default for the local system
1656 syslog and local0 is used while sending a message to the target
1657 provided via the --syslog-target option.
1658 --log-file[=file]
1660 Enables logging to a file. If file is specified, then it is
1661 used as the exact name for the log file. The default log file
1662 name used if file is omitted is /var/log/open‐
1663 vswitch/ovs-ofctl.log.
1664 --syslog-target=host:port
1666 Send syslog messages to UDP port on host, in addition to the
1667 system syslog. The host must be a numerical IP address, not a
1668 hostname.
1669 --syslog-method=method
1671 Specify method how syslog messages should be sent to syslog dae‐
1672 mon. Following forms are supported:
1673 · libc, use libc syslog() function. Downside of using this
1675 options is that libc adds fixed prefix to every message
1676 before it is actually sent to the syslog daemon over
1677 /dev/log UNIX domain socket.
1678 · unix:file, use UNIX domain socket directly. It is possi‐
1680 ble to specify arbitrary message format with this option.
1681 However, rsyslogd 8.9 and older versions use hard coded
1682 parser function anyway that limits UNIX domain socket
1683 use. If you want to use arbitrary message format with
1684 older rsyslogd versions, then use UDP socket to localhost
1685 IP address instead.
1686 · udp:ip:port, use UDP socket. With this method it is pos‐
1688 sible to use arbitrary message format also with older
1689 rsyslogd. When sending syslog messages over UDP socket
1690 extra precaution needs to be taken into account, for
1691 example, syslog daemon needs to be configured to listen
1692 on the specified UDP port, accidental iptables rules
1693 could be interfering with local syslog traffic and there
1694 are some security considerations that apply to UDP sock‐
1695 ets, but do not apply to UNIX domain sockets.
1696 · null, discards all messages logged to syslog.
1698 The default is taken from the OVS_SYSLOG_METHOD environment
1700 variable; if it is unset, the default is libc.
1701 --color[=when]
1703 Colorize the output (for some commands); when can be never,
1704 always, or auto (the default).
1705 Only some commands support output coloring. Color names and
1707 default colors may change in future releases.
1708 The environment variable OVS_COLORS can be used to specify user-
1710 defined colors and other attributes used to highlight various
1711 parts of the output. If set, its value is a colon-separated list
1712 of capabilities that defaults to
1713 ac:01;31:dr=34:le=31:pm=36:pr=35:sp=33:vl=32. Supported capabil‐
1714 ities were initially designed for coloring flows from ovs-ofctl
1715 dump-flows switch command, and they are as follows.
1716 ac=01;31
1718 SGR substring for actions= keyword in a flow. The
1719 default is a bold red text foreground.
1720 dr=34 SGR substring for drop keyword. The default is a
1722 dark blue text foreground.
1723 le=31 SGR substring for learn= keyword in a flow. The
1725 default is a red text foreground.
1726 pm=36 SGR substring for flow match attribute names. The
1728 default is a cyan text foreground.
1729 pr=35 SGR substring for keywords in a flow that are fol‐
1731 lowed by arguments inside parenthesis. The
1732 default is a magenta text foreground.
1733 sp=33 SGR substring for some special keywords in a flow,
1735 notably: table=, priority=, load:, output:, move:,
1736 group:, CONTROLLER:, set_field:, resubmit:, exit.
1737 The default is a yellow text foreground.
1738 vl=32 SGR substring for a lone flow match attribute with
1740 no field name. The default is a green text fore‐
1741 ground.
1742 See the Select Graphic Rendition (SGR) section in the documenta‐
1744 tion of the text terminal that is used for permitted values and
1745 their meaning as character attributes.
1746 -h
1748 --help Prints a brief help message to the console.
1749 -V
1751 --version
1752 Prints version information to the console.
1753
1755 ovs-appctl(8) can send commands to a running ovs-ofctl process. The
1756 supported commands are listed below.
1757 exit Causes ovs-ofctl to gracefully terminate. This command applies
1759 only when executing the monitor or snoop commands.
1760 ofctl/set-output-file file
1762 Causes all subsequent output to go to file instead of stderr.
1763 This command applies only when executing the monitor or snoop
1764 commands.
1765 ofctl/send ofmsg...
1767 Sends each ofmsg, specified as a sequence of hex digits that
1768 express an OpenFlow message, on the OpenFlow connection. This
1769 command is useful only when executing the monitor command.
1770 ofctl/packet-out packet-out
1772 Sends an OpenFlow PACKET_OUT message specified in Packet-Out
1773 Syntax, on the OpenFlow connection. See Packet-Out Syntax sec‐
1774 tion for more information. This command is useful only when
1775 executing the monitor command.
1776 ofctl/barrier
1778 Sends an OpenFlow barrier request on the OpenFlow connection and
1779 waits for a reply. This command is useful only for the monitor
1780 command.
1781
1783 The following examples assume that ovs-vswitchd has a bridge named br0
1784 configured.
1785 ovs-ofctl dump-tables br0
1787 Prints out the switch's table stats. (This is more interesting
1788 after some traffic has passed through.)
1789 ovs-ofctl dump-flows br0
1791 Prints the flow entries in the switch.
1792 ovs-ofctl add-flow table=0 actions=learn(table=1,hard_timeout=10,
1794 NXM_OF_VLAN_TCI[0..11],output:NXM_OF_IN_PORT[]), resubmit(,1)
1795 ovs-ofctl add-flow table=1 priority=0 actions=flood Implements
1796 a level 2 MAC learning switch using the learn.
1797 ovs-ofctl add-flow br0 'table=0,priority=0
1799 actions=load:3->NXM_NX_REG0[0..15],learn(table=0,priority=1,idle_time‐
1800 out=10,NXM_OF_ETH_SRC[],NXM_OF_VLAN_TCI[0..11],out‐
1801 put:NXM_NX_REG0[0..15]),output:2
1802 In this use of a learn action, the first packet from each source
1803 MAC will be sent to port 2. Subsequent packets will be output to
1804 port 3, with an idle timeout of 10 seconds. NXM field names and
1805 match field names are both accepted, e.g. NXM_NX_REG0 or reg0
1806 for the first register, and empty brackets may be omitted.
1807 Additional examples may be found documented as part of related
1809 sections.
1810
1812 ovs-fields(7), ovs-actions(7), ovs-appctl(8), ovs-vswitchd(8),
1813 ovs-vswitchd.conf.db(8)
1814Open vSwitch 2.15.0 ovs-ofctl(8)