Ubuntu Manpage: ovsdb - Open vSwitch Database (Overview)

Provided by: openvswitch-common_3.4.0-1_amd64

NAME

       ovsdb - Open vSwitch Database (Overview)

DESCRIPTION

OVSDB, the Open vSwitch Database, is a network-accessible database system. Schemas in
OVSDB specify the tables in a database and their columns’ types and can include data,
uniqueness, and referential integrity constraints. OVSDB offers atomic, consistent,
isolated, durable transactions. RFC 7047 specifies the JSON-RPC based protocol that OVSDB
clients and servers use to communicate.

The OVSDB protocol is well suited for state synchronization because it allows each client
to monitor the contents of a whole database or a subset of it. Whenever a monitored
portion of the database changes, the server tells the client what rows were added or
modified (including the new contents) or deleted. Thus, OVSDB clients can easily keep
track of the newest contents of any part of the database.

While OVSDB is general-purpose and not particularly specialized for use with Open vSwitch,
Open vSwitch does use it for multiple purposes. The leading use of OVSDB is for
configuring and monitoring ovs-vswitchd(8), the Open vSwitch switch daemon, using the
schema documented in ovs-vswitchd.conf.db(5). The Open Virtual Network (OVN) project uses
two OVSDB schemas, documented as part of that project. Finally, Open vSwitch includes the
“VTEP” schema, documented in vtep(5) that many third-party hardware switches support for
configuring VXLAN, although OVS itself does not directly use this schema.

The OVSDB protocol specification allows independent, interoperable implementations of
OVSDB to be developed. Open vSwitch includes an OVSDB server implementation named
ovsdb-server(1), which supports several protocol extensions documented in its manpage, and
a basic command-line OVSDB client named ovsdb-client(1), as well as OVSDB client libraries
for C and for Python. Open vSwitch documentation often speaks of these OVSDB
implementations in Open vSwitch as simply “OVSDB,” even though that is distinct from the
OVSDB protocol; we make the distinction explicit only when it might otherwise be unclear
from the context.

In addition to these generic OVSDB server and client tools, Open vSwitch includes tools
for working with databases that have specific schemas: ovs-vsctl works with the
ovs-vswitchd configuration database and vtep-ctl works with the VTEP database.

RFC 7047 specifies the OVSDB protocol but it does not specify an on-disk storage format.
Open vSwitch includes ovsdb-tool(1) for working with its own on-disk database formats.
The most notable feature of this format is that ovsdb-tool(1) makes it easy for users to
print the transactions that have changed a database since the last time it was compacted.
This feature is often useful for troubleshooting.

SCHEMAS

Schemas in OVSDB have a JSON format that is specified in RFC 7047. They are often stored
in files with an extension .ovsschema. An on-disk database in OVSDB includes a schema and
data, embedding both into a single file. The Open vSwitch utility ovsdb-tool has commands
that work with schema files and with the schemas embedded in database files.

An Open vSwitch schema has three important identifiers. The first is its name, which is
also the name used in JSON-RPC calls to identify a database based on that schema. For
example, the schema used to configure Open vSwitch has the name Open_vSwitch. Schema
names begin with a letter or an underscore, followed by any number of letters,
underscores, or digits. The ovsdb-tool commands schema-name and db-name extract the
schema name from a schema or database file, respectively.

An OVSDB schema also has a version of the form x.y.z e.g. 1.2.3. Schemas managed within
the Open vSwitch project manage version numbering in the following way (but OVSDB does not
mandate this approach). Whenever we change the database schema in a non-backward
compatible way (e.g. when we delete a column or a table), we increment <x> and set <y> and
<z> to 0. When we change the database schema in a backward compatible way (e.g. when we
add a new column), we increment <y> and set <z> to 0. When we change the database schema
cosmetically (e.g. we reindent its syntax), we increment <z>. The ovsdb-tool commands
schema-version and db-version extract the schema version from a schema or database file,
respectively.

Very old OVSDB schemas do not have a version, but RFC 7047 mandates it.

An OVSDB schema optionally has a “checksum.” RFC 7047 does not specify the use of the
checksum and recommends that clients ignore it. Open vSwitch uses the checksum to remind
developers to update the version: at build time, if the schema’s embedded checksum,
ignoring the checksum field itself, does not match the schema’s content, then it fails the
build with a recommendation to update the version and the checksum. Thus, a developer who
changes the schema, but does not update the version, receives an automatic reminder. In
practice this has been an effective way to ensure compliance with the version number
policy. The ovsdb-tool commands schema-cksum and db-cksum extract the schema checksum
from a schema or database file, respectively.

