1 <database title="Open vSwitch Configuration Database">
2 <p>A database with this schema holds the configuration for one Open
3 vSwitch daemon. The root of the configuration for the daemon is
4 the <ref table="Open_vSwitch"/> table, which must have exactly one
5 record. Records in other tables are significant only when they
6 can be reached directly or indirectly from the
7 <ref table="Open_vSwitch"/> table.</p>
9 <table name="Open_vSwitch" title="Open vSwitch configuration.">
10 Configuration for an Open vSwitch daemon. There must be exactly one record
11 in the <ref table="Open_vSwitch"/> table.
13 <group title="Configuration">
14 <column name="bridges">
15 Set of bridges managed by the daemon.
18 <column name="controller">
19 Default OpenFlow <ref table="Controller"/> set used by bridges. May be
20 overridden on a per-bridge basis by the <ref table="Bridge"
21 column="controller"/> column in <ref table="Bridge"/>.
24 <column name="managers">
25 Remote database clients to which the Open vSwitch's database server
26 should connect or to which it should listen.
30 SSL used globally by the daemon.
33 <column name="external_ids">
34 Key-value pairs that identify this Open vSwitch's role in
35 external systems. The currently defined key-value pairs are:
37 <dt><code>system-uuid</code></dt>
38 <dd>A universally unique identifier for the Open vSwitch's
39 physical host. The form of the identifier depends on the
40 type of the host. On a Citrix XenServer, this is the host
41 UUID displayed by, e.g., <code>xe host-list</code>.</dd>
46 <group title="Status">
47 <column name="next_cfg">
48 Sequence number for client to increment. When a client modifies
49 any part of the database configuration and wishes to wait for
50 Open vSwitch to finish applying the changes, it may increment
54 <column name="cur_cfg">
55 Sequence number that Open vSwitch sets to the current value of
56 <ref column="next_cfg"/> after it finishes applying a set of
57 configuration changes.
64 Configuration for a bridge within an
65 <ref table="Open_vSwitch"/>.
68 A <ref table="Bridge"/> record represents an Ethernet switch with one or
69 more ``ports,'' which are the <ref table="Port"/> records pointed to by
70 the <ref table="Bridge"/>'s <ref column="ports"/> column.
73 <group title="Core Features">
75 Bridge identifier. Should be alphanumeric and no more than about 8
76 bytes long. Must be unique among the names of ports, interfaces, and
81 Ports included in the bridge.
84 <column name="mirrors">
85 Port mirroring configuration.
88 <column name="netflow">
89 NetFlow configuration.
96 <column name="flood_vlans">
97 VLAN IDs of VLANs on which MAC address learning should be disabled, so
98 that packets are flooded instead of being sent to specific ports that
99 are believed to contain packets' destination MACs. This should
100 ordinarily be used to disable MAC learning on VLANs used for mirroring
101 (RSPAN VLANs). It may also be useful for debugging.
105 <group title="OpenFlow Configuration">
106 <column name="controller">
107 OpenFlow controller set. If unset, defaults to the set of
108 controllers specified by <ref column="controller"
109 table="Open_vSwitch"/> in the <ref table="Open_vSwitch"/>
110 table. If the default is also unset, then no OpenFlow
111 controllers will be used.
114 <column name="datapath_id">
115 Reports the OpenFlow datapath ID in use. Exactly 16 hex
116 digits. (Setting this column will have no useful effect. Set
117 <ref column="other_config"/>:<code>other-config</code>
122 <group title="Other Features">
123 <column name="datapath_type">
124 Name of datapath provider. The kernel datapath has
125 type <code>system</code>. The userspace datapath has
126 type <code>netdev</code>.
129 <column name="external_ids">
130 Key-value pairs that identify this bridge's role in external systems.
131 The currently defined key-value pairs are:
133 <dt><code>network-uuids</code></dt>
134 <dd>Semicolon-delimited set of universally unique identifier(s) for
135 the network with which this bridge is associated. The form of the
136 identifier(s) depends on the type of the host. On a Citrix
137 XenServer host, the network identifiers are RFC 4122 UUIDs as
138 displayed by, e.g., <code>xe network-list</code>.</dd>
142 <column name="other_config">
143 Key-value pairs for configuring rarely used bridge
144 features. The currently defined key-value pairs are:
146 <dt><code>datapath-id</code></dt>
148 digits to set the OpenFlow datapath ID to a specific
150 <dt><code>hwaddr</code></dt>
151 <dd>An Ethernet address in the form
152 <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>
153 to set the hardware address of the local port and influence the
160 <table name="Port" table="Port or bond configuration.">
161 <p>A port within a <ref table="Bridge"/>.</p>
162 <p>Most commonly, a port has exactly one ``interface,'' pointed to by its
163 <ref column="interfaces"/> column. Such a port logically
164 corresponds to a port on a physical Ethernet switch. A port
165 with more than one interface is a ``bonded port'' (see
166 <ref group="Bonding Configuration"/>).</p>
167 <p>Some properties that one might think as belonging to a port are actually
168 part of the port's <ref table="Interface"/> members.</p>
171 Port name. Should be alphanumeric and no more than about 8
172 bytes long. May be the same as the interface name, for
173 non-bonded ports. Must otherwise be unique among the names of
174 ports, interfaces, and bridges on a host.
177 <column name="interfaces">
178 The port's interfaces. If there is more than one, this is a
182 <group title="VLAN Configuration">
183 <p>A bridge port must be configured for VLANs in one of two
184 mutually exclusive ways:
186 <li>A ``trunk port'' has an empty value for
187 <ref column="tag"/> and a possibly non-empty
188 <ref column="trunks"/> value.</li>
189 <li>An ``implicitly tagged VLAN port'' or ``access port''
190 has an nonempty value for <ref column="tag"/> and an empty
191 <ref column="trunks"/> value.</li>
193 If <ref column="trunks"/> and <ref column="tag"/> are both
194 nonempty, the configuration is ill-formed.
198 <p>If nonempty, this port's implicitly tagged VLAN. Frames
199 arriving on trunk ports will be forwarded to this port only
200 if they are tagged with the given VLAN. Frames arriving on
201 other VLAN ports will be forwarded to this port only if they
202 have the same <ref column="tag"/> value. Frames forwarded
203 to this port will not have an 802.1Q header.</p>
204 <p>When a frame with a 802.1Q header that indicates a nonzero VLAN is
205 received on an implicit VLAN port, it is discarded.</p>
206 <p>Must be empty if this is a trunk port.</p>
209 <column name="trunks">
210 <p>The 802.1Q VLAN(s) that this port trunks. If the column is
211 empty, then the port trunks all VLANs as well as packets that
212 have no VLAN header. Otherwise, only frames that have an
213 802.1Q header with one of the specified VLANs are accepted.
214 If <code>0</code> is included, then frames without an 802.1Q
215 header are also accepted.</p>
216 <p>Must be empty unless this is a trunk port.</p>
220 <group title="Bonding Configuration">
221 <p>A port that has more than one interface is a ``bonded port.''
222 Bonding allows for load balancing and fail-over. Open vSwitch
223 supports ``source load balancing'' (SLB) bonding, which
224 assigns flows to slaves based on source MAC address, with
225 periodic rebalancing as traffic patterns change. This form of
226 bonding does not require 802.3ad or other special support from
227 the upstream switch to which the slave devices are
230 <p>These columns apply only to bonded ports. Their values are
231 otherwise ignored.</p>
233 <column name="bond_updelay">
234 <p>For a bonded port, the number of milliseconds for which carrier must
235 stay up on an interface before the interface is considered to be up.
236 Specify <code>0</code> to enable the interface immediately.</p>
237 <p>This setting is honored only when at least one bonded interface is
238 already enabled. When no interfaces are enabled, then the first bond
239 interface to come up is enabled immediately.</p>
242 <column name="bond_downdelay">
243 For a bonded port, the number of milliseconds for which carrier must
244 stay down on an interface before the interface is considered to be
245 down. Specify <code>0</code> to disable the interface immediately.
248 <column name="bond_fake_iface">
249 For a bonded port, whether to create a fake internal interface with the
250 name of the port. Use only for compatibility with legacy software that
255 <group title="Other Features">
257 The MAC address to use for this port for the purpose of choosing the
258 bridge's MAC address. This column does not necessarily reflect the
259 port's actual MAC address, nor will setting it change the port's actual
263 <column name="fake_bridge">
264 Does this port represent a sub-bridge for its tagged VLAN within the
265 Bridge? See ovs-vsctl(8) for more information.
268 <column name="external_ids">
269 Key-value pairs that identify this port's role in external systems. No
270 key-value pairs native to <ref table="Port"/> are currently defined.
271 For fake bridges (see the <ref column="fake_bridge"/> column), external
272 IDs for the fake bridge are defined here by prefixing a
273 <ref table="Bridge"/> <ref table="Bridge" column="external_ids"/> key
274 with <code>fake-bridge-</code>,
275 e.g. <code>fake-bridge-network-uuids</code>.
278 <column name="other_config">
279 Key-value pairs for configuring rarely used port features. The
280 currently defined key-value pairs are:
282 <dt><code>hwaddr</code></dt>
283 <dd>An Ethernet address in the form
284 <code><var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var></code>.</dd>
285 <dt><code>bond-rebalance-interval</code></dt>
286 <dd>For a bonded port, the number of milliseconds between
287 successive attempts to rebalance the bond, that is, to
288 move source MACs and their flows from one interface on
289 the bond to another in an attempt to keep usage of each
290 interface roughly equal. The default is 10000 (10
291 seconds), and the minimum is 1000 (1 second).</dd>
297 <table name="Interface" title="One physical network device in a Port.">
298 An interface within a <ref table="Port"/>.
300 <group title="Core Features">
302 Interface name. Should be alphanumeric and no more than about 8 bytes
303 long. May be the same as the port name, for non-bonded ports. Must
304 otherwise be unique among the names of ports, interfaces, and bridges
309 <p>Ethernet address to set for this interface. If unset then the
310 default MAC address is used:</p>
312 <li>For the local interface, the default is the lowest-numbered MAC
313 address among the other bridge ports, either the value of the
314 <ref table="Port" column="mac"/> in its <ref table="Port"/> record,
315 if set, or its actual MAC (for bonded ports, the MAC of its slave
316 whose name is first in alphabetical order). Internal ports and
317 bridge ports that are used as port mirroring destinations (see the
318 <ref table="Mirror"/> table) are ignored.</li>
319 <li>For other internal interfaces, the default MAC is randomly
321 <li>External interfaces typically have a MAC address associated with
324 <p>Some interfaces may not have a software-controllable MAC
328 <column name="ofport">
329 <p>OpenFlow port number for this interface. Unlike most columns, this
330 column's value should be set only by Open vSwitch itself. Other
331 clients should set this column to an empty set (the default) when
332 creating an <ref table="Interface"/>.</p>
333 <p>Open vSwitch populates this column when the port number becomes
334 known. If the interface is successfully added,
335 <ref column="ofport"/> will be set to a number between 1 and 65535
336 (generally either in the range 1 to 65280, exclusive, or 65534, the
337 port number for the OpenFlow ``local port''). If the interface
338 cannot be added then Open vSwitch sets this column
343 <group title="System-Specific Details">
345 The interface type, one of:
347 <dt><code>system</code></dt>
348 <dd>An ordinary network device, e.g. <code>eth0</code> on Linux.
349 Sometimes referred to as ``external interfaces'' since they are
350 generally connected to hardware external to that on which the Open
351 vSwitch is running. The empty string is a synonym for
352 <code>system</code>.</dd>
353 <dt><code>internal</code></dt>
354 <dd>A simulated network device that sends and receives traffic. An
355 internal interface whose <ref column="name"/> is the same as its
356 bridge's <ref table="Open_vSwitch" column="name"/> is called the
357 ``local interface.'' It does not make sense to bond an internal
358 interface, so the terms ``port'' and ``interface'' are often used
359 imprecisely for internal interfaces.</dd>
360 <dt><code>tap</code></dt>
361 <dd>A TUN/TAP device managed by Open vSwitch.</dd>
362 <dt><code>gre</code></dt>
363 <dd>An Ethernet over RFC 1702 Generic Routing Encapsulation over IPv4
364 tunnel. Each tunnel must be uniquely identified by the
365 combination of <code>remote_ip</code>, <code>local_ip</code>, and
366 <code>in_key</code>. Note that if two ports are defined that are
367 the same except one has an optional identifier and the other does
368 not, the more specific one is matched first. <code>in_key</code>
369 is considered more specific than <code>local_ip</code> if a port
370 defines one and another port defines the other. The arguments
373 <dt><code>remote_ip</code></dt>
374 <dd>Required. The tunnel endpoint.</dd>
377 <dt><code>local_ip</code></dt>
378 <dd>Optional. The destination IP that received packets must
379 match. Default is to match all addresses.</dd>
382 <dt><code>in_key</code></dt>
383 <dd>Optional. The GRE key that received packets must contain.
384 It may either be a 32-bit number (no key and a key of 0 are
385 treated as equivalent) or the word <code>flow</code>. If
386 <code>flow</code> is specified then any key will be accepted
387 and the key will be placed in the <code>tun_id</code> field
388 for matching in the flow table. The ovs-ofctl manual page
389 contains additional information about matching fields in
390 OpenFlow flows. Default is no key.</dd>
393 <dt><code>out_key</code></dt>
394 <dd>Optional. The GRE key to be set on outgoing packets. It may
395 either be a 32-bit number or the word <code>flow</code>. If
396 <code>flow</code> is specified then the key may be set using
397 the <code>set_tunnel</code> Nicira OpenFlow vendor extension (0
398 is used in the absense of an action). The ovs-ofctl manual
399 page contains additional information about the Nicira OpenFlow
400 vendor extensions. Default is no key.</dd>
403 <dt><code>key</code></dt>
404 <dd>Optional. Shorthand to set <code>in_key</code> and
405 <code>out_key</code> at the same time.</dd>
408 <dt><code>tos</code></dt>
409 <dd>Optional. The value of the ToS bits to be set on the
410 encapsulating packet. It may also be the word
411 <code>inherit</code>, in which case the ToS will be copied from
412 the inner packet if it is IPv4 or IPv6 (otherwise it will be
413 0). Note that the ECN fields are always inherited. Default is
417 <dt><code>ttl</code></dt>
418 <dd>Optional. The TTL to be set on the encapsulating packet.
419 It may also be the word <code>inherit</code>, in which case the
420 TTL will be copied from the inner packet if it is IPv4 or IPv6
421 (otherwise it will be the system default, typically 64).
422 Default is the system default TTL.</dd>
425 <dt><code>csum</code></dt>
426 <dd>Optional. Compute GRE checksums for outgoing packets and
427 require checksums for incoming packets. Default is enabled,
428 set to <code>false</code> to disable.</dd>
431 <dt><code>pmtud</code></dt>
432 <dd>Optional. Enable tunnel path MTU discovery. If enabled
433 ``ICMP destination unreachable - fragmentation'' needed
434 messages will be generated for IPv4 packets with the DF bit set
435 and IPv6 packets above the minimum MTU if the packet size
436 exceeds the path MTU minus the size of the tunnel headers. It
437 also forces the encapsulating packet DF bit to be set (it is
438 always set if the inner packet implies path MTU discovery).
439 Note that this option causes behavior that is typically
440 reserved for routers and therefore is not entirely in
441 compliance with the IEEE 802.1D specification for bridges.
442 Default is enabled, set to <code>false</code> to disable.</dd>
445 <dt><code>patch</code></dt>
446 <dd>A pair of virtual devices that act as a patch cable. A
447 <code>peer</code> argument is required that indicates the name
448 of the other side of the patch. Since a patch must work in
449 pairs, a second patch interface must be declared with the
450 <code>name</code> and <code>peer</code> arguments reversed.</dd>
454 <column name="options">
455 Configuration options whose interpretation varies based on
456 <ref column="type"/>.
460 <group title="Ingress Policing">
461 <column name="ingress_policing_burst">
462 <p>Maximum burst size for data received on this interface, in kb. The
463 default burst size if set to <code>0</code> is 1000 kb. This value
464 has no effect if <ref column="ingress_policing_rate"/>
465 is <code>0</code>.</p>
466 <p>The burst size should be at least the size of the interface's
470 <column name="ingress_policing_rate">
471 <p>Maximum rate for data received on this interface, in kbps. Data
472 received faster than this rate is dropped. Set to <code>0</code> to
473 disable policing.</p>
474 <p>The meaning of ``ingress'' is from Open vSwitch's perspective. If
475 configured on a physical interface, then it limits the rate at which
476 traffic is allowed into the system from the outside. If configured
477 on a virtual interface that is connected to a virtual machine, then
478 it limits the rate at which the guest is able to transmit.</p>
482 <group title="Other Features">
483 <column name="external_ids">
484 <p>Key-value pairs that identify this interface's role in external
485 systems. All of the currently defined key-value pairs specifically
486 apply to an interface that represents a virtual Ethernet interface
487 connected to a virtual machine. These key-value pairs should not be
488 present for other types of interfaces. Keys whose names end
489 in <code>-uuid</code> have values that uniquely identify the entity
490 in question. For a Citrix XenServer hypervisor, these values are
491 UUIDs in RFC 4122 format. Other hypervisors may use other
493 <p>The currently defined key-value pairs are:</p>
495 <dt><code>vif-uuid</code></dt>
496 <dd>The virtual interface associated with this interface.</dd>
497 <dt><code>network-uuid</code></dt>
498 <dd>The virtual network to which this interface is attached.</dd>
499 <dt><code>vm-uuid</code></dt>
500 <dd>The VM to which this interface belongs.</dd>
501 <dt><code>vif-mac</code></dt>
502 <dd>The MAC address programmed into the "virtual hardware" for this
504 form <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
505 For Citrix XenServer, this is the value of the <code>MAC</code>
506 field in the VIF record for this interface.</dd>
512 <table name="Mirror" title="Port mirroring (SPAN/RSPAN).">
513 <p>A port mirror within a <ref table="Bridge"/>.</p>
514 <p>A port mirror configures a bridge to send selected frames to special
515 ``mirrored'' ports, in addition to their normal destinations. Mirroring
516 traffic may also be referred to as SPAN or RSPAN, depending on the
517 mechanism used for delivery.</p>
520 Arbitrary identifier for the <ref table="Mirror"/>.
523 <group title="Selecting Packets for Mirroring">
524 <column name="select_all">
525 If true, every packet arriving or departing on any port is
526 selected for mirroring.
529 <column name="select_dst_port">
530 Ports on which departing packets are selected for mirroring.
533 <column name="select_src_port">
534 Ports on which arriving packets are selected for mirroring.
537 <column name="select_vlan">
538 VLANs on which packets are selected for mirroring. An empty set
539 selects packets on all VLANs.
543 <group title="Mirroring Destination Configuration">
544 <column name="output_port">
545 <p>Output port for selected packets, if nonempty. Mutually exclusive
546 with <ref column="output_vlan"/>.</p>
547 <p>Specifying a port for mirror output reserves that port exclusively
548 for mirroring. No frames other than those selected for mirroring
549 will be forwarded to the port, and any frames received on the port
550 will be discarded.</p>
551 <p>This type of mirroring is sometimes called SPAN.</p>
554 <column name="output_vlan">
555 <p>Output VLAN for selected packets, if nonempty. Mutually exclusive
556 with <ref column="output_port"/>.</p>
557 <p>The frames will be sent out all ports that trunk
558 <ref column="output_vlan"/>, as well as any ports with implicit VLAN
559 <ref column="output_vlan"/>. When a mirrored frame is sent out a
560 trunk port, the frame's VLAN tag will be set to
561 <ref column="output_vlan"/>, replacing any existing tag; when it is
562 sent out an implicit VLAN port, the frame will not be tagged. This
563 type of mirroring is sometimes called RSPAN.</p>
564 <p><em>Please note:</em> Mirroring to a VLAN can disrupt a network that
565 contains unmanaged switches. Consider an unmanaged physical switch
566 with two ports: port 1, connected to an end host, and port 2,
567 connected to an Open vSwitch configured to mirror received packets
568 into VLAN 123 on port 2. Suppose that the end host sends a packet on
569 port 1 that the physical switch forwards to port 2. The Open vSwitch
570 forwards this packet to its destination and then reflects it back on
571 port 2 in VLAN 123. This reflected packet causes the unmanaged
572 physical switch to replace the MAC learning table entry, which
573 correctly pointed to port 1, with one that incorrectly points to port
574 2. Afterward, the physical switch will direct packets destined for
575 the end host to the Open vSwitch on port 2, instead of to the end
576 host on port 1, disrupting connectivity. If mirroring to a VLAN is
577 desired in this scenario, then the physical switch must be replaced
578 by one that learns Ethernet addresses on a per-VLAN basis. In
579 addition, learning should be disabled on the VLAN containing mirrored
580 traffic. If this is not done then intermediate switches will learn
581 the MAC address of each end host from the mirrored traffic. If
582 packets being sent to that end host are also mirrored, then they will
583 be dropped since the switch will attempt to send them out the input
584 port. Disabling learning for the VLAN will cause the switch to
585 correctly send the packet out all ports configured for that VLAN. If
586 Open vSwitch is being used as an intermediate switch, learning can be
587 disabled by adding the mirrored VLAN to <ref column="flood_vlans"/>
588 in the appropriate <ref table="Bridge"/> table or tables.</p>
593 <table name="Controller" title="OpenFlow controller configuration.">
594 <p>An OpenFlow controller.</p>
596 <p>Open vSwitch permits a bridge to have any number of OpenFlow
597 controllers. When multiple controllers are configured, Open vSwitch
598 connects to all of them simultaneously. OpenFlow 1.0 does not specify
599 how multiple controllers coordinate in interacting with a single switch,
600 so more than one controller should be specified only if the controllers
601 are themselves designed to coordinate with each other.</p>
603 <group title="Core Features">
604 <column name="target">
605 <p>Connection method for controller.
606 The following connection methods are currently
609 <dt><code>ssl:<var>ip</var></code>[<code>:<var>port</var></code>]</dt>
611 <p>The specified SSL <var>port</var> (default: 6633) on the host at
612 the given <var>ip</var>, which must be expressed as an IP address
613 (not a DNS name). The <ref table="Open_vSwitch" column="ssl"/>
614 column in the <ref table="Open_vSwitch"/> must point to a valid
615 SSL configuration when this form is used.</p>
616 <p>SSL support is an optional feature that is not always built as
617 part of Open vSwitch.</p>
619 <dt><code>tcp:<var>ip</var></code>[<code>:<var>port</var></code>]</dt>
620 <dd>The specified TCP <var>port</var> (default: 6633) on the host at
621 the given <var>ip</var>, which must be expressed as an IP address
622 (not a DNS name).</dd>
623 <dt><code>discover</code></dt>
625 <p>Enables controller discovery.</p>
626 <p>In controller discovery mode, Open vSwitch broadcasts a DHCP
627 request with vendor class identifier <code>OpenFlow</code> across
628 all of the bridge's network devices. It will accept any valid
629 DHCP reply that has the same vendor class identifier and includes
630 a vendor-specific option with code 1 whose contents are a string
631 specifying the location of the controller in the same format as
632 <ref column="target"/>.</p>
633 <p>The DHCP reply may also, optionally, include a vendor-specific
634 option with code 2 whose contents are a string specifying the URI
635 to the base of the OpenFlow PKI
636 (e.g. <code>http://192.168.0.1/openflow/pki</code>). This URI is
637 used only for bootstrapping the OpenFlow PKI at initial switch
638 setup; <code>ovs-vswitchd</code> does not use it at all.</p>
640 <dt><code>none</code></dt>
641 <dd>Disables the controller.</dd>
643 <p>When multiple controllers are configured for a single bridge, the
644 <ref column="target"/> values must be unique. Duplicate
645 <ref column="target"/> values yield unspecified results.</p>
648 <column name="connection_mode">
649 <p>If it is specified, this setting must be one of the following
650 strings that describes how Open vSwitch contacts this OpenFlow
651 controller over the network:</p>
654 <dt><code>in-band</code></dt>
655 <dd>In this mode, this controller's OpenFlow traffic travels over the
656 bridge associated with the controller. With this setting, Open
657 vSwitch allows traffic to and from the controller regardless of the
658 contents of the OpenFlow flow table. (Otherwise, Open vSwitch
659 would never be able to connect to the controller, because it did
660 not have a flow to enable it.) This is the most common connection
661 mode because it is not necessary to maintain two independent
663 <dt><code>out-of-band</code></dt>
664 <dd>In this mode, OpenFlow traffic uses a control network separate
665 from the bridge associated with this controller, that is, the
666 bridge does not use any of its own network devices to communicate
667 with the controller. The control network must be configured
668 separately, before or after <code>ovs-vswitchd</code> is started.
672 <p>If not specified, the default is implementation-specific. If
673 <ref column="target"/> is <code>discover</code>, the connection mode
674 is always treated as <code>in-band</code> regardless of the actual
679 <group title="Controller Failure Detection and Handling">
680 <column name="max_backoff">
681 Maximum number of milliseconds to wait between connection attempts.
682 Default is implementation-specific.
685 <column name="inactivity_probe">
686 Maximum number of milliseconds of idle time on connection to
687 controller before sending an inactivity probe message. If Open
688 vSwitch does not communicate with the controller for the specified
689 number of seconds, it will send a probe. If a response is not
690 received for the same additional amount of time, Open vSwitch
691 assumes the connection has been broken and attempts to reconnect.
692 Default is implementation-specific.
695 <column name="fail_mode">
696 <p>When a controller is configured, it is, ordinarily, responsible
697 for setting up all flows on the switch. Thus, if the connection to
698 the controller fails, no new network connections can be set up.
699 If the connection to the controller stays down long enough,
700 no packets can pass through the switch at all. This setting
701 determines the switch's response to such a situation. It may be set
702 to one of the following:
704 <dt><code>standalone</code></dt>
705 <dd>If no message is received from the controller for three
706 times the inactivity probe interval
707 (see <ref column="inactivity_probe"/>), then Open vSwitch
708 will take over responsibility for setting up flows. In
709 this mode, Open vSwitch causes the bridge to act like an
710 ordinary MAC-learning switch. Open vSwitch will continue
711 to retry connecting to the controller in the background
712 and, when the connection succeeds, it will discontinue its
713 standalone behavior.</dd>
714 <dt><code>secure</code></dt>
715 <dd>Open vSwitch will not set up flows on its own when the
716 controller connection fails. It will continue retry
717 connecting to the controller forever.</dd>
720 <p>If this value is unset, the default is implementation-specific.</p>
721 <p>When more than one controller is configured,
722 <ref column="fail_mode"/> is considered only when none of the
723 configured controllers can be contacted. At that point, the bridge
724 enters secure mode if any of the controllers'
725 <ref column="fail_mode"/> is set to <code>secure</code>. Otherwise,
726 it enters standalone mode if at least one <ref column="fail_mode"/>
727 is set to <code>standalone</code>. If none of the
728 <ref column="fail_mode"/> values are set, the default is
729 implementation-defined.</p>
733 <group title="OpenFlow Rate Limiting">
734 <column name="controller_rate_limit">
735 <p>The maximum rate at which packets in unknown flows will be
736 forwarded to the OpenFlow controller, in packets per second. This
737 feature prevents a single bridge from overwhelming the controller.
738 If not specified, the default is implementation-specific.</p>
739 <p>In addition, when a high rate triggers rate-limiting, Open
740 vSwitch queues controller packets for each port and transmits
741 them to the controller at the configured rate. The number of
742 queued packets is limited by
743 the <ref column="controller_burst_limit"/> value. The packet
744 queue is shared fairly among the ports on a bridge.</p><p>Open
745 vSwitch maintains two such packet rate-limiters per bridge.
746 One of these applies to packets sent up to the controller
747 because they do not correspond to any flow. The other applies
748 to packets sent up to the controller by request through flow
749 actions. When both rate-limiters are filled with packets, the
750 actual rate that packets are sent to the controller is up to
751 twice the specified rate.</p>
754 <column name="controller_burst_limit">
755 In conjunction with <ref column="controller_rate_limit"/>,
756 the maximum number of unused packet credits that the bridge will
757 allow to accumulate, in packets. If not specified, the default
758 is implementation-specific.
762 <group title="Additional Discovery Configuration">
763 <p>These values are considered only when <ref column="target"/>
764 is <code>discover</code>.</p>
766 <column name="discover_accept_regex">
768 extended regular expression against which the discovered controller
769 location is validated. The regular expression is implicitly
770 anchored at the beginning of the controller location string, as
771 if it begins with <code>^</code>. If not specified, the default
772 is implementation-specific.
775 <column name="discover_update_resolv_conf">
776 Whether to update <code>/etc/resolv.conf</code> when the
777 controller is discovered. If not specified, the default
778 is implementation-specific. Open vSwitch will only modify
779 <code>/etc/resolv.conf</code> if the DHCP response that it receives
780 specifies one or more DNS servers.
784 <group title="Additional In-Band Configuration">
785 <p>These values are considered only in in-band control mode (see
786 <ref column="connection_mode"/>) and only when <ref column="target"/>
787 is not <code>discover</code>. (For controller discovery, the network
788 configuration obtained via DHCP is used instead.)</p>
790 <p>When multiple controllers are configured on a single bridge, there
791 should be only one set of unique values in these columns. If different
792 values are set for these columns in different controllers, the effect
795 <column name="local_ip">
796 The IP address to configure on the local port,
797 e.g. <code>192.168.0.123</code>. If this value is unset, then
798 <ref column="local_netmask"/> and <ref column="local_gateway"/> are
802 <column name="local_netmask">
803 The IP netmask to configure on the local port,
804 e.g. <code>255.255.255.0</code>. If <ref column="local_ip"/> is set
805 but this value is unset, then the default is chosen based on whether
806 the IP address is class A, B, or C.
809 <column name="local_gateway">
810 The IP address of the gateway to configure on the local port, as a
811 string, e.g. <code>192.168.0.1</code>. Leave this column unset if
812 this network has no gateway.
817 <table name="NetFlow">
818 A NetFlow target. NetFlow is a protocol that exports a number of
819 details about terminating IP flows, such as the principals involved
822 <column name="targets">
823 NetFlow targets in the form
824 <code><var>ip</var>:<var>port</var></code>. The <var>ip</var>
825 must be specified numerically, not as a DNS name.
828 <column name="engine_id">
829 Engine ID to use in NetFlow messages. Defaults to datapath index
833 <column name="engine_type">
834 Engine type to use in NetFlow messages. Defaults to datapath
835 index if not specified.
838 <column name="active_timeout">
839 The interval at which NetFlow records are sent for flows that are
840 still active, in seconds. A value of <code>0</code> requests the
841 default timeout (currently 600 seconds); a value of <code>-1</code>
842 disables active timeouts.
845 <column name="add_id_to_interface">
846 <p>If this column's value is <code>false</code>, the ingress and egress
847 interface fields of NetFlow flow records are derived from OpenFlow port
848 numbers. When it is <code>true</code>, the 7 most significant bits of
849 these fields will be replaced by the least significant 7 bits of the
850 engine id. This is useful because many NetFlow collectors do not
851 expect multiple switches to be sending messages from the same host, so
852 they do not store the engine information which could be used to
853 disambiguate the traffic.</p>
854 <p>When this option is enabled, a maximum of 508 ports are supported.</p>
859 SSL configuration for an Open_vSwitch.
861 <column name="private_key">
862 Name of a PEM file containing the private key used as the switch's
863 identity for SSL connections to the controller.
866 <column name="certificate">
867 Name of a PEM file containing a certificate, signed by the
868 certificate authority (CA) used by the controller and manager,
869 that certifies the switch's private key, identifying a trustworthy
873 <column name="ca_cert">
874 Name of a PEM file containing the CA certificate used to verify
875 that the switch is connected to a trustworthy controller.
878 <column name="bootstrap_ca_cert">
879 If set to <code>true</code>, then Open vSwitch will attempt to
880 obtain the CA certificate from the controller on its first SSL
881 connection and save it to the named PEM file. If it is successful,
882 it will immediately drop the connection and reconnect, and from then
883 on all SSL connections must be authenticated by a certificate signed
884 by the CA certificate thus obtained. <em>This option exposes the
885 SSL connection to a man-in-the-middle attack obtaining the initial
886 CA certificate.</em> It may still be useful for bootstrapping.
891 <p>An sFlow(R) target. sFlow is a protocol for remote monitoring
894 <column name="agent">
895 Name of the network device whose IP address should be reported as the
896 ``agent address'' to collectors. If not specified, the IP address
897 defaults to the <ref table="Controller" column="local_ip"/> in the
898 collector's <ref table="Controller"/>. If an agent IP address cannot be
899 determined either way, sFlow is disabled.
902 <column name="header">
903 Number of bytes of a sampled packet to send to the collector.
904 If not specified, the default is 128 bytes.
907 <column name="polling">
908 Polling rate in seconds to send port statistics to the collector.
909 If not specified, defaults to 30 seconds.
912 <column name="sampling">
913 Rate at which packets should be sampled and sent to the collector.
914 If not specified, defaults to 400, which means one out of 400
915 packets, on average, will be sent to the collector.
918 <column name="targets">
919 sFlow targets in the form
920 <code><var>ip</var>:<var>port</var></code>.