ovn-bridge-controller(5)

📦
version 26.09.0 · 6 versions
, in fedora 44

💖 ovn-bridge-controller(5) 💖

okay bestie, welcome to the Open vSwitch Manual page for ovn-bridge-controller — yes it's giving very "5" of it, section five, the database schema section, we love that for us 🎀

✨ NAME ✨

ovn-bridge-controller — the OVN_Bridge_Controller database schema 🦋

This database is literally the interface between the OVN Bridge Controller and the cloud management system (CMS), and its whole job is to program and control the OVS bridges using OVN logical flows. The CMS produces almost all of the contents of the database — like, basically everything, she's the main character of this whole situation. The ovn-bridge-controller program sits there monitoring the database contents and programs the OVS bridges with the OpenFlow rules. no cap. 💅

🌸 External IDs 🌸

Every single table in this database has a special column named external_ids. Same form, same purpose, every place it shows up. She's consistent, she's iconic, she never switches up. 👑

  • 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 database. iykyk. ✨

📋 TABLE SUMMARY 📋

here's the rundown of what each table in the OVN_Bridge_Controller database is actually for, bestie. Each table gets described in more detail on a later page — this is just the vibe check. 🫶

  • BR_Global — Bridge Controller configuration
  • Connection — OVSDB client connections.
  • SSL — SSL configuration.
  • Bridge — OVS Bridge to control
  • Logical_Flow — Logical flow

👑 BR_Global TABLE 👑

Summary:

br_cfg                        integer

Common Columns:

  external_ids                map of string-string pairs

Common options:

  options                     map of string-string pairs

Connection Options:

  connections                 set of Connections
  ssl                         optional SSL

Details:

  • br_cfg: integer — sequence number for client to increment. When a client modifies any part of the bridge Controller database configuration and wishes to wait for ovn-br-controller to finish applying the changes, it may increment this sequence number. like a little "hey bestie are u done yet" counter, but make it a number. 🔢

💜 Common Columns 💜

  • external_ids: map of string-string pairs — see External IDs at the beginning of this document. (scroll up bestie, we already covered her 💖)

💜 Common options 💜

  • options: map of string-string pairs — this column provides general key/value settings. The supported options are described individually below.

💜 Connection Options 💜

  • connections: set of Connections — database clients to which the Open vSwitch database server should connect or on which it should listen, along with options for how these connections should be configured. See the Connection table for more information. ✨
  • ssl: optional SSL — global SSL/TLS configuration. 🔐

and that's a wrap on part 1, but we are so not done — more of this page is coming, so stay tuned bestie 💅

🌈 Connection TABLE 🌈

okay so this table is literally the blueprint for a database connection to an Open vSwitch database (OVSDB) client. fr fr

It's mainly here to configure the Open vSwitch database server (ovsdb-server). 💅

And the tea is: that server can initiate and maintain active connections to remote clients, AND it can also just sit there and listen for database connections. Multitasking queen. 👑

Summary: 📋

Core Features:

  • target — string (must be unique within table)

Client Failure Detection and Handling:

  • max_backoff — optional integer, at least 1,000
  • inactivity_probe — optional integer

Status:

  • is_connected — boolean
  • status : last_error — optional string
  • status : state — optional string, one of ACTIVE, BACKOFF, CONNECTING, IDLE, or VOID
  • status : sec_since_connect — optional string, containing an integer, at least 0
  • status : sec_since_disconnect — optional string, containing an integer, at least 0
  • status : locks_held — optional string
  • status : locks_waiting — optional string
  • status : locks_lost — optional string
  • status : n_connections — optional string, containing an integer, at least 2
  • status : bound_port — optional string, containing an integer

Common Columns:

  • external_ids — map of string-string pairs
  • other_config — map of string-string pairs

Details: 🔍

Core Features: 🎯

target: string (must be unique within table)

This one's the connection methods for clients. ✨

The following connection methods are currently supported:

  • ssl:host[:port] — The specified SSL/TLS port on the host at the given host, which can either be a DNS name (if built with unbound library) or an IP address. A valid SSL/TLS configuration must be provided when this form is used, and this configuration can be specified via command-line options or the SSL table.

If port is not specified, it defaults to 6640.

SSL/TLS support is an optional feature that is not always built as part of OVN or Open vSwitch. 😭
  • tcp:host[:port] — The specified TCP port on the host at the given host, which can either be a DNS name (if built with unbound library) or an IP address. If host is an IPv6 address, wrap it in square brackets, e.g. tcp:[::1]:6640.

If port is not specified, it defaults to 6640.

  • pssl:[port][:host] — Listens for SSL/TLS connections on the specified TCP port. Specify 0 for port to have the kernel automatically choose an available port. If host, which can either be a DNS name (if built with unbound library) or an IP address, is specified, then connections are restricted to the resolved or specified local IP address (either IPv4 or IPv6 address). If host is an IPv6 address, wrap in square brackets, e.g. pssl:6640:[::1]. If host is not specified then it listens only on IPv4 (but not IPv6) addresses. A valid SSL/TLS configuration must be provided when this form is used, and this can be specified either via command-line options or the SSL table.

