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. The default is unix:/var/run/openvswitch/db.sock. The
17 following forms are accepted:
18 ssl:ip:port
20 The specified SSL port on the host at the given ip, which must
21 be expressed as an IP address (not a DNS name). The --pri‐
22 vate-key, --certificate, and --ca-cert options are mandatory
23 when this form is used.
24 tcp:ip:port
26 Connect to the given TCP port on ip.
27 unix:file
29 Connect to the Unix domain server socket named file.
30 pssl:port[:ip]
32 Listen on the given SSL port for a connection. By default, con‐
33 nections are not bound to a particular local IP address, but
34 specifying ip limits connections to those from the given ip.
35 The --private-key, --certificate, and --ca-cert options are
36 mandatory when this form is used.
37 ptcp:port[:ip]
39 Listen on the given TCP port for a connection. By default, con‐
40 nections are not bound to a particular local IP address, but ip
41 may be specified to listen only for connections to the given ip.
42 punix:file
44 Listen on the Unix domain server socket named file for a connec‐
45 tion.
46 ovs-vswitchd retrieves its configuration from database at startup. It
48 sets up Open vSwitch datapaths and then operates switching across each
49 bridge described in its configuration files. As the database changes,
50 ovs-vswitchd automatically updates its configuration to match.
51 Upon receipt of a SIGHUP signal, ovs-vswitchd reopens its log file, if
53 one was specified on the command line.
54 ovs-vswitchd switches may be configured with any of the following fea‐
56 tures:
57 · L2 switching with MAC learning.
59 · NIC bonding with automatic fail-over and source MAC-based TX
61 load balancing ("SLB").
62 · 802.1Q VLAN support.
64 · Port mirroring, with optional VLAN tagging.
66 · NetFlow v5 flow logging.
68 · sFlow(R) monitoring.
70 · Connectivity to an external OpenFlow controller, such as NOX.
72 Only a single instance of ovs-vswitchd is intended to run at a time. A
74 single ovs-vswitchd can manage any number of switch instances, up to
75 the maximum number of supported Open vSwitch datapaths.
76 ovs-vswitchd does all the necessary management of Open vSwitch data‐
78 paths itself. Thus, external tools, such ovs-dpctl(8), are not needed
79 for managing datapaths in conjunction with ovs-vswitchd, and their use
80 to modify datapaths when ovs-vswitchd is running can interfere with its
81 operation. (ovs-dpctl may still be useful for diagnostics.)
82 An Open vSwitch datapath kernel module must be loaded for ovs-vswitchd
84 to be useful. Please refer to the INSTALL.Linux file included in the
85 Open vSwitch distribution for instructions on how to build and load the
86 Open vSwitch kernel module.
87
89 --mlockall
90 Causes ovs-vswitchd to call the mlockall() function, to attempt
91 to lock all of its process memory into physical RAM, preventing
92 the kernel from paging any of its memory to disk. This helps to
93 avoid networking interruptions due to system memory pressure.
94 Some systems do not support mlockall() at all, and other systems
96 only allow privileged users, such as the superuser, to use it.
97 ovs-vswitchd emits a log message if mlockall() is unavailable or
98 unsuccessful.
99 --pidfile[=pidfile]
101 Causes a file (by default, ovs-vswitchd.pid) to be created indi‐
102 cating the PID of the running process. If the pidfile argument
103 is not specified, or if it does not begin with /, then it is
104 created in /var/run/openvswitch.
105 If --pidfile is not specified, no pidfile is created.
107 --overwrite-pidfile
109 By default, when --pidfile is specified and the specified pid‐
110 file already exists and is locked by a running process,
111 ovs-vswitchd refuses to start. Specify --overwrite-pidfile to
112 cause it to instead overwrite the pidfile.
113 When --pidfile is not specified, this option has no effect.
115 --detach
117 Causes ovs-vswitchd to detach itself from the foreground session
118 and run as a background process. ovs-vswitchd detaches only
119 after it has connected to the database, retrieved the initial
120 configuration, and set up that configuration.
121 --monitor
123 Creates an additional process to monitor the ovs-vswitchd dae‐
124 mon. If the daemon dies due to a signal that indicates a pro‐
125 gramming error (e.g. SIGSEGV, SIGABRT), then the monitor process
126 starts a new copy of it. If the daemon die or exits for another
127 reason, the monitor process exits.
128 This option is normally used with --detach, but it also func‐
130 tions without it.
131 --no-chdir
133 By default, when --detach is specified, ovs-vswitchd changes its
134 current working directory to the root directory after it
135 detaches. Otherwise, invoking ovs-vswitchd from a carelessly
136 chosen directory would prevent the administrator from unmounting
137 the file system that holds that directory.
138 Specifying --no-chdir suppresses this behavior, preventing
140 ovs-vswitchd from changing its current working directory. This
141 may be useful for collecting core files, since it is common
142 behavior to write core dumps into the current working directory
143 and the root directory is not a good directory to use.
144 This option has no effect when --detach is not specified.
146 Public Key Infrastructure Options
148 -p privkey.pem
149 --private-key=privkey.pem
150 Specifies a PEM file containing the private key used as
151 ovs-vswitchd's identity for outgoing SSL connections.
152 -c cert.pem
154 --certificate=cert.pem
155 Specifies a PEM file containing a certificate that certifies the
156 private key specified on -p or --private-key to be trustworthy.
157 The certificate must be signed by the certificate authority (CA)
158 that the peer in SSL connections will use to verify it.
159 -C cacert.pem
161 --ca-cert=cacert.pem
162 Specifies a PEM file containing the CA certificate that
163 ovs-vswitchd should use to verify certificates presented to it
164 by SSL peers. (This may be the same certificate that SSL peers
165 use to verify the certificate specified on -c or --certificate,
166 or it may be a different one, depending on the PKI design in
167 use.)
168 -C none
170 --ca-cert=none
171 Disables verification of certificates presented by SSL peers.
172 This introduces a security risk, because it means that certifi‐
173 cates cannot be verified to be those of known trusted hosts.
174 --bootstrap-ca-cert=cacert.pem
176 When cacert.pem exists, this option has the same effect as -C or
177 --ca-cert. If it does not exist, then ovs-vswitchd will attempt
178 to obtain the CA certificate from the SSL peer on its first SSL
179 connection and save it to the named PEM file. If it is success‐
180 ful, it will immediately drop the connection and reconnect, and
181 from then on all SSL connections must be authenticated by a cer‐
182 tificate signed by the CA certificate thus obtained.
183 This option exposes the SSL connection to a man-in-the-middle
185 attack obtaining the initial CA certificate, but it may be use‐
186 ful for bootstrapping.
187 This option is only useful if the SSL peer sends its CA certifi‐
189 cate as part of the SSL certificate chain. The SSL protocol
190 does not require the server to send the CA certificate, but
191 ovs-controller(8) can be configured to do so with the
192 --peer-ca-cert option.
193 This option is mutually exclusive with -C and --ca-cert.
195 -v[spec]
197 --verbose=[spec]
198 Sets logging levels. Without any spec, sets the log level for
199 every module and facility to dbg. Otherwise, spec is a list of
200 words separated by spaces or commas or colons, up to one from
201 each category below:
202 · A valid module name, as displayed by the vlog/list com‐
204 mand on ovs-appctl(8), limits the log level change to the
205 specified module.
206 · syslog, console, or file, to limit the log level change
208 to only to the system log, to the console, or to a file,
209 respectively.
210 · off, emer, err, warn, info, or dbg, to control the log
212 level. Messages of the given severity or higher will be
213 logged, and messages of lower severity will be filtered
214 out. off filters out all messages. See ovs-appctl(8)
215 for a definition of each log level.
216 Case is not significant within spec.
218 Regardless of the log levels set for file, logging to a file
220 will not take place unless --log-file is also specified (see
221 below).
222 For compatibility with older versions of OVS, any is accepted as
224 a word but has no effect.
225 -v
227 --verbose
228 Sets the maximum logging verbosity level, equivalent to --ver‐
229 bose=dbg.
230 --log-file[=file]
232 Enables logging to a file. If file is specified, then it is
233 used as the exact name for the log file. The default log file
234 name used if file is omitted is /var/log/open‐
235 vswitch/ovs-vswitchd.log.
236 -h
238 --help Prints a brief help message to the console.
239 -V
241 --version
242 Prints version information to the console.
243
245 ovs-appctl(8) can send commands to a running ovs-vswitchd process. The
246 currently supported commands are described below. The command descrip‐
247 tions assume an understanding of how to configure Open vSwitch.
248 GENERAL COMMANDS
250 exit Causes ovs-vswitchd to gracefully terminate.
251 qos/show interface
253 Queries the kernel for Quality of Service configuration and sta‐
254 tistics associated with the given interface.
255 bfd/show [interface]
257 Displays detailed information about Bidirectional Forwarding
258 Detection configured on interface. If interface is not speci‐
259 fied, then displays detailed information about all interfaces
260 with BFD enabled.
261 bfd/set-forwarding [interface] status
263 Force the fault status of the BFD module on interface (or all
264 interfaces if none is given) to be status. status can be
265 "true", "false", or "normal" which reverts to the standard
266 behavior.
267 cfm/show [interface]
269 Displays detailed information about Connectivity Fault Manage‐
270 ment configured on interface. If interface is not specified,
271 then displays detailed information about all interfaces with CFM
272 enabled.
273 cfm/set-fault [interface] status
275 Force the fault status of the CFM module on interface (or all
276 interfaces if none is given) to be status. status can be
277 "true", "false", or "normal" which reverts to the standard
278 behavior.
279 stp/tcn [bridge]
281 Forces a topology change event on bridge if it's running STP.
282 This may cause it to send Topology Change Notifications to its
283 peers and flush its MAC table.. If no bridge is given, forces a
284 topology change event on all bridges.
285 BRIDGE COMMANDS
287 These commands manage bridges.
288 fdb/flush [bridge]
290 Flushes bridge MAC address learning table, or all learning
291 tables if no bridge is given.
292 fdb/show bridge
294 Lists each MAC address/VLAN pair learned by the specified
295 bridge, along with the port on which it was learned and the age
296 of the entry, in seconds.
297 bridge/reconnect [bridge]
299 Makes bridge drop all of its OpenFlow controller connections and
300 reconnect. If bridge is not specified, then all bridges drop
301 their controller connections and reconnect.
302 This command might be useful for debugging OpenFlow controller
304 issues.
305 bridge/dump-flows bridge
307 Lists all flows in bridge, including those normally hidden to
308 commands such as ovs-ofctl dump-flows. Flows set up by mecha‐
309 nisms such as in-band control and fail-open are hidden from the
310 controller since it is not allowed to modify or override them.
311 BOND COMMANDS
313 These commands manage bonded ports on an Open vSwitch's bridges. To
314 understand some of these commands, it is important to understand a
315 detail of the bonding implementation called ``source load balancing''
316 (SLB). Instead of directly assigning Ethernet source addresses to
317 slaves, the bonding implementation computes a function that maps an
318 48-bit Ethernet source addresses into an 8-bit value (a ``MAC hash''
319 value). All of the Ethernet addresses that map to a single 8-bit value
320 are then assigned to a single slave.
321 bond/list
323 Lists all of the bonds, and their slaves, on each bridge.
324 bond/show [port]
326 Lists all of the bond-specific information (updelay, downdelay,
327 time until the next rebalance) about the given bonded port, or
328 all bonded ports if no port is given. Also lists information
329 about each slave: whether it is enabled or disabled, the time to
330 completion of an updelay or downdelay if one is in progress,
331 whether it is the active slave, the hashes assigned to the
332 slave. Any LACP information related to this bond may be found
333 using the lacp/show command.
334 bond/migrate port hash slave
336 Only valid for SLB bonds. Assigns a given MAC hash to a new
337 slave. port specifies the bond port, hash the MAC hash to be
338 migrated (as a decimal number between 0 and 255), and slave the
339 new slave to be assigned.
340 The reassignment is not permanent: rebalancing or fail-over will
342 cause the MAC hash to be shifted to a new slave in the usual
343 manner.
344 A MAC hash cannot be migrated to a disabled slave.
346 bond/set-active-slave port slave
348 Sets slave as the active slave on port. slave must currently be
349 enabled.
350 The setting is not permanent: a new active slave will be
352 selected if slave becomes disabled.
353 bond/enable-slave port slave
355 bond/disable-slave port slave
356 Enables (or disables) slave on the given bond port, skipping any
357 updelay (or downdelay).
358 This setting is not permanent: it persists only until the car‐
360 rier status of slave changes.
361 bond/hash mac [vlan] [basis]
363 Returns the hash value which would be used for mac with vlan and
364 basis if specified.
365 lacp/show [port]
367 Lists all of the LACP related information about the given port:
368 active or passive, aggregation key, system id, and system prior‐
369 ity. Also lists information about each slave: whether it is
370 enabled or disabled, whether it is attached or detached, port id
371 and priority, actor information, and partner information. If
372 port is not specified, then displays detailed information about
373 all interfaces with CFM enabled.
374 DATAPATH COMMANDS
376 These commands manage logical datapaths. They are are similar to the
377 equivalent ovs-dpctl commands.
378 dpif/dump-dps
380 Prints the name of each configured datapath on a separate line.
381 dpif/show
383 Prints a summary of configured datapaths, including statistics
384 and a list of connected ports. The port information includes
385 the OpenFlow port number, datapath port number, and the type.
386 (The local port is identified as OpenFlow port 65534.)
387 dpif/dump-flows dp
389 Prints to the console all flow entries in datapath dp's flow ta‐
390 ble.
391 This command is primarily useful for debugging Open vSwitch.
393 The flow table entries that it displays are not OpenFlow flow
394 entries. Instead, they are different and considerably simpler
395 flows maintained by the datapath module. If you wish to see the
396 OpenFlow flow entries, use ovs-ofctl dump-flows.
397 dpif/del-flows dp
399 Deletes all flow entries from datapath dp's flow table and
400 underlying datapath implementation (e.g., kernel datapath mod‐
401 ule).
402 This command is primarily useful for debugging Open vSwitch. As
404 discussed in dpif/dump-flows, these entries are not OpenFlow
405 flow entries.
406 OFPROTO COMMANDS
408 These commands manage the core OpenFlow switch implementation (called
409 ofproto).
410 ofproto/list
412 Lists the names of the running ofproto instances. These are the
413 names that may be used on ofproto/trace.
414 ofproto/trace [dpname] odp_flow [-generate | packet]
416 ofproto/trace bridge br_flow [-generate | packet]
417 Traces the path of an imaginary packet through switch and
418 reports the path that it took. The packet's headers (e.g.
419 source and destination) and metadata (e.g. input port), together
420 called its ``flow,'' are usually all that matter for this pur‐
421 pose. You can specify the flow in the following ways:
422 dpname odp_flow
424 odp_flow is a flow in the form printed by ovs-dpctl(8)'s
425 dump-flows command. If all of your bridges have the same
426 type, which is the common case, then you can omit dpname,
427 but if you have bridges of different types (say, both
428 ovs-netdev and ovs-system), then you need to specify a
429 dpname to disambiguate.
430 bridge br_flow
432 br_flow is a flow in the form similar to that accepted by
433 ovs-ofctl(8)'s add-flow command. (This is not an Open‐
434 Flow flow: besides other differences, it never contains
435 wildcards.) bridge names of the bridge through which
436 br_flow should be traced.
437 Most commonly, one specifies only a flow, using one of the forms
439 above, but sometimes one might need to specify an actual packet
440 instead of just a flow:
441 Side effects.
443 Some actions have side effects. For example, the normal
444 action can update the MAC learning table, and the learn
445 action can change OpenFlow tables. ofproto/trace only
446 performs side effects when a packet is specified. If you
447 want side effects to take place, then you must supply a
448 packet.
449 (Output actions are obviously side effects too, but
451 ofproto/trace never executes them, even when one speci‐
452 fies a packet.)
453 Incomplete information.
455 Most of the time, Open vSwitch can figure out everything
456 about the path of a packet using just the flow, but in
457 some special circumstances it needs to look at parts of
458 the packet that are not included in the flow. When this
459 is the case, and you do not supply a packet, then
460 ofproto/trace will tell you it needs a packet.
461 If you wish to include a packet as part of the ofproto/trace
463 operation, there are two ways to do it:
464 -generate
466 This option, added to one of the ways to specify a flow
467 already described, causes Open vSwitch to internally gen‐
468 erate a packet with the flow described and then to use
469 that packet. If your goal is to execute side effects,
470 then -generate is the easiest way to do it, but -generate
471 is not a good way to fill in incomplete information,
472 because it generates packets based on only the flow
473 information, which means that the packets really do not
474 have any more information than the flow.
475 packet This form supplies an explicit packet as a sequence of
477 hex digits. An Ethernet frame is at least 14 bytes long,
478 so there must be at least 28 hex digits. Obviously, it
479 is inconvenient to type in the hex digits by hand, so the
480 ovs-pcap(1) and ovs-tcpundump(1) utilities provide easier
481 ways.
482 With this form, packet headers are extracted directly
484 from packet, so the odp_flow or br_flow should specify
485 only metadata. The metadata can be:
486 skb_priority
488 Packet QoS priority.
489 pkt_mark
491 Mark of the packet.
492 tun_id The tunnel ID on which the packet arrived.
494 in_port
496 The port on which the packet arrived.
497 The in_port value is kernel datapath port number for the first
498 format and OpenFlow port number for the second format. The num‐
499 bering of these two types of port usually differs and there is
500 no relationship.
501 ofproto/self-check [switch]
503 Runs an internal consistency check on switch, if specified, oth‐
504 erwise on all ofproto instances, and responds with a brief sum‐
505 mary of the results. If the summary reports any errors, then
506 the Open vSwitch logs should contain more detailed information.
507 Please pass along errors reported by this command to the Open
508 vSwitch developers as bugs.
509 VLOG COMMANDS
511 These commands manage ovs-vswitchd's logging settings.
512 vlog/set [spec]
514 Sets logging levels. Without any spec, sets the log level for
515 every module and facility to dbg. Otherwise, spec is a list of
516 words separated by spaces or commas or colons, up to one from
517 each category below:
518 · A valid module name, as displayed by the vlog/list com‐
520 mand on ovs-appctl(8), limits the log level change to the
521 specified module.
522 · syslog, console, or file, to limit the log level change
524 to only to the system log, to the console, or to a file,
525 respectively.
526 · off, emer, err, warn, info, or dbg, to control the log
528 level. Messages of the given severity or higher will be
529 logged, and messages of lower severity will be filtered
530 out. off filters out all messages. See ovs-appctl(8)
531 for a definition of each log level.
532 Case is not significant within spec.
534 Regardless of the log levels set for file, logging to a file
536 will not take place unless ovs-vswitchd was invoked with the
537 --log-file option.
538 For compatibility with older versions of OVS, any is accepted as
540 a word but has no effect.
541 vlog/set PATTERN:facility:pattern
543 Sets the log pattern for facility to pattern. Refer to
544 ovs-appctl(8) for a description of the valid syntax for pattern.
545 vlog/list
547 Lists the supported logging modules and their current levels.
548 vlog/reopen
550 Causes ovs-vswitchd to close and reopen its log file. (This is
551 useful after rotating log files, to cause a new log file to be
552 used.)
553 This has no effect unless ovs-vswitchd was invoked with the
555 --log-file option.
556 vlog/disable-rate-limit [module]...
558 vlog/enable-rate-limit [module]...
559 By default, ovs-vswitchd limits the rate at which certain mes‐
560 sages can be logged. When a message would appear more fre‐
561 quently than the limit, it is suppressed. This saves disk
562 space, makes logs easier to read, and speeds up execution, but
563 occasionally troubleshooting requires more detail. Therefore,
564 vlog/disable-rate-limit allows rate limits to be disabled at the
565 level of an individual log module. Specify one or more module
566 names, as displayed by the vlog/list command. Specifying either
567 no module names at all or the keyword any disables rate limits
568 for every log module.
569 The vlog/enable-rate-limit command, whose syntax is the same as
571 vlog/disable-rate-limit, can be used to re-enable a rate limit
572 that was previously disabled.
573 MEMORY COMMANDS
575 These commands report memory usage.
576 memory/show
578 Displays some basic statistics about ovs-vswitchd's memory
579 usage. ovs-vswitchd also logs this information soon after
580 startup and periodically as its memory consumption grows.
581 COVERAGE COMMANDS
583 These commands manage ovs-vswitchd's ``coverage counters,'' which count
584 the number of times particular events occur during a daemon's runtime.
585 In addition to these commands, ovs-vswitchd automatically logs coverage
586 counter values, at INFO level, when it detects that the daemon's main
587 loop takes unusually long to run.
588 Coverage counters are useful mainly for performance analysis and debug‐
590 ging.
591 coverage/show
593 Displays the values of all of the coverage counters.
594
596 This section documents aspects of OpenFlow for which the OpenFlow spec‐
597 ification requires documentation.
598 Packet buffering.
600 The OpenFlow specification, version 1.2, says:
601 Switches that implement buffering are expected to expose,
603 through documentation, both the amount of available buffering,
604 and the length of time before buffers may be reused.
605 Open vSwitch maintains a separate set of 256 packet buffers for each
607 OpenFlow connection. Any given packet buffer is preserved until it is
608 referenced by an OFPT_FLOW_MOD or OFPT_PACKET_OUT request or for 5 sec‐
609 onds, whichever comes first.
610
612 We believe these limits to be accurate as of this writing. These lim‐
613 its assume the use of the Linux kernel datapath.
614 · ovs-vswitchd started through ovs-ctl(8) provides a limit of 7500
616 file descriptors. The limits on the number of bridges and ports
617 is decided by the availability of file descriptors. With the
618 Linux kernel datapath, creation of a single bridge consumes 3
619 file descriptors and adding a port consumes 1 file descriptor.
620 Performance will degrade beyond 1,024 ports per bridge due to
621 fixed hash table sizing. Other platforms may have different
622 limitations.
623 · 2,048 MAC learning entries per bridge, by default. (This is
625 configurable via other-config:mac-table-size in the Bridge ta‐
626 ble. See ovs-vswitchd.conf.db(5) for details.)
627 · Kernel flows are limited only by memory available to the kernel.
629 Performance will degrade beyond 1,048,576 kernel flows per
630 bridge with a 32-bit kernel, beyond 262,144 with a 64-bit ker‐
631 nel. (ovs-vswitchd should never install anywhere near that many
632 flows.)
633 · OpenFlow flows are limited only by available memory. Perfor‐
635 mance is linear in the number of unique wildcard patterns. That
636 is, an OpenFlow table that contains many flows that all match on
637 the same fields in the same way has a constant-time lookup, but
638 a table that contains many flows that match on different fields
639 requires lookup time linear in the number of flows.
640 · 255 ports per bridge participating in 802.1D Spanning Tree Pro‐
642 tocol.
643 · 32 mirrors per bridge.
645 · 15 bytes for the name of a port. (This is a Linux kernel limi‐
647 tation.)
648
650 ovs-appctl(8), ovsdb-server(1), INSTALL.Linux in the Open vSwitch dis‐
651 tribution.
652Open vSwitch 2.0.0 ovs-vswitchd(8)