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.
40 A name for the logical switch. This name has no special meaning or purpose
41 other than to provide convenience for human interaction with the ovn-nb
42 database. There is no requirement for the name to be unique. The
43 logical switch's UUID should be used as the unique identifier.
49 The logical ports connected to the logical switch.
53 It is an error for multiple logical switches to include the same
58 <column name="router_port">
60 The router port to which this logical switch is connected, or empty if
61 this logical switch is not connected to any router. A switch may be
62 connected to at most one logical router, but this is not a significant
63 restriction because logical routers may be connected into arbitrary
68 It is an error for multiple logical switches to refer to the same
74 Access control rules that apply to packets within the logical switch.
77 <group title="Common Columns">
78 <column name="external_ids">
79 See <em>External IDs</em> at the beginning of this document.
84 <table name="Logical_Port" title="L2 logical switch port">
86 A port within an L2 logical switch.
89 <group title="Core Features">
92 The logical port name.
96 For entities (VMs or containers) that are spawned in the hypervisor,
97 the name used here must match those used in the <ref key="iface-id"
98 table="Interface" column="external_ids" db="Open_vSwitch"/> in the
99 <ref db="Open_vSwitch"/> database's <ref table="Interface"
100 db="Open_vSwitch"/> table, because hypervisors use <ref key="iface-id"
101 table="Interface" column="external_ids" db="Open_vSwitch"/> as a lookup
102 key to identify the network interface of that entity.
106 For containers that share a VIF within a VM, the name can be any
107 unique identifier. See <code>Containers</code>, below, for more
114 Specify a type for this logical port. Logical ports can be used to
115 model other types of connectivity into an OVN logical switch. The
116 following types are defined:
120 <dt>(empty string)</dt>
122 A VM (or VIF) interface.
125 <dt><code>localnet</code></dt>
127 A connection to a locally accessible network from each
128 <code>ovn-controller</code> instance. A logical switch can only
129 have a single <code>localnet</code> port attached and at most one
130 regular logical port. This is used to model direct connectivity to
134 <dt><code>vtep</code></dt>
136 A port to a logical switch on a VTEP gateway.
142 <group title="Options">
143 <column name="options">
144 This column provides key/value settings specific to the logical port
145 <ref column="type"/>. The type-specific options are described
149 <group title="Options for localnet ports">
151 These options apply when <ref column="type"/> is
152 <code>localnet</code>.
155 <column name="options" key="network_name">
156 Required. The name of the network to which the <code>localnet</code>
157 port is connected. Each hypervisor, via <code>ovn-controller</code>,
158 uses its local configuration to determine exactly how to connect to
159 this locally accessible network.
163 <group title="Options for vtep ports">
165 These options apply when <ref column="type"/> is <code>vtep</code>.
168 <column name="options" key="vtep-physical-switch">
169 Required. The name of the VTEP gateway.
172 <column name="options" key="vtep-logical-switch">
173 Required. A logical switch name connected by the VTEP gateway.
178 <group title="Containers">
180 When a large number of containers are nested within a VM, it may be too
181 expensive to dedicate a VIF to each container. OVN can use VLAN tags
182 to support such cases. Each container is assigned a VLAN ID and each
183 packet that passes between the hypervisor and the VM is tagged with the
184 appropriate ID for the container. Such VLAN IDs never appear on a
185 physical wire, even inside a tunnel, so they need not be unique except
186 relative to a single VM on a hypervisor.
190 These columns are used for VIFs that represent nested containers using
191 shared VIFs. For VMs and for containers that have dedicated VIFs, they
195 <column name="parent_name">
196 The VM interface through which the nested container sends its network
197 traffic. This must match the <ref column="name"/> column for some
198 other <ref table="Logical_Port"/>.
203 The VLAN tag in the network traffic associated with a container's
208 When <ref column="type"/> is set to <code>localnet</code>, this can
209 be set to indicate that the port represents a connection to a
210 specific VLAN on a locally accessible network. The VLAN ID is used to
211 match incoming traffic and is also added to outgoing traffic.
216 <group title="Port State">
218 This column is populated by <code>ovn-northd</code>, rather than by the
219 CMS plugin as is most of this database. When a logical port is bound
220 to a physical location in the OVN Southbound database <ref
221 db="OVN_Southbound" table="Binding"/> table, <code>ovn-northd</code>
222 sets this column to <code>true</code>; otherwise, or if the port
223 becomes unbound later, it sets it to <code>false</code>. This allows
224 the CMS to wait for a VM's (or container's) networking to become active
225 before it allows the VM (or container) to start.
228 <column name="enabled">
229 This column is used to administratively set port state. If this column
230 is empty or is set to <code>true</code>, the port is enabled. If this
231 column is set to <code>false</code>, the port is disabled. A disabled
232 port has all ingress and egress traffic dropped.
237 <group title="Addressing">
238 <column name="addresses">
240 Addresses owned by the logical port.
244 Each element in the set must take one of the following forms:
248 <dt><code><var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var></code></dt>
251 An Ethernet address owned by the logical port. Like a physical
252 Ethernet NIC, a logical port ordinarily has a single fixed
257 When a OVN logical switch processes a unicast Ethernet frame
258 whose destination MAC address is in a logical port's <ref
259 column="addresses"/> column, it delivers it only to that port, as
260 if a MAC learning process had learned that MAC address on the
265 <dt><code><var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var> <var>a</var>.<var>b</var>.<var>c</var>.<var>d</var></code></dt>
268 This form has all the effects of the previous form. It also
269 indicates that the logical port owns the given IPv4 address.
273 The OVN logical switch uses this information to synthesize
274 responses to ARP requests without traversing the physical
275 network. The OVN logical router connected to the logical switch,
276 if any, uses this information to avoid issuing ARP requests for
277 logical switch ports.
281 <dt><code>unknown</code></dt>
283 This indicates that the logical port has an unknown set of Ethernet
284 addresses. When an OVN logical switch processes a unicast Ethernet
285 frame whose destination MAC address is not in any logical port's
286 <ref column="addresses"/> column, it delivers it to the port (or
287 ports) whose <ref column="addresses"/> columns include
288 <code>unknown</code>.
293 <column name="port_security">
295 A set of L2 (Ethernet) addresses from which the logical port is
296 allowed to send packets and to which it is allowed to receive
297 packets. If this column is empty, all addresses are permitted.
298 Logical ports are always allowed to receive packets addressed to
299 multicast and broadcast addresses.
303 Each member of the set is an Ethernet address in the form
304 <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
308 This specification will be extended to support L3 port security.
313 <group title="Common Columns">
314 <column name="external_ids">
315 See <em>External IDs</em> at the beginning of this document.
320 <table name="ACL" title="Access Control List (ACL) rule">
322 Each row in this table represents one ACL rule for a logical switch
323 that points to it through its <ref column="acls"/> column. The <ref
324 column="action"/> column for the highest-<ref column="priority"/>
325 matching row in this table determines a packet's treatment. If no row
326 matches, packets are allowed by default. (Default-deny treatment is
327 possible: add a rule with <ref column="priority"/> 1, <code>1</code> as
328 <ref column="match"/>, and <code>deny</code> as <ref column="action"/>.)
331 <column name="priority">
333 The ACL rule's priority. Rules with numerically higher priority
334 take precedence over those with lower. If two ACL rules with
335 the same priority both match, then the one actually applied to a
340 Return traffic from an <code>allow-related</code> flow is always
341 allowed and cannot be changed through an ACL.
345 <column name="direction">
346 <p>Direction of the traffic to which this rule should apply:</p>
349 <code>from-lport</code>: Used to implement filters on traffic
350 arriving from a logical port. These rules are applied to the
351 logical switch's ingress pipeline.
354 <code>to-lport</code>: Used to implement filters on traffic
355 forwarded to a logical port. These rules are applied to the
356 logical switch's egress pipeline.
361 <column name="match">
363 The packets that the ACL should match, in the same expression
364 language used for the <ref column="match" table="Logical_Flow"
365 db="OVN_Southbound"/> column in the OVN Southbound database's
366 <ref table="Logical_Flow" db="OVN_Southbound"/> table. The
367 <code>outport</code> logical port is only available in the
368 <code>to-lport</code> direction (the <code>inport</code> is
369 available in both directions).
373 By default all traffic is allowed. When writing a more
374 restrictive policy, it is important to remember to allow flows
375 such as ARP and IPv6 neighbor discovery packets.
379 In logical switches connected to logical routers, the special
380 port name <code>ROUTER</code> refers to the logical router port.
384 <column name="action">
385 <p>The action to take when the ACL rule matches:</p>
388 <code>allow</code>: Forward the packet.
392 <code>allow-related</code>: Forward the packet and related traffic
393 (e.g. inbound replies to an outbound connection).
397 <code>drop</code>: Silently drop the packet.
401 <code>reject</code>: Drop the packet, replying with a RST for TCP or
402 ICMP unreachable message for other IP-based protocols.
403 <code>Not implemented--currently treated as drop</code>
410 If set to <code>true</code>, packets that match the ACL will trigger a
411 log message on the transport node or nodes that perform ACL processing.
412 Logging may be combined with any <ref column="action"/>.
416 Logging is not yet implemented.
420 <group title="Common Columns">
421 <column name="external_ids">
422 See <em>External IDs</em> at the beginning of this document.
427 <table name="Logical_Router" title="L3 logical router">
429 Each row represents one L3 logical router.
434 A name for the logical router. This name has no special meaning or purpose
435 other than to provide convenience for human interaction with the ovn-nb
436 database. There is no requirement for the name to be unique. The
437 logical router's UUID should be used as the unique identifier.
441 <column name="ports">
445 <column name="default_gw">
446 IP address to use as default gateway, if any.
449 <group title="Common Columns">
450 <column name="external_ids">
451 See <em>External IDs</em> at the beginning of this document.
456 <table name="Logical_Router_Port" title="L3 logical router port">
458 A port within an L3 logical router.
462 Exactly one <ref table="Logical_Router"/> row must reference a given
468 A name for the logical router port. This name has no special meaning or purpose
469 other than to provide convenience for human interaction with the ovn-nb
470 database. There is no requirement for the name to be unique. The
471 logical router port's UUID should be used as the unique identifier.
475 <column name="network">
476 The IP address of the router and the netmask. For example,
477 <code>192.168.0.1/24</code> indicates that the router's IP address is
478 192.168.0.1 and that packets destined to 192.168.0.<var>x</var> should be
483 The Ethernet address that belongs to this router port.
486 <group title="Attachment">
488 A given router port serves one of two purposes:
493 To attach a logical switch to a logical router. A logical router
494 port of this type is referenced by exactly the <ref
495 column="router_port" table="Logical_Switch"/> column in exactly one
496 <ref table="Logical_Switch"/> row. The <ref column="peer"/> column
501 To connect one logical router to another. This requires a pair of
502 logical router ports, each connected to a different router. Each
503 router port in the pair specifies the other in its <ref
504 column="peer"/> column. No <ref table="Logical_Switch"/> refers to
511 For a router port used to connect two logical routers, this
512 identifies the other router port in the pair.
516 For a router port attached to a logical switch, this column is empty.
521 <group title="Common Columns">
522 <column name="external_ids">
523 See <em>External IDs</em> at the beginning of this document.