SERVICE MODELS

OVSDB supports four service models for databases: standalone, active-backup, relay and
clustered. The service models provide different compromises among consistency,
availability, and partition tolerance. They also differ in the number of servers required
and in terms of performance. The standalone and active-backup database service models
share one on-disk format, and clustered databases use a different format, but the OVSDB
programs work with both formats. ovsdb(5) documents these file formats. Relay databases
have no on-disk storage.

RFC 7047, which specifies the OVSDB protocol, does not mandate or specify any particular
service model.

The following sections describe the individual service models.

Standalone Database Service Model
A standalone database runs a single server. If the server stops running, the database
becomes inaccessible, and if the server’s storage is lost or corrupted, the database’s
content is lost. This service model is appropriate when the database controls a process
or activity to which it is linked via “fate-sharing.” For example, an OVSDB instance that
controls an Open vSwitch virtual switch daemon, ovs-vswitchd, is a standalone database
because a server failure would take out both the database and the virtual switch.

To set up a standalone database, use ovsdb-tool create to create a database file, then run
ovsdb-server to start the database service.

To configure a client, such as ovs-vswitchd or ovs-vsctl, to use a standalone database,
configure the server to listen on a “connection method” that the client can reach, then
point the client to that connection method. See Connection Methods below for information
about connection methods.

Open vSwitch 3.3 introduced support for configuration files via --config-file command line
option. The configuration file for a server with a standalone database may look like
this:

{
"remotes": { "<connection method>": {} },
"databases": { "<database file>": {} }
}

ovsdb-server will infer the service model from the database file itself. However, if
additional verification is desired, an optional "service-model": "standalone" can be
provided for the database file inside the inner curly braces. If the specified
service-model will not match the content of the database file, ovsdb-server will refuse to
open this database.

Active-Backup Database Service Model
An active-backup database runs two servers (on different hosts). At any given time, one
of the servers is designated with the active role and the other the backup role. An
active server behaves just like a standalone server. A backup server makes an OVSDB
connection to the active server and uses it to continuously replicate its content as it
changes in real time. OVSDB clients can connect to either server but only the active
server allows data modification or lock transactions.

Setup for an active-backup database starts from a working standalone database service,
which is initially the active server. On another node, to set up a backup server, create
a database file with the same schema as the active server. The initial contents of the
database file do not matter, as long as the schema is correct, so ovsdb-tool create will
work, as will copying the database file from the active server. Then use ovsdb-server
--sync-from=<active> to start the backup server, where <active> is an OVSDB connection
method (see Connection Methods below) that connects to the active server. At that point,
the backup server will fetch a copy of the active database and keep it up-to-date until it
is killed.

Open vSwitch 3.3 introduced support for configuration files via --config-file command line
option. The configuration file for a backup server in this case may look like this:

{
"remotes": { "<connection method>": {} },
"databases": {
"<database file>": {
"service-model": "active-backup",
"backup": true,
"source": {
"<active>": {
"inactivity-probe": <integer>,
"max-backoff": <integer>
}
}
}
}
}

All the fields in the "<database file>" description above are required. Options for the
"<active>" connection method ("inactivity-probe", etc.) can be omitted.

When the active server in an active-backup server pair fails, an administrator can switch
the backup server to an active role with the ovs-appctl command
ovsdb-server/disconnect-active-ovsdb-server. Clients then have read/write access to the
now-active server. When the --config-file is in use, the same can be achieved by changing
the "backup" value in the file and running ovsdb-server/reload command. Of course,
administrators are slow to respond compared to software, so in practice external
management software detects the active server’s failure and changes the backup server’s
role. For example, the “Integration Guide for Centralized Control” in the OVN
documentation describes how to use Pacemaker for this purpose in OVN.

Suppose an active server fails and its backup is promoted to active. If the failed server
is revived, it must be started as a backup server. Otherwise, if both servers are active,
then they may start out of sync, if the database changed while the server was down, and
they will continue to diverge over time. This also happens if the software managing the
database servers cannot reach the active server and therefore switches the backup to
active, but other hosts can reach both servers. These “split-brain” problems are
unsolvable in general for server pairs.