If port is not specified, it defaults to 6640.

SSL/TLS support is an optional feature that is not always built as part of OVN or Open vSwitch. 💀
  • ptcp:[port][:host] — Listens for connections on the specified TCP port. Specify 0 for port to have the kernel automatically choose an available port. If host, which can either be a DNS name (if built with unbound library) or an IP address, is specified, then connections are restricted to the resolved or specified local IP address (either IPv4 or IPv6 address). If host is an IPv6 address, wrap it in square brackets, e.g. ptcp:6640:[::1]. If host is not specified then it listens only on IPv4 addresses.

If port is not specified, it defaults to 6640.

heads up bestie — when multiple clients are configured, the target values must be unique. Duplicate target values yield unspecified results. not the vibe we're going for 🙈

Client Failure Detection and Handling: 🩺

  • max_backoff: optional integer, at least 1,000 — Maximum number of milliseconds to wait between connection attempts. Default is implementation-specific.
  • inactivity_probe: optional integer — Maximum number of milliseconds of idle time on connection to the client before sending an inactivity probe message. If Open vSwitch does not communicate with the client for the specified number of seconds, it will send a probe. If a response is not received for the same additional amount of time, Open vSwitch assumes the connection has been broken and attempts to reconnect. Default is implementation-specific. A value of 0 disables inactivity probes. so if you set it to zero she just stops checking, ok

Status: 📡

Key-value pair of is_connected is always updated. Other key-value pairs in the status columns may be updated depends on the target type. 👀

When target specifies a connection method that listens for inbound connections (e.g. ptcp: or punix:), both n_connections and is_connected may also be updated while the remaining key-value pairs are omitted.

On the other hand, when target specifies an outbound connection, all key-value pairs may be updated, except the above-mentioned two key-value pairs associated with inbound connection targets. They are omitted.

  • is_connected: boolean — true if currently connected to this client, false otherwise.
  • status : last_error: optional string — A human-readable description of the last error on the connection to the manager; i.e. strerror(errno). This key will exist only if an error has occurred. so if it's not there, congrats, nothing broke 🎀
  • status : state: optional string, one of ACTIVE, BACKOFF, CONNECTING, IDLE, or VOID — The state of the connection to the manager:
    • VOID — Connection is disabled.
    • BACKOFF — Attempting to reconnect at an increasing period.
    • CONNECTING — Attempting to connect.
    • ACTIVE — Connected, remote host responsive.
    • IDLE — Connection is idle. Waiting for response to keep-alive.
these values may change in the future. They are provided only for human consumption. iykyk ✨
  • status : sec_since_connect: optional string, containing an integer, at least 0 — The amount of time since this client last successfully connected to the database (in seconds). Value is empty if client has never successfully been connected.
  • status : sec_since_disconnect: optional string, containing an integer, at least 0 — The amount of time since this client last disconnected from the database (in seconds). Value is empty if client has never disconnected.
  • status : locks_held: optional string — Space-separated list of the names of OVSDB locks that the connection holds. Omitted if the connection does not hold any locks. 🔒
  • status : locks_waiting: optional string — Space-separated list of the names of OVSDB locks that the connection is currently waiting to acquire. Omitted if the connection is not waiting for any locks. ⏳
  • status : locks_lost: optional string — Space-separated list of the names of OVSDB locks that the connection has had stolen by another OVSDB client. Omitted if no locks have been stolen from this connection. someone took your lock, that's so rude 💀
  • status : n_connections: optional string, containing an integer, at least 2 — When target specifies a connection method that listens for inbound connections (e.g. ptcp: or pssl:) and more than one connection is actually active, the value is the number of active connections. Otherwise, this key-value pair is omitted.
  • status : bound_port: optional string, containing an integer — When target is ptcp: or pssl:, this is the TCP port on which the OVSDB server is listening. (This is particularly useful when target specifies a port of 0, allowing the kernel to choose any available port.) like a little receipt for the port the kernel picked for you 🧚

Common Columns: 🧩

The overall purpose of these columns is described under Common Columns at the beginning of this document.

  • external_ids: map of string-string pairs
  • other_config: map of string-string pairs

✨ SSL TABLE ✨

bestie this is where you set up all the SSL/TLS drama for talking to the ovn-nb database 💅🔐

🎀 Summary 🎀

private_key                   string
certificate                   string
ca_cert                       string
bootstrap_ca_cert             boolean
ssl_protocols                 string
ssl_ciphers                   string
ssl_ciphersuites              string
Common Columns:
  external_ids                map of string-string pairs

