@@ -8,11 +8,7 @@ ovn/utilities/ovn-sbctl.8: \
lib/ssl-peer-ca-cert.man \
lib/ssl.man \
lib/table.man \
- lib/vlog.man \
- ovsdb/remote-active.man \
- ovsdb/remote-active.man \
- ovsdb/remote-passive.man \
- ovsdb/remote-passive.man
+ lib/vlog.man
ovn/utilities/ovn-sbctl.8.in:
lib/common.man:
lib/db-ctl-base.man:
@@ -21,10 +17,6 @@ lib/ssl-peer-ca-cert.man:
lib/ssl.man:
lib/table.man:
lib/vlog.man:
-ovsdb/remote-active.man:
-ovsdb/remote-active.man:
-ovsdb/remote-passive.man:
-ovsdb/remote-passive.man:
ovsdb/ovsdb-client.1: \
ovsdb/ovsdb-client.1.in \
@@ -41,8 +33,7 @@ ovsdb/ovsdb-client.1: \
lib/table.man \
lib/vlog-syn.man \
lib/vlog.man \
- ovsdb/remote-active.man \
- ovsdb/remote-passive.man
+ ovsdb/ovsdb-schemas.man
ovsdb/ovsdb-client.1.in:
lib/common-syn.man:
lib/common.man:
@@ -57,8 +48,7 @@ lib/ssl.man:
lib/table.man:
lib/vlog-syn.man:
lib/vlog.man:
-ovsdb/remote-active.man:
-ovsdb/remote-passive.man:
+ovsdb/ovsdb-schemas.man:
ovsdb/ovsdb-server.1: \
ovsdb/ovsdb-server.1.in \
@@ -82,11 +72,7 @@ ovsdb/ovsdb-server.1: \
lib/unixctl.man \
lib/vlog-syn.man \
lib/vlog-unixctl.man \
- lib/vlog.man \
- ovsdb/remote-active.man \
- ovsdb/remote-passive.man \
- ovsdb/replication-syn.man \
- ovsdb/replication.man
+ lib/vlog.man
ovsdb/ovsdb-server.1.in:
lib/common-syn.man:
lib/common.man:
@@ -109,22 +95,20 @@ lib/unixctl.man:
lib/vlog-syn.man:
lib/vlog-unixctl.man:
lib/vlog.man:
-ovsdb/remote-active.man:
-ovsdb/remote-passive.man:
-ovsdb/replication-syn.man:
-ovsdb/replication.man:
ovsdb/ovsdb-tool.1: \
ovsdb/ovsdb-tool.1.in \
lib/common-syn.man \
lib/common.man \
lib/vlog-syn.man \
- lib/vlog.man
+ lib/vlog.man \
+ ovsdb/ovsdb-schemas.man
ovsdb/ovsdb-tool.1.in:
lib/common-syn.man:
lib/common.man:
lib/vlog-syn.man:
lib/vlog.man:
+ovsdb/ovsdb-schemas.man:
utilities/bugtool/ovs-bugtool.8: \
utilities/bugtool/ovs-bugtool.8.in
@@ -264,11 +248,7 @@ utilities/ovs-vsctl.8: \
lib/table.man \
lib/vconn-active.man \
lib/vconn-passive.man \
- lib/vlog.man \
- ovsdb/remote-active.man \
- ovsdb/remote-active.man \
- ovsdb/remote-passive.man \
- ovsdb/remote-passive.man
+ lib/vlog.man
utilities/ovs-vsctl.8.in:
lib/common.man:
lib/db-ctl-base.man:
@@ -279,10 +259,6 @@ lib/table.man:
lib/vconn-active.man:
lib/vconn-passive.man:
lib/vlog.man:
-ovsdb/remote-active.man:
-ovsdb/remote-active.man:
-ovsdb/remote-passive.man:
-ovsdb/remote-passive.man:
vswitchd/ovs-vswitchd.8: \
vswitchd/ovs-vswitchd.8.in \
@@ -299,9 +275,7 @@ vswitchd/ovs-vswitchd.8: \
lib/vlog.man \
ofproto/ofproto-dpif-unixctl.man \
ofproto/ofproto-tnl-unixctl.man \
- ofproto/ofproto-unixctl.man \
- ovsdb/remote-active.man \
- ovsdb/remote-passive.man
+ ofproto/ofproto-unixctl.man
vswitchd/ovs-vswitchd.8.in:
lib/common.man:
lib/coverage-unixctl.man:
@@ -317,8 +291,6 @@ lib/vlog.man:
ofproto/ofproto-dpif-unixctl.man:
ofproto/ofproto-tnl-unixctl.man:
ofproto/ofproto-unixctl.man:
-ovsdb/remote-active.man:
-ovsdb/remote-passive.man:
vtep/vtep-ctl.8: \
vtep/vtep-ctl.8.in \
@@ -328,11 +300,7 @@ vtep/vtep-ctl.8: \
lib/ssl-peer-ca-cert.man \
lib/ssl.man \
lib/table.man \
- lib/vlog.man \
- ovsdb/remote-active.man \
- ovsdb/remote-active.man \
- ovsdb/remote-passive.man \
- ovsdb/remote-passive.man
+ lib/vlog.man
vtep/vtep-ctl.8.in:
lib/common.man:
lib/db-ctl-base.man:
@@ -341,7 +309,3 @@ lib/ssl-peer-ca-cert.man:
lib/ssl.man:
lib/table.man:
lib/vlog.man:
-ovsdb/remote-active.man:
-ovsdb/remote-active.man:
-ovsdb/remote-passive.man:
-ovsdb/remote-passive.man:
@@ -58,11 +58,8 @@ Otherwise, the default is \fBunix:@RUNDIR@/db.sock\fR, but this
default is unlikely to be useful outside of single-machine OVN test
environments.
.IP
-\fIserver\fR must take one of the following forms:
-.RS
-.so ovsdb/remote-active.man
-.so ovsdb/remote-passive.man
-.RE
+\fIserver\fR may be an OVSDB active or passive connection method,
+e.g. \fBssl:192.168.10.5:6640\fR, as described in \fBovsdb\fR(7).
.
.IP "\fB\-\-no\-syslog\fR"
By default, \fBovn\-sbctl\fR logs its arguments and the details of any
@@ -197,14 +194,10 @@ Deletes the configured connection(s).
.
.IP "\fBset\-connection\fR [\fIaccess\-specifier\fR] \fItarget\fR\&..."
Sets the configured manager target or targets. Each \fItarget\fR may
-be preceded by an optional access-specifier (\fBread\-only\fR or
-\fBread\-write\fR) and may use any of the following forms:
-.
-.RS
-.so ovsdb/remote-active.man
-.so ovsdb/remote-passive.man
-.RE
-
+may be an OVSDB active or passive connection method,
+e.g. \fBpssl:6640\fR, as described in \fBovsdb\fR(7),
+optionally preceded by an optional access-specifier (\fBread\-only\fR or
+\fBread\-write\fR).
If provided, the effect of the access specifier persists for subsequent
targets until changed by another access specifier.
.
@@ -1,3 +1,7 @@
+# overview
+man_MANS += ovsdb/ovsdb.7
+EXTRA_DIST += ovsdb/ovsdb.7.xml
+
# libovsdb
lib_LTLIBRARIES += ovsdb/libovsdb.la
ovsdb_libovsdb_la_LDFLAGS = \
@@ -43,8 +47,7 @@ pkgconfig_DATA += \
ovsdb/libovsdb.pc
MAN_FRAGMENTS += \
- ovsdb/remote-active.man \
- ovsdb/remote-passive.man \
+ ovsdb/ovsdb-schemas.man \
ovsdb/replication.man \
ovsdb/replication-syn.man
@@ -13,21 +13,34 @@
ovsdb\-client \- command-line interface to \fBovsdb-server\fR(1)
.
.SH SYNOPSIS
+.IP "Server-Level Commands:"
\fBovsdb\-client \fR[\fIoptions\fR] \fBlist\-dbs \fR[\fIserver\fR]
-.br
+.IP "Database Schema Commands:"
\fBovsdb\-client \fR[\fIoptions\fR] \fBget\-schema \fR[\fIserver\fR] \fR[\fIdatabase\fR]
.br
-\fBovsdb\-client \fR[\fIoptions\fR] \fBget\-schema\-version\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR]
-.br
\fBovsdb\-client \fR[\fIoptions\fR] \fBlist\-tables\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR]
.br
\fBovsdb\-client \fR[\fIoptions\fR] \fBlist\-columns\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR] [\fItable\fR]
+.IP "Database Version Management Commands:"
+\fBovsdb\-client \fR[\fIoptions\fR] \fBconvert \fR[\fIserver\fR] \fIschema\fR
+.br
+\fBovsdb\-client \fR[\fIoptions\fR] \fBneeds\-conversion \fR[\fIserver\fR] \fIschema\fR
+.br
+\fBovsdb\-client \fR[\fIoptions\fR] \fBget\-schema\-version\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR]
.br
+\fBovsdb\-client \fR[\fIoptions\fR] \fBget\-schema\-cksum\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR]
+.IP "Data Management Commands:"
\fBovsdb\-client \fR[\fIoptions\fR] \fBtransact\fI \fR[\fIserver\fR] \fItransaction\fR
.br
\fBovsdb\-client \fR[\fIoptions\fR] \fBdump\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR]\fR [\fItable\fR
[\fIcolumn\fR...]]
.br
+\fBovsdb\-client \fR[\fIoptions\fR]
+\fBbackup\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR] > \fIsnapshot\fR
+.br
+\fBovsdb\-client \fR[\fIoptions\fR]
+\fBrestore\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR] < \fIsnapshot\fR
+.br
\fBovsdb\-client \fR[\fIoptions\fR] \fBmonitor\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR] \fItable\fR
[\fIcolumn\fR[\fB,\fIcolumn\fR]...]...
.br
@@ -35,13 +48,14 @@ ovsdb\-client \- command-line interface to \fBovsdb-server\fR(1)
.br
\fBovsdb\-client \fR[\fIoptions\fR] \fBmonitor-cond\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR] \fIconditions
\fItable\fR [\fIcolumn\fR[\fB,\fIcolumn\fR]...]...
-.br
+.IP "Testing Commands:"
\fBovsdb\-client \fR[\fIoptions\fR] \fBlock\fI \fR[\fIserver\fR] \fIlock\fR
.br
\fBovsdb\-client \fR[\fIoptions\fR] \fBsteal\fI \fR[\fIserver\fR] \fIlock\fR
.br
\fBovsdb\-client \fR[\fIoptions\fR] \fBunlock\fI \fR[\fIserver\fR] \fIlock\fR
.br
+.IP "Other Commands:"
\fBovsdb\-client help\fR
.IP "Output formatting options:"
[\fB\-\-format=\fIformat\fR]
@@ -61,40 +75,35 @@ ovsdb\-client \- command-line interface to \fBovsdb-server\fR(1)
.SH DESCRIPTION
The \fBovsdb\-client\fR program is a command-line client for
interacting with a running \fBovsdb\-server\fR process.
-Each command connects to an OVSDB server, which is
-\fBunix:@RUNDIR@/db.sock\fR by default, or may be specified as
-\fIserver\fR in one of the following forms:
-.RS
-.so ovsdb/remote-active.man
-.so ovsdb/remote-passive.man
-.RE
+Each command connects to the specified OVSDB \fIserver\fR, which may
+be an OVSDB active or passive connection method, as described in
+\fBovsdb\fR(7). The default server is \fBunix:@RUNDIR@/db.sock\fR
+and
+the default \fIdatabase\fR is \fBOpen_vSwitch\fR.
+.PP
+For an introduction to OVSDB and its implementation in Open vSwitch,
+see \fBovsdb\fR(7).
.PP
-The default \fIdatabase\fR is \fBOpen_vSwitch\fR.
+The following sections describe the commands that \fBovsdb\-client\fR
+supports.
+.SS "Server-Level Commands"
+Most \fBovsdb\-client\fR commands work with an individual database,
+but these commands apply to an entire database server.
.
-.SS "Commands"
-The following commands are implemented:
.IP "\fBlist\-dbs \fR[\fIserver\fR]"
Connects to \fIserver\fR, retrieves the list of known databases, and
-prints them one per line. These database names are the ones that may
-be used for \fIdatabase\fR in the following commands.
+prints them one per line. These database names are the ones that
+other commands may use for \fIdatabase\fR.
+.
+.SS "Database Schema Commands"
+.PP
+These commands obtain the schema from a database and print it or part
+of it.
.
.IP "\fBget\-schema \fR[\fIserver\fR] \fR[\fIdatabase\fR]"
Connects to \fIserver\fR, retrieves the schema for \fIdatabase\fR, and
prints it in JSON format.
.
-.IP "\fBget\-schema\-version\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR]"
-Connects to \fIserver\fR, retrieves the schema for \fIdatabase\fR, and
-prints its version number on stdout. A schema version number has the form
-\fIx\fB.\fIy\fB.\fIz\fR. See \fBovs\-vswitchd.conf.db\fR(5) for
-details.
-.IP
-Schema version numbers and Open vSwitch version numbers are
-independent.
-.IP
-If \fIdatabase\fR was created before schema versioning was introduced,
-then it will not have a version number and this command will print a
-blank line.
-.
.IP "\fBlist\-tables\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR]"
Connects to \fIserver\fR, retrieves the schema for \fIdatabase\fR, and
prints a table listing the name of each table
@@ -106,10 +115,77 @@ prints a table listing the name and type of each
column. If \fItable\fR is specified, only columns in that table are
listed; otherwise, the tables include columns in all tables.
.
+.SS "Database Version Management Commands"
+.so ovsdb/ovsdb-schemas.man
+.PP
+These commands work with different versions of OVSDB schemas and
+databases.
+.
+.IP "\fBconvert \fR[\fIserver\fR] \fIschema\fR"
+Reads an OVSDB schema in JSON format, as specified in the OVSDB
+specification, from \fIschema\fR, then connects to \fIserver\fR and
+requests the server to convert the database whose name is specified in
+\fIschema\fR to the schema also specified in \fIschema\fR.
+.IP
+The conversion is atomic, consistent, isolated, and durable. The
+OVSDB protocol does not provide a way for the server to notify a
+client that a database's schema has changed, so currently
+\fBovsdb\-server\fR disconnects any clients connected when the
+conversion takes place. Upon reconnction, clients will discover that
+the schema has changed.
+.IP
+This command can do simple ``upgrades'' and ``downgrades'' on a
+database's schema. The data in the database must be valid when
+interpreted under \fIschema\fR, with only one exception: data for
+tables and columns that do not exist in \fIschema\fR are ignored.
+Columns that exist in \fIschema\fR but not in the database are set to
+their default values. All of \fIschema\fR's constraints apply in
+full.
+.IP
+Some uses of this command can cause unrecoverable data loss. For
+example, converting a database from a schema that has a given column
+or table to one that does not will delete all data in that column or
+table. Back up critical databases before converting them.
+.IP
+This command works with clustered and standalone databases.
+Standalone databases may also be converted with \fBovsdb\-tool\fR's
+\fBconvert\fR command.
+.
+.IP "\fBneeds\-conversion \fR[\fIserver\fR] \fIschema\fR"
+Reads the schema from \fIschema\fR, then connects to \fIserver\fR and
+requests the schema from the database whose name is specified in
+\fIschema\fR. If the two schemas are the same, prints \fBno\fR on
+stdout; if they differ, prints \fByes\fR.
+.
+.IP "\fBget\-schema\-version\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR]"
+Connects to \fIserver\fR, retrieves the schema for \fIdatabase\fR, and
+prints its version number on stdout.
+If \fIdatabase\fR was created before schema versioning was introduced,
+then it will not have a version number and this command will print a
+blank line.
+.
+.IP "\fBget\-schema\-cksum\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR]"
+Connects to \fIserver\fR, retrieves the schema for \fIdatabase\fR, and
+prints its checksum on stdout. If \fIdatabase\fR does not include a
+checksum, prints a blank line.
+.
+.SS "Data Management Commands"
+.PP
+These commands read or modify the data in a database.
+.
.IP "\fBtransact\fI \fR[\fIserver\fR] \fItransaction\fR"
Connects to \fIserver\fR, sends it the specified \fItransaction\fR,
-which must be a JSON array containing one or more valid OVSDB
-operations, and prints the received reply on stdout.
+which must be a JSON array appropriate for use as the \fBparams\fR to
+a JSON-RPC \fBtransact\fR request, and prints the received reply on
+stdout.
+.
+.IP "\fBquery\fI \fR[\fIserver\fR] \fItransaction\fR"
+Connects to \fIserver\fR, sends it the specified \fItransaction\fR,
+which must be a JSON array appropriate for use as the \fBparams\fR to
+a JSON-RPC \fBtransact\fR request, and prints the received reply on
+stdout. To ensure that the transaction does not modify the database,
+this command appends an \fBabort\fR operation to the set of operations
+included in \fItransaction\fR before sending it to the database.
.
.IP "\fBdump\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR]\fR [\fItable \fR[\fIcolumn\fR...]]"
Connects to \fIserver\fR, retrieves all of the data in \fIdatabase\fR,
@@ -117,6 +193,38 @@ and prints it on stdout as a series of tables. If \fItable\fR is
specified, only that table is retrieved. If at least one \fIcolumn\fR
is specified, only those columns are retrieved.
.
+.IP "\fBbackup\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR] > \fIsnapshot\fR"
+Connects to \fIserver\fR, retrieves a snapshot of the schema and data
+in \fIdatabase\fR, and prints it on stdout in the format used for
+OVSDB standalone and active-backup database. This is an appropriate
+way to back up a remote database. The database snapshot that it
+outputs is suitable to be served up directly by \fBovsdb\-server\fR or
+used as the input to \fBovsdb\-client restore\fR.
+.IP
+Another way to back up a standalone or active-backup database is to
+copy its database file, e.g. with \fBcp\fR. This is safe even if the
+database is in use.
+.IP
+The output does not include ephemeral columns, which by design do not
+survive across restarts of \fBovsdb\-server\fR.
+.
+.IP "\fBrestore\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR] < \fIsnapshot\fR"
+Reads \fIsnapshot\fR, which must be in the format used for OVSDB
+standalone and active-backup databases. Then, connects to
+\fIserver\fR, verifies that \fIdatabase\fR and \fIsnapshot\fR have the
+same schema, then deletes all of the data in \fIdatabase\fR and
+replaces it by \fIsnapshot\fR. The replacement happens atomically, in a
+single transaction.
+.IP
+UUIDs for rows in the restored database will differ from those in
+\fIsnapshot\fR, because the OVSDB protocol does not allow clients to
+specify row UUIDs. Another way to restore a standalone or
+active-backup database, which does also restore row UUIDs, is to stop
+the server or servers, replace the database file by the snapshot, then
+restart the database. Either way, ephemeral columns are not restored,
+since by design they do not survive across restarts of
+\fBovsdb\-server\fR.
+.
.IP "\fBmonitor\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR] \fItable\fR [\fIcolumn\fR[\fB,\fIcolumn\fR]...]..."
.IQ "\fBmonitor-cond\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR] \fIconditions\fR \fItable\fR [\fIcolumn\fR[\fB,\fIcolumn\fR]...]..."
Connects to \fIserver\fR and monitors the contents of rows that match conditions in
@@ -162,13 +270,13 @@ prints the initial database contents.
The \fBmonitor\fR command uses RFC 7047 "monitor" method to open a monitor
session with the server.
.
-.SH TESTING COMMANDS
-The following commands are mostly of interest for testing the correctness
+.SS "Testing commands"
+These commands are mostly of interest for testing the correctness
of the OVSDB server.
.
-.IP "\fBovsdb\-client\fR [\fIoptions\fR] \fBlock\fI \fR[\fIserver\fR] \fIlock\fR"
-.IQ "\fBovsdb\-client\fR [\fIoptions\fR] \fBsteal\fI \fR[\fIserver\fR] \fIlock\fR"
-.IQ "\fBovsdb\-client\fR [\fIoptions\fR] \fBunlock\fI \fR[\fIserver\fR] \fIlock\fR"
+.IP "\fBlock\fI \fR[\fIserver\fR] \fIlock\fR"
+.IQ "\fBsteal\fI \fR[\fIserver\fR] \fIlock\fR"
+.IQ "\fBunlock\fI \fR[\fIserver\fR] \fIlock\fR"
Connects to \fIserver\fR and issues corresponding RFC 7047 lock operations
on \fIlock\fR. Prints json reply or subsequent update messages.
The \fB\-\-detach\fR option causes \fBovsdb\-client\fR to detach after it
@@ -212,6 +320,6 @@ With any other command, they have no effect.
.so lib/common.man
.SH "SEE ALSO"
.
+\fBovsdb\fR(7),
\fBovsdb\-server\fR(1),
-\fBovsdb\-client\fR(1),
-and the OVSDB specification.
+\fBovsdb\-client\fR(1).
new file mode 100644
@@ -0,0 +1,19 @@
+.PP
+An OVSDB schema has a schema version number, and an OVSDB database
+embeds a particular version of an OVSDB schema. These version numbers
+take the form \fIx\fB.\fIy\fB.\fIz\fR, e.g. \fB1.2.3\fR. The OVSDB
+implementation does not enforce a particular version numbering scheme,
+but schemas managed within the Open vSwitch project use the following
+approach. Whenever the database schema is changed in a non-backward
+compatible way (e.g. deleting a column or a table), \fIx\fR is
+incremented (and \fIy\fR and \fIz\fR are reset to 0). When the
+database schema is changed in a backward compatible way (e.g. adding a
+new column), \fIy\fR is incremented (and \fIz\fR is reset to 0). When
+the database schema is changed cosmetically (e.g. reindenting its
+syntax), \fIz\fR is incremented.
+.PP
+Some OVSDB databases and schemas, especially very old ones, do not
+have a version number.
+.PP
+Schema version numbers and Open vSwitch version numbers are
+independent.
@@ -19,7 +19,10 @@ ovsdb\-server \- Open vSwitch database server
.so lib/daemon-syn.man
.so lib/service-syn.man
.so lib/vlog-syn.man
-.so ovsdb/replication-syn.man
+.IP "Active-backup options:"
+[\fB\-\-sync\-from=\fIserver\fR]
+[\fB\-\-sync\-exclude-tables=\fIdb\fB:\fItable\fR[\fB,\fIdb\fB:\fItable\fR]...\fR]
+[\fB\-\-active\fR]
.so lib/ssl-syn.man
.so lib/ssl-bootstrap-syn.man
.so lib/ssl-peer-ca-cert-syn.man
@@ -31,39 +34,26 @@ ovsdb\-server \- Open vSwitch database server
The \fBovsdb\-server\fR program provides RPC interfaces to one or more
Open vSwitch databases (OVSDBs). It supports JSON-RPC client
connections over active or passive TCP/IP or Unix domain sockets.
+For an introduction to OVSDB and its implementation in Open vSwitch,
+see \fBovsdb\fR(7).
.PP
Each OVSDB file may be specified on the command line as \fIdatabase\fR.
If none is specified, the default is \fB@DBDIR@/conf.db\fR. The database
files must already have been created and initialized using, for
example, \fBovsdb\-tool create\fR.
-.
-.SH "ACTIVE and BACKUP"
-\fBovsdb\-server\fR runs either as a backup server, or as an active server.
-When \fBovsdb\-server\fR is running as a backup server, all transactions that
-can modify the database content, including the lock commands are rejected.
-Active server, on the other hand, accepts all ovsdb server transactions.
-When \fBovsdb\-server\fR role changes, all existing client connection are
-reset, requiring clients to reconnect to the server.
-.PP
-By default, \fBovsdb\-server\fR runs as an active server, except when the
-\fB\-\-sync\-from=\fIserver\fR command line option is specified and without
-the \fB\-\-no\-sync option\fR. During runtime, \fBovsdb\-server\fR role can be switch by using appctl commands.
.PP
-\fBovsdb-server/connect\-active\-ovsdb\-server\fR switches
-\fBovsdb\-server\fR into a backup server, Conversely,
-\fBovsdb-server/disconnect\-active\-ovsdb\-server\fR switches server into
-an active one.
-.
+This OVSDB implementation supports standalone, active-backup, and
+clustered database service models, as well as database replication.
+See the Service Models section of \fBovsdb\fR(7) for more information.
.SH OPTIONS
.
.IP "\fB\-\-remote=\fIremote\fR"
Adds \fIremote\fR as a connection method used by \fBovsdb\-server\fR.
-\fIremote\fR must take one of the following forms:
+The \fIremote\fR may be an OVSDB active or passive connection method,
+e.g. \fBpssl:6640\fR, as described in \fBovsdb\fR(7). The following
+additional form is also supported:
.
.RS
-.so ovsdb/remote-passive.man
-.so ovsdb/remote-active.man
-.
.IP "\fBdb:\fIdb\fB,\fItable\fB,\fIcolumn\fR"
Reads additional connection methods from \fIcolumn\fR in all of the
rows in \fItable\fR within \fIdb\fR. As the contents of \fIcolumn\fR changes,
@@ -121,8 +111,52 @@ configured remotes.
.so lib/service.man
.SS "Logging Options"
.so lib/vlog.man
-.SS "Syncing Options"
-.so ovsdb/replication.man
+.SS "Active-Backup Options"
+These options support the \fBovsdb\-server\fR active-backup service
+model and database replication. These options apply only to databases
+in the format used for standalone and active-backup databases, which
+is the database format created by \fBovsdb\-tool create\fR. By
+default, when it serves a database in this format, \fBovsdb\-server\fR
+runs as a standalone server. These options can configure it for
+active-backup use:
+.IP \(bu
+Use \fB\-\-sync\-from=\fIserver\fR to start the server in the backup
+role, replicating data from \fIserver\fR. When \fBovsdb\-server\fR is
+running as a backup server, it rejects all transactions that can
+modify the database content, including lock commands. The same form
+can be used to configure the local database as a replica of
+\fIserver\fR.
+.IP \(bu
+Use \fB\-\-sync\-from=\fIserver\fB \-\-active\fR to start the server
+in the active role, but prepared to switch to the backup role in which
+it would replicate data from \fIserver\fR. When \fBovsdb\-server\fR
+runs in active mode, it allows all transactions, including those that
+modify the database.
+.PP
+At runtime, management commands can change a server's role and otherwise
+manage active-backup features. See \fBActive-Backup Commands\fR, below,
+for more information.
+.TP
+\fB\-\-sync\-from=\fIserver\fR
+Sets up \fBovsdb\-server\fR to synchronize its databases with the
+databases in \fIserver\fR, which must be an active connection method
+in one of the forms documented in \fBovsdb\-client\fR(1). Every
+transaction committed by \fIserver\fR will be replicated to
+\fBovsdb\-server\fR. This option makes \fBovsdb\-server\fR start
+as a backup server; add \fB\-\-active\fR to make it start as an
+active server.
+.TP
+\fB\-\-sync\-exclude-tables=\fIdb\fB:\fItable\fR[\fB,\fIdb\fB:\fItable\fR]...\fR
+Causes the specified tables to be excluded from replication.
+.TP
+\fB\-\-active\fR
+By default, \fB\-\-sync\-from\fR makes \fBovsdb\-server\fR start up as
+a backup for \fIserver\fR. With \fB\-\-active\fR, however,
+\fBovsdb\-server\fR starts as an active server. Use this option to
+allow the syncing options to be specified using command line options,
+yet start the server, as the default, active server. To switch the
+running server to backup mode, use \fBovs-appctl(1)\fR to execute the
+\fBovsdb\-server/connect\-active\-ovsdb\-server\fR command.
.SS "Public Key Infrastructure Options"
The options described below for configuring the SSL public key
infrastructure accept a special syntax for obtaining their
@@ -145,7 +179,7 @@ one row in \fItable\fR.)
\fBovs\-appctl\fR(8) can send commands to a running
\fBovsdb\-server\fR process. The currently supported commands are
described below.
-.SS "OVSDB\-SERVER COMMANDS"
+.SS "\fBovsdb\-server\fR Commands"
These commands are specific to \fBovsdb\-server\fR.
.IP "\fBexit\fR"
Causes \fBovsdb\-server\fR to gracefully terminate.
@@ -210,23 +244,37 @@ again (with \fBovsdb\-server/add\-db\fR).
Outputs a list of the currently configured databases added either through
the command line or through the \fBovsdb\-server/add\-db\fR command.
.
+.SS "Active-Backup Commands"
+.PP
+These commands query and update the role of \fBovsdb\-server\fR within
+an active-backup pair of servers. See \fBActive-Backup Options\fR,
+above, and \fBActive-Backup Database Service Model\fR in
+\fBovsdb\fR(7) for more information.
+.
.IP "\fBovsdb\-server/set\-active\-ovsdb\-server \fIserver"
Sets the active \fIserver\fR from which \fBovsdb\-server\fR connects through
\fBovsdb\-server/connect\-active\-ovsdb\-server\fR.
+This overrides the \fB\-\-sync\-from\fR command-line option.
.
.IP "\fBovsdb\-server/get\-active\-ovsdb\-server"
Gets the active server from which \fBovsdb\-server\fR is currently synchronizing
its databases.
.
.IP "\fBovsdb\-server/connect\-active\-ovsdb\-server"
-Causes \fBovsdb\-server\fR to synchronize its databases with the server
-specified by \fBovsdb\-server/set\-active\-ovsdb\-server\fR.
+Switches the server to a backup role. The server starts synchronizing
+its databases with the active server specified by
+\fBovsdb\-server/set\-active\-ovsdb\-server\fR (or the
+\fB\-\-sync\-from\fR command-line option) and closes all existing
+client connections, which requires clients to reconnect.
.
.IP "\fBovsdb\-server/disconnect\-active\-ovsdb\-server"
-Causes \fBovsdb\-server\fR to stop synchronizing its databases with a active server.
+Switches the server to an active role. The server stops synchronizing
+its databases with an active server and closes all existing client
+connections, which requires clients to reconnect.
.
.IP "\fBovsdb\-server/set\-sync\-exclude\-tables \fIdb\fB:\fItable\fR[\fB,\fIdb\fB:\fItable\fR]..."
-Sets the \fItable\fR whitin \fIdb\fR that will be excluded from synchronization.
+Sets the \fItable\fR within \fIdb\fR that will be excluded from synchronization.
+This overrides the \fB\-\-sync\-exclude-tables\fR command-line option.
.
.IP "\fBovsdb\-server/get\-sync\-exclude\-tables"
Gets the tables that are currently excluded from synchronization.
@@ -241,6 +289,64 @@ When the connection is in \fIreplicating\fR state, further output shows
the list of databases currently replicating, and the tables that are
excluded.
.
+.SS "Cluster Commands"
+These commands support the \fBovsdb\-server\fR clustered service model.
+They apply only to databases in the format used for clustered databases,
+which is the database format created by \fBovsdb\-tool create\-cluster\fR
+and \fBovsdb\-tool join\-cluster\fR.
+.
+.IP "\fBcluster/cid \fIdb\fR"
+Prints the cluster ID for \fIdb\fR, which is a UUID that identifies
+the cluster. If \fIdb\fR is a database newly created by
+\fBovsdb\-tool cluster\-join\fR, that has not yet successfully joined
+its cluster, and \fB\-\-cid\fR was not specified on the
+\fBcluster\-join\fR command line, then this command will report an
+error because the cluster ID is not yet known.
+.
+.IP "\fBcluster/sid \fIdb\fR"
+Prints the server ID for \fIdb\fR, which is a UUID that identifies
+this server within the cluster.
+.
+.IP "\fBcluster/status \fIdb\fR"
+Prints this server's status within the cluster and the status of its
+connections to other servers in the cluster.
+.
+.IP "\fBcluster/leave \fR[\fB\-\-force\fR] \fIdb\fR"
+Causes this server to remove itself from the cluster that contains
+\fIdb\fR.
+.IP
+Without \fB\-\-force\fR, this command implements a graceful removal
+that succeeds only if the cluster contains at least two servers and it
+is healthy, that is, over half its servers are up. This command waits
+for leaving the cluster to succeed or fail. If it is successful, the
+response is empty; if it fails, it outputs an error message. Given
+server failures, leaving a cluster takes an unbounded amount of time,
+so it is a good idea to use \fBovs\-appctl\fR's \fB\-\-timeout\fR
+option to limit its runtime. When a timeout occurs, leaving the
+cluster may ultimately succeed.
+.IP
+With \fB\-\-force\fR, this command forces the server to leave its
+cluster and form a new single-node cluster that contains only itself.
+The data in the new cluster may be inconsistent with the former
+cluster: transactions not yet replicated to the server will be lost,
+and transactions not yet applied to the cluster may be committed.
+Afterward, any servers in its former cluster will regard the server to
+have failed.
+.IP
+When the server successfully leaves the cluster, it stops serving
+\fIdb\fR, as if \fBovsdb\-server/remove\-db \fIdb\fR had been
+executed.
+.
+.IP "\fBcluster/kick \fIdb server\fR"
+Gracefully removes \fIserver\fR from \fIdb\fR's cluster, like
+\fBcluster/leave\fR (without \fB\-\-force\fR) except that it can
+remove any server, not just this one.
+.IP
+\fIserver\fR may be a server ID, as printed by \fBcluster/sid\fR, or
+the server's local network address as passed to \fBovsdb-tool\fR's
+\fBcreate\-cluster\fR or \fBjoin\-cluster\fR command. Use
+\fBcluster/status\fR to see a list of cluster members.
+.
.so lib/vlog-unixctl.man
.so lib/memory-unixctl.man
.so lib/coverage-unixctl.man
@@ -650,5 +756,5 @@ treat a \fBmonitor\fR response with a \fBresult\fR that contains an
being monitored does not contain a table named \fBerror\fR).
.
.SH "SEE ALSO"
-.
-.BR ovsdb\-tool (1).
+\fBovsdb\fR(7),
+\fBovsdb\-tool\fR(1).
@@ -12,10 +12,11 @@
ovsdb\-tool \- Open vSwitch database management utility
.
.SH SYNOPSIS
+.IP "Database Creation Commands:"
\fBovsdb\-tool \fR[\fIoptions\fR] \fBcreate \fR[\fIdb\fR [\fIschema\fR]]
.br
-\fBovsdb\-tool \fR[\fIoptions\fR] \fBcompact \fR[\fIdb\fR [\fItarget\fR]]
-.br
+\fBovsdb\-tool \fR[\fIoptions\fR] \fBcreate\-cluster \fIdb schema address\fR
+.IP "Version Management Commands:"
\fBovsdb\-tool \fR[\fIoptions\fR] \fBconvert \fR[\fIdb\fR [\fIschema
\fR[\fItarget\fR]]]
.br
@@ -28,6 +29,8 @@ ovsdb\-tool \- Open vSwitch database management utility
\fBovsdb\-tool \fR[\fIoptions\fR] \fBdb\-cksum \fR[\fIdb\fR]
.br
\fBovsdb\-tool \fR[\fIoptions\fR] \fBschema\-cksum \fR[\fIschema\fR]
+.IP "Other commands:"
+\fBovsdb\-tool \fR[\fIoptions\fR] \fBcompact \fR[\fIdb\fR [\fItarget\fR]]
.br
\fBovsdb\-tool \fR[\fIoptions\fR] \fBquery \fR[\fIdb\fR] \fItransaction\fR
.br
@@ -44,43 +47,85 @@ The \fBovsdb\-tool\fR program is a command-line tool for managing Open
vSwitch database (OVSDB) files. It does not interact directly with
running Open vSwitch database servers (instead, use
\fBovsdb\-client\fR).
+For an introduction to OVSDB and its implementation in Open vSwitch,
+see \fBovsdb\fR(7).
+.PP
+This OVSDB implementation supports standalone and active-backup
+database service models with one on-disk format and a clustered
+database service model with a different format. \fBovsdb\-tool\fR
+supports both formats, but some commands are appropriate for only one
+format, as documented for individual commands below. For more
+information on OVSDB service models, see the \fBService Models\fR
+section in \fBovsdb\fR(7).
.
-.SS "Basic Commands"
-.IP "\fBcreate\fI db schema\fR"
-Reads an OVSDB schema from the file named \fIschema\fR and creates a
-new OVSDB database file named \fIdb\fR using that schema. The new
-database is initially empty. This command will not overwrite an
-existing \fIdb\fR.
-.IP
-\fIschema\fR must contain an OVSDB schema in JSON format. Refer to
-the OVSDB specification for details.
+.SS "Database Creation Commands"
+These commands read an OVSDB schema in JSON format, as specified in
+the OVSDB specification, from a schema file and create a new OVSDB
+database file using that schema. The new database is initially empty.
+.PP
+These commands will not overwrite an existing database file. To
+replace an existing database with a new one, first delete the old one.
.
-.IP "\fBcompact\fI db \fR[\fItarget\fR]"
-Reads \fIdb\fR and writes a compacted version. If \fItarget\fR is
-specified, the compacted version is written as a new file named
-\fItarget\fR, which must not already exist. If \fItarget\fR is
-omitted, then the compacted version of the database replaces \fIdb\fR
-in-place.
+.IP "\fBcreate\fI db schema\fR"
+Use this command to create the database for controlling
+\fBovs\-vswitchd\fR or another standalone or active-backup database.
+It creates database file \fIdb\fR with the given \fIschema\fR.
.
-.SS "Version Management Commands"
-.PP
-An OVSDB schema has a schema version number, and an OVSDB database
-embeds a particular version of an OVSDB schema. These version numbers
-take the form \fIx\fB.\fIy\fB.\fIz\fR, e.g. \fB1.2.3\fR. The OVSDB
-implementation does not enforce a particular version numbering scheme,
-but schemas managed within the Open vSwitch project use the following
-approach. Whenever the database schema is changed in a non-backward
-compatible way (e.g. deleting a column or a table), \fIx\fR is
-incremented (and \fIy\fR and \fIz\fR are reset to 0). When the
-database schema is changed in a backward compatible way (e.g. adding a
-new column), \fIy\fR is incremented (and \fIz\fR is reset to 0). When
-the database schema is changed cosmetically (e.g. reindenting its
-syntax), \fIz\fR is incremented.
+.IP "\fBcreate\-cluster\fI db schema local"
+Use this command to initialize the first server in a high-availability
+cluster of 3 (or more) database servers, e.g. for an OVN northbound or
+southbound database in an environment that cannot tolerate a single
+point of failure. It creates clustered database file \fIdb\fR with
+the given \fIschema\fR and configures the server to listen on
+\fIlocal\fR, which must take the form
+\fIprotocol\fB:\fIip\fB:\fIport\fR, where \fIprotocol\fR is \fBtcp\fR
+or \fBssl\fR, \fIip\fR is the server's IP (either an IPv4 address or
+an IPv6 address enclosed in square brackets), and \fIport\fR is a TCP
+port number.
+Only one address is specified, for the first server in the cluster,
+ordinarily the one for the server running \fBcreate\-cluster\fR.
+The address is used for communication within the cluster, not for
+communicating with OVSDB clients, and must not use the same port used
+for the OVSDB protocol.
.
-.PP
-Some OVSDB databases and schemas, especially very old ones, do not
-have a version number.
+.IP "[\fB\-\-cid=\fIuuid\fR] \fBjoin\-cluster\fI db schema local remote\fR..."
+Use this command to initialize each server after the first one in an
+OVSDB high-availability cluster. It creates clustered database file
+\fIdb\fR, obtaining the database name from \fIschema\fR, and
+configures the server to listen on \fIlocal\fR and to initially
+connect to \fIremote\fR, which must be a server that already belongs
+to the cluster. \fIlocal\fR and \fIremote\fR use the same
+\fIprotocol\fB:\fIip\fB:\fIport\fR syntax as \fBcreate\-cluster\fR.
+.IP
+This command reads \fIschema\fR only to obtain the name of the
+database. The initial schema for the database is actually the one
+passed to \fBcreate\-cluster\fR, so there is no risk of version
+mismatch.
+.IP
+This command does not do any network access, which means that it
+cannot actually join the new server to the cluster. Instead, the
+\fIdb\fR file that it creates prepares the server to join the cluster
+the first time that \fBovsdb\-server\fR serves it. As part of joining
+the cluster, the new server retrieves the database schema and obtains
+the list of all cluster members. Only after that does it become a
+full member of the cluster.
+.IP
+Optionally, more than one \fIremote\fR may be specified; for example,
+in a cluster that already contains multiple servers, one could specify
+all the existing servers. This is beneficial if some of the existing
+servers are down while the new server joins, but it is not otherwise
+needed.
+.IP
+By default, the \fIdb\fR created by \fBjoin\-cluster\fR will join any
+clustered database with the name from \fIschema\fR that is available
+at a \fIremote\fR. In theory, if machines go up and down and IP
+addresses change in the right way, it could join the wrong database
+cluster. To avoid this possibility, specify \fB\-\-cid=\fIuuid\fR,
+where \fIuuid\fR is the cluster ID of the cluster to join, as printed
+by \fBovsdb\-tool get\-cid\fR.
.
+.SS "Version Management Commands"
+.so ovsdb/ovsdb-schemas.man
.PP
These commands work with different versions of OVSDB schemas and
databases.
@@ -91,7 +136,10 @@ Reads \fIdb\fR, translating it into to the schema specified in
is specified, the translated version is written as a new file named
\fItarget\fR, which must not already exist. If \fItarget\fR is
omitted, then the translated version of the database replaces \fIdb\fR
-in-place.
+in-place. In-place conversion cannot take place if the database is
+currently being served by \fBovsdb\-server\fR (instead, either stop
+\fBovsdb\-server\fR first or use \fBovsdb\-client\fR's \fBconvert\fR
+command).
.IP
This command can do simple ``upgrades'' and ``downgrades'' on a
database's schema. The data in \fIdb\fR must be valid when
@@ -100,22 +148,25 @@ interpreted under \fIschema\fR, with only one exception: data in
ignored. Columns that exist in \fIschema\fR but not in \fIdb\fR are
set to their default values. All of \fIschema\fR's constraints apply
in full.
+.IP
+Some uses of this command can cause unrecoverable data loss. For
+example, converting a database from a schema that has a given column
+or table to one that does not will delete all data in that column or
+table. Back up critical databases before converting them.
+.IP
+This command is for standalone and active-backup databases only. For
+clustered databases, use \fBovsdb\-client\fR's \fBconvert\fR command
+to convert them online.
.
.IP "\fBneeds\-conversion\fI db schema\fR"
-Reads the schema embedded in \fIdb\fR and the standalone schema in
+Reads the schema embedded in \fIdb\fR and the JSON schema from
\fIschema\fR and compares them. If the schemas are the same, prints
-\fBno\fR on stdout; if they differ, print \fByes\fR.
+\fBno\fR on stdout; if they differ, prints \fByes\fR.
.
.IP "\fBdb\-version\fI db\fR"
.IQ "\fBschema\-version\fI schema\fR"
Prints the version number in the schema embedded within the database
-\fIdb\fR or in the standalone schema \fIschema\fR on stdout. A schema
-version number has the form \fIx\fB.\fIy\fB.\fIz\fR. See
-\fBovs\-vswitchd.conf.db\fR(5) for details.
-.IP
-Schema version numbers and Open vSwitch version numbers are
-independent.
-.IP
+\fIdb\fR or in the JSON schema \fIschema\fR on stdout.
If \fIschema\fR or \fIdb\fR was created before schema versioning was
introduced, then it will not have a version number and this command
will print a blank line.
@@ -123,25 +174,44 @@ will print a blank line.
.IP "\fBdb\-cksum\fI db\fR"
.IQ "\fBschema\-cksum\fI schema\fR"
Prints the checksum in the schema embedded within the database
-\fIdb\fR or of the standalone schema \fIschema\fR on stdout.
-.IP
+\fIdb\fR or of the JSON schema \fIschema\fR on stdout.
If \fIschema\fR or \fIdb\fR was created before schema checksums were
introduced, then it will not have a checksum and this command
will print a blank line.
.
.SS "Other Commands"
.
+.IP "\fBcompact\fI db \fR[\fItarget\fR]"
+Reads \fIdb\fR and writes a compacted version. If \fItarget\fR is
+specified, the compacted version is written as a new file named
+\fItarget\fR, which must not already exist. If \fItarget\fR is
+omitted, then the compacted version of the database replaces \fIdb\fR
+in-place. This command is not needed in normal operation because
+\fBovsdb\-server\fR from time to time automatically compacts a
+database that grows much larger than its minimum size.
+.IP
+This command does not work if \fIdb\fR is currently being served by
+\fBovsdb\-server\fR, or if it is otherwise locked for writing by
+another process. This command also does not work with clustered
+databases. Instead, in either case, send the
+\fBovsdb\-server/compact\fR command to \fBovsdb\-server\fR, via
+\fBovs\-appctl\fR).
+.
.IP "\fBquery\fI db transaction\fR"
Opens \fIdb\fR, executes \fItransaction\fR on it, and prints the
results. The \fItransaction\fR must be a JSON array in the format of
the \fBparams\fR array for the JSON-RPC \fBtransact\fR method, as
described in the OVSDB specification.
.IP
-The \fIdb\fR is opened for read-only access, so this command may
+This command opens \fIdb\fR for read-only access, so it may
safely run concurrently with other database activity, including
\fBovsdb\-server\fR and other database writers. The \fItransaction\fR
may specify database modifications, but these will have no effect on
\fIdb\fR.
+.IP
+This command does not work with clustered databases. Instead, use
+\fBovsdb-client\fR's \fBquery\fR command to send the query to
+\fBovsdb\-server\fR.
.
.IP "\fBtransact\fI db transaction\fR"
Opens \fIdb\fR, executes \fItransaction\fR on it, prints the results,
@@ -149,11 +219,11 @@ and commits any changes to \fIdb\fR. The \fItransaction\fR must be a
JSON array in the format of the \fBparams\fR array for the JSON-RPC
\fBtransact\fR method, as described in the OVSDB specification.
.IP
-The \fIdb\fR is opened and locked for read/write access, so this
-command will fail if the database is opened for writing by any other
-process, including \fBovsdb\-server\fR(1). Use \fBovsdb\-client\fR(1),
-instead, to write to a database that is served by
-\fBovsdb\-server\fR(1).
+This command does not work if \fIdb\fR is currently being served by
+\fBovsdb\-server\fR, or if it is otherwise locked for writing by
+another process. This command also does not work with clustered
+databases. Instead, in either case, use \fBovsdb\-client\fR's
+\fBtransact\fR command to send the query to \fBovsdb\-server\fR.
.
.IP "\fBshow\-log\fI db\fR"
Prints a summary of the records in \fIdb\fR's log, including the time
@@ -167,6 +237,14 @@ modified by each transaction. With two \fB\-m\fRs, \fBshow\-log\fR
also prints the values of the columns modified by each change to a
record.
.
+.IP "\fBdb\-name\fI db\fR"
+.IQ "\fBschema\-name\fI schema\fR"
+Prints the name of the schema embedded within the database \fIdb\fR or
+in the JSON schema \fIschema\fR on stdout.
+.
+.IP "\fBdb\-cid\fI db\fR"
+Prints the cluster ID for the clustered database \fIdb\fR.
+.
.SH OPTIONS
.SS "Logging Options"
.so lib/vlog.man
@@ -178,6 +256,6 @@ default \fIschema\fR is \fB@pkgdatadir@/vswitch.ovsschema\fR. The
\fBhelp\fR command also displays these defaults.
.SH "SEE ALSO"
.
+\fBovsdb\fR(7),
\fBovsdb\-server\fR(1),
-\fBovsdb\-client\fR(1),
-and the OVSDB specification.
+\fBovsdb\-client\fR(1).
new file mode 100644
@@ -0,0 +1,725 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manpage program="ovsdb" section="7" title="OVSDB">
+ <h1>Name</h1>
+ <p>ovsdb -- Open vSwitch Database</p>
+
+ <h1>Description</h1>
+ <p>
+ OVSDB, the Open vSwitch Database, is a network 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.
+ </p>
+
+ <p>
+ 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.
+ </p>
+
+ <p>
+ 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
+ <code>ovs-vswitchd</code>(8), the Open vSwitch switch daemon, using the
+ schema documented in <code>ovs-vswitchd.conf.db</code>(5). The Open
+ Virtual Network (OVN) sub-project of OVS uses two OVSDB schemas, documented
+ in <code>ovn-nb</code>(5) and <code>ovn-sb</code>(5). Finally, Open
+ vSwitch includes the ``VTEP'' schema, documented in <code>vtep</code>(5)
+ that many third-party hardware switches support for configuring VXLAN,
+ although OVS itself does not directly use this schema.
+ </p>
+
+ <p>
+ The OVSDB protocol specification allows independent, interoperable
+ implementations of OVSDB to be developed. Open vSwitch includes a OVSDB
+ server implementation named <code>ovsdb-server</code>(1), which supports
+ several protocol extensions documented in its manpage, and a basic
+ command-line OVSDB client named <code>ovsdb-client</code>(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.
+ </p>
+
+ <p>
+ In addition to these generic OVSDB server and client tools, Open vSwitch
+ includes tools for working with databases that have specific schemas:
+ <code>ovs-vsctl</code> works with the <code>ovs-vswitchd</code>
+ configuration database, <code>vtep-ctl</code> works with the VTEP database,
+ <code>ovn-nbctl</code> works with the OVN Northbound database, and so on.
+ </p>
+
+ <p>
+ RFC 7047 specifies the OVSDB protocol but it does not specify an on-disk
+ storage format. Open vSwitch includes <code>ovsdb-tool</code>(1) for
+ working with its own on-disk database format. The most notable feature of
+ this format is that <code>ovsdb-tool</code>(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.
+ </p>
+
+ <h1>Schemas</h1>
+
+ <p>
+ Schemas in OVSDB have a JSON format that is specified in RFC 7047. They
+ are often stored in files with an extension <code>.ovsschema</code>. An
+ on-disk database in OVSDB includes a schema and data, embedding both into a
+ single file. The Open vSwitch utility <code>ovsdb-tool</code> has commands
+ that work with schema files and with the schemas embedded in database
+ files.
+ </p>
+
+ <p>
+ 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 <code>Open_vSwitch</code>. Schema names begin with a
+ letter or an underscore, followed by any number of letters, underscores, or
+ digits. The <code>ovsdb-tool</code> commands <code>schema-name</code> and
+ <code>db-name</code> extract the schema name from a schema or database
+ file, respectively.
+ </p>
+
+ <p>
+ An OVSDB schema also has a version of the form
+ <code><var>x</var>.<var>y</var>.<var>z</var></code>,
+ e.g. <code>1.2.3</code>. 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 a column or a table), we increment
+ <var>x</var> and set <var>y</var> and <var>z</var> to 0. When we change
+ the database schema in a backward compatible way (e.g. when we add a new
+ column), we increment <var>y</var> and set <var>z</var> to 0. When we
+ change the database schema cosmetically (e.g. we reindent its syntax), we
+ increment <var>z</var>. The <code>ovsdb-tool</code> commands
+ <code>schema-version</code> and <code>db-version</code> extract the schema
+ version from a schema or database file, respectively.
+ </p>
+
+ <p>
+ Very old OVSDB schemas do not have a version, but RFC 7047 mandates it.
+ </p>
+
+ <p>
+ 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 <code>ovsdb-tool</code>
+ commands <code>schema-cksum</code> and <code>db-cksum</code> extract the
+ schema checksum from a schema or database file, respectively.
+ </p>
+
+ <h1>Service Models</h1>
+
+ <p>
+ OVSDB supports three service models for databases: <dfn>standalone</dfn>,
+ <dfn>active-backup</dfn>, and <dfn>clustered</dfn>. 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.
+ </p>
+
+ <p>
+ RFC 7047, which specifies the OVSDB protocol, does not mandate or specify
+ any particular service model.
+ </p>
+
+ <p>
+ The following sections describe the individual service models.
+ </p>
+
+ <h3>Standalone Database Service Model</h3>
+
+ <p>
+ A <dfn>standalone</dfn> 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, <code>ovs-vswitchd</code>, is a
+ standalone database because a server failure would take out both the
+ database and the virtual switch.
+ </p>
+
+ <p>
+ To set up a standalone database, use <code>ovsdb-tool create</code> to
+ create a database file, then run <code>ovsdb-server</code> to start the
+ database service.
+ </p>
+
+ <h3>Active-Backup Database Service Model</h3>
+
+ <p>
+ An <dfn>active-backup</dfn> database runs two servers (on different hosts).
+ At any given time, one of the servers is designated with the
+ <dfn>active</dfn> role and the other the <dfn>backup</dfn> 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.
+ </p>
+
+ <p>
+ 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 <code>ovsdb-tool create</code>
+ will work, as will copying the database file from the active server. Then
+ use <code>ovsdb-server --sync-from=<var>active</var></code> to start the
+ backup server, where <var>active</var> is an OVSDB connection method (see
+ <ref section="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.
+ </p>
+
+ <p>
+ When the active server in an active-backup server pair fails, an
+ administrator can switch the backup server to an active role with the
+ <code>ovs-appctl</code> command
+ <code>ovsdb-server/disconnect-active-ovsdb-server</code>. Clients then
+ have read/write access to the now-active server. 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 <cite>Integration Guide for
+ Centralized Control</cite> in the Open vSwitch documentation describes how
+ to use Pacemaker for this purpose in OVN.
+ </p>
+
+ <p>
+ 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 done, 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.
+ </p>
+
+ <p>
+ 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.
+ </p>
+
+ <p>
+ Open vSwitch 2.6 introduced support for the active-backup service model.
+ </p>
+
+ <h3>Clustered Database Service Model</h3>
+
+ <p>
+ A <dfn>clustered</dfn> database runs across 3 or 5 database servers (the
+ <dfn>cluster</dfn>) 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.
+ </p>
+
+ <p>
+ Clusters larger than 5 servers will also work, with every 2 added
+ servers allowing the cluster to tolerate 1 more failure, but
+ performance decreases, especially write performance. 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.
+ </p>
+
+ <p>
+ To set up a clustered database, first initialize it on a single node by
+ running <code>ovsdb-tool create-cluster</code> and starting
+ <code>ovsdb-server</code>. To add a server to a cluster, run
+ <code>ovsdb-tool join-cluster</code> on the new server and start
+ <code>ovsdb-server</code>. To remove a running server from a cluster, use
+ <code>ovs-appctl</code> to invoke the <code>cluster/leave</code> 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
+ <code>ovs-appctl</code> to invoke <code>cluster-kick</code> to make the
+ remaining servers kick it out of the cluster.
+ </p>
+
+ <p>
+ 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 cannot be done, though, use
+ <code>ovs-appctl</code> to invoke <code>cluster/leave --force</code> on a
+ running server. This command forces the server to which it is directed to
+ leave its cluster and form a new single-node cluster that contains only
+ itself. The data in the new cluster may be inconsistent with the former
+ cluster: transactions not yet replicated to the server will be lost, and
+ transactions not yet applied to the cluster may be committed. Afterward,
+ any servers in its former cluster will regard the server to have failed.
+ </p>
+
+ <p>
+ 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
+ <code>ovsdb-tool</code> 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.
+ </p>
+
+ <p>
+ To upgrade the <code>ovsdb-server</code> 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 <ref
+ section="Upgrading or Downgrading a Database"/>.)
+ </p>
+
+ <p>
+ Open vSwitch 2.8 introduced support for the clustered service model.
+ </p>
+
+ <h2>Database Replication</h2>
+
+ <p>
+ OVSDB can layer <dfn>replication</dfn> 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 <code>replica</code>).
+ 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.
+ </p>
+
+ <p>
+ 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.
+ </p>
+
+ <p>
+ Open vSwitch 2.6 introduced support for database replication.
+ </p>
+
+ <h1>Connection Methods</h1>
+
+ <p>
+ An OVSDB <dfn>connection method</dfn> 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. <code>ovsdb-server</code> uses connection methods
+ to specify how it should listen for connections from clients and
+ <code>ovsdb-client</code> uses them to specify how it should connect to a
+ server. Connections in the opposite direction, where
+ <code>ovsdb-server</code> connects to a client that is configured to listen
+ for an incoming connection, are also possible.
+ </p>
+
+ <p>
+ Connection methods are classified as <dfn>active</dfn> or
+ <dfn>passive</dfn>. An active connection method makes an outgoing
+ connection to a remote host; a passive connection method listens for
+ connection from remote hosts. The most common arrangement is to configure
+ an 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.
+ </p>
+
+ <p>
+ OVSDB supports the following active connection methods:
+ </p>
+
+ <dl>
+ <dt><code>ssl:<var>ip</var>:<var>port</var></code></dt>
+ <dd>
+ <p>
+ The specified SSL or TLS <var>port</var> on the host at the given
+ <var>ip</var>.
+ </p>
+ </dd>
+
+ <dt><code>tcp:<var>ip</var>:<var>port</var></code></dt>
+ <dd>
+ <p>
+ The specified TCP <var>port</var> on the host at the given
+ <var>ip</var>.
+ </p>
+ </dd>
+
+ <dt><code>unix:<var>file</var></code></dt>
+ <dd>
+ <p>
+ On Unix-like systems, connect to the Unix domain server socket named
+ <var>file</var>.
+ </p>
+
+ <p>
+ On Windows, connect to a local named pipe that is represented by a file
+ created in the path <var>file</var> to mimic the behavior of a Unix
+ domain socket.
+ </p>
+ </dd>
+
+ <dt><var>method1</var><code>, </code><var>method2</var><code>, </code>...<code>, </code><var>methodN</var></dt>
+ <dd>
+ <p>
+ 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).
+ </p>
+
+ <p>
+ 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 <code>cid:<var>uuid</var></code> in the
+ list of connection methods, where <var>uuid</var> is the cluster ID of
+ the desired database cluster, as printed by <code>ovsdb-tool
+ get-cid</code>. This feature is optional.
+ </p>
+ </dd>
+ </dl>
+
+ <p>
+ OVSDB supports the following passive connection methods:
+ </p>
+
+ <dl>
+ <dt><code>pssl:<var>port</var></code></dt>
+ <dt><code>pssl:<var>port</var>:<var>ip</var></code></dt>
+ <dd>
+ Listen on the given TCP <var>port</var> for SSL or TLS connections. By
+ default, connections are not bound to a particular local IP address and
+ connections from IPv6 addresses are not accepted. Specifying
+ <var>ip</var> limits connections to those from the given IP.
+ </dd>
+
+ <dt><code>ptcp:<var>port</var></code></dt>
+ <dt><code>ptcp:<var>port</var>:<var>ip</var></code></dt>
+ <dd>
+ Listen on the given TCP <var>port</var>. By
+ default, connections are not bound to a particular local IP address and
+ connections from IPv6 addresses are not accepted. Specifying
+ <var>ip</var> limits connections to those from the given IP.
+ </dd>
+
+ <dt><code>punix:<var>file</var></code></dt>
+ <dd>
+ <p>
+ On Unix-like systems, listens for connections on the Unix domain socket
+ named <var>file</var>.
+ </p>
+
+ <p>
+ On Windows, listens on a local named pipe, creating a named pipe
+ <var>file</var> to mimic the behavior of a Unix domain socket.
+ </p>
+ </dd>
+ </dl>
+
+ <p>
+ All IP-based connection methods accept IPv4 and IPv6 addresses. DNS names
+ are not accepted. To specify an IPv6 address, wrap it in square brackets,
+ e.g. <code>ssl:[::1]:6640</code>.
+ </p>
+
+ <p>
+ The <var>port</var> may be omitted from connection methods that use a port
+ number. The default <var>port</var> for TCP-based connection methods is
+ 6640, e.g. <code>pssl:</code> is equivalent to <code>pssl:6640</code>. 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.
+ </p>
+
+ <p>
+ The <code>ssl</code> and <code>pssl</code> connection methods requires
+ additional configuration through <code>--private-key</code>,
+ <code>--certificate</code>, and <code>--ca-cert</code> command line
+ options. Open vSwitch can be built without SSL support, in which case
+ these connection methods are not supported.
+ </p>
+
+ <h1>Database Life Cycle</h1>
+
+ <p>
+ This section describes how to handle various events in the life cycle of
+ a database using the Open vSwitch implementation of OVSDB.
+ </p>
+
+ <h2>Creating a Database</h2>
+
+ <p>
+ Creating and starting up the service for a new database was covered
+ separately for each database service model in the <ref section="Service
+ Models"/> section, above.
+ </p>
+
+ <h2>Backing Up and Restoring a Database</h2>
+
+ <p>
+ OVSDB is often used in contexts where the database contents are not
+ particularly valuable. For example, in many systems, the database for
+ configuring <code>ovs-vswitchd</code> is essentially rebuilt from scratch
+ at boot time. It is not worthwhile to back up these databases.
+ </p>
+
+ <p>
+ When OVSDB is used for valuable data, a backup strategy is worth
+ considering. One way is to use database replication, discussed above in
+ <ref section="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.
+ </p>
+
+ <p>
+ 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 <code>cp</code>, 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 (short of taking a snapshot of all
+ the servers' database files at the same time).
+ </p>
+
+ <p>
+ Another way to make a backup, which works with all OVSDB service models, is
+ to use <code>ovsdb-client backup</code>, 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.
+ </p>
+
+ <p>
+ 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 <code>cp</code>), and then restart
+ the servers. Another way, which works with any service model, is to use
+ <code>ovsdb-client restore</code>, which connects to a running database
+ server and replaces the data in one of its databases by a provided
+ snapshot. Using <code>ovsdb-client restore</code> has the disadvantage
+ that UUIDs of rows in the restored database will differ from those in the
+ snapshot the OVSDB protocol does not allow clients to specify row UUIDs.
+ </p>
+
+ <p>
+ None of these approaches save and restore 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.
+ </p>
+
+ <p>
+ 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.
+ </p>
+
+ <h2>Upgrading or Downgrading a Database</h2>
+
+ <p>
+ 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.
+ </p>
+
+ <p>
+ 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.
+ </p>
+
+ <p>
+ Converting a database can lose data, so it is wise to make a backup
+ beforehand.
+ </p>
+
+ <p>
+ 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
+ <code>ovsdb-tool convert</code> to convert it to the new schema, and then
+ restart the database server.
+ </p>
+
+ <p>
+ OVSDB also supports online database schema conversion, for any of its
+ database service models. To convert a database online, use
+ <code>ovsdb-client convert</code>. The conversion is atomic, consistent,
+ isolated, and durable. The OVSDB protocol does not provide a way for the
+ server to notify a client that a database's schema has changed, so
+ currently <code>ovsdb-server</code> disconnects any clients connected when
+ the conversion takes place. Upon reconnction, clients will discover that
+ the schema has changed.
+ </p>
+
+ <p>
+ Schema versions and checksums (see <ref section="Schemas"/>, above) can
+ give hints about whether a database needs to be converted to a new schema.
+ If there is any question, though, the <code>needs-conversion</code> command
+ on <code>ovsdb-tool</code> and <code>ovsdb-client</code> can provide a
+ definitive answer.
+ </p>
+
+ <h2>Working with Database History</h2>
+
+ <p>
+ 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.
+ </p>
+
+ <h3>Compacting Databases</h3>
+
+ <p>
+ If OVSDB database files were truly append-only, then over time they would
+ grow without bound. To avoid this problem, OVSDB can <dfn>compact</dfn> 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, <code>ovsdb-server</code> automatically
+ compacts a database that grows much larger than its minimum size.
+ </p>
+
+ <p>
+ Because <code>ovsdb-server</code> automatically compacts databases, it is
+ usually not necessary to compact them manually, but OVSDB still offers a
+ few ways to do it. First, <code>ovsdb-tool compact</code> can compact a
+ standalone or active-backup database that is not currently being served by
+ <code>ovsdb-server</code> (or otherwise locked for writing by another
+ process). To compact any database that is currently being served by
+ <code>ovsdb-server</code>, use <code>ovs-appctl</code> to send the
+ <code>ovsdb-server/compact</code> 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.
+ </p>
+
+ <h3>Viewing History</h3>
+
+ <p>
+ The <code>ovsdb-tool</code> utility's <code>show-log</code> 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 <code>-m</code> 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, <code>ovs-vsctl</code> adds its command line to the transactions
+ that it makes.
+ </p>
+
+ <p>
+ The <code>show-log</code> 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.
+ </p>
+
+ <h3>Truncating History</h3>
+
+ <p>
+ 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 <var>i</var> of the first record
+ to delete in <code>ovsdb-tool show-log</code> output. Each record is two
+ lines of plain text, so trimming the log is as simple as running <code>head
+ -n <var>j</var></code>, where <var>j</var> = 2<var>i</var>.
+ </p>
+
+ <h2>Corruption</h2>
+
+ <p>
+ When <code>ovsdb-server</code> 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.
+ </p>
+
+ <p>
+ 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.
+ </p>
+
+ <p>
+ The first record in a standalone or active-backup database file specifies
+ the schema. <code>ovsdb-server</code> will refuse to work with such a
+ database, 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.
+ </p>
+
+ <p>
+ When <code>ovsdb-server</code> adds records to a database file in which it
+ detected corruption, it first truncates the file just after the last good
+ record.
+ </p>
+
+ <h1>See Also</h1>
+
+ <p>RFC 7047, ``The Open vSwitch Database Management Protocol.''</p>
+
+ <p>
+ Open vSwitch implementations of generic OVSDB functionality:
+ <code>ovsdb-server</code>(1),
+ <code>ovsdb-client</code>(1),
+ <code>ovsdb-tool</code>(1).
+ </p>
+
+ <p>
+ Tools for working with databases that have specific OVSDB schemas:
+ <code>ovs-vsctl</code>(8),
+ <code>vtep-ctl</code>(8),
+ <code>ovn-nbctl</code>(8),
+ <code>ovn-sbctl</code>(8).
+ </p>
+
+ <p>
+ OVSDB schemas for Open vSwitch and related functionality:
+ <code>ovs-vswitchd.conf.db</code>(5),
+ <code>vtep</code>(5),
+ <code>ovn-nb</code>(5),
+ <code>ovn-sb</code>(5).
+ </p>
+</manpage>
deleted file mode 100644
@@ -1,19 +0,0 @@
-.IP "\fBssl:\fIip\fB:\fIport\fR"
-The specified SSL \fIport\fR on the host at the given \fIip\fR, which
-must be expressed as an IP address (not a DNS name) in IPv4 or IPv6 address
-format. If \fIip\fR is an IPv6 address, then wrap \fIip\fR with square
-brackets, e.g.: \fBssl:[::1]:6640\fR.
-The \fB\-\-private\-key\fR, \fB\-\-certificate\fR, and \fB\-\-ca\-cert\fR
-options are mandatory when this form is used.
-.
-.IP "\fBtcp:\fIip\fB:\fIport\fR"
-Connect to the given TCP \fIport\fR on \fIip\fR, where \fIip\fR can be IPv4
-or IPv6 address. If \fIip\fR is an IPv6 address, then wrap \fIip\fR with
-square brackets, e.g.: \fBtcp:[::1]:6640\fR.
-.
-.IP "\fBunix:\fIfile\fR"
-On POSIX, connect to the Unix domain server socket named \fIfile\fR.
-.IP
-On Windows, connect to a local named pipe that is represented by a file
-created in the path \fIfile\fR to mimic the behavior of a Unix domain
-socket.
deleted file mode 100644
@@ -1,26 +0,0 @@
-.IP "\fBpssl:\fIport\fR[\fB:\fIip\fR]"
-Listen on the given SSL \fIport\fR for a connection. By default,
-connections are not bound to a particular local IP address and
-it listens only on IPv4 (but not IPv6) addresses, but
-specifying \fIip\fR limits connections to those from the given
-\fIip\fR, either IPv4 or IPv6 address. If \fIip\fR is
-an IPv6 address, then wrap \fIip\fR with square brackets, e.g.:
-\fBpssl:6640:[::1]\fR. The \fB\-\-private\-key\fR,
-\fB\-\-certificate\fR, and \fB\-\-ca\-cert\fR options are mandatory
-when this form is used.
-.
-.IP "\fBptcp:\fIport\fR[\fB:\fIip\fR]"
-Listen on the given TCP \fIport\fR for a connection. By default,
-connections are not bound to a particular local IP address and
-it listens only on IPv4 (but not IPv6) addresses, but
-\fIip\fR may be specified to listen only for connections to the given
-\fIip\fR, either IPv4 or IPv6 address. If \fIip\fR is
-an IPv6 address, then wrap \fIip\fR with square brackets, e.g.:
-\fBptcp:6640:[::1]\fR.
-.
-.IP "\fBpunix:\fIfile\fR"
-On POSIX, listen on the Unix domain server socket named \fIfile\fR for a
-connection.
-.IP
-On Windows, listen on a local named pipe. A file is created in the
-path \fIfile\fR to mimic the behavior of a Unix domain socket.
@@ -1,23 +0,0 @@
-The following options allow \fBovsdb\-server\fR to synchronize its databases
-with another running \fBovsdb\-server\fR.
-.TP
-\fB\-\-sync\-from=\fIserver\fR
-Sets up \fBovsdb\-server\fR to synchronize its databases with the
-databases in \fIserver\fR, which must be an active connection method
-in one of the forms documented in \fBovsdb\-client\fR(1). Every
-transaction committed by \fIserver\fR will be replicated to
-\fBovsdb\-server\fR. This option makes \fBovsdb\-server\fR start
-as a backup server; add \fB\-\-active\fR to make it start as an
-active server.
-.TP
-\fB\-\-sync\-exclude-tables=\fIdb:table[,db:table]...\fR
-Causes the specified tables to be excluded from replication.
-.TP
-\fB\-\-active\fR
-By default, \fB\-\-sync\-from\fR makes \fBovsdb\-server\fR start up as
-a backup for \fIserver\fR. With \fB\-\-active\fR, however,
-\fBovsdb\-server\fR starts as an active server. Use this option to
-allow the syncing options to be specified using command line options,
-yet start the server, as the default, active server. To switch the
-running server to backup mode, use \fBovs-appctl(1)\fR to execute the
-\fBovsdb\-server/connect\-active\-ovsdb\-server\fR command.
@@ -80,23 +80,24 @@ def inline_xml_to_nroff(node, font, to_upper=False, newline='\n'):
s += inline_xml_to_nroff(child, r'\fB', to_upper, newline)
return s + font
elif node.tagName == 'ref':
- s = r'\fB'
if node.hasAttribute('column'):
- s += node.attributes['column'].nodeValue
+ s = node.attributes['column'].nodeValue
if node.hasAttribute('key'):
s += ':' + node.attributes['key'].nodeValue
elif node.hasAttribute('table'):
- s += node.attributes['table'].nodeValue
+ s = node.attributes['table'].nodeValue
elif node.hasAttribute('group'):
- s += node.attributes['group'].nodeValue
+ s = node.attributes['group'].nodeValue
elif node.hasAttribute('db'):
- s += node.attributes['db'].nodeValue
+ s = node.attributes['db'].nodeValue
elif node.hasAttribute('field'):
- s += node.attributes['field'].nodeValue
+ s = node.attributes['field'].nodeValue
+ elif node.hasAttribute('section'):
+ s = node.attributes['section'].nodeValue
else:
raise error.Error("'ref' lacks required attributes: %s"
% list(node.attributes.keys()))
- return s + font
+ return r'\fB' + re.sub(r'\s+', ' ', s) + font
elif node.tagName in ['var', 'dfn', 'i', 'cite']:
s = r'\fI'
for child in node.childNodes:
@@ -78,14 +78,9 @@ the global options by \fB\-\-\fR.
.
.IP "\fB\-\-db=\fIserver\fR"
Sets \fIserver\fR as the database server that \fBovs\-vsctl\fR
-contacts to query or modify configuration. The default is
-\fBunix:@RUNDIR@/db.sock\fR. \fIserver\fR must take one of the
-following forms:
-.RS
-.so ovsdb/remote-active.man
-.so ovsdb/remote-passive.man
-.RE
-.
+contacts to query or modify configuration. \fIserver\fR may be an
+OVSDB active or passive connection method, as described in
+\fBovsdb\fR(7). The default is \fBunix:@RUNDIR@/db.sock\fR.
.IP "\fB\-\-no\-wait\fR"
Prevents \fBovs\-vsctl\fR from waiting for \fBovs\-vswitchd\fR to
reconfigure itself according to the modified database. This
@@ -410,13 +405,9 @@ Prints the configured manager(s).
Deletes the configured manager(s).
.
.IP "\fBset\-manager\fR \fItarget\fR\&..."
-Sets the configured manager target or targets. Each \fItarget\fR may
-use any of the following forms:
-.
-.RS
-.so ovsdb/remote-active.man
-.so ovsdb/remote-passive.man
-.RE
+Sets the configured manager target or targets.
+Each \fItarget\fR may be an OVSDB active or passive connection method,
+e.g. \fBpssl:6640\fR, as described in \fBovsdb\fR(7).
.
.SS "SSL Configuration"
When \fBovs\-vswitchd\fR is configured to connect over SSL for management or
@@ -19,10 +19,9 @@ A daemon that manages and controls any number of Open vSwitch switches
on the local machine.
.PP
The \fIdatabase\fR argument specifies how \fBovs\-vswitchd\fR connects
-to \fBovsdb\-server\fR. The default is \fBunix:@RUNDIR@/db.sock\fR.
-The following forms are accepted:
-.so ovsdb/remote-active.man
-.so ovsdb/remote-passive.man
+to \fBovsdb\-server\fR. \fIdatabase\fR may be an OVSDB active or
+passive connection method, as described in \fBovsdb\fR(7). The
+default is \fBunix:@RUNDIR@/db.sock\fR.
.PP
\fBovs\-vswitchd\fR retrieves its configuration from \fIdatabase\fR at
startup. It sets up Open vSwitch datapaths and then operates
@@ -52,15 +52,10 @@ command line has options, then those options must be separated from
the global options by \fB\-\-\fR.
.
.IP "\fB\-\-db=\fIserver\fR"
-Sets \fIserver\fR as the database server that \fBvtep\-ctl\fR
-contacts to query or modify configuration. The default is
-\fBunix:@RUNDIR@/db.sock\fR. \fIserver\fR must take one of the
-following forms:
-.RS
-.so ovsdb/remote-active.man
-.so ovsdb/remote-passive.man
-.RE
-.
+Sets \fIserver\fR as the database server that \fBvtep\-ctl\fR contacts
+to query or modify configuration. \fIserver\fR may be an OVSDB active
+or passive connection method, as described in \fBovsdb\fR(7). The
+default is \fBunix:@RUNDIR@/db.sock\fR.
.IP "\fB\-\-no\-syslog\fR"
By default, \fBvtep\-ctl\fR logs its arguments and the details of any
changes that it makes to the system log. This option disables this
@@ -336,13 +331,9 @@ Prints the configured manager(s).
Deletes the configured manager(s).
.
.IP "\fBset\-manager\fR \fItarget\fR\&..."
-Sets the configured manager target or targets. Each \fItarget\fR may
-use any of the following forms:
-.
-.RS
-.so ovsdb/remote-active.man
-.so ovsdb/remote-passive.man
-.RE
+Sets the configured manager target or targets.
+Each \fItarget\fR may be an OVSDB active or passive connection method,
+e.g. \fBpssl:6640\fR, as described in \fBovsdb\fR(7).
.
.SS "Database Commands"
.
I'm calling this "aspirational documentation" because it documents code that is incompletely implemented and does not work yet. I'd appreciate feedback on the plan. I suggest reading ovsdb.7.xml in particular, which explains the overall design, goal, and use of OVSDB, with a lot of detail on how clustering is meant to work from a user perspective. Signed-off-by: Ben Pfaff <blp@ovn.org> --- manpages.mk | 56 +--- ovn/utilities/ovn-sbctl.8.in | 19 +- ovsdb/automake.mk | 7 +- ovsdb/ovsdb-client.1.in | 184 ++++++++--- ovsdb/ovsdb-schemas.man | 19 ++ ovsdb/ovsdb-server.1.in | 168 ++++++++-- ovsdb/ovsdb-tool.1.in | 186 +++++++---- ovsdb/ovsdb.7.xml | 725 +++++++++++++++++++++++++++++++++++++++++++ ovsdb/remote-active.man | 19 -- ovsdb/remote-passive.man | 26 -- ovsdb/replication.man | 23 -- python/build/nroff.py | 15 +- utilities/ovs-vsctl.8.in | 21 +- vswitchd/ovs-vswitchd.8.in | 7 +- vtep/vtep-ctl.8.in | 23 +- 15 files changed, 1204 insertions(+), 294 deletions(-) create mode 100644 ovsdb/ovsdb-schemas.man create mode 100644 ovsdb/ovsdb.7.xml delete mode 100644 ovsdb/remote-active.man delete mode 100644 ovsdb/remote-passive.man