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
--private-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:
- •
- 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.
- •
- facility may be syslog, console, or
file to set the levels for logging to the system log, the console,
or a file respectively, 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).
- •
- 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 different 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:
- •
- 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.
- •
- facility may be syslog, console, or
file to set the levels for logging to the system log, the console,
or a file respectively, 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.
- •
- 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 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.
- 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 crippling
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 trigger 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).