.\" -*- nroff -*-
.de IQ
.  br
.  ns
.  IP "\\$1"
..
.TH ovsdb\-server 1 "@VERSION@" "Open vSwitch" "Open vSwitch Manual"
.\" This program's name:
.ds PN ovsdb\-server
.
.SH NAME
ovsdb\-server \- Open vSwitch database server
.
.SH SYNOPSIS
\fBovsdb\-server\fR
[\fIdatabase\fR]\&...
[\fB\-\-remote=\fIremote\fR]\&...
[\fB\-\-run=\fIcommand\fR]
.so lib/daemon-syn.man
.so lib/service-syn.man
.so lib/vlog-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
.so lib/ssl-connect-syn.man
.so lib/unixctl-syn.man
.so lib/common-syn.man
.
.SH DESCRIPTION
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.
.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.
.SH OPTIONS
.
.IP "\fB\-\-remote=\fIremote\fR"
Adds \fIremote\fR as a connection method used by \fBovsdb\-server\fR.
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
.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,
\fBovsdb\-server\fR also adds and drops connection methods accordingly.
.IP
If \fIcolumn\fR's type is string or set of strings, then the
connection methods are taken directly from the column.  The connection
methods in the column must have one of the forms described above.
.IP
If \fIcolumn\fR's type is UUID or set of UUIDs and references a table,
then each UUID is looked up in the referenced table to obtain a row.
The following columns in the row, if present and of the correct type,
configure a connection method.  Any additional columns are ignored.
.RS
.IP "\fBtarget\fR (string)"
Connection method, in one of the forms described above.  This column
is mandatory: if it is missing or empty then no connection method can
be configured.
.IP "\fBmax_backoff\fR (integer)"
Maximum number of milliseconds to wait between connection attempts.
.IP "\fBinactivity_probe\fR (integer)"
Maximum number of milliseconds of idle time on connection to
client before sending an inactivity probe message.
.IP "\fBread_only\fR (boolean)"
If true, only read-only transactions are allowed on this connection.
.RE
.IP
It is an error for \fIcolumn\fR to have another type.
.RE
.
.IP
To connect or listen on multiple connection methods, use multiple
\fB\-\-remote\fR options.
.
.IP "\fB\-\-run=\fIcommand\fR]"
Ordinarily \fBovsdb\-server\fR runs forever, or until it is told to
exit (see \fBRUNTIME MANAGEMENT COMMANDS\fR below).  With this option,
\fBovsdb\-server\fR instead starts a shell subprocess running
\fIcommand\fR.  When the subprocess terminates, \fBovsdb\-server\fR
also exits gracefully.  If the subprocess exits normally with exit
code 0, then \fBovsdb\-server\fR exits with exit code 0 also;
otherwise, it exits with exit code 1.
.IP
This option can be useful where a database server is needed only to
run a single command, e.g.:
.B "ovsdb\-server \-\-remote=punix:socket \-\-run='ovsdb\-client dump unix:socket Open_vSwitch'"
.IP
This option is not supported on Windows platform.
.SS "Daemon Options"
.ds DD \
\fBovsdb\-server\fR detaches only after it starts listening on all \
configured remotes.
.so lib/daemon.man
.SS "Service Options"
.so lib/service.man
.SS "Logging Options"
.so lib/vlog.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
configuration from the database.  If any of these options is given
\fBdb:\fIdb\fB,\fItable\fB,\fIcolumn\fR as its argument, then the
actual file name is read from the specified \fIcolumn\fR in \fItable\fR
within the \fIdb\fR database.  The \fIcolumn\fR must have type
string or set of strings.  The first nonempty string in the table is taken
as the file name.  (This means that ordinarily there should be at most
one row in \fItable\fR.)
.so lib/ssl.man
.so lib/ssl-bootstrap.man
.so lib/ssl-peer-ca-cert.man
.SS "SSL Connection Options"
.so lib/ssl-connect.man
.SS "Other Options"
.so lib/unixctl.man
.so lib/common.man
.SH "RUNTIME MANAGEMENT COMMANDS"
\fBovs\-appctl\fR(8) can send commands to a running
\fBovsdb\-server\fR process.  The currently supported commands are
described below.
.SS "\fBovsdb\-server\fR Commands"
These commands are specific to \fBovsdb\-server\fR.
.IP "\fBexit\fR"
Causes \fBovsdb\-server\fR to gracefully terminate.
.IP "\fBovsdb\-server/compact\fR [\fIdb\fR]"
Compacts database \fIdb\fR in-place.  If \fIdb\fR is not
specified, compacts every database in-place.  A database is also
compacted automatically when a transaction is logged if it is over 4
times as large as its previous compacted size (and at least 10 MB),
but not before 100 commits have been added or 10 minutes have elapsed
since the last compaction.
.
.IP "\fBovsdb\-server/reconnect\fR"
Makes \fBovsdb\-server\fR drop all of the JSON\-RPC
connections to database clients and reconnect.
.IP
This command might be useful for debugging issues with database
clients.
.
.IP "\fBovsdb\-server/add\-remote \fIremote\fR"
Adds a remote, as if \fB\-\-remote=\fIremote\fR had been specified on
the \fBovsdb\-server\fR command line.  (If \fIremote\fR is already a
remote, this command succeeds without changing the configuration.)
.
.IP "\fBovsdb\-server/remove\-remote \fIremote\fR"
Removes the specified \fIremote\fR from the configuration, failing
with an error if \fIremote\fR is not configured as a remote.  This
command only works with remotes that were named on \fB\-\-remote\fR or
\fBovsdb\-server/add\-remote\fR, that is, it will not remove remotes
added indirectly because they were read from the database by
configuring a \fBdb:\fIdb\fB,\fItable\fB,\fIcolumn\fR remote.
(You can remove a database source with \fBovsdb\-server/remove\-remote
\fBdb:\fIdb\fB,\fItable\fB,\fIcolumn\fR, but not individual
remotes found indirectly through the database.)
.
.IP "\fBovsdb\-server/list\-remotes"
Outputs a list of the currently configured remotes named on
\fB\-\-remote\fR or \fBovsdb\-server/add\-remote\fR, that is, it does
not list remotes added indirectly because they were read from the
database by configuring a
\fBdb:\fIdb\fB,\fItable\fB,\fIcolumn\fR remote.
.
.IP "\fBovsdb\-server/add\-db \fIdatabase\fR"
Adds the \fIdatabase\fR to the running \fBovsdb\-server\fR.  The database
file must already have been created and initialized using, for example,
\fBovsdb\-tool create\fR.
.
.IP "\fBovsdb\-server/remove\-db \fIdatabase\fR"
Removes \fIdatabase\fR from the running \fBovsdb\-server\fR.  \fIdatabase\fR
must be a database name as listed by \fBovsdb-server/list\-dbs\fR.
.IP
If a remote has been configured that points to the specified
\fIdatabase\fR (e.g. \fB\-\-remote=db:\fIdatabase\fB,\fR... on the
command line), then it will be disabled until another database with
the same name is added again (with \fBovsdb\-server/add\-db\fR).
.IP
Any public key infrastructure options specified through this database
(e.g. \fB\-\-private\-key=db:\fIdatabase,\fR... on the command line)
will be disabled until another database with the same name is added
again (with \fBovsdb\-server/add\-db\fR).
.
.IP "\fBovsdb\-server/list\-dbs"
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"
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"
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 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.
.
.IP "\fBovsdb\-server/sync\-status"
Prints a summary of replication run time information. The \fBstate\fR
information is always provided, indicating whether the server is running
in the \fIactive\fR or the \fIbackup\fR mode.
When running in backup mode, replication connection status, which
can be either \fIconnecting\fR, \fIreplicating\fR or \fIerror\fR, are shown.
When the connection is in \fIreplicating\fR state, further output shows
the list of databases currently replicating, and the tables that are
excluded.
.
.so lib/vlog-unixctl.man
.so lib/memory-unixctl.man
.so lib/coverage-unixctl.man
.SH "BUGS"
.
In Open vSwitch before version 2.4, when \fBovsdb\-server\fR sent
JSON-RPC error responses to some requests, it incorrectly formulated
them with the \fBresult\fR and \fBerror\fR swapped, so that the
response appeared to indicate success (with a nonsensical result)
rather than an error.  The requests that suffered from this problem
were:
.
.IP \fBtransact\fR
.IQ \fBget_schema\fR
Only if the request names a nonexistent database.
.IP \fBmonitor\fR
.IQ \fBlock\fR
.IQ \fBunlock\fR
In all error cases.
.
.PP
Of these cases, the only error that a well-written application is
likely to encounter in practice is \fBmonitor\fR of tables or columns
that do not exist, in an situation where the application has been
upgraded but the old database schema is still temporarily in use.  To
handle this situation gracefully, we recommend that clients should
treat a \fBmonitor\fR response with a \fBresult\fR that contains an
\fBerror\fR key-value pair as an error (assuming that the database
being monitored does not contain a table named \fBerror\fR).
.
.SH "SEE ALSO"
\fBovsdb\fR(7),
\fBovsdb\-tool\fR(1),
\fBovsdb\-server\fR(5),
\fBovsdb\-server\fR(7).