Compared to a standalone server, the active-backup service model somewhat increases
availability, at a risk of split-brain. It adds generally insignificant performance
overhead. On the other hand, the clustered service model, discussed below, requires at
least 3 servers and has greater performance overhead, but it avoids the need for external
management software and eliminates the possibility of split-brain.

Open vSwitch 2.6 introduced support for the active-backup service model.

IMPORTANT:
There was a change of a database file format in version 2.15. To upgrade/downgrade the
ovsdb-server processes across this version follow the instructions described under
Upgrading from version 2.14 and earlier to 2.15 and later and Downgrading from version
2.15 and later to 2.14 and earlier.

Another change happened in version 3.2. To upgrade/downgrade the ovsdb-server
processes across this version follow the instructions described under Upgrading from
version 3.1 and earlier to 3.2 and later and Downgrading from version 3.2 and later to
3.1 and earlier.

Clustered Database Service Model
A clustered database runs across 3 or 5 or more database servers (the cluster) on
different hosts. Servers in a cluster automatically synchronize writes within the
cluster. A 3-server cluster can remain available in the face of at most 1 server failure;
a 5-server cluster tolerates up to 2 failures. Clusters larger than 5 servers will also
work, with every 2 added servers allowing the cluster to tolerate 1 more failure, but
write performance decreases. The number of servers should be odd: a 4- or 6-server
cluster cannot tolerate more failures than a 3- or 5-server cluster, respectively.

To set up a clustered database, first initialize it on a single node by running ovsdb-tool
create-cluster, then start ovsdb-server. Depending on its arguments, the create-cluster
command can create an empty database or copy a standalone database’s contents into the new
database.

Open vSwitch 3.3 introduced support for configuration files via --config-file command line
option. The configuration file for a server with a clustered database may look like this:

{
"remotes": { "<connection method>": {} },
"databases": { "<database file>": {} }
}

ovsdb-server will infer the service model from the database file itself. However, if
additional verification is desired, an optional "service-model": "clustered" can be
provided for the database file inside the inner curly braces. If the specified
service-model will not match the content of the database file, ovsdb-server will refuse to
open this database.

To configure a client to use a clustered database, first configure all of the servers to
listen on a connection method that the client can reach, then point the client to all of
the servers’ connection methods, comma-separated. See Connection Methods, below, for more
detail.

Open vSwitch 2.9 introduced support for the clustered service model.

How to Maintain a Clustered Database
To add a server to a cluster, run ovsdb-tool join-cluster on the new server and start
ovsdb-server. To remove a running server from a cluster, use ovs-appctl to invoke the
cluster/leave command. When a server fails and cannot be recovered, e.g. because its hard
disk crashed, or to otherwise remove a server that is down from a cluster, use ovs-appctl
to invoke cluster/kick to make the remaining servers kick it out of the cluster.

The above methods for adding and removing servers only work for healthy clusters, that is,
for clusters with no more failures than their maximum tolerance. For example, in a
3-server cluster, the failure of 2 servers prevents servers joining or leaving the cluster
(as well as database access).

To prevent data loss or inconsistency, the preferred solution to this problem is to bring
up enough of the failed servers to make the cluster healthy again, then if necessary
remove any remaining failed servers and add new ones. If this is not an option, see the
next section for Manual cluster recovery.

Once a server leaves a cluster, it may never rejoin it. Instead, create a new server and
join it to the cluster.

The servers in a cluster synchronize data over a cluster management protocol that is
specific to Open vSwitch; it is not the same as the OVSDB protocol specified in RFC 7047.
For this purpose, a server in a cluster is tied to a particular IP address and TCP port,
which is specified in the ovsdb-tool command that creates or joins the cluster. The TCP
port used for clustering must be different from that used for OVSDB clients. To change
the port or address of a server in a cluster, first remove it from the cluster, then add
it back with the new address.

To upgrade the ovsdb-server processes in a cluster from one version of Open vSwitch to
another, upgrading them one at a time will keep the cluster healthy during the upgrade
process. (This is different from upgrading a database schema, which is covered later
under Upgrading or Downgrading a Database.)

Clustered OVSDB does not support the OVSDB “ephemeral columns” feature. ovsdb-tool and
ovsdb-client change ephemeral columns into persistent ones when they work with schemas for
clustered databases. Future versions of OVSDB might add support for this feature.

