From 8351253cb9e767507bb7eec9cd0dbc4abc3e8cfd Mon Sep 17 00:00:00 2001 From: Ben Pfaff Date: Wed, 7 Oct 2015 15:34:54 -0700 Subject: [PATCH] ovn-nb.xml: Reorganize documentation for Logical_Port table. 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 Acked-by: Justin Pettit --- ovn/ovn-nb.xml | 382 ++++++++++++++++++++++++++----------------------- 1 file changed, 202 insertions(+), 180 deletions(-) diff --git a/ovn/ovn-nb.xml b/ovn/ovn-nb.xml index 7f6f70315..c119a271b 100644 --- a/ovn/ovn-nb.xml +++ b/ovn/ovn-nb.xml @@ -86,207 +86,229 @@ A port within an L2 logical switch.

- -

- The logical port name. -

+ + +

+ The logical port name. +

-

- For entities (VMs or containers) that are spawned in the hypervisor, - the name used here must match those used in the in the - database's table, because hypervisors use as a lookup - key to identify the network interface of that entity. -

+

+ For entities (VMs or containers) that are spawned in the hypervisor, + the name used here must match those used in the in the + database's table, because hypervisors use as a lookup + key to identify the network interface of that entity. +

-

- For containers that are spawned inside a VM, the name can be - any unique identifier. In such a case, - must be populated. -

- +

+ For containers that share a VIF within a VM, the name can be any + unique identifier. See Containers, below, for more + information. +

+ - -

- 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: -

+ +

+ 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: +

-
-
localnet
-
A connection to a locally accessible network from each - ovn-controller instance. A logical switch can only - have a single localnet port attached and at most one - regular logical port. This is used to model direct connectivity - to an existing network.
-
- -
-
vtep
-
A port to a logical switch on a VTEP gateway. In order - to get this port correctly recognized by the OVN controller, the - :vtep-physical-switch - and :vtep-logical-switch - must also be defined.
-
- +
+
(empty string)
+
+ A VM (or VIF) interface. +
+ +
localnet
+
+ A connection to a locally accessible network from each + ovn-controller instance. A logical switch can only + have a single localnet port attached and at most one + regular logical port. This is used to model direct connectivity to + an existing network. +
+ +
vtep
+
+ A port to a logical switch on a VTEP gateway. +
+
+ + - -

+ + This column provides key/value settings specific to the logical port - . The following options are defined: -

+ . The type-specific options are described + individually below. + -
-
network_name
-
- Must be set when is localnet. - ovn-controller uses local configuration to determine - exactly how to connect to this locally accessible network. -
-
- -
-
vtep-physical-switch
-
- The name of the VTEP gateway. Must be set when - is vtep. -
-
- -
-
vtep-logical-switch
-
- A logical switch name connected by the VTEP gateway. Must be - set when is vtep. -
-
- + +

+ These options apply when is + localnet. +

- - When 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 in the - table, because hypervisors in this case use - as a lookup key to identify the network interface - of the tenant VM. - + + Required. The name of the network to which the localnet + port is connected. Each hypervisor, via ovn-controller, + uses its local configuration to determine exactly how to connect to + this locally accessible network. + + - -

- When is empty and 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. -

- -

- When is set to localnet, 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. -

- + +

+ These options apply when is vtep. +

- - This column is populated by ovn-northd, 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 table, ovn-northd - sets this column to true; otherwise, or if the port - becomes unbound later, it sets it to false. 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. - + + Required. The name of the VTEP gateway. + - - This column is used to administratively set port state. If this column is - empty or is set to true, the port is enabled. If this column - is set to false, the port is disabled. A disabled port has all - ingress and egress traffic dropped. - + + Required. A logical switch name connected by the VTEP gateway. + + + - +

- 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.

- 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.

-
-
xx:xx:xx:xx:xx:xx
-
-

- An Ethernet address owned by the logical port. Like a physical - Ethernet NIC, a logical port ordinarily has a single fixed Ethernet - address. -

- -

- When a OVN logical switch processes a unicast Ethernet frame whose - destination MAC address is in a logical port's column, it delivers it only to that port, as - if a MAC learning process had learned that MAC address on the port. -

-
- -
xx:xx:xx:xx:xx:xx a.b.c.d
-
-

- This form has all the effects of the previous form. It also - indicates that the logical port owns the given IPv4 address. -

- -

- 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. -

-
- -
unknown
-
- 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 column, it delivers it to the port (or ports) - whose columns include unknown. -
-
- + + The VM interface through which the nested container sends its network + traffic. This must match the column for some + other . + - -

- 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. -

+ +

+ The VLAN tag in the network traffic associated with a container's + network interface. +

-

- Each member of the set is an Ethernet address in the form - xx:xx:xx:xx:xx:xx. -

+

+ When is set to localnet, 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. +

+ + -

- This specification will be extended to support L3 port security. -

- + + + This column is populated by ovn-northd, 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 table, ovn-northd + sets this column to true; otherwise, or if the port + becomes unbound later, it sets it to false. 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. + + + + This column is used to administratively set port state. If this column + is empty or is set to true, the port is enabled. If this + column is set to false, the port is disabled. A disabled + port has all ingress and egress traffic dropped. + + + + + + +

+ Addresses owned by the logical port. +

+ +

+ Each element in the set must take one of the following forms: +

+ +
+
xx:xx:xx:xx:xx:xx
+
+

+ An Ethernet address owned by the logical port. Like a physical + Ethernet NIC, a logical port ordinarily has a single fixed + Ethernet address. +

+ +

+ When a OVN logical switch processes a unicast Ethernet frame + whose destination MAC address is in a logical port's column, it delivers it only to that port, as + if a MAC learning process had learned that MAC address on the + port. +

+
+ +
xx:xx:xx:xx:xx:xx a.b.c.d
+
+

+ This form has all the effects of the previous form. It also + indicates that the logical port owns the given IPv4 address. +

+ +

+ 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. +

+
+ +
unknown
+
+ 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 + column, it delivers it to the port (or + ports) whose columns include + unknown. +
+
+ + + +

+ 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. +

+ +

+ Each member of the set is an Ethernet address in the form + xx:xx:xx:xx:xx:xx. +

+ +

+ This specification will be extended to support L3 port security. +

+ + -- 2.20.1