A port within an L2 logical switch.
Summary:
Core Features:
name string (must be unique within
table)
type string
Options:
options map of string-string pairs
Options for router ports:
options : router-port optional string
options : nat-addresses optional string
Options for localnet ports:
options : network_name optional string
Options for l2gateway ports:
options : network_name optional string
options : l2gateway-chassis
optional string
Options for vtep ports:
options : vtep-physical-switch
optional string
options : vtep-logical-switch
optional string
VMI (or VIF) Options:
options : requested-chassis
optional string
options : qos_max_rate optional string
options : qos_burst optional string
Containers:
parent_name optional string
tag_request optional integer, in range 0 to
4,095
tag optional integer, in range 1 to
4,095
Port State:
up optional boolean
enabled optional boolean
Addressing:
addresses set of strings
dynamic_addresses optional string
port_security set of strings
DHCP:
dhcpv4_options optional weak reference to
DHCP_Options
dhcpv6_options optional weak reference to
DHCP_Options
ha_chassis_group optional HA_Chassis_Group
Naming:
external_ids : neutron:port_name
optional string
Common Columns:
external_ids map of string-string pairs
Details:
Core Features:
name: string (must be unique within table)
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 external_ids:iface-id in the Open_vSwitch database's
Interface table, because hypervisors use
external_ids:iface-id as a lookup key to identify the
network interface of that entity.
For containers that share a VIF within a VM, the name can
be any unique identifier. See Containers, below, for more
information.
type: string
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:
(empty string)
A VM (or VIF) interface.
router A connection to a logical router.
localnet
A connection to a locally accessible network from
each ovn-controller instance. A logical switch can
only have a single localnet port attached. This is
used to model direct connectivity to an existing
network.
localport
A connection to a local VIF. Traffic that arrives
on a localport is never forwarded over a tunnel to
another chassis. These ports are present on every
chassis and have the same address in all of them.
This is used to model connectivity to local
services that run on every hypervisor.
l2gateway
A connection to a physical network.
vtep A port to a logical switch on a VTEP gateway.
external
Represents a logical port which is external and not
having an OVS port in the integration bridge. OVN
will never receive any traffic from this port or
send any traffic to this port. OVN can support
native services like DHCPv4/DHCPv6/DNS for this
port. If ha_chassis_group is defined,
ovn-controller running in the master chassis of the
HA chassis group will bind this port to provide
these native services. It is expected that this
port belong to a bridged logical switch (with a
localnet port).
It is recommended to use the same HA chassis group
for all the external ports of a logical switch.
Otherwise, the physical switch might see MAC flap
issue when different chassis provide the native
services. For example when supporting native DHCPv4
service, DHCPv4 server mac (configured in
options:server_mac column in table DHCP_Options)
originating from different ports can cause MAC flap
issue. The MAC of the logical router IP(s) can also
flap if the same HA chassis group is not set for
all the external ports of a logical switch.
Below are some of the use cases where external
ports can be used.
• VMs connected to SR-IOV nics - Traffic from
these VMs by passes the kernel stack and
local ovn-controller do not bind these ports
and cannot serve the native services.
• When CMS supports provisioning baremetal
servers.
Options:
options: map of string-string pairs
This column provides key/value settings specific to the
logical port type. The type-specific options are described
individually below.
Options for router ports:
These options apply when type is router.
options : router-port: optional string
Required. The name of the Logical_Router_Port to which
this logical switch port is connected.
options : nat-addresses: optional string
This is used to send gratuitous ARPs for SNAT and DNAT IP
addresses via the localnet port that is attached to the
same logical switch as this type router port. This option
is specified on a logical switch port that is connected to
a gateway router, or a logical switch port that is
connected to a distributed gateway port on a logical
router.
This must take one of the following forms:
router Gratuitous ARPs will be sent for all SNAT and DNAT
external IP addresses and for all load balancer IP
addresses defined on the options:router-port's
logical router, using the options:router-port's MAC
address.
This form of options:nat-addresses is valid for
logical switch ports where options:router-port is
the name of a port on a gateway router, or the name
of a distributed gateway port.
Supported only in OVN 2.8 and later. Earlier
versions required NAT addresses to be manually
synchronized.
Ethernet address followed by one or more IPv4 addresses
Example: 80:fa:5b:06:72:b7 158.36.44.22
158.36.44.24. This would result in generation of
gratuitous ARPs for IP addresses 158.36.44.22 and
158.36.44.24 with a MAC address of
80:fa:5b:06:72:b7.
This form of options:nat-addresses is only valid
for logical switch ports where options:router-port
is the name of a port on a gateway router.
Options for localnet ports:
These options apply when type is localnet.
options : network_name: optional string
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.
Options for l2gateway ports:
These options apply when type is l2gateway.
options : network_name: optional string
Required. The name of the network to which the l2gateway
port is connected. The L2 gateway, via ovn-controller,
uses its local configuration to determine exactly how to
connect to this network.
options : l2gateway-chassis: optional string
Required. The chassis on which the l2gateway logical port
should be bound to. ovn-controller running on the defined
chassis will connect this logical port to the physical
network.
Options for vtep ports:
These options apply when type is vtep.
options : vtep-physical-switch: optional string
Required. The name of the VTEP gateway.
options : vtep-logical-switch: optional string
Required. A logical switch name connected by the VTEP
gateway.
VMI (or VIF) Options:
These options apply to logical ports with type having (empty
string)
options : requested-chassis: optional string
If set, identifies a specific chassis (by name or
hostname) that is allowed to bind this port. Using this
option will prevent thrashing between two chassis trying
to bind the same port during a live migration. It can also
prevent similar thrashing due to a mis-configuration, if a
port is accidentally created on more than one chassis.
options : qos_max_rate: optional string
If set, indicates the maximum rate for data sent from this
interface, in bit/s. The traffic will be shaped according
to this limit.
options : qos_burst: optional string
If set, indicates the maximum burst size for data sent
from this interface, in bits.
Containers:
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.
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.
parent_name: optional string
The VM interface through which the nested container sends
its network traffic. This must match the name column for
some other Logical_Switch_Port.
tag_request: optional integer, in range 0 to 4,095
The VLAN tag in the network traffic associated with a
container's network interface. The client can request
ovn-northd to allocate a tag that is unique within the
scope of a specific parent (specified in parent_name) by
setting a value of 0 in this column. The allocated value
is written by ovn-northd in the tag column. (Note that
these tags are allocated and managed locally in
ovn-northd, so they cannot be reconstructed in the event
that the database is lost.) The client can also request a
specific non-zero tag and ovn-northd will honor it and
copy that value to the tag column.
When type is set to localnet or l2gateway, 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.
tag: optional integer, in range 1 to 4,095
The VLAN tag allocated by ovn-northd based on the contents
of the tag_request column.
Port State:
up: optional boolean
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 Binding 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.
Logical ports of router type are an exception to this
rule. They are considered to be always up, that is this
column is always set to true.
enabled: optional boolean
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.
Addressing:
addresses: set of strings
Addresses owned by the logical port.
Each element in the set must take one of the following
forms:
Ethernet address followed by zero or more IPv4 or IPv6
addresses (or both)
An Ethernet address defined is 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 addresses column, it delivers it
only to that port, as if a MAC learning process had
learned that MAC address on the port.
If IPv4 or IPv6 address(es) (or both) are defined,
it indicates that the logical port owns the given
IP addresses.
If IPv4 address(es) are defined, 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.
Note that the order here is important. The Ethernet
address must be listed before the IP address(es) if
defined.
Examples:
80:fa:5b:06:72:b7
This indicates that the logical port owns
the above mac address.
80:fa:5b:06:72:b7 10.0.0.4 20.0.0.4
This indicates that the logical port owns
the mac address and two IPv4 addresses.
80:fa:5b:06:72:b7
fdaa:15f2:72cf:0:f816:3eff:fe20:3f41
This indicates that the logical port owns
the mac address and 1 IPv6 address.
80:fa:5b:06:72:b7 10.0.0.4
fdaa:15f2:72cf:0:f816:3eff:fe20:3f41
This indicates that the logical port owns
the mac address and 1 IPv4 address and 1
IPv6 address.
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 addresses column, it delivers it to the port
(or ports) whose addresses columns include unknown.
dynamic
Use this keyword to make ovn-northd generate a
globally unique MAC address and choose an unused
IPv4 address with the logical port's subnet and
store them in the port's dynamic_addresses column.
ovn-northd will use the subnet specified in
other_config:subnet in the port's Logical_Switch.
Ethernet address followed by keyword "dynamic"
The keyword dynamic after the MAC address indicates
that ovn-northd should choose an unused IPv4
address from the logical port's subnet and store it
with the specified MAC in the port's
dynamic_addresses column. ovn-northd will use the
subnet specified in other_config:subnet in the
port's Logical_Switch table.
Examples:
80:fa:5b:06:72:b7 dynamic
This indicates that the logical port owns
the specified MAC address and ovn-northd
should allocate an unused IPv4 address for
the logical port from the corresponding
logical switch subnet.
Keyword "dynamic" followed by an IPv4/IPv6 address
The keyword dynamic followed by an IPv4/IPv6
address indicates that ovn-northd should choose a
dynamic ethernet address and use the provided
IPv4/IPv6 address as network address.
Examples:
dynamic 192.168.0.1 2001::1
This indicates that ovn-northd should
allocate a unique MAC address and use the
provided IPv4/IPv6 address for the related
port
router Accepted only when type is router. This indicates
that the Ethernet, IPv4, and IPv6 addresses for
this logical switch port should be obtained from
the connected logical router port, as specified by
router-port in options.
The resulting addresses are used to populate the
logical switch's destination lookup, and also for
the logical switch to generate ARP and ND replies.
If the connected logical router port has a
redirect-chassis specified and the logical router
has rules specified in nat with external_mac, then
those addresses are also used to populate the
switch's destination lookup.
Supported only in OVN 2.7 and later. Earlier
versions required router addresses to be manually
synchronized.
dynamic_addresses: optional string
Addresses assigned to the logical port by ovn-northd, if
dynamic is specified in addresses. Addresses will be of
the same format as those that populate the addresses
column. Note that dynamically assigned addresses are
constructed and managed locally in ovn-northd, so they
cannot be reconstructed in the event that the database is
lost.
port_security: set of strings
This column controls the addresses from which the host
attached to the logical port (``the host'') is allowed to
send packets and to which it is allowed to receive
packets. If this column is empty, all addresses are
permitted.
Each element in the set must begin with one Ethernet
address. This would restrict the host to sending packets
from and receiving packets to the ethernet addresses
defined in the logical port's port_security column. It
also restricts the inner source MAC addresses that the
host may send in ARP and IPv6 Neighbor Discovery packets.
The host is always allowed to receive packets to multicast
and broadcast Ethernet addresses.
Each element in the set may additionally contain one or
more IPv4 or IPv6 addresses (or both), with optional
masks. If a mask is given, it must be a CIDR mask. In
addition to the restrictions described for Ethernet
addresses above, such an element restricts the IPv4 or
IPv6 addresses from which the host may send and to which
it may receive packets to the specified addresses. A
masked address, if the host part is zero, indicates that
the host is allowed to use any address in the subnet; if
the host part is nonzero, the mask simply indicates the
size of the subnet. In addition:
• If any IPv4 address is given, the host is also
allowed to receive packets to the IPv4 local
broadcast address 255.255.255.255 and to IPv4
multicast addresses (224.0.0.0/4). If an IPv4
address with a mask is given, the host is also
allowed to receive packets to the broadcast address
in that specified subnet.
If any IPv4 address is given, the host is
additionally restricted to sending ARP packets with
the specified source IPv4 address. (RARP is not
restricted.)
• If any IPv6 address is given, the host is also
allowed to receive packets to IPv6 multicast
addresses (ff00::/8).
If any IPv6 address is given, the host is
additionally restricted to sending IPv6 Neighbor
Discovery Solicitation or Advertisement packets
with the specified source address or, for
solicitations, the unspecified address.
If an element includes an IPv4 address, but no IPv6
addresses, then IPv6 traffic is not allowed. If an element
includes an IPv6 address, but no IPv4 address, then IPv4
and ARP traffic is not allowed.
This column uses the same lexical syntax as the match
column in the OVN Southbound database's Pipeline table.
Multiple addresses within an element may be space or comma
separated.
This column is provided as a convenience to cloud
management systems, but all of the features that it
implements can be implemented as ACLs using the ACL table.
Examples:
80:fa:5b:06:72:b7
The host may send traffic from and receive traffic
to the specified MAC address, and to receive
traffic to Ethernet multicast and broadcast
addresses, but not otherwise. The host may not send
ARP or IPv6 Neighbor Discovery packets with inner
source Ethernet addresses other than the one
specified.
80:fa:5b:06:72:b7 192.168.1.10/24
This adds further restrictions to the first
example. The host may send IPv4 packets from or
receive IPv4 packets to only 192.168.1.10, except
that it may also receive IPv4 packets to
192.168.1.255 (based on the subnet mask),
255.255.255.255, and any address in 224.0.0.0/4.
The host may not send ARPs with a source Ethernet
address other than 80:fa:5b:06:72:b7 or source IPv4
address other than 192.168.1.10. The host may not
send or receive any IPv6 (including IPv6 Neighbor
Discovery) traffic.
"80:fa:5b:12:42:ba", "80:fa:5b:06:72:b7 192.168.1.10/24"
The host may send traffic from and receive traffic
to the specified MAC addresses, and to receive
traffic to Ethernet multicast and broadcast
addresses, but not otherwise. With MAC
80:fa:5b:12:42:ba, the host may send traffic from
and receive traffic to any L3 address. With MAC
80:fa:5b:06:72:b7, the host may send IPv4 packets
from or receive IPv4 packets to only 192.168.1.10,
except that it may also receive IPv4 packets to
192.168.1.255 (based on the subnet mask),
255.255.255.255, and any address in 224.0.0.0/4.
The host may not send or receive any IPv6
(including IPv6 Neighbor Discovery) traffic.
DHCP:
dhcpv4_options: optional weak reference to DHCP_Options
This column defines the DHCPv4 Options to be included by
the ovn-controller when it replies to the DHCPv4 requests.
Please see the DHCP_Options table.
dhcpv6_options: optional weak reference to DHCP_Options
This column defines the DHCPv6 Options to be included by
the ovn-controller when it replies to the DHCPv6 requests.
Please see the DHCP_Options table.
ha_chassis_group: optional HA_Chassis_Group
References a row in the OVN Northbound database's
HA_Chassis_Group table. It indicates the HA chassis group
to use if the type is set to external. If type is not
external, this column is ignored.
Naming:
external_ids : neutron:port_name: optional string
This column gives an optional human-friendly name for the
port. This name has no special meaning or purpose other
than to provide convenience for human interaction with the
northbound database.
Neutron copies this from its own port object's name.
(Neutron ports do are not assigned human-friendly names by
default, so it will often be empty.)
Common Columns:
external_ids: map of string-string pairs
See External IDs at the beginning of this document.
The ovn-northd program copies all these pairs into the
external_ids column of the Port_Binding table in
OVN_Southbound database.
