@@ -86,207 +86,229 @@
A port within an L2 logical switch.
</p>
- <column name="name">
- <p>
- The logical port name.
- </p>
+ <group title="Core Features">
+ <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 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>
+ <p>
+ For containers that share a VIF within a VM, the name can be any
+ unique identifier. See <code>Containers</code>, below, for more
+ information.
+ </p>
+ </column>
- <column name="type">
- <p>
- Specify a type for this logical port. Logical ports can be used to model
- other types of connectivity into an OVN logical switch. Leaving this
- column blank maintains the default logical port behavior, which is
- for a VM (or VIF) interface. The following other types are defined:
- </p>
+ <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. The
+ following 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>
+ <dl>
+ <dt>(empty string)</dt>
+ <dd>
+ A VM (or VIF) interface.
+ </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.
+ </dd>
+
+ <dt><code>vtep</code></dt>
+ <dd>
+ A port to a logical switch on a VTEP gateway.
+ </dd>
+ </dl>
+ </column>
+ </group>
- <column name="options">
- <p>
+ <group title="Options">
+ <column name="options">
This column provides key/value settings specific to the logical port
- <ref column="type"/>. The following options are defined:
- </p>
+ <ref column="type"/>. The type-specific options are described
+ individually below.
+ </column>
- <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>
+ <group title="Options for localnet ports">
+ <p>
+ These options apply when <ref column="type"/> is
+ <code>localnet</code>.
+ </p>
- <column name="parent_name">
- When <ref column="name"/> identifies the interface of a container
- spawned inside a tenant VM, this column represents the VM interface
- through which the container interface sends its network traffic.
- The name used here must match those used in the <ref key="iface-id"
- table="Interface" column="external_ids" db="Open_vSwitch"/> in the
- <ref db="Open_vSwitch"/> table, because hypervisors in this case use
- <ref key="iface-id" table="Interface" column="external_ids"
- db="Open_vSwitch"/> as a lookup key to identify the network interface
- of the tenant VM.
- </column>
+ <column name="options" key="network_name">
+ Required. The name of the network to which the <code>localnet</code>
+ port is connected. Each hypervisor, via <code>ovn-controller</code>,
+ uses its local configuration to determine exactly how to connect to
+ this locally accessible network.
+ </column>
+ </group>
- <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>
+ <group title="Options for vtep ports">
+ <p>
+ These options apply when <ref column="type"/> is <code>vtep</code>.
+ </p>
- <column name="up">
- This column is populated by <code>ovn-northd</code>, rather than by
- the CMS plugin as is most of this database. When a logical port is bound
- to a physical location in the OVN Southbound database <ref
- db="OVN_Southbound" table="Binding"/> table, <code>ovn-northd</code>
- sets this column to <code>true</code>; otherwise, or if the port
- becomes unbound later, it sets it to <code>false</code>. This
- allows the CMS to wait for a VM's (or container's) networking to
- become active before it allows the VM (or container) to start.
- </column>
+ <column name="options" key="vtep-physical-switch">
+ Required. The name of the VTEP gateway.
+ </column>
- <column name="enabled">
- This column is used to administratively set port state. If this column is
- empty or is set to <code>true</code>, the port is enabled. If this column
- is set to <code>false</code>, the port is disabled. A disabled port has all
- ingress and egress traffic dropped.
- </column>
+ <column name="options" key="vtep-logical-switch">
+ Required. A logical switch name connected by the VTEP gateway.
+ </column>
+ </group>
+ </group>
- <column name="addresses">
+ <group title="Containers">
<p>
- Addresses owned by the logical port.
+ When a large number of containers are nested within a VM, it may be too
+ expensive to dedicate a VIF to each container. OVN can use VLAN tags
+ to support such cases. Each container is assigned a VLAN ID and each
+ packet that passes between the hypervisor and the VM is tagged with the
+ appropriate ID for the container. Such VLAN IDs never appear on a
+ physical wire, even inside a tunnel, so they need not be unique except
+ relative to a single VM on a hypervisor.
</p>
<p>
- Each element in the set must take one of the following forms:
+ These columns are used for VIFs that represent nested containers using
+ shared VIFs. For VMs and for containers that have dedicated VIFs, they
+ are empty.
</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="parent_name">
+ The VM interface through which the nested container sends its network
+ traffic. This must match the <ref column="name"/> column for some
+ other <ref table="Logical_Port"/>.
+ </column>
- <column name="port_security">
- <p>
- A set of L2 (Ethernet) addresses
- from which the logical port is allowed to send packets and to which it
- is allowed to receive packets. If this column is empty, all addresses
- are permitted. Logical ports are always allowed to receive packets
- addressed to multicast and broadcast addresses.
- </p>
+ <column name="tag">
+ <p>
+ The VLAN tag in the network traffic associated with a container's
+ network interface.
+ </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>
+ 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>
+ </group>
- <p>
- This specification will be extended to support L3 port security.
- </p>
- </column>
+ <group title="Port State">
+ <column name="up">
+ This column is populated by <code>ovn-northd</code>, rather than by the
+ CMS plugin as is most of this database. When a logical port is bound
+ to a physical location in the OVN Southbound database <ref
+ db="OVN_Southbound" table="Binding"/> table, <code>ovn-northd</code>
+ sets this column to <code>true</code>; otherwise, or if the port
+ becomes unbound later, it sets it to <code>false</code>. This allows
+ the CMS to wait for a VM's (or container's) networking to become active
+ before it allows the VM (or container) to start.
+ </column>
+
+ <column name="enabled">
+ This column is used to administratively set port state. If this column
+ is empty or is set to <code>true</code>, the port is enabled. If this
+ column is set to <code>false</code>, the port is disabled. A disabled
+ port has all ingress and egress traffic dropped.
+ </column>
+
+ </group>
+
+ <group title="Addressing">
+ <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) addresses from which the logical port is
+ allowed to send packets and to which it is allowed to receive
+ packets. If this column is empty, all addresses are permitted.
+ Logical ports are always allowed to receive packets addressed to
+ multicast and broadcast addresses.
+ </p>
+
+ <p>
+ Each member of the set is an Ethernet address in the form
+ <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
+ </p>
+
+ <p>
+ This specification will be extended to support L3 port security.
+ </p>
+ </column>
+ </group>
<group title="Common Columns">
<column name="external_ids">
This uses the column grouping feature and the ability to document an individual key within a column to better, in my opinion, organize the documentation for the Logical_Port table. This will make it easier to document a new port type that a future commit will add. Signed-off-by: Ben Pfaff <blp@nicira.com> --- ovn/ovn-nb.xml | 382 ++++++++++++++++++++++++++++++--------------------------- 1 file changed, 202 insertions(+), 180 deletions(-)