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