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_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>.
158 If a given logical switch has multiple <code>router</code> ports, the
159 <ref table="Logical_Router_Port"/> rows that they reference must be
160 all on the same <ref table="Logical_Router"/> (for different
164 <column name="options" key="router-port">
165 Required. The <ref column="name"/> of the <ref
166 table="Logical_Router_Port"/> to which this logical switch port is
171 <group title="Options for localnet ports">
173 These options apply when <ref column="type"/> is
174 <code>localnet</code>.
177 <column name="options" key="network_name">
178 Required. The name of the network to which the <code>localnet</code>
179 port is connected. Each hypervisor, via <code>ovn-controller</code>,
180 uses its local configuration to determine exactly how to connect to
181 this locally accessible network.
185 <group title="Options for vtep ports">
187 These options apply when <ref column="type"/> is <code>vtep</code>.
190 <column name="options" key="vtep-physical-switch">
191 Required. The name of the VTEP gateway.
194 <column name="options" key="vtep-logical-switch">
195 Required. A logical switch name connected by the VTEP gateway.
199 <group title="VMI (or VIF) Options">
201 These options apply to logical ports with <ref column="type"/> having
205 <column name="options" key="policing_rate">
206 If set, indicates the maximum rate for data sent from this interface,
207 in kbps. Data exceeding this rate is dropped.
210 <column name="options" key="policing_burst">
211 If set, indicates the maximum burst size for data sent from this
217 <group title="Containers">
219 When a large number of containers are nested within a VM, it may be too
220 expensive to dedicate a VIF to each container. OVN can use VLAN tags
221 to support such cases. Each container is assigned a VLAN ID and each
222 packet that passes between the hypervisor and the VM is tagged with the
223 appropriate ID for the container. Such VLAN IDs never appear on a
224 physical wire, even inside a tunnel, so they need not be unique except
225 relative to a single VM on a hypervisor.
229 These columns are used for VIFs that represent nested containers using
230 shared VIFs. For VMs and for containers that have dedicated VIFs, they
234 <column name="parent_name">
235 The VM interface through which the nested container sends its network
236 traffic. This must match the <ref column="name"/> column for some
237 other <ref table="Logical_Port"/>.
242 The VLAN tag in the network traffic associated with a container's
247 When <ref column="type"/> is set to <code>localnet</code>, this can
248 be set to indicate that the port represents a connection to a
249 specific VLAN on a locally accessible network. The VLAN ID is used to
250 match incoming traffic and is also added to outgoing traffic.
255 <group title="Port State">
257 This column is populated by <code>ovn-northd</code>, rather than by the
258 CMS plugin as is most of this database. When a logical port is bound
259 to a physical location in the OVN Southbound database <ref
260 db="OVN_Southbound" table="Binding"/> table, <code>ovn-northd</code>
261 sets this column to <code>true</code>; otherwise, or if the port
262 becomes unbound later, it sets it to <code>false</code>. This allows
263 the CMS to wait for a VM's (or container's) networking to become active
264 before it allows the VM (or container) to start.
267 <column name="enabled">
268 This column is used to administratively set port state. If this column
269 is empty or is set to <code>true</code>, the port is enabled. If this
270 column is set to <code>false</code>, the port is disabled. A disabled
271 port has all ingress and egress traffic dropped.
276 <group title="Addressing">
277 <column name="addresses">
279 Addresses owned by the logical port.
283 Each element in the set must take one of the following forms:
287 <dt><code>Ethernet address followed by zero or more IPv4 or IPv6 addresses (or both)</code></dt>
290 An Ethernet address defined is owned by the logical port.
291 Like a physical Ethernet NIC, a logical port ordinarily has
292 a single fixed Ethernet address.
296 When a OVN logical switch processes a unicast Ethernet frame
297 whose destination MAC address is in a logical port's <ref
298 column="addresses"/> column, it delivers it only to that port, as
299 if a MAC learning process had learned that MAC address on the
304 If IPv4 or IPv6 address(es) (or both) are defined, it indicates
305 that the logical port owns the given IP addresses.
309 If IPv4 address(es) are defined, the OVN logical switch uses this
310 information to synthesize responses to ARP requests without
311 traversing the physical network. The OVN logical router connected
312 to the logical switch, if any, uses this information to avoid
313 issuing ARP requests for logical switch ports.
317 Note that the order here is important. The Ethernet address must
318 be listed before the IP address(es) if defined.
326 <dt><code>80:fa:5b:06:72:b7</code></dt>
328 This indicates that the logical port owns the above mac address.
331 <dt><code>80:fa:5b:06:72:b7 10.0.0.4 20.0.0.4</code></dt>
333 This indicates that the logical port owns the mac address and two
337 <dt><code>80:fa:5b:06:72:b7 fdaa:15f2:72cf:0:f816:3eff:fe20:3f41</code></dt>
339 This indicates that the logical port owns the mac address and
343 <dt><code>80:fa:5b:06:72:b7 10.0.0.4 fdaa:15f2:72cf:0:f816:3eff:fe20:3f41</code></dt>
345 This indicates that the logical port owns the mac address and
346 1 IPv4 address and 1 IPv6 address.
351 <dt><code>unknown</code></dt>
353 This indicates that the logical port has an unknown set of Ethernet
354 addresses. When an OVN logical switch processes a unicast Ethernet
355 frame whose destination MAC address is not in any logical port's
356 <ref column="addresses"/> column, it delivers it to the port (or
357 ports) whose <ref column="addresses"/> columns include
358 <code>unknown</code>.
363 <column name="port_security">
365 A set of L2 (Ethernet) addresses from which the logical port is
366 allowed to send packets and to which it is allowed to receive
367 packets. If this column is empty, all addresses are permitted.
368 Logical ports are always allowed to receive packets addressed to
369 multicast and broadcast addresses.
373 Each member of the set is an Ethernet address in the form
374 <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
378 This specification will be extended to support L3 port security.
383 <group title="Common Columns">
384 <column name="external_ids">
385 See <em>External IDs</em> at the beginning of this document.
390 <table name="ACL" title="Access Control List (ACL) rule">
392 Each row in this table represents one ACL rule for a logical switch
393 that points to it through its <ref column="acls"/> column. The <ref
394 column="action"/> column for the highest-<ref column="priority"/>
395 matching row in this table determines a packet's treatment. If no row
396 matches, packets are allowed by default. (Default-deny treatment is
397 possible: add a rule with <ref column="priority"/> 0, <code>0</code> as
398 <ref column="match"/>, and <code>deny</code> as <ref column="action"/>.)
401 <column name="priority">
403 The ACL rule's priority. Rules with numerically higher priority
404 take precedence over those with lower. If two ACL rules with
405 the same priority both match, then the one actually applied to a
410 Return traffic from an <code>allow-related</code> flow is always
411 allowed and cannot be changed through an ACL.
415 <column name="direction">
416 <p>Direction of the traffic to which this rule should apply:</p>
419 <code>from-lport</code>: Used to implement filters on traffic
420 arriving from a logical port. These rules are applied to the
421 logical switch's ingress pipeline.
424 <code>to-lport</code>: Used to implement filters on traffic
425 forwarded to a logical port. These rules are applied to the
426 logical switch's egress pipeline.
431 <column name="match">
433 The packets that the ACL should match, in the same expression
434 language used for the <ref column="match" table="Logical_Flow"
435 db="OVN_Southbound"/> column in the OVN Southbound database's
436 <ref table="Logical_Flow" db="OVN_Southbound"/> table. The
437 <code>outport</code> logical port is only available in the
438 <code>to-lport</code> direction (the <code>inport</code> is
439 available in both directions).
443 By default all traffic is allowed. When writing a more
444 restrictive policy, it is important to remember to allow flows
445 such as ARP and IPv6 neighbor discovery packets.
449 Note that you can not create an ACL matching on a port with
454 Note that when <code>localnet</code> port exists in a lswitch, for
455 <code>to-lport</code> direction, the <code>inport</code> works only if
456 the <code>to-lport</code> is located on the same chassis as the
461 <column name="action">
462 <p>The action to take when the ACL rule matches:</p>
465 <code>allow</code>: Forward the packet.
469 <code>allow-related</code>: Forward the packet and related traffic
470 (e.g. inbound replies to an outbound connection).
474 <code>drop</code>: Silently drop the packet.
478 <code>reject</code>: Drop the packet, replying with a RST for TCP or
479 ICMP unreachable message for other IP-based protocols.
480 <code>Not implemented--currently treated as drop</code>
487 If set to <code>true</code>, packets that match the ACL will trigger a
488 log message on the transport node or nodes that perform ACL processing.
489 Logging may be combined with any <ref column="action"/>.
493 Logging is not yet implemented.
497 <group title="Common Columns">
498 <column name="external_ids">
499 See <em>External IDs</em> at the beginning of this document.
504 <table name="Logical_Router" title="L3 logical router">
506 Each row represents one L3 logical router.
511 A name for the logical router. This name has no special meaning or purpose
512 other than to provide convenience for human interaction with the ovn-nb
513 database. There is no requirement for the name to be unique. The
514 logical router's UUID should be used as the unique identifier.
518 <column name="ports">
522 <column name="default_gw">
523 IP address to use as default gateway, if any.
526 <group title="Common Columns">
527 <column name="external_ids">
528 See <em>External IDs</em> at the beginning of this document.
533 <table name="Logical_Router_Port" title="L3 logical router port">
535 A port within an L3 logical router.
539 Exactly one <ref table="Logical_Router"/> row must reference a given
545 A name for the logical router port.
549 In addition to provide convenience for human interaction with the
550 ovn-nb database, this column is used as reference by its patch port in
551 <ref table="Logical_Port"/> or another logical router port in <ref
552 table="Logical_Router_Port"/>.
556 <column name="network">
557 The IP address of the router and the netmask. For example,
558 <code>192.168.0.1/24</code> indicates that the router's IP address is
559 192.168.0.1 and that packets destined to 192.168.0.<var>x</var> should be
564 The Ethernet address that belongs to this router port.
567 <column name="enabled">
568 This column is used to administratively set port state. If this column
569 is empty or is set to <code>true</code>, the port is enabled. If this
570 column is set to <code>false</code>, the port is disabled. A disabled
571 port has all ingress and egress traffic dropped.
574 <group title="Attachment">
576 A given router port serves one of two purposes:
581 To attach a logical switch to a logical router. A logical router
582 port of this type is referenced by exactly one <ref
583 table="Logical_Port"/> of type <code>router</code>. The value of
584 <ref column="name"/> is set as <code>router-port</code> in column
585 <ref column="options"/> of <ref table="Logical_Port"/>.
586 In this case <ref column="peer"/> column is empty.
590 To connect one logical router to another. This requires a pair of
591 logical router ports, each connected to a different router. Each
592 router port in the pair specifies the other in its <ref
593 column="peer"/> column. No <ref table="Logical_Switch"/> refers to
600 For a router port used to connect two logical routers, this
601 identifies the other router port in the pair by <ref column="name"/>.
605 For a router port attached to a logical switch, this column is empty.
610 <group title="Common Columns">
611 <column name="external_ids">
612 See <em>External IDs</em> at the beginning of this document.