1ovs-vswitchd(8) Open vSwitch Manual ovs-vswitchd(8)
2
6 ovs-vswitchd - Open vSwitch daemon
7
9 ovs-vswitchd [database]
10
12 A daemon that manages and controls any number of Open vSwitch switches
13 on the local machine.
14 The database argument specifies how ovs-vswitchd connects to
16 ovsdb-server. database may be an OVSDB active or passive connection
17 method, as described in ovsdb(7). The default is unix:/var/run/open‐
18 vswitch/db.sock.
19 ovs-vswitchd retrieves its configuration from database at startup. It
21 sets up Open vSwitch datapaths and then operates switching across each
22 bridge described in its configuration files. As the database changes,
23 ovs-vswitchd automatically updates its configuration to match.
24 ovs-vswitchd switches may be configured with any of the following fea‐
26 tures:
27 • L2 switching with MAC learning.
29 • NIC bonding with automatic fail-over and source MAC-based TX
31 load balancing ("SLB").
32 • 802.1Q VLAN support.
34 • Port mirroring, with optional VLAN tagging.
36 • NetFlow v5 flow logging.
38 • sFlow(R) monitoring.
40 • Connectivity to an external OpenFlow controller, such as NOX.
42 Only a single instance of ovs-vswitchd is intended to run at a time. A
44 single ovs-vswitchd can manage any number of switch instances, up to
45 the maximum number of supported Open vSwitch datapaths.
46 ovs-vswitchd does all the necessary management of Open vSwitch data‐
48 paths itself. Thus, ovs-dpctl(8) (and its userspace datapath counter‐
49 parts accessible via ovs-appctl dpctl/command) are not needed with
50 ovs-vswitchd and should not be used because they can interfere with its
51 operation. These tools are still useful for diagnostics.
52 An Open vSwitch datapath kernel module must be loaded for ovs-vswitchd
54 to be useful. Refer to the documentation for instructions on how to
55 build and load the Open vSwitch kernel module.
56
58 --mlockall
59 Causes ovs-vswitchd to call the mlockall() function, to attempt
60 to lock all of its process memory into physical RAM, preventing
61 the kernel from paging any of its memory to disk. This helps to
62 avoid networking interruptions due to system memory pressure.
63 Some systems do not support mlockall() at all, and other systems
65 only allow privileged users, such as the superuser, to use it.
66 ovs-vswitchd emits a log message if mlockall() is unavailable or
67 unsuccessful.
68 DPDK Options
70 For details on initializing ovs-vswitchd to use DPDK ports, refer to
71 the documentation or ovs-vswitchd.conf.db(5).
72 Daemon Options
74 The following options are valid on POSIX based platforms.
75 --pidfile[=pidfile]
77 Causes a file (by default, ovs-vswitchd.pid) to be created indi‐
78 cating the PID of the running process. If the pidfile argument
79 is not specified, or if it does not begin with /, then it is
80 created in /var/run/openvswitch.
81 If --pidfile is not specified, no pidfile is created.
83 --overwrite-pidfile
85 By default, when --pidfile is specified and the specified pid‐
86 file already exists and is locked by a running process,
87 ovs-vswitchd refuses to start. Specify --overwrite-pidfile to
88 cause it to instead overwrite the pidfile.
89 When --pidfile is not specified, this option has no effect.
91 --detach
93 Runs ovs-vswitchd as a background process. The process forks,
94 and in the child it starts a new session, closes the standard
95 file descriptors (which has the side effect of disabling logging
96 to the console), and changes its current directory to the root
97 (unless --no-chdir is specified). After the child completes its
98 initialization, the parent exits. ovs-vswitchd detaches only
99 after it has connected to the database, retrieved the initial
100 configuration, and set up that configuration.
101 --monitor
103 Creates an additional process to monitor the ovs-vswitchd dae‐
104 mon. If the daemon dies due to a signal that indicates a pro‐
105 gramming error (SIGABRT, SIGALRM, SIGBUS, SIGFPE, SIGILL, SIG‐
106 PIPE, SIGSEGV, SIGXCPU, or SIGXFSZ) then the monitor process
107 starts a new copy of it. If the daemon dies or exits for an‐
108 other reason, the monitor process exits.
109 This option is normally used with --detach, but it also func‐
111 tions without it.
112 --no-chdir
114 By default, when --detach is specified, ovs-vswitchd changes its
115 current working directory to the root directory after it de‐
116 taches. Otherwise, invoking ovs-vswitchd from a carelessly cho‐
117 sen directory would prevent the administrator from unmounting
118 the file system that holds that directory.
119 Specifying --no-chdir suppresses this behavior, preventing
121 ovs-vswitchd from changing its current working directory. This
122 may be useful for collecting core files, since it is common be‐
123 havior to write core dumps into the current working directory
124 and the root directory is not a good directory to use.
125 This option has no effect when --detach is not specified.
127 --no-self-confinement
129 By default daemon will try to self-confine itself to work with
130 files under well-known directories determined during build. It
131 is better to stick with this default behavior and not to use
132 this flag unless some other Access Control is used to confine
133 daemon. Note that in contrast to other access control implemen‐
134 tations that are typically enforced from kernel-space (e.g. DAC
135 or MAC), self-confinement is imposed from the user-space daemon
136 itself and hence should not be considered as a full confinement
137 strategy, but instead should be viewed as an additional layer of
138 security.
139 --user Causes ovs-vswitchd to run as a different user specified in
141 "user:group", thus dropping most of the root privileges. Short
142 forms "user" and ":group" are also allowed, with current user or
143 group are assumed respectively. Only daemons started by the root
144 user accepts this argument.
145 On Linux, daemons will be granted CAP_IPC_LOCK and
147 CAP_NET_BIND_SERVICES before dropping root privileges. Daemons
148 that interact with a datapath, such as ovs-vswitchd, will be
149 granted three additional capabilities, namely CAP_NET_ADMIN,
150 CAP_NET_BROADCAST and CAP_NET_RAW. The capability change will
151 apply even if the new user is root.
152 On Windows, this option is not currently supported. For security
154 reasons, specifying this option will cause the daemon process
155 not to start.
156 Service Options
158 The following options are valid only on Windows platform.
159 --service
161 Causes ovs-vswitchd to run as a service in the background. The
162 service should already have been created through external tools
163 like SC.exe.
164 --service-monitor
166 Causes the ovs-vswitchd service to be automatically restarted by
167 the Windows services manager if the service dies or exits for
168 unexpected reasons.
169 When --service is not specified, this option has no effect.
171 Public Key Infrastructure Options
173 -p privkey.pem
174 --private-key=privkey.pem
175 Specifies a PEM file containing the private key used as
176 ovs-vswitchd's identity for outgoing SSL connections.
177 -c cert.pem
179 --certificate=cert.pem
180 Specifies a PEM file containing a certificate that certifies the
181 private key specified on -p or --private-key to be trustworthy.
182 The certificate must be signed by the certificate authority (CA)
183 that the peer in SSL connections will use to verify it.
184 -C cacert.pem
186 --ca-cert=cacert.pem
187 Specifies a PEM file containing the CA certificate that
188 ovs-vswitchd should use to verify certificates presented to it
189 by SSL peers. (This may be the same certificate that SSL peers
190 use to verify the certificate specified on -c or --certificate,
191 or it may be a different one, depending on the PKI design in
192 use.)
193 -C none
195 --ca-cert=none
196 Disables verification of certificates presented by SSL peers.
197 This introduces a security risk, because it means that certifi‐
198 cates cannot be verified to be those of known trusted hosts.
199 --bootstrap-ca-cert=cacert.pem
201 When cacert.pem exists, this option has the same effect as -C or
202 --ca-cert. If it does not exist, then ovs-vswitchd will attempt
203 to obtain the CA certificate from the SSL peer on its first SSL
204 connection and save it to the named PEM file. If it is success‐
205 ful, it will immediately drop the connection and reconnect, and
206 from then on all SSL connections must be authenticated by a cer‐
207 tificate signed by the CA certificate thus obtained.
208 This option exposes the SSL connection to a man-in-the-middle
210 attack obtaining the initial CA certificate, but it may be use‐
211 ful for bootstrapping.
212 This option is only useful if the SSL peer sends its CA certifi‐
214 cate as part of the SSL certificate chain. The SSL protocol
215 does not require the server to send the CA certificate.
216 This option is mutually exclusive with -C and --ca-cert.
218 --peer-ca-cert=peer-cacert.pem
220 Specifies a PEM file that contains one or more additional cer‐
221 tificates to send to SSL peers. peer-cacert.pem should be the
222 CA certificate used to sign ovs-vswitchd's own certificate, that
223 is, the certificate specified on -c or --certificate. If
224 ovs-vswitchd's certificate is self-signed, then --certificate
225 and --peer-ca-cert should specify the same file.
226 This option is not useful in normal operation, because the SSL
228 peer must already have the CA certificate for the peer to have
229 any confidence in ovs-vswitchd's identity. However, this offers
230 a way for a new installation to bootstrap the CA certificate on
231 its first SSL connection.
232 Logging Options
234 -v[spec]
235 --verbose=[spec]
236 Sets logging levels. Without any spec, sets the log level for
237 every module and destination to dbg. Otherwise, spec is a list
238 of words separated by spaces or commas or colons, up to one from
239 each category below:
240 • A valid module name, as displayed by the vlog/list com‐
242 mand on ovs-appctl(8), limits the log level change to the
243 specified module.
244 • syslog, console, or file, to limit the log level change
246 to only to the system log, to the console, or to a file,
247 respectively. (If --detach is specified, ovs-vswitchd
248 closes its standard file descriptors, so logging to the
249 console will have no effect.)
250 On Windows platform, syslog is accepted as a word and is
252 only useful along with the --syslog-target option (the
253 word has no effect otherwise).
254 • off, emer, err, warn, info, or dbg, to control the log
256 level. Messages of the given severity or higher will be
257 logged, and messages of lower severity will be filtered
258 out. off filters out all messages. See ovs-appctl(8)
259 for a definition of each log level.
260 Case is not significant within spec.
262 Regardless of the log levels set for file, logging to a file
264 will not take place unless --log-file is also specified (see be‐
265 low).
266 For compatibility with older versions of OVS, any is accepted as
268 a word but has no effect.
269 -v
271 --verbose
272 Sets the maximum logging verbosity level, equivalent to --ver‐
273 bose=dbg.
274 -vPATTERN:destination:pattern
276 --verbose=PATTERN:destination:pattern
277 Sets the log pattern for destination to pattern. Refer to
278 ovs-appctl(8) for a description of the valid syntax for pattern.
279 -vFACILITY:facility
281 --verbose=FACILITY:facility
282 Sets the RFC5424 facility of the log message. facility can be
283 one of kern, user, mail, daemon, auth, syslog, lpr, news, uucp,
284 clock, ftp, ntp, audit, alert, clock2, local0, local1, local2,
285 local3, local4, local5, local6 or local7. If this option is not
286 specified, daemon is used as the default for the local system
287 syslog and local0 is used while sending a message to the target
288 provided via the --syslog-target option.
289 --log-file[=file]
291 Enables logging to a file. If file is specified, then it is
292 used as the exact name for the log file. The default log file
293 name used if file is omitted is /var/log/open‐
294 vswitch/ovs-vswitchd.log.
295 --syslog-target=host:port
297 Send syslog messages to UDP port on host, in addition to the
298 system syslog. The host must be a numerical IP address, not a
299 hostname.
300 --syslog-method=method
302 Specify method how syslog messages should be sent to syslog dae‐
303 mon. Following forms are supported:
304 • libc, use libc syslog() function. Downside of using this
306 options is that libc adds fixed prefix to every message
307 before it is actually sent to the syslog daemon over
308 /dev/log UNIX domain socket.
309 • unix:file, use UNIX domain socket directly. It is possi‐
311 ble to specify arbitrary message format with this option.
312 However, rsyslogd 8.9 and older versions use hard coded
313 parser function anyway that limits UNIX domain socket
314 use. If you want to use arbitrary message format with
315 older rsyslogd versions, then use UDP socket to localhost
316 IP address instead.
317 • udp:ip:port, use UDP socket. With this method it is pos‐
319 sible to use arbitrary message format also with older
320 rsyslogd. When sending syslog messages over UDP socket
321 extra precaution needs to be taken into account, for ex‐
322 ample, syslog daemon needs to be configured to listen on
323 the specified UDP port, accidental iptables rules could
324 be interfering with local syslog traffic and there are
325 some security considerations that apply to UDP sockets,
326 but do not apply to UNIX domain sockets.
327 • null, discards all messages logged to syslog.
329 The default is taken from the OVS_SYSLOG_METHOD environment
331 variable; if it is unset, the default is libc.
332 Other Options
334 --unixctl=socket
335 Sets the name of the control socket on which ovs-vswitchd lis‐
336 tens for runtime management commands (see RUNTIME MANAGEMENT
337 COMMANDS, below). If socket does not begin with /, it is inter‐
338 preted as relative to /var/run/openvswitch. If --unixctl is not
339 used at all, the default socket is /var/run/open‐
340 vswitch/ovs-vswitchd.pid.ctl, where pid is ovs-vswitchd's
341 process ID.
342 On Windows a local named pipe is used to listen for runtime man‐
344 agement commands. A file is created in the absolute path as
345 pointed by socket or if --unixctl is not used at all, a file is
346 created as ovs-vswitchd.ctl in the configured OVS_RUNDIR direc‐
347 tory. The file exists just to mimic the behavior of a Unix do‐
348 main socket.
349 Specifying none for socket disables the control socket feature.
351 -h
353 --help Prints a brief help message to the console.
354 -V
356 --version
357 Prints version information to the console.
358
360 ovs-appctl(8) can send commands to a running ovs-vswitchd process. The
361 currently supported commands are described below. The command descrip‐
362 tions assume an understanding of how to configure Open vSwitch.
363 GENERAL COMMANDS
365 exit --cleanup
366 Causes ovs-vswitchd to gracefully terminate. If --cleanup is
367 specified, deletes flows from datapaths and releases other data‐
368 path resources configured by ovs-vswitchd. Otherwise, datapath
369 flows and other resources remains undeleted. Resources of data‐
370 paths that are integrated into ovs-vswitchd (e.g. the netdev
371 datapath type) are always released regardless of --cleanup ex‐
372 cept for ports with internal type. Use --cleanup to release in‐
373 ternal ports too.
374 qos/show-types interface
376 Queries the interface for a list of Quality of Service types
377 that are configurable via Open vSwitch for the given interface.
378 qos/show interface
380 Queries the kernel for Quality of Service configuration and sta‐
381 tistics associated with the given interface.
382 bfd/show [interface]
384 Displays detailed information about Bidirectional Forwarding De‐
385 tection configured on interface. If interface is not specified,
386 then displays detailed information about all interfaces with BFD
387 enabled.
388 bfd/set-forwarding [interface] status
390 Force the fault status of the BFD module on interface (or all
391 interfaces if none is given) to be status. status can be
392 "true", "false", or "normal" which reverts to the standard be‐
393 havior.
394 cfm/show [interface]
396 Displays detailed information about Connectivity Fault Manage‐
397 ment configured on interface. If interface is not specified,
398 then displays detailed information about all interfaces with CFM
399 enabled.
400 cfm/set-fault [interface] status
402 Force the fault status of the CFM module on interface (or all
403 interfaces if none is given) to be status. status can be
404 "true", "false", or "normal" which reverts to the standard be‐
405 havior.
406 stp/tcn [bridge]
408 Forces a topology change event on bridge if it's running STP.
409 This may cause it to send Topology Change Notifications to its
410 peers and flush its MAC table. If no bridge is given, forces a
411 topology change event on all bridges.
412 stp/show [bridge]
414 Displays detailed information about spanning tree on the bridge.
415 If bridge is not specified, then displays detailed information
416 about all bridges with STP enabled.
417 rstp/tcn [bridge]
419 Forces a topology change event on bridge if it's running RSTP.
420 This may cause it to send Topology Change Notifications to its
421 peers and flush its MAC table. If no bridge is given, forces a
422 topology change event on all bridges.
423 rstp/show [bridge]
425 Displays detailed information about rapid spanning tree on the
426 bridge. If bridge is not specified, then displays detailed in‐
427 formation about all bridges with RSTP enabled.
428 BRIDGE COMMANDS
430 These commands manage bridges.
431 fdb/add bridge port vlan mac
433 Adds mac address to a port and vlan on a bridge. This utility
434 can be used to pre-populate fdb table without relying on dynamic
435 mac learning.
436 fdb/del bridge vlan mac
438 Deletes mac address from a port and vlan on a bridge.
439 fdb/flush [bridge]
441 Flushes bridge MAC address learning table, or all learning ta‐
442 bles if no bridge is given.
443 fdb/show bridge
445 Lists each MAC address/VLAN pair learned by the specified
446 bridge, along with the port on which it was learned and the age
447 of the entry, in seconds.
448 fdb/stats-clear [bridge]
450 Clear bridge MAC address learning table statistics, or all sta‐
451 tistics if no bridge is given.
452 fdb/stats-show bridge
454 Show MAC address learning table statistics for the specified
455 bridge.
456 mdb/flush [bridge]
458 Flushes bridge multicast snooping table, or all snooping tables
459 if no bridge is given.
460 mdb/show bridge
462 Lists each multicast group/VLAN pair learned by the specified
463 bridge, along with the port on which it was learned and the age
464 of the entry, in seconds.
465 bridge/reconnect [bridge]
467 Makes bridge drop all of its OpenFlow controller connections and
468 reconnect. If bridge is not specified, then all bridges drop
469 their controller connections and reconnect.
470 This command might be useful for debugging OpenFlow controller
472 issues.
473 bridge/dump-flows [--offload-stats] bridge
475 Lists all flows in bridge, including those normally hidden to
476 commands such as ovs-ofctl dump-flows. Flows set up by mecha‐
477 nisms such as in-band control and fail-open are hidden from the
478 controller since it is not allowed to modify or override them.
479 If --offload-stats are specified then also list statistics for
480 offloaded packets and bytes, which are a subset of the total
481 packets and bytes.
482 BOND COMMANDS
484 These commands manage bonded ports on an Open vSwitch's bridges. To
485 understand some of these commands, it is important to understand a de‐
486 tail of the bonding implementation called ``source load balancing''
487 (SLB). Instead of directly assigning Ethernet source addresses to mem‐
488 bers, the bonding implementation computes a function that maps an
489 48-bit Ethernet source addresses into an 8-bit value (a ``MAC hash''
490 value). All of the Ethernet addresses that map to a single 8-bit value
491 are then assigned to a single member.
492 bond/list
494 Lists all of the bonds, and their members, on each bridge.
495 bond/show [port]
497 Lists all of the bond-specific information (updelay, downdelay,
498 time until the next rebalance) about the given bonded port, or
499 all bonded ports if no port is given. Also lists information
500 about each members: whether it is enabled or disabled, the time
501 to completion of an updelay or downdelay if one is in progress,
502 whether it is the active member, the hashes assigned to the mem‐
503 ber. Any LACP information related to this bond may be found us‐
504 ing the lacp/show command.
505 bond/migrate port hash member
507 Only valid for SLB bonds. Assigns a given MAC hash to a new
508 member. port specifies the bond port, hash the MAC hash to be
509 migrated (as a decimal number between 0 and 255), and member the
510 new member to be assigned.
511 The reassignment is not permanent: rebalancing or fail-over will
513 cause the MAC hash to be shifted to a new member in the usual
514 manner.
515 A MAC hash cannot be migrated to a disabled member.
517 bond/set-active-member port member
519 Sets member as the active member on port. member must currently
520 be enabled.
521 The setting is not permanent: a new active member will be se‐
523 lected if member becomes disabled.
524 bond/enable-member port member
526 bond/disable-member port member
527 Enables (or disables) member on the given bond port, skipping
528 any updelay (or downdelay).
529 This setting is not permanent: it persists only until the car‐
531 rier status of member changes.
532 bond/hash mac [vlan] [basis]
534 Returns the hash value which would be used for mac with vlan and
535 basis if specified.
536 lacp/show [port]
538 Lists all of the LACP related information about the given port:
539 active or passive, aggregation key, system id, and system prior‐
540 ity. Also lists information about each member: whether it is
541 enabled or disabled, whether it is attached or detached, port id
542 and priority, actor information, and partner information. If
543 port is not specified, then displays detailed information about
544 all interfaces with CFM enabled.
545 lacp/stats-show [port]
547 Lists various stats about LACP PDUs (number of RX/TX PDUs, bad
548 PDUs received) and member state (number of times its state ex‐
549 pired/defaulted and carrier status changed) for the given port.
550 If port is not specified, then displays stats of all interfaces
551 with LACP enabled.
552 DPCTL DATAPATH DEBUGGING COMMANDS
554 The primary way to configure ovs-vswitchd is through the Open vSwitch
555 database, e.g. using ovs-vsctl(8). These commands provide a debugging
556 interface for managing datapaths. They implement the same features
557 (and syntax) as ovs-dpctl(8). Unlike ovs-dpctl(8), these commands work
558 with datapaths that are integrated into ovs-vswitchd (e.g. the netdev
559 datapath type).
560 Do not use commands to add or remove or modify datapaths if
562 ovs-vswitchd is running because this interferes with ovs-vswitchd's own
563 datapath management.
564 dpctl/add-dp dp [netdev[,option]...]
566 Creates datapath dp, with a local port also named dp. This will
567 fail if a network device dp already exists.
568 If netdevs are specified, ovs-vswitchd adds them to the new
570 datapath, just as if add-if was specified.
571 dpctl/del-dp dp
573 Deletes datapath dp. If dp is associated with any network de‐
574 vices, they are automatically removed.
575 dpctl/add-if dp netdev[,option]...
577 Adds each netdev to the set of network devices datapath dp moni‐
578 tors, where dp is the name of an existing datapath, and netdev
579 is the name of one of the host's network devices, e.g. eth0.
580 Once a network device has been added to a datapath, the datapath
581 has complete ownership of the network device's traffic and the
582 network device appears silent to the rest of the system.
583 A netdev may be followed by a comma-separated list of options.
585 The following options are currently supported:
586 type=type
588 Specifies the type of port to add. The default type is
589 system.
590 port_no=port
592 Requests a specific port number within the datapath. If
593 this option is not specified then one will be automati‐
594 cally assigned.
595 key=value
597 Adds an arbitrary key-value option to the port's configu‐
598 ration.
599 ovs-vswitchd.conf.db(5) documents the available port types and
601 options.
602 dpctl/set-if dp port[,option]...
604 Reconfigures each port in dp as specified. An option of the
605 form key=value adds the specified key-value option to the port
606 or overrides an existing key's value. An option of the form
607 key=, that is, without a value, deletes the key-value named key.
608 The type and port number of a port cannot be changed, so type
609 and port_no are only allowed if they match the existing configu‐
610 ration.
611 dpctl/del-if dp netdev...
613 Removes each netdev from the list of network devices datapath dp
614 monitors.
615 dpctl/dump-dps
617 Prints the name of each configured datapath on a separate line.
618 dpctl/show [-s | --statistics] [dp...]
620 Prints a summary of configured datapaths, including their data‐
621 path numbers and a list of ports connected to each datapath.
622 (The local port is identified as port 0.) If -s or --statistics
623 is specified, then packet and byte counters are also printed for
624 each port.
625 The datapath numbers consists of flow stats and mega flow mask
627 stats.
628 The "lookups" row displays three stats related to flow lookup
630 triggered by processing incoming packets in the datapath. "hit"
631 displays number of packets matches existing flows. "missed" dis‐
632 plays the number of packets not matching any existing flow and
633 require user space processing. "lost" displays number of pack‐
634 ets destined for user space process but subsequently dropped be‐
635 fore reaching userspace. The sum of "hit" and "miss" equals to
636 the total number of packets datapath processed.
637 The "flows" row displays the number of flows in datapath.
639 The "masks" row displays the mega flow mask stats. This row is
641 omitted for datapath not implementing mega flow. "hit" displays
642 the total number of masks visited for matching incoming packets.
643 "total" displays number of masks in the datapath. "hit/pkt" dis‐
644 plays the average number of masks visited per packet; the ratio
645 between "hit" and total number of packets processed by the data‐
646 path.
647 If one or more datapaths are specified, information on only
649 those datapaths are displayed. Otherwise, ovs-vswitchd displays
650 information about all configured datapaths.
651 DATAPATH FLOW TABLE DEBUGGING COMMANDS
653 The following commands are primarily useful for debugging Open vSwitch.
654 The flow table entries (both matches and actions) that they work with
655 are not OpenFlow flow entries. Instead, they are different and consid‐
656 erably simpler flows maintained by the Open vSwitch kernel module. Do
657 not use commands to add or remove or modify datapath flows if
658 ovs-vswitchd is running because it interferes with ovs-vswitchd's own
659 datapath flow management. Use ovs-ofctl(8), instead, to work with
660 OpenFlow flow entries.
661 The dp argument to each of these commands is optional when exactly one
663 datapath exists, in which case that datapath is the default. When mul‐
664 tiple datapaths exist, then a datapath name is required.
665 dpctl/dump-flows [-m | --more] [--names | --no-names] [dp] [filter=fil‐
667 ter] [type=type] [pmd=pmd]
668 Prints to the console all flow entries in datapath dp's flow ta‐
669 ble. Without -m or --more, output omits match fields that a
670 flow wildcards entirely; with -m or --more, output includes all
671 wildcarded fields.
672 If filter=filter is specified, only displays the flows that
674 match the filter. filter is a flow in the form similar to that
675 accepted by ovs-ofctl(8)'s add-flow command. (This is not an
676 OpenFlow flow: besides other differences, it never contains
677 wildcards.) The filter is also useful to match wildcarded
678 fields in the datapath flow. As an example, fil‐
679 ter='tcp,tp_src=100' will match the datapath flow containing
680 'tcp(src=80/0xff00,dst=8080/0xff)'.
681 If pmd=pmd is specified, only displays flows of the specified
683 pmd. Using pmd=-1 will restrict the dump to flows from the main
684 thread. This option is only supported by the userspace data‐
685 path.
686 If type=type is specified, only displays flows of the specified
688 types. This option supported only for ovs-appctl
689 dpctl/dump-flows. type is a comma separated list, which can
690 contain any of the following:
691 ovs - displays flows handled in the ovs dp
692 tc - displays flows handled in the tc dp
693 dpdk - displays flows fully offloaded by dpdk
694 offloaded - displays flows offloaded to the HW
695 non-offloaded - displays flows not offloaded to the HW
696 partially-offloaded - displays flows where only part of their
697 proccessing is done in HW
698 all - displays all the types of flows
699 By default all the types of flows are displayed. ovs-dpctl al‐
701 ways acts as if the type was ovs.
702 dpctl/add-flow [dp] flow actions
704 dpctl/mod-flow [--clear] [--may-create] [-s | --statistics] [dp] flow
706 actions
707 Adds or modifies a flow in dp's flow table that, when a packet
708 matching flow arrives, causes actions to be executed.
709 The add-flow command succeeds only if flow does not already ex‐
711 ist in dp. Contrariwise, mod-flow without --may-create only
712 modifies the actions for an existing flow. With --may-create,
713 mod-flow will add a new flow or modify an existing one.
714 If -s or --statistics is specified, then mod-flow prints the
716 modified flow's statistics. A flow's statistics are the number
717 of packets and bytes that have passed through the flow, the
718 elapsed time since the flow last processed a packet (if ever),
719 and (for TCP flows) the union of the TCP flags processed through
720 the flow.
721 With --clear, mod-flow zeros out the flow's statistics. The
723 statistics printed if -s or --statistics is also specified are
724 those from just before clearing the statistics.
725 NOTE: flow and actions do not match the syntax used with
727 ovs-ofctl(8)'s add-flow command.
728 Usage Examples
730 Forward ARP between ports 1 and 2 on datapath myDP:
732 ovs-dpctl add-flow myDP \
734 "in_port(1),eth(),eth_type(0x0806),arp()" 2
735 ovs-dpctl add-flow myDP \
737 "in_port(2),eth(),eth_type(0x0806),arp()" 1
738 Forward all IPv4 traffic between two addresses on ports 1 and 2:
740 ovs-dpctl add-flow myDP \
742 "in_port(1),eth(),eth_type(0x800),\
743 ipv4(src=172.31.110.4,dst=172.31.110.5)" 2
744 ovs-dpctl add-flow myDP \
746 "in_port(2),eth(),eth_type(0x800),\
747 ipv4(src=172.31.110.5,dst=172.31.110.4)" 1
748 dpctl/add-flows [dp] file
750 dpctl/mod-flows [dp] file
751 dpctl/del-flows [dp] file
752 Reads flow entries from file (or stdin if file is -) and adds,
753 modifies, or deletes each entry to the datapath. Each flow
754 specification (e.g., each line in file) may start with add, mod‐
755 ify, or delete keyword to specify whether a flow is to be added,
756 modified, or deleted. A flow specification without one of these
757 keywords is treated based on the used command. All flow modifi‐
758 cations are executed as individual transactions in the order
759 specified.
760 dpctl/del-flow [-s | --statistics] [dp] flow
762 Deletes the flow from dp's flow table that matches flow. If -s
763 or --statistics is specified, then del-flow prints the deleted
764 flow's statistics.
765 dpctl/get-flow [dp] ufid:ufid [-m | --more] [--names | --no-names]
767 Fetches the flow from dp's flow table with unique identifier
768 ufid. ufid must be specified as a string of 32 hexadecimal
769 characters.
770 dpctl/del-flows [dp]
772 Deletes all flow entries from datapath dp's flow table.
773 DATAPATH FLOW CACHE COMMANDS
775 The following commands are useful for debugging and configuring the
776 datapath flow cache settings.
777 dpctl/cache-get-size [dp]
779 Prints the current cache sizes to the console.
780 dpctl/cache-set-size dp cache size
782 Set the dp's specific cache to the given size. The cache name
783 can be found by using the cache-get-size command.
784 CONNECTION TRACKING TABLE COMMANDS
786 The following commands are useful for debugging and configuring the
787 connection tracking table in the datapath.
788 The dp argument to each of these commands is optional when exactly one
790 datapath exists, in which case that datapath is the default. When mul‐
791 tiple datapaths exist, then a datapath name is required.
792 N.B.(Linux specific): the system datapaths (i.e. the Linux kernel mod‐
794 ule Open vSwitch datapaths) share a single connection tracking table
795 (which is also used by other kernel subsystems, such as iptables, nfta‐
796 bles and the regular host stack). Therefore, the following commands do
797 not apply specifically to one datapath.
798 dpctl/ipf-set-enabled [dp] v4|v6
800 dpctl/ipf-set-disabled [dp] v4|v6
801 Enables or disables IP fragmentation handling for the userspace
802 connection tracker. Either v4 or v6 must be specified. Both
803 IPv4 and IPv6 fragment reassembly are enabled by default. Only
804 supported for the userspace datapath.
805 dpctl/ipf-set-min-frag [dp] v4|v6 minfrag
807 Sets the minimum fragment size (L3 header and data) for non-fi‐
808 nal fragments to minfrag. Either v4 or v6 must be specified.
809 For enhanced DOS security, higher minimum fragment sizes can
810 usually be used. The default IPv4 value is 1200 and the clamped
811 minimum is 400. The default IPv6 value is 1280, with a clamped
812 minimum of 400, for testing flexibility. The maximum fragment
813 size is not clamped, however, setting this value too high might
814 result in valid fragments being dropped. Only supported for
815 userspace datapath.
816 dpctl/ipf-set-max-nfrags [dp] maxfrags
818 Sets the maximum number of fragments tracked by the userspace
819 datapath connection tracker to maxfrags. The default value is
820 1000 and the clamped maximum is 5000. Note that packet buffers
821 can be held by the fragmentation module while fragments are in‐
822 complete, but will timeout after 15 seconds. Memory pool sizing
823 should be set accordingly when fragmentation is enabled. Only
824 supported for userspace datapath.
825 dpctl/ipf-get-status [dp] [-m | --more]
827 Gets the configuration settings and fragment counters associated
828 with the fragmentation handling of the userspace datapath con‐
829 nection tracker. With -m or --more, also dumps the IP fragment
830 lists. Only supported for userspace datapath.
831 dpctl/dump-conntrack [-m | --more] [-s | --statistics] [dp] [zone=zone]
833 Prints to the console all the connection entries in the tracker
834 used by dp. If zone=zone is specified, only shows the connec‐
835 tions in zone. With --more, some implementation specific de‐
836 tails are included. With --statistics timeouts and timestamps
837 are added to the output.
838 dpctl/flush-conntrack [dp] [zone=zone] [ct-origin-tuple [ct-reply-tu‐
840 ple]]
841 Flushes the connection entries in the tracker used by dp based
842 on zone and connection tracking tuple ct-origin-tuple. If ct-
843 tuple is not provided, flushes all the connection entries. If
844 zone=zone is specified, only flushes the connections in zone.
845 If ct-[orig|reply]-tuple is provided, flushes the connection en‐
847 try specified by ct-[orig|reply]-tuple in zone. The zone de‐
848 faults to 0 if it is not provided. The userspace connection
849 tracker requires flushing with the original pre-NATed tuple and
850 a warning log will be otherwise generated. The tuple can be
851 partial and will remove all connections that are matching on the
852 specified fields. In order to specify only ct-reply-tuple, pro‐
853 vide empty string as ct-origin-tuple.
854 Note: Currently there is a limitation for matching on ICMP, in
856 order to partially match on ICMP parameters the ct-[orig|re‐
857 ply]-tuple has to include either source or destination IP.
858 An example of an IPv4 ICMP ct-[orig|reply]-tuple:
860 "ct_nw_src=10.1.1.1,ct_nw_dst=10.1.1.2,ct_nw_proto=1,icmp_type=8,icmp_code=0,icmp_id=10"
862 An example of an IPv6 TCP ct-[orig|reply]-tuple:
864 "ct_ipv6_src=fc00::1,ct_ipv6_dst=fc00::2,ct_nw_proto=6,ct_tp_src=1,ct_tp_dst=2"
866 dpctl/ct-stats-show [dp] [zone=zone] [-m | --more]
868 Displays the number of connections grouped by protocol used by
869 dp. If zone=zone is specified, numbers refer to the connections
870 in zone. With --more, groups by connection state for each pro‐
871 tocol.
872 dpctl/ct-bkts [dp] [gt=threshold]
874 For each conntrack bucket, displays the number of connections
875 used by dp. If gt=threshold is specified, bucket numbers are
876 displayed when the number of connections in a bucket is greater
877 than threshold.
878 dpctl/ct-set-maxconns [dp] maxconns
880 Sets the maximum limit of connection tracker entries to maxconns
881 on dp. This can be used to reduce the processing load on the
882 system due to connection tracking or simply limiting connection
883 tracking. If the number of connections is already over the new
884 maximum limit request then the new maximum limit will be en‐
885 forced when the number of connections decreases to that limit,
886 which normally happens due to connection expiry. Only supported
887 for userspace datapath.
888 dpctl/ct-get-maxconns [dp]
890 Prints the maximum limit of connection tracker entries on dp.
891 Only supported for userspace datapath.
892 dpctl/ct-get-nconns [dp]
894 Prints the current number of connection tracker entries on dp.
895 Only supported for userspace datapath.
896 dpctl/ct-enable-tcp-seq-chk [dp]
898 dpctl/ct-disable-tcp-seq-chk [dp]
899 Enables or disables TCP sequence checking. When set to dis‐
900 abled, all sequence number verification is disabled, including
901 for TCP resets. This is similar, but not the same as 'be_lib‐
902 eral' mode, as in Netfilter. Disabling sequence number verifi‐
903 cation is not an optimization in itself, but is needed for some
904 hardware offload support which might offer some performance ad‐
905 vantage. Sequence number checking is enabled by default to en‐
906 force better security and should only be disabled if required
907 for hardware offload support. This command is only supported
908 for the userspace datapath.
909 dpctl/ct-get-tcp-seq-chk [dp]
911 Prints whether TCP sequence checking is enabled or disabled on
912 dp. Only supported for the userspace datapath.
913 dpctl/ct-set-limits [dp] [default=default_limit]
915 [zone=zone,limit=limit]...
916 Sets the maximum allowed number of connections in a connection
917 tracking zone. A specific zone may be set to limit, and multi‐
918 ple zones may be specified with a comma-separated list. If a
919 per-zone limit for a particular zone is not specified in the
920 datapath, it defaults to the default per-zone limit. A default
921 zone may be specified with the default=default_limit argument.
922 Initially, the default per-zone limit is unlimited. An unlim‐
923 ited number of entries may be set with 0 limit.
924 dpctl/ct-del-limits [dp] zone=zone[,zone]...
926 Deletes the connection tracking limit for zone. Multiple zones
927 may be specified with a comma-separated list.
928 dpctl/ct-get-limits [dp] [zone=zone[,zone]...]
930 Retrieves the maximum allowed number of connections and current
931 counts per-zone. If zone is given, only the specified zone(s)
932 are printed. If no zones are specified, all the zone limits and
933 counts are provided. The command always displays the default
934 zone limit.
935 DPDK COMMANDS
937 These commands manage DPDK components.
938 dpdk/lcore-list
940 Lists the DPDK lcores and their cpu affinity. When
941 RTE_MAX_LCORE lcores are registered, some OVS PMD threads won't
942 appear.
943 dpdk/log-list
945 Lists all DPDK components that emit logs and their logging lev‐
946 els.
947 dpdk/log-set [spec]
949 Sets DPDK components logging level. Without any spec, sets the
950 logging level for all DPDK components to debug. Otherwise, spec
951 is a list of words separated by spaces: a word can be either a
952 logging level (emergency, alert, critical, error, warning, no‐
953 tice, info or debug) or a pattern matching DPDK components (see
954 dpdk/log-list command on ovs-appctl(8)) separated by a colon
955 from the logging level to apply.
956 dpdk/get-malloc-stats
958 Prints the heap information statistics about DPDK malloc.
959 DPIF-NETDEV COMMANDS
961 These commands are used to expose internal information (mostly statis‐
962 tics) about the "dpif-netdev" userspace datapath. If there is only one
963 datapath (as is often the case, unless dpctl/ commands are used), the
964 dp argument can be omitted. By default the commands present data for
965 all pmd threads in the datapath. By specifying the "-pmd Core" option
966 one can filter the output for a single pmd in the datapath.
967 dpif-netdev/pmd-stats-show [-pmd core] [dp]
969 Shows performance statistics for one or all pmd threads of the
970 datapath dp. The special thread "main" sums up the statistics of
971 every non pmd thread.
972 The sum of "phwol hits", "simple match hits", "emc hits", "smc
974 hits", "megaflow hits" and "miss" is the number of packet
975 lookups performed by the datapath. Beware that a recirculated
976 packet experiences one additional lookup per recirculation, so
977 there may be more lookups than forwarded packets in the data‐
978 path.
979 The MFEX Opt hits displays the number of packets that are pro‐
981 cessed by the optimized miniflow extract implementations.
982 Cycles are counted using the TSC or similar facilities (when
984 available on the platform). The duration of one cycle depends on
985 the processing platform.
986 "idle cycles" refers to cycles spent in PMD iterations not for‐
988 warding any any packets. "processing cycles" refers to cycles
989 spent in PMD iterations forwarding at least one packet, includ‐
990 ing the cost for polling, processing and transmitting said pack‐
991 ets.
992 To reset these counters use dpif-netdev/pmd-stats-clear.
994 dpif-netdev/pmd-stats-clear [dp]
996 Resets to zero the per pmd thread performance numbers shown by
997 the dpif-netdev/pmd-stats-show and dpif-netdev/pmd-perf-show
998 commands. It will NOT reset datapath or bridge statistics, only
999 the values shown by the above commands.
1000 dpif-netdev/pmd-perf-show [-nh] [-it iter_len] [-ms ms_len] [-pmd core]
1002 [dp]
1003 Shows detailed performance metrics for one or all pmds threads
1004 of the user space datapath.
1005 The collection of detailed statistics can be controlled by a new
1007 configuration parameter "other_config:pmd-perf-metrics". By de‐
1008 fault it is disabled. The run-time overhead, when enabled, is in
1009 the order of 1%.
1010 — used cycles
1013 — forwared packets
1014 — number of rx batches
1015 — packets/rx batch
1016 — max. vhostuser queue fill level
1017 — number of upcalls
1018 — cycles spent in upcalls
1019 This raw recorded data is used threefold:
1021 1. In histograms for each of the following metrics:
1024 — cycles/iteration (logarithmic)
1025 — packets/iteration (logarithmic)
1026 — cycles/packet
1027 — packets/batch
1028 — max. vhostuser qlen (logarithmic)
1029 — upcalls
1030 — cycles/upcall (logarithmic) The histograms bins
1031 are divided linear or logarithmic.
1032 2. A cyclic history of the above metrics for 1024 iterations
1033 3. A cyclic history of the cummulative/average values per
1034 millisecond wall clock for the last 1024 milliseconds:
1035 — number of iterations
1036 — avg. cycles/iteration
1037 — packets (Kpps)
1038 — avg. packets/batch
1039 — avg. max vhost qlen
1040 — upcalls
1041 — avg. cycles/upcall
1042 The command options are:
1044 -nh Suppress the histograms
1046 -it iter_len
1048 Display the last iter_len iteration stats
1049 -ms ms_len
1051 Display the last ms_len millisecond stats
1052 The output always contains the following global PMD statistics:
1054 Time: 15:24:55.270
1056 Measurement duration: 1.008 s
1057 pmd thread numa_id 0 core_id 1:
1059 Iterations: 572817 (1.76 us/it)
1061 - Used TSC cycles: 2419034712 ( 99.9 % of total cycles)
1062 - idle iterations: 486808 ( 15.9 % of used cycles)
1063 - busy iterations: 86009 ( 84.1 % of used cycles)
1064 Rx packets: 2399607 (2381 Kpps, 848 cycles/pkt)
1065 Datapath passes: 3599415 (1.50 passes/pkt)
1066 - PHWOL hits: 0 ( 0.0 %)
1067 - MFEX Opt hits: 3570133 ( 99.2 %)
1068 - Simple Match hits: 0 ( 0.0 %)
1069 - EMC hits: 336472 ( 9.3 %)
1070 - SMC hits: 0 ( 0.0 %)
1071 - Megaflow hits: 3262943 ( 90.7 %, 1.00 subtbl lookups/hit)
1072 - Upcalls: 0 ( 0.0 %, 0.0 us/upcall)
1073 - Lost upcalls: 0 ( 0.0 %)
1074 Tx packets: 2399607 (2381 Kpps)
1075 Tx batches: 171400 (14.00 pkts/batch)
1076 Here "Rx packets" actually reflects the number of packets for‐
1078 warded by the datapath. "Datapath passes" matches the number of
1079 packet lookups as reported by the dpif-netdev/pmd-stats-show
1080 command.
1081 To reset the counters and start a new measurement use dpif-net‐
1083 dev/pmd-stats-clear.
1084 dpif-netdev/pmd-perf-log-set on|off [-b before] [-a after] [-e|-ne]
1086 [-us usec] [-q qlen]
1087 The userspace "netdev" datapath is able to supervise the PMD
1088 performance metrics and detect iterations with suspicious sta‐
1089 tistics according to the following criteria:
1090 — The iteration lasts longer than usec microseconds (de‐
1092 fault 250). This can be used to capture events where a
1093 PMD is blocked or interrupted for such a period of time
1094 that there is a risk for dropped packets on any of its Rx
1095 queues.
1096 — The max vhost qlen exceeds a threshold qlen (default
1098 128). This can be used to infer virtio queue overruns and
1099 dropped packets inside a VM, which are not visible in OVS
1100 otherwise.
1101 Such suspicious iterations can be logged together with their it‐
1103 eration statistics in the ovs-vswitchd.log to be able to corre‐
1104 late them to packet drop or other events outside OVS.
1105 The above command enables (on) or disables (off) supervision and
1107 logging at run-time and can be used to adjust the above thresh‐
1108 olds for detecting suspicious iterations. By default supervision
1109 and logging is disabled.
1110 The command options are:
1112 -b before
1114 The number of iterations before the suspicious iteration
1115 to be logged (default 5).
1116 -a after
1118 The number of iterations after the suspicious iteration
1119 to be logged (default 5).
1120 -e Extend logging interval if another suspicious iteration
1122 is detected before logging occurs.
1123 -ne Do not extend logging interval if another suspicious it‐
1125 eration is detected before logging occurs (default).
1126 -q qlen
1128 Suspicious vhost queue fill level threshold. Increase
1129 this to 512 if the Qemu supports 1024 virtio queue length
1130 (default 128).
1131 -us usec
1133 Change the duration threshold for a suspicious iteration
1134 (default 250 us).
1135 Note: Logging of suspicious iterations itself consumes a considerable
1137 amount of processing cycles of a PMD which may be visible in the itera‐
1138 tion history. In the worst case this can lead OVS to detect another
1139 suspicious iteration caused by logging.
1140 If more than 100 iterations around a suspicious iteration have been
1142 logged once, OVS falls back to the safe default values (-b 5 -a 5 -ne)
1143 to avoid that logging itself continuously causes logging of further
1144 suspicious iterations.
1145 dpif-netdev/pmd-rxq-show [-pmd core] [dp]
1147 For one or all pmd threads of the datapath dp show the list of
1148 queue-ids with port names, which this thread polls.
1149 dpif-netdev/pmd-rxq-rebalance [dp]
1151 Reassigns rxqs to pmds in the datapath dp based on their current
1152 usage.
1153 dpif-netdev/bond-show [dp]
1155 When "other_config:lb-output-action" is set to "true", the
1156 userspace datapath handles the load balancing of bonds directly
1157 instead of depending on flow recirculation (only in balance-tcp
1158 mode).
1159 When this is the case, the above command prints the load-balanc‐
1161 ing information of the bonds configured in datapath dp showing
1162 the interface associated with each bucket (hash).
1163 dpif-netdev/subtable-lookup-prio-get
1165 Lists the DPCLS implementations or lookup functions that are
1166 available as well as their priorities.
1167 dpif-netdev/subtable-lookup-prio-set lookup_function prio
1169 Sets the priority of a lookup function by name, lookup_function,
1170 and priority, prio, which should be a positive integer value.
1171 The highest priority lookup function is used for classification.
1172 The number of affected dpcls ports and subtables is returned.
1174 dpif-netdev/dpif-impl-get
1176 Lists the DPIF implementations that are available.
1177 dpif-netdev/dpif-impl-set dpif_impl
1179 Sets the DPIF to be used to dpif_impl. By default "dpif_scalar"
1180 is used.
1181 dpif-netdev/miniflow-parser-get
1183 Lists the miniflow extract implementations that are available.
1184 dpif-netdev/miniflow-parser-set [-pmd core] miniflow_impl [study_cnt]
1186 Sets the miniflow extract to miniflow_impl for a specified PMD
1187 or all PMDs in the case where no value is specified. By default
1188 "scalar" is used. study_cnt defaults to 128 and indicates the
1189 number of packets that the "study" miniflow implementation must
1190 parse before choosing an optimal implementation.
1191 DPIF-NETLINK COMMANDS
1193 These commands are used to expose internal information of the "dpif-
1194 netlink" kernel space datapath.
1195 dpif-netlink/dispatch-mode
1197 Displays the "dispatch-mode" for all datapaths.
1198 NETDEV-DPDK COMMANDS
1200 These commands manage DPDK related ports (type=dpdk*).
1201 netdev-dpdk/set-admin-state [interface] up | down
1203 Change the admin state for DPDK interface to up or down. If in‐
1204 terface is not specified, then it applies to all DPDK ports.
1205 netdev-dpdk/detach pci-address
1207 Detaches device with corresponding pci-address from DPDK. This
1208 command can be used to detach device if it wasn't detached auto‐
1209 matically after port deletion. Refer to the documentation for
1210 details and instructions.
1211 netdev-dpdk/get-mempool-info [interface]
1213 Prints the debug information about memory pool used by DPDK in‐
1214 terface. If called without arguments, information of all the
1215 available mempools will be printed. For additional mempool sta‐
1216 tistics enable CONFIG_RTE_LIBRTE_MEMPOOL_DEBUG while building
1217 DPDK.
1218 ODP-EXECUTE COMMANDS
1220 These commands manage the "odp-execute" component.
1221 odp-execute/action-impl-show
1224 Lists the actions implementations that are available and high‐
1225 lights the currently enabled one.
1226 odp-execute/action-impl-set action_impl
1228 Sets the action implementation to any available implementation.
1229 By default "scalar" is used.
1230 DATAPATH DEBUGGING COMMANDS
1232 These commands query and modify datapaths. They are are similar to
1233 ovs-dpctl(8) commands. dpif/show has the additional functionality, be‐
1234 yond dpctl/show of printing OpenFlow port numbers. The other commands
1235 are redundant and will be removed in a future release.
1236 dpif/dump-dps
1238 Prints the name of each configured datapath on a separate line.
1239 dpif/show
1241 Prints a summary of configured datapaths, including statistics
1242 and a list of connected ports. The port information includes
1243 the OpenFlow port number, datapath port number, and the type.
1244 (The local port is identified as OpenFlow port 65534.)
1245 dpif/dump-flows [-m] dp
1247 Prints to the console all flow entries in datapath dp's flow ta‐
1248 ble. Without -m, output omits match fields that a flow wildcards
1249 entirely; with -m output includes all wildcarded fields.
1250 This command is primarily useful for debugging Open vSwitch.
1252 The flow table entries that it displays are not OpenFlow flow
1253 entries. Instead, they are different and considerably simpler
1254 flows maintained by the datapath module. If you wish to see the
1255 OpenFlow flow entries, use ovs-ofctl dump-flows.
1256 dpif/del-flows dp
1258 Deletes all flow entries from datapath dp's flow table and un‐
1259 derlying datapath implementation (e.g., kernel datapath module).
1260 This command is primarily useful for debugging Open vSwitch. As
1262 discussed in dpif/dump-flows, these entries are not OpenFlow
1263 flow entries.
1264 OFPROTO COMMANDS
1266 These commands manage the core OpenFlow switch implementation (called
1267 ofproto).
1268 ofproto/list
1270 Lists the names of the running ofproto instances. These are the
1271 names that may be used on ofproto/trace.
1272 ofproto/trace [options] [dpname] odp_flow [packet]
1274 ofproto/trace [options] bridge br_flow [packet]]
1275 ofproto/trace-packet-out [options] [dpname] odp_flow [packet] actions
1276 ofproto/trace-packet-out [options] bridge br_flow [packet] actions
1277 Traces the path of an imaginary packet through switch and re‐
1278 ports the path that it took. The initial treatment of the
1279 packet varies based on the command:
1280 • ofproto/trace looks the packet up in the OpenFlow flow
1282 table, as if the packet had arrived on an OpenFlow port.
1283 • ofproto/trace-packet-out applies the specified OpenFlow
1285 actions, as if the packet, flow, and actions had been
1286 specified in an OpenFlow ``packet-out'' request.
1287 The packet's headers (e.g. source and destination) and metadata
1289 (e.g. input port), together called its ``flow,'' are usually all
1290 that matter for the purpose of tracing a packet. You can spec‐
1291 ify the flow in the following ways:
1292 dpname odp_flow
1294 odp_flow is a flow in the form printed by ovs-dpctl(8)'s
1295 dump-flows command. If all of your bridges have the same
1296 type, which is the common case, then you can omit dpname,
1297 but if you have bridges of different types (say, both
1298 ovs-netdev and ovs-system), then you need to specify a
1299 dpname to disambiguate.
1300 bridge br_flow
1302 br_flow is a flow in the form similar to that accepted by
1303 ovs-ofctl(8)'s add-flow command. (This is not an Open‐
1304 Flow flow: besides other differences, it never contains
1305 wildcards.) bridge names of the bridge through which
1306 br_flow should be traced.
1307 These commands support the following options:
1309 --generate
1311 Generate a packet from the flow (see below for more in‐
1312 formation).
1313 --l7 payload
1315 --l7-len length
1316 Accepted only with --generate (see below for more infor‐
1317 mation).
1318 --consistent
1320 Accepted by ofproto-trace-packet-out only. With this op‐
1321 tion, the command rejects actions that are inconsistent
1322 with the specified packet. (An example of an inconsis‐
1323 tency is attempting to strip the VLAN tag from a packet
1324 that does not have a VLAN tag.) Open vSwitch ignores
1325 most forms of inconsistency in OpenFlow 1.0 and rejects
1326 inconsistencies in later versions of OpenFlow. The op‐
1327 tion is necessary because the command does not ordinarily
1328 imply a particular OpenFlow version. One exception is
1329 that, when actions includes an action that only OpenFlow
1330 1.1 and later supports (such as push_vlan), --consistent
1331 is automatically enabled.
1332 --ct-next flags
1334 When the traced flow triggers conntrack actions, of‐
1335 proto/trace will automatically trace the forked packet
1336 processing pipeline with user specified ct_state. This
1337 option sets the ct_state flags that the conntrack module
1338 will report. The flags must be a comma- or space-sepa‐
1339 rated list of the following connection tracking flags:
1340 • trk: Include to indicate connection tracking has
1342 taken place.
1343 • new: Include to indicate a new flow.
1345 • est: Include to indicate an established flow.
1347 • rel: Include to indicate a related flow.
1349 • rpl: Include to indicate a reply flow.
1351 • inv: Include to indicate a connection entry in a
1353 bad state.
1354 • dnat: Include to indicate a packet whose destina‐
1356 tion IP address has been changed.
1357 • snat: Include to indicate a packet whose source IP
1359 address has been changed.
1360 When --ct-next is unspecified, or when there are fewer
1362 --ct-next options than ct actions, the flags default to
1363 trk,new.
1364 Most commonly, one specifies only a flow, using one of the forms
1366 above, but sometimes one might need to specify an actual packet
1367 instead of just a flow:
1368 Side effects.
1370 Some actions have side effects. For example, the normal
1371 action can update the MAC learning table, and the learn
1372 action can change OpenFlow tables. The trace commands
1373 only perform side effects when a packet is specified. If
1374 you want side effects to take place, then you must supply
1375 a packet.
1376 (Output actions are obviously side effects too, but the
1378 trace commands never execute them, even when one speci‐
1379 fies a packet.)
1380 Incomplete information.
1382 Most of the time, Open vSwitch can figure out everything
1383 about the path of a packet using just the flow, but in
1384 some special circumstances it needs to look at parts of
1385 the packet that are not included in the flow. When this
1386 is the case, and you do not supply a packet, then a trace
1387 command will tell you it needs a packet.
1388 If you wish to include a packet as part of a trace operation,
1390 there are two ways to do it:
1391 --generate
1393 This option, added to one of the ways to specify a flow
1394 already described, causes Open vSwitch to internally gen‐
1395 erate a packet with the flow described and then to use
1396 that packet. If your goal is to execute side effects,
1397 then --generate is the easiest way to do it, but --gener‐
1398 ate is not a good way to fill in incomplete information,
1399 because it generates packets based on only the flow in‐
1400 formation, which means that the packets really do not
1401 have any more information than the flow.
1402 By default, for protocols that allow arbitrary L7 pay‐
1404 loads, the generated packet has 64 bytes of payload. Use
1405 --l7-len to change the payload length, or --l7 to specify
1406 the exact contents of the payload.
1407 packet This form supplies an explicit packet as a sequence of
1409 hex digits. An Ethernet frame is at least 14 bytes long,
1410 so there must be at least 28 hex digits. Obviously, it
1411 is inconvenient to type in the hex digits by hand, so the
1412 ovs-pcap(1) and ovs-tcpundump(1) utilities provide easier
1413 ways.
1414 With this form, packet headers are extracted directly
1416 from packet, so the odp_flow or br_flow should specify
1417 only metadata. The metadata can be:
1418 skb_priority
1420 Packet QoS priority.
1421 pkt_mark
1423 Mark of the packet.
1424 ct_state
1426 Connection state of the packet.
1427 ct_zone
1429 Connection tracking zone for packet.
1430 ct_mark
1432 Connection mark of the packet.
1433 ct_label
1435 Connection label of the packet.
1436 tun_id The tunnel ID on which the packet arrived.
1438 in_port
1440 The port on which the packet arrived.
1441 The in_port value is kernel datapath port number for the first
1443 format and OpenFlow port number for the second format. The num‐
1444 bering of these two types of port usually differs and there is
1445 no relationship.
1446 Usage examples:
1448 Trace an unicast ICMP echo request on ingress port 1 to destination
1450 MAC 00:00:5E:00:53:01
1451 ofproto/trace br in_port=1,icmp,icmp_type=8,\
1452 dl_dst=00:00:5E:00:53:01
1453 Trace an unicast ICMP echo reply on ingress port 1 to destination
1455 MAC 00:00:5E:00:53:01
1456 ofproto/trace br in_port=1,icmp,icmp_type=0,\
1457 dl_dst=00:00:5E:00:53:01
1458 Trace an ARP request on ingress port 1
1460 ofproto/trace br in_port=1,arp,arp_op=1
1461 Trace an ARP reply on ingress port 1
1463 ofproto/trace br in_port=1,arp,arp_op=2
1464 VLOG COMMANDS
1466 These commands manage ovs-vswitchd's logging settings.
1467 vlog/set [spec]
1469 Sets logging levels. Without any spec, sets the log level for
1470 every module and destination to dbg. Otherwise, spec is a list
1471 of words separated by spaces or commas or colons, up to one from
1472 each category below:
1473 • A valid module name, as displayed by the vlog/list com‐
1475 mand on ovs-appctl(8), limits the log level change to the
1476 specified module.
1477 • syslog, console, or file, to limit the log level change
1479 to only to the system log, to the console, or to a file,
1480 respectively.
1481 On Windows platform, syslog is accepted as a word and is
1483 only useful along with the --syslog-target option (the
1484 word has no effect otherwise).
1485 • off, emer, err, warn, info, or dbg, to control the log
1487 level. Messages of the given severity or higher will be
1488 logged, and messages of lower severity will be filtered
1489 out. off filters out all messages. See ovs-appctl(8)
1490 for a definition of each log level.
1491 Case is not significant within spec.
1493 Regardless of the log levels set for file, logging to a file
1495 will not take place unless ovs-vswitchd was invoked with the
1496 --log-file option.
1497 For compatibility with older versions of OVS, any is accepted as
1499 a word but has no effect.
1500 vlog/set PATTERN:destination:pattern
1502 Sets the log pattern for destination to pattern. Refer to
1503 ovs-appctl(8) for a description of the valid syntax for pattern.
1504 vlog/list
1506 Lists the supported logging modules and their current levels.
1507 vlog/list-pattern
1509 Lists logging patterns used for each destination.
1510 vlog/close
1512 Causes ovs-vswitchd to close its log file, if it is open. (Use
1513 vlog/reopen to reopen it later.)
1514 vlog/reopen
1516 Causes ovs-vswitchd to close its log file, if it is open, and
1517 then reopen it. (This is useful after rotating log files, to
1518 cause a new log file to be used.)
1519 This has no effect unless ovs-vswitchd was invoked with the
1521 --log-file option.
1522 vlog/disable-rate-limit [module]...
1524 vlog/enable-rate-limit [module]...
1525 By default, ovs-vswitchd limits the rate at which certain mes‐
1526 sages can be logged. When a message would appear more fre‐
1527 quently than the limit, it is suppressed. This saves disk
1528 space, makes logs easier to read, and speeds up execution, but
1529 occasionally troubleshooting requires more detail. Therefore,
1530 vlog/disable-rate-limit allows rate limits to be disabled at the
1531 level of an individual log module. Specify one or more module
1532 names, as displayed by the vlog/list command. Specifying either
1533 no module names at all or the keyword any disables rate limits
1534 for every log module.
1535 The vlog/enable-rate-limit command, whose syntax is the same as
1537 vlog/disable-rate-limit, can be used to re-enable a rate limit
1538 that was previously disabled.
1539 MEMORY COMMANDS
1541 These commands report memory usage.
1542 memory/show
1544 Displays some basic statistics about ovs-vswitchd's memory us‐
1545 age. ovs-vswitchd also logs this information soon after startup
1546 and periodically as its memory consumption grows.
1547 COVERAGE COMMANDS
1549 These commands manage ovs-vswitchd's ``coverage counters,'' which count
1550 the number of times particular events occur during a daemon's runtime.
1551 In addition to these commands, ovs-vswitchd automatically logs coverage
1552 counter values, at INFO level, when it detects that the daemon's main
1553 loop takes unusually long to run.
1554 Coverage counters are useful mainly for performance analysis and debug‐
1556 ging.
1557 coverage/show
1559 Displays the averaged per-second rates for the last few seconds,
1560 the last minute and the last hour, and the total counts of all
1561 of the coverage counters.
1562 coverage/read-counter counter
1564 Displays the total count for the given coverage counter.
1565 OPENVSWITCH TUNNELING COMMANDS
1567 These commands query and modify OVS tunnel components.
1568 ovs/route/add ipv4_address/plen output_bridge [GW]
1570 Adds ipv4_address/plen route to vswitchd routing table. out‐
1571 put_bridge needs to be OVS bridge name. This command is useful
1572 if OVS cached routes does not look right.
1573 ovs/route/show
1575 Print all routes in OVS routing table, This includes routes
1576 cached from system routing table and user configured routes.
1577 ovs/route/del ipv4_address/plen
1579 Delete ipv4_address/plen route from OVS routing table.
1580 tnl/neigh/show
1582 tnl/arp/show
1584 OVS builds ARP cache by snooping are messages. This command
1585 shows ARP cache table.
1586 tnl/neigh/set bridge ip mac
1588 tnl/arp/set bridge ip mac
1590 Adds or modifies an ARP cache entry in bridge, mapping ip to
1591 mac.
1592 tnl/neigh/flush
1594 tnl/arp/flush
1596 Flush ARP table.
1597 tnl/neigh/aging [seconds]
1599 tnl/arp/aging [seconds]
1601 Changes the aging time. The accepted values of seconds are be‐
1602 tween 1 and 3600. The new entries will get the value as speci‐
1603 fied in seconds. For the existing entries, the aging time is up‐
1604 dated only if the current expiration is greater than seconds.
1605 If used without arguments, it prints the current aging value.
1607 tnl/egress_port_range [num1] [num2]
1609 Set range for UDP source port used for UDP based Tunnels. For
1610 example VxLAN. If case of zero arguments this command prints
1611 current range in use.
1612
1614 This section documents aspects of OpenFlow for which the OpenFlow spec‐
1615 ification requires documentation.
1616 Packet buffering.
1618 The OpenFlow specification, version 1.2, says:
1619 Switches that implement buffering are expected to expose,
1621 through documentation, both the amount of available buffering,
1622 and the length of time before buffers may be reused.
1623 Open vSwitch does not maintains any packet buffers.
1625 Bundle lifetime
1627 The OpenFlow specification, version 1.4, says:
1628 If the switch does not receive any OFPT_BUNDLE_CONTROL or
1630 OFPT_BUNDLE_ADD_MESSAGE message for an opened bundle_id for a
1631 switch defined time greater than 1s, it may send an ofp_er‐
1632 ror_msg with OFPET_BUNDLE_FAILED type and OFPBFC_TIMEOUT code.
1633 If the switch does not receive any new message in a bundle apart
1634 from echo request and replies for a switch defined time greater
1635 than 1s, it may send an ofp_error_msg with OFPET_BUNDLE_FAILED
1636 type and OFPBFC_TIMEOUT code.
1637 Open vSwitch implements default idle bundle lifetime of 10 seconds.
1639 (This is configurable via other-config:bundle-idle-timeout in the
1640 Open_vSwitch table. See ovs-vswitchd.conf.db(5) for details.)
1641
1643 We believe these limits to be accurate as of this writing. These lim‐
1644 its assume the use of the Linux kernel datapath.
1645 • ovs-vswitchd started through ovs-ctl(8) provides a limit of
1647 65535 file descriptors. The limits on the number of bridges and
1648 ports is decided by the availability of file descriptors. With
1649 the Linux kernel datapath, creation of a single bridge consumes
1650 three file descriptors and each port consumes one additional
1651 file descriptor. Other platforms may have different limita‐
1652 tions.
1653 • 8,192 MAC learning entries per bridge, by default. (This is
1655 configurable via other-config:mac-table-size in the Bridge ta‐
1656 ble. See ovs-vswitchd.conf.db(5) for details.)
1657 • Kernel flows are limited only by memory available to the kernel.
1659 Performance will degrade beyond 1,048,576 kernel flows per
1660 bridge with a 32-bit kernel, beyond 262,144 with a 64-bit ker‐
1661 nel. (ovs-vswitchd should never install anywhere near that many
1662 flows.)
1663 • OpenFlow flows are limited only by available memory. Perfor‐
1665 mance is linear in the number of unique wildcard patterns. That
1666 is, an OpenFlow table that contains many flows that all match on
1667 the same fields in the same way has a constant-time lookup, but
1668 a table that contains many flows that match on different fields
1669 requires lookup time linear in the number of flows.
1670 • 255 ports per bridge participating in 802.1D Spanning Tree Pro‐
1672 tocol.
1673 • 32 mirrors per bridge.
1675 • 15 bytes for the name of a port, for ports implemented in the
1677 Linux kernel. Ports implemented in userspace, such as patch
1678 ports, do not have an arbitrary length limitation. OpenFlow
1679 also limit port names to 15 bytes.
1680
1682 ovs-appctl(8), ovsdb-server(1).
1683Open vSwitch 3.1.1 ovs-vswitchd(8)