OVSDB(5) Open vSwitch OVSDB(5)

NAME
ovsdb - Open vSwitch Database (File Formats)

DESCRIPTION
OVSDB, the Open vSwitch Database, is a database system whose network
protocol is specified by RFC 7047. The RFC does not specify an on-disk
storage format. The OVSDB implementation in Open vSwitch implements
two storage formats: one for standalone (and active-backup) databases,
and the other for clustered databases. This manpage documents both of
these formats.

Most users do not need to be concerned with this specification. In‐
stead, to manipulate OVSDB files, refer to ovsdb-tool(1). For an in‐
troduction to OVSDB as a whole, read ovsdb(7).

OVSDB files explicitly record changes that are implied by the database
schema. For example, the OVSDB “garbage collection” feature means that
when a client removes the last reference to a garbage-collected row,
the database server automatically removes that row. The database file
explicitly records the deletion of the garbage-collected row, so that
the reader does not need to infer it.

OVSDB files do not include the values of ephemeral columns.

Standalone and clustered database files share the common structure de‐
scribed here. They are text files encoded in UTF-8 with LF (U+000A)
line ends, organized as append-only series of records. Each record
consists of 2 lines of text.

The first line in each record has the format OVSDB <magic> <length>
<hash>, where <magic> is JSON for standalone databases or CLUSTER for
clustered databases, <length> is a positive decimal integer, and <hash>
is a SHA-1 checksum expressed as 40 hexadecimal digits. Words in the
first line must be separated by exactly one space.

The second line must be exactly length bytes long (including the LF)
and its SHA-1 checksum (including the LF) must match hash exactly. The
line’s contents must be a valid JSON object as specified by RFC 4627.
Strings in the JSON object must be valid UTF-8. To ensure that the
second line is exactly one line of text, the OVSDB implementation ex‐
presses any LF characters within a JSON string as \n. For the same
reason, and to save space, the OVSDB implementation does not “pretty
print” the JSON object with spaces and LFs. (The OVSDB implementation
tolerates LFs when reading an OVSDB database file, as long as length
and hash are correct.)

JSON Notation
We use notation from RFC 7047 here to describe the JSON data in
records. In addition to the notation defined there, we add the follow‐
ing:

<raw-uuid>
A 36-character JSON string that contains a UUID in the format
described by RFC 4122, e.g.
"550e8400-e29b-41d4-a716-446655440000"

Standalone Format
The first record in a standalone database contains the JSON schema for
the database, as specified in RFC 7047. Only this record is mandatory
(a standalone file that contains only a schema represents an empty
database).

The second and subsequent records in a standalone database are transac‐
tion records. Each record may have the following optional special mem‐
bers, which do not have any semantics but are often useful to adminis‐
trators looking through a database log with ovsdb-tool show-log:

"_date": <integer>
The time at which the transaction was committed, as an integer
number of milliseconds since the Unix epoch. Early versions of
OVSDB counted seconds instead of milliseconds; these can be de‐
tected by noticing that their values are less than 2**32.

OVSDB always writes a _date member.

"_comment": <string>
A JSON string that specifies the comment provided in a transac‐
tion comment operation. If a transaction has multiple comment
operations, OVSDB concatenates them into a single _comment mem‐
ber, separated by a new-line.

OVSDB only writes a _comment member if it would be a nonempty
string.

Each of these records also has one or more additional members, each of
which maps from the name of a database table to a <table-txn>:

<table-txn>
A JSON object that describes the effects of a transaction on a
database table. Its names are <raw-uuid>s for rows in the table
and its values are <row-txn>s.

<row-txn>
Either null, which indicates that the transaction deleted this
row, or a JSON object that describes how the transaction in‐
serted or modified the row, whose names are the names of columns
and whose values are <value>s that give the column’s new value.

For new rows, the OVSDB implementation omits columns whose val‐
ues have the default values for their types defined in RFC 7047
section 5.2.1; for modified rows, the OVSDB implementation omits
columns whose values are unchanged.

Clustered Format
The clustered format has the following additional notation:

<uint64>
A JSON integer that represents a 64-bit unsigned integer. The
OVS JSON implementation only supports integers in the range
-2**63 through 2**63-1, so 64-bit unsigned integer values from
2**63 through 2**64-1 are expressed as negative numbers.

<address>
A JSON string that represents a network address to support clus‐
tering, in the <protocol>:<ip>:<port> syntax described in
ovsdb-tool(1).

<servers>
A JSON object whose names are <raw-uuid>s that identify servers
and whose values are <address>es that specify those servers’ ad‐
dresses.

<cluster-txn>
A JSON array with two elements:

1. The first element is either a <database-schema> or null. A
<database-schema> element is always present in the first
record of a clustered database to indicate the database’s
initial schema. If it is not null in a later record, it in‐
dicates a change of schema for the database.

2. The second element is either a transaction record in the for‐
mat described under Standalone Format above, or null.

When a schema is present, the transaction record is relative to
an empty database. That is, a schema change effectively resets
the database to empty and the transaction record represents the
full database contents. This allows readers to be ignorant of
the full semantics of schema change.

The first record in a clustered database contains the following mem‐
bers, all of which are required, except prev_election_timer:

"server_id": <raw-uuid>
The server’s own UUID, which must be unique within the cluster.

