<p>
This database is the interface between OVN and the cloud management system
(CMS), such as OpenStack, running above it. The CMS produces almost all of
- the contents of the database. The <code>ovs-nbd</code> program monitors
- the database contents, transforms it, and stores it into the <ref
- db="OVN"/> database.
+ the contents of the database. The <code>ovn-northd</code> program
+ monitors the database contents, transforms it, and stores it into the <ref
+ db="OVN_Southbound"/> database.
</p>
<p>
<table name="Logical_Switch" title="L2 logical switch">
<p>
- Each row represents one L2 logical switch. A given switch's ports are
- the <ref table="Logical_Port"/> rows whose <ref table="Logical_Port"
- column="lswitch"/> column points to its row.
+ Each row represents one L2 logical switch.
</p>
+ <column name="name">
+ <p>
+ A name for the logical switch. This name has no special meaning or purpose
+ other than to provide convenience for human interaction with the ovn-nb
+ database. There is no requirement for the name to be unique. The
+ logical switch's UUID should be used as the unique identifier.
+ </p>
+ </column>
+
+ <column name="ports">
+ <p>
+ The logical ports connected to the logical switch.
+ </p>
+
+ <p>
+ It is an error for multiple logical switches to include the same
+ logical port.
+ </p>
+ </column>
+
<column name="router_port">
<p>
The router port to which this logical switch is connected, or empty if
restriction because logical routers may be connected into arbitrary
topologies.
</p>
+
+ <p>
+ It is an error for multiple logical switches to refer to the same
+ router port.
+ </p>
+ </column>
+
+ <column name="acls">
+ Access control rules that apply to packets within the logical switch.
</column>
<group title="Common Columns">
A port within an L2 logical switch.
</p>
- <column name="lswitch">
- The logical switch to which the logical port is connected.
+ <column name="name">
+ <p>
+ The logical port name.
+ </p>
+
+ <p>
+ For entities (VMs or containers) that are spawned in the hypervisor,
+ the name used here must match those used in the <ref key="iface-id"
+ table="Interface" column="external_ids" db="Open_vSwitch"/> in the
+ <ref db="Open_vSwitch"/> database's <ref table="Interface"
+ db="Open_vSwitch"/> table, because hypervisors use <ref key="iface-id"
+ table="Interface" column="external_ids" db="Open_vSwitch"/> as a lookup
+ key to identify the network interface of that entity.
+ </p>
+
+ <p>
+ For containers that are spawned inside a VM, the name can be
+ any unique identifier. In such a case, <ref column="parent_name"/>
+ must be populated.
+ </p>
</column>
- <column name="name">
- The logical port name. The name used here must match those used in the
+ <column name="type">
+ <p>
+ Specify a type for this logical port. Logical ports can be used to model
+ other types of connectivity into an OVN logical switch. Leaving this
+ column blank maintains the default logical port behavior, which is
+ for a VM (or VIF) interface. The following other types are defined:
+ </p>
+
+ <dl>
+ <dt><code>localnet</code></dt>
+ <dd>A connection to a locally accessible network from each
+ <code>ovn-controller</code> instance. A logical switch can only
+ have a single <code>localnet</code> port attached and at most one
+ regular logical port. This is used to model direct connectivity
+ to an existing network.</dd>
+ </dl>
+
+ <dl>
+ <dt><code>vtep</code></dt>
+ <dd>A port to a logical switch on a VTEP gateway. In order
+ to get this port correctly recognized by the OVN controller, the
+ <ref column="options" table="Logical_Port"/>:<code>vtep-physical-switch</code>
+ and <ref column="options" table="Logical_Port"/>:<code>vtep-logical-switch</code>
+ must also be defined.</dd>
+ </dl>
+ </column>
+
+ <column name="options">
+ <p>
+ This column provides key/value settings specific to the logical port
+ <ref column="type"/>. The following options are defined:
+ </p>
+
+ <dl>
+ <dt><code>network_name</code></dt>
+ <dd>
+ Must be set when <ref column="type"/> is <code>localnet</code>.
+ <code>ovn-controller</code> uses local configuration to determine
+ exactly how to connect to this locally accessible network.
+ </dd>
+ </dl>
+
+ <dl>
+ <dt><code>vtep-physical-switch</code></dt>
+ <dd>
+ The name of the VTEP gateway. Must be set when
+ <ref column="type"/> is <code>vtep</code>.
+ </dd>
+ </dl>
+
+ <dl>
+ <dt><code>vtep-logical-switch</code></dt>
+ <dd>
+ A logical switch name connected by the VTEP gateway. Must be
+ set when <ref column="type"/> is <code>vtep</code>.
+ </dd>
+ </dl>
+ </column>
+
+ <column name="parent_name">
+ When <ref column="name"/> identifies the interface of a container
+ spawned inside a tenant VM, this column represents the VM interface
+ through which the container interface sends its network traffic.
+ The name used here must match those used in the <ref key="iface-id"
+ table="Interface" column="external_ids" db="Open_vSwitch"/> in the
+ <ref db="Open_vSwitch"/> table, because hypervisors in this case use
<ref key="iface-id" table="Interface" column="external_ids"
- db="Open_vSwitch"/> in the <ref db="Open_vSwitch"/> database's <ref
- table="Interface" db="Open_vSwitch"/> table, because hypervisors use <ref
- key="iface-id" table="Interface" column="external_ids"
- db="Open_vSwitch"/> as a lookup key for logical ports.
+ db="Open_vSwitch"/> as a lookup key to identify the network interface
+ of the tenant VM.
+ </column>
+
+ <column name="tag">
+ <p>
+ When <ref column="type"/> is empty and <ref column="name"/> identifies
+ the interface of a container spawned inside a tenant VM, this column
+ identifies the VLAN tag in the network traffic associated with that
+ container's network interface. When there are multiple container
+ interfaces inside a VM, all of them send their network traffic through a
+ single VM network interface and this value helps OVN identify the correct
+ container interface.
+ </p>
+
+ <p>
+ When <ref column="type"/> is set to <code>localnet</code>, this can be
+ set to indicate that the port represents a connection to a specific
+ VLAN on a locally accessible network. The VLAN ID is used to match
+ incoming traffic and is also added to outgoing traffic.
+ </p>
</column>
<column name="up">
- This column is populated by <code>ovn-nbd</code>, rather than by the CMS
- plugin as is most of this database. When a logical port is bound to a
- physical location in the OVN database <ref db="OVN" table="Bindings"/>
- table, <code>ovn-nbd</code> sets this column to <code>true</code>;
- otherwise, or if the port becomes unbound later, it sets it to
- <code>false</code>. This allows the CMS to wait for a VM's networking to
- become active before it allows the VM to start.
+ This column is populated by <code>ovn-northd</code>, rather than by
+ the CMS plugin as is most of this database. When a logical port is bound
+ to a physical location in the OVN Southbound database <ref
+ db="OVN_Southbound" table="Binding"/> table, <code>ovn-northd</code>
+ sets this column to <code>true</code>; otherwise, or if the port
+ becomes unbound later, it sets it to <code>false</code>. This
+ allows the CMS to wait for a VM's (or container's) networking to
+ become active before it allows the VM (or container) to start.
</column>
- <column name="macs">
- The logical port's own Ethernet address or addresses, each in the form
- <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
- Like a physical Ethernet NIC, a logical port ordinarily has a single
- fixed Ethernet address. The string <code>unknown</code> is also allowed
- to indicate that the logical port has an unknown set of (additional)
- source addresses.
+ <column name="enabled">
+ This column is used to administratively set port state. If this column is
+ empty or is set to <code>true</code>, the port is enabled. If this column
+ is set to <code>false</code>, the port is disabled. A disabled port has all
+ ingress and egress traffic dropped.
+ </column>
+
+ <column name="addresses">
+ <p>
+ Addresses owned by the logical port.
+ </p>
+
+ <p>
+ Each element in the set must take one of the following forms:
+ </p>
+
+ <dl>
+ <dt><code><var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var></code></dt>
+ <dd>
+ <p>
+ An Ethernet address owned by the logical port. Like a physical
+ Ethernet NIC, a logical port ordinarily has a single fixed Ethernet
+ address.
+ </p>
+
+ <p>
+ When a OVN logical switch processes a unicast Ethernet frame whose
+ destination MAC address is in a logical port's <ref
+ column="addresses"/> column, it delivers it only to that port, as
+ if a MAC learning process had learned that MAC address on the port.
+ </p>
+ </dd>
+
+ <dt><code><var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var> <var>a</var>.<var>b</var>.<var>c</var>.<var>d</var></code></dt>
+ <dd>
+ <p>
+ This form has all the effects of the previous form. It also
+ indicates that the logical port owns the given IPv4 address.
+ </p>
+
+ <p>
+ The OVN logical switch uses this information to synthesize
+ responses to ARP requests without traversing the physical network.
+ The OVN logical router connected to the logical switch, if any,
+ uses this information to avoid issuing ARP requests for logical
+ switch ports.
+ </p>
+ </dd>
+
+ <dt><code>unknown</code></dt>
+ <dd>
+ This indicates that the logical port has an unknown set of Ethernet
+ addresses. When an OVN logical switch processes a unicast Ethernet
+ frame whose destination MAC address is not in any logical port's <ref
+ column="addresses"/> column, it delivers it to the port (or ports)
+ whose <ref column="addresses"/> columns include <code>unknown</code>.
+ </dd>
+ </dl>
</column>
<column name="port_security">
<p>
- A set of L2 (Ethernet) or L3 (IPv4 or IPv6) addresses or L2+L3 pairs
+ A set of L2 (Ethernet) addresses
from which the logical port is allowed to send packets and to which it
is allowed to receive packets. If this column is empty, all addresses
- are permitted.
+ are permitted. Logical ports are always allowed to receive packets
+ addressed to multicast and broadcast addresses.
+ </p>
+
+ <p>
+ Each member of the set is an Ethernet address in the form
+ <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
</p>
<p>
- Exact syntax is TBD. One could simply use comma- or space-separated L2
- and L3 addresses in each set member, or replace this by a subset of the
- general-purpose expression language used for the <ref column="match"
- table="Pipeline" db="OVN"/> column in the OVN database's <ref
- table="Pipeline" db="OVN"/> table.
+ This specification will be extended to support L3 port security.
</p>
</column>
<table name="ACL" title="Access Control List (ACL) rule">
<p>
- Each row in this table represents one ACL rule for the logical switch in
- its <ref column="lswitch"/> column. The <ref column="action"/> column for
- the highest-<ref column="priority"/> matching row in this table
- determines a packet's treatment. If no row matches, packets are allowed
- by default. (Default-deny treatment is possible: add a rule with <ref
- column="priority"/> 0, <code>true</code> as <ref column="match"/>, and
- <code>deny</code> as <ref column="action"/>.)
+ Each row in this table represents one ACL rule for a logical switch
+ that points to it through its <ref column="acls"/> column. The <ref
+ column="action"/> column for the highest-<ref column="priority"/>
+ matching row in this table determines a packet's treatment. If no row
+ matches, packets are allowed by default. (Default-deny treatment is
+ possible: add a rule with <ref column="priority"/> 1, <code>1</code> as
+ <ref column="match"/>, and <code>deny</code> as <ref column="action"/>.)
</p>
- <column name="lswitch">
- The switch to which the ACL rule applies. The expression in the
- <ref column="match"/> column may match against logical ports
- within this switch.
+ <column name="priority">
+ <p>
+ The ACL rule's priority. Rules with numerically higher priority
+ take precedence over those with lower. If two ACL rules with
+ the same priority both match, then the one actually applied to a
+ packet is undefined.
+ </p>
+
+ <p>
+ Return traffic from an <code>allow-related</code> flow is always
+ allowed and cannot be changed through an ACL.
+ </p>
</column>
- <column name="priority">
- The ACL rule's priority. Rules with numerically higher priority take
- precedence over those with lower. If two ACL rules with the same
- priority both match, then the one actually applied to a packet is
- undefined.
+ <column name="direction">
+ <p>Direction of the traffic to which this rule should apply:</p>
+ <ul>
+ <li>
+ <code>from-lport</code>: Used to implement filters on traffic
+ arriving from a logical port. These rules are applied to the
+ logical switch's ingress pipeline.
+ </li>
+ <li>
+ <code>to-lport</code>: Used to implement filters on traffic
+ forwarded to a logical port. These rules are applied to the
+ logical switch's egress pipeline.
+ </li>
+ </ul>
</column>
<column name="match">
- The packets that the ACL should match, in the same expression language
- used for the <ref column="match" table="Pipeline" db="OVN"/> column in
- the OVN database's <ref table="Pipeline" db="OVN"/> table. Match
- <code>inport</code> and <code>outport</code> against names of logical
- ports within <ref column="lswitch"/> to implement ingress and egress ACLs,
- respectively. In logical switches connected to logical routers, the
- special port name <code>ROUTER</code> refers to the logical router port.
+ <p>
+ The packets that the ACL should match, in the same expression
+ language used for the <ref column="match" table="Logical_Flow"
+ db="OVN_Southbound"/> column in the OVN Southbound database's
+ <ref table="Logical_Flow" db="OVN_Southbound"/> table. The
+ <code>outport</code> logical port is only available in the
+ <code>to-lport</code> direction (the <code>inport</code> is
+ available in both directions).
+ </p>
+
+ <p>
+ By default all traffic is allowed. When writing a more
+ restrictive policy, it is important to remember to allow flows
+ such as ARP and IPv6 neighbor discovery packets.
+ </p>
+
+ <p>
+ In logical switches connected to logical routers, the special
+ port name <code>ROUTER</code> refers to the logical router port.
+ </p>
</column>
<column name="action">
<p>The action to take when the ACL rule matches:</p>
-
<ul>
- <li>
- <code>allow</code>: Forward the packet.
- </li>
-
- <li>
- <code>allow-related</code>: Forward the packet and related traffic
- (e.g. inbound replies to an outbound connection).
- </li>
-
- <li>
- <code>drop</code>: Silently drop the packet.
- </li>
-
- <li>
- <code>reject</code>: Drop the packet, replying with a RST for TCP or
- ICMP unreachable message for other IP-based protocols.
- </li>
+ <li>
+ <code>allow</code>: Forward the packet.
+ </li>
+
+ <li>
+ <code>allow-related</code>: Forward the packet and related traffic
+ (e.g. inbound replies to an outbound connection).
+ </li>
+
+ <li>
+ <code>drop</code>: Silently drop the packet.
+ </li>
+
+ <li>
+ <code>reject</code>: Drop the packet, replying with a RST for TCP or
+ ICMP unreachable message for other IP-based protocols.
+ <code>Not implemented--currently treated as drop</code>
+ </li>
</ul>
</column>
<column name="log">
- If set to <code>true</code>, packets that match the ACL will trigger a
- log message on the transport node or nodes that perform ACL processing.
- Logging may be combined with any <ref column="action"/>.
+ <p>
+ If set to <code>true</code>, packets that match the ACL will trigger a
+ log message on the transport node or nodes that perform ACL processing.
+ Logging may be combined with any <ref column="action"/>.
+ </p>
+
+ <p>
+ Logging is not yet implemented.
+ </p>
</column>
<group title="Common Columns">
<table name="Logical_Router" title="L3 logical router">
<p>
- Each row represents one L3 logical router. A given router's ports are
- the <ref table="Logical_Router_Port"/> rows whose <ref
- table="Logical_Router_Port" column="router"/> column points to its row.
+ Each row represents one L3 logical router.
</p>
- <column name="ip">
- The logical router's own IP address. The logical router uses this
- address for ICMP replies (e.g. network unreachable messages) and other
- traffic that it originates and responds to traffic destined to this
- address (e.g. ICMP echo requests).
+ <column name="name">
+ <p>
+ A name for the logical router. This name has no special meaning or purpose
+ other than to provide convenience for human interaction with the ovn-nb
+ database. There is no requirement for the name to be unique. The
+ logical router's UUID should be used as the unique identifier.
+ </p>
+ </column>
+
+ <column name="ports">
+ The router's ports.
</column>
<column name="default_gw">
</p>
<p>
- A router port is always attached to a switch port. The connection can be
- identified by following the <ref column="router_port"
- table="Logical_Port"/> column from an appropriate <ref
- table="Logical_Port"/> row.
+ Exactly one <ref table="Logical_Router"/> row must reference a given
+ logical router port.
</p>
- <column name="router">
- The router to which the port belongs.
+ <column name="name">
+ <p>
+ A name for the logical router port. This name has no special meaning or purpose
+ other than to provide convenience for human interaction with the ovn-nb
+ database. There is no requirement for the name to be unique. The
+ logical router port's UUID should be used as the unique identifier.
+ </p>
</column>
<column name="network">
- The IP network and netmask of the network on the router port. Used for
- routing.
+ The IP address of the router and the netmask. For example,
+ <code>192.168.0.1/24</code> indicates that the router's IP address is
+ 192.168.0.1 and that packets destined to 192.168.0.<var>x</var> should be
+ routed to this port.
</column>
<column name="mac">
The Ethernet address that belongs to this router port.
</column>
+ <group title="Attachment">
+ <p>
+ A given router port serves one of two purposes:
+ </p>
+
+ <ul>
+ <li>
+ To attach a logical switch to a logical router. A logical router
+ port of this type is referenced by exactly the <ref
+ column="router_port" table="Logical_Switch"/> column in exactly one
+ <ref table="Logical_Switch"/> row. The <ref column="peer"/> column
+ is empty.
+ </li>
+
+ <li>
+ To connect one logical router to another. This requires a pair of
+ logical router ports, each connected to a different router. Each
+ router port in the pair specifies the other in its <ref
+ column="peer"/> column. No <ref table="Logical_Switch"/> refers to
+ the router port.
+ </li>
+ </ul>
+
+ <column name="peer">
+ <p>
+ For a router port used to connect two logical routers, this
+ identifies the other router port in the pair.
+ </p>
+
+ <p>
+ For a router port attached to a logical switch, this column is empty.
+ </p>
+ </column>
+ </group>
+
<group title="Common Columns">
<column name="external_ids">
See <em>External IDs</em> at the beginning of this document.
projects / cascardo / ovs.git / blobdiff