<h2>Database Structure</h2>
<p>
- The OVN Southbound database contains three classes of data with
+ The OVN Southbound database contains classes of data with
different properties, as described in the sections below.
</p>
data.
</p>
- <h3>Bindings data</h3>
+ <h3>Logical-physical bindings</h3>
<p>
- Bindings data link logical and physical components. They show the current
+ These tables link logical and physical components. They show the current
placement of logical components (such as VMs and VIFs) onto chassis, and
map logical entities to the values that represent them in tunnel
encapsulations.
</p>
<p>
- Bindings change frequently, at least every time a VM powers up or down
+ These tables change frequently, at least every time a VM powers up or down
or migrates, and especially quickly in a container environment. The
amount of data per VM (or VIF) is small.
</p>
contain binding data.
</p>
+ <h3>MAC bindings</h3>
+
+ <p>
+ The <ref table="MAC_Binding"/> table tracks the bindings from IP addresses
+ to Ethernet addresses that are dynamically discovered using ARP (for IPv4)
+ and neighbor discovery (for IPv6). Usually, IP-to-MAC bindings for virtual
+ machines are statically populated into the <ref table="Port_Binding"/>
+ table, so <ref table="MAC_Binding"/> is primarily used to discover bindings
+ on physical networks.
+ </p>
+
<h2>Common Columns</h2>
<p>
</p>
<column name="name">
- A chassis name, taken from <ref key="system-id" table="Open_vSwitch"
- column="external_ids" db="Open_vSwitch"/> in the Open_vSwitch
- database's <ref table="Open_vSwitch" db="Open_vSwitch"/> table. OVN does
- not prescribe a particular format for chassis names.
+ OVN does not prescribe a particular format for chassis names.
+ ovn-controller populates this column using <ref key="system-id"
+ table="Open_vSwitch" column="external_ids" db="Open_vSwitch"/>
+ in the Open_vSwitch database's <ref table="Open_vSwitch"
+ db="Open_vSwitch"/> table. ovn-controller-vtep populates this
+ column with <ref table="Physical_Switch" column="name"
+ db="hardware_vtep"/> in the hardware_vtep database's
+ <ref table="Physical_Switch" db="hardware_vtep"/> table.
+ </column>
+
+ <column name="hostname">
+ The hostname of the chassis, if applicable. ovn-controller will populate
+ this column with the hostname of the host it is running on.
+ ovn-controller-vtep will leave this column empty.
</column>
+ <column name="external_ids" key="ovn-bridge-mappings">
+ <code>ovn-controller</code> populates this key with the set of bridge
+ mappings it has been configured to use. Other applications should treat
+ this key as read-only. See <code>ovn-controller</code>(8) for more
+ information.
+ </column>
+
+ <group title="Common Columns">
+ The overall purpose of these columns is described under <code>Common
+ Columns</code> at the beginning of this document.
+
+ <column name="external_ids"/>
+ </group>
+
<group title="Encapsulation Configuration">
<p>
OVN uses encapsulation to transmit logical dataplane packets
The default action when no flow matches is to drop packets.
</p>
- <p><em>Logical Life Cycle of a Packet</em></p>
+ <p><em>Architectural Logical Life Cycle of a Packet</em></p>
<p>
This following description focuses on the life cycle of a packet through
a logical datapath, ignoring physical details of the implementation.
- Please refer to <em>Life Cycle of a Packet</em> in
+ Please refer to <em>Architectural Physical Life Cycle of a Packet</em> in
<code>ovn-architecture</code>(7) for the physical information.
</p>
<li><code>icmp4.type</code> <code>icmp4.code</code></li>
<li><code>icmp6.type</code> <code>icmp6.code</code></li>
<li><code>nd.target</code> <code>nd.sll</code> <code>nd.tll</code></li>
+ <li><code>ct_mark</code> <code>ct_label</code></li>
<li>
<p>
<code>ct_state</code>, which has the following Boolean subfields:
</p>
<ul>
+ <li><code>eth.bcast</code> expands to <code>eth.dst == ff:ff:ff:ff:ff:ff</code></li>
+ <li><code>eth.mcast</code> expands to <code>eth.dst[40]</code></li>
<li><code>vlan.present</code> expands to <code>vlan.tci[12]</code></li>
<li><code>ip4</code> expands to <code>eth.type == 0x800</code></li>
+ <li><code>ip4.mcast</code> expands to <code>ip4.dst[28..31] == 0xe</code></li>
<li><code>ip6</code> expands to <code>eth.type == 0x86dd</code></li>
<li><code>ip</code> expands to <code>ip4 || ip6</code></li>
<li><code>icmp4</code> expands to <code>ip4 && ip.proto == 1</code></li>
<p>
Output to the input port is implicitly dropped, that is,
<code>output</code> becomes a no-op if <code>outport</code> ==
- <code>inport</code>.
+ <code>inport</code>. Occasionally it may be useful to override
+ this behavior, e.g. to send an ARP reply to an ARP request; to do
+ so, use <code>inport = "";</code> to set the logical input port to
+ an empty string (which should not be used as the name of any
+ logical port).
</p>
</dd>
</p>
</dd>
+ <dt><code>ip.ttl--;</code></dt>
+ <dd>
+ <p>
+ Decrements the IPv4 or IPv6 TTL. If this would make the TTL zero
+ or negative, then processing of the packet halts; no further
+ actions are processed. (To properly handle such cases, a
+ higher-priority flow should match on
+ <code>ip.ttl == {0, 1};</code>.)
+ </p>
+
+ <p><b>Prerequisite:</b> <code>ip</code></p>
+ </dd>
+
<dt><code>ct_next;</code></dt>
<dd>
<p>
<dt><code>ct_commit;</code></dt>
<dd>
- Commit the flow to the connection tracking entry associated
- with it by a previous call to <code>ct_next</code>.
+ <p>
+ Commit the flow to the connection tracking entry associated
+ with it by a previous call to <code>ct_next</code>.
+ </p>
+ <p>
+ Note that if you want processing to continue in the next table,
+ you must execute the <code>next</code> action after
+ <code>ct_commit</code>.
+ </p>
+ </dd>
+
+ <dt><code>ct_dnat;</code></dt>
+ <dt><code>ct_dnat(<var>IP</var>);</code></dt>
+ <dd>
+ <p>
+ <code>ct_dnat</code> sends the packet through the DNAT zone in
+ connection tracking table to unDNAT any packet that was DNATed in
+ the opposite direction. The packet is then automatically sent to
+ to the next tables as if followed by <code>next;</code> action.
+ The next tables will see the changes in the packet caused by
+ the connection tracker.
+ </p>
+ <p>
+ <code>ct_dnat(<var>IP</var>)</code> sends the packet through the
+ DNAT zone to change the destination IP address of the packet to
+ the one provided inside the parenthesis and commits the connection.
+ The packet is then automatically sent to the next tables as if
+ followed by <code>next;</code> action. The next tables will see
+ the changes in the packet caused by the connection tracker.
+ </p>
+ </dd>
+
+ <dt><code>ct_snat;</code></dt>
+ <dt><code>ct_snat(<var>IP</var>);</code></dt>
+ <dd>
+ <p>
+ <code>ct_snat</code> sends the packet through the SNAT zone to
+ unSNAT any packet that was SNATed in the opposite direction. If
+ the packet needs to be sent to the next tables, then it should be
+ followed by a <code>next;</code> action. The next tables will not
+ see the changes in the packet caused by the connection tracker.
+ </p>
+ <p>
+ <code>ct_snat(<var>IP</var>)</code> sends the packet through the
+ SNAT zone to change the source IP address of the packet to
+ the one provided inside the parenthesis and commits the connection.
+ The packet is then automatically sent to the next tables as if
+ followed by <code>next;</code> action. The next tables will see the
+ changes in the packet caused by the connection tracker.
+ </p>
+ </dd>
+
+ <dt><code>arp { <var>action</var>; </code>...<code> };</code></dt>
+ <dd>
+ <p>
+ Temporarily replaces the IPv4 packet being processed by an ARP
+ packet and executes each nested <var>action</var> on the ARP
+ packet. Actions following the <var>arp</var> action, if any, apply
+ to the original, unmodified packet.
+ </p>
+
+ <p>
+ The ARP packet that this action operates on is initialized based on
+ the IPv4 packet being processed, as follows. These are default
+ values that the nested actions will probably want to change:
+ </p>
+
+ <ul>
+ <li><code>eth.src</code> unchanged</li>
+ <li><code>eth.dst</code> unchanged</li>
+ <li><code>eth.type = 0x0806</code></li>
+ <li><code>arp.op = 1</code> (ARP request)</li>
+ <li><code>arp.sha</code> copied from <code>eth.src</code></li>
+ <li><code>arp.spa</code> copied from <code>ip4.src</code></li>
+ <li><code>arp.tha = 00:00:00:00:00:00</code></li>
+ <li><code>arp.tpa</code> copied from <code>ip4.dst</code></li>
+ </ul>
+
+ <p>
+ The ARP packet has the same VLAN header, if any, as the IP packet
+ it replaces.
+ </p>
+
+ <p><b>Prerequisite:</b> <code>ip4</code></p>
+ </dd>
+
+ <dt><code>get_arp(<var>P</var>, <var>A</var>);</code></dt>
+
+ <dd>
+ <p>
+ <b>Parameters</b>: logical port string field <var>P</var>, 32-bit
+ IP address field <var>A</var>.
+ </p>
+
+ <p>
+ Looks up <var>A</var> in <var>P</var>'s ARP table. If an entry is
+ found, stores its Ethernet address in <code>eth.dst</code>,
+ otherwise stores <code>00:00:00:00:00:00</code> in
+ <code>eth.dst</code>.
+ </p>
+
+ <p><b>Example:</b> <code>get_arp(outport, ip4.dst);</code></p>
+ </dd>
+
+ <dt>
+ <code>put_arp(<var>P</var>, <var>A</var>, <var>E</var>);</code>
+ </dt>
+
+ <dd>
+ <p>
+ <b>Parameters</b>: logical port string field <var>P</var>, 32-bit
+ IP address field <var>A</var>, 48-bit Ethernet address field
+ <var>E</var>.
+ </p>
+
+ <p>
+ Adds or updates the entry for IP address <var>A</var> in logical
+ port <var>P</var>'s ARP table, setting its Ethernet address to
+ <var>E</var>.
+ </p>
+
+ <p><b>Example:</b> <code>put_arp(inport, arp.spa, arp.sha);</code></p>
</dd>
</dl>
</p>
<dl>
- <dt><code>learn</code></dt>
-
- <dt><code>dec_ttl { <var>action</var>, </code>...<code> } { <var>action</var>; </code>...<code>};</code></dt>
+ <dt><code>icmp4 { <var>action</var>; </code>...<code> };</code></dt>
<dd>
- decrement TTL; execute first set of actions if
- successful, second set if TTL decrement fails
+ <p>
+ Temporarily replaces the IPv4 packet being processed by an ICMPv4
+ packet and executes each nested <var>action</var> on the ICMPv4
+ packet. Actions following the <var>icmp4</var> action, if any,
+ apply to the original, unmodified packet.
+ </p>
+
+ <p>
+ The ICMPv4 packet that this action operates on is initialized based
+ on the IPv4 packet being processed, as follows. These are default
+ values that the nested actions will probably want to change.
+ Ethernet and IPv4 fields not listed here are not changed:
+ </p>
+
+ <ul>
+ <li><code>ip.proto = 1</code> (ICMPv4)</li>
+ <li><code>ip.frag = 0</code> (not a fragment)</li>
+ <li><code>icmp4.type = 3</code> (destination unreachable)</li>
+ <li><code>icmp4.code = 1</code> (host unreachable)</li>
+ </ul>
+
+ <p>
+ Details TBD.
+ </p>
+
+ <p><b>Prerequisite:</b> <code>ip4</code></p>
</dd>
- <dt><code>icmp_reply { <var>action</var>, </code>...<code> };</code></dt>
- <dd>generate ICMP reply from packet, execute <var>action</var>s</dd>
+ <dt><code>tcp_reset;</code></dt>
+ <dd>
+ <p>
+ This action transforms the current TCP packet according to the
+ following pseudocode:
+ </p>
- <dt><code>arp { <var>action</var>, </code>...<code> }</code></dt>
- <dd>generate ARP from packet, execute <var>action</var>s</dd>
+ <pre>
+if (tcp.ack) {
+ tcp.seq = tcp.ack;
+} else {
+ tcp.ack = tcp.seq + length(tcp.payload);
+ tcp.seq = 0;
+}
+tcp.flags = RST;
+</pre>
+
+ <p>
+ Then, the action drops all TCP options and payload data, and
+ updates the TCP checksum.
+ </p>
+
+ <p>
+ Details TBD.
+ </p>
+
+ <p><b>Prerequisite:</b> <code>tcp</code></p>
+ </dd>
</dl>
</column>
constructed for each supported encapsulation.
</column>
- <column name="external_ids" key="logical-switch" type='{"type": "uuid"}'>
- Each row in <ref table="Datapath_Binding"/> is associated with some
- logical datapath. <code>ovn-northd</code> uses this key to store the
- UUID of the logical datapath <ref table="Logical_Switch"
- db="OVN_Northbound"/> row in the <ref db="OVN_Northbound"/> database.
- </column>
+ <group title="OVN_Northbound Relationship">
+ <p>
+ Each row in <ref table="Datapath_Binding"/> is associated with some
+ logical datapath. <code>ovn-northd</code> uses these keys to track the
+ association of a logical datapath with concepts in the <ref
+ db="OVN_Northbound"/> database.
+ </p>
+
+ <column name="external_ids" key="logical-switch" type='{"type": "uuid"}'>
+ For a logical datapath that represents a logical switch,
+ <code>ovn-northd</code> stores in this key the UUID of the
+ corresponding <ref table="Logical_Switch" db="OVN_Northbound"/> row in
+ the <ref db="OVN_Northbound"/> database.
+ </column>
+
+ <column name="external_ids" key="logical-router" type='{"type": "uuid"}'>
+ For a logical datapath that represents a logical router,
+ <code>ovn-northd</code> stores in this key the UUID of the
+ corresponding <ref table="Logical_Router" db="OVN_Northbound"/> row in
+ the <ref db="OVN_Northbound"/> database.
+ </column>
+ </group>
<group title="Common Columns">
The overall purpose of these columns is described under <code>Common
<table name="Port_Binding" title="Physical-Logical Port Bindings">
<p>
- Each row in this table identifies the physical location of a logical
- port.
+ Most rows in this table identify the physical location of a logical port.
+ (The exceptions are logical patch ports, which do not have any physical
+ location.)
</p>
<p>
- For every <code>Logical_Port</code> record in <code>OVN_Northbound</code>
- database, <code>ovn-northd</code> creates a record in this table.
- <code>ovn-northd</code> populates and maintains every column except
- the <code>chassis</code> column, which it leaves empty in new records.
+ For every <code>Logical_Switch_Port</code> record in
+ <code>OVN_Northbound</code> database, <code>ovn-northd</code>
+ creates a record in this table. <code>ovn-northd</code> populates
+ and maintains every column except the <code>chassis</code> column,
+ which it leaves empty in new records.
</p>
<p>
which <code>ovn-controller</code>/<code>ovn-controller-vtep</code> in
turn finds out by monitoring the local hypervisor's Open_vSwitch
database, which identifies logical ports via the conventions described
- in <code>IntegrationGuide.md</code>.
+ in <code>IntegrationGuide.md</code>. (The exceptions are for
+ <code>Port_Binding</code> records with <code>type</code> of
+ <code>gateway</code>, whose locations are identified by
+ <code>ovn-northd</code> via the <code>options:gateway-chassis</code>
+ column in this table. <code>ovn-controller</code> is still responsible
+ to populate the <code>chassis</code> column.)
</p>
<p>
</column>
<column name="logical_port">
- A logical port, taken from <ref table="Logical_Port" column="name"
- db="OVN_Northbound"/> in the OVN_Northbound database's <ref
- table="Logical_Port" db="OVN_Northbound"/> table. OVN does not
- prescribe a particular format for the logical port ID.
+ A logical port, taken from <ref table="Logical_Switch_Port"
+ column="name" db="OVN_Northbound"/> in the OVN_Northbound
+ database's <ref table="Logical_Switch_Port" db="OVN_Northbound"/>
+ table. OVN does not prescribe a particular format for the
+ logical port ID.
</column>
<column name="chassis">
<dl>
<dt>(empty string)</dt>
<dd>VM (or VIF) interface.</dd>
+
+ <dt><code>patch</code></dt>
+ <dd>
+ One of a pair of logical ports that act as if connected by a patch
+ cable. Useful for connecting two logical datapaths, e.g. to connect
+ a logical router to a logical switch or to another logical router.
+ </dd>
+
+ <dt><code>gateway</code></dt>
+ <dd>
+ One of a pair of logical ports that act as if connected by a patch
+ cable across multiple chassis. Useful for connecting a logical
+ switch with a Gateway router (which is only resident on a
+ particular chassis).
+ </dd>
+
<dt><code>localnet</code></dt>
<dd>
A connection to a locally accessible network from each
<code>ovn-controller</code> instance. A logical switch can only
- have a single <code>localnet</code> port attached and at most one
- regular logical port. This is used to model direct connectivity to
- an existing network.
+ have a single <code>localnet</code> port attached. This is used
+ to model direct connectivity to an existing network.
</dd>
<dt><code>vtep</code></dt>
</column>
</group>
+ <group title="Patch Options">
+ <p>
+ These options apply to logical ports with <ref column="type"/> of
+ <code>patch</code>.
+ </p>
+
+ <column name="options" key="peer">
+ The <ref column="logical_port"/> in the <ref table="Port_Binding"/>
+ record for the other side of the patch. The named <ref
+ column="logical_port"/> must specify this <ref column="logical_port"/>
+ in its own <code>peer</code> option. That is, the two patch logical
+ ports must have reversed <ref column="logical_port"/> and
+ <code>peer</code> values.
+ </column>
+ </group>
+
+ <group title="Gateway Options">
+ <p>
+ These options apply to logical ports with <ref column="type"/> of
+ <code>gateway</code>.
+ </p>
+
+ <column name="options" key="peer">
+ The <ref column="logical_port"/> in the <ref table="Port_Binding"/>
+ record for the other side of the 'gateway' port. The named <ref
+ column="logical_port"/> must specify this <ref column="logical_port"/>
+ in its own <code>peer</code> option. That is, the two 'gateway'
+ logical ports must have reversed <ref column="logical_port"/> and
+ <code>peer</code> values.
+ </column>
+
+ <column name="options" key="gateway-chassis">
+ The <code>chassis</code> in which the port resides.
+ </column>
+ </group>
+
<group title="Localnet Options">
<p>
These options apply to logical ports with <ref column="type"/> of
</column>
</group>
+ <group title="VMI (or VIF) Options">
+ <p>
+ These options apply to logical ports with <ref column="type"/> having
+ (empty string)
+ </p>
+
+ <column name="options" key="policing_rate">
+ If set, indicates the maximum rate for data sent from this interface,
+ in kbps. Data exceeding this rate is dropped.
+ </column>
+
+ <column name="options" key="policing_burst">
+ If set, indicates the maximum burst size for data sent from this
+ interface, in kb.
+ </column>
+ </group>
+
<group title="Nested Containers">
<p>
These columns support containers nested within a VM. Specifically,
<column name="parent_port">
This is taken from
- <ref table="Logical_Port" column="parent_name" db="OVN_Northbound"/>
- in the OVN_Northbound database's <ref table="Logical_Port"
- db="OVN_Northbound"/> table.
+ <ref table="Logical_Switch_Port" column="parent_name"
+ db="OVN_Northbound"/> in the OVN_Northbound database's
+ <ref table="Logical_Switch_Port" db="OVN_Northbound"/> table.
</column>
<column name="tag">
</column>
</group>
</table>
+
+ <table name="MAC_Binding" title="IP to MAC bindings">
+ <p>
+ Each row in this table specifies a binding from an IP address to an
+ Ethernet address that has been discovered through ARP (for IPv4) or
+ neighbor discovery (for IPv6). This table is primarily used to discover
+ bindings on physical networks, because IP-to-MAC bindings for virtual
+ machines are usually populated statically into the <ref
+ table="Port_Binding"/> table.
+ </p>
+
+ <p>
+ This table expresses a functional relationship: <ref
+ table="MAC_Binding"/>(<ref column="logical_port"/>, <ref column="ip"/>) =
+ <ref column="mac"/>.
+ </p>
+
+ <p>
+ In outline, the lifetime of a logical router's MAC binding looks like
+ this:
+ </p>
+
+ <ol>
+ <li>
+ On hypervisor 1, a logical router determines that a packet should be
+ forwarded to IP address <var>A</var> on one of its router ports. It
+ uses its logical flow table to determine that <var>A</var> lacks a
+ static IP-to-MAC binding and the <code>get_arp</code> action to
+ determine that it lacks a dynamic IP-to-MAC binding.
+ </li>
+
+ <li>
+ Using an OVN logical <code>arp</code> action, the logical router
+ generates and sends a broadcast ARP request to the router port. It
+ drops the IP packet.
+ </li>
+
+ <li>
+ The logical switch attached to the router port delivers the ARP request
+ to all of its ports. (It might make sense to deliver it only to ports
+ that have no static IP-to-MAC bindings, but this could also be
+ surprising behavior.)
+ </li>
+
+ <li>
+ A host or VM on hypervisor 2 (which might be the same as hypervisor 1)
+ attached to the logical switch owns the IP address in question. It
+ composes an ARP reply and unicasts it to the logical router port's
+ Ethernet address.
+ </li>
+
+ <li>
+ The logical switch delivers the ARP reply to the logical router port.
+ </li>
+
+ <li>
+ The logical router flow table executes a <code>put_arp</code> action.
+ To record the IP-to-MAC binding, <code>ovn-controller</code> adds a row
+ to the <ref table="MAC_Binding"/> table.
+ </li>
+
+ <li>
+ On hypervisor 1, <code>ovn-controller</code> receives the updated <ref
+ table="MAC_Binding"/> table from the OVN southbound database. The next
+ packet destined to <var>A</var> through the logical router is sent
+ directly to the bound Ethernet address.
+ </li>
+ </ol>
+
+ <column name="logical_port">
+ The logical port on which the binding was discovered.
+ </column>
+
+ <column name="ip">
+ The bound IP address.
+ </column>
+
+ <column name="mac">
+ The Ethernet address to which the IP is bound.
+ </column>
+ </table>
</database>
projects / cascardo / ovs.git / blobdiff