.\" -*- nroff -*-
.TH ovsdb\-server 1 "November 2009" "Open vSwitch" "Open vSwitch Manual"
.\" This program's name:
.ds PN ovsdb\-server
.\" SSL peer program's name:
.ds SN ovsdb\-client
.
.SH NAME
ovsdb\-server \- Open vSwitch database server
.
.SH SYNOPSIS
\fBovsdb\-server\fR
[\fIdatabase\fR]
[\fB\-\-remote=\fIremote\fR]\&...
[\fB\-\-run=\fIcommand\fR]
.IP "Daemon options:"
[\fB\-\-pidfile\fR[\fB=\fIpidfile\fR]]
[\fB\-\-overwrite\-pidfile\fR]
[\fB\-\-detach\fR]
[\fB\-\-no\-chdir\fR]
.IP "Logging options:"
[\fB\-v\fR[\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]]]]\&...
.br
[\fB\-\-verbose[=\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]]]]\&...
.br
[\fB\-\-log\-file\fR[\fB=\fIfile\fR]]
.IP "Public key infrastructure options:"
[\fB\-\-private\-key=\fIprivkey.pem\fR]
.br
[\fB\-\-certificate=\fIcert.pem\fR]
.br
[\fB\-\-ca\-cert=\fIcacert.pem\fR]
.br
[\fB\-\-bootstrap\-ca\-cert=\fIcacert.pem]
.IP "Runtime management options:"
\fB\-\-unixctl=\fIsocket\fR
.IP "Common options:"
[\fB\-h\fR | \fB\-\-help\fR]
[\fB\-V\fR | \fB\-\-version\fR]