"local_address": <address>
The address on which the server listens for connections from
other servers in the cluster.

"name": <id>
The database schema name. It is only important when a server is
in the process of joining a cluster: a server will only join a
cluster if the name matches. (If the database schema name were
unique, then we would not also need a cluster ID.)

"cluster_id": <raw-uuid>
The cluster’s UUID. The all-zeros UUID is not a valid cluster
ID.

"prev_term": <uint64> and "prev_index": <uint64>
The Raft term and index just before the beginning of the log.

"prev_servers": <servers>
The set of one or more servers in the cluster at index “prev_in‐
dex” and term “prev_term”. It might not include this server, if
it was not the initial server in the cluster.

"prev_election_timer": <uint64>
The election base time before the beginning of the log. If not
exist, the default value 1000 ms is used as if it exists this
record.

"prev_data": <json-value> and "prev_eid": <raw-uuid>
A snapshot of the data in the database at index “prev_index” and
term “prev_term”, and the entry ID for that data. The snapshot
must contain a schema.

The second and subsequent records, if present, in a clustered database
represent changes to the database, to the cluster state, or both.
There are several types of these records. The most important types of
records directly represent persistent state described in the Raft spec‐
ification:

Entry A Raft log entry.

Term The start of a new term.

Vote The server’s vote for a leader in the current term.

The following additional types of records aid debugging and trou‐
bleshooting, but they do not affect correctness.

Leader Identifies a newly elected leader for the current term.

Commit Index
An update to the server’s commit_index.

Note A human-readable description of some event.

The table below identifies the members that each type of record con‐
tains. “yes” indicates that a member is required, “?” that it is op‐
tional, blank that it is forbidden, and [1] that data and eid must be
either both present or both absent.
┌────────────┬───────┬──────┬──────┬────────┬────────────┬──────┐
│ member │ Entry │ Term │ Vote │ Leader │ Commit In‐ │ Note │
│ │ │ │ │ │ dex │ │
├────────────┼───────┼──────┼──────┼────────┼────────────┼──────┤
│ comment │ ? │ ? │ ? │ ? │ ? │ ? │
├────────────┼───────┼──────┼──────┼────────┼────────────┼──────┤
│ term │ yes │ yes │ yes │ yes │ │ │
├────────────┼───────┼──────┼──────┼────────┼────────────┼──────┤
│ index │ yes │ │ │ │ │ │
├────────────┼───────┼──────┼──────┼────────┼────────────┼──────┤
│ servers │ ? │ │ │ │ │ │
├────────────┼───────┼──────┼──────┼────────┼────────────┼──────┤
│ elec‐ │ ? │ │ │ │ │ │
│ tion_timer │ │ │ │ │ │ │
├────────────┼───────┼──────┼──────┼────────┼────────────┼──────┤
│ data │ [1] │ │ │ │ │ │
├────────────┼───────┼──────┼──────┼────────┼────────────┼──────┤
│ eid │ [1] │ │ │ │ │ │
├────────────┼───────┼──────┼──────┼────────┼────────────┼──────┤
│ vote │ │ │ yes │ │ │ │
├────────────┼───────┼──────┼──────┼────────┼────────────┼──────┤
│ leader │ │ │ │ yes │ │ │
├────────────┼───────┼──────┼──────┼────────┼────────────┼──────┤
│ commit_in‐ │ │ │ │ │ yes │ │
│ dex │ │ │ │ │ │ │
├────────────┼───────┼──────┼──────┼────────┼────────────┼──────┤
│ note │ │ │ │ │ │ yes │
└────────────┴───────┴──────┴──────┴────────┴────────────┴──────┘

The members are:

"comment": <string>
A human-readable string giving an administrator more information
about the reason a record was emitted.

"term": <uint64>
The term in which the activity occurred.

"index": <uint64>
The index of a log entry.

"servers": <servers>
Server configuration in a log entry.

"election_timer": <uint64>
Leader election timeout base value in a log entry.

"data": <json-value>
The data in a log entry.

"eid": <raw-uuid>
Entry ID in a log entry.

"vote": <raw-uuid>
The server ID for which this server voted.

"leader": <raw-uuid>
The server ID of the server. Emitted by both leaders and fol‐
lowers when a leader is elected.

"commit_index": <uint64>
Updated commit_index value.

"note": <string>
One of a few special strings indicating important events. The
currently defined strings are:

"transfer leadership"
This server transferred leadership to a different server
(with details included in comment).

"left" This server finished leaving the cluster. (This lets
subsequent readers know that the server is not part of
the cluster and should not attempt to connect to it.)

Joining a Cluster
In addition to general format for a clustered database, there is also a
special case for a database file created by ovsdb-tool join-cluster.
Such a file contains exactly one record, which conveys the information
passed to the join-cluster command. It has the following members:

"server_id": <raw-uuid> and "local_address": <address> and "name": <id>
These have the same semantics described above in the general de‐
scription of the format.

"cluster_id": <raw-uuid>
This is provided only if the user gave the --cid option to
join-cluster. It has the same semantics described above.

"remote_addresses"; [<address>*]
One or more remote servers to contact for joining the cluster.

When the server successfully joins the cluster, the database file is
replaced by one described in Clustered Format.

AUTHOR
The Open vSwitch Development Community

3.4 Nov 16, 2024 OVSDB(5)