Manual cluster recovery
IMPORTANT:
The procedure below will result in cid and sid change. A new cluster will be
initialized.

To recover a clustered database after a failure:

1. Stop all old cluster ovsdb-server instances before proceeding.

2. Pick one of the old members which will serve as a bootstrap member of the
to-be-recovered cluster.

3. Convert its database file to the standalone format using ovsdb-tool
cluster-to-standalone.

4. Backup the standalone database file.

5. Create a new single-node cluster with ovsdb-tool create-cluster using the previously
saved standalone database file, then start ovsdb-server.

6. Once the single-node cluster is up and running and serves the restored data, new
members should be created and added to the cluster, as usual, with ovsdb-tool
join-cluster.

NOTE:
The data in the new cluster may be inconsistent with the former cluster: transactions
not yet replicated to the server chosen in step 2 will be lost, and transactions not
yet applied to the cluster may be committed.

Upgrading from version 2.14 and earlier to 2.15 and later
There is a change of a database file format in version 2.15 that doesn’t allow older
versions of ovsdb-server to read the database file modified by the ovsdb-server version
2.15 or later. This also affects runtime communications between servers in active-backup
and cluster service models. To upgrade the ovsdb-server processes from one version of Open
vSwitch (2.14 or earlier) to another (2.15 or higher) instructions below should be
followed. (This is different from upgrading a database schema, which is covered later
under Upgrading or Downgrading a Database.)

In case of standalone service model no special handling during upgrade is required.

For the active-backup service model, administrator needs to update backup ovsdb-server
first and the active one after that, or shut down both servers and upgrade at the same
time.

For the cluster service model recommended upgrade strategy is following:

1. Upgrade processes one at a time. Each ovsdb-server process after upgrade should be
started with --disable-file-column-diff command line argument.

2. When all ovsdb-server processes upgraded, use ovs-appctl to invoke
ovsdb/file/column-diff-enable command on each of them or restart all ovsdb-server
processes one at a time without --disable-file-column-diff command line option.

Downgrading from version 2.15 and later to 2.14 and earlier
Similar to upgrading covered under Upgrading from version 2.14 and earlier to 2.15 and
later, downgrading from the ovsdb-server version 2.15 and later to 2.14 and earlier
requires additional steps. (This is different from upgrading a database schema, which is
covered later under Upgrading or Downgrading a Database.)

For all service models it’s required to:

1. Stop all ovsdb-server processes (single process for standalone service model, all
involved processes for active-backup and cluster service models).

2. Compact all database files with ovsdb-tool compact command.

3. Downgrade and restart ovsdb-server processes.

Upgrading from version 3.1 and earlier to 3.2 and later
There is another change of a database file format in version 3.2 that doesn’t allow older
versions of ovsdb-server to read the database file modified by the ovsdb-server version
3.2 or later. This also affects runtime communications between servers in cluster service
models. To upgrade the ovsdb-server processes from one version of Open vSwitch (3.1 or
earlier) to another (3.2 or higher) instructions below should be followed. (This is
different from upgrading a database schema, which is covered later under Upgrading or
Downgrading a Database.)

In case of standalone or active-backup service model no special handling during upgrade is
required.

For the cluster service model recommended upgrade strategy is following:

1. Upgrade processes one at a time. Each ovsdb-server process after upgrade should be
started with --disable-file-no-data-conversion command line argument.

2. When all ovsdb-server processes upgraded, use ovs-appctl to invoke
ovsdb/file/no-data-conversion-enable command on each of them or restart all
ovsdb-server processes one at a time without --disable-file-no-data-conversion command
line option.

Downgrading from version 3.2 and later to 3.1 and earlier
Similar to upgrading covered under Upgrading from version 3.1 and earlier to 3.2 and
later, downgrading from the ovsdb-server version 3.2 and later to 3.1 and earlier requires
additional steps. (This is different from upgrading a database schema, which is covered
later under Upgrading or Downgrading a Database.)

For all service models it’s required to:

1. Compact all database files via ovsdb-server/compact command with ovs-appctl utility.
This should be done for each involved ovsdb-server process separately (single process
for standalone service model, all involved processes for active-backup and cluster
service models).

2. Stop all ovsdb-server processes. Make sure that no database schema conversion
operations were performed between steps 1 and 2. For standalone and active-backup
service models, the database compaction can be performed after stopping all the
processes instead with the ovsdb-tool compact command.