.
.SH DESCRIPTION
The \fBovsdb\-server\fR program provides RPC interfaces to an Open
vSwitch database (OVSDB).  It supports JSON-RPC client connections
over active or passive TCP/IP or Unix domain sockets.
.PP
The OVSDB file may be specified on the command line as \fIdatabase\fR.
The default is \fB/var/lib/openvswitch/conf.db\fR.  The database
file must already have been created and initialized using, for
example, \fBovsdb\-tool create\fR.
.
.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:
.
.RS
.IP "\fBpssl:\fIport\fR[\fB:\fIip\fR]"
Listen on the given SSL \fIport\fR for a connection.  By default,
\fB\*(PN\fR listens for connections to any local IP address, but
specifying \fIip\fR limits connections to those from the given
\fIip\fR.  The \fB\-\-private\-key\fR, \fB\-\-certificate\fR, and
\fB\-\-ca\-cert\fR options are mandatory when this form is used.
.
.IP "\fBptcp:\fIport\fR[\fB:\fIip\fR]"
Listen on the given TCP \fIport\fR for a connection.  By default,
\fB\*(PN\fR listens for connections to any local IP address, but
\fIip\fR may be specified to listen only for connections to the given
\fIip\fR.
.
.IP "\fBpunix:\fIfile\fR"
Listen on the Unix domain server socket named \fIfile\fR for a
connection.
.IP "\fBssl:\fIip\fB:\fIport\fR"
The specified SSL \fIport\fR on the host at the given \fIip\fR, which
must be expressed as an IP address (not a DNS name).  The
\fB\-\-private\-key\fR, \fB\-\-certificate\fR, and \fB\-\-ca\-cert\fR
options are mandatory when this form is used.
.
.IP "\fBtcp:\fIip\fB:\fIport\fR"
Connect to the given TCP \fIport\fR on \fIip\fR.
.
.IP "\fBunix:\fIfile\fR"
Connect to the Unix domain server socket named \fIfile\fR.
.
.IP "\fBdb:\fItable\fB,\fIcolumn\fR"
Reads additional connection methods from \fIcolumn\fR in all of the
rows in \fItable\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.
.RE
.IP
It is an error for \fIcolumn\fR to have another type.
.RE
.
.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'"
.SS "Daemon Options"
.ds DD \
\fBovsdb\-server\fR detaches only after it starts listening on all \
configured remotes.
.TP
\fB\-\-pidfile\fR[\fB=\fIpidfile\fR]
Causes a file (by default, \fB\*(PN.pid\fR) to be created indicating
the PID of the running process.  If the \fIpidfile\fR argument is not
specified, or
if it does not begin with \fB/\fR, then it is created in
\fB/var/run/openvswitch\fR.
.IP
If \fB\-\-pidfile\fR is not specified, no pidfile is created.
.
.TP
\fB\-\-overwrite\-pidfile\fR
By default, when \fB\-\-pidfile\fR is specified and the specified pidfile 
already exists and is locked by a running process, \fB\*(PN\fR refuses 
to start.  Specify \fB\-\-overwrite\-pidfile\fR to cause it to instead 
overwrite the pidfile.
.IP
When \fB\-\-pidfile\fR is not specified, this option has no effect.
.
.TP
\fB\-\-detach\fR
Causes \fB\*(PN\fR to detach itself from the foreground session and
run as a background process. \*(DD
.
.TP
\fB\-\-monitor\fR
Creates an additional process to monitor the \fB\*(PN\fR daemon.  If
the daemon dies due to a signal that indicates a programming error
(e.g. \fBSIGSEGV\fR, \fBSIGABRT\fR), then the monitor process starts a
new copy of it.  If the daemon die or exits for another reason, the
monitor process exits.
.IP
This option is normally used with \fB\-\-detach\fR, but it also
functions without it.
.
.TP
\fB\-\-no\-chdir\fR
By default, when \fB\-\-detach\fR is specified, \fB\*(PN\fR 
changes its current working directory to the root directory after it 
detaches.  Otherwise, invoking \fB\*(PN\fR from a carelessly chosen 
directory would prevent the administrator from unmounting the file 
system that holds that directory.
.IP
Specifying \fB\-\-no\-chdir\fR suppresses this behavior, preventing
\fB\*(PN\fR from changing its current working directory.  This may be 
useful for collecting core files, since it is common behavior to write 
core dumps into the current working directory and the root directory 
is not a good directory to use.
.IP
This option has no effect when \fB\-\-detach\fR is not specified.
.SS "Logging Options"
.TP
\fB\-v\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]], \fB\-\-verbose=\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]]
.
Sets the logging level for \fImodule\fR in \fIfacility\fR to
\fIlevel\fR:
.
.RS
.IP \(bu
\fImodule\fR may be any valid module name (as displayed by the
\fB\-\-list\fR action on \fBovs\-appctl\fR(8)), or the special name
\fBANY\fR to set the logging levels for all modules.
.
.IP \(bu
\fIfacility\fR may be \fBsyslog\fR, \fBconsole\fR, or \fBfile\fR to
set the levels for logging to the system log, the console, or a file
respectively, or \fBANY\fR to set the logging levels for both
facilities.  If it is omitted, \fIfacility\fR defaults to \fBANY\fR.
.IP
Regardless of the log levels set for \fBfile\fR, logging to a file
will not take place unless \fB\-\-log\-file\fR is also specified (see
below).
.
.IP \(bu 
\fIlevel\fR must be one of \fBoff\fR, \fBemer\fR, \fBerr\fR, \fBwarn\fR,
\fBinfo\fR, or
\fBdbg\fR, designating the minimum severity of a message for it to be
logged.  If it is omitted, \fIlevel\fR defaults to \fBdbg\fR.  See
\fBovs\-appctl\fR(8) for a definition of each log level.
.RE
.
.TP
\fB\-v\fR, \fB\-\-verbose\fR
Sets the maximum logging verbosity level, equivalent to
\fB\-\-verbose=ANY:ANY:dbg\fR.
.
.TP
\fB\-vPATTERN:\fIfacility\fB:\fIpattern\fR, \fB\-\-verbose=PATTERN:\fIfacility\fB:\fIpattern\fR
Sets the log pattern for \fIfacility\fR to \fIpattern\fR.  Refer to
\fBovs\-appctl\fR(8) for a description of the valid syntax for \fIpattern\fR.
.
.TP
\fB\-\-log\-file\fR[\fB=\fIfile\fR]
Enables logging to a file.  If \fIfile\fR is specified, then it is
used as the exact name for the log file.  The default log file name
used if \fIfile\fR is omitted is \fB/var/log/openvswitch/\*(PN.log\fR.
.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:\fItable\fB,\fIcolumn\fR as its argument, then the actual file
name is read from the specified \fIcolumn\fR in \fItable\fR within the
\fBovsdb\-server\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.)
.de IQ
.  br
.  ns
.  IP "\\$1"
..
.IP "\fB\-p\fR \fIprivkey.pem\fR"
.IQ "\fB\-\-private\-key=\fIprivkey.pem\fR"
Specifies a PEM file containing the private key used as \fB\*(PN\fR's
identity for outgoing SSL connections.
.
.IP "\fB\-c\fR \fIcert.pem\fR"
.IQ "\fB\-\-certificate=\fIcert.pem\fR"
Specifies a PEM file containing a certificate that certifies the
private key specified on \fB\-p\fR or \fB\-\-private\-key\fR to be
trustworthy.  The certificate must be signed by the certificate
authority (CA) that the peer in SSL connections will use to verify it.
.
.IP "\fB\-C\fR \fIcacert.pem\fR"
.IQ "\fB\-\-ca\-cert=\fIcacert.pem\fR"
Specifies a PEM file containing the CA certificate that \fB\*(PN\fR
should use to verify certificates presented to it by SSL peers.  (This
may be the same certificate that SSL peers use to verify the
certificate specified on \fB\-c\fR or \fB\-\-certificate\fR, or it may
be a different one, depending on the PKI design in use.)
.
.IP "\fB\-C none\fR"
.IQ "\fB\-\-ca\-cert=none\fR"
Disables verification of certificates presented by SSL peers.  This
introduces a security risk, because it means that certificates cannot
be verified to be those of known trusted hosts.
.IP "\fB\-\-bootstrap\-ca\-cert=\fIcacert.pem\fR"
When \fIcacert.pem\fR exists, this option has the same effect as
\fB\-C\fR or \fB\-\-ca\-cert\fR.  If it does not exist, then
\fB\*(PN\fR will attempt to obtain the CA certificate from the
SSL peer on its first SSL connection and save it to the named PEM
file.  If it is successful, it will immediately drop the connection
and reconnect, and from then on all SSL connections must be
authenticated by a certificate signed by the CA certificate thus
obtained.
.IP
\fBThis option exposes the SSL connection to a man-in-the-middle
attack obtaining the initial CA certificate\fR, but it may be useful
for bootstrapping.
.IP
This option is only useful if the SSL peer sends its CA certificate as
part of the SSL certificate chain.  The SSL protocol does not require
the server to send the CA certificate, but
\fB\*(SN\fR(8) can be configured to do so with the
\fB\-\-peer\-ca\-cert\fR option.
.IP
This option is mutually exclusive with \fB\-C\fR and
\fB\-\-ca\-cert\fR.
.SS "Other Options"
.IP "\fB\-\-unixctl=\fIsocket\fR"
Sets the name of the control socket on which \fB\*(PN\fR listens for
runtime management commands (see \fBRUNTIME MANAGEMENT COMMANDS\fR,
below).  If \fIsocket\fR does not begin with \fB/\fR, it is
interpreted as relative to \fB/var/run/openvswitch\fR.  If \fB\-\-unixctl\fR is
not used at all, the default socket is
\fB/var/run/openvswitch/\*(PN.\fIpid\fB.ctl\fR, where \fIpid\fR is \fB\*(PN\fR's
process ID.
Specifying \fBnone\fR for \fIsocket\fR disables the control socket
feature.
.TP
\fB\-h\fR, \fB\-\-help\fR
Prints a brief help message to the console.
.
.TP
\fB\-V\fR, \fB\-\-version\fR
Prints version information to the console.
.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 "OVSDB\-SERVER COMMANDS"
These commands are specific to \fBovsdb\-server\fR.
.IP "\fBexit\fR"
Causes \fBovsdb\-server\fR to gracefully terminate.
.IP "\fBovsdb\-server/compact\fR"
Compacts the database in-place.  The database is also automatically
compacted occasionally.
.
.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.
.
.SS "VLOG COMMANDS"
These commands manage \fB\*(PN\fR's logging settings.
.IP "\fBvlog/set\fR \fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]]"
Sets the logging level for \fImodule\fR in \fIfacility\fR to
\fIlevel\fR:
.
.RS
.IP \(bu
\fImodule\fR may be any valid module name (as displayed by the
\fB\-\-list\fR action on \fBovs\-appctl\fR(8)), or the special name
\fBANY\fR to set the logging levels for all modules.
.
.IP \(bu
\fIfacility\fR may be \fBsyslog\fR, \fBconsole\fR, or \fBfile\fR to
set the levels for logging to the system log, the console, or a file
respectively, or \fBANY\fR to set the logging levels for both
facilities.  If it is omitted, \fIfacility\fR defaults to \fBANY\fR.
.IP
The log level for the \fBfile\fR facility has no effect unless
\fB\*(PN\fR was invoked with the \fB\-\-log\-file\fR option.
.IP \(bu 
\fIlevel\fR must be one of \fBoff\fR, \fBemer\fR, \fBerr\fR, \fBwarn\fR,
\fBinfo\fR, or
\fBdbg\fR, designating the minimum severity of a message for it to be
logged.  If it is omitted, \fIlevel\fR defaults to \fBdbg\fR.
.RE
.IP "\fBvlog/set PATTERN:\fIfacility\fB:\fIpattern\fR"
Sets the log pattern for \fIfacility\fR to \fIpattern\fR.  Refer to
\fBovs\-appctl\fR(8) for a description of the valid syntax for \fIpattern\fR.
.
.IP "\fBvlog/list\fR"
Lists the supported logging modules and their current levels.
.
.IP "\fBvlog/reopen\fR"
Causes \fB\*(PN\fR to close and reopen its log file.  (This is useful
after rotating log files, to cause a new log file to be used.)
.IP
This has no effect unless \fB\*(PN\fR was invoked with the
\fB\-\-log\-file\fR option.
.SS "STRESS OPTION COMMANDS"
These command manage stress options, which allow developers testing
Open vSwitch to trigger behavior that otherwise would occur only in
corner cases.  Developers and testers can thereby more easily discover
bugs that would otherwise manifest only rarely or
nondeterministically.  Stress options may cause surprising behavior
even when they do not actually reveal bugs, so they should only be
enabled as part of testing Open vSwitch.
.
.IP "\fBstress/enable\fR"
.IQ "\fBstress/disable\fR"
All stress options are disabled by default.  Use \fBstress/enable\fR
to enable stress options and \fBstress/disable\fR to disable them.
.
.IP "\fBstress/list\fR"
Lists and describes the available stress options and their settings in
tabular form.  The columns in the table are:
.RS
.IP "NAME"
A single-word identifier for the option, used to identify stress
options to \fBstress/set\fR.
.
.IP "DESCRIPTION"
A description for a person unfamiliar with the detailed internals of
the code what behavior the option affects.
.
.IP "PERIOD"
Currently configured trigger period.  If the stress option is
disabled, this is \fBdisabled\fR.  Otherwise this is a number giving
the number of occurrences of the event between activations of the
stress option triggers.
.
.IP "MODE"
If the stress option is disabled, this is \fBn/a\fR.  Otherwise it is
\fBperiodic\fR if the stress option triggers after exactly the period,
or \fBrandom\fR if it triggers randomly but on average after the
number of occurrences specified by the period.
.
.IP "COUNTER"
If the stress option is disabled, this is \fBn/a\fR.  Otherwise it is
the number of occurrences of the event before the next time the stress
option triggers.
.
.IP "HITS"
The number of times that this stress option has triggered since this
program started.
.
.IP "RECOMMENDED"
A suggested period for a person unfamiliar with the internals.  It
should put reasonable stress on the system without crippling it.
.
.IP "MINIMUM"
.IQ "MAXIMUM"
Minimum and maximum values allowed for the period.
.
.IP "DEFAULT"
The default period, used when stress options have been enabled (with
\fBstress/enable\fR) but this particular stress option has not been
specifically configured (with \fBstress/set\fR).  It is \fBdisabled\fR
if the option is disabled by default.  It is nonzero for options that
can be left on at low levels without noticeable impact to the end user.
.RE
.
.IP "\fBstress/set \fIoption\fR \fIperiod\fR [\fBrandom\fR|\fBperiodic\fR]"
Sets the period at which stress \fIoption\fR triggers to
\fIperiod\fR.  A \fIperiod\fR of 0 disables \fIoption\fR.  Specify
\fBrandom\fR to make the option trigger randomly with an average
period of \fIperiod\fR, or \fBperiodic\fR to trigger exactly every
\fIperiod\fR events; the latter is the default.
.IP
If stress options have not been enabled with \fBstress/enable\fR, this
command has no effect.
.SH "SEE ALSO"
.
.BR ovsdb\-tool (1).