🔍 Details 🔍

  • private_key: string — the name of a PEM file holding the private key that acts as this switch's whole identity for SSL/TLS connections to the controller. it's giving "who dis" energy 🔑
  • certificate: string — the name of a PEM file with a certificate, signed by the certificate authority (CA) that the controller and manager use, which certifies the switch's private key and marks it as a trustworthy switch 🫶📜
  • ca_cert: string — the name of a PEM file with the CA certificate that's used to verify the switch is actually connected to a trustworthy controller and not some random impostor 🙈
  • bootstrap_ca_cert: boolean — if you set this to true, then Open vSwitch will try to grab the CA certificate from the controller on its very first SSL/TLS connection and save it into the named PEM file. if that works out, it immediately drops the connection and reconnects, and from then on every SSL/TLS connection has to be authenticated by a certificate signed by the CA certificate it just got. so yeah…
⚠️ no cap, this option literally exposes the SSL/TLS connection to a man-in-the-middle attack getting the initial CA certificate. it may still be useful for bootstrapping, but know what you're doing 💀
  • ssl_protocols: string — a range, or a comma- or space-delimited list, of the SSL/TLS protocols you want enabled for SSL/TLS connections 🌈

supported protocols include TLSv1.2 and TLSv1.3. ranges can be given as two protocol names separated with a dash (TLSv1.2-TLSv1.3), or as a single protocol name with a plus sign (TLSv1.2+). the value can be a list of protocols or exactly one range. the range is the preferred way of specifying protocols, and the configuration always behaves as if the range between the minimum and the maximum specified version is provided — like, if the value is set to TLSv1.X,TLSv1.(X+2), then TLSv1.(X+1) will also be enabled as if it was a range. and regardless of order, the highest protocol supported by both sides will be chosen when making the connection 👑

the default when this option is omitted is TLSv1.2+. periodt.

  • ssl_ciphers: string — the list of ciphers (in OpenSSL cipher string format) to be supported for SSL/TLS connections with TLSv1.2. the default when this option is omitted is DEFAULT:@SECLEVEL=2 🔒
  • ssl_ciphersuites: string — the list of ciphersuites (in OpenSSL ciphersuites string format) to be supported for SSL/TLS connections with TLSv1.3 and later. when this option is omitted, the default value from OpenSSL gets used 🦋

💫 Common Columns 💫

the overall purpose of these columns is described under Common Columns at the beginning of this document, iykyk.

  • external_ids: map of string-string pairs

🌉 Bridge TABLE 🌉

🎀 Summary 🎀

name                          string (must be unique within table)
options                       map of string-string pairs
external_ids                  map of string-string pairs

🔍 Details 🔍

  • name: string (must be unique within table) — the name of the OVS bridge. this bridge should already exist in the local OVS database, so don't come in here expecting it to be invented on the spot 🙈🌉
  • options: map of string-string pairs — reserved for future use. that's it, that's the whole thing 😭
  • external_ids: map of string-string pairs — see External IDs at the beginning of this document.

🧠 Logical_Flow TABLE 🧠

🎀 Summary 🎀

bridge                        optional Bridge
table_id                      integer, in range 0 to 100
priority                      integer, in range 0 to 65,535
match                         string
actions                       string
external_ids                  map of string-string pairs

🔍 Details 🔍

  • bridge: optional Bridge — the bridge that this logical flow belongs to 🌉
  • table_id: integer, in range 0 to 100 — the stage in the logical pipeline, which is basically analogous to an OpenFlow table number 💅
  • priority: integer, in range 0 to 65,535 — the flow's priority. flows with a numerically higher priority take precedence over the lower ones. but listen: if two logical flows with the same priority both match, then the one that actually gets applied to the packet is undefined 😭 so maybe don't do that
  • match: string — a matching expression. OVN gives you a superset of OpenFlow matching capabilities, using a syntax that's similar to Boolean expressions in a programming language 🧚

please see the documentation of the match column of the Logical_Flow table in the OVN_Southbound database 📖

  • actions: string — logical datapath actions, to be executed when the logical flow represented by this row is the highest-priority match 🔥

actions share lexical syntax with the match column. an empty set of actions (or one that contains just white space or comments), or a set of actions that consists of just drop;, causes the matched packets to be dropped. otherwise, the column should contain a sequence of actions, each terminated by a semicolon.

please see the documentation of the actions column of the Logical_Flow table in the OVN_Southbound database 📖

okay so while ovn-br-controller technically supports all OVN logical flow actions defined in the actions column of the Logical_Flow table in the OVN_Southbound, some actions are not intended for use by the CMS. these include controller OpenFlow actions (e.g., put_dhcp_opts, dns_lookup) and OVN-specific actions (e.g., look_arp, look_fdb) 🙅♀️

it's the CMS's responsibility to avoid using such actions. when the CMS defines the packet pipeline in the OVS bridge and adds logical flows using ovn-br-controller, it's expected to be mindful of using only relevant OVN actions, bestie 🫶

  • external_ids: map of string-string pairs — see External IDs at the beginning of this document.

and that's the whole page, babe!! 💖 this was ovn-bridge-controller(5), from Open vSwitch 26.09.1, rocking DB Schema 0.0.1, and it's got a date on it too so you know it's fresh. go forth and slay those logical flows 👑✨🦋

📦 where this page comes from