ovsdb-server(1) Open vSwitch Manual ovsdb-server(1)
NAME
ovsdb-server - Open vSwitch database server
SYNOPSIS
ovsdb-server [database] [--remote=remote]... [--run=command]
Daemon options:
[--pidfile[=pidfile]] [--overwrite-pidfile] [--detach] [--no-chdir]
Logging options:
[-v[module[:facility[:level]]]]...
[--verbose[=module[:facility[:level]]]]...
[--log-file[=file]]
Public key infrastructure options:
[--private-key=privkey.pem]
[--certificate=cert.pem]
[--ca-cert=cacert.pem]
[--bootstrap-ca-cert=cacert.pem]
Runtime management options:
--unixctl=socket
Common options:
[-h | --help] [-V | --version]
DESCRIPTION
The ovsdb-server 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.
The OVSDB file may be specified on the command line as database. The default is /var/lib/openvswitch/conf.db. The database file must
already have been created and initialized using, for example, ovsdb-tool create.
OPTIONS
--remote=remote
Adds remote as a connection method used by ovsdb-server. remote must take one of the following forms:
pssl:port[:ip]
Listen on the given SSL port for a connection. By default, ovsdb-server listens for connections to any local IP address, but
specifying ip limits connections to those from the given ip. The --private-key, --certificate, and --ca-cert options are
mandatory when this form is used.
ptcp:port[:ip]
Listen on the given TCP port for a connection. By default, ovsdb-server listens for connections to any local IP address, but
ip may be specified to listen only for connections to the given ip.
punix:file
Listen on the Unix domain server socket named file for a connection.
ssl:ip:port
The specified SSL port on the host at the given ip, which must be expressed as an IP address (not a DNS name). The --pri-
vate-key, --certificate, and --ca-cert options are mandatory when this form is used.
tcp:ip:port
Connect to the given TCP port on ip.
unix:file
Connect to the Unix domain server socket named file.
db:table,column
Reads additional connection methods from column in all of the rows in table. As the contents of column changes, ovsdb-server
also adds and drops connection methods accordingly.
If column'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.
If column'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.
target (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.
max_backoff (integer)
Maximum number of milliseconds to wait between connection attempts.
inactivity_probe (integer)
Maximum number of milliseconds of idle time on connection to client before sending an inactivity probe message.
It is an error for column to have another type.
--run=command]
Ordinarily ovsdb-server runs forever, or until it is told to exit (see RUNTIME MANAGEMENT COMMANDS below). With this option,
ovsdb-server instead starts a shell subprocess running command. When the subprocess terminates, ovsdb-server also exits gracefully.
If the subprocess exits normally with exit code 0, then ovsdb-server exits with exit code 0 also; otherwise, it exits with exit code
1.
This option can be useful where a database server is needed only to run a single command, e.g.: ovsdb-server --remote=punix:socket
--run='ovsdb-client dump unix:socket Open_vSwitch'
Daemon Options
--pidfile[=pidfile]
Causes a file (by default, ovsdb-server.pid) to be created indicating the PID of the running process. If the pidfile argument is
not specified, or if it does not begin with /, then it is created in /var/run/openvswitch.
If --pidfile is not specified, no pidfile is created.
--overwrite-pidfile
By default, when --pidfile is specified and the specified pidfile already exists and is locked by a running process, ovsdb-server
refuses to start. Specify --overwrite-pidfile to cause it to instead overwrite the pidfile.
When --pidfile is not specified, this option has no effect.
--detach
Causes ovsdb-server to detach itself from the foreground session and run as a background process. ovsdb-server detaches only after
it starts listening on all configured remotes.
--monitor
Creates an additional process to monitor the ovsdb-server daemon. If the daemon dies due to a signal that indicates a programming
error (e.g. SIGSEGV, SIGABRT), then the monitor process starts a new copy of it. If the daemon die or exits for another reason, the
monitor process exits.
This option is normally used with --detach, but it also functions without it.
--no-chdir
By default, when --detach is specified, ovsdb-server changes its current working directory to the root directory after it detaches.
Otherwise, invoking ovsdb-server from a carelessly chosen directory would prevent the administrator from unmounting the file system
that holds that directory.
Specifying --no-chdir suppresses this behavior, preventing ovsdb-server 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.
This option has no effect when --detach is not specified.
Logging Options
-vmodule[:facility[:level]], --verbose=module[:facility[:level]]
Sets the logging level for module in facility to level:
o module may be any valid module name (as displayed by the --list action on ovs-appctl(8)), or the special name ANY to set the
logging levels for all modules.
o facility may be syslog, console, or file to set the levels for logging to the system log, the console, or a file respec-
tively, or ANY to set the logging levels for both facilities. If it is omitted, facility defaults to ANY.
Regardless of the log levels set for file, logging to a file will not take place unless --log-file is also specified (see
below).
o level must be one of off, emer, err, warn, info, or dbg, designating the minimum severity of a message for it to be logged.
If it is omitted, level defaults to dbg. See ovs-appctl(8) for a definition of each log level.
-v, --verbose
Sets the maximum logging verbosity level, equivalent to --verbose=ANY:ANY:dbg.
-vPATTERN:facility:pattern, --verbose=PATTERN:facility:pattern
Sets the log pattern for facility to pattern. Refer to ovs-appctl(8) for a description of the valid syntax for pattern.
--log-file[=file]
Enables logging to a file. If file is specified, then it is used as the exact name for the log file. The default log file name
used if file is omitted is /var/log/openvswitch/ovsdb-server.log.
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 db:table,column as its argument, then the actual file name is read from the specified
column in table within the ovsdb-server database. The column 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 table.)
-p privkey.pem
--private-key=privkey.pem
Specifies a PEM file containing the private key used as ovsdb-server's identity for outgoing SSL connections.
-c cert.pem
--certificate=cert.pem
Specifies a PEM file containing a certificate that certifies the private key specified on -p or --private-key to be trustworthy.
The certificate must be signed by the certificate authority (CA) that the peer in SSL connections will use to verify it.
-C cacert.pem
--ca-cert=cacert.pem
Specifies a PEM file containing the CA certificate that ovsdb-server 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 -c or --certificate, or it may be a dif-
ferent one, depending on the PKI design in use.)
-C none
--ca-cert=none
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.
--bootstrap-ca-cert=cacert.pem
When cacert.pem exists, this option has the same effect as -C or --ca-cert. If it does not exist, then ovsdb-server 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.
This option exposes the SSL connection to a man-in-the-middle attack obtaining the initial CA certificate, but it may be useful for
bootstrapping.
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 ovsdb-client(8) can be configured to do so with the --peer-ca-cert option.
This option is mutually exclusive with -C and --ca-cert.
Other Options
--unixctl=socket
Sets the name of the control socket on which ovsdb-server listens for runtime management commands (see RUNTIME MANAGEMENT COMMANDS,
below). If socket does not begin with /, it is interpreted as relative to /var/run/openvswitch. If --unixctl is not used at all,
the default socket is /var/run/openvswitch/ovsdb-server.pid.ctl, where pid is ovsdb-server's process ID. Specifying none for socket
disables the control socket feature.
-h, --help
Prints a brief help message to the console.
-V, --version
Prints version information to the console.
RUNTIME MANAGEMENT COMMANDS
ovs-appctl(8) can send commands to a running ovsdb-server process. The currently supported commands are described below.
OVSDB-SERVER COMMANDS
These commands are specific to ovsdb-server.
exit Causes ovsdb-server to gracefully terminate.
ovsdb-server/compact
Compacts the database in-place. The database is also automatically compacted occasionally.
ovsdb-server/reconnect
Makes ovsdb-server drop all of the JSON-RPC connections to database clients and reconnect.
This command might be useful for debugging issues with database clients.
VLOG COMMANDS
These commands manage ovsdb-server's logging settings.
vlog/set module[:facility[:level]]
Sets the logging level for module in facility to level:
o module may be any valid module name (as displayed by the --list action on ovs-appctl(8)), or the special name ANY to set the
logging levels for all modules.
o facility may be syslog, console, or file to set the levels for logging to the system log, the console, or a file respec-
tively, or ANY to set the logging levels for both facilities. If it is omitted, facility defaults to ANY.
The log level for the file facility has no effect unless ovsdb-server was invoked with the --log-file option.
o level must be one of off, emer, err, warn, info, or dbg, designating the minimum severity of a message for it to be logged.
If it is omitted, level defaults to dbg.
vlog/set PATTERN:facility:pattern
Sets the log pattern for facility to pattern. Refer to ovs-appctl(8) for a description of the valid syntax for pattern.
vlog/list
Lists the supported logging modules and their current levels.
vlog/reopen
Causes ovsdb-server to close and reopen its log file. (This is useful after rotating log files, to cause a new log file to be
used.)
This has no effect unless ovsdb-server was invoked with the --log-file option.
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 nondeterministi-
cally. 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.
stress/enable
stress/disable
All stress options are disabled by default. Use stress/enable to enable stress options and stress/disable to disable them.
stress/list
Lists and describes the available stress options and their settings in tabular form. The columns in the table are:
NAME A single-word identifier for the option, used to identify stress options to stress/set.
DESCRIPTION
A description for a person unfamiliar with the detailed internals of the code what behavior the option affects.
PERIOD Currently configured trigger period. If the stress option is disabled, this is disabled. Otherwise this is a number giving
the number of occurrences of the event between activations of the stress option triggers.
MODE If the stress option is disabled, this is n/a. Otherwise it is periodic if the stress option triggers after exactly the
period, or random if it triggers randomly but on average after the number of occurrences specified by the period.
COUNTER
If the stress option is disabled, this is n/a. Otherwise it is the number of occurrences of the event before the next time
the stress option triggers.
HITS The number of times that this stress option has triggered since this program started.
RECOMMENDED
A suggested period for a person unfamiliar with the internals. It should put reasonable stress on the system without crip-
pling it.
MINIMUM
MAXIMUM
Minimum and maximum values allowed for the period.
DEFAULT
The default period, used when stress options have been enabled (with stress/enable) but this particular stress option has not
been specifically configured (with stress/set). It is disabled 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.
stress/set option period [random|periodic]
Sets the period at which stress option triggers to period. A period of 0 disables option. Specify random to make the option trig-
ger randomly with an average period of period, or periodic to trigger exactly every period events; the latter is the default.
If stress options have not been enabled with stress/enable, this command has no effect.
SEE ALSO
ovsdb-tool(1).
Open vSwitch November 2009 ovsdb-server(1)