3. Downgrade and restart ovsdb-server processes.

Understanding Cluster Consistency
To ensure consistency, clustered OVSDB uses the Raft algorithm described in Diego Ongaro’s
Ph.D. thesis, “Consensus: Bridging Theory and Practice”. In an operational Raft cluster,
at any given time a single server is the “leader” and the other nodes are “followers”.
Only the leader processes transactions, but a transaction is only committed when a
majority of the servers confirm to the leader that they have written it to persistent
storage.

In most database systems, read and write access to the database happens through
transactions. In such a system, Raft allows a cluster to present a strongly consistent
transactional interface. OVSDB uses conventional transactions for writes, but clients
often effectively do reads a different way, by asking the server to “monitor” a database
or a subset of one on the client’s behalf. Whenever monitored data changes, the server
automatically tells the client what changed, which allows the client to maintain an
accurate snapshot of the database in its memory. Of course, at any given time, the
snapshot may be somewhat dated since some of it could have changed without the change
notification yet being received and processed by the client.

Given this unconventional usage model, OVSDB also adopts an unconventional clustering
model. Each server in a cluster acts independently for the purpose of monitors and
read-only transactions, without verifying that data is up-to-date with the leader.
Servers forward transactions that write to the database to the leader for execution,
ensuring consistency. This has the following consequences:

• Transactions that involve writes, against any server in the cluster, are linearizable if
clients take care to use correct prerequisites, which is the same condition required for
linearizability in a standalone OVSDB. (Actually, “at-least-once” consistency, because
OVSDB does not have a session mechanism to drop duplicate transactions if a connection
drops after the server commits it but before the client receives the result.)

• Read-only transactions can yield results based on a stale version of the database, if
they are executed against a follower. Transactions on the leader always yield fresh
results. (With monitors, as explained above, a client can always see stale data even
without clustering, so clustering does not change the consistency model for monitors.)

• Monitor-based (or read-heavy) workloads scale well across a cluster, because clustering
OVSDB adds no additional work or communication for reads and monitors.

• A write-heavy client should connect to the leader, to avoid the overhead of followers
forwarding transactions to the leader.

• When a client conducts a mix of read and write transactions across more than one server
in a cluster, it can see inconsistent results because a read transaction might read
stale data whose updates have not yet propagated from the leader. By default, utilities
such as ovn-sbctl (in OVN) connect to the cluster leader to avoid this issue.

The same might occur for transactions against a single follower except that the OVSDB
server ensures that the results of a write forwarded to the leader by a given server are
visible at that server before it replies to the requesting client.

• If a client uses a database on one server in a cluster, then another server in the
cluster (perhaps because the first server failed), the client could observe stale data.
Clustered OVSDB clients, however, can use a column in the _Server database to detect
that data on a server is older than data that the client previously read. The OVSDB
client library in Open vSwitch uses this feature to avoid servers with stale data.

Relay Service Model
A relay database is a way to scale out read-mostly access to the existing database working
in any service model including relay.

Relay database creates and maintains an OVSDB connection with another OVSDB server. It
uses this connection to maintain an in-memory copy of the remote database (a.k.a. the
relay source) keeping the copy up-to-date as the database content changes on the relay
source in the real time.

The purpose of relay server is to scale out the number of database clients. Read-only
transactions and monitor requests are fully handled by the relay server itself. For the
transactions that request database modifications, relay works as a proxy between the
client and the relay source, i.e. it forwards transactions and replies between them.

Compared to the clustered and active-backup models, relay service model provides read and
write access to the database similarly to a clustered database (and even more scalable),
but with generally insignificant performance overhead of an active-backup model. At the
same time it doesn’t increase availability that needs to be covered by the service model
of the relay source.

Relay database has no on-disk storage and therefore cannot be converted to any other
service model.

If there is already a database started in any service model, to start a relay database
server use ovsdb-server relay:<DB_NAME>:<relay source>, where <DB_NAME> is the database
name as specified in the schema of the database that existing server runs, and <relay
source> is an OVSDB connection method (see Connection Methods below) that connects to the
existing database server. <relay source> could contain a comma-separated list of
connection methods, e.g. to connect to any server of the clustered database. Multiple
relay servers could be started for the same relay source.

