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.
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 are spawned inside a VM, the name can be
106 any unique identifier. In such a case, <ref column="parent_name"/>
113 Specify a type for this logical port. Logical ports can be used to model
114 other types of connectivity into an OVN logical switch. Leaving this
115 column blank maintains the default logical port behavior, which is
116 for a VM (or VIF) interface. The following other types are defined:
120 <dt><code>localnet</code></dt>
121 <dd>A connection to a locally accessible network from each
122 <code>ovn-controller</code> instance. A logical switch can only
123 have a single <code>localnet</code> port attached and at most one
124 regular logical port. This is used to model direct connectivity
125 to an existing network.</dd>
129 <dt><code>vtep</code></dt>
130 <dd>A port to a logical switch on a VTEP gateway. In order
131 to get this port correctly recognized by the OVN controller, the
132 <ref column="options" table="Logical_Port"/>:<code>vtep-physical-switch</code>
133 and <ref column="options" table="Logical_Port"/>:<code>vtep-logical-switch</code>
134 must also be defined.</dd>
138 <column name="options">
140 This column provides key/value settings specific to the logical port
141 <ref column="type"/>. The following options are defined:
145 <dt><code>network_name</code></dt>
147 Must be set when <ref column="type"/> is <code>localnet</code>.
148 <code>ovn-controller</code> uses local configuration to determine
149 exactly how to connect to this locally accessible network.
154 <dt><code>vtep-physical-switch</code></dt>
156 The name of the VTEP gateway. Must be set when
157 <ref column="type"/> is <code>vtep</code>.
162 <dt><code>vtep-logical-switch</code></dt>
164 A logical switch name connected by the VTEP gateway. Must be
165 set when <ref column="type"/> is <code>vtep</code>.
170 <column name="parent_name">
171 When <ref column="name"/> identifies the interface of a container
172 spawned inside a tenant VM, this column represents the VM interface
173 through which the container interface sends its network traffic.
174 The name used here must match those used in the <ref key="iface-id"
175 table="Interface" column="external_ids" db="Open_vSwitch"/> in the
176 <ref db="Open_vSwitch"/> table, because hypervisors in this case use
177 <ref key="iface-id" table="Interface" column="external_ids"
178 db="Open_vSwitch"/> as a lookup key to identify the network interface
184 When <ref column="type"/> is empty and <ref column="name"/> identifies
185 the interface of a container spawned inside a tenant VM, this column
186 identifies the VLAN tag in the network traffic associated with that
187 container's network interface. When there are multiple container
188 interfaces inside a VM, all of them send their network traffic through a
189 single VM network interface and this value helps OVN identify the correct
194 When <ref column="type"/> is set to <code>localnet</code>, this can be
195 set to indicate that the port represents a connection to a specific
196 VLAN on a locally accessible network. The VLAN ID is used to match
197 incoming traffic and is also added to outgoing traffic.
202 This column is populated by <code>ovn-northd</code>, rather than by
203 the CMS plugin as is most of this database. When a logical port is bound
204 to a physical location in the OVN Southbound database <ref
205 db="OVN_Southbound" table="Binding"/> table, <code>ovn-northd</code>
206 sets this column to <code>true</code>; otherwise, or if the port
207 becomes unbound later, it sets it to <code>false</code>. This
208 allows the CMS to wait for a VM's (or container's) networking to
209 become active before it allows the VM (or container) to start.
212 <column name="enabled">
213 This column is used to administratively set port state. If this column is
214 empty or is set to <code>true</code>, the port is enabled. If this column
215 is set to <code>false</code>, the port is disabled. A disabled port has all
216 ingress and egress traffic dropped.
220 The logical port's own Ethernet address or addresses, each in the form
221 <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
222 Like a physical Ethernet NIC, a logical port ordinarily has a single
223 fixed Ethernet address. The string <code>unknown</code> is also allowed
224 to indicate that the logical port has an unknown set of (additional)
228 <column name="port_security">
230 A set of L2 (Ethernet) addresses
231 from which the logical port is allowed to send packets and to which it
232 is allowed to receive packets. If this column is empty, all addresses
233 are permitted. Logical ports are always allowed to receive packets
234 addressed to multicast and broadcast addresses.
238 Each member of the set is an Ethernet address in the form
239 <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
243 This specification will be extended to support L3 port security.
247 <group title="Common Columns">
248 <column name="external_ids">
249 See <em>External IDs</em> at the beginning of this document.
254 <table name="ACL" title="Access Control List (ACL) rule">
256 Each row in this table represents one ACL rule for a logical switch
257 that points to it through its <ref column="acls"/> column. The <ref
258 column="action"/> column for the highest-<ref column="priority"/>
259 matching row in this table determines a packet's treatment. If no row
260 matches, packets are allowed by default. (Default-deny treatment is
261 possible: add a rule with <ref column="priority"/> 1, <code>1</code> as
262 <ref column="match"/>, and <code>deny</code> as <ref column="action"/>.)
265 <column name="priority">
267 The ACL rule's priority. Rules with numerically higher priority
268 take precedence over those with lower. If two ACL rules with
269 the same priority both match, then the one actually applied to a
274 Return traffic from an <code>allow-related</code> flow is always
275 allowed and cannot be changed through an ACL.
279 <column name="direction">
280 <p>Direction of the traffic to which this rule should apply:</p>
283 <code>from-lport</code>: Used to implement filters on traffic
284 arriving from a logical port. These rules are applied to the
285 logical switch's ingress pipeline.
288 <code>to-lport</code>: Used to implement filters on traffic
289 forwarded to a logical port. These rules are applied to the
290 logical switch's egress pipeline.
295 <column name="match">
297 The packets that the ACL should match, in the same expression
298 language used for the <ref column="match" table="Logical_Flow"
299 db="OVN_Southbound"/> column in the OVN Southbound database's
300 <ref table="Logical_Flow" db="OVN_Southbound"/> table. The
301 <code>outport</code> logical port is only available in the
302 <code>to-lport</code> direction (the <code>inport</code> is
303 available in both directions).
307 By default all traffic is allowed. When writing a more
308 restrictive policy, it is important to remember to allow flows
309 such as ARP and IPv6 neighbor discovery packets.
313 In logical switches connected to logical routers, the special
314 port name <code>ROUTER</code> refers to the logical router port.
318 <column name="action">
319 <p>The action to take when the ACL rule matches:</p>
322 <code>allow</code>: Forward the packet.
326 <code>allow-related</code>: Forward the packet and related traffic
327 (e.g. inbound replies to an outbound connection).
331 <code>drop</code>: Silently drop the packet.
335 <code>reject</code>: Drop the packet, replying with a RST for TCP or
336 ICMP unreachable message for other IP-based protocols.
337 <code>Not implemented--currently treated as drop</code>
344 If set to <code>true</code>, packets that match the ACL will trigger a
345 log message on the transport node or nodes that perform ACL processing.
346 Logging may be combined with any <ref column="action"/>.
350 Logging is not yet implemented.
354 <group title="Common Columns">
355 <column name="external_ids">
356 See <em>External IDs</em> at the beginning of this document.
361 <table name="Logical_Router" title="L3 logical router">
363 Each row represents one L3 logical router.
368 A name for the logical router. This name has no special meaning or purpose
369 other than to provide convenience for human interaction with the ovn-nb
370 database. There is no requirement for the name to be unique. The
371 logical router's UUID should be used as the unique identifier.
375 <column name="ports">
376 The router's ports. This is a set of weak references, so a <ref
377 table="Logical_Switch"/> must also refer to any given <ref
378 table="Logical_Router_Port"/> or it will automatically be deleted.
381 <column name="default_gw">
382 IP address to use as default gateway, if any.
385 <group title="Common Columns">
386 <column name="external_ids">
387 See <em>External IDs</em> at the beginning of this document.
392 <table name="Logical_Router_Port" title="L3 logical router port">
394 A port within an L3 logical router.
398 A router port is always attached to a logical switch and to a logical
399 router. The former attachment, which is enforced by the database schema,
400 can be identified by finding the <ref table="Logical_Switch"/> row whose
401 <ref column="router_port" table="Logical_Switch"/> column points to the
402 router port. The latter attachment, which the database schema does not
403 enforce, can be identified by finding the <ref table="Logical_Router"/>
404 row whose <ref column="ports" table="Logical_Router"/> column includes
410 A name for the logical router port. This name has no special meaning or purpose
411 other than to provide convenience for human interaction with the ovn-nb
412 database. There is no requirement for the name to be unique. The
413 logical router port's UUID should be used as the unique identifier.
417 <column name="network">
418 The IP address of the router and the netmask. For example,
419 <code>192.168.0.1/24</code> indicates that the router's IP address is
420 192.168.0.1 and that packets destined to 192.168.0.<var>x</var> should be
425 The Ethernet address that belongs to this router port.
428 <group title="Common Columns">
429 <column name="external_ids">
430 See <em>External IDs</em> at the beginning of this document.