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
72 <column name="load_balancer">
73 Load balance a virtual ipv4 address to a set of logical port endpoint
78 Access control rules that apply to packets within the logical switch.
81 <group title="Common Columns">
82 <column name="external_ids">
83 See <em>External IDs</em> at the beginning of this document.
88 <table name="Logical_Switch_Port" title="L2 logical switch port">
90 A port within an L2 logical switch.
93 <group title="Core Features">
96 The logical port name.
100 For entities (VMs or containers) that are spawned in the hypervisor,
101 the name used here must match those used in the <ref key="iface-id"
102 table="Interface" column="external_ids" db="Open_vSwitch"/> in the
103 <ref db="Open_vSwitch"/> database's <ref table="Interface"
104 db="Open_vSwitch"/> table, because hypervisors use <ref key="iface-id"
105 table="Interface" column="external_ids" db="Open_vSwitch"/> as a lookup
106 key to identify the network interface of that entity.
110 For containers that share a VIF within a VM, the name can be any
111 unique identifier. See <code>Containers</code>, below, for more
118 Specify a type for this logical port. Logical ports can be used to
119 model other types of connectivity into an OVN logical switch. The
120 following types are defined:
124 <dt>(empty string)</dt>
126 A VM (or VIF) interface.
129 <dt><code>router</code></dt>
131 A connection to a logical router.
134 <dt><code>localnet</code></dt>
136 A connection to a locally accessible network from each
137 <code>ovn-controller</code> instance. A logical switch can only
138 have a single <code>localnet</code> port attached. This is used
139 to model direct connectivity to an existing network.
142 <dt><code>l2gateway</code></dt>
144 A connection to a physical network.
147 <dt><code>vtep</code></dt>
149 A port to a logical switch on a VTEP gateway.
155 <group title="Options">
156 <column name="options">
157 This column provides key/value settings specific to the logical port
158 <ref column="type"/>. The type-specific options are described
162 <group title="Options for router ports">
164 These options apply when <ref column="type"/> is <code>router</code>.
167 <column name="options" key="router-port">
168 Required. The <ref column="name"/> of the <ref
169 table="Logical_Router_Port"/> to which this logical switch port is
174 <group title="Options for localnet ports">
176 These options apply when <ref column="type"/> is
177 <code>localnet</code>.
180 <column name="options" key="network_name">
181 Required. The name of the network to which the <code>localnet</code>
182 port is connected. Each hypervisor, via <code>ovn-controller</code>,
183 uses its local configuration to determine exactly how to connect to
184 this locally accessible network.
188 <group title="Options for l2gateway ports">
190 These options apply when <ref column="type"/> is
191 <code>l2gateway</code>.
194 <column name="options" key="network_name">
195 Required. The name of the network to which the <code>l2gateway</code>
196 port is connected. The L2 gateway, via <code>ovn-controller</code>,
197 uses its local configuration to determine exactly how to connect to
201 <column name="options" key="l2gateway-chassis">
202 Required. The chassis on which the <code>l2gateway</code> logical
203 port should be bound to. <code>ovn-controller</code> running on the
204 defined chassis will connect this logical port to the physical network.
209 <group title="Options for vtep ports">
211 These options apply when <ref column="type"/> is <code>vtep</code>.
214 <column name="options" key="vtep-physical-switch">
215 Required. The name of the VTEP gateway.
218 <column name="options" key="vtep-logical-switch">
219 Required. A logical switch name connected by the VTEP gateway.
223 <group title="VMI (or VIF) Options">
225 These options apply to logical ports with <ref column="type"/> having
229 <column name="options" key="policing_rate">
230 If set, indicates the maximum rate for data sent from this interface,
231 in kbps. Data exceeding this rate is dropped.
234 <column name="options" key="policing_burst">
235 If set, indicates the maximum burst size for data sent from this
241 <group title="Containers">
243 When a large number of containers are nested within a VM, it may be too
244 expensive to dedicate a VIF to each container. OVN can use VLAN tags
245 to support such cases. Each container is assigned a VLAN ID and each
246 packet that passes between the hypervisor and the VM is tagged with the
247 appropriate ID for the container. Such VLAN IDs never appear on a
248 physical wire, even inside a tunnel, so they need not be unique except
249 relative to a single VM on a hypervisor.
253 These columns are used for VIFs that represent nested containers using
254 shared VIFs. For VMs and for containers that have dedicated VIFs, they
258 <column name="parent_name">
259 The VM interface through which the nested container sends its network
260 traffic. This must match the <ref column="name"/> column for some
261 other <ref table="Logical_Switch_Port"/>.
266 The VLAN tag in the network traffic associated with a container's
271 When <ref column="type"/> is set to <code>localnet</code>, this can
272 be set to indicate that the port represents a connection to a
273 specific VLAN on a locally accessible network. The VLAN ID is used to
274 match incoming traffic and is also added to outgoing traffic.
279 <group title="Port State">
281 This column is populated by <code>ovn-northd</code>, rather than by the
282 CMS plugin as is most of this database. When a logical port is bound
283 to a physical location in the OVN Southbound database <ref
284 db="OVN_Southbound" table="Binding"/> table, <code>ovn-northd</code>
285 sets this column to <code>true</code>; otherwise, or if the port
286 becomes unbound later, it sets it to <code>false</code>. This allows
287 the CMS to wait for a VM's (or container's) networking to become active
288 before it allows the VM (or container) to start.
291 <column name="enabled">
292 This column is used to administratively set port state. If this column
293 is empty or is set to <code>true</code>, the port is enabled. If this
294 column is set to <code>false</code>, the port is disabled. A disabled
295 port has all ingress and egress traffic dropped.
300 <group title="Addressing">
301 <column name="addresses">
303 Addresses owned by the logical port.
307 Each element in the set must take one of the following forms:
311 <dt><code>Ethernet address followed by zero or more IPv4 or IPv6 addresses (or both)</code></dt>
314 An Ethernet address defined is owned by the logical port.
315 Like a physical Ethernet NIC, a logical port ordinarily has
316 a single fixed Ethernet address.
320 When a OVN logical switch processes a unicast Ethernet frame
321 whose destination MAC address is in a logical port's <ref
322 column="addresses"/> column, it delivers it only to that port, as
323 if a MAC learning process had learned that MAC address on the
328 If IPv4 or IPv6 address(es) (or both) are defined, it indicates
329 that the logical port owns the given IP addresses.
333 If IPv4 address(es) are defined, the OVN logical switch uses this
334 information to synthesize responses to ARP requests without
335 traversing the physical network. The OVN logical router connected
336 to the logical switch, if any, uses this information to avoid
337 issuing ARP requests for logical switch ports.
341 Note that the order here is important. The Ethernet address must
342 be listed before the IP address(es) if defined.
350 <dt><code>80:fa:5b:06:72:b7</code></dt>
352 This indicates that the logical port owns the above mac address.
355 <dt><code>80:fa:5b:06:72:b7 10.0.0.4 20.0.0.4</code></dt>
357 This indicates that the logical port owns the mac address and two
361 <dt><code>80:fa:5b:06:72:b7 fdaa:15f2:72cf:0:f816:3eff:fe20:3f41</code></dt>
363 This indicates that the logical port owns the mac address and
367 <dt><code>80:fa:5b:06:72:b7 10.0.0.4 fdaa:15f2:72cf:0:f816:3eff:fe20:3f41</code></dt>
369 This indicates that the logical port owns the mac address and
370 1 IPv4 address and 1 IPv6 address.
375 <dt><code>unknown</code></dt>
377 This indicates that the logical port has an unknown set of Ethernet
378 addresses. When an OVN logical switch processes a unicast Ethernet
379 frame whose destination MAC address is not in any logical port's
380 <ref column="addresses"/> column, it delivers it to the port (or
381 ports) whose <ref column="addresses"/> columns include
382 <code>unknown</code>.
387 <column name="port_security">
389 This column controls the addresses from which the host attached to the
390 logical port (``the host'') is allowed to send packets and to which it
391 is allowed to receive packets. If this column is empty, all addresses
396 Each element in the set must begin with one Ethernet address.
397 This would restrict the host to sending packets from and receiving
398 packets to the ethernet addresses defined in the logical port's
399 <ref column="port_security"/> column. It also restricts the inner
400 source MAC addresses that the host may send in ARP and IPv6
401 Neighbor Discovery packets. The host is always allowed to receive packets
402 to multicast and broadcast Ethernet addresses.
406 Each element in the set may additionally contain one or more IPv4 or
407 IPv6 addresses (or both), with optional masks. If a mask is given, it
408 must be a CIDR mask. In addition to the restrictions described for
409 Ethernet addresses above, such an element restricts the IPv4 or IPv6
410 addresses from which the host may send and to which it may receive
411 packets to the specified addresses. A masked address, if the host part
412 is zero, indicates that the host is allowed to use any address in the
413 subnet; if the host part is nonzero, the mask simply indicates the size
414 of the subnet. In addition:
420 If any IPv4 address is given, the host is also allowed to receive
421 packets to the IPv4 local broadcast address 255.255.255.255 and to
422 IPv4 multicast addresses (224.0.0.0/4). If an IPv4 address with a
423 mask is given, the host is also allowed to receive packets to the
424 broadcast address in that specified subnet.
428 If any IPv4 address is given, the host is additionally restricted
429 to sending ARP packets with the specified source IPv4 address.
430 (RARP is not restricted.)
436 If any IPv6 address is given, the host is also allowed to receive
437 packets to IPv6 multicast addresses (ff00::/8).
441 If any IPv6 address is given, the host is additionally restricted
442 to sending IPv6 Neighbor Discovery Solicitation or Advertisement
443 packets with the specified source address or, for solicitations,
444 the unspecified address.
450 If an element includes an IPv4 address, but no IPv6 addresses, then
451 IPv6 traffic is not allowed. If an element includes an IPv6 address,
452 but no IPv4 address, then IPv4 and ARP traffic is not allowed.
456 This column uses the same lexical syntax as the <ref column="match"
457 table="Pipeline" db="OVN_Southbound"/> column in the OVN Southbound
458 database's <ref table="Pipeline" db="OVN_Southbound"/> table. Multiple
459 addresses within an element may be space or comma separated.
463 This column is provided as a convenience to cloud management systems,
464 but all of the features that it implements can be implemented as ACLs
465 using the <ref table="ACL"/> table.
473 <dt><code>80:fa:5b:06:72:b7</code></dt>
475 The host may send traffic from and receive traffic to the specified
476 MAC address, and to receive traffic to Ethernet multicast and
477 broadcast addresses, but not otherwise. The host may not send ARP or
478 IPv6 Neighbor Discovery packets with inner source Ethernet addresses
479 other than the one specified.
482 <dt><code>80:fa:5b:06:72:b7 192.168.1.10/24</code></dt>
484 This adds further restrictions to the first example. The host may
485 send IPv4 packets from or receive IPv4 packets to only 192.168.1.10,
486 except that it may also receive IPv4 packets to 192.168.1.255 (based
487 on the subnet mask), 255.255.255.255, and any address in 224.0.0.0/4.
488 The host may not send ARPs with a source Ethernet address other than
489 80:fa:5b:06:72:b7 or source IPv4 address other than 192.168.1.10.
490 The host may not send or receive any IPv6 (including IPv6 Neighbor
494 <dt><code>"80:fa:5b:12:42:ba", "80:fa:5b:06:72:b7 192.168.1.10/24"</code></dt>
496 The host may send traffic from and receive traffic to the
497 specified MAC addresses, and
498 to receive traffic to Ethernet multicast and broadcast addresses,
499 but not otherwise. With MAC 80:fa:5b:12:42:ba, the host may
500 send traffic from and receive traffic to any L3 address.
501 With MAC 80:fa:5b:06:72:b7, the host may send IPv4 packets from or
502 receive IPv4 packets to only 192.168.1.10, except that it may also
503 receive IPv4 packets to 192.168.1.255 (based on the subnet mask),
504 255.255.255.255, and any address in 224.0.0.0/4. The host may not
505 send or receive any IPv6 (including IPv6 Neighbor Discovery) traffic.
511 <group title="Common Columns">
512 <column name="external_ids">
513 See <em>External IDs</em> at the beginning of this document.
518 <table name="Address_Set" title="Address Sets">
520 Each row in this table represents a named set of addresses.
521 An address set may contain Ethernet, IPv4, or IPv6 addresses
522 with optional bitwise or CIDR masks.
523 Address set may ultimately be used in ACLs to compare against
524 fields such as <code>ip4.src</code> or <code>ip6.src</code>.
525 A single address set must contain addresses of the
526 same type. As an example, the following would create an address set
527 with three IP addresses:
531 ovn-nbctl create Address_Set name=set1 addresses='10.0.0.1 10.0.0.2 10.0.0.3'
535 Address sets may be used in the <ref column="match" table="ACL"/> column
536 of the <ref table="ACL"/> table. For syntax information, see the details
537 of the expression language used for the <ref column="match"
538 table="Logical_Flow" db="OVN_Southbound"/> column in the <ref
539 table="Logical_Flow" db="OVN_Southbound"/> table of the <ref
540 db="OVN_Southbound"/> database.
544 A name for the address set. This must be unique among all address sets.
547 <column name="addresses">
548 The set of addresses in string form.
551 <group title="Common Columns">
552 <column name="external_ids">
553 See <em>External IDs</em> at the beginning of this document.
558 <table name="Load_Balancer" title="load balancer">
560 Each row represents one load balancer.
565 A map of virtual IPv4 addresses (and an optional port number with
566 <code>:</code> as a separator) associated with this load balancer and
567 their corresponding endpoint IPv4 addresses (and optional port numbers
568 with <code>:</code> as separators) separated by commas. If
569 the destination IP address (and port number) of a packet leaving a
570 container or a VM matches the virtual IPv4 address (and port number)
571 provided here as a key, then OVN will statefully replace the
572 destination IP address by one of the provided IPv4 address (and port
573 number) in this map as a value. Examples for keys are "192.168.1.4"
574 and "172.16.1.8:80". Examples for value are "10.0.0.1, 10.0.0.2" and
575 "20.0.0.10:8800, 20.0.0.11:8800".
579 <column name="protocol">
581 Valid protocols are <code>tcp</code> or <code>udp</code>. This column
582 is useful when a port number is provided as part of the
583 <code>vips</code> column. If this column is empty and a port number
584 is provided as part of <code>vips</code> column, OVN assumes the
585 protocol to be <code>tcp</code>.
589 <group title="Common Columns">
590 <column name="external_ids">
591 See <em>External IDs</em> at the beginning of this document.
596 <table name="ACL" title="Access Control List (ACL) rule">
598 Each row in this table represents one ACL rule for a logical switch
599 that points to it through its <ref column="acls"/> column. The <ref
600 column="action"/> column for the highest-<ref column="priority"/>
601 matching row in this table determines a packet's treatment. If no row
602 matches, packets are allowed by default. (Default-deny treatment is
603 possible: add a rule with <ref column="priority"/> 0, <code>0</code> as
604 <ref column="match"/>, and <code>deny</code> as <ref column="action"/>.)
607 <column name="priority">
609 The ACL rule's priority. Rules with numerically higher priority
610 take precedence over those with lower. If two ACL rules with
611 the same priority both match, then the one actually applied to a
616 Return traffic from an <code>allow-related</code> flow is always
617 allowed and cannot be changed through an ACL.
621 <column name="direction">
622 <p>Direction of the traffic to which this rule should apply:</p>
625 <code>from-lport</code>: Used to implement filters on traffic
626 arriving from a logical port. These rules are applied to the
627 logical switch's ingress pipeline.
630 <code>to-lport</code>: Used to implement filters on traffic
631 forwarded to a logical port. These rules are applied to the
632 logical switch's egress pipeline.
637 <column name="match">
639 The packets that the ACL should match, in the same expression
640 language used for the <ref column="match" table="Logical_Flow"
641 db="OVN_Southbound"/> column in the OVN Southbound database's
642 <ref table="Logical_Flow" db="OVN_Southbound"/> table. The
643 <code>outport</code> logical port is only available in the
644 <code>to-lport</code> direction (the <code>inport</code> is
645 available in both directions).
649 By default all traffic is allowed. When writing a more
650 restrictive policy, it is important to remember to allow flows
651 such as ARP and IPv6 neighbor discovery packets.
655 Note that you can not create an ACL matching on a port with
660 Note that when <code>localnet</code> port exists in a lswitch, for
661 <code>to-lport</code> direction, the <code>inport</code> works only if
662 the <code>to-lport</code> is located on the same chassis as the
667 <column name="action">
668 <p>The action to take when the ACL rule matches:</p>
671 <code>allow</code>: Forward the packet.
675 <code>allow-related</code>: Forward the packet and related traffic
676 (e.g. inbound replies to an outbound connection).
680 <code>drop</code>: Silently drop the packet.
684 <code>reject</code>: Drop the packet, replying with a RST for TCP or
685 ICMP unreachable message for other IP-based protocols.
686 <code>Not implemented--currently treated as drop</code>
693 If set to <code>true</code>, packets that match the ACL will trigger a
694 log message on the transport node or nodes that perform ACL processing.
695 Logging may be combined with any <ref column="action"/>.
699 Logging is not yet implemented.
703 <group title="Common Columns">
704 <column name="external_ids">
705 See <em>External IDs</em> at the beginning of this document.
710 <table name="Logical_Router" title="L3 logical router">
712 Each row represents one L3 logical router.
717 A name for the logical router. This name has no special meaning or purpose
718 other than to provide convenience for human interaction with the ovn-nb
719 database. There is no requirement for the name to be unique. The
720 logical router's UUID should be used as the unique identifier.
724 <column name="ports">
728 <column name="static_routes">
729 One or more static routes for the router.
732 <column name="enabled">
733 This column is used to administratively set router state. If this column
734 is empty or is set to <code>true</code>, the router is enabled. If this
735 column is set to <code>false</code>, the router is disabled. A disabled
736 router has all ingress and egress traffic dropped.
740 One or more NAT rules for the router. NAT rules only work on the
744 <group title="Options">
746 Additional options for the logical router.
749 <column name="options" key="chassis">
751 If set, indicates that the logical router in question is a Gateway
752 router (which is centralized) and resides in the set chassis. The
753 same value is also used by <code>ovn-controller</code> to
754 uniquely identify the chassis in the OVN deployment and
755 comes from <code>external_ids:system-id</code> in the
756 <code>Open_vSwitch</code> table of Open_vSwitch database.
760 The Gateway router can only be connected to a distributed router
761 via a switch if SNAT and DNAT are to be configured in the Gateway
767 <group title="Common Columns">
768 <column name="external_ids">
769 See <em>External IDs</em> at the beginning of this document.
774 <table name="Logical_Router_Port" title="L3 logical router port">
776 A port within an L3 logical router.
780 Exactly one <ref table="Logical_Router"/> row must reference a given
786 A name for the logical router port.
790 In addition to provide convenience for human interaction with the
791 ovn-nb database, this column is used as reference by its patch port in
792 <ref table="Logical_Switch_Port"/> or another logical router port in
793 <ref table="Logical_Router_Port"/>.
797 <column name="networks">
799 The IP addresses and netmasks of the router. For example,
800 <code>192.168.0.1/24</code> indicates that the router's IP
801 address is 192.168.0.1 and that packets destined to
802 192.168.0.<var>x</var> should be routed to this port.
807 The Ethernet address that belongs to this router port.
810 <column name="enabled">
811 This column is used to administratively set port state. If this column
812 is empty or is set to <code>true</code>, the port is enabled. If this
813 column is set to <code>false</code>, the port is disabled. A disabled
814 port has all ingress and egress traffic dropped.
817 <group title="Attachment">
819 A given router port serves one of two purposes:
824 To attach a logical switch to a logical router. A logical router
825 port of this type is referenced by exactly one <ref
826 table="Logical_Switch_Port"/> of type <code>router</code>.
827 The value of <ref column="name"/> is set as
828 <code>router-port</code> in column <ref column="options"/> of
829 <ref table="Logical_Switch_Port"/>. In this case <ref
830 column="peer"/> column is empty.
834 To connect one logical router to another. This requires a pair of
835 logical router ports, each connected to a different router. Each
836 router port in the pair specifies the other in its <ref
837 column="peer"/> column. No <ref table="Logical_Switch"/> refers to
844 For a router port used to connect two logical routers, this
845 identifies the other router port in the pair by <ref column="name"/>.
849 For a router port attached to a logical switch, this column is empty.
854 <group title="Common Columns">
855 <column name="external_ids">
856 See <em>External IDs</em> at the beginning of this document.
861 <table name="Logical_Router_Static_Route" title="Logical router static routes">
863 Each record represents a static route.
866 <column name="ip_prefix">
868 IP prefix of this route (e.g. 192.168.100.0/24).
872 <column name="nexthop">
874 Nexthop IP address for this route. Nexthop IP address should be the IP
875 address of a connected router port or the IP address of a logical port.
879 <column name="output_port">
881 The name of the <ref table="Logical_Router_Port"/> via which the packet
882 needs to be sent out. This is optional and when not specified,
883 OVN will automatically figure this out based on the
884 <ref column="nexthop"/>.
889 <table name="NAT" title="NAT rules for a Gateway router.">
891 Each record represents a NAT rule in a Gateway router.
895 <p>Type of the NAT rule.</p>
898 When <ref column="type"/> is <code>dnat</code>, the externally
899 visible IP address <ref column="external_ip"/> is DNATted to the IP
900 address <ref column="logical_ip"/> in the logical space.
903 When <ref column="type"/> is <code>snat</code>, IP packets
904 with their source IP address that either matches the IP address
905 in <ref column="logical_ip"/> or is in the network provided by
906 <ref column="logical_ip"/> is SNATed into the IP address in
907 <ref column="external_ip"/>.
910 When <ref column="type"/> is <code>dnat_and_snat</code>, the
911 externally visible IP address <ref column="external_ip"/> is
912 DNATted to the IP address <ref column="logical_ip"/> in the
913 logical space. In addition, IP packets with the source IP
914 address that matches <ref column="logical_ip"/> is SNATed into
915 the IP address in <ref column="external_ip"/>.
920 <column name="external_ip">
924 <column name="logical_ip">
925 An IPv4 network (e.g 192.168.1.0/24) or an IPv4 address.