1 <?xml version="1.0" encoding="utf-8"?>
2 <database name="ovn-sb" title="OVN Southbound Database">
4 This database holds logical and physical configuration and state for the
5 Open Virtual Network (OVN) system to support virtual network abstraction.
6 For an introduction to OVN, please see <code>ovn-architecture</code>(7).
10 The OVN Southbound database sits at the center of the OVN
11 architecture. It is the one component that speaks both southbound
12 directly to all the hypervisors and gateways, via
13 <code>ovn-controller</code>, and northbound to the Cloud Management
14 System, via <code>ovn-northd</code>:
17 <h2>Database Structure</h2>
20 The OVN Southbound database contains three classes of data with
21 different properties, as described in the sections below.
24 <h3>Physical Network (PN) data</h3>
27 PN tables contain information about the chassis nodes in the system. This
28 contains all the information necessary to wire the overlay, such as IP
29 addresses, supported tunnel types, and security keys.
33 The amount of PN data is small (O(n) in the number of chassis) and it
34 changes infrequently, so it can be replicated to every chassis.
38 The <ref table="Chassis"/> table comprises the PN tables.
41 <h3>Logical Network (LN) data</h3>
44 LN tables contain the topology of logical switches and routers, ACLs,
45 firewall rules, and everything needed to describe how packets traverse a
46 logical network, represented as logical datapath flows (see Logical
47 Datapath Flows, below).
51 LN data may be large (O(n) in the number of logical ports, ACL rules,
52 etc.). Thus, to improve scaling, each chassis should receive only data
53 related to logical networks in which that chassis participates. Past
54 experience shows that in the presence of large logical networks, even
55 finer-grained partitioning of data, e.g. designing logical flows so that
56 only the chassis hosting a logical port needs related flows, pays off
57 scale-wise. (This is not necessary initially but it is worth bearing in
62 The LN is a slave of the cloud management system running northbound of OVN.
63 That CMS determines the entire OVN logical configuration and therefore the
64 LN's content at any given time is a deterministic function of the CMS's
65 configuration, although that happens indirectly via the OVN Northbound DB
66 and <code>ovn-northd</code>.
70 LN data is likely to change more quickly than PN data. This is especially
71 true in a container environment where VMs are created and destroyed (and
72 therefore added to and deleted from logical switches) quickly.
76 <ref table="Logical_Flow"/> and <ref table="Multicast_Group"/> contain LN
80 <h3>Bindings data</h3>
83 Bindings data link logical and physical components. They show the current
84 placement of logical components (such as VMs and VIFs) onto chassis, and
85 map logical entities to the values that represent them in tunnel
90 Bindings change frequently, at least every time a VM powers up or down
91 or migrates, and especially quickly in a container environment. The
92 amount of data per VM (or VIF) is small.
96 Each chassis is authoritative about the VMs and VIFs that it hosts at any
97 given time and can efficiently flood that state to a central location, so
98 the consistency needs are minimal.
102 The <ref table="Port_Binding"/> and <ref table="Datapath_Binding"/> tables
103 contain binding data.
106 <h2>Common Columns</h2>
109 Some tables contain a special column named <code>external_ids</code>. This
110 column has the same form and purpose each place that it appears, so we
111 describe it here to save space later.
115 <dt><code>external_ids</code>: map of string-string pairs</dt>
117 Key-value pairs for use by the software that manages the OVN Southbound
118 database rather than by <code>ovn-controller</code>. In particular,
119 <code>ovn-northd</code> can use key-value pairs in this column to relate
120 entities in the southbound database to higher-level entities (such as
121 entities in the OVN Northbound database). Individual key-value pairs in
122 this column may be documented in some cases to aid in understanding and
123 troubleshooting, but the reader should not mistake such documentation as
128 <table name="Chassis" title="Physical Network Hypervisor and Gateway Information">
130 Each row in this table represents a hypervisor or gateway (a chassis) in
131 the physical network (PN). Each chassis, via
132 <code>ovn-controller</code>, adds and updates its own row, and keeps a
133 copy of the remaining rows to determine how to reach other hypervisors.
137 When a chassis shuts down gracefully, it should remove its own row.
138 (This is not critical because resources hosted on the chassis are equally
139 unreachable regardless of whether the row is present.) If a chassis
140 shuts down permanently without removing its row, some kind of manual or
141 automatic cleanup is eventually needed; we can devise a process for that
146 A chassis name, taken from <ref key="system-id" table="Open_vSwitch"
147 column="external_ids" db="Open_vSwitch"/> in the Open_vSwitch
148 database's <ref table="Open_vSwitch" db="Open_vSwitch"/> table. OVN does
149 not prescribe a particular format for chassis names.
152 <group title="Encapsulation Configuration">
154 OVN uses encapsulation to transmit logical dataplane packets
158 <column name="encaps">
159 Points to supported encapsulation configurations to transmit
160 logical dataplane packets to this chassis. Each entry is a <ref
161 table="Encap"/> record that describes the configuration.
165 <group title="Gateway Configuration">
167 A <dfn>gateway</dfn> is a chassis that forwards traffic between the
168 OVN-managed part of a logical network and a physical VLAN, extending a
169 tunnel-based logical network into a physical network. Gateways are
170 typically dedicated nodes that do not host VMs.
173 <column name="vtep_logical_switches">
174 Stores all vtep logical switch names connected by this gateway
180 <table name="Encap" title="Encapsulation Types">
182 The <ref column="encaps" table="Chassis"/> column in the <ref
183 table="Chassis"/> table refers to rows in this table to identify
184 how OVN may transmit logical dataplane packets to this chassis.
185 Each chassis, via <code>ovn-controller</code>(8), adds and updates
186 its own rows and keeps a copy of the remaining rows to determine
187 how to reach other chassis.
191 The encapsulation to use to transmit packets to this chassis.
192 Hypervisors must use either <code>geneve</code> or
193 <code>stt</code>. Gateways may use <code>vxlan</code>,
194 <code>geneve</code>, or <code>stt</code>.
197 <column name="options">
198 Options for configuring the encapsulation, e.g. IPsec parameters when
199 IPsec support is introduced. No options are currently defined.
203 The IPv4 address of the encapsulation tunnel endpoint.
207 <table name="Logical_Flow" title="Logical Network Flows">
209 Each row in this table represents one logical flow. The cloud management
210 system, via its OVN integration, populates this table with logical flows
211 that implement the L2 and L3 topology specified in the CMS configuration.
212 Each hypervisor, via <code>ovn-controller</code>, translates the logical
213 flows into OpenFlow flows specific to its hypervisor and installs them
218 Logical flows are expressed in an OVN-specific format, described here. A
219 logical datapath flow is much like an OpenFlow flow, except that the
220 flows are written in terms of logical ports and logical datapaths instead
221 of physical ports and physical datapaths. Translation between logical
222 and physical flows helps to ensure isolation between logical datapaths.
223 (The logical flow abstraction also allows the CMS to do less work, since
224 it does not have to separately compute and push out physical flows to each
229 The default action when no flow matches is to drop packets.
232 <p><em>Logical Life Cycle of a Packet</em></p>
235 This following description focuses on the life cycle of a packet through
236 a logical datapath, ignoring physical details of the implementation.
237 Please refer to <em>Life Cycle of a Packet</em> in
238 <code>ovn-architecture</code>(7) for the physical information.
242 The description here is written as if OVN itself executes these steps,
243 but in fact OVN (that is, <code>ovn-controller</code>) programs Open
244 vSwitch, via OpenFlow and OVSDB, to execute them on its behalf.
248 At a high level, OVN passes each packet through the logical datapath's
249 logical ingress pipeline, which may output the packet to one or more
250 logical port or logical multicast groups. For each such logical output
251 port, OVN passes the packet through the datapath's logical egress
252 pipeline, which may either drop the packet or deliver it to the
253 destination. Between the two pipelines, outputs to logical multicast
254 groups are expanded into logical ports, so that the egress pipeline only
255 processes a single logical output port at a time. Between the two
256 pipelines is also where, when necessary, OVN encapsulates a packet in a
257 tunnel (or tunnels) to transmit to remote hypervisors.
261 In more detail, to start, OVN searches the <ref table="Logical_Flow"/>
262 table for a row with correct <ref column="logical_datapath"/>, a <ref
263 column="pipeline"/> of <code>ingress</code>, a <ref column="table_id"/>
264 of 0, and a <ref column="match"/> that is true for the packet. If none
265 is found, OVN drops the packet. If OVN finds more than one, it chooses
266 the match with the highest <ref column="priority"/>. Then OVN executes
267 each of the actions specified in the row's <ref table="actions"/> column,
268 in the order specified. Some actions, such as those to modify packet
269 headers, require no further details. The <code>next</code> and
270 <code>output</code> actions are special.
274 The <code>next</code> action causes the above process to be repeated
275 recursively, except that OVN searches for <ref column="table_id"/> of 1
276 instead of 0. Similarly, any <code>next</code> action in a row found in
277 that table would cause a further search for a <ref column="table_id"/> of
278 2, and so on. When recursive processing completes, flow control returns
279 to the action following <code>next</code>.
283 The <code>output</code> action also introduces recursion. Its effect
284 depends on the current value of the <code>outport</code> field. Suppose
285 <code>outport</code> designates a logical port. First, OVN compares
286 <code>inport</code> to <code>outport</code>; if they are equal, it treats
287 the <code>output</code> as a no-op. In the common case, where they are
288 different, the packet enters the egress pipeline. This transition to the
289 egress pipeline discards register data, e.g. <code>reg0</code>
290 ... <code>reg5</code>, to achieve uniform behavior regardless of whether
291 the egress pipeline is on a different hypervisor (because registers
292 aren't preserve across tunnel encapsulation).
296 To execute the egress pipeline, OVN again searches the <ref
297 table="Logical_Flow"/> table for a row with correct <ref
298 column="logical_datapath"/>, a <ref column="table_id"/> of 0, a <ref
299 column="match"/> that is true for the packet, but now looking for a <ref
300 column="pipeline"/> of <code>egress</code>. If no matching row is found,
301 the output becomes a no-op. Otherwise, OVN executes the actions for the
302 matching flow (which is chosen from multiple, if necessary, as already
307 In the <code>egress</code> pipeline, the <code>next</code> action acts as
308 already described, except that it, of course, searches for
309 <code>egress</code> flows. The <code>output</code> action, however, now
310 directly outputs the packet to the output port (which is now fixed,
311 because <code>outport</code> is read-only within the egress pipeline).
315 The description earlier assumed that <code>outport</code> referred to a
316 logical port. If it instead designates a logical multicast group, then
317 the description above still applies, with the addition of fan-out from
318 the logical multicast group to each logical port in the group. For each
319 member of the group, OVN executes the logical pipeline as described, with
320 the logical output port replaced by the group member.
323 <column name="logical_datapath">
324 The logical datapath to which the logical flow belongs.
327 <column name="pipeline">
329 The primary flows used for deciding on a packet's destination are the
330 <code>ingress</code> flows. The <code>egress</code> flows implement
331 ACLs. See <em>Logical Life Cycle of a Packet</em>, above, for details.
335 <column name="table_id">
336 The stage in the logical pipeline, analogous to an OpenFlow table number.
339 <column name="priority">
340 The flow's priority. Flows with numerically higher priority take
341 precedence over those with lower. If two logical datapath flows with the
342 same priority both match, then the one actually applied to the packet is
346 <column name="match">
348 A matching expression. OVN provides a superset of OpenFlow matching
349 capabilities, using a syntax similar to Boolean expressions in a
350 programming language.
354 The most important components of match expression are
355 <dfn>comparisons</dfn> between <dfn>symbols</dfn> and
356 <dfn>constants</dfn>, e.g. <code>ip4.dst == 192.168.0.1</code>,
357 <code>ip.proto == 6</code>, <code>arp.op == 1</code>, <code>eth.type ==
358 0x800</code>. The logical AND operator <code>&&</code> and
359 logical OR operator <code>||</code> can combine comparisons into a
364 Matching expressions also support parentheses for grouping, the logical
365 NOT prefix operator <code>!</code>, and literals <code>0</code> and
366 <code>1</code> to express ``false'' or ``true,'' respectively. The
367 latter is useful by itself as a catch-all expression that matches every
371 <p><em>Symbols</em></p>
374 <em>Type</em>. Symbols have <dfn>integer</dfn> or <dfn>string</dfn>
375 type. Integer symbols have a <dfn>width</dfn> in bits.
379 <em>Kinds</em>. There are three kinds of symbols:
385 <dfn>Fields</dfn>. A field symbol represents a packet header or
386 metadata field. For example, a field
387 named <code>vlan.tci</code> might represent the VLAN TCI field in a
392 A field symbol can have integer or string type. Integer fields can
393 be nominal or ordinal (see <em>Level of Measurement</em>,
400 <dfn>Subfields</dfn>. A subfield represents a subset of bits from
401 a larger field. For example, a field <code>vlan.vid</code> might
402 be defined as an alias for <code>vlan.tci[0..11]</code>. Subfields
403 are provided for syntactic convenience, because it is always
404 possible to instead refer to a subset of bits from a field
409 Only ordinal fields (see <em>Level of Measurement</em>,
410 below) may have subfields. Subfields are always ordinal.
416 <dfn>Predicates</dfn>. A predicate is shorthand for a Boolean
417 expression. Predicates may be used much like 1-bit fields. For
418 example, <code>ip4</code> might expand to <code>eth.type ==
419 0x800</code>. Predicates are provided for syntactic convenience,
420 because it is always possible to instead specify the underlying
425 A predicate whose expansion refers to any nominal field or
426 predicate (see <em>Level of Measurement</em>, below) is nominal;
427 other predicates have Boolean level of measurement.
433 <em>Level of Measurement</em>. See
434 http://en.wikipedia.org/wiki/Level_of_measurement for the statistical
435 concept on which this classification is based. There are three
442 <dfn>Ordinal</dfn>. In statistics, ordinal values can be ordered
443 on a scale. OVN considers a field (or subfield) to be ordinal if
444 its bits can be examined individually. This is true for the
445 OpenFlow fields that OpenFlow or Open vSwitch makes ``maskable.''
449 Any use of a nominal field may specify a single bit or a range of
450 bits, e.g. <code>vlan.tci[13..15]</code> refers to the PCP field
451 within the VLAN TCI, and <code>eth.dst[40]</code> refers to the
452 multicast bit in the Ethernet destination address.
456 OVN supports all the usual arithmetic relations (<code>==</code>,
457 <code>!=</code>, <code><</code>, <code><=</code>,
458 <code>></code>, and <code>>=</code>) on ordinal fields and
459 their subfields, because OVN can implement these in OpenFlow and
460 Open vSwitch as collections of bitwise tests.
466 <dfn>Nominal</dfn>. In statistics, nominal values cannot be
467 usefully compared except for equality. This is true of OpenFlow
468 port numbers, Ethernet types, and IP protocols are examples: all of
469 these are just identifiers assigned arbitrarily with no deeper
470 meaning. In OpenFlow and Open vSwitch, bits in these fields
471 generally aren't individually addressable.
475 OVN only supports arithmetic tests for equality on nominal fields,
476 because OpenFlow and Open vSwitch provide no way for a flow to
477 efficiently implement other comparisons on them. (A test for
478 inequality can be sort of built out of two flows with different
479 priorities, but OVN matching expressions always generate flows with
484 String fields are always nominal.
490 <dfn>Boolean</dfn>. A nominal field that has only two values, 0
491 and 1, is somewhat exceptional, since it is easy to support both
492 equality and inequality tests on such a field: either one can be
493 implemented as a test for 0 or 1.
497 Only predicates (see above) have a Boolean level of measurement.
501 This isn't a standard level of measurement.
507 <em>Prerequisites</em>. Any symbol can have prerequisites, which are
508 additional condition implied by the use of the symbol. For example,
509 For example, <code>icmp4.type</code> symbol might have prerequisite
510 <code>icmp4</code>, which would cause an expression <code>icmp4.type ==
511 0</code> to be interpreted as <code>icmp4.type == 0 &&
512 icmp4</code>, which would in turn expand to <code>icmp4.type == 0
513 && eth.type == 0x800 && ip4.proto == 1</code> (assuming
514 <code>icmp4</code> is a predicate defined as suggested under
515 <em>Types</em> above).
518 <p><em>Relational operators</em></p>
521 All of the standard relational operators <code>==</code>,
522 <code>!=</code>, <code><</code>, <code><=</code>,
523 <code>></code>, and <code>>=</code> are supported. Nominal
524 fields support only <code>==</code> and <code>!=</code>, and only in a
525 positive sense when outer <code>!</code> are taken into account,
526 e.g. given string field <code>inport</code>, <code>inport ==
527 "eth0"</code> and <code>!(inport != "eth0")</code> are acceptable, but
528 not <code>inport != "eth0"</code>.
532 The implementation of <code>==</code> (or <code>!=</code> when it is
533 negated), is more efficient than that of the other relational
537 <p><em>Constants</em></p>
540 Integer constants may be expressed in decimal, hexadecimal prefixed by
541 <code>0x</code>, or as dotted-quad IPv4 addresses, IPv6 addresses in
542 their standard forms, or Ethernet addresses as colon-separated hex
543 digits. A constant in any of these forms may be followed by a slash
544 and a second constant (the mask) in the same form, to form a masked
545 constant. IPv4 and IPv6 masks may be given as integers, to express
550 String constants have the same syntax as quoted strings in JSON (thus,
551 they are Unicode strings).
555 Some operators support sets of constants written inside curly braces
556 <code>{</code> ... <code>}</code>. Commas between elements of a set,
557 and after the last elements, are optional. With <code>==</code>,
558 ``<code><var>field</var> == { <var>constant1</var>,
559 <var>constant2</var>,</code> ... <code>}</code>'' is syntactic sugar
560 for ``<code><var>field</var> == <var>constant1</var> ||
561 <var>field</var> == <var>constant2</var> || </code>...<code></code>.
562 Similarly, ``<code><var>field</var> != { <var>constant1</var>,
563 <var>constant2</var>, </code>...<code> }</code>'' is equivalent to
564 ``<code><var>field</var> != <var>constant1</var> &&
565 <var>field</var> != <var>constant2</var> &&
566 </code>...<code></code>''.
569 <p><em>Miscellaneous</em></p>
572 Comparisons may name the symbol or the constant first,
573 e.g. <code>tcp.src == 80</code> and <code>80 == tcp.src</code> are both
578 Tests for a range may be expressed using a syntax like <code>1024 <=
579 tcp.src <= 49151</code>, which is equivalent to <code>1024 <=
580 tcp.src && tcp.src <= 49151</code>.
584 For a one-bit field or predicate, a mention of its name is equivalent
585 to <code><var>symobl</var> == 1</code>, e.g. <code>vlan.present</code>
586 is equivalent to <code>vlan.present == 1</code>. The same is true for
587 one-bit subfields, e.g. <code>vlan.tci[12]</code>. There is no
588 technical limitation to implementing the same for ordinal fields of all
589 widths, but the implementation is expensive enough that the syntax
590 parser requires writing an explicit comparison against zero to make
591 mistakes less likely, e.g. in <code>tcp.src != 0</code> the comparison
592 against 0 is required.
596 <em>Operator precedence</em> is as shown below, from highest to lowest.
597 There are two exceptions where parentheses are required even though the
598 table would suggest that they are not: <code>&&</code> and
599 <code>||</code> require parentheses when used together, and
600 <code>!</code> requires parentheses when applied to a relational
601 expression. Thus, in <code>(eth.type == 0x800 || eth.type == 0x86dd)
602 && ip.proto == 6</code> or <code>!(arp.op == 1)</code>, the
603 parentheses are mandatory.
607 <li><code>()</code></li>
608 <li><code>== != < <= > >=</code></li>
609 <li><code>!</code></li>
610 <li><code>&& ||</code></li>
614 <em>Comments</em> may be introduced by <code>//</code>, which extends
615 to the next new-line. Comments within a line may be bracketed by
616 <code>/*</code> and <code>*/</code>. Multiline comments are not
620 <p><em>Symbols</em></p>
623 Most of the symbols below have integer type. Only <code>inport</code>
624 and <code>outport</code> have string type. <code>inport</code> names a
625 logical port. Thus, its value is a <ref column="logical_port"/> name
626 from the <ref table="Port_Binding"/> table. <code>outport</code> may
627 name a logical port, as <code>inport</code>, or a logical multicast
628 group defined in the <ref table="Multicast_Group"/> table. For both
629 symbols, only names within the flow's logical datapath may be used.
633 <li><code>reg0</code>...<code>reg5</code></li>
634 <li><code>inport</code> <code>outport</code></li>
635 <li><code>eth.src</code> <code>eth.dst</code> <code>eth.type</code></li>
636 <li><code>vlan.tci</code> <code>vlan.vid</code> <code>vlan.pcp</code> <code>vlan.present</code></li>
637 <li><code>ip.proto</code> <code>ip.dscp</code> <code>ip.ecn</code> <code>ip.ttl</code> <code>ip.frag</code></li>
638 <li><code>ip4.src</code> <code>ip4.dst</code></li>
639 <li><code>ip6.src</code> <code>ip6.dst</code> <code>ip6.label</code></li>
640 <li><code>arp.op</code> <code>arp.spa</code> <code>arp.tpa</code> <code>arp.sha</code> <code>arp.tha</code></li>
641 <li><code>tcp.src</code> <code>tcp.dst</code> <code>tcp.flags</code></li>
642 <li><code>udp.src</code> <code>udp.dst</code></li>
643 <li><code>sctp.src</code> <code>sctp.dst</code></li>
644 <li><code>icmp4.type</code> <code>icmp4.code</code></li>
645 <li><code>icmp6.type</code> <code>icmp6.code</code></li>
646 <li><code>nd.target</code> <code>nd.sll</code> <code>nd.tll</code></li>
651 <column name="actions">
653 Logical datapath actions, to be executed when the logical flow
654 represented by this row is the highest-priority match.
658 Actions share lexical syntax with the <ref column="match"/> column. An
659 empty set of actions (or one that contains just white space or
660 comments), or a set of actions that consists of just
661 <code>drop;</code>, causes the matched packets to be dropped.
662 Otherwise, the column should contain a sequence of actions, each
663 terminated by a semicolon.
667 The following actions are defined:
671 <dt><code>output;</code></dt>
674 In the ingress pipeline, this action executes the
675 <code>egress</code> pipeline as a subroutine. If
676 <code>outport</code> names a logical port, the egress pipeline
677 executes once; if it is a multicast group, the egress pipeline runs
678 once for each logical port in the group.
682 In the egress pipeline, this action performs the actual
683 output to the <code>outport</code> logical port. (In the egress
684 pipeline, <code>outport</code> never names a multicast group.)
688 Output to the input port is implicitly dropped, that is,
689 <code>output</code> becomes a no-op if <code>outport</code> ==
694 <dt><code>next;</code></dt>
696 Executes the next logical datapath table as a subroutine.
699 <dt><code><var>field</var> = <var>constant</var>;</code></dt>
702 Sets data or metadata field <var>field</var> to constant value
703 <var>constant</var>, e.g. <code>outport = "vif0";</code> to set the
704 logical output port. To set only a subset of bits in a field,
705 specify a subfield for <var>field</var> or a masked
706 <var>constant</var>, e.g. one may use <code>vlan.pcp[2] = 1;</code>
707 or <code>vlan.pcp = 4/4;</code> to set the most sigificant bit of
712 Assigning to a field with prerequisites implicitly adds those
713 prerequisites to <ref column="match"/>; thus, for example, a flow
714 that sets <code>tcp.dst</code> applies only to TCP flows,
715 regardless of whether its <ref column="match"/> mentions any TCP
720 Not all fields are modifiable (e.g. <code>eth.type</code> and
721 <code>ip.proto</code> are read-only), and not all modifiable fields
722 may be partially modified (e.g. <code>ip.ttl</code> must assigned
723 as a whole). The <code>outport</code> field is modifiable in the
724 <code>ingress</code> pipeline but not in the <code>egress</code>
731 The following actions will likely be useful later, but they have not
732 been thought out carefully.
736 <dt><code><var>field1</var> = <var>field2</var>;</code></dt>
738 Extends the assignment action to allow copying between fields.
741 <dt><code>learn</code></dt>
743 <dt><code>conntrack</code></dt>
745 <dt><code>dec_ttl { <var>action</var>, </code>...<code> } { <var>action</var>; </code>...<code>};</code></dt>
747 decrement TTL; execute first set of actions if
748 successful, second set if TTL decrement fails
751 <dt><code>icmp_reply { <var>action</var>, </code>...<code> };</code></dt>
752 <dd>generate ICMP reply from packet, execute <var>action</var>s</dd>
754 <dt><code>arp { <var>action</var>, </code>...<code> }</code></dt>
755 <dd>generate ARP from packet, execute <var>action</var>s</dd>
760 <table name="Multicast_Group" title="Logical Port Multicast Groups">
762 The rows in this table define multicast groups of logical ports.
763 Multicast groups allow a single packet transmitted over a tunnel to a
764 hypervisor to be delivered to multiple VMs on that hypervisor, which
765 uses bandwidth more efficiently.
769 Each row in this table defines a logical multicast group numbered <ref
770 column="tunnel_key"/> within <ref column="datapath"/>, whose logical
771 ports are listed in the <ref column="ports"/> column.
774 <column name="datapath">
775 The logical datapath in which the multicast group resides.
778 <column name="tunnel_key">
779 The value used to designate this logical egress port in tunnel
780 encapsulations. An index forces the key to be unique within the <ref
781 column="datapath"/>. The unusual range ensures that multicast group IDs
782 do not overlap with logical port IDs.
787 The logical multicast group's name. An index forces the name to be
788 unique within the <ref column="datapath"/>. Logical flows in the
789 ingress pipeline may output to the group just as for individual logical
790 ports, by assigning the group's name to <code>outport</code> and
791 executing an <code>output</code> action.
795 Multicast group names and logical port names share a single namespace
796 and thus should not overlap (but the database schema cannot enforce
797 this). To try to avoid conflicts, <code>ovn-northd</code> uses names
798 that begin with <code>_MC_</code>.
802 <column name="ports">
803 The logical ports included in the multicast group. All of these ports
804 must be in the <ref column="datapath"/> logical datapath (but the
805 database schema cannot enforce this).
809 <table name="Datapath_Binding" title="Physical-Logical Datapath Bindings">
811 Each row in this table identifies physical bindings of a logical
812 datapath. A logical datapath implements a logical pipeline among the
813 ports in the <ref table="Port_Binding"/> table associated with it. In
814 practice, the pipeline in a given logical datapath implements either a
815 logical switch or a logical router.
818 <column name="tunnel_key">
819 The tunnel key value to which the logical datapath is bound.
820 The <code>Tunnel Encapsulation</code> section in
821 <code>ovn-architecture</code>(7) describes how tunnel keys are
822 constructed for each supported encapsulation.
825 <column name="external_ids" key="logical-switch" type='{"type": "uuid"}'>
826 Each row in <ref table="Datapath_Binding"/> is associated with some
827 logical datapath. <code>ovn-northd</code> uses this key to store the
828 UUID of the logical datapath <ref table="Logical_Switch"
829 db="OVN_Northbound"/> row in the <ref db="OVN_Northbound"/> database.
832 <group title="Common Columns">
833 The overall purpose of these columns is described under <code>Common
834 Columns</code> at the beginning of this document.
836 <column name="external_ids"/>
840 <table name="Port_Binding" title="Physical-Logical Port Bindings">
842 Each row in this table identifies the physical location of a logical
847 For every <code>Logical_Port</code> record in <code>OVN_Northbound</code>
848 database, <code>ovn-northd</code> creates a record in this table.
849 <code>ovn-northd</code> populates and maintains every column except
850 the <code>chassis</code> column, which it leaves empty in new records.
854 <code>ovn-controller</code> populates the <code>chassis</code> column
855 for the records that identify the logical ports that are located on its
856 hypervisor, which <code>ovn-controller</code> in turn finds out by
857 monitoring the local hypervisor's Open_vSwitch database, which
858 identifies logical ports via the conventions described in
859 <code>IntegrationGuide.md</code>.
863 When a chassis shuts down gracefully, it should clean up the
864 <code>chassis</code> column that it previously had populated.
865 (This is not critical because resources hosted on the chassis are equally
866 unreachable regardless of whether their rows are present.) To handle the
867 case where a VM is shut down abruptly on one chassis, then brought up
868 again on a different one, <code>ovn-controller</code> must overwrite the
869 <code>chassis</code> column with new information.
872 <column name="datapath">
873 The logical datapath to which the logical port belongs.
876 <column name="logical_port">
877 A logical port, taken from <ref table="Logical_Port" column="name"
878 db="OVN_Northbound"/> in the OVN_Northbound database's
879 <ref table="Logical_Port" db="OVN_Northbound"/> table. OVN does not
880 prescribe a particular format for the logical port ID.
885 A type for this logical port. Logical ports can be used to model
886 other types of connectivity into an OVN logical switch. Leaving this column
887 blank maintains the default logical port behavior.
891 There are no other logical port types implemented yet.
895 <column name="options">
896 This column provides key/value settings specific to the logical port
897 <ref column="type"/>.
900 <column name="tunnel_key">
902 A number that represents the logical port in the key (e.g. STT key or
903 Geneve TLV) field carried within tunnel protocol packets.
907 The tunnel ID must be unique within the scope of a logical datapath.
911 <column name="parent_port">
912 For containers created inside a VM, this is taken from
913 <ref table="Logical_Port" column="parent_name" db="OVN_Northbound"/>
914 in the OVN_Northbound database's <ref table="Logical_Port"
915 db="OVN_Northbound"/> table. It is left empty if
916 <ref column="logical_port"/> belongs to a VM or a container created
921 When <ref column="logical_port"/> identifies the interface of a container
922 spawned inside a VM, this column identifies the VLAN tag in
923 the network traffic associated with that container's network interface.
924 It is left empty if <ref column="logical_port"/> belongs to a VM or a
925 container created in the hypervisor.
928 <column name="chassis">
929 The physical location of the logical port. To successfully identify a
930 chassis, this column must be a <ref table="Chassis"/> record. This is
931 populated by <code>ovn-controller</code>.
936 The Ethernet address or addresses used as a source address on the
937 logical port, each in the form
938 <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
939 The string <code>unknown</code> is also allowed to indicate that the
940 logical port has an unknown set of (additional) source addresses.
944 A VM interface would ordinarily have a single Ethernet address. A
945 gateway port might initially only have <code>unknown</code>, and then
946 add MAC addresses to the set as it learns new source addresses.