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>/
<code>ovn-controller-vtep
</code>, and
14 northbound to the Cloud Management System, via
<code>ovn-northd
</code>:
17 <h2>Database Structure
</h2>
20 The OVN Southbound database contains 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
66 <ref db=
"OVN_Northbound"/> database 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>Logical-physical bindings
</h3>
83 These tables 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 These tables 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 <h3>MAC bindings
</h3>
109 The
<ref table=
"MAC_Binding"/> table tracks the bindings from IP addresses
110 to Ethernet addresses that are dynamically discovered using ARP (for IPv4)
111 and neighbor discovery (for IPv6). Usually, IP-to-MAC bindings for virtual
112 machines are statically populated into the
<ref table=
"Port_Binding"/>
113 table, so
<ref table=
"MAC_Binding"/> is primarily used to discover bindings
114 on physical networks.
117 <h2>Common Columns
</h2>
120 Some tables contain a special column named
<code>external_ids
</code>. This
121 column has the same form and purpose each place that it appears, so we
122 describe it here to save space later.
126 <dt><code>external_ids
</code>: map of string-string pairs
</dt>
128 Key-value pairs for use by the software that manages the OVN Southbound
129 database rather than by
130 <code>ovn-controller
</code>/
<code>ovn-controller-vtep
</code>. In
131 particular,
<code>ovn-northd
</code> can use key-value pairs in this
132 column to relate entities in the southbound database to higher-level
133 entities (such as entities in the OVN Northbound database). Individual
134 key-value pairs in this column may be documented in some cases to aid
135 in understanding and troubleshooting, but the reader should not mistake
136 such documentation as comprehensive.
140 <table name=
"Chassis" title=
"Physical Network Hypervisor and Gateway Information">
142 Each row in this table represents a hypervisor or gateway (a chassis) in
143 the physical network (PN). Each chassis, via
144 <code>ovn-controller
</code>/
<code>ovn-controller-vtep
</code>, adds
145 and updates its own row, and keeps a copy of the remaining rows to
146 determine how to reach other hypervisors.
150 When a chassis shuts down gracefully, it should remove its own row.
151 (This is not critical because resources hosted on the chassis are equally
152 unreachable regardless of whether the row is present.) If a chassis
153 shuts down permanently without removing its row, some kind of manual or
154 automatic cleanup is eventually needed; we can devise a process for that
159 OVN does not prescribe a particular format for chassis names.
160 ovn-controller populates this column using
<ref key=
"system-id"
161 table=
"Open_vSwitch" column=
"external_ids" db=
"Open_vSwitch"/>
162 in the Open_vSwitch database's
<ref table=
"Open_vSwitch"
163 db=
"Open_vSwitch"/> table. ovn-controller-vtep populates this
164 column with
<ref table=
"Physical_Switch" column=
"name"
165 db=
"hardware_vtep"/> in the hardware_vtep database's
166 <ref table=
"Physical_Switch" db=
"hardware_vtep"/> table.
169 <column name=
"hostname">
170 The hostname of the chassis, if applicable. ovn-controller will populate
171 this column with the hostname of the host it is running on.
172 ovn-controller-vtep will leave this column empty.
175 <column name=
"external_ids" key=
"ovn-bridge-mappings">
176 <code>ovn-controller
</code> populates this key with the set of bridge
177 mappings it has been configured to use. Other applications should treat
178 this key as read-only. See
<code>ovn-controller
</code>(
8) for more
182 <group title=
"Common Columns">
183 The overall purpose of these columns is described under
<code>Common
184 Columns
</code> at the beginning of this document.
186 <column name=
"external_ids"/>
189 <group title=
"Encapsulation Configuration">
191 OVN uses encapsulation to transmit logical dataplane packets
195 <column name=
"encaps">
196 Points to supported encapsulation configurations to transmit
197 logical dataplane packets to this chassis. Each entry is a
<ref
198 table=
"Encap"/> record that describes the configuration.
202 <group title=
"Gateway Configuration">
204 A
<dfn>gateway
</dfn> is a chassis that forwards traffic between the
205 OVN-managed part of a logical network and a physical VLAN, extending a
206 tunnel-based logical network into a physical network. Gateways are
207 typically dedicated nodes that do not host VMs and will be controlled
208 by
<code>ovn-controller-vtep
</code>.
211 <column name=
"vtep_logical_switches">
212 Stores all VTEP logical switch names connected by this gateway
213 chassis. The
<ref table=
"Port_Binding"/> table entry with
214 <ref column=
"options" table=
"Port_Binding"/>:
<code>vtep-physical-switch
</code>
215 equal
<ref table=
"Chassis"/> <ref column=
"name" table=
"Chassis"/>, and
216 <ref column=
"options" table=
"Port_Binding"/>:
<code>vtep-logical-switch
</code>
217 value in
<ref table=
"Chassis"/>
218 <ref column=
"vtep_logical_switches" table=
"Chassis"/>, will be
219 associated with this
<ref table=
"Chassis"/>.
224 <table name=
"Encap" title=
"Encapsulation Types">
226 The
<ref column=
"encaps" table=
"Chassis"/> column in the
<ref
227 table=
"Chassis"/> table refers to rows in this table to identify
228 how OVN may transmit logical dataplane packets to this chassis.
229 Each chassis, via
<code>ovn-controller
</code>(
8) or
230 <code>ovn-controller-vtep
</code>(
8), adds and updates its own rows
231 and keeps a copy of the remaining rows to determine how to reach
236 The encapsulation to use to transmit packets to this chassis.
237 Hypervisors must use either
<code>geneve
</code> or
238 <code>stt
</code>. Gateways may use
<code>vxlan
</code>,
239 <code>geneve
</code>, or
<code>stt
</code>.
242 <column name=
"options">
243 Options for configuring the encapsulation, e.g. IPsec parameters when
244 IPsec support is introduced. No options are currently defined.
248 The IPv4 address of the encapsulation tunnel endpoint.
252 <table name=
"Address_Set" title=
"Address Sets">
254 See the documentation for the
<ref table=
"Address_Set"
255 db=
"OVN_Northbound"/> table in the
<ref db=
"OVN_Northbound"/> database
259 <column name=
"name"/>
260 <column name=
"addresses"/>
263 <table name=
"Logical_Flow" title=
"Logical Network Flows">
265 Each row in this table represents one logical flow.
266 <code>ovn-northd
</code> populates this table with logical flows
267 that implement the L2 and L3 topologies specified in the
268 <ref db=
"OVN_Northbound"/> database. Each hypervisor, via
269 <code>ovn-controller
</code>, translates the logical flows into
270 OpenFlow flows specific to its hypervisor and installs them into
275 Logical flows are expressed in an OVN-specific format, described here. A
276 logical datapath flow is much like an OpenFlow flow, except that the
277 flows are written in terms of logical ports and logical datapaths instead
278 of physical ports and physical datapaths. Translation between logical
279 and physical flows helps to ensure isolation between logical datapaths.
280 (The logical flow abstraction also allows the OVN centralized
281 components to do less work, since they do not have to separately
282 compute and push out physical flows to each chassis.)
286 The default action when no flow matches is to drop packets.
289 <p><em>Architectural Logical Life Cycle of a Packet
</em></p>
292 This following description focuses on the life cycle of a packet through
293 a logical datapath, ignoring physical details of the implementation.
294 Please refer to
<em>Architectural Physical Life Cycle of a Packet
</em> in
295 <code>ovn-architecture
</code>(
7) for the physical information.
299 The description here is written as if OVN itself executes these steps,
300 but in fact OVN (that is,
<code>ovn-controller
</code>) programs Open
301 vSwitch, via OpenFlow and OVSDB, to execute them on its behalf.
305 At a high level, OVN passes each packet through the logical datapath's
306 logical ingress pipeline, which may output the packet to one or more
307 logical port or logical multicast groups. For each such logical output
308 port, OVN passes the packet through the datapath's logical egress
309 pipeline, which may either drop the packet or deliver it to the
310 destination. Between the two pipelines, outputs to logical multicast
311 groups are expanded into logical ports, so that the egress pipeline only
312 processes a single logical output port at a time. Between the two
313 pipelines is also where, when necessary, OVN encapsulates a packet in a
314 tunnel (or tunnels) to transmit to remote hypervisors.
318 In more detail, to start, OVN searches the
<ref table=
"Logical_Flow"/>
319 table for a row with correct
<ref column=
"logical_datapath"/>, a
<ref
320 column=
"pipeline"/> of
<code>ingress
</code>, a
<ref column=
"table_id"/>
321 of
0, and a
<ref column=
"match"/> that is true for the packet. If none
322 is found, OVN drops the packet. If OVN finds more than one, it chooses
323 the match with the highest
<ref column=
"priority"/>. Then OVN executes
324 each of the actions specified in the row's
<ref table=
"actions"/> column,
325 in the order specified. Some actions, such as those to modify packet
326 headers, require no further details. The
<code>next
</code> and
327 <code>output
</code> actions are special.
331 The
<code>next
</code> action causes the above process to be repeated
332 recursively, except that OVN searches for
<ref column=
"table_id"/> of
1
333 instead of
0. Similarly, any
<code>next
</code> action in a row found in
334 that table would cause a further search for a
<ref column=
"table_id"/> of
335 2, and so on. When recursive processing completes, flow control returns
336 to the action following
<code>next
</code>.
340 The
<code>output
</code> action also introduces recursion. Its effect
341 depends on the current value of the
<code>outport
</code> field. Suppose
342 <code>outport
</code> designates a logical port. First, OVN compares
343 <code>inport
</code> to
<code>outport
</code>; if they are equal, it treats
344 the
<code>output
</code> as a no-op. In the common case, where they are
345 different, the packet enters the egress pipeline. This transition to the
346 egress pipeline discards register data, e.g.
<code>reg0
</code> ...
347 <code>reg4
</code> and connection tracking state, to achieve
348 uniform behavior regardless of whether the egress pipeline is on a
349 different hypervisor (because registers aren't preserve across
350 tunnel encapsulation).
354 To execute the egress pipeline, OVN again searches the
<ref
355 table=
"Logical_Flow"/> table for a row with correct
<ref
356 column=
"logical_datapath"/>, a
<ref column=
"table_id"/> of
0, a
<ref
357 column=
"match"/> that is true for the packet, but now looking for a
<ref
358 column=
"pipeline"/> of
<code>egress
</code>. If no matching row is found,
359 the output becomes a no-op. Otherwise, OVN executes the actions for the
360 matching flow (which is chosen from multiple, if necessary, as already
365 In the
<code>egress
</code> pipeline, the
<code>next
</code> action acts as
366 already described, except that it, of course, searches for
367 <code>egress
</code> flows. The
<code>output
</code> action, however, now
368 directly outputs the packet to the output port (which is now fixed,
369 because
<code>outport
</code> is read-only within the egress pipeline).
373 The description earlier assumed that
<code>outport
</code> referred to a
374 logical port. If it instead designates a logical multicast group, then
375 the description above still applies, with the addition of fan-out from
376 the logical multicast group to each logical port in the group. For each
377 member of the group, OVN executes the logical pipeline as described, with
378 the logical output port replaced by the group member.
381 <p><em>Pipeline Stages
</em></p>
384 <code>ovn-northd
</code> is responsible for populating the
385 <ref table=
"Logical_Flow"/> table, so the stages are an
386 implementation detail and subject to change. This section
387 describes the current logical flow table.
391 The ingress pipeline consists of the following stages:
395 Port Security (Table
0): Validates the source address, drops
396 packets with a VLAN tag, and, if configured, verifies that the
397 logical port is allowed to send with the source address.
401 L2 Destination Lookup (Table
1): Forwards known unicast
402 addresses to the appropriate logical port. Unicast packets to
403 unknown hosts are forwarded to logical ports configured with the
404 special
<code>unknown
</code> mac address. Broadcast, and
405 multicast are flooded to all ports in the logical switch.
410 The egress pipeline consists of the following stages:
414 ACL (Table
0): Applies any specified access control lists.
418 Port Security (Table
1): If configured, verifies that the
419 logical port is allowed to receive packets with the destination
424 <column name=
"logical_datapath">
425 The logical datapath to which the logical flow belongs.
428 <column name=
"pipeline">
430 The primary flows used for deciding on a packet's destination are the
431 <code>ingress
</code> flows. The
<code>egress
</code> flows implement
432 ACLs. See
<em>Logical Life Cycle of a Packet
</em>, above, for details.
436 <column name=
"table_id">
437 The stage in the logical pipeline, analogous to an OpenFlow table number.
440 <column name=
"priority">
441 The flow's priority. Flows with numerically higher priority take
442 precedence over those with lower. If two logical datapath flows with the
443 same priority both match, then the one actually applied to the packet is
447 <column name=
"match">
449 A matching expression. OVN provides a superset of OpenFlow matching
450 capabilities, using a syntax similar to Boolean expressions in a
451 programming language.
455 The most important components of match expression are
456 <dfn>comparisons
</dfn> between
<dfn>symbols
</dfn> and
457 <dfn>constants
</dfn>, e.g.
<code>ip4.dst ==
192.168.0.1</code>,
458 <code>ip.proto ==
6</code>,
<code>arp.op ==
1</code>,
<code>eth.type ==
459 0x800</code>. The logical AND operator
<code>&&</code> and
460 logical OR operator
<code>||
</code> can combine comparisons into a
465 Matching expressions also support parentheses for grouping, the logical
466 NOT prefix operator
<code>!
</code>, and literals
<code>0</code> and
467 <code>1</code> to express ``false'' or ``true,'' respectively. The
468 latter is useful by itself as a catch-all expression that matches every
472 <p><em>Symbols
</em></p>
475 <em>Type
</em>. Symbols have
<dfn>integer
</dfn> or
<dfn>string
</dfn>
476 type. Integer symbols have a
<dfn>width
</dfn> in bits.
480 <em>Kinds
</em>. There are three kinds of symbols:
486 <dfn>Fields
</dfn>. A field symbol represents a packet header or
487 metadata field. For example, a field
488 named
<code>vlan.tci
</code> might represent the VLAN TCI field in a
493 A field symbol can have integer or string type. Integer fields can
494 be nominal or ordinal (see
<em>Level of Measurement
</em>,
501 <dfn>Subfields
</dfn>. A subfield represents a subset of bits from
502 a larger field. For example, a field
<code>vlan.vid
</code> might
503 be defined as an alias for
<code>vlan.tci[
0.
.11]
</code>. Subfields
504 are provided for syntactic convenience, because it is always
505 possible to instead refer to a subset of bits from a field
510 Only ordinal fields (see
<em>Level of Measurement
</em>,
511 below) may have subfields. Subfields are always ordinal.
517 <dfn>Predicates
</dfn>. A predicate is shorthand for a Boolean
518 expression. Predicates may be used much like
1-bit fields. For
519 example,
<code>ip4
</code> might expand to
<code>eth.type ==
520 0x800</code>. Predicates are provided for syntactic convenience,
521 because it is always possible to instead specify the underlying
526 A predicate whose expansion refers to any nominal field or
527 predicate (see
<em>Level of Measurement
</em>, below) is nominal;
528 other predicates have Boolean level of measurement.
534 <em>Level of Measurement
</em>. See
535 http://en.wikipedia.org/wiki/Level_of_measurement for the statistical
536 concept on which this classification is based. There are three
543 <dfn>Ordinal
</dfn>. In statistics, ordinal values can be ordered
544 on a scale. OVN considers a field (or subfield) to be ordinal if
545 its bits can be examined individually. This is true for the
546 OpenFlow fields that OpenFlow or Open vSwitch makes ``maskable.''
550 Any use of a nominal field may specify a single bit or a range of
551 bits, e.g.
<code>vlan.tci[
13.
.15]
</code> refers to the PCP field
552 within the VLAN TCI, and
<code>eth.dst[
40]
</code> refers to the
553 multicast bit in the Ethernet destination address.
557 OVN supports all the usual arithmetic relations (
<code>==
</code>,
558 <code>!=
</code>,
<code><</code>,
<code><=
</code>,
559 <code>></code>, and
<code>>=
</code>) on ordinal fields and
560 their subfields, because OVN can implement these in OpenFlow and
561 Open vSwitch as collections of bitwise tests.
567 <dfn>Nominal
</dfn>. In statistics, nominal values cannot be
568 usefully compared except for equality. This is true of OpenFlow
569 port numbers, Ethernet types, and IP protocols are examples: all of
570 these are just identifiers assigned arbitrarily with no deeper
571 meaning. In OpenFlow and Open vSwitch, bits in these fields
572 generally aren't individually addressable.
576 OVN only supports arithmetic tests for equality on nominal fields,
577 because OpenFlow and Open vSwitch provide no way for a flow to
578 efficiently implement other comparisons on them. (A test for
579 inequality can be sort of built out of two flows with different
580 priorities, but OVN matching expressions always generate flows with
585 String fields are always nominal.
591 <dfn>Boolean
</dfn>. A nominal field that has only two values,
0
592 and
1, is somewhat exceptional, since it is easy to support both
593 equality and inequality tests on such a field: either one can be
594 implemented as a test for
0 or
1.
598 Only predicates (see above) have a Boolean level of measurement.
602 This isn't a standard level of measurement.
608 <em>Prerequisites
</em>. Any symbol can have prerequisites, which are
609 additional condition implied by the use of the symbol. For example,
610 For example,
<code>icmp4.type
</code> symbol might have prerequisite
611 <code>icmp4
</code>, which would cause an expression
<code>icmp4.type ==
612 0</code> to be interpreted as
<code>icmp4.type ==
0 &&
613 icmp4
</code>, which would in turn expand to
<code>icmp4.type ==
0
614 && eth.type ==
0x800 && ip4.proto ==
1</code> (assuming
615 <code>icmp4
</code> is a predicate defined as suggested under
616 <em>Types
</em> above).
619 <p><em>Relational operators
</em></p>
622 All of the standard relational operators
<code>==
</code>,
623 <code>!=
</code>,
<code><</code>,
<code><=
</code>,
624 <code>></code>, and
<code>>=
</code> are supported. Nominal
625 fields support only
<code>==
</code> and
<code>!=
</code>, and only in a
626 positive sense when outer
<code>!
</code> are taken into account,
627 e.g. given string field
<code>inport
</code>,
<code>inport ==
628 "eth0"</code> and
<code>!(inport !=
"eth0")
</code> are acceptable, but
629 not
<code>inport !=
"eth0"</code>.
633 The implementation of
<code>==
</code> (or
<code>!=
</code> when it is
634 negated), is more efficient than that of the other relational
638 <p><em>Constants
</em></p>
641 Integer constants may be expressed in decimal, hexadecimal prefixed by
642 <code>0x
</code>, or as dotted-quad IPv4 addresses, IPv6 addresses in
643 their standard forms, or Ethernet addresses as colon-separated hex
644 digits. A constant in any of these forms may be followed by a slash
645 and a second constant (the mask) in the same form, to form a masked
646 constant. IPv4 and IPv6 masks may be given as integers, to express
651 String constants have the same syntax as quoted strings in JSON (thus,
652 they are Unicode strings).
656 Some operators support sets of constants written inside curly braces
657 <code>{
</code> ...
<code>}
</code>. Commas between elements of a set,
658 and after the last elements, are optional. With
<code>==
</code>,
659 ``
<code><var>field
</var> == {
<var>constant1
</var>,
660 <var>constant2
</var>,
</code> ...
<code>}
</code>'' is syntactic sugar
661 for ``
<code><var>field
</var> ==
<var>constant1
</var> ||
662 <var>field
</var> ==
<var>constant2
</var> ||
</code>...
<code></code>.
663 Similarly, ``
<code><var>field
</var> != {
<var>constant1
</var>,
664 <var>constant2
</var>,
</code>...
<code> }
</code>'' is equivalent to
665 ``
<code><var>field
</var> !=
<var>constant1
</var> &&
666 <var>field
</var> !=
<var>constant2
</var> &&
667 </code>...
<code></code>''.
671 You may refer to a set of IPv4, IPv6, or MAC addresses stored in the
672 <ref table=
"Address_Set"/> table by its
<ref column=
"name"
673 table=
"Address_Set"/>. An
<ref table=
"Address_Set"/> with a name
674 of
<code>set1
</code> can be referred to as
678 <p><em>Miscellaneous
</em></p>
681 Comparisons may name the symbol or the constant first,
682 e.g.
<code>tcp.src ==
80</code> and
<code>80 == tcp.src
</code> are both
687 Tests for a range may be expressed using a syntax like
<code>1024 <=
688 tcp.src
<=
49151</code>, which is equivalent to
<code>1024 <=
689 tcp.src
&& tcp.src
<=
49151</code>.
693 For a one-bit field or predicate, a mention of its name is equivalent
694 to
<code><var>symobl
</var> ==
1</code>, e.g.
<code>vlan.present
</code>
695 is equivalent to
<code>vlan.present ==
1</code>. The same is true for
696 one-bit subfields, e.g.
<code>vlan.tci[
12]
</code>. There is no
697 technical limitation to implementing the same for ordinal fields of all
698 widths, but the implementation is expensive enough that the syntax
699 parser requires writing an explicit comparison against zero to make
700 mistakes less likely, e.g. in
<code>tcp.src !=
0</code> the comparison
701 against
0 is required.
705 <em>Operator precedence
</em> is as shown below, from highest to lowest.
706 There are two exceptions where parentheses are required even though the
707 table would suggest that they are not:
<code>&&</code> and
708 <code>||
</code> require parentheses when used together, and
709 <code>!
</code> requires parentheses when applied to a relational
710 expression. Thus, in
<code>(eth.type ==
0x800 || eth.type ==
0x86dd)
711 && ip.proto ==
6</code> or
<code>!(arp.op ==
1)
</code>, the
712 parentheses are mandatory.
716 <li><code>()
</code></li>
717 <li><code>== !=
< <=
> >=
</code></li>
718 <li><code>!
</code></li>
719 <li><code>&& ||
</code></li>
723 <em>Comments
</em> may be introduced by
<code>//
</code>, which extends
724 to the next new-line. Comments within a line may be bracketed by
725 <code>/*
</code> and
<code>*/
</code>. Multiline comments are not
729 <p><em>Symbols
</em></p>
732 Most of the symbols below have integer type. Only
<code>inport
</code>
733 and
<code>outport
</code> have string type.
<code>inport
</code> names a
734 logical port. Thus, its value is a
<ref column=
"logical_port"/> name
735 from the
<ref table=
"Port_Binding"/> table.
<code>outport
</code> may
736 name a logical port, as
<code>inport
</code>, or a logical multicast
737 group defined in the
<ref table=
"Multicast_Group"/> table. For both
738 symbols, only names within the flow's logical datapath may be used.
742 <li><code>reg0
</code>...
<code>reg4
</code></li>
743 <li><code>inport
</code> <code>outport
</code></li>
744 <li><code>eth.src
</code> <code>eth.dst
</code> <code>eth.type
</code></li>
745 <li><code>vlan.tci
</code> <code>vlan.vid
</code> <code>vlan.pcp
</code> <code>vlan.present
</code></li>
746 <li><code>ip.proto
</code> <code>ip.dscp
</code> <code>ip.ecn
</code> <code>ip.ttl
</code> <code>ip.frag
</code></li>
747 <li><code>ip4.src
</code> <code>ip4.dst
</code></li>
748 <li><code>ip6.src
</code> <code>ip6.dst
</code> <code>ip6.label
</code></li>
749 <li><code>arp.op
</code> <code>arp.spa
</code> <code>arp.tpa
</code> <code>arp.sha
</code> <code>arp.tha
</code></li>
750 <li><code>tcp.src
</code> <code>tcp.dst
</code> <code>tcp.flags
</code></li>
751 <li><code>udp.src
</code> <code>udp.dst
</code></li>
752 <li><code>sctp.src
</code> <code>sctp.dst
</code></li>
753 <li><code>icmp4.type
</code> <code>icmp4.code
</code></li>
754 <li><code>icmp6.type
</code> <code>icmp6.code
</code></li>
755 <li><code>nd.target
</code> <code>nd.sll
</code> <code>nd.tll
</code></li>
756 <li><code>ct_mark
</code> <code>ct_label
</code></li>
759 <code>ct_state
</code>, which has the following Boolean subfields:
762 <li><code>ct.new
</code>: True for a new flow
</li>
763 <li><code>ct.est
</code>: True for an established flow
</li>
764 <li><code>ct.rel
</code>: True for a related flow
</li>
765 <li><code>ct.rpl
</code>: True for a reply flow
</li>
766 <li><code>ct.inv
</code>: True for a connection entry in a bad state
</li>
769 <code>ct_state
</code> and its subfields are initialized by the
770 <code>ct_next
</code> action, described below.
776 The following predicates are supported:
780 <li><code>eth.bcast
</code> expands to
<code>eth.dst == ff:ff:ff:ff:ff:ff
</code></li>
781 <li><code>eth.mcast
</code> expands to
<code>eth.dst[
40]
</code></li>
782 <li><code>vlan.present
</code> expands to
<code>vlan.tci[
12]
</code></li>
783 <li><code>ip4
</code> expands to
<code>eth.type ==
0x800</code></li>
784 <li><code>ip4.mcast
</code> expands to
<code>ip4.dst[
28.
.31] ==
0xe</code></li>
785 <li><code>ip6
</code> expands to
<code>eth.type ==
0x86dd</code></li>
786 <li><code>ip
</code> expands to
<code>ip4 || ip6
</code></li>
787 <li><code>icmp4
</code> expands to
<code>ip4
&& ip.proto ==
1</code></li>
788 <li><code>icmp6
</code> expands to
<code>ip6
&& ip.proto ==
58</code></li>
789 <li><code>icmp
</code> expands to
<code>icmp4 || icmp6
</code></li>
790 <li><code>ip.is_frag
</code> expands to
<code>ip.frag[
0]
</code></li>
791 <li><code>ip.later_frag
</code> expands to
<code>ip.frag[
1]
</code></li>
792 <li><code>ip.first_frag
</code> expands to
<code>ip.is_frag
&& !ip.later_frag
</code></li>
793 <li><code>arp
</code> expands to
<code>eth.type ==
0x806</code></li>
794 <li><code>nd
</code> expands to
<code>icmp6.type == {
135,
136}
&& icmp6.code ==
0</code></li>
795 <li><code>tcp
</code> expands to
<code>ip.proto ==
6</code></li>
796 <li><code>udp
</code> expands to
<code>ip.proto ==
17</code></li>
797 <li><code>sctp
</code> expands to
<code>ip.proto ==
132</code></li>
801 <column name=
"actions">
803 Logical datapath actions, to be executed when the logical flow
804 represented by this row is the highest-priority match.
808 Actions share lexical syntax with the
<ref column=
"match"/> column. An
809 empty set of actions (or one that contains just white space or
810 comments), or a set of actions that consists of just
811 <code>drop;
</code>, causes the matched packets to be dropped.
812 Otherwise, the column should contain a sequence of actions, each
813 terminated by a semicolon.
817 The following actions are defined:
821 <dt><code>output;
</code></dt>
824 In the ingress pipeline, this action executes the
825 <code>egress
</code> pipeline as a subroutine. If
826 <code>outport
</code> names a logical port, the egress pipeline
827 executes once; if it is a multicast group, the egress pipeline runs
828 once for each logical port in the group.
832 In the egress pipeline, this action performs the actual
833 output to the
<code>outport
</code> logical port. (In the egress
834 pipeline,
<code>outport
</code> never names a multicast group.)
838 Output to the input port is implicitly dropped, that is,
839 <code>output
</code> becomes a no-op if
<code>outport
</code> ==
840 <code>inport
</code>. Occasionally it may be useful to override
841 this behavior, e.g. to send an ARP reply to an ARP request; to do
842 so, use
<code>inport =
"";
</code> to set the logical input port to
843 an empty string (which should not be used as the name of any
848 <dt><code>next;
</code></dt>
849 <dt><code>next(
<var>table
</var>);
</code></dt>
851 Executes another logical datapath table as a subroutine. By default,
852 the table after the current one is executed. Specify
853 <var>table
</var> to jump to a specific table in the same pipeline.
856 <dt><code><var>field
</var> =
<var>constant
</var>;
</code></dt>
859 Sets data or metadata field
<var>field
</var> to constant value
860 <var>constant
</var>, e.g.
<code>outport =
"vif0";
</code> to set the
861 logical output port. To set only a subset of bits in a field,
862 specify a subfield for
<var>field
</var> or a masked
863 <var>constant
</var>, e.g. one may use
<code>vlan.pcp[
2] =
1;
</code>
864 or
<code>vlan.pcp =
4/
4;
</code> to set the most sigificant bit of
869 Assigning to a field with prerequisites implicitly adds those
870 prerequisites to
<ref column=
"match"/>; thus, for example, a flow
871 that sets
<code>tcp.dst
</code> applies only to TCP flows,
872 regardless of whether its
<ref column=
"match"/> mentions any TCP
877 Not all fields are modifiable (e.g.
<code>eth.type
</code> and
878 <code>ip.proto
</code> are read-only), and not all modifiable fields
879 may be partially modified (e.g.
<code>ip.ttl
</code> must assigned
880 as a whole). The
<code>outport
</code> field is modifiable in the
881 <code>ingress
</code> pipeline but not in the
<code>egress
</code>
886 <dt><code><var>field1
</var> =
<var>field2
</var>;
</code></dt>
889 Sets data or metadata field
<var>field1
</var> to the value of data
890 or metadata field
<var>field2
</var>, e.g.
<code>reg0 =
891 ip4.src;
</code> copies
<code>ip4.src
</code> into
<code>reg0
</code>.
892 To modify only a subset of a field's bits, specify a subfield for
893 <var>field1
</var> or
<var>field2
</var> or both, e.g.
<code>vlan.pcp
894 = reg0[
0.
.2];
</code> copies the least-significant bits of
895 <code>reg0
</code> into the VLAN PCP.
899 <var>field1
</var> and
<var>field2
</var> must be the same type,
900 either both string or both integer fields. If they are both
901 integer fields, they must have the same width.
905 If
<var>field1
</var> or
<var>field2
</var> has prerequisites, they
906 are added implicitly to
<ref column=
"match"/>. It is possible to
907 write an assignment with contradictory prerequisites, such as
908 <code>ip4.src = ip6.src[
0.
.31];
</code>, but the contradiction means
909 that a logical flow with such an assignment will never be matched.
913 <dt><code><var>field1
</var> <-
> <var>field2
</var>;
</code></dt>
916 Similar to
<code><var>field1
</var> =
<var>field2
</var>;
</code>
917 except that the two values are exchanged instead of copied. Both
918 <var>field1
</var> and
<var>field2
</var> must modifiable.
922 <dt><code>ip.ttl--;
</code></dt>
925 Decrements the IPv4 or IPv6 TTL. If this would make the TTL zero
926 or negative, then processing of the packet halts; no further
927 actions are processed. (To properly handle such cases, a
928 higher-priority flow should match on
929 <code>ip.ttl == {
0,
1};
</code>.)
932 <p><b>Prerequisite:
</b> <code>ip
</code></p>
935 <dt><code>ct_next;
</code></dt>
938 Apply connection tracking to the flow, initializing
939 <code>ct_state
</code> for matching in later tables.
940 Automatically moves on to the next table, as if followed by
945 As a side effect, IP fragments will be reassembled for matching.
946 If a fragmented packet is output, then it will be sent with any
947 overlapping fragments squashed. The connection tracking state is
948 scoped by the logical port, so overlapping addresses may be used.
949 To allow traffic related to the matched flow, execute
950 <code>ct_commit
</code>.
954 It is possible to have actions follow
<code>ct_next
</code>,
955 but they will not have access to any of its side-effects and
956 is not generally useful.
960 <dt><code>ct_commit;
</code></dt>
961 <dt><code>ct_commit(ct_mark=
<var>value[/mask]
</var>);
</code></dt>
962 <dt><code>ct_commit(ct_label=
<var>value[/mask]
</var>);
</code></dt>
963 <dt><code>ct_commit(ct_mark=
<var>value[/mask]
</var>, ct_label=
<var>value[/mask]
</var>);
</code></dt>
966 Commit the flow to the connection tracking entry associated with it
967 by a previous call to
<code>ct_next
</code>. When
968 <code>ct_mark=
<var>value[/mask]
</var></code> and/or
969 <code>ct_label=
<var>value[/mask]
</var></code> are supplied,
970 <code>ct_mark
</code> and/or
<code>ct_label
</code> will be set to the
971 values indicated by
<var>value[/mask]
</var> on the connection
972 tracking entry.
<code>ct_mark
</code> is a
32-bit field.
973 <code>ct_label
</code> is technically a
128-bit field, though OVN
974 currently only supports
64-bits and will later be extended to
975 support the full
128-bits.
979 Note that if you want processing to continue in the next table,
980 you must execute the
<code>next
</code> action after
981 <code>ct_commit
</code>. You may also leave out
<code>next
</code>
982 which will commit connection tracking state, and then drop the
983 packet. This could be useful for setting
<code>ct_mark
</code>
984 on a connection tracking entry before dropping a packet,
989 <dt><code>ct_dnat;
</code></dt>
990 <dt><code>ct_dnat(
<var>IP
</var>);
</code></dt>
993 <code>ct_dnat
</code> sends the packet through the DNAT zone in
994 connection tracking table to unDNAT any packet that was DNATed in
995 the opposite direction. The packet is then automatically sent to
996 to the next tables as if followed by
<code>next;
</code> action.
997 The next tables will see the changes in the packet caused by
998 the connection tracker.
1001 <code>ct_dnat(
<var>IP
</var>)
</code> sends the packet through the
1002 DNAT zone to change the destination IP address of the packet to
1003 the one provided inside the parentheses and commits the connection.
1004 The packet is then automatically sent to the next tables as if
1005 followed by
<code>next;
</code> action. The next tables will see
1006 the changes in the packet caused by the connection tracker.
1010 <dt><code>ct_snat;
</code></dt>
1011 <dt><code>ct_snat(
<var>IP
</var>);
</code></dt>
1014 <code>ct_snat
</code> sends the packet through the SNAT zone to
1015 unSNAT any packet that was SNATed in the opposite direction. If
1016 the packet needs to be sent to the next tables, then it should be
1017 followed by a
<code>next;
</code> action. The next tables will not
1018 see the changes in the packet caused by the connection tracker.
1021 <code>ct_snat(
<var>IP
</var>)
</code> sends the packet through the
1022 SNAT zone to change the source IP address of the packet to
1023 the one provided inside the parenthesis and commits the connection.
1024 The packet is then automatically sent to the next tables as if
1025 followed by
<code>next;
</code> action. The next tables will see the
1026 changes in the packet caused by the connection tracker.
1030 <dt><code>arp {
<var>action
</var>;
</code>...
<code> };
</code></dt>
1033 Temporarily replaces the IPv4 packet being processed by an ARP
1034 packet and executes each nested
<var>action
</var> on the ARP
1035 packet. Actions following the
<var>arp
</var> action, if any, apply
1036 to the original, unmodified packet.
1040 The ARP packet that this action operates on is initialized based on
1041 the IPv4 packet being processed, as follows. These are default
1042 values that the nested actions will probably want to change:
1046 <li><code>eth.src
</code> unchanged
</li>
1047 <li><code>eth.dst
</code> unchanged
</li>
1048 <li><code>eth.type =
0x0806</code></li>
1049 <li><code>arp.op =
1</code> (ARP request)
</li>
1050 <li><code>arp.sha
</code> copied from
<code>eth.src
</code></li>
1051 <li><code>arp.spa
</code> copied from
<code>ip4.src
</code></li>
1052 <li><code>arp.tha =
00:
00:
00:
00:
00:
00</code></li>
1053 <li><code>arp.tpa
</code> copied from
<code>ip4.dst
</code></li>
1057 The ARP packet has the same VLAN header, if any, as the IP packet
1061 <p><b>Prerequisite:
</b> <code>ip4
</code></p>
1065 <code>na {
<var>action
</var>;
</code>...
<code> };
</code>
1070 Temporarily replaces the IPv6 packet being processed by an IPv6
1071 neighbor advertisement (NA) packet and executes each nested
1072 <var>action
</var> on the NA packet. Actions following the
1073 <var>na
</var> action, if any, apply to the original, unmodified
1078 The NA packet that this action operates on is initialized based on
1079 the IPv6 packet being processed, as follows. These are default
1080 values that the nested actions will probably want to change:
1084 <li><code>eth.dst
</code> exchanged with
<code>eth.src
</code></li>
1085 <li><code>eth.type =
0x86dd</code></li>
1086 <li><code>ip6.dst
</code> copied from
<code>ip6.src
</code></li>
1087 <li><code>ip6.src
</code> copied from
<code>nd.target
</code></li>
1088 <li><code>icmp6.type =
136</code> (Neighbor Advertisement)
</li>
1089 <li><code>nd.target
</code> unchanged
</li>
1090 <li><code>nd.sll =
00:
00:
00:
00:
00:
00</code></li>
1091 <li><code>nd.tll
</code> copied from
<code>eth.dst
</code></li>
1095 The ND packet has the same VLAN header, if any, as the IPv6 packet
1100 <b>Prerequisite:
</b> <code>nd
</code>
1104 <dt><code>get_arp(
<var>P
</var>,
<var>A
</var>);
</code></dt>
1108 <b>Parameters
</b>: logical port string field
<var>P
</var>,
32-bit
1109 IP address field
<var>A
</var>.
1113 Looks up
<var>A
</var> in
<var>P
</var>'s ARP table. If an entry is
1114 found, stores its Ethernet address in
<code>eth.dst
</code>,
1115 otherwise stores
<code>00:
00:
00:
00:
00:
00</code> in
1116 <code>eth.dst
</code>.
1119 <p><b>Example:
</b> <code>get_arp(outport, ip4.dst);
</code></p>
1123 <code>put_arp(
<var>P
</var>,
<var>A
</var>,
<var>E
</var>);
</code>
1128 <b>Parameters
</b>: logical port string field
<var>P
</var>,
32-bit
1129 IP address field
<var>A
</var>,
48-bit Ethernet address field
1134 Adds or updates the entry for IP address
<var>A
</var> in logical
1135 port
<var>P
</var>'s ARP table, setting its Ethernet address to
1139 <p><b>Example:
</b> <code>put_arp(inport, arp.spa, arp.sha);
</code></p>
1143 <code><var>R
</var> = put_dhcp_opts(
<code>offerip
</code> =
<var>IP
</var>,
<var>D1
</var> =
<var>V1
</var>,
<var>D2
</var> =
<var>V2
</var>, ...,
<var>Dn
</var> =
<var>Vn
</var>);
</code>
1148 <b>Parameters
</b>: one or more DHCP option/value pairs, the first
1149 of which must set a value for the offered IP,
<code>offerip
</code>.
1153 <b>Result
</b>: stored to a
1-bit subfield
<var>R
</var>.
1157 Valid only in the ingress pipeline.
1161 When this action is applied to a DHCP request packet (DHCPDISCOVER
1162 or DHCPREQUEST), it changes the packet into a DHCP reply (DHCPOFFER
1163 or DHCPACK, respectively), replaces the options by those specified
1164 as parameters, and stores
1 in
<var>R
</var>.
1168 When this action is applied to a non-DHCP packet or a DHCP packet
1169 that is not DHCPDISCOVER or DHCPREQUEST, it leaves the packet
1170 unchanged and stores
0 in
<var>R
</var>.
1174 The contents of the
<ref table=
"DHCP_Option"/> table control the
1175 DHCP option names and values that this action supports.
1181 reg0[
0] = put_dhcp_opts(offerip =
10.0.0.2, router =
10.0.0.1,
1182 netmask =
255.255.255.0, dns_server = {
8.8.8.8,
7.7.7.7});
1187 <dt><code>ct_lb;
</code></dt>
1188 <dt><code>ct_lb(
</code><var>ip
</var>[
<code>:
</code><var>port
</var>]...
<code>);
</code></dt>
1191 With one or more arguments,
<code>ct_lb
</code> commits the packet
1192 to the connection tracking table and DNATs the packet's destination
1193 IP address (and port) to the IP address or addresses (and optional
1194 ports) specified in the string. If multiple comma-separated IP
1195 addresses are specified, each is given equal weight for picking the
1196 DNAT address. Processing automatically moves on to the next table,
1197 as if
<code>next;
</code> were specified, and later tables act on
1198 the packet as modified by the connection tracker. Connection
1199 tracking state is scoped by the logical port, so overlapping
1200 addresses may be used.
1203 Without arguments,
<code>ct_lb
</code> sends the packet to the
1204 connection tracking table to NAT the packets. If the packet is
1205 part of an established connection that was previously committed to
1206 the connection tracker via
<code>ct_lb(
</code>...
<code>)
</code>, it
1207 will automatically get DNATed to the same IP address as the first
1208 packet in that connection.
1214 The following actions will likely be useful later, but they have not
1215 been thought out carefully.
1219 <dt><code>icmp4 {
<var>action
</var>;
</code>...
<code> };
</code></dt>
1222 Temporarily replaces the IPv4 packet being processed by an ICMPv4
1223 packet and executes each nested
<var>action
</var> on the ICMPv4
1224 packet. Actions following the
<var>icmp4
</var> action, if any,
1225 apply to the original, unmodified packet.
1229 The ICMPv4 packet that this action operates on is initialized based
1230 on the IPv4 packet being processed, as follows. These are default
1231 values that the nested actions will probably want to change.
1232 Ethernet and IPv4 fields not listed here are not changed:
1236 <li><code>ip.proto =
1</code> (ICMPv4)
</li>
1237 <li><code>ip.frag =
0</code> (not a fragment)
</li>
1238 <li><code>icmp4.type =
3</code> (destination unreachable)
</li>
1239 <li><code>icmp4.code =
1</code> (host unreachable)
</li>
1246 <p><b>Prerequisite:
</b> <code>ip4
</code></p>
1249 <dt><code>tcp_reset;
</code></dt>
1252 This action transforms the current TCP packet according to the
1253 following pseudocode:
1260 tcp.ack = tcp.seq + length(tcp.payload);
1267 Then, the action drops all TCP options and payload data, and
1268 updates the TCP checksum.
1275 <p><b>Prerequisite:
</b> <code>tcp
</code></p>
1280 <column name=
"external_ids" key=
"stage-name">
1281 Human-readable name for this flow's stage in the pipeline.
1284 <group title=
"Common Columns">
1285 The overall purpose of these columns is described under
<code>Common
1286 Columns
</code> at the beginning of this document.
1288 <column name=
"external_ids"/>
1292 <table name=
"Multicast_Group" title=
"Logical Port Multicast Groups">
1294 The rows in this table define multicast groups of logical ports.
1295 Multicast groups allow a single packet transmitted over a tunnel to a
1296 hypervisor to be delivered to multiple VMs on that hypervisor, which
1297 uses bandwidth more efficiently.
1301 Each row in this table defines a logical multicast group numbered
<ref
1302 column=
"tunnel_key"/> within
<ref column=
"datapath"/>, whose logical
1303 ports are listed in the
<ref column=
"ports"/> column.
1306 <column name=
"datapath">
1307 The logical datapath in which the multicast group resides.
1310 <column name=
"tunnel_key">
1311 The value used to designate this logical egress port in tunnel
1312 encapsulations. An index forces the key to be unique within the
<ref
1313 column=
"datapath"/>. The unusual range ensures that multicast group IDs
1314 do not overlap with logical port IDs.
1317 <column name=
"name">
1319 The logical multicast group's name. An index forces the name to be
1320 unique within the
<ref column=
"datapath"/>. Logical flows in the
1321 ingress pipeline may output to the group just as for individual logical
1322 ports, by assigning the group's name to
<code>outport
</code> and
1323 executing an
<code>output
</code> action.
1327 Multicast group names and logical port names share a single namespace
1328 and thus should not overlap (but the database schema cannot enforce
1329 this). To try to avoid conflicts,
<code>ovn-northd
</code> uses names
1330 that begin with
<code>_MC_
</code>.
1334 <column name=
"ports">
1335 The logical ports included in the multicast group. All of these ports
1336 must be in the
<ref column=
"datapath"/> logical datapath (but the
1337 database schema cannot enforce this).
1341 <table name=
"Datapath_Binding" title=
"Physical-Logical Datapath Bindings">
1343 Each row in this table identifies physical bindings of a logical
1344 datapath. A logical datapath implements a logical pipeline among the
1345 ports in the
<ref table=
"Port_Binding"/> table associated with it. In
1346 practice, the pipeline in a given logical datapath implements either a
1347 logical switch or a logical router.
1350 <column name=
"tunnel_key">
1351 The tunnel key value to which the logical datapath is bound.
1352 The
<code>Tunnel Encapsulation
</code> section in
1353 <code>ovn-architecture
</code>(
7) describes how tunnel keys are
1354 constructed for each supported encapsulation.
1357 <group title=
"OVN_Northbound Relationship">
1359 Each row in
<ref table=
"Datapath_Binding"/> is associated with some
1360 logical datapath.
<code>ovn-northd
</code> uses these keys to track the
1361 association of a logical datapath with concepts in the
<ref
1362 db=
"OVN_Northbound"/> database.
1365 <column name=
"external_ids" key=
"logical-switch" type='{
"type":
"uuid"}'
>
1366 For a logical datapath that represents a logical switch,
1367 <code>ovn-northd
</code> stores in this key the UUID of the
1368 corresponding
<ref table=
"Logical_Switch" db=
"OVN_Northbound"/> row in
1369 the
<ref db=
"OVN_Northbound"/> database.
1372 <column name=
"external_ids" key=
"logical-router" type='{
"type":
"uuid"}'
>
1373 For a logical datapath that represents a logical router,
1374 <code>ovn-northd
</code> stores in this key the UUID of the
1375 corresponding
<ref table=
"Logical_Router" db=
"OVN_Northbound"/> row in
1376 the
<ref db=
"OVN_Northbound"/> database.
1380 <group title=
"Common Columns">
1381 The overall purpose of these columns is described under
<code>Common
1382 Columns
</code> at the beginning of this document.
1384 <column name=
"external_ids"/>
1388 <table name=
"Port_Binding" title=
"Physical-Logical Port Bindings">
1390 Most rows in this table identify the physical location of a logical port.
1391 (The exceptions are logical patch ports, which do not have any physical
1396 For every
<code>Logical_Switch_Port
</code> record in
1397 <code>OVN_Northbound
</code> database,
<code>ovn-northd
</code>
1398 creates a record in this table.
<code>ovn-northd
</code> populates
1399 and maintains every column except the
<code>chassis
</code> column,
1400 which it leaves empty in new records.
1404 <code>ovn-controller
</code>/
<code>ovn-controller-vtep
</code>
1405 populates the
<code>chassis
</code> column for the records that
1406 identify the logical ports that are located on its hypervisor/gateway,
1407 which
<code>ovn-controller
</code>/
<code>ovn-controller-vtep
</code> in
1408 turn finds out by monitoring the local hypervisor's Open_vSwitch
1409 database, which identifies logical ports via the conventions described
1410 in
<code>IntegrationGuide.md
</code>. (The exceptions are for
1411 <code>Port_Binding
</code> records with
<code>type
</code> of
1412 <code>gateway
</code>, whose locations are identified by
1413 <code>ovn-northd
</code> via the
<code>options:gateway-chassis
</code>
1414 column in this table.
<code>ovn-controller
</code> is still responsible
1415 to populate the
<code>chassis
</code> column.)
1419 When a chassis shuts down gracefully, it should clean up the
1420 <code>chassis
</code> column that it previously had populated.
1421 (This is not critical because resources hosted on the chassis are equally
1422 unreachable regardless of whether their rows are present.) To handle the
1423 case where a VM is shut down abruptly on one chassis, then brought up
1424 again on a different one,
1425 <code>ovn-controller
</code>/
<code>ovn-controller-vtep
</code> must
1426 overwrite the
<code>chassis
</code> column with new information.
1429 <group title=
"Core Features">
1430 <column name=
"datapath">
1431 The logical datapath to which the logical port belongs.
1434 <column name=
"logical_port">
1435 A logical port, taken from
<ref table=
"Logical_Switch_Port"
1436 column=
"name" db=
"OVN_Northbound"/> in the OVN_Northbound
1437 database's
<ref table=
"Logical_Switch_Port" db=
"OVN_Northbound"/>
1438 table. OVN does not prescribe a particular format for the
1442 <column name=
"chassis">
1443 The meaning of this column depends on the value of the
<ref column=
"type"/>
1444 column. This is the meaning for each
<ref column=
"type"/>
1447 <dt>(empty string)
</dt>
1449 The physical location of the logical port. To successfully identify a
1450 chassis, this column must be a
<ref table=
"Chassis"/> record. This is
1451 populated by
<code>ovn-controller
</code>.
1456 The physical location of the hardware_vtep gateway. To successfully
1457 identify a chassis, this column must be a
<ref table=
"Chassis"/> record.
1458 This is populated by
<code>ovn-controller-vtep
</code>.
1463 Always empty. A localnet port is realized on every chassis that has
1464 connectivity to the corresponding physical network.
1469 The physical location of the L3 gateway. To successfully identify a
1470 chassis, this column must be a
<ref table=
"Chassis"/> record. This is
1471 populated by
<code>ovn-controller
</code> based on the value of
1472 the
<code>options:gateway-chassis
</code> column in this table.
1477 The physical location of this L2 gateway. To successfully identify a
1478 chassis, this column must be a
<ref table=
"Chassis"/> record.
1479 This is populated by an entity external to OVN, either manually or by
1486 <column name=
"tunnel_key">
1488 A number that represents the logical port in the key (e.g. STT key or
1489 Geneve TLV) field carried within tunnel protocol packets.
1493 The tunnel ID must be unique within the scope of a logical datapath.
1499 The Ethernet address or addresses used as a source address on the
1500 logical port, each in the form
1501 <var>xx
</var>:
<var>xx
</var>:
<var>xx
</var>:
<var>xx
</var>:
<var>xx
</var>:
<var>xx
</var>.
1502 The string
<code>unknown
</code> is also allowed to indicate that the
1503 logical port has an unknown set of (additional) source addresses.
1507 A VM interface would ordinarily have a single Ethernet address. A
1508 gateway port might initially only have
<code>unknown
</code>, and then
1509 add MAC addresses to the set as it learns new source addresses.
1513 <column name=
"type">
1515 A type for this logical port. Logical ports can be used to model other
1516 types of connectivity into an OVN logical switch. The following types
1521 <dt>(empty string)
</dt>
1522 <dd>VM (or VIF) interface.
</dd>
1524 <dt><code>patch
</code></dt>
1526 One of a pair of logical ports that act as if connected by a patch
1527 cable. Useful for connecting two logical datapaths, e.g. to connect
1528 a logical router to a logical switch or to another logical router.
1531 <dt><code>gateway
</code></dt>
1533 One of a pair of logical ports that act as if connected by a patch
1534 cable across multiple chassis. Useful for connecting a logical
1535 switch with a Gateway router (which is only resident on a
1536 particular chassis).
1539 <dt><code>localnet
</code></dt>
1541 A connection to a locally accessible network from each
1542 <code>ovn-controller
</code> instance. A logical switch can only
1543 have a single
<code>localnet
</code> port attached. This is used
1544 to model direct connectivity to an existing network.
1547 <dt><code>l2gateway
</code></dt>
1549 An L2 connection to a physical network. The chassis this
1550 <ref table=
"Port_Binding"/> is bound to will serve as
1551 an L2 gateway to the network named by
1552 <ref column=
"options" table=
"Port_Binding"/>:
<code>network_name
</code>.
1555 <dt><code>vtep
</code></dt>
1557 A port to a logical switch on a VTEP gateway chassis. In order to
1558 get this port correctly recognized by the OVN controller, the
<ref
1560 table=
"Port_Binding"/>:
<code>vtep-physical-switch
</code> and
<ref
1562 table=
"Port_Binding"/>:
<code>vtep-logical-switch
</code> must also
1569 <group title=
"Patch Options">
1571 These options apply to logical ports with
<ref column=
"type"/> of
1575 <column name=
"options" key=
"peer">
1576 The
<ref column=
"logical_port"/> in the
<ref table=
"Port_Binding"/>
1577 record for the other side of the patch. The named
<ref
1578 column=
"logical_port"/> must specify this
<ref column=
"logical_port"/>
1579 in its own
<code>peer
</code> option. That is, the two patch logical
1580 ports must have reversed
<ref column=
"logical_port"/> and
1581 <code>peer
</code> values.
1585 <group title=
"L3 Gateway Options">
1587 These options apply to logical ports with
<ref column=
"type"/> of
1588 <code>gateway
</code>.
1591 <column name=
"options" key=
"peer">
1592 The
<ref column=
"logical_port"/> in the
<ref table=
"Port_Binding"/>
1593 record for the other side of the 'gateway' port. The named
<ref
1594 column=
"logical_port"/> must specify this
<ref column=
"logical_port"/>
1595 in its own
<code>peer
</code> option. That is, the two 'gateway'
1596 logical ports must have reversed
<ref column=
"logical_port"/> and
1597 <code>peer
</code> values.
1600 <column name=
"options" key=
"gateway-chassis">
1601 The
<code>chassis
</code> in which the port resides.
1605 <group title=
"Localnet Options">
1607 These options apply to logical ports with
<ref column=
"type"/> of
1608 <code>localnet
</code>.
1611 <column name=
"options" key=
"network_name">
1612 Required.
<code>ovn-controller
</code> uses the configuration entry
1613 <code>ovn-bridge-mappings
</code> to determine how to connect to this
1614 network.
<code>ovn-bridge-mappings
</code> is a list of network names
1615 mapped to a local OVS bridge that provides access to that network. An
1616 example of configuring
<code>ovn-bridge-mappings
</code> would be:
1618 <pre>$ ovs-vsctl set open . external-ids:ovn-bridge-mappings=physnet1:br-eth0,physnet2:br-eth1
</pre>
1621 When a logical switch has a
<code>localnet
</code> port attached,
1622 every chassis that may have a local vif attached to that logical
1623 switch must have a bridge mapping configured to reach that
1624 <code>localnet
</code>. Traffic that arrives on a
1625 <code>localnet
</code> port is never forwarded over a tunnel to
1631 If set, indicates that the port represents a connection to a specific
1632 VLAN on a locally accessible network. The VLAN ID is used to match
1633 incoming traffic and is also added to outgoing traffic.
1637 <group title=
"L2 Gateway Options">
1639 These options apply to logical ports with
<ref column=
"type"/> of
1640 <code>l2gateway
</code>.
1643 <column name=
"options" key=
"network_name">
1644 Required.
<code>ovn-controller
</code> uses the configuration entry
1645 <code>ovn-bridge-mappings
</code> to determine how to connect to this
1646 network.
<code>ovn-bridge-mappings
</code> is a list of network names
1647 mapped to a local OVS bridge that provides access to that network. An
1648 example of configuring
<code>ovn-bridge-mappings
</code> would be:
1650 <pre>$ ovs-vsctl set open . external-ids:ovn-bridge-mappings=physnet1:br-eth0,physnet2:br-eth1
</pre>
1653 When a logical switch has a
<code>l2gateway
</code> port attached,
1654 the chassis that the
<code>l2gateway
</code> port is bound to
1655 must have a bridge mapping configured to reach the network
1656 identified by
<code>network_name
</code>.
1661 If set, indicates that the gateway is connected to a specific
1662 VLAN on the physical network. The VLAN ID is used to match
1663 incoming traffic and is also added to outgoing traffic.
1667 <group title=
"VTEP Options">
1669 These options apply to logical ports with
<ref column=
"type"/> of
1673 <column name=
"options" key=
"vtep-physical-switch">
1674 Required. The name of the VTEP gateway.
1677 <column name=
"options" key=
"vtep-logical-switch">
1678 Required. A logical switch name connected by the VTEP gateway. Must
1679 be set when
<ref column=
"type"/> is
<code>vtep
</code>.
1683 <group title=
"VMI (or VIF) Options">
1685 These options apply to logical ports with
<ref column=
"type"/> having
1689 <column name=
"options" key=
"policing_rate">
1690 If set, indicates the maximum rate for data sent from this interface,
1691 in kbps. Data exceeding this rate is dropped.
1694 <column name=
"options" key=
"policing_burst">
1695 If set, indicates the maximum burst size for data sent from this
1700 <group title=
"Nested Containers">
1702 These columns support containers nested within a VM. Specifically,
1703 they are used when
<ref column=
"type"/> is empty and
<ref
1704 column=
"logical_port"/> identifies the interface of a container spawned
1705 inside a VM. They are empty for containers or VMs that run directly on
1709 <column name=
"parent_port">
1711 <ref table=
"Logical_Switch_Port" column=
"parent_name"
1712 db=
"OVN_Northbound"/> in the OVN_Northbound database's
1713 <ref table=
"Logical_Switch_Port" db=
"OVN_Northbound"/> table.
1718 Identifies the VLAN tag in the network traffic associated with that
1719 container's network interface.
1723 This column is used for a different purpose when
<ref column=
"type"/>
1724 is
<code>localnet
</code> (see
<code>Localnet Options
</code>, above)
1725 or
<code>l2gateway
</code> (see
<code>L2 Gateway Options
</code>, above).
1731 <table name=
"MAC_Binding" title=
"IP to MAC bindings">
1733 Each row in this table specifies a binding from an IP address to an
1734 Ethernet address that has been discovered through ARP (for IPv4) or
1735 neighbor discovery (for IPv6). This table is primarily used to discover
1736 bindings on physical networks, because IP-to-MAC bindings for virtual
1737 machines are usually populated statically into the
<ref
1738 table=
"Port_Binding"/> table.
1742 This table expresses a functional relationship:
<ref
1743 table=
"MAC_Binding"/>(
<ref column=
"logical_port"/>,
<ref column=
"ip"/>) =
1744 <ref column=
"mac"/>.
1748 In outline, the lifetime of a logical router's MAC binding looks like
1754 On hypervisor
1, a logical router determines that a packet should be
1755 forwarded to IP address
<var>A
</var> on one of its router ports. It
1756 uses its logical flow table to determine that
<var>A
</var> lacks a
1757 static IP-to-MAC binding and the
<code>get_arp
</code> action to
1758 determine that it lacks a dynamic IP-to-MAC binding.
1762 Using an OVN logical
<code>arp
</code> action, the logical router
1763 generates and sends a broadcast ARP request to the router port. It
1764 drops the IP packet.
1768 The logical switch attached to the router port delivers the ARP request
1769 to all of its ports. (It might make sense to deliver it only to ports
1770 that have no static IP-to-MAC bindings, but this could also be
1771 surprising behavior.)
1775 A host or VM on hypervisor
2 (which might be the same as hypervisor
1)
1776 attached to the logical switch owns the IP address in question. It
1777 composes an ARP reply and unicasts it to the logical router port's
1782 The logical switch delivers the ARP reply to the logical router port.
1786 The logical router flow table executes a
<code>put_arp
</code> action.
1787 To record the IP-to-MAC binding,
<code>ovn-controller
</code> adds a row
1788 to the
<ref table=
"MAC_Binding"/> table.
1792 On hypervisor
1,
<code>ovn-controller
</code> receives the updated
<ref
1793 table=
"MAC_Binding"/> table from the OVN southbound database. The next
1794 packet destined to
<var>A
</var> through the logical router is sent
1795 directly to the bound Ethernet address.
1799 <column name=
"logical_port">
1800 The logical port on which the binding was discovered.
1804 The bound IP address.
1808 The Ethernet address to which the IP is bound.
1812 <table name=
"DHCP_Options" title=
"DHCP Options supported by native OVN DHCP">
1814 Each row in this table stores the DHCP Options supported by native OVN
1815 DHCP.
<code>ovn-northd
</code> populates this table with the supported
1816 DHCP options.
<code>ovn-controller
</code> looks up this table to get the
1817 DHCP codes of the DHCP options defined in the
"put_dhcp_opts" action.
1818 Please refer to the RFC
2132 <code>"https://tools.ietf.org/html/rfc2132"</code>
1819 for the possible list of DHCP options that can be defined here.
1822 <column name=
"name">
1824 Name of the DHCP option.
1828 Example.
name=
"router"
1832 <column name=
"code">
1834 DHCP option code for the DHCP option as defined in the RFC
2132.
1842 <column name=
"type">
1844 Data type of the DHCP option code.
1848 <dt><code>value: bool
</code></dt>
1851 This indicates that the value of the DHCP option is a bool.
1855 Example.
"name=ip_forward_enable",
"code=19",
"type=bool".
1859 put_dhcp_opts(..., ip_forward_enable =
1,...)
1863 <dt><code>value: uint8
</code></dt>
1866 This indicates that the value of the DHCP option is an unsigned
1871 Example.
"name=default_ttl",
"code=23",
"type=uint8".
1875 put_dhcp_opts(..., default_ttl =
50,...)
1879 <dt><code>value: uint16
</code></dt>
1882 This indicates that the value of the DHCP option is an unsigned
1887 Example.
"name=mtu",
"code=26",
"type=uint16".
1891 put_dhcp_opts(..., mtu =
1450,...)
1895 <dt><code>value: uint32
</code></dt>
1898 This indicates that the value of the DHCP option is an unsigned
1903 Example.
"name=lease_time",
"code=51",
"type=uint32".
1907 put_dhcp_opts(..., lease_time =
86400,...)
1911 <dt><code>value: ipv4
</code></dt>
1914 This indicates that the value of the DHCP option is an IPv4
1915 address or addresses.
1919 Example.
"name=router",
"code=3",
"type=ipv4".
1923 put_dhcp_opts(..., router =
10.0.0.1,...)
1927 Example.
"name=dns_server",
"code=6",
"type=ipv4".
1931 put_dhcp_opts(..., dns_server = {
8.8.8.8 7.7.7.7},...)
1935 <dt><code>value: static_routes
</code></dt>
1938 This indicates that the value of the DHCP option contains a pair of
1939 IPv4 route and next hop addresses.
1943 Example.
"name=classless_static_route",
"code=121",
"type=static_routes".
1947 put_dhcp_opts(..., classless_static_route = {
30.0.0.0/
24,
10.0.0.4,
0.0.0.0/
0,
10.0.0.1}...)
1951 <dt><code>value: str
</code></dt>
1954 This indicates that the value of the DHCP option is a string.
1958 Example.
"name=host_name",
"code=12",
"type=str".