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"/>
111 <column name="parent_name">
112 When <ref column="name"/> identifies the interface of a container
113 spawned inside a tenant VM, this column represents the VM interface
114 through which the container interface sends its network traffic.
115 The name used here must match those used in the <ref key="iface-id"
116 table="Interface" column="external_ids" db="Open_vSwitch"/> in the
117 <ref db="Open_vSwitch"/> table, because hypervisors in this case use
118 <ref key="iface-id" table="Interface" column="external_ids"
119 db="Open_vSwitch"/> as a lookup key to identify the network interface
124 When <ref column="name"/> identifies the interface of a container
125 spawned inside a tenant VM, this column identifies the VLAN tag in
126 the network traffic associated with that container's network interface.
127 When there are multiple container interfaces inside a VM, all of
128 them send their network traffic through a single VM network interface and
129 this value helps OVN identify the correct container interface.
133 This column is populated by <code>ovn-northd</code>, rather than by
134 the CMS plugin as is most of this database. When a logical port is bound
135 to a physical location in the OVN Southbound database <ref
136 db="OVN_Southbound" table="Binding"/> table, <code>ovn-northd</code>
137 sets this column to <code>true</code>; otherwise, or if the port
138 becomes unbound later, it sets it to <code>false</code>. This
139 allows the CMS to wait for a VM's (or container's) networking to
140 become active before it allows the VM (or container) to start.
143 <column name="enabled">
144 This column is used to administratively set port state. If this column is
145 empty or is set to <code>true</code>, the port is enabled. If this column
146 is set to <code>false</code>, the port is disabled. A disabled port has all
147 ingress and egress traffic dropped.
151 The logical port's own Ethernet address or addresses, each in the form
152 <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
153 Like a physical Ethernet NIC, a logical port ordinarily has a single
154 fixed Ethernet address. The string <code>unknown</code> is also allowed
155 to indicate that the logical port has an unknown set of (additional)
159 <column name="port_security">
161 A set of L2 (Ethernet) addresses
162 from which the logical port is allowed to send packets and to which it
163 is allowed to receive packets. If this column is empty, all addresses
164 are permitted. Logical ports are always allowed to receive packets
165 addressed to multicast and broadcast addresses.
169 Each member of the set is an Ethernet address in the form
170 <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
174 This specification will be extended to support L3 port security.
178 <group title="Common Columns">
179 <column name="external_ids">
180 See <em>External IDs</em> at the beginning of this document.
185 <table name="ACL" title="Access Control List (ACL) rule">
187 Each row in this table represents one ACL rule for a logical switch
188 that points to it through its <ref column="acls"/> column. The <ref
189 column="action"/> column for the highest-<ref column="priority"/>
190 matching row in this table determines a packet's treatment. If no row
191 matches, packets are allowed by default. (Default-deny treatment is
192 possible: add a rule with <ref column="priority"/> 1, <code>1</code> as
193 <ref column="match"/>, and <code>deny</code> as <ref column="action"/>.)
196 <column name="priority">
197 The ACL rule's priority. Rules with numerically higher priority take
198 precedence over those with lower. If two ACL rules with the same
199 priority both match, then the one actually applied to a packet is
203 <column name="match">
204 The packets that the ACL should match, in the same expression
205 language used for the <ref column="match" table="Pipeline"
206 db="OVN_Southbound"/> column in the OVN Southbound database's <ref
207 table="Pipeline" db="OVN_Southbound"/> table. Match
208 <code>inport</code> and <code>outport</code> against names of
209 logical ports within <ref column="lswitch"/> to implement ingress
210 and egress ACLs, respectively. In logical switches connected to
211 logical routers, the special port name <code>ROUTER</code> refers
212 to the logical router port.
215 <column name="action">
216 <p>The action to take when the ACL rule matches:</p>
220 <code>allow</code>: Forward the packet.
224 <code>allow-related</code>: Forward the packet and related traffic
225 (e.g. inbound replies to an outbound connection).
229 <code>drop</code>: Silently drop the packet.
233 <code>reject</code>: Drop the packet, replying with a RST for TCP or
234 ICMP unreachable message for other IP-based protocols.
239 Only <code>allow</code> and <code>drop</code> are implemented:
240 <code>allow-related</code> is currently treated as <code>allow</code>,
241 and <code>reject</code> as <code>drop</code>.
247 If set to <code>true</code>, packets that match the ACL will trigger a
248 log message on the transport node or nodes that perform ACL processing.
249 Logging may be combined with any <ref column="action"/>.
253 Logging is not yet implemented.
257 <group title="Common Columns">
258 <column name="external_ids">
259 See <em>External IDs</em> at the beginning of this document.
264 <table name="Logical_Router" title="L3 logical router">
266 Each row represents one L3 logical router.
269 <column name="ports">
270 The router's ports. This is a set of weak references, so a <ref
271 table="Logical_Switch"/> must also refer to any given <ref
272 table="Logical_Router_Port"/> or it will automatically be deleted.
276 The logical router's own IP address. The logical router uses this
277 address for ICMP replies (e.g. network unreachable messages) and other
278 traffic that it originates and responds to traffic destined to this
279 address (e.g. ICMP echo requests).
282 <column name="default_gw">
283 IP address to use as default gateway, if any.
286 <group title="Common Columns">
287 <column name="external_ids">
288 See <em>External IDs</em> at the beginning of this document.
293 <table name="Logical_Router_Port" title="L3 logical router port">
295 A port within an L3 logical router.
299 A router port is always attached to a logical switch and to a logical
300 router. The former attachment, which is enforced by the database schema,
301 can be identified by finding the <ref table="Logical_Switch"/> row whose
302 <ref column="router_port" table="Logical_Switch"/> column points to the
303 router port. The latter attachment, which the database schema does not
304 enforce, can be identified by finding the <ref table="Logical_Router"/>
305 row whose <ref column="ports" table="Logical_Router"/> column includes
309 <column name="network">
310 The IP network and netmask of the network on the router port. Used for
315 The Ethernet address that belongs to this router port.
318 <group title="Common Columns">
319 <column name="external_ids">
320 See <em>External IDs</em> at the beginning of this document.