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 When this column is set to <code>localnet</code>, this logical port
120 represents a connection to a locally accessible network from each
121 <code>ovn-controller</code> instance. A logical switch can only have a
122 single <code>localnet</code> port attached and at most one regular
123 logical port. This is used to model direct connectivity to an existing
128 <column name="options">
130 This column provides key/value settings specific to the logical port
131 <ref column="type"/>.
135 When <ref column="type"/> is set to <code>localnet</code>, you must set
136 the option <code>network_name</code>. <code>ovn-controller</code> uses
137 local configuration to determine exactly how to connect to this locally
142 <column name="parent_name">
143 When <ref column="name"/> identifies the interface of a container
144 spawned inside a tenant VM, this column represents the VM interface
145 through which the container interface sends its network traffic.
146 The name used here must match those used in the <ref key="iface-id"
147 table="Interface" column="external_ids" db="Open_vSwitch"/> in the
148 <ref db="Open_vSwitch"/> table, because hypervisors in this case use
149 <ref key="iface-id" table="Interface" column="external_ids"
150 db="Open_vSwitch"/> as a lookup key to identify the network interface
155 When <ref column="name"/> identifies the interface of a container
156 spawned inside a tenant VM, this column identifies the VLAN tag in
157 the network traffic associated with that container's network interface.
158 When there are multiple container interfaces inside a VM, all of
159 them send their network traffic through a single VM network interface and
160 this value helps OVN identify the correct container interface.
164 This column is populated by <code>ovn-northd</code>, rather than by
165 the CMS plugin as is most of this database. When a logical port is bound
166 to a physical location in the OVN Southbound database <ref
167 db="OVN_Southbound" table="Binding"/> table, <code>ovn-northd</code>
168 sets this column to <code>true</code>; otherwise, or if the port
169 becomes unbound later, it sets it to <code>false</code>. This
170 allows the CMS to wait for a VM's (or container's) networking to
171 become active before it allows the VM (or container) to start.
174 <column name="enabled">
175 This column is used to administratively set port state. If this column is
176 empty or is set to <code>true</code>, the port is enabled. If this column
177 is set to <code>false</code>, the port is disabled. A disabled port has all
178 ingress and egress traffic dropped.
182 The logical port's own Ethernet address or addresses, each in the form
183 <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
184 Like a physical Ethernet NIC, a logical port ordinarily has a single
185 fixed Ethernet address. The string <code>unknown</code> is also allowed
186 to indicate that the logical port has an unknown set of (additional)
190 <column name="port_security">
192 A set of L2 (Ethernet) addresses
193 from which the logical port is allowed to send packets and to which it
194 is allowed to receive packets. If this column is empty, all addresses
195 are permitted. Logical ports are always allowed to receive packets
196 addressed to multicast and broadcast addresses.
200 Each member of the set is an Ethernet address in the form
201 <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
205 This specification will be extended to support L3 port security.
209 <group title="Common Columns">
210 <column name="external_ids">
211 See <em>External IDs</em> at the beginning of this document.
216 <table name="ACL" title="Access Control List (ACL) rule">
218 Each row in this table represents one ACL rule for a logical switch
219 that points to it through its <ref column="acls"/> column. The <ref
220 column="action"/> column for the highest-<ref column="priority"/>
221 matching row in this table determines a packet's treatment. If no row
222 matches, packets are allowed by default. (Default-deny treatment is
223 possible: add a rule with <ref column="priority"/> 1, <code>1</code> as
224 <ref column="match"/>, and <code>deny</code> as <ref column="action"/>.)
227 <column name="priority">
228 The ACL rule's priority. Rules with numerically higher priority take
229 precedence over those with lower. If two ACL rules with the same
230 priority both match, then the one actually applied to a packet is
234 <column name="match">
235 The packets that the ACL should match, in the same expression language
236 used for the <ref column="match" table="Logical_Flow"
237 db="OVN_Southbound"/> column in the OVN Southbound database's <ref
238 table="Logical_Flow" db="OVN_Southbound"/> table. Match
239 <code>inport</code> and <code>outport</code> against names of logical
240 ports within <ref column="lswitch"/> to implement ingress and egress
241 ACLs, respectively. In logical switches connected to logical routers,
242 the special port name <code>ROUTER</code> refers to the logical router
246 <column name="action">
247 <p>The action to take when the ACL rule matches:</p>
251 <code>allow</code>: Forward the packet.
255 <code>allow-related</code>: Forward the packet and related traffic
256 (e.g. inbound replies to an outbound connection).
260 <code>drop</code>: Silently drop the packet.
264 <code>reject</code>: Drop the packet, replying with a RST for TCP or
265 ICMP unreachable message for other IP-based protocols.
270 Only <code>allow</code> and <code>drop</code> are implemented:
271 <code>allow-related</code> is currently treated as <code>allow</code>,
272 and <code>reject</code> as <code>drop</code>.
278 If set to <code>true</code>, packets that match the ACL will trigger a
279 log message on the transport node or nodes that perform ACL processing.
280 Logging may be combined with any <ref column="action"/>.
284 Logging is not yet implemented.
288 <group title="Common Columns">
289 <column name="external_ids">
290 See <em>External IDs</em> at the beginning of this document.
295 <table name="Logical_Router" title="L3 logical router">
297 Each row represents one L3 logical router.
302 A name for the logical router. This name has no special meaning or purpose
303 other than to provide convenience for human interaction with the ovn-nb
304 database. There is no requirement for the name to be unique. The
305 logical router's UUID should be used as the unique identifier.
309 <column name="ports">
310 The router's ports. This is a set of weak references, so a <ref
311 table="Logical_Switch"/> must also refer to any given <ref
312 table="Logical_Router_Port"/> or it will automatically be deleted.
315 <column name="default_gw">
316 IP address to use as default gateway, if any.
319 <group title="Common Columns">
320 <column name="external_ids">
321 See <em>External IDs</em> at the beginning of this document.
326 <table name="Logical_Router_Port" title="L3 logical router port">
328 A port within an L3 logical router.
332 A router port is always attached to a logical switch and to a logical
333 router. The former attachment, which is enforced by the database schema,
334 can be identified by finding the <ref table="Logical_Switch"/> row whose
335 <ref column="router_port" table="Logical_Switch"/> column points to the
336 router port. The latter attachment, which the database schema does not
337 enforce, can be identified by finding the <ref table="Logical_Router"/>
338 row whose <ref column="ports" table="Logical_Router"/> column includes
344 A name for the logical router port. This name has no special meaning or purpose
345 other than to provide convenience for human interaction with the ovn-nb
346 database. There is no requirement for the name to be unique. The
347 logical router port's UUID should be used as the unique identifier.
351 <column name="network">
352 The IP address of the router and the netmask. For example,
353 <code>192.168.0.1/24</code> indicates that the router's IP address is
354 192.168.0.1 and that packets destined to 192.168.0.<var>x</var> should be
359 The Ethernet address that belongs to this router port.
362 <group title="Common Columns">
363 <column name="external_ids">
364 See <em>External IDs</em> at the beginning of this document.