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. A given switch's ports are
36 the <ref table="Logical_Port"/> rows whose <ref table="Logical_Port"
37 column="lswitch"/> column points to its row.
42 A name for the logical switch. This name has no special meaning or purpose
43 other than to provide convenience for human interaction with the ovn-nb
44 database. There is no requirement for the name to be unique. The
45 logical switch's UUID should be used as the unique identifier.
49 <column name="router_port">
51 The router port to which this logical switch is connected, or empty if
52 this logical switch is not connected to any router. A switch may be
53 connected to at most one logical router, but this is not a significant
54 restriction because logical routers may be connected into arbitrary
59 <group title="Common Columns">
60 <column name="external_ids">
61 See <em>External IDs</em> at the beginning of this document.
66 <table name="Logical_Port" title="L2 logical switch port">
68 A port within an L2 logical switch.
71 <column name="lswitch">
72 The logical switch to which the logical port is connected.
77 The logical port name.
81 For entities (VMs or containers) that are spawned in the hypervisor,
82 the name used here must match those used in the <ref key="iface-id"
83 table="Interface" column="external_ids" db="Open_vSwitch"/> in the
84 <ref db="Open_vSwitch"/> database's <ref table="Interface"
85 db="Open_vSwitch"/> table, because hypervisors use <ref key="iface-id"
86 table="Interface" column="external_ids" db="Open_vSwitch"/> as a lookup
87 key to identify the network interface of that entity.
91 For containers that are spawned inside a VM, the name can be
92 any unique identifier. In such a case, <ref column="parent_name"/>
97 <column name="parent_name">
98 When <ref column="name"/> identifies the interface of a container
99 spawned inside a tenant VM, this column represents the VM interface
100 through which the container interface sends its network traffic.
101 The name used here must match those used in the <ref key="iface-id"
102 table="Interface" column="external_ids" db="Open_vSwitch"/> in the
103 <ref db="Open_vSwitch"/> table, because hypervisors in this case use
104 <ref key="iface-id" table="Interface" column="external_ids"
105 db="Open_vSwitch"/> as a lookup key to identify the network interface
110 When <ref column="name"/> identifies the interface of a container
111 spawned inside a tenant VM, this column identifies the VLAN tag in
112 the network traffic associated with that container's network interface.
113 When there are multiple container interfaces inside a VM, all of
114 them send their network traffic through a single VM network interface and
115 this value helps OVN identify the correct container interface.
119 This column is populated by <code>ovn-northd</code>, rather than by
120 the CMS plugin as is most of this database. When a logical port is bound
121 to a physical location in the OVN Southbound database <ref
122 db="OVN_Southbound" table="Bindings"/> table, <code>ovn-northd</code>
123 sets this column to <code>true</code>; otherwise, or if the port
124 becomes unbound later, it sets it to <code>false</code>. This
125 allows the CMS to wait for a VM's (or container's) networking to
126 become active before it allows the VM (or container) to start.
130 The logical port's own Ethernet address or addresses, each in the form
131 <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
132 Like a physical Ethernet NIC, a logical port ordinarily has a single
133 fixed Ethernet address. The string <code>unknown</code> is also allowed
134 to indicate that the logical port has an unknown set of (additional)
138 <column name="port_security">
140 A set of L2 (Ethernet) or L3 (IPv4 or IPv6) addresses or L2+L3 pairs
141 from which the logical port is allowed to send packets and to which it
142 is allowed to receive packets. If this column is empty, all addresses
147 Exact syntax is TBD. One could simply use comma- or
148 space-separated L2 and L3 addresses in each set member, or
149 replace this by a subset of the general-purpose expression
150 language used for the <ref column="match" table="Pipeline"
151 db="OVN_Southbound"/> column in the OVN Southbound database's
152 <ref table="Pipeline" db="OVN_Southbound"/> table.
156 <group title="Common Columns">
157 <column name="external_ids">
158 See <em>External IDs</em> at the beginning of this document.
163 <table name="ACL" title="Access Control List (ACL) rule">
165 Each row in this table represents one ACL rule for the logical switch in
166 its <ref column="lswitch"/> column. The <ref column="action"/> column for
167 the highest-<ref column="priority"/> matching row in this table
168 determines a packet's treatment. If no row matches, packets are allowed
169 by default. (Default-deny treatment is possible: add a rule with <ref
170 column="priority"/> 0, <code>true</code> as <ref column="match"/>, and
171 <code>deny</code> as <ref column="action"/>.)
174 <column name="lswitch">
175 The switch to which the ACL rule applies. The expression in the
176 <ref column="match"/> column may match against logical ports
180 <column name="priority">
181 The ACL rule's priority. Rules with numerically higher priority take
182 precedence over those with lower. If two ACL rules with the same
183 priority both match, then the one actually applied to a packet is
187 <column name="match">
188 The packets that the ACL should match, in the same expression
189 language used for the <ref column="match" table="Pipeline"
190 db="OVN_Southbound"/> column in the OVN Southbound database's <ref
191 table="Pipeline" db="OVN_Southbound"/> table. Match
192 <code>inport</code> and <code>outport</code> against names of
193 logical ports within <ref column="lswitch"/> to implement ingress
194 and egress ACLs, respectively. In logical switches connected to
195 logical routers, the special port name <code>ROUTER</code> refers
196 to the logical router port.
199 <column name="action">
200 <p>The action to take when the ACL rule matches:</p>
204 <code>allow</code>: Forward the packet.
208 <code>allow-related</code>: Forward the packet and related traffic
209 (e.g. inbound replies to an outbound connection).
213 <code>drop</code>: Silently drop the packet.
217 <code>reject</code>: Drop the packet, replying with a RST for TCP or
218 ICMP unreachable message for other IP-based protocols.
224 If set to <code>true</code>, packets that match the ACL will trigger a
225 log message on the transport node or nodes that perform ACL processing.
226 Logging may be combined with any <ref column="action"/>.
229 <group title="Common Columns">
230 <column name="external_ids">
231 See <em>External IDs</em> at the beginning of this document.
236 <table name="Logical_Router" title="L3 logical router">
238 Each row represents one L3 logical router. A given router's ports are
239 the <ref table="Logical_Router_Port"/> rows whose <ref
240 table="Logical_Router_Port" column="router"/> column points to its row.
244 The logical router's own IP address. The logical router uses this
245 address for ICMP replies (e.g. network unreachable messages) and other
246 traffic that it originates and responds to traffic destined to this
247 address (e.g. ICMP echo requests).
250 <column name="default_gw">
251 IP address to use as default gateway, if any.
254 <group title="Common Columns">
255 <column name="external_ids">
256 See <em>External IDs</em> at the beginning of this document.
261 <table name="Logical_Router_Port" title="L3 logical router port">
263 A port within an L3 logical router.
267 A router port is always attached to a switch port. The connection can be
268 identified by following the <ref column="router_port"
269 table="Logical_Port"/> column from an appropriate <ref
270 table="Logical_Port"/> row.
273 <column name="router">
274 The router to which the port belongs.
277 <column name="network">
278 The IP network and netmask of the network on the router port. Used for
283 The Ethernet address that belongs to this router port.
286 <group title="Common Columns">
287 <column name="external_ids">
288 See <em>External IDs</em> at the beginning of this document.