1ovs-vswitchd.conf.db(5) Open vSwitch Manual ovs-vswitchd.conf.db(5)
2
6 Open_vSwitch - Open_vSwitch database schema
7 A database with this schema holds the configuration for one Open
9 vSwitch daemon. The top-level configuration for the daemon is the
10 Open_vSwitch table, which must have exactly one record. Records in
11 other tables are significant only when they can be reached directly or
12 indirectly from the Open_vSwitch table. Records that are not reachable
13 from the Open_vSwitch table are automatically deleted from the data‐
14 base, except for records in a few distinguished ``root set’’ tables.
15 Common Columns
17 Most tables contain two special columns, named other_config and exter‐
18 nal_ids. These columns have the same form and purpose each place that
19 they appear, so we describe them here to save space later.
20 other_config: map of string-string pairs
22 Key-value pairs for configuring rarely used features.
23 Supported keys, along with the forms taken by their val‐
24 ues, are documented individually for each table.
25 A few tables do not have other_config columns because no
27 key-value pairs have yet been defined for them.
28 external_ids: map of string-string pairs
30 Key-value pairs for use by external frameworks that inte‐
31 grate with Open vSwitch, rather than by Open vSwitch
32 itself. System integrators should either use the Open
33 vSwitch development mailing list to coordinate on common
34 key-value definitions, or choose key names that are
35 likely to be unique. In some cases, where key-value
36 pairs have been defined that are likely to be widely use‐
37 ful, they are documented individually for each table.
38
40 The following list summarizes the purpose of each of the tables in the
41 Open_vSwitch database. Each table is described in more detail on a
42 later page.
43 Table Purpose
45 Open_vSwitch
46 Open vSwitch configuration.
47 Bridge Bridge configuration.
48 Port Port configuration.
49 Interface One physical network device in a Port.
50 Flow_Table
51 OpenFlow table configuration
52 QoS Quality of Service configuration
53 Queue QoS output queue.
54 Mirror Port mirroring.
55 Controller
56 OpenFlow controller configuration.
57 Manager OVSDB management connection.
58 NetFlow NetFlow configuration.
59 SSL SSL configuration.
60 sFlow sFlow configuration.
61 IPFIX IPFIX configuration.
62 Flow_Sample_Collector_Set
63 Flow_Sample_Collector_Set configuration.
64
66 Configuration for an Open vSwitch daemon. There must be exactly one
67 record in the Open_vSwitch table.
68 Summary:
70 Configuration:
71 bridges set of Bridges
72 ssl optional SSL
73 external_ids : system-id optional string
74 external_ids : xs-system-uuid
75 optional string
76 other_config : flow-restore-wait
77 optional string, either true or false
78 other_config : flow-eviction-threshold
79 optional string, containing an integer,
80 at least 0
81 other_config : force-miss-model
82 optional string
83 other_config : n-handler-threads
84 optional string, containing an integer,
85 at least 1
86 Status:
87 next_cfg integer
88 cur_cfg integer
89 Statistics:
90 other_config : enable-statistics
91 optional string, either true or false
92 statistics : cpu optional string, containing an integer,
93 at least 1
94 statistics : load_average
95 optional string
96 statistics : memory optional string
97 statistics : process_NAME
98 optional string
99 statistics : file_systems
100 optional string
101 Version Reporting:
102 ovs_version optional string
103 db_version optional string
104 system_type optional string
105 system_version optional string
106 Database Configuration:
107 manager_options set of Managers
108 Common Columns:
109 other_config map of string-string pairs
110 external_ids map of string-string pairs
111 Details:
113 Configuration:
114 bridges: set of Bridges
116 Set of bridges managed by the daemon.
117 ssl: optional SSL
119 SSL used globally by the daemon.
120 external_ids : system-id: optional string
122 A unique identifier for the Open vSwitch’s physical host. The
123 form of the identifier depends on the type of the host. On a
124 Citrix XenServer, this will likely be the same as exter‐
125 nal_ids:xs-system-uuid.
126 external_ids : xs-system-uuid: optional string
128 The Citrix XenServer universally unique identifier for the phys‐
129 ical host as displayed by xe host-list.
130 other_config : flow-restore-wait: optional string, either true or false
132 When ovs-vswitchd starts up, it has an empty flow table and
133 therefore it handles all arriving packets in its default fashion
134 according to its configuration, by dropping them or sending them
135 to an OpenFlow controller or switching them as a standalone
136 switch. This behavior is ordinarily desirable. However, if
137 ovs-vswitchd is restarting as part of a ``hot-upgrade,’’ then
138 this leads to a relatively long period during which packets are
139 mishandled.
140 This option allows for improvement. When ovs-vswitchd starts
142 with this value set as true, it will neither flush or expire
143 previously set datapath flows nor will it send and receive any
144 packets to or from the datapath. When this value is later set
145 to false, ovs-vswitchd will start receiving packets from the
146 datapath and re-setup the flows.
147 Thus, with this option, the procedure for a hot-upgrade of
149 ovs-vswitchd becomes roughly the following:
150 1.
152 Stop ovs-vswitchd.
153 2.
155 Set other_config:flow-restore-wait to true.
156 3.
158 Start ovs-vswitchd.
159 4.
161 Use ovs-ofctl (or some other program, such as an OpenFlow con‐
162 troller) to restore the OpenFlow flow table to the desired
163 state.
164 5.
166 Set other_config:flow-restore-wait to false (or remove it
167 entirely from the database).
168 The ovs-ctl’s ``restart’’ and ``force-reload-kmod’’ functions
170 use the above config option during hot upgrades.
171 other_config : flow-eviction-threshold: optional string, containing an
173 integer, at least 0
174 A number of flows as a nonnegative integer. This sets number of
175 flows at which eviction from the datapath flow table will be
176 triggered. If there are a large number of flows then increasing
177 this value to around the number of flows present can result in
178 reduced CPU usage and packet loss.
179 The default is 2500. Values below 100 will be rounded up to
181 100.
182 other_config : force-miss-model: optional string
184 Specifies userspace behaviour for handling flow misses. This
185 takes precedence over flow-eviction-threshold.
186 auto Handle automatically based on the flow-eviction-threshold
188 and the flow setup governer (default, recommended).
189 with-facets
191 Always create facets. Expensive kernel flow creation and
192 statistics tracking is always performed, even on flows
193 with only a small number of packets.
194 without-facets
196 Always handle without facets. Forces flow misses to be
197 handled in userspace. May cause an increase in CPU usage
198 and packet loss on high throughput.
199 other_config : n-handler-threads: optional string, containing an inte‐
201 ger, at least 1
202 Specifies the number of threads for software datapaths to use
203 for handling new flows. The default is two less than the number
204 of online CPU cores (but at least 1).
205 This configuration is per datapath. If you have more than one
207 software datapath (e.g. some system bridges and some netdev
208 bridges), then the total number of threads is n-handler-threads
209 times the number of software datapaths.
210 Status:
212 next_cfg: integer
214 Sequence number for client to increment. When a client modifies
215 any part of the database configuration and wishes to wait for
216 Open vSwitch to finish applying the changes, it may increment
217 this sequence number.
218 cur_cfg: integer
220 Sequence number that Open vSwitch sets to the current value of
221 next_cfg after it finishes applying a set of configuration
222 changes.
223 Statistics:
225 The statistics column contains key-value pairs that report statistics
226 about a system running an Open vSwitch. These are updated periodically
227 (currently, every 5 seconds). Key-value pairs that cannot be deter‐
228 mined or that do not apply to a platform are omitted.
229 other_config : enable-statistics: optional string, either true or false
231 Statistics are disabled by default to avoid overhead in the com‐
232 mon case when statistics gathering is not useful. Set this
233 value to true to enable populating the statistics column or to
234 false to explicitly disable it.
235 statistics : cpu: optional string, containing an integer, at least 1
237 Number of CPU processors, threads, or cores currently online and
238 available to the operating system on which Open vSwitch is run‐
239 ning, as an integer. This may be less than the number
240 installed, if some are not online or if they are not available
241 to the operating system.
242 Open vSwitch userspace processes are not multithreaded, but the
244 Linux kernel-based datapath is.
245 statistics : load_average: optional string
247 A comma-separated list of three floating-point numbers, repre‐
248 senting the system load average over the last 1, 5, and 15 min‐
249 utes, respectively.
250 statistics : memory: optional string
252 A comma-separated list of integers, each of which represents a
253 quantity of memory in kilobytes that describes the operating
254 system on which Open vSwitch is running. In respective order,
255 these values are:
256 1.
258 Total amount of RAM allocated to the OS.
259 2.
261 RAM allocated to the OS that is in use.
262 3.
264 RAM that can be flushed out to disk or otherwise discarded if
265 that space is needed for another purpose. This number is nec‐
266 essarily less than or equal to the previous value.
267 4.
269 Total disk space allocated for swap.
270 5.
272 Swap space currently in use.
273 On Linux, all five values can be determined and are included.
275 On other operating systems, only the first two values can be
276 determined, so the list will only have two values.
277 statistics : process_NAME: optional string
279 One such key-value pair, with NAME replaced by a process name,
280 will exist for each running Open vSwitch daemon process, with
281 name replaced by the daemon’s name (e.g. process_ovs-vswitchd).
282 The value is a comma-separated list of integers. The integers
283 represent the following, with memory measured in kilobytes and
284 durations in milliseconds:
285 1.
287 The process’s virtual memory size.
288 2.
290 The process’s resident set size.
291 3.
293 The amount of user and system CPU time consumed by the
294 process.
295 4.
297 The number of times that the process has crashed and been
298 automatically restarted by the monitor.
299 5.
301 The duration since the process was started.
302 6.
304 The duration for which the process has been running.
305 The interpretation of some of these values depends on whether
307 the process was started with the --monitor. If it was not, then
308 the crash count will always be 0 and the two durations will
309 always be the same. If --monitor was given, then the crash
310 count may be positive; if it is, the latter duration is the
311 amount of time since the most recent crash and restart.
312 There will be one key-value pair for each file in Open vSwitch’s
314 ``run directory’’ (usually /var/run/openvswitch) whose name ends
315 in .pid, whose contents are a process ID, and which is locked by
316 a running process. The name is taken from the pidfile’s name.
317 Currently Open vSwitch is only able to obtain all of the above
319 detail on Linux systems. On other systems, the same key-value
320 pairs will be present but the values will always be the empty
321 string.
322 statistics : file_systems: optional string
324 A space-separated list of information on local, writable file
325 systems. Each item in the list describes one file system and
326 consists in turn of a comma-separated list of the following:
327 1.
329 Mount point, e.g. / or /var/log. Any spaces or commas in the
330 mount point are replaced by underscores.
331 2.
333 Total size, in kilobytes, as an integer.
334 3.
336 Amount of storage in use, in kilobytes, as an integer.
337 This key-value pair is omitted if there are no local, writable
339 file systems or if Open vSwitch cannot obtain the needed infor‐
340 mation.
341 Version Reporting:
343 These columns report the types and versions of the hardware and soft‐
344 ware running Open vSwitch. We recommend in general that software
345 should test whether specific features are supported instead of relying
346 on version number checks. These values are primarily intended for
347 reporting to human administrators.
348 ovs_version: optional string
350 The Open vSwitch version number, e.g. 1.1.0.
351 db_version: optional string
353 The database schema version number in the form
354 major.minor.tweak, e.g. 1.2.3. Whenever the database schema is
355 changed in a non-backward compatible way (e.g. deleting a column
356 or a table), major is incremented. When the database schema is
357 changed in a backward compatible way (e.g. adding a new column),
358 minor is incremented. When the database schema is changed cos‐
359 metically (e.g. reindenting its syntax), tweak is incremented.
360 The schema version is part of the database schema, so it can
362 also be retrieved by fetching the schema using the Open vSwitch
363 database protocol.
364 system_type: optional string
366 An identifier for the type of system on top of which Open
367 vSwitch runs, e.g. XenServer or KVM.
368 System integrators are responsible for choosing and setting an
370 appropriate value for this column.
371 system_version: optional string
373 The version of the system identified by system_type, e.g.
374 5.6.100-39265p on XenServer 5.6.100 build 39265.
375 System integrators are responsible for choosing and setting an
377 appropriate value for this column.
378 Database Configuration:
380 These columns primarily configure the Open vSwitch database
381 (ovsdb-server), not the Open vSwitch switch (ovs-vswitchd). The OVSDB
382 database also uses the ssl settings.
383 The Open vSwitch switch does read the database configuration to deter‐
385 mine remote IP addresses to which in-band control should apply.
386 manager_options: set of Managers
388 Database clients to which the Open vSwitch database server
389 should connect or to which it should listen, along with options
390 for how these connection should be configured. See the Manager
391 table for more information.
392 Common Columns:
394 The overall purpose of these columns is described under Common Columns
395 at the beginning of this document.
396 other_config: map of string-string pairs
398 external_ids: map of string-string pairs
400
402 Configuration for a bridge within an Open_vSwitch.
403 A Bridge record represents an Ethernet switch with one or more
405 ``ports,’’ which are the Port records pointed to by the Bridge’s ports
406 column.
407 Summary:
409 Core Features:
410 name string (must be unique within table)
411 ports set of Ports
412 mirrors set of Mirrors
413 netflow optional NetFlow
414 sflow optional sFlow
415 ipfix optional IPFIX
416 flood_vlans set of up to 4,096 integers, in range 0
417 to 4,095
418 OpenFlow Configuration:
419 controller set of Controllers
420 flow_tables map of integer-Flow_Table pairs, key in
421 range 0 to 254
422 fail_mode optional string, either secure or stand‐
423 alone
424 datapath_id optional string
425 other_config : datapath-id optional string
426 other_config : dp-desc optional string
427 other_config : disable-in-band
428 optional string, either true or false
429 other_config : in-band-queue
430 optional string, containing an integer,
431 in range 0 to 4,294,967,295
432 protocols set of strings, one of OpenFlow11, Open‐
433 Flow10, OpenFlow13, or OpenFlow12
434 Spanning Tree Configuration:
435 stp_enable boolean
436 other_config : stp-system-id
437 optional string
438 other_config : stp-priority
439 optional string, containing an integer,
440 in range 0 to 65,535
441 other_config : stp-hello-time
442 optional string, containing an integer,
443 in range 1 to 10
444 other_config : stp-max-age optional string, containing an integer,
445 in range 6 to 40
446 other_config : stp-forward-delay
447 optional string, containing an integer,
448 in range 4 to 30
449 Other Features:
450 datapath_type string
451 external_ids : bridge-id optional string
452 external_ids : xs-network-uuids
453 optional string
454 other_config : hwaddr optional string
455 other_config : forward-bpdu
456 optional string, either true or false
457 other_config : mac-aging-time
458 optional string, containing an integer,
459 at least 1
460 other_config : mac-table-size
461 optional string, containing an integer,
462 at least 1
463 Bridge Status:
464 status map of string-string pairs
465 status : stp_bridge_id optional string
466 status : stp_designated_root
467 optional string
468 status : stp_root_path_cost
469 optional string
470 Common Columns:
471 other_config map of string-string pairs
472 external_ids map of string-string pairs
473 Details:
475 Core Features:
476 name: string (must be unique within table)
478 Bridge identifier. Should be alphanumeric and no more than
479 about 8 bytes long. Must be unique among the names of ports,
480 interfaces, and bridges on a host.
481 ports: set of Ports
483 Ports included in the bridge.
484 mirrors: set of Mirrors
486 Port mirroring configuration.
487 netflow: optional NetFlow
489 NetFlow configuration.
490 sflow: optional sFlow
492 sFlow(R) configuration.
493 ipfix: optional IPFIX
495 IPFIX configuration.
496 flood_vlans: set of up to 4,096 integers, in range 0 to 4,095
498 VLAN IDs of VLANs on which MAC address learning should be dis‐
499 abled, so that packets are flooded instead of being sent to spe‐
500 cific ports that are believed to contain packets’ destination
501 MACs. This should ordinarily be used to disable MAC learning on
502 VLANs used for mirroring (RSPAN VLANs). It may also be useful
503 for debugging.
504 SLB bonding (see the bond_mode column in the Port table) is
506 incompatible with flood_vlans. Consider using another bonding
507 mode or a different type of mirror instead.
508 OpenFlow Configuration:
510 controller: set of Controllers
512 OpenFlow controller set. If unset, then no OpenFlow controllers
513 will be used.
514 If there are primary controllers, removing all of them clears
516 the flow table. If there are no primary controllers, adding one
517 also clears the flow table. Other changes to the set of con‐
518 trollers, such as adding or removing a service controller,
519 adding another primary controller to supplement an existing pri‐
520 mary controller, or removing only one of two primary con‐
521 trollers, have no effect on the flow table.
522 flow_tables: map of integer-Flow_Table pairs, key in range 0 to 254
524 Configuration for OpenFlow tables. Each pair maps from an Open‐
525 Flow table ID to configuration for that table.
526 fail_mode: optional string, either secure or standalone
528 When a controller is configured, it is, ordinarily, responsible
529 for setting up all flows on the switch. Thus, if the connection
530 to the controller fails, no new network connections can be set
531 up. If the connection to the controller stays down long enough,
532 no packets can pass through the switch at all. This setting
533 determines the switch’s response to such a situation. It may be
534 set to one of the following:
535 standalone
537 If no message is received from the controller for three
538 times the inactivity probe interval (see inactiv‐
539 ity_probe), then Open vSwitch will take over responsibil‐
540 ity for setting up flows. In this mode, Open vSwitch
541 causes the bridge to act like an ordinary MAC-learning
542 switch. Open vSwitch will continue to retry connecting
543 to the controller in the background and, when the connec‐
544 tion succeeds, it will discontinue its standalone behav‐
545 ior.
546 secure Open vSwitch will not set up flows on its own when the
548 controller connection fails or when no controllers are
549 defined. The bridge will continue to retry connecting to
550 any defined controllers forever.
551 The default is standalone if the value is unset, but future ver‐
553 sions of Open vSwitch may change the default.
554 The standalone mode can create forwarding loops on a bridge that
556 has more than one uplink port unless STP is enabled. To avoid
557 loops on such a bridge, configure secure mode or enable STP (see
558 stp_enable).
559 When more than one controller is configured, fail_mode is con‐
561 sidered only when none of the configured controllers can be con‐
562 tacted.
563 Changing fail_mode when no primary controllers are configured
565 clears the flow table.
566 datapath_id: optional string
568 Reports the OpenFlow datapath ID in use. Exactly 16 hex digits.
569 (Setting this column has no useful effect. Set other-con‐
570 fig:datapath-id instead.)
571 other_config : datapath-id: optional string
573 Exactly 16 hex digits to set the OpenFlow datapath ID to a spe‐
574 cific value. May not be all-zero.
575 other_config : dp-desc: optional string
577 Human readable description of datapath. It it a maximum 256
578 byte-long free-form string to describe the datapath for debug‐
579 ging purposes, e.g. switch3 in room 3120.
580 other_config : disable-in-band: optional string, either true or false
582 If set to true, disable in-band control on the bridge regardless
583 of controller and manager settings.
584 other_config : in-band-queue: optional string, containing an integer,
586 in range 0 to 4,294,967,295
587 A queue ID as a nonnegative integer. This sets the OpenFlow
588 queue ID that will be used by flows set up by in-band control on
589 this bridge. If unset, or if the port used by an in-band con‐
590 trol flow does not have QoS configured, or if the port does not
591 have a queue with the specified ID, the default queue is used
592 instead.
593 protocols: set of strings, one of OpenFlow11, OpenFlow10, OpenFlow13,
595 or OpenFlow12
596 List of OpenFlow protocols that may be used when negotiating a
597 connection with a controller. A default value of OpenFlow10
598 will be used if this column is empty.
599 Spanning Tree Configuration:
601 The IEEE 802.1D Spanning Tree Protocol (STP) is a network protocol that
602 ensures loop-free topologies. It allows redundant links to be included
603 in the network to provide automatic backup paths if the active links
604 fails.
605 stp_enable: boolean
607 Enable spanning tree on the bridge. By default, STP is disabled
608 on bridges. Bond, internal, and mirror ports are not supported
609 and will not participate in the spanning tree.
610 other_config : stp-system-id: optional string
612 The bridge’s STP identifier (the lower 48 bits of the bridge-id)
613 in the form xx:xx:xx:xx:xx:xx. By default, the identifier is
614 the MAC address of the bridge.
615 other_config : stp-priority: optional string, containing an integer, in
617 range 0 to 65,535
618 The bridge’s relative priority value for determining the root
619 bridge (the upper 16 bits of the bridge-id). A bridge with the
620 lowest bridge-id is elected the root. By default, the priority
621 is 0x8000.
622 other_config : stp-hello-time: optional string, containing an integer,
624 in range 1 to 10
625 The interval between transmissions of hello messages by desig‐
626 nated ports, in seconds. By default the hello interval is 2
627 seconds.
628 other_config : stp-max-age: optional string, containing an integer, in
630 range 6 to 40
631 The maximum age of the information transmitted by the bridge
632 when it is the root bridge, in seconds. By default, the maximum
633 age is 20 seconds.
634 other_config : stp-forward-delay: optional string, containing an inte‐
636 ger, in range 4 to 30
637 The delay to wait between transitioning root and designated
638 ports to forwarding, in seconds. By default, the forwarding
639 delay is 15 seconds.
640 Other Features:
642 datapath_type: string
644 Name of datapath provider. The kernel datapath has type system.
645 The userspace datapath has type netdev.
646 external_ids : bridge-id: optional string
648 A unique identifier of the bridge. On Citrix XenServer this
649 will commonly be the same as external_ids:xs-network-uuids.
650 external_ids : xs-network-uuids: optional string
652 Semicolon-delimited set of universally unique identifier(s) for
653 the network with which this bridge is associated on a Citrix
654 XenServer host. The network identifiers are RFC 4122 UUIDs as
655 displayed by, e.g., xe network-list.
656 other_config : hwaddr: optional string
658 An Ethernet address in the form xx:xx:xx:xx:xx:xx to set the
659 hardware address of the local port and influence the datapath
660 ID.
661 other_config : forward-bpdu: optional string, either true or false
663 Option to allow forwarding of BPDU frames when NORMAL action is
664 invoked. Frames with reserved Ethernet addresses (e.g. STP
665 BPDU) will be forwarded when this option is enabled and the
666 switch is not providing that functionality. If STP is enabled
667 on the port, STP BPDUs will never be forwarded. If the Open
668 vSwitch bridge is used to connect different Ethernet networks,
669 and if Open vSwitch node does not run STP, then this option
670 should be enabled. Default is disabled, set to true to enable.
671 The following destination MAC addresss will not be forwarded
672 when this option is enabled.
673 01:80:c2:00:00:00
675 IEEE 802.1D Spanning Tree Protocol (STP).
676 01:80:c2:00:00:01
678 IEEE Pause frame.
679 01:80:c2:00:00:0x
681 Other reserved protocols.
682 00:e0:2b:00:00:00
684 Extreme Discovery Protocol (EDP).
685 00:e0:2b:00:00:04 and 00:e0:2b:00:00:06
687 Ethernet Automatic Protection Switching (EAPS).
688 01:00:0c:cc:cc:cc
690 Cisco Discovery Protocol (CDP), VLAN Trunking Protocol
691 (VTP), Dynamic Trunking Protocol (DTP), Port Aggregation
692 Protocol (PAgP), and others.
693 01:00:0c:cc:cc:cd
695 Cisco Shared Spanning Tree Protocol PVSTP+.
696 01:00:0c:cd:cd:cd
698 Cisco STP Uplink Fast.
699 01:00:0c:00:00:00
701 Cisco Inter Switch Link.
702 01:00:0c:cc:cc:cx
704 Cisco CFM.
705 other_config : mac-aging-time: optional string, containing an integer,
707 at least 1
708 The maximum number of seconds to retain a MAC learning entry for
709 which no packets have been seen. The default is currently 300
710 seconds (5 minutes). The value, if specified, is forced into a
711 reasonable range, currently 15 to 3600 seconds.
712 A short MAC aging time allows a network to more quickly detect
714 that a host is no longer connected to a switch port. However,
715 it also makes it more likely that packets will be flooded unnec‐
716 essarily, when they are addressed to a connected host that
717 rarely transmits packets. To reduce the incidence of unneces‐
718 sary flooding, use a MAC aging time longer than the maximum
719 interval at which a host will ordinarily transmit packets.
720 other_config : mac-table-size: optional string, containing an integer,
722 at least 1
723 The maximum number of MAC addresses to learn. The default is
724 currently 2048. The value, if specified, is forced into a rea‐
725 sonable range, currently 10 to 1,000,000.
726 Bridge Status:
728 Status information about bridges.
729 status: map of string-string pairs
731 Key-value pairs that report bridge status.
732 status : stp_bridge_id: optional string
734 The bridge-id (in hex) used in spanning tree advertisements.
735 Configuring the bridge-id is described in the stp-system-id and
736 stp-priority keys of the other_config section earlier.
737 status : stp_designated_root: optional string
739 The designated root (in hex) for this spanning tree.
740 status : stp_root_path_cost: optional string
742 The path cost of reaching the designated bridge. A lower number
743 is better.
744 Common Columns:
746 The overall purpose of these columns is described under Common Columns
747 at the beginning of this document.
748 other_config: map of string-string pairs
750 external_ids: map of string-string pairs
752
754 A port within a Bridge.
755 Most commonly, a port has exactly one ``interface,’’ pointed to by its
757 interfaces column. Such a port logically corresponds to a port on a
758 physical Ethernet switch. A port with more than one interface is a
759 ``bonded port’’ (see Bonding Configuration).
760 Some properties that one might think as belonging to a port are actu‐
762 ally part of the port’s Interface members.
763 Summary:
765 name string (must be unique within table)
766 interfaces set of 1 or more Interfaces
767 VLAN Configuration:
768 vlan_mode optional string, one of access,
769 native-tagged, native-untagged, or trunk
770 tag optional integer, in range 0 to 4,095
771 trunks set of up to 4,096 integers, in range 0
772 to 4,095
773 other_config : priority-tags
774 optional string, either true or false
775 Bonding Configuration:
776 bond_mode optional string, one of active-backup,
777 balance-tcp, or balance-slb
778 other_config : bond-hash-basis
779 optional string, containing an integer
780 Link Failure Detection:
781 other_config : bond-detect-mode
782 optional string, either miimon or carrier
783 other_config : bond-miimon-interval
784 optional string, containing an integer
785 bond_updelay integer
786 bond_downdelay integer
787 LACP Configuration:
788 lacp optional string, one of active, passive,
789 or off
790 other_config : lacp-system-id
791 optional string
792 other_config : lacp-system-priority
793 optional string, containing an integer,
794 in range 1 to 65,535
795 other_config : lacp-time optional string, either slow or fast
796 Rebalancing Configuration:
797 other_config : bond-rebalance-interval
798 optional string, containing an integer,
799 in range 0 to 10,000
800 bond_fake_iface boolean
801 Spanning Tree Configuration:
802 other_config : stp-enable optional string, either true or false
803 other_config : stp-port-num
804 optional string, containing an integer,
805 in range 1 to 255
806 other_config : stp-port-priority
807 optional string, containing an integer,
808 in range 0 to 255
809 other_config : stp-path-cost
810 optional string, containing an integer,
811 in range 0 to 65,535
812 Other Features:
813 qos optional QoS
814 mac optional string
815 fake_bridge boolean
816 external_ids : fake-bridge-id-*
817 optional string
818 Port Status:
819 status map of string-string pairs
820 status : stp_port_id optional string
821 status : stp_state optional string, one of disabled, for‐
822 warding, learning, listening, or blocking
823 status : stp_sec_in_state optional string, containing an integer,
824 at least 0
825 status : stp_role optional string, one of designated,
826 alternate, or root
827 Port Statistics:
828 Statistics: STP transmit and receive counters:
829 statistics : stp_tx_count
830 optional integer
831 statistics : stp_rx_count
832 optional integer
833 statistics : stp_error_count
834 optional integer
835 Common Columns:
836 other_config map of string-string pairs
837 external_ids map of string-string pairs
838 Details:
840 name: string (must be unique within table)
841 Port name. Should be alphanumeric and no more than about 8
842 bytes long. May be the same as the interface name, for non-
843 bonded ports. Must otherwise be unique among the names of
844 ports, interfaces, and bridges on a host.
845 interfaces: set of 1 or more Interfaces
847 The port’s interfaces. If there is more than one, this is a
848 bonded Port.
849 VLAN Configuration:
851 Bridge ports support the following types of VLAN configuration:
852 trunk A trunk port carries packets on one or more specified
854 VLANs specified in the trunks column (often, on every
855 VLAN). A packet that ingresses on a trunk port is in the
856 VLAN specified in its 802.1Q header, or VLAN 0 if the
857 packet has no 802.1Q header. A packet that egresses
858 through a trunk port will have an 802.1Q header if it has
859 a nonzero VLAN ID.
860 Any packet that ingresses on a trunk port tagged with a
862 VLAN that the port does not trunk is dropped.
863 access An access port carries packets on exactly one VLAN speci‐
865 fied in the tag column. Packets egressing on an access
866 port have no 802.1Q header.
867 Any packet with an 802.1Q header with a nonzero VLAN ID
869 that ingresses on an access port is dropped, regardless
870 of whether the VLAN ID in the header is the access port’s
871 VLAN ID.
872 native-tagged
874 A native-tagged port resembles a trunk port, with the
875 exception that a packet without an 802.1Q header that
876 ingresses on a native-tagged port is in the ``native
877 VLAN’’ (specified in the tag column).
878 native-untagged
880 A native-untagged port resembles a native-tagged port,
881 with the exception that a packet that egresses on a
882 native-untagged port in the native VLAN will not have an
883 802.1Q header.
884 A packet will only egress through bridge ports that carry the VLAN of
886 the packet, as described by the rules above.
887 vlan_mode: optional string, one of access, native-tagged,
889 native-untagged, or trunk
890 The VLAN mode of the port, as described above. When this column
891 is empty, a default mode is selected as follows:
892 · If tag contains a value, the port is an access port. The
894 trunks column should be empty.
895 · Otherwise, the port is a trunk port. The trunks column
897 value is honored if it is present.
898 tag: optional integer, in range 0 to 4,095
900 For an access port, the port’s implicitly tagged VLAN. For a
901 native-tagged or native-untagged port, the port’s native VLAN.
902 Must be empty if this is a trunk port.
903 trunks: set of up to 4,096 integers, in range 0 to 4,095
905 For a trunk, native-tagged, or native-untagged port, the 802.1Q
906 VLAN or VLANs that this port trunks; if it is empty, then the
907 port trunks all VLANs. Must be empty if this is an access port.
908 A native-tagged or native-untagged port always trunks its native
910 VLAN, regardless of whether trunks includes that VLAN.
911 other_config : priority-tags: optional string, either true or false
913 An 802.1Q header contains two important pieces of information: a
914 VLAN ID and a priority. A frame with a zero VLAN ID, called a
915 ``priority-tagged’’ frame, is supposed to be treated the same
916 way as a frame without an 802.1Q header at all (except for the
917 priority).
918 However, some network elements ignore any frame that has 802.1Q
920 header at all, even when the VLAN ID is zero. Therefore, by
921 default Open vSwitch does not output priority-tagged frames,
922 instead omitting the 802.1Q header entirely if the VLAN ID is
923 zero. Set this key to true to enable priority-tagged frames on
924 a port.
925 Regardless of this setting, Open vSwitch omits the 802.1Q header
927 on output if both the VLAN ID and priority would be zero.
928 All frames output to native-tagged ports have a nonzero VLAN ID,
930 so this setting is not meaningful on native-tagged ports.
931 Bonding Configuration:
933 A port that has more than one interface is a ``bonded port.’’ Bonding
934 allows for load balancing and fail-over.
935 The following types of bonding will work with any kind of upstream
937 switch. On the upstream switch, do not configure the interfaces as a
938 bond:
939 balance-slb
941 Balances flows among slaves based on source MAC address
942 and output VLAN, with periodic rebalancing as traffic
943 patterns change.
944 active-backup
946 Assigns all flows to one slave, failing over to a backup
947 slave when the active slave is disabled. This is the
948 only bonding mode in which interfaces may be plugged into
949 different upstream switches.
950 The following modes require the upstream switch to support 802.3ad with
952 successful LACP negotiation:
953 balance-tcp
955 Balances flows among slaves based on L2, L3, and L4 pro‐
956 tocol information such as destination MAC address, IP
957 address, and TCP port.
958 These columns apply only to bonded ports. Their values are otherwise
960 ignored.
961 bond_mode: optional string, one of active-backup, balance-tcp, or bal‐
963 ance-slb
964 The type of bonding used for a bonded port. Defaults to
965 active-backup if unset.
966 other_config : bond-hash-basis: optional string, containing an integer
968 An integer hashed along with flows when choosing output slaves
969 in load balanced bonds. When changed, all flows will be
970 assigned different hash values possibly causing slave selection
971 decisions to change. Does not affect bonding modes which do not
972 employ load balancing such as active-backup.
973 Link Failure Detection:
975 An important part of link bonding is detecting that links are down so
976 that they may be disabled. These settings determine how Open vSwitch
977 detects link failure.
978 other_config : bond-detect-mode: optional string, either miimon or car‐
980 rier
981 The means used to detect link failures. Defaults to carrier
982 which uses each interface’s carrier to detect failures. When
983 set to miimon, will check for failures by polling each inter‐
984 face’s MII.
985 other_config : bond-miimon-interval: optional string, containing an
987 integer
988 The interval, in milliseconds, between successive attempts to
989 poll each interface’s MII. Relevant only when other_con‐
990 fig:bond-detect-mode is miimon.
991 bond_updelay: integer
993 The number of milliseconds for which the link must stay up on an
994 interface before the interface is considered to be up. Specify
995 0 to enable the interface immediately.
996 This setting is honored only when at least one bonded interface
998 is already enabled. When no interfaces are enabled, then the
999 first bond interface to come up is enabled immediately.
1000 bond_downdelay: integer
1002 The number of milliseconds for which the link must stay down on
1003 an interface before the interface is considered to be down.
1004 Specify 0 to disable the interface immediately.
1005 LACP Configuration:
1007 LACP, the Link Aggregation Control Protocol, is an IEEE standard that
1008 allows switches to automatically detect that they are connected by mul‐
1009 tiple links and aggregate across those links. These settings control
1010 LACP behavior.
1011 lacp: optional string, one of active, passive, or off
1013 Configures LACP on this port. LACP allows directly connected
1014 switches to negotiate which links may be bonded. LACP may be
1015 enabled on non-bonded ports for the benefit of any switches they
1016 may be connected to. active ports are allowed to initiate LACP
1017 negotiations. passive ports are allowed to participate in LACP
1018 negotiations initiated by a remote switch, but not allowed to
1019 initiate such negotiations themselves. If LACP is enabled on a
1020 port whose partner switch does not support LACP, the bond will
1021 be disabled. Defaults to off if unset.
1022 other_config : lacp-system-id: optional string
1024 The LACP system ID of this Port. The system ID of a LACP bond
1025 is used to identify itself to its partners. Must be a nonzero
1026 MAC address. Defaults to the bridge Ethernet address if unset.
1027 other_config : lacp-system-priority: optional string, containing an
1029 integer, in range 1 to 65,535
1030 The LACP system priority of this Port. In LACP negotiations,
1031 link status decisions are made by the system with the numeri‐
1032 cally lower priority.
1033 other_config : lacp-time: optional string, either slow or fast
1035 The LACP timing which should be used on this Port. By default
1036 slow is used. When configured to be fast LACP heartbeats are
1037 requested at a rate of once per second causing connectivity
1038 problems to be detected more quickly. In slow mode, heartbeats
1039 are requested at a rate of once every 30 seconds.
1040 Rebalancing Configuration:
1042 These settings control behavior when a bond is in balance-slb or bal‐
1043 ance-tcp mode.
1044 other_config : bond-rebalance-interval: optional string, containing an
1046 integer, in range 0 to 10,000
1047 For a load balanced bonded port, the number of milliseconds
1048 between successive attempts to rebalance the bond, that is, to
1049 move flows from one interface on the bond to another in an
1050 attempt to keep usage of each interface roughly equal. If zero,
1051 load balancing is disabled on the bond (link failure still cause
1052 flows to move). If less than 1000ms, the rebalance interval
1053 will be 1000ms.
1054 bond_fake_iface: boolean
1056 For a bonded port, whether to create a fake internal interface
1057 with the name of the port. Use only for compatibility with
1058 legacy software that requires this.
1059 Spanning Tree Configuration:
1061 other_config : stp-enable: optional string, either true or false
1063 If spanning tree is enabled on the bridge, member ports are
1064 enabled by default (with the exception of bond, internal, and
1065 mirror ports which do not work with STP). If this column’s
1066 value is false spanning tree is disabled on the port.
1067 other_config : stp-port-num: optional string, containing an integer, in
1069 range 1 to 255
1070 The port number used for the lower 8 bits of the port-id. By
1071 default, the numbers will be assigned automatically. If any
1072 port’s number is manually configured on a bridge, then they must
1073 all be.
1074 other_config : stp-port-priority: optional string, containing an inte‐
1076 ger, in range 0 to 255
1077 The port’s relative priority value for determining the root port
1078 (the upper 8 bits of the port-id). A port with a lower port-id
1079 will be chosen as the root port. By default, the priority is
1080 0x80.
1081 other_config : stp-path-cost: optional string, containing an integer,
1083 in range 0 to 65,535
1084 Spanning tree path cost for the port. A lower number indicates
1085 a faster link. By default, the cost is based on the maximum
1086 speed of the link.
1087 Other Features:
1089 qos: optional QoS
1091 Quality of Service configuration for this port.
1092 mac: optional string
1094 The MAC address to use for this port for the purpose of choosing
1095 the bridge’s MAC address. This column does not necessarily
1096 reflect the port’s actual MAC address, nor will setting it
1097 change the port’s actual MAC address.
1098 fake_bridge: boolean
1100 Does this port represent a sub-bridge for its tagged VLAN within
1101 the Bridge? See ovs-vsctl(8) for more information.
1102 external_ids : fake-bridge-id-*: optional string
1104 External IDs for a fake bridge (see the fake_bridge column) are
1105 defined by prefixing a Bridge external_ids key with
1106 fake-bridge-, e.g. fake-bridge-xs-network-uuids.
1107 Port Status:
1109 Status information about ports attached to bridges.
1110 status: map of string-string pairs
1112 Key-value pairs that report port status.
1113 status : stp_port_id: optional string
1115 The port-id (in hex) used in spanning tree advertisements for
1116 this port. Configuring the port-id is described in the
1117 stp-port-num and stp-port-priority keys of the other_config sec‐
1118 tion earlier.
1119 status : stp_state: optional string, one of disabled, forwarding,
1121 learning, listening, or blocking
1122 STP state of the port.
1123 status : stp_sec_in_state: optional string, containing an integer, at
1125 least 0
1126 The amount of time (in seconds) port has been in the current STP
1127 state.
1128 status : stp_role: optional string, one of designated, alternate, or
1130 root
1131 STP role of the port.
1132 Port Statistics:
1134 Key-value pairs that report port statistics.
1135 Statistics: STP transmit and receive counters:
1137 statistics : stp_tx_count: optional integer
1139 Number of STP BPDUs sent on this port by the spanning tree
1140 library.
1141 statistics : stp_rx_count: optional integer
1143 Number of STP BPDUs received on this port and accepted by the
1144 spanning tree library.
1145 statistics : stp_error_count: optional integer
1147 Number of bad STP BPDUs received on this port. Bad BPDUs
1148 include runt packets and those with an unexpected protocol ID.
1149 Common Columns:
1151 The overall purpose of these columns is described under Common Columns
1152 at the beginning of this document.
1153 other_config: map of string-string pairs
1155 external_ids: map of string-string pairs
1157
1159 An interface within a Port.
1160 Summary:
1162 Core Features:
1163 name string (must be unique within table)
1164 ifindex optional integer, in range 0 to
1165 4,294,967,295
1166 mac_in_use optional string
1167 mac optional string
1168 ofport optional integer
1169 ofport_request optional integer, in range 1 to 65,279
1170 System-Specific Details:
1171 type string
1172 Tunnel Options:
1173 options : remote_ip optional string
1174 options : local_ip optional string
1175 options : in_key optional string
1176 options : out_key optional string
1177 options : key optional string
1178 options : tos optional string
1179 options : ttl optional string
1180 options : df_default optional string, either true or false
1181 Tunnel Options: gre and ipsec_gre only:
1182 options : csum optional string, either true or false
1183 Tunnel Options: ipsec_gre only:
1184 options : peer_cert optional string
1185 options : certificate optional string
1186 options : private_key optional string
1187 options : psk optional string
1188 Patch Options:
1189 options : peer optional string
1190 Interface Status:
1191 admin_state optional string, either down or up
1192 link_state optional string, either down or up
1193 link_resets optional integer
1194 link_speed optional integer
1195 duplex optional string, either full or half
1196 mtu optional integer
1197 lacp_current optional boolean
1198 status map of string-string pairs
1199 status : driver_name optional string
1200 status : driver_version optional string
1201 status : firmware_version optional string
1202 status : source_ip optional string
1203 status : tunnel_egress_iface
1204 optional string
1205 status : tunnel_egress_iface_carrier
1206 optional string, either down or up
1207 Statistics:
1208 Statistics: Successful transmit and receive counters:
1209 statistics : rx_packets optional integer
1210 statistics : rx_bytes optional integer
1211 statistics : tx_packets optional integer
1212 statistics : tx_bytes optional integer
1213 Statistics: Receive errors:
1214 statistics : rx_dropped optional integer
1215 statistics : rx_frame_err
1216 optional integer
1217 statistics : rx_over_err optional integer
1218 statistics : rx_crc_err optional integer
1219 statistics : rx_errors optional integer
1220 Statistics: Transmit errors:
1221 statistics : tx_dropped optional integer
1222 statistics : collisions optional integer
1223 statistics : tx_errors optional integer
1224 Ingress Policing:
1225 ingress_policing_rate integer, at least 0
1226 ingress_policing_burst integer, at least 0
1227 Bidirectional Forwarding Detection (BFD):
1228 bfd : enable optional string
1229 bfd : min_rx optional string, containing an integer,
1230 at least 1
1231 bfd : min_tx optional string, containing an integer,
1232 at least 1
1233 bfd : decay_min_rx optional string, containing an integer
1234 bfd : forwarding_if_rx optional string, either true or false
1235 bfd : cpath_down optional string, either true or false
1236 bfd : check_tnl_key optional string, either true or false
1237 bfd : bfd_dst_mac optional string
1238 bfd_status : state optional string, one of down, init, up,
1239 or admin_down
1240 bfd_status : forwarding optional string, either true or false
1241 bfd_status : diagnostic optional string
1242 bfd_status : remote_state optional string, one of down, init, up,
1243 or admin_down
1244 bfd_status : remote_diagnostic
1245 optional string
1246 Connectivity Fault Management:
1247 cfm_mpid optional integer
1248 cfm_fault optional boolean
1249 cfm_fault_status : recv none
1250 cfm_fault_status : rdi none
1251 cfm_fault_status : maid none
1252 cfm_fault_status : loopback
1253 none
1254 cfm_fault_status : overflow
1255 none
1256 cfm_fault_status : override
1257 none
1258 cfm_fault_status : interval
1259 none
1260 cfm_remote_opstate optional string, either down or up
1261 cfm_health optional integer, in range 0 to 100
1262 cfm_remote_mpids set of integers
1263 other_config : cfm_interval
1264 optional string, containing an integer
1265 other_config : cfm_extended
1266 optional string, either true or false
1267 other_config : cfm_demand optional string, either true or false
1268 other_config : cfm_opstate optional string, either down or up
1269 other_config : cfm_ccm_vlan
1270 optional string, containing an integer,
1271 in range 1 to 4,095
1272 other_config : cfm_ccm_pcp optional string, containing an integer,
1273 in range 1 to 7
1274 Bonding Configuration:
1275 other_config : lacp-port-id
1276 optional string, containing an integer,
1277 in range 1 to 65,535
1278 other_config : lacp-port-priority
1279 optional string, containing an integer,
1280 in range 1 to 65,535
1281 other_config : lacp-aggregation-key
1282 optional string, containing an integer,
1283 in range 1 to 65,535
1284 Virtual Machine Identifiers:
1285 external_ids : attached-mac
1286 optional string
1287 external_ids : iface-id optional string
1288 external_ids : iface-status
1289 optional string, either active or inac‐
1290 tive
1291 external_ids : xs-vif-uuid optional string
1292 external_ids : xs-network-uuid
1293 optional string
1294 external_ids : vm-id optional string
1295 external_ids : xs-vm-uuid optional string
1296 VLAN Splinters:
1297 other_config : enable-vlan-splinters
1298 optional string, either true or false
1299 Common Columns:
1300 other_config map of string-string pairs
1301 external_ids map of string-string pairs
1302 Details:
1304 Core Features:
1305 name: string (must be unique within table)
1307 Interface name. Should be alphanumeric and no more than about 8
1308 bytes long. May be the same as the port name, for non-bonded
1309 ports. Must otherwise be unique among the names of ports,
1310 interfaces, and bridges on a host.
1311 ifindex: optional integer, in range 0 to 4,294,967,295
1313 A positive interface index as defined for SNMP MIB-II in RFCs
1314 1213 and 2863, if the interface has one, otherwise 0. The
1315 ifindex is useful for seamless integration with protocols such
1316 as SNMP and sFlow.
1317 mac_in_use: optional string
1319 The MAC address in use by this interface.
1320 mac: optional string
1322 Ethernet address to set for this interface. If unset then the
1323 default MAC address is used:
1324 · For the local interface, the default is the lowest-num‐
1326 bered MAC address among the other bridge ports, either
1327 the value of the mac in its Port record, if set, or its
1328 actual MAC (for bonded ports, the MAC of its slave whose
1329 name is first in alphabetical order). Internal ports and
1330 bridge ports that are used as port mirroring destinations
1331 (see the Mirror table) are ignored.
1332 · For other internal interfaces, the default MAC is ran‐
1334 domly generated.
1335 · External interfaces typically have a MAC address associ‐
1337 ated with their hardware.
1338 Some interfaces may not have a software-controllable MAC
1340 address.
1341 ofport: optional integer
1343 OpenFlow port number for this interface. Unlike most columns,
1344 this column’s value should be set only by Open vSwitch itself.
1345 Other clients should set this column to an empty set (the
1346 default) when creating an Interface.
1347 Open vSwitch populates this column when the port number becomes
1349 known. If the interface is successfully added, ofport will be
1350 set to a number between 1 and 65535 (generally either in the
1351 range 1 to 65279, inclusive, or 65534, the port number for the
1352 OpenFlow ``local port’’). If the interface cannot be added then
1353 Open vSwitch sets this column to -1.
1354 When ofport_request is not set, Open vSwitch picks an appropri‐
1356 ate value for this column and then tries to keep the value con‐
1357 stant across restarts.
1358 ofport_request: optional integer, in range 1 to 65,279
1360 Requested OpenFlow port number for this interface. The port
1361 number must be between 1 and 65279, inclusive. Some datapaths
1362 cannot satisfy all requests for particular port numbers. When
1363 this column is empty or the request cannot be fulfilled, the
1364 system will choose a free port. The ofport column reports the
1365 assigned OpenFlow port number.
1366 The port number must be requested in the same transaction that
1368 creates the port.
1369 System-Specific Details:
1371 type: string
1373 The interface type, one of:
1374 system An ordinary network device, e.g. eth0 on Linux. Some‐
1376 times referred to as ``external interfaces’’ since they
1377 are generally connected to hardware external to that on
1378 which the Open vSwitch is running. The empty string is a
1379 synonym for system.
1380 internal
1382 A simulated network device that sends and receives traf‐
1383 fic. An internal interface whose name is the same as its
1384 bridge’s name is called the ``local interface.’’ It does
1385 not make sense to bond an internal interface, so the
1386 terms ``port’’ and ``interface’’ are often used impre‐
1387 cisely for internal interfaces.
1388 tap A TUN/TAP device managed by Open vSwitch.
1390 gre An Ethernet over RFC 2890 Generic Routing Encapsulation
1392 over IPv4 tunnel.
1393 ipsec_gre
1395 An Ethernet over RFC 2890 Generic Routing Encapsulation
1396 over IPv4 IPsec tunnel.
1397 gre64 It is same as GRE, but it allows 64 bit key. To store
1399 higher 32-bits of key, it uses GRE protocol sequence num‐
1400 ber field. This is non standard use of GRE protocol since
1401 OVS does not increment sequence number for every packet
1402 at time of encap as expected by standard GRE implementa‐
1403 tion. See Tunnel Options for information on configuring
1404 GRE tunnels.
1405 ipsec_gre64
1407 Same as IPSEC_GRE except 64 bit key.
1408 vxlan An Ethernet tunnel over the experimental, UDP-based VXLAN
1410 protocol described at
1411 http://tools.ietf.org/html/draft-mahalingam-dutt-dcops-vxlan-03.
1412 Open vSwitch uses UDP destination port 4789. The source
1414 port used for VXLAN traffic varies on a per-flow basis
1415 and is in the ephemeral port range.
1416 lisp A layer 3 tunnel over the experimental, UDP-based Loca‐
1418 tor/ID Separation Protocol (RFC 6830).
1419 patch A pair of virtual devices that act as a patch cable.
1421 null An ignored interface. Deprecated and slated for removal
1423 in February 2013.
1424 Tunnel Options:
1426 These options apply to interfaces with type of gre, ipsec_gre, gre64,
1427 ipsec_gre64, vxlan, and lisp.
1428 Each tunnel must be uniquely identified by the combination of type,
1430 options:remote_ip, options:local_ip, and options:in_key. If two ports
1431 are defined that are the same except one has an optional identifier and
1432 the other does not, the more specific one is matched first.
1433 options:in_key is considered more specific than options:local_ip if a
1434 port defines one and another port defines the other.
1435 options : remote_ip: optional string
1437 Required. The remote tunnel endpoint, one of:
1438 · An IPv4 address (not a DNS name), e.g. 192.168.0.123.
1440 Only unicast endpoints are supported.
1441 · The word flow. The tunnel accepts packets from any
1443 remote tunnel endpoint. To process only packets from a
1444 specific remote tunnel endpoint, the flow entries may
1445 match on the tun_src field. When sending packets to a
1446 remote_ip=flow tunnel, the flow actions must explicitly
1447 set the tun_dst field to the IP address of the desired
1448 remote tunnel endpoint, e.g. with a set_field action.
1449 The remote tunnel endpoint for any packet received from a tunnel
1451 is available in the tun_src field for matching in the flow ta‐
1452 ble.
1453 options : local_ip: optional string
1455 Optional. The tunnel destination IP that received packets must
1456 match. Default is to match all addresses. If specified, may be
1457 one of:
1458 · An IPv4 address (not a DNS name), e.g. 192.168.12.3.
1460 · The word flow. The tunnel accepts packets sent to any of
1462 the local IP addresses of the system running OVS. To
1463 process only packets sent to a specific IP address, the
1464 flow entries may match on the tun_dst field. When send‐
1465 ing packets to a local_ip=flow tunnel, the flow actions
1466 may explicitly set the tun_src field to the desired IP
1467 address, e.g. with a set_field action. However, while
1468 routing the tunneled packet out, the local system may
1469 override the specified address with the local IP address
1470 configured for the outgoing system interface.
1471 This option is valid only for tunnels also configured
1473 with the remote_ip=flow option.
1474 The tunnel destination IP address for any packet received from a
1476 tunnel is available in the tun_dst field for matching in the
1477 flow table.
1478 options : in_key: optional string
1480 Optional. The key that received packets must contain, one of:
1481 · 0. The tunnel receives packets with no key or with a key
1483 of 0. This is equivalent to specifying no options:in_key
1484 at all.
1485 · A positive 24-bit (for VXLAN and LISP), 32-bit (for GRE)
1487 or 64-bit (for GRE64) number. The tunnel receives only
1488 packets with the specified key.
1489 · The word flow. The tunnel accepts packets with any key.
1491 The key will be placed in the tun_id field for matching
1492 in the flow table. The ovs-ofctl manual page contains
1493 additional information about matching fields in OpenFlow
1494 flows.
1495 options : out_key: optional string
1497 Optional. The key to be set on outgoing packets, one of:
1498 · 0. Packets sent through the tunnel will have no key.
1500 This is equivalent to specifying no options:out_key at
1501 all.
1502 · A positive 24-bit (for VXLAN and LISP), 32-bit (for GRE)
1504 or 64-bit (for GRE64) number. Packets sent through the
1505 tunnel will have the specified key.
1506 · The word flow. Packets sent through the tunnel will have
1508 the key set using the set_tunnel Nicira OpenFlow vendor
1509 extension (0 is used in the absence of an action). The
1510 ovs-ofctl manual page contains additional information
1511 about the Nicira OpenFlow vendor extensions.
1512 options : key: optional string
1514 Optional. Shorthand to set in_key and out_key at the same time.
1515 options : tos: optional string
1517 Optional. The value of the ToS bits to be set on the encapsu‐
1518 lating packet. ToS is interpreted as DSCP and ECN bits, ECN
1519 part must be zero. It may also be the word inherit, in which
1520 case the ToS will be copied from the inner packet if it is IPv4
1521 or IPv6 (otherwise it will be 0). The ECN fields are always
1522 inherited. Default is 0.
1523 options : ttl: optional string
1525 Optional. The TTL to be set on the encapsulating packet. It
1526 may also be the word inherit, in which case the TTL will be
1527 copied from the inner packet if it is IPv4 or IPv6 (otherwise it
1528 will be the system default, typically 64). Default is the sys‐
1529 tem default TTL.
1530 options : df_default: optional string, either true or false
1532 Optional. If enabled, the Don’t Fragment bit will be set on
1533 tunnel outer headers to allow path MTU discovery. Default is
1534 enabled; set to false to disable.
1535 Tunnel Options: gre and ipsec_gre only:
1537 Only gre and ipsec_gre interfaces support these options.
1538 options : csum: optional string, either true or false
1540 Optional. Compute GRE checksums on outgoing packets. Default
1541 is disabled, set to true to enable. Checksums present on incom‐
1542 ing packets will be validated regardless of this setting.
1543 GRE checksums impose a significant performance penalty because
1545 they cover the entire packet. The encapsulated L3, L4, and L7
1546 packet contents typically have their own checksums, so this
1547 additional checksum only adds value for the GRE and encapsulated
1548 L2 headers.
1549 This option is supported for ipsec_gre, but not useful because
1551 GRE checksums are weaker than, and redundant with, IPsec payload
1552 authentication.
1553 Tunnel Options: ipsec_gre only:
1555 Only ipsec_gre interfaces support these options.
1556 options : peer_cert: optional string
1558 Required for certificate authentication. A string containing
1559 the peer’s certificate in PEM format. Additionally the host’s
1560 certificate must be specified with the certificate option.
1561 options : certificate: optional string
1563 Required for certificate authentication. The name of a PEM file
1564 containing a certificate that will be presented to the peer dur‐
1565 ing authentication.
1566 options : private_key: optional string
1568 Optional for certificate authentication. The name of a PEM file
1569 containing the private key associated with certificate. If cer‐
1570 tificate contains the private key, this option may be omitted.
1571 options : psk: optional string
1573 Required for pre-shared key authentication. Specifies a pre-
1574 shared key for authentication that must be identical on both
1575 sides of the tunnel.
1576 Patch Options:
1578 Only patch interfaces support these options.
1579 options : peer: optional string
1581 The name of the Interface for the other side of the patch. The
1582 named Interface’s own peer option must specify this Interface’s
1583 name. That is, the two patch interfaces must have reversed name
1584 and peer values.
1585 Interface Status:
1587 Status information about interfaces attached to bridges, updated every
1588 5 seconds. Not all interfaces have all of these properties; virtual
1589 interfaces don’t have a link speed, for example. Non-applicable col‐
1590 umns will have empty values.
1591 admin_state: optional string, either down or up
1593 The administrative state of the physical network link.
1594 link_state: optional string, either down or up
1596 The observed state of the physical network link. This is ordi‐
1597 narily the link’s carrier status. If the interface’s Port is a
1598 bond configured for miimon monitoring, it is instead the network
1599 link’s miimon status.
1600 link_resets: optional integer
1602 The number of times Open vSwitch has observed the link_state of
1603 this Interface change.
1604 link_speed: optional integer
1606 The negotiated speed of the physical network link. Valid values
1607 are positive integers greater than 0.
1608 duplex: optional string, either full or half
1610 The duplex mode of the physical network link.
1611 mtu: optional integer
1613 The MTU (maximum transmission unit); i.e. the largest amount of
1614 data that can fit into a single Ethernet frame. The standard
1615 Ethernet MTU is 1500 bytes. Some physical media and many kinds
1616 of virtual interfaces can be configured with higher MTUs.
1617 This column will be empty for an interface that does not have an
1619 MTU as, for example, some kinds of tunnels do not.
1620 lacp_current: optional boolean
1622 Boolean value indicating LACP status for this interface. If
1623 true, this interface has current LACP information about its LACP
1624 partner. This information may be used to monitor the health of
1625 interfaces in a LACP enabled port. This column will be empty if
1626 LACP is not enabled.
1627 status: map of string-string pairs
1629 Key-value pairs that report port status. Supported status val‐
1630 ues are type-dependent; some interfaces may not have a valid
1631 status:driver_name, for example.
1632 status : driver_name: optional string
1634 The name of the device driver controlling the network adapter.
1635 status : driver_version: optional string
1637 The version string of the device driver controlling the network
1638 adapter.
1639 status : firmware_version: optional string
1641 The version string of the network adapter’s firmware, if avail‐
1642 able.
1643 status : source_ip: optional string
1645 The source IP address used for an IPv4 tunnel end-point, such as
1646 gre.
1647 status : tunnel_egress_iface: optional string
1649 Egress interface for tunnels. Currently only relevant for GRE
1650 tunnels On Linux systems, this column will show the name of the
1651 interface which is responsible for routing traffic destined for
1652 the configured options:remote_ip. This could be an internal
1653 interface such as a bridge port.
1654 status : tunnel_egress_iface_carrier: optional string, either down or
1656 up
1657 Whether carrier is detected on status:tunnel_egress_iface.
1658 Statistics:
1660 Key-value pairs that report interface statistics. The current imple‐
1661 mentation updates these counters periodically. Future implementations
1662 may update them when an interface is created, when they are queried
1663 (e.g. using an OVSDB select operation), and just before an interface is
1664 deleted due to virtual interface hot-unplug or VM shutdown, and perhaps
1665 at other times, but not on any regular periodic basis.
1666 These are the same statistics reported by OpenFlow in its struct
1668 ofp_port_stats structure. If an interface does not support a given
1669 statistic, then that pair is omitted.
1670 Statistics: Successful transmit and receive counters:
1672 statistics : rx_packets: optional integer
1674 Number of received packets.
1675 statistics : rx_bytes: optional integer
1677 Number of received bytes.
1678 statistics : tx_packets: optional integer
1680 Number of transmitted packets.
1681 statistics : tx_bytes: optional integer
1683 Number of transmitted bytes.
1684 Statistics: Receive errors:
1686 statistics : rx_dropped: optional integer
1688 Number of packets dropped by RX.
1689 statistics : rx_frame_err: optional integer
1691 Number of frame alignment errors.
1692 statistics : rx_over_err: optional integer
1694 Number of packets with RX overrun.
1695 statistics : rx_crc_err: optional integer
1697 Number of CRC errors.
1698 statistics : rx_errors: optional integer
1700 Total number of receive errors, greater than or equal to the sum
1701 of the above.
1702 Statistics: Transmit errors:
1704 statistics : tx_dropped: optional integer
1706 Number of packets dropped by TX.
1707 statistics : collisions: optional integer
1709 Number of collisions.
1710 statistics : tx_errors: optional integer
1712 Total number of transmit errors, greater than or equal to the
1713 sum of the above.
1714 Ingress Policing:
1716 These settings control ingress policing for packets received on this
1717 interface. On a physical interface, this limits the rate at which
1718 traffic is allowed into the system from the outside; on a virtual
1719 interface (one connected to a virtual machine), this limits the rate at
1720 which the VM is able to transmit.
1721 Policing is a simple form of quality-of-service that simply drops pack‐
1723 ets received in excess of the configured rate. Due to its simplicity,
1724 policing is usually less accurate and less effective than egress QoS
1725 (which is configured using the QoS and Queue tables).
1726 Policing is currently implemented only on Linux. The Linux implementa‐
1728 tion uses a simple ``token bucket’’ approach:
1729 · The size of the bucket corresponds to ingress_polic‐
1731 ing_burst. Initially the bucket is full.
1732 · Whenever a packet is received, its size (converted to
1734 tokens) is compared to the number of tokens currently in
1735 the bucket. If the required number of tokens are avail‐
1736 able, they are removed and the packet is forwarded. Oth‐
1737 erwise, the packet is dropped.
1738 · Whenever it is not full, the bucket is refilled with
1740 tokens at the rate specified by ingress_policing_rate.
1741 Policing interacts badly with some network protocols, and especially
1743 with fragmented IP packets. Suppose that there is enough network
1744 activity to keep the bucket nearly empty all the time. Then this token
1745 bucket algorithm will forward a single packet every so often, with the
1746 period depending on packet size and on the configured rate. All of the
1747 fragments of an IP packets are normally transmitted back-to-back, as a
1748 group. In such a situation, therefore, only one of these fragments
1749 will be forwarded and the rest will be dropped. IP does not provide
1750 any way for the intended recipient to ask for only the remaining frag‐
1751 ments. In such a case there are two likely possibilities for what will
1752 happen next: either all of the fragments will eventually be retransmit‐
1753 ted (as TCP will do), in which case the same problem will recur, or the
1754 sender will not realize that its packet has been dropped and data will
1755 simply be lost (as some UDP-based protocols will do). Either way, it
1756 is possible that no forward progress will ever occur.
1757 ingress_policing_rate: integer, at least 0
1759 Maximum rate for data received on this interface, in kbps. Data
1760 received faster than this rate is dropped. Set to 0 (the
1761 default) to disable policing.
1762 ingress_policing_burst: integer, at least 0
1764 Maximum burst size for data received on this interface, in kb.
1765 The default burst size if set to 0 is 1000 kb. This value has
1766 no effect if ingress_policing_rate is 0.
1767 Specifying a larger burst size lets the algorithm be more for‐
1769 giving, which is important for protocols like TCP that react se‐
1770 verely to dropped packets. The burst size should be at least
1771 the size of the interface’s MTU. Specifying a value that is
1772 numerically at least as large as 10% of ingress_policing_rate
1773 helps TCP come closer to achieving the full rate.
1774 Bidirectional Forwarding Detection (BFD):
1776 BFD, defined in RFC 5880 and RFC 5881, allows point to point detection
1777 of connectivity failures by occasional transmission of BFD control mes‐
1778 sages. It is implemented in Open vSwitch to serve as a more popular
1779 and standards compliant alternative to CFM.
1780 BFD operates by regularly transmitting BFD control messages at a rate
1782 negotiated independently in each direction. Each endpoint specifies
1783 the rate at which it expects to receive control messages, and the rate
1784 at which it’s willing to transmit them. Open vSwitch uses a detection
1785 multiplier of three, meaning that an endpoint which fails to receive
1786 BFD control messages for a period of three times the expected reception
1787 rate, will signal a connectivity fault. In the case of a unidirec‐
1788 tional connectivity issue, the system not receiving BFD control mes‐
1789 sages will signal the problem to its peer in the messages it transmits.
1790 The Open vSwitch implementation of BFD aims to comply faithfully with
1792 the requirements put forth in RFC 5880. Currently, the only known
1793 omission is ``Demand Mode’’, which we hope to include in future. Open
1794 vSwitch does not implement the optional Authentication or ``Echo Mode’’
1795 features.
1796 bfd : enable: optional string
1798 When true BFD is enabled on this Interface, otherwise it’s dis‐
1799 abled. Defaults to false.
1800 bfd : min_rx: optional string, containing an integer, at least 1
1802 The fastest rate, in milliseconds, at which this BFD session is
1803 willing to receive BFD control messages. The actual rate may be
1804 slower if the remote endpoint isn’t willing to transmit as
1805 quickly as specified. Defaults to 1000.
1806 bfd : min_tx: optional string, containing an integer, at least 1
1808 The fastest rate, in milliseconds, at which this BFD session is
1809 willing to transmit BFD control messages. The actual rate may
1810 be slower if the remote endpoint isn’t willing to receive as
1811 quickly as specified. Defaults to 100.
1812 bfd : decay_min_rx: optional string, containing an integer
1814 decay_min_rx is used to set the min_rx, when there is no obvious
1815 incoming data traffic at the interface. It cannot be set less
1816 than the min_rx. The decay feature is disabled by setting the
1817 decay_min_rx to 0. And the feature is reset everytime itself or
1818 min_rx is reconfigured.
1819 bfd : forwarding_if_rx: optional string, either true or false
1821 When forwarding_if_rx is true the interface will be considered
1822 capable of packet I/O as long as there is packet received at
1823 interface. This is important in that when link becomes tempo‐
1824 rarily conjested, consecutive BFD control packets can be lost.
1825 And the forwarding_if_rx can prevent link failover by detecting
1826 non-control packets received at interface.
1827 bfd : cpath_down: optional string, either true or false
1829 Concatenated path down may be used when the local system should
1830 not have traffic forwarded to it for some reason other than a
1831 connectivty failure on the interface being monitored. When a
1832 controller thinks this may be the case, it may set cpath_down to
1833 true which may cause the remote BFD session not to forward traf‐
1834 fic to this Interface. Defaults to false.
1835 bfd : check_tnl_key: optional string, either true or false
1837 When set to true, Check Tunnel Key will make BFD only accept
1838 control messages with an in_key of zero. Defaults to false.
1839 bfd : bfd_dst_mac: optional string
1841 An Ethernet address in the form xx:xx:xx:xx:xx:xx to set the
1842 destination mac address of the bfd packet. If this field is set,
1843 it is assumed that all the bfd packets destined to this inter‐
1844 face also has the same destination mac address. If not set, a
1845 default value of 00:23:20:00:00:01 is used.
1846 bfd_status : state: optional string, one of down, init, up, or
1848 admin_down
1849 State of the BFD session. The BFD session is fully healthy and
1850 negotiated if UP.
1851 bfd_status : forwarding: optional string, either true or false
1853 True if the BFD session believes this Interface may be used to
1854 forward traffic. Typically this means the local session is sig‐
1855 naling UP, and the remote system isn’t signaling a problem such
1856 as concatenated path down.
1857 bfd_status : diagnostic: optional string
1859 A short message indicating what the BFD session thinks is wrong
1860 in case of a problem.
1861 bfd_status : remote_state: optional string, one of down, init, up, or
1863 admin_down
1864 State of the remote endpoint’s BFD session.
1865 bfd_status : remote_diagnostic: optional string
1867 A short message indicating what the remote endpoint’s BFD ses‐
1868 sion thinks is wrong in case of a problem.
1869 Connectivity Fault Management:
1871 802.1ag Connectivity Fault Management (CFM) allows a group of Mainte‐
1872 nance Points (MPs) called a Maintenance Association (MA) to detect con‐
1873 nectivity problems with each other. MPs within a MA should have com‐
1874 plete and exclusive interconnectivity. This is verified by occasion‐
1875 ally broadcasting Continuity Check Messages (CCMs) at a configurable
1876 transmission interval.
1877 According to the 802.1ag specification, each Maintenance Point should
1879 be configured out-of-band with a list of Remote Maintenance Points it
1880 should have connectivity to. Open vSwitch differs from the specifica‐
1881 tion in this area. It simply assumes the link is faulted if no Remote
1882 Maintenance Points are reachable, and considers it not faulted other‐
1883 wise.
1884 When operating over tunnels which have no in_key, or an in_key of flow.
1886 CFM will only accept CCMs with a tunnel key of zero.
1887 cfm_mpid: optional integer
1889 A Maintenance Point ID (MPID) uniquely identifies each endpoint
1890 within a Maintenance Association. The MPID is used to identify
1891 this endpoint to other Maintenance Points in the MA. Each end
1892 of a link being monitored should have a different MPID. Must be
1893 configured to enable CFM on this Interface.
1894 cfm_fault: optional boolean
1896 Indicates a connectivity fault triggered by an inability to
1897 receive heartbeats from any remote endpoint. When a fault is
1898 triggered on Interfaces participating in bonds, they will be
1899 disabled.
1900 Faults can be triggered for several reasons. Most importantly
1902 they are triggered when no CCMs are received for a period of 3.5
1903 times the transmission interval. Faults are also triggered when
1904 any CCMs indicate that a Remote Maintenance Point is not receiv‐
1905 ing CCMs but able to send them. Finally, a fault is triggered
1906 if a CCM is received which indicates unexpected configuration.
1907 Notably, this case arises when a CCM is received which adver‐
1908 tises the local MPID.
1909 cfm_fault_status : recv: none
1911 Indicates a CFM fault was triggered due to a lack of CCMs
1912 received on the Interface.
1913 cfm_fault_status : rdi: none
1915 Indicates a CFM fault was triggered due to the reception of a
1916 CCM with the RDI bit flagged. Endpoints set the RDI bit in
1917 their CCMs when they are not receiving CCMs themselves. This
1918 typically indicates a unidirectional connectivity failure.
1919 cfm_fault_status : maid: none
1921 Indicates a CFM fault was triggered due to the reception of a
1922 CCM with a MAID other than the one Open vSwitch uses. CFM
1923 broadcasts are tagged with an identification number in addition
1924 to the MPID called the MAID. Open vSwitch only supports receiv‐
1925 ing CCM broadcasts tagged with the MAID it uses internally.
1926 cfm_fault_status : loopback: none
1928 Indicates a CFM fault was triggered due to the reception of a
1929 CCM advertising the same MPID configured in the cfm_mpid column
1930 of this Interface. This may indicate a loop in the network.
1931 cfm_fault_status : overflow: none
1933 Indicates a CFM fault was triggered because the CFM module
1934 received CCMs from more remote endpoints than it can keep track
1935 of.
1936 cfm_fault_status : override: none
1938 Indicates a CFM fault was manually triggered by an administrator
1939 using an ovs-appctl command.
1940 cfm_fault_status : interval: none
1942 Indicates a CFM fault was triggered due to the reception of a
1943 CCM frame having an invalid interval.
1944 cfm_remote_opstate: optional string, either down or up
1946 When in extended mode, indicates the operational state of the
1947 remote endpoint as either up or down. See other_con‐
1948 fig:cfm_opstate.
1949 cfm_health: optional integer, in range 0 to 100
1951 Indicates the health of the interface as a percentage of CCM
1952 frames received over 21 other_config:cfm_intervals. The health
1953 of an interface is undefined if it is communicating with more
1954 than one cfm_remote_mpids. It reduces if healthy heartbeats are
1955 not received at the expected rate, and gradually improves as
1956 healthy heartbeats are received at the desired rate. Every 21
1957 other_config:cfm_intervals, the health of the interface is
1958 refreshed.
1959 As mentioned above, the faults can be triggered for several rea‐
1961 sons. The link health will deteriorate even if heartbeats are
1962 received but they are reported to be unhealthy. An unhealthy
1963 heartbeat in this context is a heartbeat for which either some
1964 fault is set or is out of sequence. The interface health can be
1965 100 only on receiving healthy heartbeats at the desired rate.
1966 cfm_remote_mpids: set of integers
1968 When CFM is properly configured, Open vSwitch will occasionally
1969 receive CCM broadcasts. These broadcasts contain the MPID of
1970 the sending Maintenance Point. The list of MPIDs from which
1971 this Interface is receiving broadcasts from is regularly col‐
1972 lected and written to this column.
1973 other_config : cfm_interval: optional string, containing an integer
1975 The interval, in milliseconds, between transmissions of CFM
1976 heartbeats. Three missed heartbeat receptions indicate a con‐
1977 nectivity fault.
1978 In standard operation only intervals of 3, 10, 100, 1,000,
1980 10,000, 60,000, or 600,000 ms are supported. Other values will
1981 be rounded down to the nearest value on the list. Extended mode
1982 (see other_config:cfm_extended) supports any interval up to
1983 65,535 ms. In either mode, the default is 1000 ms.
1984 We do not recommend using intervals less than 100 ms.
1986 other_config : cfm_extended: optional string, either true or false
1988 When true, the CFM module operates in extended mode. This causes
1989 it to use a nonstandard destination address to avoid conflicting
1990 with compliant implementations which may be running concurrently
1991 on the network. Furthermore, extended mode increases the accu‐
1992 racy of the cfm_interval configuration parameter by breaking
1993 wire compatibility with 802.1ag compliant implementations.
1994 Defaults to false.
1995 other_config : cfm_demand: optional string, either true or false
1997 When true, and other_config:cfm_extended is true, the CFM module
1998 operates in demand mode. When in demand mode, traffic received
1999 on the Interface is used to indicate liveness. CCMs are still
2000 transmitted and received, but if the Interface is receiving
2001 traffic, their absence does not cause a connectivity fault.
2002 Demand mode has a couple of caveats:
2004 · To ensure that ovs-vswitchd has enough time to pull sta‐
2006 tistics from the datapath, the fault detection interval
2007 is set to 3.5 * MAX(other_config:cfm_interval, 500) ms.
2008 · To avoid ambiguity, demand mode disables itself when
2010 there are multiple remote maintenance points.
2011 · If the Interface is heavily congested, CCMs containing
2013 the other_config:cfm_opstate status may be dropped caus‐
2014 ing changes in the operational state to be delayed. Sim‐
2015 ilarly, if CCMs containing the RDI bit are not received,
2016 unidirectional link failures may not be detected.
2017 other_config : cfm_opstate: optional string, either down or up
2019 When down, the CFM module marks all CCMs it generates as opera‐
2020 tionally down without triggering a fault. This allows remote
2021 maintenance points to choose not to forward traffic to the
2022 Interface on which this CFM module is running. Currently, in
2023 Open vSwitch, the opdown bit of CCMs affects Interfaces partici‐
2024 pating in bonds, and the bundle OpenFlow action. This setting is
2025 ignored when CFM is not in extended mode. Defaults to up.
2026 other_config : cfm_ccm_vlan: optional string, containing an integer, in
2028 range 1 to 4,095
2029 When set, the CFM module will apply a VLAN tag to all CCMs it
2030 generates with the given value. May be the string random in
2031 which case each CCM will be tagged with a different randomly
2032 generated VLAN.
2033 other_config : cfm_ccm_pcp: optional string, containing an integer, in
2035 range 1 to 7
2036 When set, the CFM module will apply a VLAN tag to all CCMs it
2037 generates with the given PCP value, the VLAN ID of the tag is
2038 governed by the value of other_config:cfm_ccm_vlan. If
2039 other_config:cfm_ccm_vlan is unset, a VLAN ID of zero is used.
2040 Bonding Configuration:
2042 other_config : lacp-port-id: optional string, containing an integer, in
2044 range 1 to 65,535
2045 The LACP port ID of this Interface. Port IDs are used in LACP
2046 negotiations to identify individual ports participating in a
2047 bond.
2048 other_config : lacp-port-priority: optional string, containing an inte‐
2050 ger, in range 1 to 65,535
2051 The LACP port priority of this Interface. In LACP negotiations
2052 Interfaces with numerically lower priorities are preferred for
2053 aggregation.
2054 other_config : lacp-aggregation-key: optional string, containing an
2056 integer, in range 1 to 65,535
2057 The LACP aggregation key of this Interface. Interfaces with
2058 different aggregation keys may not be active within a given Port
2059 at the same time.
2060 Virtual Machine Identifiers:
2062 These key-value pairs specifically apply to an interface that repre‐
2063 sents a virtual Ethernet interface connected to a virtual machine.
2064 These key-value pairs should not be present for other types of inter‐
2065 faces. Keys whose names end in -uuid have values that uniquely iden‐
2066 tify the entity in question. For a Citrix XenServer hypervisor, these
2067 values are UUIDs in RFC 4122 format. Other hypervisors may use other
2068 formats.
2069 external_ids : attached-mac: optional string
2071 The MAC address programmed into the ``virtual hardware’’ for
2072 this interface, in the form xx:xx:xx:xx:xx:xx. For Citrix
2073 XenServer, this is the value of the MAC field in the VIF record
2074 for this interface.
2075 external_ids : iface-id: optional string
2077 A system-unique identifier for the interface. On XenServer,
2078 this will commonly be the same as external_ids:xs-vif-uuid.
2079 external_ids : iface-status: optional string, either active or inactive
2081 Hypervisors may sometimes have more than one interface associ‐
2082 ated with a given external_ids:iface-id, only one of which is
2083 actually in use at a given time. For example, in some circum‐
2084 stances XenServer has both a ``tap’’ and a ``vif’’ interface for
2085 a single external_ids:iface-id, but only uses one of them at a
2086 time. A hypervisor that behaves this way must mark the cur‐
2087 rently in use interface active and the others inactive. A
2088 hypervisor that never has more than one interface for a given
2089 external_ids:iface-id may mark that interface active or omit
2090 external_ids:iface-status entirely.
2091 During VM migration, a given external_ids:iface-id might tran‐
2093 siently be marked active on two different hypervisors. That is,
2094 active means that this external_ids:iface-id is the active
2095 instance within a single hypervisor, not in a broader scope.
2096 There is one exception: some hypervisors support ``migration’’
2097 from a given hypervisor to itself (most often for test pur‐
2098 poses). During such a ``migration,’’ two instances of a single
2099 external_ids:iface-id might both be briefly marked active on a
2100 single hypervisor.
2101 external_ids : xs-vif-uuid: optional string
2103 The virtual interface associated with this interface.
2104 external_ids : xs-network-uuid: optional string
2106 The virtual network to which this interface is attached.
2107 external_ids : vm-id: optional string
2109 The VM to which this interface belongs. On XenServer, this will
2110 be the same as external_ids:xs-vm-uuid.
2111 external_ids : xs-vm-uuid: optional string
2113 The VM to which this interface belongs.
2114 VLAN Splinters:
2116 The ``VLAN splinters’’ feature increases Open vSwitch compatibility
2117 with buggy network drivers in old versions of Linux that do not prop‐
2118 erly support VLANs when VLAN devices are not used, at some cost in mem‐
2119 ory and performance.
2120 When VLAN splinters are enabled on a particular interface, Open vSwitch
2122 creates a VLAN device for each in-use VLAN. For sending traffic tagged
2123 with a VLAN on the interface, it substitutes the VLAN device. Traffic
2124 received on the VLAN device is treated as if it had been received on
2125 the interface on the particular VLAN.
2126 VLAN splinters consider a VLAN to be in use if:
2128 · The VLAN is the tag value in any Port record.
2130 · The VLAN is listed within the trunks column of the Port
2132 record of an interface on which VLAN splinters are
2133 enabled. An empty trunks does not influence the in-use
2134 VLANs: creating 4,096 VLAN devices is impractical because
2135 it will exceed the current 1,024 port per datapath limit.
2136 · An OpenFlow flow within any bridge matches the VLAN.
2138 The same set of in-use VLANs applies to every interface on which VLAN
2140 splinters are enabled. That is, the set is not chosen separately for
2141 each interface but selected once as the union of all in-use VLANs based
2142 on the rules above.
2143 It does not make sense to enable VLAN splinters on an interface for an
2145 access port, or on an interface that is not a physical port.
2146 VLAN splinters are deprecated. When broken device drivers are no
2148 longer in widespread use, we will delete this feature.
2149 other_config : enable-vlan-splinters: optional string, either true or
2151 false
2152 Set to true to enable VLAN splinters on this interface.
2153 Defaults to false.
2154 VLAN splinters increase kernel and userspace memory overhead, so
2156 do not use them unless they are needed.
2157 VLAN splinters do not support 802.1p priority tags. Received
2159 priorities will appear to be 0, regardless of their actual val‐
2160 ues, and priorities on transmitted packets will also be cleared
2161 to 0.
2162 Common Columns:
2164 The overall purpose of these columns is described under Common Columns
2165 at the beginning of this document.
2166 other_config: map of string-string pairs
2168 external_ids: map of string-string pairs
2170
2172 Configuration for a particular OpenFlow table.
2173 Summary:
2175 name optional string
2176 flow_limit optional integer, at least 0
2177 overflow_policy optional string, either refuse or evict
2178 groups set of strings
2179 Details:
2181 name: optional string
2182 The table’s name. Set this column to change the name that con‐
2183 trollers will receive when they request table statistics, e.g.
2184 ovs-ofctl dump-tables. The name does not affect switch behav‐
2185 ior.
2186 flow_limit: optional integer, at least 0
2188 If set, limits the number of flows that may be added to the ta‐
2189 ble. Open vSwitch may limit the number of flows in a table for
2190 other reasons, e.g. due to hardware limitations or for resource
2191 availability or performance reasons.
2192 overflow_policy: optional string, either refuse or evict
2194 Controls the switch’s behavior when an OpenFlow flow table modi‐
2195 fication request would add flows in excess of flow_limit. The
2196 supported values are:
2197 refuse Refuse to add the flow or flows. This is also the
2199 default policy when overflow_policy is unset.
2200 evict Delete the flow that will expire soonest. See groups for
2202 details.
2203 groups: set of strings
2205 When overflow_policy is evict, this controls how flows are cho‐
2206 sen for eviction when the flow table would otherwise exceed
2207 flow_limit flows. Its value is a set of NXM fields or sub-
2208 fields, each of which takes one of the forms field[] or
2209 field[start..end], e.g. NXM_OF_IN_PORT[]. Please see
2210 nicira-ext.h for a complete list of NXM field names.
2211 When a flow must be evicted due to overflow, the flow to evict
2213 is chosen through an approximation of the following algorithm:
2214 1.
2216 Divide the flows in the table into groups based on the values
2217 of the specified fields or subfields, so that all of the flows
2218 in a given group have the same values for those fields. If a
2219 flow does not specify a given field, that field’s value is
2220 treated as 0.
2221 2.
2223 Consider the flows in the largest group, that is, the group
2224 that contains the greatest number of flows. If two or more
2225 groups all have the same largest number of flows, consider the
2226 flows in all of those groups.
2227 3.
2229 Among the flows under consideration, choose the flow that
2230 expires soonest for eviction.
2231 The eviction process only considers flows that have an idle
2233 timeout or a hard timeout. That is, eviction never deletes per‐
2234 manent flows. (Permanent flows do count against flow_limit.)
2235 Open vSwitch ignores any invalid or unknown field specifica‐
2237 tions.
2238 When overflow_policy is not evict, this column has no effect.
2240
2242 Quality of Service (QoS) configuration for each Port that references
2243 it.
2244 Summary:
2246 type string
2247 queues map of integer-Queue pairs, key in range
2248 0 to 4,294,967,295
2249 Configuration for linux-htb and linux-hfsc:
2250 other_config : max-rate optional string, containing an integer
2251 Common Columns:
2252 other_config map of string-string pairs
2253 external_ids map of string-string pairs
2254 Details:
2256 type: string
2257 The type of QoS to implement. The currently defined types are
2258 listed below:
2259 linux-htb
2261 Linux ``hierarchy token bucket’’ classifier. See tc-
2262 htb(8) (also at http://linux.die.net/man/8/tc-htb) and
2263 the HTB manual (http://luxik.cdi.cz/~devik/qos/htb/man‐
2264 ual/userg.htm) for information on how this classifier
2265 works and how to configure it.
2266 linux-hfsc
2268 Linux "Hierarchical Fair Service Curve" classifier. See
2269 http://linux-ip.net/articles/hfsc.en/ for information on
2270 how this classifier works.
2271 queues: map of integer-Queue pairs, key in range 0 to 4,294,967,295
2273 A map from queue numbers to Queue records. The supported range
2274 of queue numbers depend on type. The queue numbers are the same
2275 as the queue_id used in OpenFlow in struct ofp_action_enqueue
2276 and other structures.
2277 Queue 0 is the ``default queue.’’ It is used by OpenFlow output
2279 actions when no specific queue has been set. When no configura‐
2280 tion for queue 0 is present, it is automatically configured as
2281 if a Queue record with empty dscp and other_config columns had
2282 been specified. (Before version 1.6, Open vSwitch would leave
2283 queue 0 unconfigured in this case. With some queuing disci‐
2284 plines, this dropped all packets destined for the default
2285 queue.)
2286 Configuration for linux-htb and linux-hfsc:
2288 The linux-htb and linux-hfsc classes support the following key-value
2289 pair:
2290 other_config : max-rate: optional string, containing an integer
2292 Maximum rate shared by all queued traffic, in bit/s. Optional.
2293 If not specified, for physical interfaces, the default is the
2294 link rate. For other interfaces or if the link rate cannot be
2295 determined, the default is currently 100 Mbps.
2296 Common Columns:
2298 The overall purpose of these columns is described under Common Columns
2299 at the beginning of this document.
2300 other_config: map of string-string pairs
2302 external_ids: map of string-string pairs
2304
2306 A configuration for a port output queue, used in configuring Quality of
2307 Service (QoS) features. May be referenced by queues column in QoS ta‐
2308 ble.
2309 Summary:
2311 dscp optional integer, in range 0 to 63
2312 Configuration for linux-htb QoS:
2313 other_config : min-rate optional string, containing an integer,
2314 at least 1
2315 other_config : max-rate optional string, containing an integer,
2316 at least 1
2317 other_config : burst optional string, containing an integer,
2318 at least 1
2319 other_config : priority optional string, containing an integer,
2320 in range 0 to 4,294,967,295
2321 Configuration for linux-hfsc QoS:
2322 other_config : min-rate optional string, containing an integer,
2323 at least 1
2324 other_config : max-rate optional string, containing an integer,
2325 at least 1
2326 Common Columns:
2327 other_config map of string-string pairs
2328 external_ids map of string-string pairs
2329 Details:
2331 dscp: optional integer, in range 0 to 63
2332 If set, Open vSwitch will mark all traffic egressing this Queue
2333 with the given DSCP bits. Traffic egressing the default Queue
2334 is only marked if it was explicitly selected as the Queue at the
2335 time the packet was output. If unset, the DSCP bits of traffic
2336 egressing this Queue will remain unchanged.
2337 Configuration for linux-htb QoS:
2339 QoS type linux-htb may use queue_ids less than 61440. It has the fol‐
2340 lowing key-value pairs defined.
2341 other_config : min-rate: optional string, containing an integer, at
2343 least 1
2344 Minimum guaranteed bandwidth, in bit/s.
2345 other_config : max-rate: optional string, containing an integer, at
2347 least 1
2348 Maximum allowed bandwidth, in bit/s. Optional. If specified,
2349 the queue’s rate will not be allowed to exceed the specified
2350 value, even if excess bandwidth is available. If unspecified,
2351 defaults to no limit.
2352 other_config : burst: optional string, containing an integer, at least
2354 1
2355 Burst size, in bits. This is the maximum amount of ``credits’’
2356 that a queue can accumulate while it is idle. Optional.
2357 Details of the linux-htb implementation require a minimum burst
2358 size, so a too-small burst will be silently ignored.
2359 other_config : priority: optional string, containing an integer, in
2361 range 0 to 4,294,967,295
2362 A queue with a smaller priority will receive all the excess
2363 bandwidth that it can use before a queue with a larger value
2364 receives any. Specific priority values are unimportant; only
2365 relative ordering matters. Defaults to 0 if unspecified.
2366 Configuration for linux-hfsc QoS:
2368 QoS type linux-hfsc may use queue_ids less than 61440. It has the fol‐
2369 lowing key-value pairs defined.
2370 other_config : min-rate: optional string, containing an integer, at
2372 least 1
2373 Minimum guaranteed bandwidth, in bit/s.
2374 other_config : max-rate: optional string, containing an integer, at
2376 least 1
2377 Maximum allowed bandwidth, in bit/s. Optional. If specified,
2378 the queue’s rate will not be allowed to exceed the specified
2379 value, even if excess bandwidth is available. If unspecified,
2380 defaults to no limit.
2381 Common Columns:
2383 The overall purpose of these columns is described under Common Columns
2384 at the beginning of this document.
2385 other_config: map of string-string pairs
2387 external_ids: map of string-string pairs
2389
2391 A port mirror within a Bridge.
2392 A port mirror configures a bridge to send selected frames to special
2394 ``mirrored’’ ports, in addition to their normal destinations. Mirror‐
2395 ing traffic may also be referred to as SPAN or RSPAN, depending on how
2396 the mirrored traffic is sent.
2397 Summary:
2399 name string
2400 Selecting Packets for Mirroring:
2401 select_all boolean
2402 select_dst_port set of weak reference to Ports
2403 select_src_port set of weak reference to Ports
2404 select_vlan set of up to 4,096 integers, in range 0
2405 to 4,095
2406 Mirroring Destination Configuration:
2407 output_port optional weak reference to Port
2408 output_vlan optional integer, in range 1 to 4,095
2409 Statistics: Mirror counters:
2410 statistics : tx_packets optional integer
2411 statistics : tx_bytes optional integer
2412 Common Columns:
2413 external_ids map of string-string pairs
2414 Details:
2416 name: string
2417 Arbitrary identifier for the Mirror.
2418 Selecting Packets for Mirroring:
2420 To be selected for mirroring, a given packet must enter or leave the
2421 bridge through a selected port and it must also be in one of the
2422 selected VLANs.
2423 select_all: boolean
2425 If true, every packet arriving or departing on any port is
2426 selected for mirroring.
2427 select_dst_port: set of weak reference to Ports
2429 Ports on which departing packets are selected for mirroring.
2430 select_src_port: set of weak reference to Ports
2432 Ports on which arriving packets are selected for mirroring.
2433 select_vlan: set of up to 4,096 integers, in range 0 to 4,095
2435 VLANs on which packets are selected for mirroring. An empty set
2436 selects packets on all VLANs.
2437 Mirroring Destination Configuration:
2439 These columns are mutually exclusive. Exactly one of them must be
2440 nonempty.
2441 output_port: optional weak reference to Port
2443 Output port for selected packets, if nonempty.
2444 Specifying a port for mirror output reserves that port exclu‐
2446 sively for mirroring. No frames other than those selected for
2447 mirroring via this column will be forwarded to the port, and any
2448 frames received on the port will be discarded.
2449 The output port may be any kind of port supported by Open
2451 vSwitch. It may be, for example, a physical port (sometimes
2452 called SPAN) or a GRE tunnel.
2453 output_vlan: optional integer, in range 1 to 4,095
2455 Output VLAN for selected packets, if nonempty.
2456 The frames will be sent out all ports that trunk output_vlan, as
2458 well as any ports with implicit VLAN output_vlan. When a mir‐
2459 rored frame is sent out a trunk port, the frame’s VLAN tag will
2460 be set to output_vlan, replacing any existing tag; when it is
2461 sent out an implicit VLAN port, the frame will not be tagged.
2462 This type of mirroring is sometimes called RSPAN.
2463 See the documentation for other_config:forward-bpdu in the
2465 Interface table for a list of destination MAC addresses which
2466 will not be mirrored to a VLAN to avoid confusing switches that
2467 interpret the protocols that they represent.
2468 Please note: Mirroring to a VLAN can disrupt a network that con‐
2470 tains unmanaged switches. Consider an unmanaged physical switch
2471 with two ports: port 1, connected to an end host, and port 2,
2472 connected to an Open vSwitch configured to mirror received pack‐
2473 ets into VLAN 123 on port 2. Suppose that the end host sends a
2474 packet on port 1 that the physical switch forwards to port 2.
2475 The Open vSwitch forwards this packet to its destination and
2476 then reflects it back on port 2 in VLAN 123. This reflected
2477 packet causes the unmanaged physical switch to replace the MAC
2478 learning table entry, which correctly pointed to port 1, with
2479 one that incorrectly points to port 2. Afterward, the physical
2480 switch will direct packets destined for the end host to the Open
2481 vSwitch on port 2, instead of to the end host on port 1, dis‐
2482 rupting connectivity. If mirroring to a VLAN is desired in this
2483 scenario, then the physical switch must be replaced by one that
2484 learns Ethernet addresses on a per-VLAN basis. In addition,
2485 learning should be disabled on the VLAN containing mirrored
2486 traffic. If this is not done then intermediate switches will
2487 learn the MAC address of each end host from the mirrored traf‐
2488 fic. If packets being sent to that end host are also mirrored,
2489 then they will be dropped since the switch will attempt to send
2490 them out the input port. Disabling learning for the VLAN will
2491 cause the switch to correctly send the packet out all ports con‐
2492 figured for that VLAN. If Open vSwitch is being used as an
2493 intermediate switch, learning can be disabled by adding the mir‐
2494 rored VLAN to flood_vlans in the appropriate Bridge table or
2495 tables.
2496 Mirroring to a GRE tunnel has fewer caveats than mirroring to a
2498 VLAN and should generally be preferred.
2499 Statistics: Mirror counters:
2501 Key-value pairs that report mirror statistics.
2502 statistics : tx_packets: optional integer
2504 Number of packets transmitted through this mirror.
2505 statistics : tx_bytes: optional integer
2507 Number of bytes transmitted through this mirror.
2508 Common Columns:
2510 The overall purpose of these columns is described under Common Columns
2511 at the beginning of this document.
2512 external_ids: map of string-string pairs
2514
2516 An OpenFlow controller.
2517 Open vSwitch supports two kinds of OpenFlow controllers:
2519 Primary controllers
2521 This is the kind of controller envisioned by the OpenFlow
2522 1.0 specification. Usually, a primary controller imple‐
2523 ments a network policy by taking charge of the switch’s
2524 flow table.
2525 Open vSwitch initiates and maintains persistent connec‐
2527 tions to primary controllers, retrying the connection
2528 each time it fails or drops. The fail_mode column in the
2529 Bridge table applies to primary controllers.
2530 Open vSwitch permits a bridge to have any number of pri‐
2532 mary controllers. When multiple controllers are config‐
2533 ured, Open vSwitch connects to all of them simultane‐
2534 ously. Because OpenFlow 1.0 does not specify how multi‐
2535 ple controllers coordinate in interacting with a single
2536 switch, more than one primary controller should be speci‐
2537 fied only if the controllers are themselves designed to
2538 coordinate with each other. (The Nicira-defined NXT_ROLE
2539 OpenFlow vendor extension may be useful for this.)
2540 Service controllers
2542 These kinds of OpenFlow controller connections are
2543 intended for occasional support and maintenance use, e.g.
2544 with ovs-ofctl. Usually a service controller connects
2545 only briefly to inspect or modify some of a switch’s
2546 state.
2547 Open vSwitch listens for incoming connections from ser‐
2549 vice controllers. The service controllers initiate and,
2550 if necessary, maintain the connections from their end.
2551 The fail_mode column in the Bridge table does not apply
2552 to service controllers.
2553 Open vSwitch supports configuring any number of service
2555 controllers.
2556 The target determines the type of controller.
2558 Summary:
2560 Core Features:
2561 target string
2562 connection_mode optional string, either in-band or
2563 out-of-band
2564 Controller Failure Detection and Handling:
2565 max_backoff optional integer, at least 1,000
2566 inactivity_probe optional integer
2567 Asynchronous Message Configuration:
2568 enable_async_messages optional boolean
2569 controller_rate_limit optional integer, at least 100
2570 controller_burst_limit optional integer, at least 25
2571 Additional In-Band Configuration:
2572 local_ip optional string
2573 local_netmask optional string
2574 local_gateway optional string
2575 Controller Status:
2576 is_connected boolean
2577 role optional string, one of slave, other, or
2578 master
2579 status : last_error optional string
2580 status : state optional string, one of ACTIVE, VOID,
2581 CONNECTING, IDLE, or BACKOFF
2582 status : sec_since_connect optional string, containing an integer,
2583 at least 0
2584 status : sec_since_disconnect
2585 optional string, containing an integer,
2586 at least 1
2587 Connection Parameters:
2588 other_config : dscp optional string, containing an integer
2589 Common Columns:
2590 external_ids map of string-string pairs
2591 other_config map of string-string pairs
2592 Details:
2594 Core Features:
2595 target: string
2597 Connection method for controller.
2598 The following connection methods are currently supported for
2600 primary controllers:
2601 ssl:ip[:port]
2603 The specified SSL port (default: 6633) on the host at the
2604 given ip, which must be expressed as an IP address (not a
2605 DNS name). The ssl column in the Open_vSwitch table must
2606 point to a valid SSL configuration when this form is
2607 used.
2608 SSL support is an optional feature that is not always
2610 built as part of Open vSwitch.
2611 tcp:ip[:port]
2613 The specified TCP port (default: 6633) on the host at the
2614 given ip, which must be expressed as an IP address (not a
2615 DNS name).
2616 The following connection methods are currently supported for
2618 service controllers:
2619 pssl:[port][:ip]
2621 Listens for SSL connections on the specified TCP port
2622 (default: 6633). If ip, which must be expressed as an IP
2623 address (not a DNS name), is specified, then connections
2624 are restricted to the specified local IP address.
2625 The ssl column in the Open_vSwitch table must point to a
2627 valid SSL configuration when this form is used.
2628 SSL support is an optional feature that is not always
2630 built as part of Open vSwitch.
2631 ptcp:[port][:ip]
2633 Listens for connections on the specified TCP port
2634 (default: 6633). If ip, which must be expressed as an IP
2635 address (not a DNS name), is specified, then connections
2636 are restricted to the specified local IP address.
2637 When multiple controllers are configured for a single bridge,
2639 the target values must be unique. Duplicate target values yield
2640 unspecified results.
2641 connection_mode: optional string, either in-band or out-of-band
2643 If it is specified, this setting must be one of the following
2644 strings that describes how Open vSwitch contacts this OpenFlow
2645 controller over the network:
2646 in-band
2648 In this mode, this controller’s OpenFlow traffic travels
2649 over the bridge associated with the controller. With
2650 this setting, Open vSwitch allows traffic to and from the
2651 controller regardless of the contents of the OpenFlow
2652 flow table. (Otherwise, Open vSwitch would never be able
2653 to connect to the controller, because it did not have a
2654 flow to enable it.) This is the most common connection
2655 mode because it is not necessary to maintain two indepen‐
2656 dent networks.
2657 out-of-band
2659 In this mode, OpenFlow traffic uses a control network
2660 separate from the bridge associated with this controller,
2661 that is, the bridge does not use any of its own network
2662 devices to communicate with the controller. The control
2663 network must be configured separately, before or after
2664 ovs-vswitchd is started.
2665 If not specified, the default is implementation-specific.
2667 Controller Failure Detection and Handling:
2669 max_backoff: optional integer, at least 1,000
2671 Maximum number of milliseconds to wait between connection
2672 attempts. Default is implementation-specific.
2673 inactivity_probe: optional integer
2675 Maximum number of milliseconds of idle time on connection to
2676 controller before sending an inactivity probe message. If Open
2677 vSwitch does not communicate with the controller for the speci‐
2678 fied number of seconds, it will send a probe. If a response is
2679 not received for the same additional amount of time, Open
2680 vSwitch assumes the connection has been broken and attempts to
2681 reconnect. Default is implementation-specific. A value of 0
2682 disables inactivity probes.
2683 Asynchronous Message Configuration:
2685 OpenFlow switches send certain messages to controllers spontanenously,
2686 that is, not in response to any request from the controller. These
2687 messages are called ``asynchronous messages.’’ These columns allow
2688 asynchronous messages to be limited or disabled to ensure the best use
2689 of network resources.
2690 enable_async_messages: optional boolean
2692 The OpenFlow protocol enables asynchronous messages at time of
2693 connection establishment, which means that a controller can
2694 receive asynchronous messages, potentially many of them, even if
2695 it turns them off immediately after connecting. Set this column
2696 to false to change Open vSwitch behavior to disable, by default,
2697 all asynchronous messages. The controller can use the
2698 NXT_SET_ASYNC_CONFIG Nicira extension to OpenFlow to turn on any
2699 messages that it does want to receive, if any.
2700 controller_rate_limit: optional integer, at least 100
2702 The maximum rate at which the switch will forward packets to the
2703 OpenFlow controller, in packets per second. This feature pre‐
2704 vents a single bridge from overwhelming the controller. If not
2705 specified, the default is implementation-specific.
2706 In addition, when a high rate triggers rate-limiting, Open
2708 vSwitch queues controller packets for each port and transmits
2709 them to the controller at the configured rate. The con‐
2710 troller_burst_limit value limits the number of queued packets.
2711 Ports on a bridge share the packet queue fairly.
2712 Open vSwitch maintains two such packet rate-limiters per bridge:
2714 one for packets sent up to the controller because they do not
2715 correspond to any flow, and the other for packets sent up to the
2716 controller by request through flow actions. When both rate-lim‐
2717 iters are filled with packets, the actual rate that packets are
2718 sent to the controller is up to twice the specified rate.
2719 controller_burst_limit: optional integer, at least 25
2721 In conjunction with controller_rate_limit, the maximum number of
2722 unused packet credits that the bridge will allow to accumulate,
2723 in packets. If not specified, the default is implementation-
2724 specific.
2725 Additional In-Band Configuration:
2727 These values are considered only in in-band control mode (see connec‐
2728 tion_mode).
2729 When multiple controllers are configured on a single bridge, there
2731 should be only one set of unique values in these columns. If different
2732 values are set for these columns in different controllers, the effect
2733 is unspecified.
2734 local_ip: optional string
2736 The IP address to configure on the local port, e.g.
2737 192.168.0.123. If this value is unset, then local_netmask and
2738 local_gateway are ignored.
2739 local_netmask: optional string
2741 The IP netmask to configure on the local port, e.g.
2742 255.255.255.0. If local_ip is set but this value is unset, then
2743 the default is chosen based on whether the IP address is class
2744 A, B, or C.
2745 local_gateway: optional string
2747 The IP address of the gateway to configure on the local port, as
2748 a string, e.g. 192.168.0.1. Leave this column unset if this
2749 network has no gateway.
2750 Controller Status:
2752 is_connected: boolean
2754 true if currently connected to this controller, false otherwise.
2755 role: optional string, one of slave, other, or master
2757 The level of authority this controller has on the associated
2758 bridge. Possible values are:
2759 other Allows the controller access to all OpenFlow features.
2761 master Equivalent to other, except that there may be at most one
2763 master controller at a time. When a controller config‐
2764 ures itself as master, any existing master is demoted to
2765 the slaverole.
2766 slave Allows the controller read-only access to OpenFlow fea‐
2768 tures. Attempts to modify the flow table will be
2769 rejected with an error. Slave controllers do not receive
2770 OFPT_PACKET_IN or OFPT_FLOW_REMOVED messages, but they do
2771 receive OFPT_PORT_STATUS messages.
2772 status : last_error: optional string
2774 A human-readable description of the last error on the connection
2775 to the controller; i.e. strerror(errno). This key will exist
2776 only if an error has occurred.
2777 status : state: optional string, one of ACTIVE, VOID, CONNECTING, IDLE,
2779 or BACKOFF
2780 The state of the connection to the controller:
2781 VOID Connection is disabled.
2783 BACKOFF
2785 Attempting to reconnect at an increasing period.
2786 CONNECTING
2788 Attempting to connect.
2789 ACTIVE Connected, remote host responsive.
2791 IDLE Connection is idle. Waiting for response to keep-alive.
2793 These values may change in the future. They are provided only
2795 for human consumption.
2796 status : sec_since_connect: optional string, containing an integer, at
2798 least 0
2799 The amount of time since this controller last successfully con‐
2800 nected to the switch (in seconds). Value is empty if controller
2801 has never successfully connected.
2802 status : sec_since_disconnect: optional string, containing an integer,
2804 at least 1
2805 The amount of time since this controller last disconnected from
2806 the switch (in seconds). Value is empty if controller has never
2807 disconnected.
2808 Connection Parameters:
2810 Additional configuration for a connection between the controller and
2811 the Open vSwitch.
2812 other_config : dscp: optional string, containing an integer
2814 The Differentiated Service Code Point (DSCP) is specified using
2815 6 bits in the Type of Service (TOS) field in the IP header. DSCP
2816 provides a mechanism to classify the network traffic and provide
2817 Quality of Service (QoS) on IP networks. The DSCP value speci‐
2818 fied here is used when establishing the connection between the
2819 controller and the Open vSwitch. If no value is specified, a
2820 default value of 48 is chosen. Valid DSCP values must be in the
2821 range 0 to 63.
2822 Common Columns:
2824 The overall purpose of these columns is described under Common Columns
2825 at the beginning of this document.
2826 external_ids: map of string-string pairs
2828 other_config: map of string-string pairs
2830
2832 Configuration for a database connection to an Open vSwitch database
2833 (OVSDB) client.
2834 This table primarily configures the Open vSwitch database
2836 (ovsdb-server), not the Open vSwitch switch (ovs-vswitchd). The switch
2837 does read the table to determine what connections should be treated as
2838 in-band.
2839 The Open vSwitch database server can initiate and maintain active con‐
2841 nections to remote clients. It can also listen for database connec‐
2842 tions.
2843 Summary:
2845 Core Features:
2846 target string (must be unique within table)
2847 connection_mode optional string, either in-band or
2848 out-of-band
2849 Client Failure Detection and Handling:
2850 max_backoff optional integer, at least 1,000
2851 inactivity_probe optional integer
2852 Status:
2853 is_connected boolean
2854 status : last_error optional string
2855 status : state optional string, one of ACTIVE, VOID,
2856 CONNECTING, IDLE, or BACKOFF
2857 status : sec_since_connect optional string, containing an integer,
2858 at least 0
2859 status : sec_since_disconnect
2860 optional string, containing an integer,
2861 at least 0
2862 status : locks_held optional string
2863 status : locks_waiting optional string
2864 status : locks_lost optional string
2865 status : n_connections optional string, containing an integer,
2866 at least 2
2867 status : bound_port optional string, containing an integer
2868 Connection Parameters:
2869 other_config : dscp optional string, containing an integer
2870 Common Columns:
2871 external_ids map of string-string pairs
2872 other_config map of string-string pairs
2873 Details:
2875 Core Features:
2876 target: string (must be unique within table)
2878 Connection method for managers.
2879 The following connection methods are currently supported:
2881 ssl:ip[:port]
2883 The specified SSL port (default: 6632) on the host at the
2884 given ip, which must be expressed as an IP address (not a
2885 DNS name). The ssl column in the Open_vSwitch table must
2886 point to a valid SSL configuration when this form is
2887 used.
2888 SSL support is an optional feature that is not always
2890 built as part of Open vSwitch.
2891 tcp:ip[:port]
2893 The specified TCP port (default: 6632) on the host at the
2894 given ip, which must be expressed as an IP address (not a
2895 DNS name).
2896 pssl:[port][:ip]
2898 Listens for SSL connections on the specified TCP port
2899 (default: 6632). Specify 0 for port to have the kernel
2900 automatically choose an available port. If ip, which
2901 must be expressed as an IP address (not a DNS name), is
2902 specified, then connections are restricted to the speci‐
2903 fied local IP address.
2904 The ssl column in the Open_vSwitch table must point to a
2906 valid SSL configuration when this form is used.
2907 SSL support is an optional feature that is not always
2909 built as part of Open vSwitch.
2910 ptcp:[port][:ip]
2912 Listens for connections on the specified TCP port
2913 (default: 6632). Specify 0 for port to have the kernel
2914 automatically choose an available port. If ip, which
2915 must be expressed as an IP address (not a DNS name), is
2916 specified, then connections are restricted to the speci‐
2917 fied local IP address.
2918 When multiple managers are configured, the target values must be
2920 unique. Duplicate target values yield unspecified results.
2921 connection_mode: optional string, either in-band or out-of-band
2923 If it is specified, this setting must be one of the following
2924 strings that describes how Open vSwitch contacts this OVSDB
2925 client over the network:
2926 in-band
2928 In this mode, this connection’s traffic travels over a
2929 bridge managed by Open vSwitch. With this setting, Open
2930 vSwitch allows traffic to and from the client regardless
2931 of the contents of the OpenFlow flow table. (Otherwise,
2932 Open vSwitch would never be able to connect to the
2933 client, because it did not have a flow to enable it.)
2934 This is the most common connection mode because it is not
2935 necessary to maintain two independent networks.
2936 out-of-band
2938 In this mode, the client’s traffic uses a control network
2939 separate from that managed by Open vSwitch, that is, Open
2940 vSwitch does not use any of its own network devices to
2941 communicate with the client. The control network must be
2942 configured separately, before or after ovs-vswitchd is
2943 started.
2944 If not specified, the default is implementation-specific.
2946 Client Failure Detection and Handling:
2948 max_backoff: optional integer, at least 1,000
2950 Maximum number of milliseconds to wait between connection
2951 attempts. Default is implementation-specific.
2952 inactivity_probe: optional integer
2954 Maximum number of milliseconds of idle time on connection to the
2955 client before sending an inactivity probe message. If Open
2956 vSwitch does not communicate with the client for the specified
2957 number of seconds, it will send a probe. If a response is not
2958 received for the same additional amount of time, Open vSwitch
2959 assumes the connection has been broken and attempts to recon‐
2960 nect. Default is implementation-specific. A value of 0 dis‐
2961 ables inactivity probes.
2962 Status:
2964 is_connected: boolean
2966 true if currently connected to this manager, false otherwise.
2967 status : last_error: optional string
2969 A human-readable description of the last error on the connection
2970 to the manager; i.e. strerror(errno). This key will exist only
2971 if an error has occurred.
2972 status : state: optional string, one of ACTIVE, VOID, CONNECTING, IDLE,
2974 or BACKOFF
2975 The state of the connection to the manager:
2976 VOID Connection is disabled.
2978 BACKOFF
2980 Attempting to reconnect at an increasing period.
2981 CONNECTING
2983 Attempting to connect.
2984 ACTIVE Connected, remote host responsive.
2986 IDLE Connection is idle. Waiting for response to keep-alive.
2988 These values may change in the future. They are provided only
2990 for human consumption.
2991 status : sec_since_connect: optional string, containing an integer, at
2993 least 0
2994 The amount of time since this manager last successfully con‐
2995 nected to the database (in seconds). Value is empty if manager
2996 has never successfully connected.
2997 status : sec_since_disconnect: optional string, containing an integer,
2999 at least 0
3000 The amount of time since this manager last disconnected from the
3001 database (in seconds). Value is empty if manager has never dis‐
3002 connected.
3003 status : locks_held: optional string
3005 Space-separated list of the names of OVSDB locks that the con‐
3006 nection holds. Omitted if the connection does not hold any
3007 locks.
3008 status : locks_waiting: optional string
3010 Space-separated list of the names of OVSDB locks that the con‐
3011 nection is currently waiting to acquire. Omitted if the connec‐
3012 tion is not waiting for any locks.
3013 status : locks_lost: optional string
3015 Space-separated list of the names of OVSDB locks that the con‐
3016 nection has had stolen by another OVSDB client. Omitted if no
3017 locks have been stolen from this connection.
3018 status : n_connections: optional string, containing an integer, at
3020 least 2
3021 When target specifies a connection method that listens for
3022 inbound connections (e.g. ptcp: or pssl:) and more than one con‐
3023 nection is actually active, the value is the number of active
3024 connections. Otherwise, this key-value pair is omitted.
3025 When multiple connections are active, status columns and key-
3027 value pairs (other than this one) report the status of one arbi‐
3028 trarily chosen connection.
3029 status : bound_port: optional string, containing an integer
3031 When target is ptcp: or pssl:, this is the TCP port on which the
3032 OVSDB server is listening. (This is is particularly useful when
3033 target specifies a port of 0, allowing the kernel to choose any
3034 available port.)
3035 Connection Parameters:
3037 Additional configuration for a connection between the manager and the
3038 Open vSwitch Database.
3039 other_config : dscp: optional string, containing an integer
3041 The Differentiated Service Code Point (DSCP) is specified using
3042 6 bits in the Type of Service (TOS) field in the IP header. DSCP
3043 provides a mechanism to classify the network traffic and provide
3044 Quality of Service (QoS) on IP networks. The DSCP value speci‐
3045 fied here is used when establishing the connection between the
3046 manager and the Open vSwitch. If no value is specified, a
3047 default value of 48 is chosen. Valid DSCP values must be in the
3048 range 0 to 63.
3049 Common Columns:
3051 The overall purpose of these columns is described under Common Columns
3052 at the beginning of this document.
3053 external_ids: map of string-string pairs
3055 other_config: map of string-string pairs
3057
3059 A NetFlow target. NetFlow is a protocol that exports a number of
3060 details about terminating IP flows, such as the principals involved and
3061 duration.
3062 Summary:
3064 targets set of 1 or more strings
3065 engine_id optional integer, in range 0 to 255
3066 engine_type optional integer, in range 0 to 255
3067 active_timeout integer, at least -1
3068 add_id_to_interface boolean
3069 Common Columns:
3070 external_ids map of string-string pairs
3071 Details:
3073 targets: set of 1 or more strings
3074 NetFlow targets in the form ip:port. The ip must be specified
3075 numerically, not as a DNS name.
3076 engine_id: optional integer, in range 0 to 255
3078 Engine ID to use in NetFlow messages. Defaults to datapath
3079 index if not specified.
3080 engine_type: optional integer, in range 0 to 255
3082 Engine type to use in NetFlow messages. Defaults to datapath
3083 index if not specified.
3084 active_timeout: integer, at least -1
3086 The interval at which NetFlow records are sent for flows that
3087 are still active, in seconds. A value of 0 requests the default
3088 timeout (currently 600 seconds); a value of -1 disables active
3089 timeouts.
3090 add_id_to_interface: boolean
3092 If this column’s value is false, the ingress and egress inter‐
3093 face fields of NetFlow flow records are derived from OpenFlow
3094 port numbers. When it is true, the 7 most significant bits of
3095 these fields will be replaced by the least significant 7 bits of
3096 the engine id. This is useful because many NetFlow collectors
3097 do not expect multiple switches to be sending messages from the
3098 same host, so they do not store the engine information which
3099 could be used to disambiguate the traffic.
3100 When this option is enabled, a maximum of 508 ports are sup‐
3102 ported.
3103 Common Columns:
3105 The overall purpose of these columns is described under Common Columns
3106 at the beginning of this document.
3107 external_ids: map of string-string pairs
3109
3111 SSL configuration for an Open_vSwitch.
3112 Summary:
3114 private_key string
3115 certificate string
3116 ca_cert string
3117 bootstrap_ca_cert boolean
3118 Common Columns:
3119 external_ids map of string-string pairs
3120 Details:
3122 private_key: string
3123 Name of a PEM file containing the private key used as the
3124 switch’s identity for SSL connections to the controller.
3125 certificate: string
3127 Name of a PEM file containing a certificate, signed by the cer‐
3128 tificate authority (CA) used by the controller and manager, that
3129 certifies the switch’s private key, identifying a trustworthy
3130 switch.
3131 ca_cert: string
3133 Name of a PEM file containing the CA certificate used to verify
3134 that the switch is connected to a trustworthy controller.
3135 bootstrap_ca_cert: boolean
3137 If set to true, then Open vSwitch will attempt to obtain the CA
3138 certificate from the controller on its first SSL connection and
3139 save it to the named PEM file. If it is successful, it will
3140 immediately drop the connection and reconnect, and from then on
3141 all SSL connections must be authenticated by a certificate
3142 signed by the CA certificate thus obtained. This option exposes
3143 the SSL connection to a man-in-the-middle attack obtaining the
3144 initial CA certificate. It may still be useful for bootstrap‐
3145 ping.
3146 Common Columns:
3148 The overall purpose of these columns is described under Common Columns
3149 at the beginning of this document.
3150 external_ids: map of string-string pairs
3152
3154 A set of sFlow(R) targets. sFlow is a protocol for remote monitoring
3155 of switches.
3156 Summary:
3158 agent optional string
3159 header optional integer
3160 polling optional integer
3161 sampling optional integer
3162 targets set of 1 or more strings
3163 Common Columns:
3164 external_ids map of string-string pairs
3165 Details:
3167 agent: optional string
3168 Name of the network device whose IP address should be reported
3169 as the ``agent address’’ to collectors. If not specified, the
3170 agent device is figured from the first target address and the
3171 routing table. If the routing table does not contain a route to
3172 the target, the IP address defaults to the local_ip in the col‐
3173 lector’s Controller. If an agent IP address cannot be deter‐
3174 mined any of these ways, sFlow is disabled.
3175 header: optional integer
3177 Number of bytes of a sampled packet to send to the collector.
3178 If not specified, the default is 128 bytes.
3179 polling: optional integer
3181 Polling rate in seconds to send port statistics to the collec‐
3182 tor. If not specified, defaults to 30 seconds.
3183 sampling: optional integer
3185 Rate at which packets should be sampled and sent to the collec‐
3186 tor. If not specified, defaults to 400, which means one out of
3187 400 packets, on average, will be sent to the collector.
3188 targets: set of 1 or more strings
3190 sFlow targets in the form ip:port.
3191 Common Columns:
3193 The overall purpose of these columns is described under Common Columns
3194 at the beginning of this document.
3195 external_ids: map of string-string pairs
3197
3199 A set of IPFIX collectors. IPFIX is a protocol that exports a number
3200 of details about flows.
3201 Summary:
3203 targets set of 1 or more strings
3204 sampling optional integer, in range 1 to
3205 4,294,967,295
3206 obs_domain_id optional integer, in range 0 to
3207 4,294,967,295
3208 obs_point_id optional integer, in range 0 to
3209 4,294,967,295
3210 cache_active_timeout optional integer, in range 0 to 4,200
3211 cache_max_flows optional integer, in range 0 to
3212 4,294,967,295
3213 Common Columns:
3214 external_ids map of string-string pairs
3215 Details:
3217 targets: set of 1 or more strings
3218 IPFIX target collectors in the form ip:port.
3219 sampling: optional integer, in range 1 to 4,294,967,295
3221 For per-bridge packet sampling, i.e. when this row is referenced
3222 from a Bridge, the rate at which packets should be sampled and
3223 sent to each target collector. If not specified, defaults to
3224 400, which means one out of 400 packets, on average, will be
3225 sent to each target collector. Ignored for per-flow sampling,
3226 i.e. when this row is referenced from a Flow_Sample_Collec‐
3227 tor_Set.
3228 obs_domain_id: optional integer, in range 0 to 4,294,967,295
3230 For per-bridge packet sampling, i.e. when this row is referenced
3231 from a Bridge, the IPFIX Observation Domain ID sent in each
3232 IPFIX packet. If not specified, defaults to 0. Ignored for
3233 per-flow sampling, i.e. when this row is referenced from a
3234 Flow_Sample_Collector_Set.
3235 obs_point_id: optional integer, in range 0 to 4,294,967,295
3237 For per-bridge packet sampling, i.e. when this row is referenced
3238 from a Bridge, the IPFIX Observation Point ID sent in each IPFIX
3239 flow record. If not specified, defaults to 0. Ignored for per-
3240 flow sampling, i.e. when this row is referenced from a Flow_Sam‐
3241 ple_Collector_Set.
3242 cache_active_timeout: optional integer, in range 0 to 4,200
3244 The maximum period in seconds for which an IPFIX flow record is
3245 cached and aggregated before being sent. If not specified,
3246 defaults to 0. If 0, caching is disabled.
3247 cache_max_flows: optional integer, in range 0 to 4,294,967,295
3249 The maximum number of IPFIX flow records that can be cached at a
3250 time. If not specified, defaults to 0. If 0, caching is dis‐
3251 abled.
3252 Common Columns:
3254 The overall purpose of these columns is described under Common Columns
3255 at the beginning of this document.
3256 external_ids: map of string-string pairs
3258
3260 A set of IPFIX collectors of packet samples generated by OpenFlow sam‐
3261 ple actions.
3262 Summary:
3264 id integer, in range 0 to 4,294,967,295
3265 bridge Bridge
3266 ipfix optional IPFIX
3267 Common Columns:
3268 external_ids map of string-string pairs
3269 Details:
3271 id: integer, in range 0 to 4,294,967,295
3272 The ID of this collector set, unique among the bridge’s collec‐
3273 tor sets, to be used as the collector_set_id in OpenFlow sample
3274 actions.
3275 bridge: Bridge
3277 The bridge into which OpenFlow sample actions can be added to
3278 send packet samples to this set of IPFIX collectors.
3279 ipfix: optional IPFIX
3281 Configuration of the set of IPFIX collectors to send one flow
3282 record per sampled packet to.
3283 Common Columns:
3285 The overall purpose of these columns is described under Common Columns
3286 at the beginning of this document.
3287 external_ids: map of string-string pairs
3289Open vSwitch 2.0.0 ovs-vswitchd.conf.db(5)