Open vSwitch 3.3 introduced support for configuration files via --config-file command line
option. The configuration file for a relay database server in this case may look like
this:

{
"remotes": { "<connection method>": {} },
"databases": {
"<DB_NAME>": {
"service-model": "relay",
"source": {
"<relay source>": {
"inactivity-probe": <integer>,
"max-backoff": <integer>
}
}
}
}
}

Both the "service-model" and the "source" are required. Options for the "<relay source>"
connection method ("inactivity-probe", etc.) can be omitted.

Since the way relays handle read and write transactions is very similar to the clustered
model where “cluster” means “set of relay servers connected to the same relay source”,
“follower” means “relay server” and the “leader” means “relay source”, same consistency
consequences as for the clustered model applies to relay as well (See Understanding
Cluster Consistency above).

Open vSwitch 2.16 introduced support for relay service model.

DATABASE REPLICATION

       OVSDB  can  layer  replication  on top of any of its service models.  Replication, in this
       context, means to make, and keep up-to-date,  a  read-only  copy  of  the  contents  of  a
       database  (the  replica).   One  use  of  replication is to keep an up-to-date backup of a
       database.  A replica used solely for backup would not need to support clients of its  own.
       A  set  of  replicas  that  do serve clients could be used to scale out read access to the
       primary database, however Relay Service Model is more suitable for that purpose.

       A database replica is set up in the same way as a backup server in an active-backup  pair,
       with the difference that the replica is never promoted to an active role.

       A database can have multiple replicas.

       Open vSwitch 2.6 introduced support for database replication.

CONNECTION METHODS

       An  OVSDB  connection  method is a string that specifies how to make a JSON-RPC connection
       between an OVSDB client and server.  Connection methods  are  part  of  the  Open  vSwitch
       implementation  of  OVSDB  and  not  specified  by RFC 7047.  ovsdb-server uses connection
       methods to specify how it should listen for connections from clients and ovsdb-client uses
       them to specify how it should connect to a server.  Connections in the opposite direction,
       where ovsdb-server connects to a client that is  configured  to  listen  for  an  incoming
       connection, are also possible.

       Connection methods are classified as active or passive.  An active connection method makes
       an outgoing connection  to  a  remote  host;  a  passive  connection  method  listens  for
       connections  from  remote  hosts.   The  most  common arrangement is to configure an OVSDB
       server with passive connection methods  and  clients  with  active  ones,  but  the  OVSDB
       implementation in Open vSwitch supports the opposite arrangement as well.

       OVSDB supports the following active connection methods:

       ssl:<host>:<port>
              The specified SSL or TLS <port> on the given <host>.

       tcp:<host>:<port>
              The specified TCP <port> on the given <host>.

       unix:<file>
              On Unix-like systems, connect to the Unix domain server socket named <file>.

              On  Windows, connect to a local named pipe that is represented by a file created in
              the path <file> to mimic the behavior of a Unix domain socket.

       <method1>,<method2>,…,<methodN>
              For a clustered database service to be highly available, a client must be  able  to
              connect to any of the servers in the cluster.  To do so, specify connection methods
              for each of the servers separated by commas (and optional spaces).

              In theory, if machines go up and down and IP addresses change in the right  way,  a
              client  could talk to the wrong instance of a database.  To avoid this possibility,
              add cid:<uuid> to the list of methods, where  <uuid>  is  the  cluster  ID  of  the
              desired  database  cluster,  as  printed  by  ovsdb-tool  db-cid.   This feature is
              optional.

       OVSDB supports the following passive connection methods:

       pssl:<port>[:<ip>]
              Listen on the given TCP <port> for SSL or TLS connections.  By default, connections
              are not bound to a particular local IP address.  Specifying <ip> limits connections
              to those from the given IP.

       ptcp:<port>[:<ip>]
              Listen on the given TCP <port>.   By  default,  connections  are  not  bound  to  a
              particular  local IP address.  Specifying <ip> limits connections to those from the
              given IP.

       punix:<file>
              On Unix-like systems, listens for connections  on  the  Unix  domain  socket  named
              <file>.

              On  Windows,  listens  on a local named pipe, creating a named pipe <file> to mimic
              the behavior of  a  Unix  domain  socket.  The  ACLs  of  the  named  pipe  include
              LocalSystem, Administrators, and Creator Owner.

       All  IP-based  connection  methods  accept  IPv4  and  IPv6 addresses.  To specify an IPv6
       address, wrap it in square brackets, e.g.  ssl:[::1]:6640.   Passive  IP-based  connection
       methods  by  default  listen  for IPv4 connections only; use [::] as the address to accept
       both IPv4 and IPv6 connections, e.g. pssl:6640:[::].  DNS names are also accepted if built
       with  unbound  library.   On Linux, use %<device> to designate a scope for IPv6 link-level
       addresses, e.g. ssl:[fe80::1234%eth0]:6653.

       The <port> may be omitted from connection methods that use a  port  number.   The  default
       <port>  for  TCP-based  connection methods is 6640, e.g. pssl: is equivalent to pssl:6640.
       In  Open  vSwitch  prior  to  version  2.4.0,  the  default  port  was  6632.   To   avoid
       incompatibility  between  older  and  newer versions, we encourage users to specify a port
       number.

       The  ssl  and  pssl  connection  methods   requires   additional   configuration   through
       --private-key,  --certificate,  and  --ca-cert  command line options.  Open vSwitch can be
       built without SSL support, in which case these connection methods are not supported.

