ovn-nb(5) Open vSwitch Manual ovn-nb(5)
NAME
ovn-nb - OVN_Northbound database schema
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 ovn-northd program
monitors the database contents, transforms it, and stores it into the
OVN_Southbound database.
We generally speak of ``the’’ CMS, but one can imagine scenarios in
which multiple CMSes manage different parts of an OVN deployment.
External IDs
Each of the tables in this database contains a special column, named
external_ids. This column has the same form and purpose each place it
appears.
external_ids: map of string-string pairs
Key-value pairs for use by the CMS. The CMS might use
certain pairs, for example, to identify entities in its
own configuration that correspond to those in this data‐
base.
TABLE SUMMARY
The following list summarizes the purpose of each of the tables in the
OVN_Northbound database. Each table is described in more detail on a
later page.
Table Purpose
Logical_Switch
L2 logical switch
Logical_Port
L2 logical switch port
ACL Access Control List (ACL) rule
Logical_Router
L3 logical router
Logical_Router_Port
L3 logical router port
Logical_Switch TABLE
Each row represents one L2 logical switch.
Summary:
name string
ports set of Logical_Ports
acls set of ACLs
Common Columns:
external_ids map of string-string pairs
Details:
name: string
A name for the logical switch. This name has no special meaning
or purpose other than to provide convenience for human interac‐
tion 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.
ports: set of Logical_Ports
The logical ports connected to the logical switch.
It is an error for multiple logical switches to include the same
logical port.
acls: set of ACLs
Access control rules that apply to packets within the logical
switch.
Common Columns:
external_ids: map of string-string pairs
See External IDs at the beginning of this document.
Logical_Port TABLE
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, containing an uuid
Options for localnet ports:
options : network_name optional string
Options for vtep ports:
options : vtep-physical-switch
optional string
options : vtep-logical-switch
optional string
Containers:
parent_name optional string
tag optional integer, in range 1 to 4,095
Port State:
up optional boolean
enabled optional boolean
Addressing:
addresses set of strings
port_security set of strings
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 hyper‐
visor, the name used here must match those used in the exter‐
nal_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 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.
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.
A given logical switch may have at most one logical port of type
router. (This is not a significant restriction because logical routers
may be connected into arbitrary topologies.)
options : router-port: optional string, containing an uuid
Required. The UUID of the Logical_Router_Port to which this
logical switch port is connected.
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 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.
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_Port.
tag: optional integer, in range 1 to 4,095
The VLAN tag in the network traffic associated with a con‐
tainer’s network interface.
When type 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 traf‐
fic and is also added to outgoing traffic.
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.
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:
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 addresses 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 synthe‐
size 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 pro‐
cesses 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 col‐
umns include unknown.
port_security: set of strings
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.
Common Columns:
external_ids: map of string-string pairs
See External IDs at the beginning of this document.
ACL TABLE
Each row in this table represents one ACL rule for a logical switch
that points to it through its acls column. The action column for the
highest-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 priority 1, 1 as
match, and deny as action.)
Summary:
priority integer, in range 1 to 65,534
direction string, either to-lport or from-lport
match string
action string, one of allow-related, drop,
allow, or reject
log boolean
Common Columns:
external_ids map of string-string pairs
Details:
priority: integer, in range 1 to 65,534
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.
Return traffic from an allow-related flow is always allowed and
cannot be changed through an ACL.
direction: string, either to-lport or from-lport
Direction of the traffic to which this rule should apply:
· from-lport: Used to implement filters on traffic arriving
from a logical port. These rules are applied to the log‐
ical switch’s ingress pipeline.
· to-lport: Used to implement filters on traffic forwarded
to a logical port. These rules are applied to the logi‐
cal switch’s egress pipeline.
match: string
The packets that the ACL should match, in the same expression
language used for the match column in the OVN Southbound data‐
base’s Logical_Flow table. The outport logical port is only
available in the to-lport direction (the inport is available in
both directions).
By default all traffic is allowed. When writing a more restric‐
tive policy, it is important to remember to allow flows such as
ARP and IPv6 neighbor discovery packets.
action: string, one of allow-related, drop, allow, or reject
The action to take when the ACL rule matches:
· allow: Forward the packet.
· allow-related: Forward the packet and related traffic
(e.g. inbound replies to an outbound connection).
· drop: Silently drop the packet.
· reject: Drop the packet, replying with a RST for TCP or
ICMP unreachable message for other IP-based protocols.
Not implemented--currently treated as drop
log: boolean
If set to true, packets that match the ACL will trigger a log
message on the transport node or nodes that perform ACL process‐
ing. Logging may be combined with any action.
Logging is not yet implemented.
Common Columns:
external_ids: map of string-string pairs
See External IDs at the beginning of this document.
Logical_Router TABLE
Each row represents one L3 logical router.
Summary:
name string
ports set of Logical_Router_Ports
default_gw optional string
Common Columns:
external_ids map of string-string pairs
Details:
name: string
A name for the logical router. This name has no special meaning
or purpose other than to provide convenience for human interac‐
tion 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.
ports: set of Logical_Router_Ports
The router’s ports.
default_gw: optional string
IP address to use as default gateway, if any.
Common Columns:
external_ids: map of string-string pairs
See External IDs at the beginning of this document.
Logical_Router_Port TABLE
A port within an L3 logical router.
Exactly one Logical_Router row must reference a given logical router
port.
Summary:
name string
network string
mac string
enabled optional boolean
Attachment:
peer optional Logical_Router_Port
Common Columns:
external_ids map of string-string pairs
Details:
name: string
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.
network: string
The IP address of the router and the netmask. For example,
192.168.0.1/24 indicates that the router’s IP address is
192.168.0.1 and that packets destined to 192.168.0.x should be
routed to this port.
mac: string
The Ethernet address that belongs to this router port.
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.
Attachment:
A given router port serves one of two purposes:
· To attach a logical switch to a logical router. A logi‐
cal router port of this type is referenced by exactly one
Logical_Port of type router. The peer column is empty.
· To connect one logical router to another. This requires
a pair of logical router ports, each connected to a dif‐
ferent router. Each router port in the pair specifies
the other in its peer column. No Logical_Switch refers
to the router port.
peer: optional Logical_Router_Port
For a router port used to connect two logical routers, this
identifies the other router port in the pair.
For a router port attached to a logical switch, this column is
empty.
Common Columns:
external_ids: map of string-string pairs
See External IDs at the beginning of this document.
Open vSwitch 2.4.90 DB Schema 1.0.0 ovn-nb(5)