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 column
115 blank maintains the default logical port behavior.
119 There are no other logical port types implemented yet.
123 <column name="options">
124 This column provides key/value settings specific to the logical port
125 <ref column="type"/>.
128 <column name="parent_name">
129 When <ref column="name"/> identifies the interface of a container
130 spawned inside a tenant VM, this column represents the VM interface
131 through which the container interface sends its network traffic.
132 The name used here must match those used in the <ref key="iface-id"
133 table="Interface" column="external_ids" db="Open_vSwitch"/> in the
134 <ref db="Open_vSwitch"/> table, because hypervisors in this case use
135 <ref key="iface-id" table="Interface" column="external_ids"
136 db="Open_vSwitch"/> as a lookup key to identify the network interface
141 When <ref column="name"/> identifies the interface of a container
142 spawned inside a tenant VM, this column identifies the VLAN tag in
143 the network traffic associated with that container's network interface.
144 When there are multiple container interfaces inside a VM, all of
145 them send their network traffic through a single VM network interface and
146 this value helps OVN identify the correct container interface.
150 This column is populated by <code>ovn-northd</code>, rather than by
151 the CMS plugin as is most of this database. When a logical port is bound
152 to a physical location in the OVN Southbound database <ref
153 db="OVN_Southbound" table="Binding"/> table, <code>ovn-northd</code>
154 sets this column to <code>true</code>; otherwise, or if the port
155 becomes unbound later, it sets it to <code>false</code>. This
156 allows the CMS to wait for a VM's (or container's) networking to
157 become active before it allows the VM (or container) to start.
160 <column name="enabled">
161 This column is used to administratively set port state. If this column is
162 empty or is set to <code>true</code>, the port is enabled. If this column
163 is set to <code>false</code>, the port is disabled. A disabled port has all
164 ingress and egress traffic dropped.
168 The logical port's own Ethernet address or addresses, each in the form
169 <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
170 Like a physical Ethernet NIC, a logical port ordinarily has a single
171 fixed Ethernet address. The string <code>unknown</code> is also allowed
172 to indicate that the logical port has an unknown set of (additional)
176 <column name="port_security">
178 A set of L2 (Ethernet) addresses
179 from which the logical port is allowed to send packets and to which it
180 is allowed to receive packets. If this column is empty, all addresses
181 are permitted. Logical ports are always allowed to receive packets
182 addressed to multicast and broadcast addresses.
186 Each member of the set is an Ethernet address in the form
187 <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
191 This specification will be extended to support L3 port security.
195 <group title="Common Columns">
196 <column name="external_ids">
197 See <em>External IDs</em> at the beginning of this document.
202 <table name="ACL" title="Access Control List (ACL) rule">
204 Each row in this table represents one ACL rule for a logical switch
205 that points to it through its <ref column="acls"/> column. The <ref
206 column="action"/> column for the highest-<ref column="priority"/>
207 matching row in this table determines a packet's treatment. If no row
208 matches, packets are allowed by default. (Default-deny treatment is
209 possible: add a rule with <ref column="priority"/> 1, <code>1</code> as
210 <ref column="match"/>, and <code>deny</code> as <ref column="action"/>.)
213 <column name="priority">
214 The ACL rule's priority. Rules with numerically higher priority take
215 precedence over those with lower. If two ACL rules with the same
216 priority both match, then the one actually applied to a packet is
220 <column name="match">
221 The packets that the ACL should match, in the same expression language
222 used for the <ref column="match" table="Logical_Flow"
223 db="OVN_Southbound"/> column in the OVN Southbound database's <ref
224 table="Logical_Flow" db="OVN_Southbound"/> table. Match
225 <code>inport</code> and <code>outport</code> against names of logical
226 ports within <ref column="lswitch"/> to implement ingress and egress
227 ACLs, respectively. In logical switches connected to logical routers,
228 the special port name <code>ROUTER</code> refers to the logical router
232 <column name="action">
233 <p>The action to take when the ACL rule matches:</p>
237 <code>allow</code>: Forward the packet.
241 <code>allow-related</code>: Forward the packet and related traffic
242 (e.g. inbound replies to an outbound connection).
246 <code>drop</code>: Silently drop the packet.
250 <code>reject</code>: Drop the packet, replying with a RST for TCP or
251 ICMP unreachable message for other IP-based protocols.
256 Only <code>allow</code> and <code>drop</code> are implemented:
257 <code>allow-related</code> is currently treated as <code>allow</code>,
258 and <code>reject</code> as <code>drop</code>.
264 If set to <code>true</code>, packets that match the ACL will trigger a
265 log message on the transport node or nodes that perform ACL processing.
266 Logging may be combined with any <ref column="action"/>.
270 Logging is not yet implemented.
274 <group title="Common Columns">
275 <column name="external_ids">
276 See <em>External IDs</em> at the beginning of this document.
281 <table name="Logical_Router" title="L3 logical router">
283 Each row represents one L3 logical router.
288 A name for the logical router. This name has no special meaning or purpose
289 other than to provide convenience for human interaction with the ovn-nb
290 database. There is no requirement for the name to be unique. The
291 logical router's UUID should be used as the unique identifier.
295 <column name="ports">
296 The router's ports. This is a set of weak references, so a <ref
297 table="Logical_Switch"/> must also refer to any given <ref
298 table="Logical_Router_Port"/> or it will automatically be deleted.
301 <column name="default_gw">
302 IP address to use as default gateway, if any.
305 <group title="Common Columns">
306 <column name="external_ids">
307 See <em>External IDs</em> at the beginning of this document.
312 <table name="Logical_Router_Port" title="L3 logical router port">
314 A port within an L3 logical router.
318 A router port is always attached to a logical switch and to a logical
319 router. The former attachment, which is enforced by the database schema,
320 can be identified by finding the <ref table="Logical_Switch"/> row whose
321 <ref column="router_port" table="Logical_Switch"/> column points to the
322 router port. The latter attachment, which the database schema does not
323 enforce, can be identified by finding the <ref table="Logical_Router"/>
324 row whose <ref column="ports" table="Logical_Router"/> column includes
330 A name for the logical router port. This name has no special meaning or purpose
331 other than to provide convenience for human interaction with the ovn-nb
332 database. There is no requirement for the name to be unique. The
333 logical router port's UUID should be used as the unique identifier.
337 <column name="network">
338 The IP address of the router and the netmask. For example,
339 <code>192.168.0.1/24</code> indicates that the router's IP address is
340 192.168.0.1 and that packets destined to 192.168.0.<var>x</var> should be
345 The Ethernet address that belongs to this router port.
348 <group title="Common Columns">
349 <column name="external_ids">
350 See <em>External IDs</em> at the beginning of this document.