1 <?xml version="1.0" encoding="utf-8"?>
2 <database name="ovn-nb" title="OVN Northbound Database">
4 This database is the interface between OVN and the cloud management system
5 (CMS), such as OpenStack, running above it. The CMS produces almost all of
6 the contents of the database. The <code>ovn-northd</code> program
7 monitors the database contents, transforms it, and stores it into the <ref
8 db="OVN_Southbound"/> database.
12 We generally speak of ``the'' CMS, but one can imagine scenarios in
13 which multiple CMSes manage different parts of an OVN deployment.
19 Each of the tables in this database contains a special column, named
20 <code>external_ids</code>. This column has the same form and purpose each
25 <dt><code>external_ids</code>: map of string-string pairs</dt>
27 Key-value pairs for use by the CMS. The CMS might use certain pairs, for
28 example, to identify entities in its own configuration that correspond to
29 those in this database.
33 <table name="Logical_Switch" title="L2 logical switch">
35 Each row represents one L2 logical switch.
39 There are two kinds of logical switches, that is, ones that fully
40 virtualize the network (overlay logical switches) and ones that provide
41 simple connectivity to a physical network (bridged logical switches).
42 They work in the same way when providing connectivity between logical
43 ports on same chasis, but differently when connecting remote logical
44 ports. Overlay logical switches connect remote logical ports by tunnels,
45 while bridged logical switches provide connectivity to remote ports by
46 bridging the packets to directly connected physical L2 segment with the
47 help of <code>localnet</code> ports. Each bridged logical switch has
48 one and only one <code>localnet</code> port, which has only one special
49 address <code>unknown</code>.
54 A name for the logical switch. This name has no special meaning or purpose
55 other than to provide convenience for human interaction with the ovn-nb
56 database. There is no requirement for the name to be unique. The
57 logical switch's UUID should be used as the unique identifier.
63 The logical ports connected to the logical switch.
67 It is an error for multiple logical switches to include the same
73 Access control rules that apply to packets within the logical switch.
76 <group title="Common Columns">
77 <column name="external_ids">
78 See <em>External IDs</em> at the beginning of this document.
83 <table name="Logical_Switch_Port" title="L2 logical switch port">
85 A port within an L2 logical switch.
88 <group title="Core Features">
91 The logical port name.
95 For entities (VMs or containers) that are spawned in the hypervisor,
96 the name used here must match those used in the <ref key="iface-id"
97 table="Interface" column="external_ids" db="Open_vSwitch"/> in the
98 <ref db="Open_vSwitch"/> database's <ref table="Interface"
99 db="Open_vSwitch"/> table, because hypervisors use <ref key="iface-id"
100 table="Interface" column="external_ids" db="Open_vSwitch"/> as a lookup
101 key to identify the network interface of that entity.
105 For containers that share a VIF within a VM, the name can be any
106 unique identifier. See <code>Containers</code>, below, for more
113 Specify a type for this logical port. Logical ports can be used to
114 model other types of connectivity into an OVN logical switch. The
115 following types are defined:
119 <dt>(empty string)</dt>
121 A VM (or VIF) interface.
124 <dt><code>router</code></dt>
126 A connection to a logical router.
129 <dt><code>localnet</code></dt>
131 A connection to a locally accessible network from each
132 <code>ovn-controller</code> instance. A logical switch can only
133 have a single <code>localnet</code> port attached. This is used
134 to model direct connectivity to an existing network.
137 <dt><code>vtep</code></dt>
139 A port to a logical switch on a VTEP gateway.
145 <group title="Options">
146 <column name="options">
147 This column provides key/value settings specific to the logical port
148 <ref column="type"/>. The type-specific options are described
152 <group title="Options for router ports">
154 These options apply when <ref column="type"/> is <code>router</code>.
157 <column name="options" key="router-port">
158 Required. The <ref column="name"/> of the <ref
159 table="Logical_Router_Port"/> to which this logical switch port is
164 <group title="Options for localnet ports">
166 These options apply when <ref column="type"/> is
167 <code>localnet</code>.
170 <column name="options" key="network_name">
171 Required. The name of the network to which the <code>localnet</code>
172 port is connected. Each hypervisor, via <code>ovn-controller</code>,
173 uses its local configuration to determine exactly how to connect to
174 this locally accessible network.
178 <group title="Options for vtep ports">
180 These options apply when <ref column="type"/> is <code>vtep</code>.
183 <column name="options" key="vtep-physical-switch">
184 Required. The name of the VTEP gateway.
187 <column name="options" key="vtep-logical-switch">
188 Required. A logical switch name connected by the VTEP gateway.
192 <group title="VMI (or VIF) Options">
194 These options apply to logical ports with <ref column="type"/> having
198 <column name="options" key="policing_rate">
199 If set, indicates the maximum rate for data sent from this interface,
200 in kbps. Data exceeding this rate is dropped.
203 <column name="options" key="policing_burst">
204 If set, indicates the maximum burst size for data sent from this
210 <group title="Containers">
212 When a large number of containers are nested within a VM, it may be too
213 expensive to dedicate a VIF to each container. OVN can use VLAN tags
214 to support such cases. Each container is assigned a VLAN ID and each
215 packet that passes between the hypervisor and the VM is tagged with the
216 appropriate ID for the container. Such VLAN IDs never appear on a
217 physical wire, even inside a tunnel, so they need not be unique except
218 relative to a single VM on a hypervisor.
222 These columns are used for VIFs that represent nested containers using
223 shared VIFs. For VMs and for containers that have dedicated VIFs, they
227 <column name="parent_name">
228 The VM interface through which the nested container sends its network
229 traffic. This must match the <ref column="name"/> column for some
230 other <ref table="Logical_Switch_Port"/>.
235 The VLAN tag in the network traffic associated with a container's
240 When <ref column="type"/> is set to <code>localnet</code>, this can
241 be set to indicate that the port represents a connection to a
242 specific VLAN on a locally accessible network. The VLAN ID is used to
243 match incoming traffic and is also added to outgoing traffic.
248 <group title="Port State">
250 This column is populated by <code>ovn-northd</code>, rather than by the
251 CMS plugin as is most of this database. When a logical port is bound
252 to a physical location in the OVN Southbound database <ref
253 db="OVN_Southbound" table="Binding"/> table, <code>ovn-northd</code>
254 sets this column to <code>true</code>; otherwise, or if the port
255 becomes unbound later, it sets it to <code>false</code>. This allows
256 the CMS to wait for a VM's (or container's) networking to become active
257 before it allows the VM (or container) to start.
260 <column name="enabled">
261 This column is used to administratively set port state. If this column
262 is empty or is set to <code>true</code>, the port is enabled. If this
263 column is set to <code>false</code>, the port is disabled. A disabled
264 port has all ingress and egress traffic dropped.
269 <group title="Addressing">
270 <column name="addresses">
272 Addresses owned by the logical port.
276 Each element in the set must take one of the following forms:
280 <dt><code>Ethernet address followed by zero or more IPv4 or IPv6 addresses (or both)</code></dt>
283 An Ethernet address defined is owned by the logical port.
284 Like a physical Ethernet NIC, a logical port ordinarily has
285 a single fixed Ethernet address.
289 When a OVN logical switch processes a unicast Ethernet frame
290 whose destination MAC address is in a logical port's <ref
291 column="addresses"/> column, it delivers it only to that port, as
292 if a MAC learning process had learned that MAC address on the
297 If IPv4 or IPv6 address(es) (or both) are defined, it indicates
298 that the logical port owns the given IP addresses.
302 If IPv4 address(es) are defined, the OVN logical switch uses this
303 information to synthesize responses to ARP requests without
304 traversing the physical network. The OVN logical router connected
305 to the logical switch, if any, uses this information to avoid
306 issuing ARP requests for logical switch ports.
310 Note that the order here is important. The Ethernet address must
311 be listed before the IP address(es) if defined.
319 <dt><code>80:fa:5b:06:72:b7</code></dt>
321 This indicates that the logical port owns the above mac address.
324 <dt><code>80:fa:5b:06:72:b7 10.0.0.4 20.0.0.4</code></dt>
326 This indicates that the logical port owns the mac address and two
330 <dt><code>80:fa:5b:06:72:b7 fdaa:15f2:72cf:0:f816:3eff:fe20:3f41</code></dt>
332 This indicates that the logical port owns the mac address and
336 <dt><code>80:fa:5b:06:72:b7 10.0.0.4 fdaa:15f2:72cf:0:f816:3eff:fe20:3f41</code></dt>
338 This indicates that the logical port owns the mac address and
339 1 IPv4 address and 1 IPv6 address.
344 <dt><code>unknown</code></dt>
346 This indicates that the logical port has an unknown set of Ethernet
347 addresses. When an OVN logical switch processes a unicast Ethernet
348 frame whose destination MAC address is not in any logical port's
349 <ref column="addresses"/> column, it delivers it to the port (or
350 ports) whose <ref column="addresses"/> columns include
351 <code>unknown</code>.
356 <column name="port_security">
358 This column controls the addresses from which the host attached to the
359 logical port (``the host'') is allowed to send packets and to which it
360 is allowed to receive packets. If this column is empty, all addresses
365 Each element in the set must begin with one Ethernet address.
366 This would restrict the host to sending packets from and receiving
367 packets to the ethernet addresses defined in the logical port's
368 <ref column="port_security"/> column. It also restricts the inner
369 source MAC addresses that the host may send in ARP and IPv6
370 Neighbor Discovery packets. The host is always allowed to receive packets
371 to multicast and broadcast Ethernet addresses.
375 Each element in the set may additionally contain one or more IPv4 or
376 IPv6 addresses (or both), with optional masks. If a mask is given, it
377 must be a CIDR mask. In addition to the restrictions described for
378 Ethernet addresses above, such an element restricts the IPv4 or IPv6
379 addresses from which the host may send and to which it may receive
380 packets to the specified addresses. A masked address, if the host part
381 is zero, indicates that the host is allowed to use any address in the
382 subnet; if the host part is nonzero, the mask simply indicates the size
383 of the subnet. In addition:
389 If any IPv4 address is given, the host is also allowed to receive
390 packets to the IPv4 local broadcast address 255.255.255.255 and to
391 IPv4 multicast addresses (224.0.0.0/4). If an IPv4 address with a
392 mask is given, the host is also allowed to receive packets to the
393 broadcast address in that specified subnet.
397 If any IPv4 address is given, the host is additionally restricted
398 to sending ARP packets with the specified source IPv4 address.
399 (RARP is not restricted.)
405 If any IPv6 address is given, the host is also allowed to receive
406 packets to IPv6 multicast addresses (ff00::/8).
410 If any IPv6 address is given, the host is additionally restricted
411 to sending IPv6 Neighbor Discovery Solicitation or Advertisement
412 packets with the specified source address or, for solicitations,
413 the unspecified address.
419 If an element includes an IPv4 address, but no IPv6 addresses, then
420 IPv6 traffic is not allowed. If an element includes an IPv6 address,
421 but no IPv4 address, then IPv4 and ARP traffic is not allowed.
425 This column uses the same lexical syntax as the <ref column="match"
426 table="Pipeline" db="OVN_Southbound"/> column in the OVN Southbound
427 database's <ref table="Pipeline" db="OVN_Southbound"/> table. Multiple
428 addresses within an element may be space or comma separated.
432 This column is provided as a convenience to cloud management systems,
433 but all of the features that it implements can be implemented as ACLs
434 using the <ref table="ACL"/> table.
442 <dt><code>80:fa:5b:06:72:b7</code></dt>
444 The host may send traffic from and receive traffic to the specified
445 MAC address, and to receive traffic to Ethernet multicast and
446 broadcast addresses, but not otherwise. The host may not send ARP or
447 IPv6 Neighbor Discovery packets with inner source Ethernet addresses
448 other than the one specified.
451 <dt><code>80:fa:5b:06:72:b7 192.168.1.10/24</code></dt>
453 This adds further restrictions to the first example. The host may
454 send IPv4 packets from or receive IPv4 packets to only 192.168.1.10,
455 except that it may also receive IPv4 packets to 192.168.1.255 (based
456 on the subnet mask), 255.255.255.255, and any address in 224.0.0.0/4.
457 The host may not send ARPs with a source Ethernet address other than
458 80:fa:5b:06:72:b7 or source IPv4 address other than 192.168.1.10.
459 The host may not send or receive any IPv6 (including IPv6 Neighbor
463 <dt><code>"80:fa:5b:12:42:ba", "80:fa:5b:06:72:b7 192.168.1.10/24"</code></dt>
465 The host may send traffic from and receive traffic to the
466 specified MAC addresses, and
467 to receive traffic to Ethernet multicast and broadcast addresses,
468 but not otherwise. With MAC 80:fa:5b:12:42:ba, the host may
469 send traffic from and receive traffic to any L3 address.
470 With MAC 80:fa:5b:06:72:b7, the host may send IPv4 packets from or
471 receive IPv4 packets to only 192.168.1.10, except that it may also
472 receive IPv4 packets to 192.168.1.255 (based on the subnet mask),
473 255.255.255.255, and any address in 224.0.0.0/4. The host may not
474 send or receive any IPv6 (including IPv6 Neighbor Discovery) traffic.
480 <group title="Common Columns">
481 <column name="external_ids">
482 See <em>External IDs</em> at the beginning of this document.
487 <table name="ACL" title="Access Control List (ACL) rule">
489 Each row in this table represents one ACL rule for a logical switch
490 that points to it through its <ref column="acls"/> column. The <ref
491 column="action"/> column for the highest-<ref column="priority"/>
492 matching row in this table determines a packet's treatment. If no row
493 matches, packets are allowed by default. (Default-deny treatment is
494 possible: add a rule with <ref column="priority"/> 0, <code>0</code> as
495 <ref column="match"/>, and <code>deny</code> as <ref column="action"/>.)
498 <column name="priority">
500 The ACL rule's priority. Rules with numerically higher priority
501 take precedence over those with lower. If two ACL rules with
502 the same priority both match, then the one actually applied to a
507 Return traffic from an <code>allow-related</code> flow is always
508 allowed and cannot be changed through an ACL.
512 <column name="direction">
513 <p>Direction of the traffic to which this rule should apply:</p>
516 <code>from-lport</code>: Used to implement filters on traffic
517 arriving from a logical port. These rules are applied to the
518 logical switch's ingress pipeline.
521 <code>to-lport</code>: Used to implement filters on traffic
522 forwarded to a logical port. These rules are applied to the
523 logical switch's egress pipeline.
528 <column name="match">
530 The packets that the ACL should match, in the same expression
531 language used for the <ref column="match" table="Logical_Flow"
532 db="OVN_Southbound"/> column in the OVN Southbound database's
533 <ref table="Logical_Flow" db="OVN_Southbound"/> table. The
534 <code>outport</code> logical port is only available in the
535 <code>to-lport</code> direction (the <code>inport</code> is
536 available in both directions).
540 By default all traffic is allowed. When writing a more
541 restrictive policy, it is important to remember to allow flows
542 such as ARP and IPv6 neighbor discovery packets.
546 Note that you can not create an ACL matching on a port with
551 Note that when <code>localnet</code> port exists in a lswitch, for
552 <code>to-lport</code> direction, the <code>inport</code> works only if
553 the <code>to-lport</code> is located on the same chassis as the
558 <column name="action">
559 <p>The action to take when the ACL rule matches:</p>
562 <code>allow</code>: Forward the packet.
566 <code>allow-related</code>: Forward the packet and related traffic
567 (e.g. inbound replies to an outbound connection).
571 <code>drop</code>: Silently drop the packet.
575 <code>reject</code>: Drop the packet, replying with a RST for TCP or
576 ICMP unreachable message for other IP-based protocols.
577 <code>Not implemented--currently treated as drop</code>
584 If set to <code>true</code>, packets that match the ACL will trigger a
585 log message on the transport node or nodes that perform ACL processing.
586 Logging may be combined with any <ref column="action"/>.
590 Logging is not yet implemented.
594 <group title="Common Columns">
595 <column name="external_ids">
596 See <em>External IDs</em> at the beginning of this document.
601 <table name="Logical_Router" title="L3 logical router">
603 Each row represents one L3 logical router.
608 A name for the logical router. This name has no special meaning or purpose
609 other than to provide convenience for human interaction with the ovn-nb
610 database. There is no requirement for the name to be unique. The
611 logical router's UUID should be used as the unique identifier.
615 <column name="ports">
619 <column name="static_routes">
620 One or more static routes for the router.
623 <column name="default_gw">
624 IP address to use as default gateway, if any.
627 <column name="enabled">
628 This column is used to administratively set router state. If this column
629 is empty or is set to <code>true</code>, the router is enabled. If this
630 column is set to <code>false</code>, the router is disabled. A disabled
631 router has all ingress and egress traffic dropped.
635 One or more NAT rules for the router. NAT rules only work on the
639 <group title="Options">
641 Additional options for the logical router.
644 <column name="options" key="chassis">
646 If set, indicates that the logical router in question is a Gateway
647 router (which is centralized) and resides in the set chassis. The
648 same value is also used by <code>ovn-controller</code> to
649 uniquely identify the chassis in the OVN deployment and
650 comes from <code>external_ids:system-id</code> in the
651 <code>Open_vSwitch</code> table of Open_vSwitch database.
655 The Gateway router can only be connected to a distributed router
656 via a switch if SNAT and DNAT are to be configured in the Gateway
662 <group title="Common Columns">
663 <column name="external_ids">
664 See <em>External IDs</em> at the beginning of this document.
669 <table name="Logical_Router_Port" title="L3 logical router port">
671 A port within an L3 logical router.
675 Exactly one <ref table="Logical_Router"/> row must reference a given
681 A name for the logical router port.
685 In addition to provide convenience for human interaction with the
686 ovn-nb database, this column is used as reference by its patch port in
687 <ref table="Logical_Switch_Port"/> or another logical router port in
688 <ref table="Logical_Router_Port"/>.
692 <column name="network">
693 The IP address of the router and the netmask. For example,
694 <code>192.168.0.1/24</code> indicates that the router's IP address is
695 192.168.0.1 and that packets destined to 192.168.0.<var>x</var> should be
700 The Ethernet address that belongs to this router port.
703 <column name="enabled">
704 This column is used to administratively set port state. If this column
705 is empty or is set to <code>true</code>, the port is enabled. If this
706 column is set to <code>false</code>, the port is disabled. A disabled
707 port has all ingress and egress traffic dropped.
710 <group title="Attachment">
712 A given router port serves one of two purposes:
717 To attach a logical switch to a logical router. A logical router
718 port of this type is referenced by exactly one <ref
719 table="Logical_Switch_Port"/> of type <code>router</code>.
720 The value of <ref column="name"/> is set as
721 <code>router-port</code> in column <ref column="options"/> of
722 <ref table="Logical_Switch_Port"/>. In this case <ref
723 column="peer"/> column is empty.
727 To connect one logical router to another. This requires a pair of
728 logical router ports, each connected to a different router. Each
729 router port in the pair specifies the other in its <ref
730 column="peer"/> column. No <ref table="Logical_Switch"/> refers to
737 For a router port used to connect two logical routers, this
738 identifies the other router port in the pair by <ref column="name"/>.
742 For a router port attached to a logical switch, this column is empty.
747 <group title="Common Columns">
748 <column name="external_ids">
749 See <em>External IDs</em> at the beginning of this document.
754 <table name="Logical_Router_Static_Route" title="Logical router static routes">
756 Each record represents a static route.
759 <column name="ip_prefix">
761 IP prefix of this route (e.g. 192.168.100.0/24).
765 <column name="nexthop">
767 Nexthop IP address for this route. Nexthop IP address should be the IP
768 address of a connected router port or the IP address of a logical port.
772 <column name="output_port">
774 The name of the <ref table="Logical_Router_Port"/> via which the packet
775 needs to be sent out. This is optional and when not specified,
776 OVN will automatically figure this out based on the
777 <ref column="nexthop"/>.
782 <table name="NAT" title="NAT rules for a Gateway router.">
784 Each record represents a NAT rule in a Gateway router.
788 <p>Type of the NAT rule.</p>
791 When <ref column="type"/> is <code>dnat</code>, the externally
792 visible IP address <ref column="external_ip"/> is DNATted to the IP
793 address <ref column="logical_ip"/> in the logical space.
796 When <ref column="type"/> is <code>snat</code>, IP packets
797 with their source IP address that either matches the IP address
798 in <ref column="logical_ip"/> or is in the network provided by
799 <ref column="logical_ip"/> is SNATed into the IP address in
800 <ref column="external_ip"/>.
803 When <ref column="type"/> is <code>dnat_and_snat</code>, the
804 externally visible IP address <ref column="external_ip"/> is
805 DNATted to the IP address <ref column="logical_ip"/> in the
806 logical space. In addition, IP packets with the source IP
807 address that matches <ref column="logical_ip"/> is SNATed into
808 the IP address in <ref column="external_ip"/>.
813 <column name="external_ip">
817 <column name="logical_ip">
818 An IPv4 network (e.g 192.168.1.0/24) or an IPv4 address.