[ovs-dev] [PATCH RFC 43/52] ovsdb: Improve documentation.
Ben Pfaff
blp at ovn.org
Tue Sep 19 22:01:16 UTC 2017
Signed-off-by: Ben Pfaff <blp at ovn.org>
---
NEWS | 2 +
manpages.mk | 56 +---
ovn/controller/ovn-controller.8.xml | 5 +-
ovn/northd/ovn-northd.8.xml | 6 +-
ovn/utilities/ovn-sbctl.8.in | 19 +-
ovsdb/.gitignore | 2 +
ovsdb/automake.mk | 15 +-
ovsdb/ovsdb-client.1.in | 111 ++++---
ovsdb/ovsdb-schemas.man | 19 ++
ovsdb/ovsdb-server.1.in | 110 +++++--
ovsdb/ovsdb-tool.1.in | 126 ++++----
ovsdb/ovsdb.5.xml | 151 +++++++++
ovsdb/ovsdb.7.xml | 605 ++++++++++++++++++++++++++++++++++++
ovsdb/remote-active.man | 17 -
ovsdb/remote-active.xml | 30 --
ovsdb/remote-passive.man | 19 --
ovsdb/remote-passive.xml | 36 ---
ovsdb/replication-syn.man | 2 -
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 +-
23 files changed, 1042 insertions(+), 378 deletions(-)
create mode 100644 ovsdb/ovsdb-schemas.man
create mode 100644 ovsdb/ovsdb.5.xml
create mode 100644 ovsdb/ovsdb.7.xml
delete mode 100644 ovsdb/remote-active.man
delete mode 100644 ovsdb/remote-active.xml
delete mode 100644 ovsdb/remote-passive.man
delete mode 100644 ovsdb/remote-passive.xml
delete mode 100644 ovsdb/replication-syn.man
delete mode 100644 ovsdb/replication.man
diff --git a/NEWS b/NEWS
index 1ab0f1038c24..31f4b884bf55 100644
--- a/NEWS
+++ b/NEWS
@@ -1,6 +1,8 @@
Post-v2.8.0
--------------------
- OVSDB:
+ * New high-level documentation in ovsdb(7).
+ * New file format documentation for developers in ovsdb(5).
* ovsdb-server now always hosts a built-in database named _Server. See
ovsdb-server(5) for more details.
- ovs-vsctl and other commands that display data in tables now support a
diff --git a/manpages.mk b/manpages.mk
index d610d8862f24..7d6a507e0039 100644
--- a/manpages.mk
+++ b/manpages.mk
@@ -16,11 +16,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:
@@ -29,10 +25,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 \
@@ -49,8 +41,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:
@@ -65,8 +56,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 \
@@ -90,11 +80,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:
@@ -117,22 +103,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
@@ -252,11 +236,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:
@@ -267,10 +247,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 \
@@ -287,9 +263,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:
@@ -305,8 +279,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 \
@@ -316,11 +288,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:
@@ -329,7 +297,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:
diff --git a/ovn/controller/ovn-controller.8.xml b/ovn/controller/ovn-controller.8.xml
index 5641abc7c6f3..2af3db5ab851 100644
--- a/ovn/controller/ovn-controller.8.xml
+++ b/ovn/controller/ovn-controller.8.xml
@@ -55,10 +55,9 @@
information from the local Open vSwitch's ovsdb-server instance.
The default location is <code>db.sock</code> in the local Open
vSwitch's "run" directory. It may be overridden by specifying the
- <var>ovs-database</var> argument in one of the following forms:
+ <var>ovs-database</var> argument as an OVSDB active or passive
+ connection method, as described in <code>ovsdb</code>(7).
</p>
- <xi:include href="ovsdb/remote-active.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
- <xi:include href="ovsdb/remote-passive.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
<p>
<code>ovn-controller</code> assumes it gets configuration
diff --git a/ovn/northd/ovn-northd.8.xml b/ovn/northd/ovn-northd.8.xml
index 0d85ec0d2ba2..a568c31d9ba5 100644
--- a/ovn/northd/ovn-northd.8.xml
+++ b/ovn/northd/ovn-northd.8.xml
@@ -36,11 +36,9 @@
</dd>
</dl>
<p>
- <var>database</var> in the above options must take one of the following
- forms:
+ <var>database</var> in the above options must be an OVSDB active or
+ passive connection method, as described in <code>ovsdb</code>(7).
</p>
- <xi:include href="ovsdb/remote-active.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
- <xi:include href="ovsdb/remote-passive.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
<h2>Daemon Options</h2>
<xi:include href="lib/daemon.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
diff --git a/ovn/utilities/ovn-sbctl.8.in b/ovn/utilities/ovn-sbctl.8.in
index ec24da4ee754..cd43cf3beb6f 100644
--- a/ovn/utilities/ovn-sbctl.8.in
+++ b/ovn/utilities/ovn-sbctl.8.in
@@ -58,11 +58,8 @@ Otherwise, the default is \fBunix:@RUNDIR@/ovnsb_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
@@ -210,14 +207,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.
.
diff --git a/ovsdb/.gitignore b/ovsdb/.gitignore
index fbcefafc6e97..39fac62ab630 100644
--- a/ovsdb/.gitignore
+++ b/ovsdb/.gitignore
@@ -11,3 +11,5 @@
/ovsdb-tool
/ovsdb-tool.1
/libovsdb.pc
+/ovsdb.5
+/ovsdb.7
diff --git a/ovsdb/automake.mk b/ovsdb/automake.mk
index c1d402c43206..c6490288bc4b 100644
--- a/ovsdb/automake.mk
+++ b/ovsdb/automake.mk
@@ -1,3 +1,8 @@
+# general documentation
+man_MANS += ovsdb/ovsdb.5 ovsdb/ovsdb.7
+EXTRA_DIST += ovsdb/ovsdb.5.xml ovsdb/ovsdb.7.xml
+CLEANFILES += ovsdb/ovsdb.5 ovsdb/ovsdb.7
+
# libovsdb
lib_LTLIBRARIES += ovsdb/libovsdb.la
ovsdb_libovsdb_la_LDFLAGS = \
@@ -46,15 +51,7 @@ ovsdb_libovsdb_la_CPPFLAGS = $(AM_CPPFLAGS)
pkgconfig_DATA += \
ovsdb/libovsdb.pc
-MAN_FRAGMENTS += \
- ovsdb/remote-active.man \
- ovsdb/remote-passive.man \
- ovsdb/replication.man \
- ovsdb/replication-syn.man
-
-EXTRA_DIST += \
- ovsdb/remote-active.xml \
- ovsdb/remote-passive.xml
+MAN_FRAGMENTS += ovsdb/ovsdb-schemas.man
# ovsdb-tool
bin_PROGRAMS += ovsdb/ovsdb-tool
diff --git a/ovsdb/ovsdb-client.1.in b/ovsdb/ovsdb-client.1.in
index d3dd84c3bb6a..4b543d96e552 100644
--- a/ovsdb/ovsdb-client.1.in
+++ b/ovsdb/ovsdb-client.1.in
@@ -13,16 +13,18 @@
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:"
.br
+\fBovsdb\-client \fR[\fIoptions\fR] \fBget\-schema\-version\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
@@ -33,8 +35,9 @@ ovsdb\-client \- command-line interface to \fBovsdb-server\fR(1)
.br
\fBovsdb\-client \fR[\fIoptions\fR] \fBmonitor\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR] \fBALL\fR
.br
-\fBovsdb\-client \fR[\fIoptions\fR] \fBmonitor-cond\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR] \fIconditions
+\fBovsdb\-client \fR[\fIoptions\fR] \fBmonitor\-cond\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR] \fIconditions
\fItable\fR [\fIcolumn\fR[\fB,\fIcolumn\fR]...]...
+.IP "Testing Commands:"
.br
\fBovsdb\-client \fR[\fIoptions\fR] \fBlock\fI \fR[\fIserver\fR] \fIlock\fR
.br
@@ -42,6 +45,7 @@ ovsdb\-client \- command-line interface to \fBovsdb-server\fR(1)
.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]
@@ -60,40 +64,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
-The default \fIdatabase\fR is \fBOpen_vSwitch\fR.
+For an introduction to OVSDB and its implementation in Open vSwitch,
+see \fBovsdb\fR(7).
+.PP
+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
@@ -105,10 +104,36 @@ 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 "\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.
+.
+.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,7 +142,7 @@ specified, only that table is retrieved. If at least one \fIcolumn\fR
is specified, only those columns are retrieved.
.
.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]...]..."
+.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
\fItable\fR in \fIdatabase\fR. By default, the initial contents of \fItable\fR are
printed, followed by each change as it occurs. If conditions empty,
@@ -144,12 +169,12 @@ line.
with the following change: A condition can be either a 3-element JSON array
as deescribed in the RFC or a boolean value..
.IP
-If \fB\-\-detach\fR is used with \fBmonitor\fR or \fBmonitor-cond\fR, then
+If \fB\-\-detach\fR is used with \fBmonitor\fR or \fBmonitor\-cond\fR, then
\fBovsdb\-client\fR detaches after it has successfully received and
printed the initial contents of \fItable\fR.
.IP
The \fBmonitor\fR command uses RFC 7047 "monitor" method to open a monitor
-session with the server. The \fBmonitor-cond\fR command uses RFC 7047
+session with the server. The \fBmonitor\-cond\fR command uses RFC 7047
extension "monitor_cond" method. See \fBovsdb\-server\fR(1) for details.
.IP "\fBmonitor\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR] \fBALL\fR"
Connects to \fIserver\fR and monitors the contents of all tables in
@@ -161,13 +186,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
@@ -190,13 +215,13 @@ The following options controlling output formatting:
.so lib/table.man
.
.IP "\fB\-\-timestamp\fR"
-For the \fBmonitor\fR and \fBmonitor-cond\fR commands, add a timestamp to each
+For the \fBmonitor\fR and \fBmonitor\-cond\fR commands, add a timestamp to each
table update. Most output formats add the timestamp on a line of its own
just above the table. The JSON output format puts the timestamp in a
member of the top-level JSON object named \fBtime\fR.
.
.SS "Daemon Options"
-The daemon options apply only to the \fBmonitor\fR and \fBmonitor-cond\fR commands.
+The daemon options apply only to the \fBmonitor\fR and \fBmonitor\-cond\fR commands.
With any other command, they have no effect.
.ds DD
.so lib/daemon.man
@@ -211,6 +236,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).
diff --git a/ovsdb/ovsdb-schemas.man b/ovsdb/ovsdb-schemas.man
new file mode 100644
index 000000000000..3630d5da3dd8
--- /dev/null
+++ b/ovsdb/ovsdb-schemas.man
@@ -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.
diff --git a/ovsdb/ovsdb-server.1.in b/ovsdb/ovsdb-server.1.in
index 455010c3f5fa..02144125e67c 100644
--- a/ovsdb/ovsdb-server.1.in
+++ b/ovsdb/ovsdb-server.1.in
@@ -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,44 +34,31 @@ 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 at DBDIR@/conf.db\fR. The database
files must already have been created and initialized using, for
example, \fBovsdb\-tool create\fR.
.PP
+This OVSDB implementation supports standalone and active-backup
+databases, as well as database replication.
+See the Service Models section of \fBovsdb\fR(7) for more information.
+.PP
In addition to user-specified databases, \fBovsdb\-server\fR version
2.9 and later also always hosts a built-in database named
\fB_Server\fR. Please see \fBovsdb\-server\fR(5) for documentation on
this database's schema.
-.
-.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\-\-active\fR option. 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.
-.
.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,
@@ -126,8 +116,50 @@ 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. 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
@@ -150,7 +182,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.
@@ -215,23 +247,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.
@@ -709,5 +755,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).
diff --git a/ovsdb/ovsdb-tool.1.in b/ovsdb/ovsdb-tool.1.in
index 8c799f4cc990..ebfd33b27163 100644
--- a/ovsdb/ovsdb-tool.1.in
+++ b/ovsdb/ovsdb-tool.1.in
@@ -12,10 +12,10 @@
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
+.IP "Version Management Commands:"
\fBovsdb\-tool \fR[\fIoptions\fR] \fBconvert \fR[\fIdb\fR [\fIschema
\fR[\fItarget\fR]]]
.br
@@ -28,6 +28,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 +46,30 @@ 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 a common on-disk format For a
+specification of this format, see \fBovsdb\fR(5). 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 create a new OVSDB database file.
+They 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, which
+must be the name of a file that contains an OVSDB schema in JSON
+format, as specified in the OVSDB specification. The new database is
+initially empty.
.
.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.
-.
-.PP
-Some OVSDB databases and schemas, especially very old ones, do not
-have a version number.
-.
+.so ovsdb/ovsdb-schemas.man
.PP
These commands work with different versions of OVSDB schemas and
databases.
@@ -91,7 +80,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,44 +92,56 @@ 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
.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
.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.
-.
+.IP
.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.
-.
+.IP
.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. Instead, send the \fBovsdb\-server/compact\fR
+command to \fBovsdb\-server\fR, via \fBovs\-appctl\fR).
+.
.IP "[\fB\-\-rbac\-role=\fIrole\fR] \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
@@ -152,11 +156,10 @@ 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. Instead, use \fBovsdb\-client\fR's \fBtransact\fR
+command to send the query to \fBovsdb\-server\fR.
.IP
By default, the transaction is executed using the ``superuser'' RBAC
role. Use \fB\-\-rbac\-role\fR to specify a different role.
@@ -173,6 +176,11 @@ 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 \fR[\fIdb\fR]"
+.IQ "\fBschema\-name \fR[\fIschema\fR]"
+Prints the name of the schema embedded within the database \fIdb\fR or
+in the JSON schema \fIschema\fR on stdout.
+.
.SH OPTIONS
.SS "Logging Options"
.so lib/vlog.man
@@ -184,6 +192,6 @@ default \fIschema\fR is \fB at 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).
diff --git a/ovsdb/ovsdb.5.xml b/ovsdb/ovsdb.5.xml
new file mode 100644
index 000000000000..2f40acea03cb
--- /dev/null
+++ b/ovsdb/ovsdb.5.xml
@@ -0,0 +1,151 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manpage program="ovsdb" section="5" title="OVSDB">
+ <h1>Name</h1>
+ <p>ovsdb -- Open vSwitch Database (File Formats)</p>
+
+ <h1>Description</h1>
+ <p>
+ 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. This manpage documents the format used by Open vSwitch.
+ </p>
+
+ <p>
+ Most users do not need to be concerned with this specification. Instead,
+ to manipulate OVSDB files, refer to <code>ovsdb-tool</code>(1). For an
+ introduction to OVSDB as a whole, read <code>ovsdb</code>(7).
+ </p>
+
+ <p>
+ 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.
+ </p>
+
+ <p>
+ OVSDB files do not include the values of ephemeral columns.
+ </p>
+
+ <p>
+ Database files 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.
+ </p>
+
+ <p>
+ The first line in each record has the format <code>OVSDB JSON
+ <var>length</var> <var>hash</var></code>, where <var>length</var> is a
+ positive decimal integer and <var>hash</var> is a SHA-1 checksum expressed
+ as 40 hexadecimal digits. Words in the first line must be separated by
+ exactly one space.
+ </p>
+
+ <p>
+ The second line must be exactly <var>length</var> bytes long (including the
+ LF) and its SHA-1 checksum (including the LF) must match <var>hash</var>
+ 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
+ expresses any LF characters within a JSON string as <code>\n</code>. 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 <var>length</var> and <var>hash</var> are correct.)
+ </p>
+
+ <h2>JSON Notation</h2>
+
+ <p>
+ We use notation from RFC 7047 here to describe the JSON data in records.
+ In addition to the notation defined there, we add the following:
+ </p>
+
+ <dl>
+ <dt><raw-uuid></dt>
+ <dd>
+ A 36-character JSON string that contains a UUID in the format described
+ by RFC 4122, e.g. <code>"550e8400-e29b-41d4-a716-446655440000"</code>.
+ </dd>
+ </dl>
+
+ <h2>Standalone Format</h2>
+
+ <p>
+ 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).
+ </p>
+
+ <p>
+ The second and subsequent records in a standalone database are transaction
+ records. Each record may have the following optional special members,
+ which do not have any semantics but are often useful to administrators
+ looking through a database log with <code>ovsdb-tool show-log</code>:
+ </p>
+
+ <dl>
+ <dt>"_date": <integer></dt>
+ <dd>
+ <p>
+ 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 detected by noticing that
+ their values are less than 2**32.
+ </p>
+
+ <p>
+ OVSDB always writes a <code>_date</code> member.
+ </p>
+ </dd>
+
+ <dt>"_comment": <string></dt>
+ <dd>
+ <p>
+ A JSON string that specifies the comment provided in a transaction
+ <code>comment</code> operation. If a transaction has multiple
+ <code>comment</code> operations, OVSDB concatenates them into a single
+ <code>_comment</code> member, separated by a new-line.
+ </p>
+
+ <p>
+ OVSDB only writes a <code>_comment</code> member if it would be
+ a nonempty string.
+ </p>
+ </dd>
+ </dl>
+
+ <p>
+ 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>:
+ </p>
+
+ <dl>
+ <dt><table-txn></dt>
+ <dd>
+ 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.
+ </dd>
+
+ <dt><row-txn></dt>
+ <dd>
+ <p>
+ Either <code>null</code>, which indicates that the transaction deleted
+ this row, or a JSON object that describes how the transaction inserted
+ or modified the row, whose names are the names of columns and whose
+ values are <value>s that give the column's new value.
+ </p>
+
+ <p>
+ For new rows, the OVSDB implementation omits columns whose values 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.
+ </p>
+ </dd>
+ </dl>
+
+</manpage>
diff --git a/ovsdb/ovsdb.7.xml b/ovsdb/ovsdb.7.xml
new file mode 100644
index 000000000000..8d9a6ec97caf
--- /dev/null
+++ b/ovsdb/ovsdb.7.xml
@@ -0,0 +1,605 @@
+<?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 formats. 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 two service models for databases: <dfn>standalone</dfn>, and
+ <dfn>active-backup</dfn>. The service models provide different compromises
+ among consistency and availability.
+ </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.
+ </p>
+
+ <p>
+ Open vSwitch 2.6 introduced support for the active-backup 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>
+ </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>. On Linux, use
+ <code>%<var>device</var></code> to designate a scope for IPv6 link-level
+ addresses, e.g. <code>ssl:[fe80::1234%eth0]:6653</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.
+ </p>
+
+ <p>
+ To restore from a backup, stop the database server or servers, overwrite
+ the database file with the backup (e.g. with <code>cp</code>), and then
+ restart the servers.
+ </p>
+
+ <p>
+ None of these approaches saves and restores data in columns that the schema
+ designates as ephemeral. This is by design: the designer of a schema only
+ marks a column as ephemeral if it is acceptable for its data to be lost
+ when a database server restarts.
+ </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
+ 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 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. 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>
diff --git a/ovsdb/remote-active.man b/ovsdb/remote-active.man
deleted file mode 100644
index bf5b323dd55e..000000000000
--- a/ovsdb/remote-active.man
+++ /dev/null
@@ -1,17 +0,0 @@
-.IP "\fBssl:\fIip\fB:\fIport\fR"
-.IQ "\fBtcp:\fIip\fB:\fIport\fR"
-The given SSL or plain TCP \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. On
-Linux, use \fB%\fIdevice\fR to designate a scope for IPv6 link-level
-addresses, e.g. \fBssl:[fe80::1234%eth0]:6653\fR. For \fBssl\fR, the
-\fB\-\-private\-key\fR, \fB\-\-certificate\fR, and \fB\-\-ca\-cert\fR
-options are mandatory.
-.
-.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.
diff --git a/ovsdb/remote-active.xml b/ovsdb/remote-active.xml
deleted file mode 100644
index cdd2cb841106..000000000000
--- a/ovsdb/remote-active.xml
+++ /dev/null
@@ -1,30 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<dl>
- <dt><code>ssl:</code><var>ip</var><code>:</code><var>port</var></dt>
- <dd>
- The specified SSL <var>port</var> on the host at the given <var>ip</var>,
- which must be expressed as an IP address (not a DNS name) in IPv4 or IPv6
- address format. If <var>ip</var> is an IPv6 address, then wrap
- <var>ip</var> with square brackets, e.g.: <code>ssl:[::1]:6640</code>.
- The <code>--private-key</code>, <code>--certificate</code>, and
- <code>--ca-cert</code> options are mandatory when this form is used.
- </dd>
- <dt><code>tcp:</code><var>ip</var><code>:</code><var>port</var></dt>
- <dd>
- Connect to the given TCP <var>port</var> on <var>ip</var>, where
- <var>ip</var> can be an IPv4 or IPv6 address. If <var>ip</var> is an
- IPv6 address, then wrap <var>ip</var> with square brackets, e.g.:
- <code>tcp:[::1]:6640</code>.
- </dd>
- <dt><code>unix:</code><var>file</var></dt>
- <dd>
- <p>
- On POSIX, 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>
-</dl>
diff --git a/ovsdb/remote-passive.man b/ovsdb/remote-passive.man
deleted file mode 100644
index f2a1868442da..000000000000
--- a/ovsdb/remote-passive.man
+++ /dev/null
@@ -1,19 +0,0 @@
-.IP "\fBpssl:\fIport\fR[\fB:\fIip\fR]"
-.IQ "\fBptcp:\fIport\fR[\fB:\fIip\fR]"
-Listen on the given SSL or 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 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. On Linux,
-use \fB%\fIdevice\fR to designate a scope for IPv6 link-level
-addresses, e.g. \fBpssl:6653:[fe80::1234%eth0]\fR. For \fBpssl\fR,
-the \fB\-\-private\-key\fR, \fB\-\-certificate\fR, and
-\fB\-\-ca\-cert\fR options are mandatory.
-.
-.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.
diff --git a/ovsdb/remote-passive.xml b/ovsdb/remote-passive.xml
deleted file mode 100644
index 8560d6cfa110..000000000000
--- a/ovsdb/remote-passive.xml
+++ /dev/null
@@ -1,36 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<dl>
- <dt><code>pssl:</code><var>port</var><code>:</code><var>ip</var></dt>
- <dd>
- Listen on the given SSL <var>port</var> 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 <var>ip</var> limits connections to those from the given
- <var>ip</var>, either IPv4 or IPv6 address. If <var>ip</var> is
- an IPv6 address, then wrap <var>ip</var> with square brackets, e.g.:
- <code>pssl:6640:[::1]</code>. The <code>--private-key</code>,
- <code>--certificate</code>, and <code>--ca-cert</code> options are
- mandatory when this form is used.
- </dd>
- <dt><code>ptcp:</code><var>port</var><code>:</code><var>ip</var></dt>
- <dd>
- Listen on the given TCP <var>port</var> 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
- <var>ip</var> may be specified to listen only for connections to the given
- <var>ip</var>, either IPv4 or IPv6 address. If <var>ip</var> is
- an IPv6 address, then wrap <var>ip</var> with square brackets, e.g.:
- <code>ptcp:6640:[::1]</code>.
- </dd>
- <dt><code>punix:</code><var>file</var></dt>
- <dd>
- <p>
- On POSIX, listen on the Unix domain server socket named <var>file</var>
- for a connection.
- </p>
- <p>
- On Windows, listen on a local named pipe. A file is created in the path
- <var>file</var> to mimic the behavior of a Unix domain socket.
- </p>
- </dd>
-</dl>
diff --git a/ovsdb/replication-syn.man b/ovsdb/replication-syn.man
deleted file mode 100644
index adfd7c287238..000000000000
--- a/ovsdb/replication-syn.man
+++ /dev/null
@@ -1,2 +0,0 @@
-.IP "Syncing options:"
-[\fB\-\-sync\-from=\fIserver\fR]
diff --git a/ovsdb/replication.man b/ovsdb/replication.man
deleted file mode 100644
index a2ea665107ba..000000000000
--- a/ovsdb/replication.man
+++ /dev/null
@@ -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.
diff --git a/python/build/nroff.py b/python/build/nroff.py
index 401f6992af9b..73353061cccc 100644
--- a/python/build/nroff.py
+++ b/python/build/nroff.py
@@ -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:
diff --git a/utilities/ovs-vsctl.8.in b/utilities/ovs-vsctl.8.in
index e5e565e8a58a..f539af5486e4 100644
--- a/utilities/ovs-vsctl.8.in
+++ b/utilities/ovs-vsctl.8.in
@@ -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
diff --git a/vswitchd/ovs-vswitchd.8.in b/vswitchd/ovs-vswitchd.8.in
index c18baf6db9e7..478acc52fa28 100644
--- a/vswitchd/ovs-vswitchd.8.in
+++ b/vswitchd/ovs-vswitchd.8.in
@@ -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
diff --git a/vtep/vtep-ctl.8.in b/vtep/vtep-ctl.8.in
index b980a7186cf2..abf5e1673f78 100644
--- a/vtep/vtep-ctl.8.in
+++ b/vtep/vtep-ctl.8.in
@@ -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"
.
--
2.10.2
More information about the dev
mailing list