DATABASE LIFE CYCLE

This section describes how to handle various events in the life cycle of a database using
the Open vSwitch implementation of OVSDB.

Creating a Database
Creating and starting up the service for a new database was covered separately for each
database service model in the Service Models section, above. A single ovsdb-server
process may serve any number of databases with different service models at the same time.

Backing Up and Restoring a Database
OVSDB is often used in contexts where the database contents are not particularly valuable.
For example, in many systems, the database for configuring ovs-vswitchd is essentially
rebuilt from scratch at boot time. It is not worthwhile to back up these databases.

When OVSDB is used for valuable data, a backup strategy is worth considering. One way is
to use database replication, discussed above in Database Replication which keeps an
online, up-to-date copy of a database, possibly on a remote system. This works with all
OVSDB service models.

A more common backup strategy is to periodically take and store a snapshot. For the
standalone and active-backup service models, making a copy of the database file, e.g.
using cp, effectively makes a snapshot, and because OVSDB database files are append-only,
it works even if the database is being modified when the snapshot takes place. This
approach does not work for clustered databases.

Another way to make a backup, which works with all OVSDB service models, is to use
ovsdb-client backup, which connects to a running database server and outputs an atomic
snapshot of its schema and content, in the same format used for standalone and
active-backup databases.

Multiple options are also available when the time comes to restore a database from a
backup. For the standalone and active-backup service models, one option is to stop the
database server or servers, overwrite the database file with the backup (e.g. with cp),
and then restart the servers. Another way, which works with any service model, is to use
ovsdb-client restore, which connects to a running database server and replaces the data in
one of its databases by a provided snapshot. The advantage of ovsdb-client restore is
that it causes zero downtime for the database and its server. It has the downside that
UUIDs of rows in the restored database will differ from those in the snapshot, because the
OVSDB protocol does not allow clients to specify row UUIDs.

None of these approaches saves and restores data in columns that the schema designates as
ephemeral. This is by design: the designer of a schema only marks a column as ephemeral
if it is acceptable for its data to be lost when a database server restarts.

Clustering and backup serve different purposes. Clustering increases availability, but it
does not protect against data loss if, for example, a malicious or malfunctioning OVSDB
client deletes or tampers with data.

Changing Database Service Model
Use ovsdb-tool create-cluster to create a clustered database from the contents of a
standalone database. Use ovsdb-client backup to create a standalone database from the
contents of a running clustered database. When the cluster is down and cannot be revived,
ovsdb-client backup will not work.

Use ovsdb-tool cluster-to-standalone to convert clustered database to standalone database
when the cluster is down and cannot be revived.

Upgrading or Downgrading a Database
The evolution of a piece of software can require changes to the schemas of the databases
that it uses. For example, new features might require new tables or new columns in
existing tables, or conceptual changes might require a database to be reorganized in other
ways. In some cases, the easiest way to deal with a change in a database schema is to
delete the existing database and start fresh with the new schema, especially if the data
in the database is easy to reconstruct. But in many other cases, it is better to convert
the database from one schema to another.

