1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
|
<?xml version="1.0" encoding="utf-8"?>
<database name="ovn-nb" title="OVN Northbound Database">
<p>
This database is the interface between OVN and the cloud management system
(CMS), such as OpenStack, running above it. The CMS produces almost all of
the contents of the database. The <code>ovn-northd</code> program
monitors the database contents, transforms it, and stores it into the <ref
db="OVN_Southbound"/> database.
</p>
<p>
We generally speak of ``the'' CMS, but one can imagine scenarios in
which multiple CMSes manage different parts of an OVN deployment.
</p>
<h2>External IDs</h2>
<p>
Each of the tables in this database contains a special column, named
<code>external_ids</code>. This column has the same form and purpose each
place it appears.
</p>
<dl>
<dt><code>external_ids</code>: map of string-string pairs</dt>
<dd>
Key-value pairs for use by the CMS. The CMS might use certain pairs, for
example, to identify entities in its own configuration that correspond to
those in this database.
</dd>
</dl>
<table name="Logical_Switch" title="L2 logical switch">
<p>
Each row represents one L2 logical switch.
</p>
<column name="name">
<p>
A name for the logical switch. This name has no special meaning or purpose
other than to provide convenience for human interaction with the ovn-nb
database. There is no requirement for the name to be unique. The
logical switch's UUID should be used as the unique identifier.
</p>
</column>
<column name="ports">
<p>
The logical ports connected to the logical switch.
</p>
<p>
It is an error for multiple logical switches to include the same
logical port.
</p>
</column>
<column name="router_port">
<p>
The router port to which this logical switch is connected, or empty if
this logical switch is not connected to any router. A switch may be
connected to at most one logical router, but this is not a significant
restriction because logical routers may be connected into arbitrary
topologies.
</p>
<p>
It is an error for multiple logical switches to refer to the same
router port.
</p>
</column>
<column name="acls">
Access control rules that apply to packets within the logical switch.
</column>
<group title="Common Columns">
<column name="external_ids">
See <em>External IDs</em> at the beginning of this document.
</column>
</group>
</table>
<table name="Logical_Port" title="L2 logical switch port">
<p>
A port within an L2 logical switch.
</p>
<column name="name">
<p>
The logical port name.
</p>
<p>
For entities (VMs or containers) that are spawned in the hypervisor,
the name used here must match those used in the <ref key="iface-id"
table="Interface" column="external_ids" db="Open_vSwitch"/> in the
<ref db="Open_vSwitch"/> database's <ref table="Interface"
db="Open_vSwitch"/> table, because hypervisors use <ref key="iface-id"
table="Interface" column="external_ids" db="Open_vSwitch"/> as a lookup
key to identify the network interface of that entity.
</p>
<p>
For containers that are spawned inside a VM, the name can be
any unique identifier. In such a case, <ref column="parent_name"/>
must be populated.
</p>
</column>
<column name="type">
<p>
Specify a type for this logical port. Logical ports can be used to model
other types of connectivity into an OVN logical switch. Leaving this
column blank maintains the default logical port behavior, which is
for a VM (or VIF) interface. The following other types are defined:
</p>
<dl>
<dt><code>localnet</code></dt>
<dd>A connection to a locally accessible network from each
<code>ovn-controller</code> instance. A logical switch can only
have a single <code>localnet</code> port attached and at most one
regular logical port. This is used to model direct connectivity
to an existing network.</dd>
</dl>
<dl>
<dt><code>vtep</code></dt>
<dd>A port to a logical switch on a VTEP gateway. In order
to get this port correctly recognized by the OVN controller, the
<ref column="options" table="Logical_Port"/>:<code>vtep-physical-switch</code>
and <ref column="options" table="Logical_Port"/>:<code>vtep-logical-switch</code>
must also be defined.</dd>
</dl>
</column>
<column name="options">
<p>
This column provides key/value settings specific to the logical port
<ref column="type"/>. The following options are defined:
</p>
<dl>
<dt><code>network_name</code></dt>
<dd>
Must be set when <ref column="type"/> is <code>localnet</code>.
<code>ovn-controller</code> uses local configuration to determine
exactly how to connect to this locally accessible network.
</dd>
</dl>
<dl>
<dt><code>vtep-physical-switch</code></dt>
<dd>
The name of the VTEP gateway. Must be set when
<ref column="type"/> is <code>vtep</code>.
</dd>
</dl>
<dl>
<dt><code>vtep-logical-switch</code></dt>
<dd>
A logical switch name connected by the VTEP gateway. Must be
set when <ref column="type"/> is <code>vtep</code>.
</dd>
</dl>
</column>
<column name="parent_name">
When <ref column="name"/> identifies the interface of a container
spawned inside a tenant VM, this column represents the VM interface
through which the container interface sends its network traffic.
The name used here must match those used in the <ref key="iface-id"
table="Interface" column="external_ids" db="Open_vSwitch"/> in the
<ref db="Open_vSwitch"/> table, because hypervisors in this case use
<ref key="iface-id" table="Interface" column="external_ids"
db="Open_vSwitch"/> as a lookup key to identify the network interface
of the tenant VM.
</column>
<column name="tag">
<p>
When <ref column="type"/> is empty and <ref column="name"/> identifies
the interface of a container spawned inside a tenant VM, this column
identifies the VLAN tag in the network traffic associated with that
container's network interface. When there are multiple container
interfaces inside a VM, all of them send their network traffic through a
single VM network interface and this value helps OVN identify the correct
container interface.
</p>
<p>
When <ref column="type"/> is set to <code>localnet</code>, this can be
set to indicate that the port represents a connection to a specific
VLAN on a locally accessible network. The VLAN ID is used to match
incoming traffic and is also added to outgoing traffic.
</p>
</column>
<column name="up">
This column is populated by <code>ovn-northd</code>, rather than by
the CMS plugin as is most of this database. When a logical port is bound
to a physical location in the OVN Southbound database <ref
db="OVN_Southbound" table="Binding"/> table, <code>ovn-northd</code>
sets this column to <code>true</code>; otherwise, or if the port
becomes unbound later, it sets it to <code>false</code>. This
allows the CMS to wait for a VM's (or container's) networking to
become active before it allows the VM (or container) to start.
</column>
<column name="enabled">
This column is used to administratively set port state. If this column is
empty or is set to <code>true</code>, the port is enabled. If this column
is set to <code>false</code>, the port is disabled. A disabled port has all
ingress and egress traffic dropped.
</column>
<column name="addresses">
The logical port's own Ethernet address or addresses, each in the form
<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
Like a physical Ethernet NIC, a logical port ordinarily has a single
fixed Ethernet address. The string <code>unknown</code> is also allowed
to indicate that the logical port has an unknown set of (additional)
source addresses.
</column>
<column name="port_security">
<p>
A set of L2 (Ethernet) addresses
from which the logical port is allowed to send packets and to which it
is allowed to receive packets. If this column is empty, all addresses
are permitted. Logical ports are always allowed to receive packets
addressed to multicast and broadcast addresses.
</p>
<p>
Each member of the set is an Ethernet address in the form
<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
</p>
<p>
This specification will be extended to support L3 port security.
</p>
</column>
<group title="Common Columns">
<column name="external_ids">
See <em>External IDs</em> at the beginning of this document.
</column>
</group>
</table>
<table name="ACL" title="Access Control List (ACL) rule">
<p>
Each row in this table represents one ACL rule for a logical switch
that points to it through its <ref column="acls"/> column. The <ref
column="action"/> column for the highest-<ref column="priority"/>
matching row in this table determines a packet's treatment. If no row
matches, packets are allowed by default. (Default-deny treatment is
possible: add a rule with <ref column="priority"/> 1, <code>1</code> as
<ref column="match"/>, and <code>deny</code> as <ref column="action"/>.)
</p>
<column name="priority">
<p>
The ACL rule's priority. Rules with numerically higher priority
take precedence over those with lower. If two ACL rules with
the same priority both match, then the one actually applied to a
packet is undefined.
</p>
<p>
Return traffic from an <code>allow-related</code> flow is always
allowed and cannot be changed through an ACL.
</p>
</column>
<column name="direction">
<p>Direction of the traffic to which this rule should apply:</p>
<ul>
<li>
<code>from-lport</code>: Used to implement filters on traffic
arriving from a logical port. These rules are applied to the
logical switch's ingress pipeline.
</li>
<li>
<code>to-lport</code>: Used to implement filters on traffic
forwarded to a logical port. These rules are applied to the
logical switch's egress pipeline.
</li>
</ul>
</column>
<column name="match">
<p>
The packets that the ACL should match, in the same expression
language used for the <ref column="match" table="Logical_Flow"
db="OVN_Southbound"/> column in the OVN Southbound database's
<ref table="Logical_Flow" db="OVN_Southbound"/> table. The
<code>outport</code> logical port is only available in the
<code>to-lport</code> direction (the <code>inport</code> is
available in both directions).
</p>
<p>
By default all traffic is allowed. When writing a more
restrictive policy, it is important to remember to allow flows
such as ARP and IPv6 neighbor discovery packets.
</p>
<p>
In logical switches connected to logical routers, the special
port name <code>ROUTER</code> refers to the logical router port.
</p>
</column>
<column name="action">
<p>The action to take when the ACL rule matches:</p>
<ul>
<li>
<code>allow</code>: Forward the packet.
</li>
<li>
<code>allow-related</code>: Forward the packet and related traffic
(e.g. inbound replies to an outbound connection).
</li>
<li>
<code>drop</code>: Silently drop the packet.
</li>
<li>
<code>reject</code>: Drop the packet, replying with a RST for TCP or
ICMP unreachable message for other IP-based protocols.
<code>Not implemented--currently treated as drop</code>
</li>
</ul>
</column>
<column name="log">
<p>
If set to <code>true</code>, packets that match the ACL will trigger a
log message on the transport node or nodes that perform ACL processing.
Logging may be combined with any <ref column="action"/>.
</p>
<p>
Logging is not yet implemented.
</p>
</column>
<group title="Common Columns">
<column name="external_ids">
See <em>External IDs</em> at the beginning of this document.
</column>
</group>
</table>
<table name="Logical_Router" title="L3 logical router">
<p>
Each row represents one L3 logical router.
</p>
<column name="name">
<p>
A name for the logical router. This name has no special meaning or purpose
other than to provide convenience for human interaction with the ovn-nb
database. There is no requirement for the name to be unique. The
logical router's UUID should be used as the unique identifier.
</p>
</column>
<column name="ports">
The router's ports.
</column>
<column name="default_gw">
IP address to use as default gateway, if any.
</column>
<group title="Common Columns">
<column name="external_ids">
See <em>External IDs</em> at the beginning of this document.
</column>
</group>
</table>
<table name="Logical_Router_Port" title="L3 logical router port">
<p>
A port within an L3 logical router.
</p>
<p>
Exactly one <ref table="Logical_Router"/> row must reference a given
logical router port.
</p>
<column name="name">
<p>
A name for the logical router port. This name has no special meaning or purpose
other than to provide convenience for human interaction with the ovn-nb
database. There is no requirement for the name to be unique. The
logical router port's UUID should be used as the unique identifier.
</p>
</column>
<column name="network">
The IP address of the router and the netmask. For example,
<code>192.168.0.1/24</code> indicates that the router's IP address is
192.168.0.1 and that packets destined to 192.168.0.<var>x</var> should be
routed to this port.
</column>
<column name="mac">
The Ethernet address that belongs to this router port.
</column>
<group title="Attachment">
<p>
A given router port serves one of two purposes:
</p>
<ul>
<li>
To attach a logical switch to a logical router. A logical router
port of this type is referenced by exactly the <ref
column="router_port" table="Logical_Switch"/> column in exactly one
<ref table="Logical_Switch"/> row. The <ref column="peer"/> column
is empty.
</li>
<li>
To connect one logical router to another. This requires a pair of
logical router ports, each connected to a different router. Each
router port in the pair specifies the other in its <ref
column="peer"/> column. No <ref table="Logical_Switch"/> refers to
the router port.
</li>
</ul>
<column name="peer">
<p>
For a router port used to connect two logical routers, this
identifies the other router port in the pair.
</p>
<p>
For a router port attached to a logical switch, this column is empty.
</p>
</column>
</group>
<group title="Common Columns">
<column name="external_ids">
See <em>External IDs</em> at the beginning of this document.
</column>
</group>
</table>
</database>
|