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
183 When <ref column="name"/> identifies the interface of a container
184 spawned inside a tenant VM, this column identifies the VLAN tag in
185 the network traffic associated with that container's network interface.
186 When there are multiple container interfaces inside a VM, all of
187 them send their network traffic through a single VM network interface and
188 this value helps OVN identify the correct container interface.
192 This column is populated by <code>ovn-northd</code>, rather than by
193 the CMS plugin as is most of this database. When a logical port is bound
194 to a physical location in the OVN Southbound database <ref
195 db="OVN_Southbound" table="Binding"/> table, <code>ovn-northd</code>
196 sets this column to <code>true</code>; otherwise, or if the port
197 becomes unbound later, it sets it to <code>false</code>. This
198 allows the CMS to wait for a VM's (or container's) networking to
199 become active before it allows the VM (or container) to start.
202 <column name="enabled">
203 This column is used to administratively set port state. If this column is
204 empty or is set to <code>true</code>, the port is enabled. If this column
205 is set to <code>false</code>, the port is disabled. A disabled port has all
206 ingress and egress traffic dropped.
210 The logical port's own Ethernet address or addresses, each in the form
211 <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
212 Like a physical Ethernet NIC, a logical port ordinarily has a single
213 fixed Ethernet address. The string <code>unknown</code> is also allowed
214 to indicate that the logical port has an unknown set of (additional)
218 <column name="port_security">
220 A set of L2 (Ethernet) addresses
221 from which the logical port is allowed to send packets and to which it
222 is allowed to receive packets. If this column is empty, all addresses
223 are permitted. Logical ports are always allowed to receive packets
224 addressed to multicast and broadcast addresses.
228 Each member of the set is an Ethernet address in the form
229 <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
233 This specification will be extended to support L3 port security.
237 <group title="Common Columns">
238 <column name="external_ids">
239 See <em>External IDs</em> at the beginning of this document.
244 <table name="ACL" title="Access Control List (ACL) rule">
246 Each row in this table represents one ACL rule for a logical switch
247 that points to it through its <ref column="acls"/> column. The <ref
248 column="action"/> column for the highest-<ref column="priority"/>
249 matching row in this table determines a packet's treatment. If no row
250 matches, packets are allowed by default. (Default-deny treatment is
251 possible: add a rule with <ref column="priority"/> 1, <code>1</code> as
252 <ref column="match"/>, and <code>deny</code> as <ref column="action"/>.)
255 <column name="priority">
257 The ACL rule's priority. Rules with numerically higher priority
258 take precedence over those with lower. If two ACL rules with
259 the same priority both match, then the one actually applied to a
264 Return traffic from an <code>allow-related</code> flow is always
265 allowed and cannot be changed through an ACL.
269 <column name="direction">
270 <p>Direction of the traffic to which this rule should apply:</p>
273 <code>from-lport</code>: Used to implement filters on traffic
274 arriving from a logical port. These rules are applied to the
275 logical switch's ingress pipeline.
278 <code>to-lport</code>: Used to implement filters on traffic
279 forwarded to a logical port. These rules are applied to the
280 logical switch's egress pipeline.
285 <column name="match">
287 The packets that the ACL should match, in the same expression
288 language used for the <ref column="match" table="Logical_Flow"
289 db="OVN_Southbound"/> column in the OVN Southbound database's
290 <ref table="Logical_Flow" db="OVN_Southbound"/> table. The
291 <code>outport</code> logical port is only available in the
292 <code>to-lport</code> direction (the <code>inport</code> is
293 available in both directions).
297 By default all traffic is allowed. When writing a more
298 restrictive policy, it is important to remember to allow flows
299 such as ARP and IPv6 neighbor discovery packets.
303 In logical switches connected to logical routers, the special
304 port name <code>ROUTER</code> refers to the logical router port.
308 <column name="action">
309 <p>The action to take when the ACL rule matches:</p>
312 <code>allow</code>: Forward the packet.
316 <code>allow-related</code>: Forward the packet and related traffic
317 (e.g. inbound replies to an outbound connection).
321 <code>drop</code>: Silently drop the packet.
325 <code>reject</code>: Drop the packet, replying with a RST for TCP or
326 ICMP unreachable message for other IP-based protocols.
327 <code>Not implemented--currently treated as drop</code>
334 If set to <code>true</code>, packets that match the ACL will trigger a
335 log message on the transport node or nodes that perform ACL processing.
336 Logging may be combined with any <ref column="action"/>.
340 Logging is not yet implemented.
344 <group title="Common Columns">
345 <column name="external_ids">
346 See <em>External IDs</em> at the beginning of this document.
351 <table name="Logical_Router" title="L3 logical router">
353 Each row represents one L3 logical router.
358 A name for the logical router. This name has no special meaning or purpose
359 other than to provide convenience for human interaction with the ovn-nb
360 database. There is no requirement for the name to be unique. The
361 logical router's UUID should be used as the unique identifier.
365 <column name="ports">
366 The router's ports. This is a set of weak references, so a <ref
367 table="Logical_Switch"/> must also refer to any given <ref
368 table="Logical_Router_Port"/> or it will automatically be deleted.
371 <column name="default_gw">
372 IP address to use as default gateway, if any.
375 <group title="Common Columns">
376 <column name="external_ids">
377 See <em>External IDs</em> at the beginning of this document.
382 <table name="Logical_Router_Port" title="L3 logical router port">
384 A port within an L3 logical router.
388 A router port is always attached to a logical switch and to a logical
389 router. The former attachment, which is enforced by the database schema,
390 can be identified by finding the <ref table="Logical_Switch"/> row whose
391 <ref column="router_port" table="Logical_Switch"/> column points to the
392 router port. The latter attachment, which the database schema does not
393 enforce, can be identified by finding the <ref table="Logical_Router"/>
394 row whose <ref column="ports" table="Logical_Router"/> column includes
400 A name for the logical router port. This name has no special meaning or purpose
401 other than to provide convenience for human interaction with the ovn-nb
402 database. There is no requirement for the name to be unique. The
403 logical router port's UUID should be used as the unique identifier.
407 <column name="network">
408 The IP address of the router and the netmask. For example,
409 <code>192.168.0.1/24</code> indicates that the router's IP address is
410 192.168.0.1 and that packets destined to 192.168.0.<var>x</var> should be
415 The Ethernet address that belongs to this router port.
418 <group title="Common Columns">
419 <column name="external_ids">
420 See <em>External IDs</em> at the beginning of this document.