The OVSDB implementation in Open vSwitch has built-in support for some simple cases of
converting a database from one schema to another. This support can handle changes that
add or remove database columns or tables or that eliminate constraints (for example,
changing a column that must have exactly one value into one that has one or more values).
It can also handle changes that add constraints or make them stricter, but only if the
existing data in the database satisfies the new constraints (for example, changing a
column that has one or more values into a column with exactly one value, if every row in
the column has exactly one value). The built-in conversion can cause data loss in obvious
ways, for example if the new schema removes tables or columns, or indirectly, for example
by deleting unreferenced rows in tables that the new schema marks for garbage collection.

Converting a database can lose data, so it is wise to make a backup beforehand.

To use OVSDB’s built-in support for schema conversion with a standalone or active-backup
database, first stop the database server or servers, then use ovsdb-tool convert to
convert it to the new schema, and then restart the database server.

OVSDB also supports online database schema conversion for any of its database service
models. To convert a database online, use ovsdb-client convert. The conversion is
atomic, consistent, isolated, and durable. ovsdb-server disconnects any clients connected
when the conversion takes place (except clients that use the set_db_change_aware Open
vSwitch extension RPC). Upon reconnection, clients will discover that the schema has
changed.

Schema versions and checksums (see Schemas above) can give hints about whether a database
needs to be converted to a new schema. If there is any question, though, the
needs-conversion command on ovsdb-tool and ovsdb-client can provide a definitive answer.

Working with Database History
Both on-disk database formats that OVSDB supports are organized as a stream of transaction
records. Each record describes a change to the database as a list of rows that were
inserted or deleted or modified, along with the details. Therefore, in normal operation,
a database file only grows, as each change causes another record to be appended at the
end. Usually, a user has no need to understand this file structure. This section covers
some exceptions.

Compacting Databases
If OVSDB database files were truly append-only, then over time they would grow without
bound. To avoid this problem, OVSDB can compact a database file, that is, replace it by a
new version that contains only the current database contents, as if it had been inserted
by a single transaction. From time to time, ovsdb-server automatically compacts a
database that grows much larger than its minimum size.

Because ovsdb-server automatically compacts databases, it is usually not necessary to
compact them manually, but OVSDB still offers a few ways to do it. First, ovsdb-tool
compact can compact a standalone or active-backup database that is not currently being
served by ovsdb-server (or otherwise locked for writing by another process). To compact
any database that is currently being served by ovsdb-server, use ovs-appctl to send the
ovsdb-server/compact command. Each server in an active-backup or clustered database
maintains its database file independently, so to compact all of them, issue this command
separately on each server.

Viewing History
The ovsdb-tool utility’s show-log command displays the transaction records in an OVSDB
database file in a human-readable format. By default, it shows minimal detail, but adding
the option -m once or twice increases the level of detail. In addition to the transaction
data, it shows the time and date of each transaction and any “comment” added to the
transaction by the client. The comments can be helpful for quickly understanding a
transaction; for example, ovs-vsctl adds its command line to the transactions that it
makes.

The show-log command works with both OVSDB file formats, but the details of the output
format differ. For active-backup and clustered databases, the sequence of transactions in
each server’s log will differ, even at points when they reflect the same data.

Truncating History
It may occasionally be useful to “roll back” a database file to an earlier point. Because
of the organization of OVSDB records, this is easy to do. Start by noting the record
number <i> of the first record to delete in ovsdb-tool show-log output. Each record is
two lines of plain text, so trimming the log is as simple as running head -n <j>, where
<j> = 2 * <i>.

Corruption
When ovsdb-server opens an OVSDB database file, of any kind, it reads as many transaction
records as it can from the file until it reaches the end of the file or it encounters a
corrupted record. At that point it stops reading and regards the data that it has read to
this point as the full contents of the database file, effectively rolling the database
back to an earlier point.

Each transaction record contains an embedded SHA-1 checksum, which the server verifies as
it reads a database file. It detects corruption when a checksum fails to verify. Even
though SHA-1 is no longer considered secure for use in cryptography, it is acceptable for
this purpose because it is not used to defend against malicious attackers.

The first record in a standalone or active-backup database file specifies the schema.
ovsdb-server will refuse to work with a database where this record is corrupted, or with a
clustered database file with corruption in the first few records. Delete and recreate
such a database, or restore it from a backup.

When ovsdb-server adds records to a database file in which it detected corruption, it
first truncates the file just after the last good record.

AUTHOR

       The Open vSwitch Development Community

COPYRIGHT

       2016-2024, The Open vSwitch Development Community