.\" -*- nroff -*-
-.TH ovsdb\-server 1 "November 2009" "Open vSwitch" "Open vSwitch Manual"
+.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
.
.SH SYNOPSIS
\fBovsdb\-server\fR
-\fIdatabase\fR
-[\fB--remote=\fIremote\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
+.so lib/ssl-syn.man
+.so lib/ssl-bootstrap-syn.man
+.so lib/ssl-peer-ca-cert-syn.man
+.so lib/unixctl-syn.man
.so lib/common-syn.man
.
.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.
+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.
.PP
-The name of the OVSDB file must be specified on the command line as
-\fIdatabase\fR, which must already have been created and initialized
-using, for example, \fBovsdb\-tool create\fR.
+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.
.
.SH OPTIONS
.
.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,
+\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
+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 "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 "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 "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 [\fIdb\fR]\&..."
+Compacts each database \fIdb\fR in-place. If no \fIdb\fR is
+specified, compacts every database in-place. Databases are 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.
+.
+.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.
+.
.so lib/vlog-unixctl.man
+.so lib/memory-unixctl.man
+.so lib/coverage-unixctl.man
+.SH "SPECIFICATIONS"
+.
+.PP
+\fBovsdb\-server\fR implements the Open vSwitch Database (OVSDB)
+protocol specified in RFC 7047, with the following clarifications:
+.
+.IP "3.1. JSON Usage"
+RFC 4627 says that names within a JSON object should be unique.
+The Open vSwitch JSON parser discards all but the last value
+for a name that is specified more than once.
+.
+.IP
+The definition of <error> allows for implementation extensions.
+Currently \fBovsdb\-server\fR uses the following additional "error"
+strings which might change in later releases):
+.
+.RS
+.IP "\fBsyntax error\fR or \fBunknown column\fR"
+The request could not be parsed as an OVSDB request. An additional
+"syntax" member, whose value is a string that contains JSON, may
+narrow down the particular syntax that could not be parsed.
+.IP "\fBinternal error\fR"
+The request triggered a bug in \fBovsdb\-server\fR.
+.IP "\fBovsdb error\fR"
+A map or set contains a duplicate key.
+.RE
+.
+.IP "3.2. Schema Format"
+RFC 7047 requires the "version" field in <database-schema>. Current
+versions of \fBovsdb\-server\fR allow it to be omitted (future
+versions are likely to require it).
+.
+.IP "4. Wire Protocol"
+The original OVSDB specifications included the following reason,
+omitted from RFC 7047, to operate JSON-RPC directly over a stream
+instead of over HTTP:
+.
+.RS
+.IP \(bu
+JSON-RPC is a peer-to-peer protocol, but HTTP is a client-server
+protocol, which is a poor match. Thus, JSON-RPC over HTTP requires
+the client to periodically poll the server to receive server requests.
+.IP \(bu
+HTTP is more complicated than stream connections and doesn't provide
+any corresponding advantage.
+.IP \(bu
+The JSON-RPC specification for HTTP transport is incomplete.
+.RE
+.
+.IP "4.1.5. Monitor"
+For backward compatibility, \fBovsdb\-server\fR currently permits a
+single <monitor-request> to be used instead of an array; it is treated
+as a single-element array. Future versions of \fBovsdb\-server\fR
+might remove this compatibility feature.
+.IP
+Because the <json-value> parameter is used to match subsequent update
+notifications (see below) to the request, it must be unique among all
+active monitors. \fBovsdb\-server\fR rejects attempt to create two
+monitors with the same identifier.
+.
+.IP "4.1.12. Monitor2"
+A new monitor method added in Open vSwitch version 2.5. Monitor2 allows
+for more efficient update notifications (described below).
+.IP
+The monitor method described in Section 4.1.5 also applies to
+monitor2, with the following exceptions.
+.
+.RS
+.IP \(bu
+RPC request method becomes "monitor2".
+.IP \(bu
+Replay result follows <table-updates2>, described in Section 4.1.13.
+.IP \(bu
+Subsequent changes are sent to the client using the "update2" monitor
+notification, described in Section 4.1.13
+.RE
+.
+.IP
+Both monitor and monitor2 sessions can exist concurrently. However,
+monitor and monitor2 shares the same <json-value> parameter space; it
+must be unique among all monitor and monitor2 sessions.
+.
+.IP "4.1.13. Update2 notification"
+The "update2" notification is sent by the server to the client to report
+changes in tables that are being monitored following a "monitor2" request
+as described above. The notification has the following members:
+.
+.RS
+.nf
+"method": "update2"
+"params": [<json-value>, <table-updates2>]
+"id": null
+.fi
+.RE
+.
+.IP
+The <json-value> in "params" is the same as the value passed as the
+<json-value> in "params" for the corresponding "monitor" request.
+<table-updates2> is an object that maps from a table name to a <table-update2>.
+A <table-update2> is an object that maps from row's UUID to a <row-update2> object. A <row-update2> is an object with one of the following members:
+.
+.RS
+.IP "\(dqinitial\(dq: <row>"
+present for "initial" updates
+.IP "\(dqinsert\(dq: <row>"
+present for "insert" updates
+.IP "\(dqdelete\(dq: <row>"
+present for "delete" updates
+.IP "\(dqmodify\(dq: <row>"
+present for "modify" updates
+.RE
+.
+.IP
+The format of <row> is described in Section 5.1.
+.
+.IP
+<row> is always a null object for a "delete" update. In "initial" and
+"insert" updates, <row> omits columns whose values equal the default
+value of the column type.
+.
+.IP
+For a "modify" update, <row> contains only the columns that are modified.
+<row> stores the difference between the old and new value for those columns,
+as described below.
+.
+.IP
+For columns with single value, the difference is the value of the new
+column.
+.
+.IP
+The difference between two sets are all elements that only belong
+to one of the sets.
+.
+.IP
+The difference between two maps are all key-value pairs whose keys
+appears in only one of the maps, plus the key-value pairs whose keys
+appear in both maps but with different values. For the latter
+elements, <row> includes the value from the new column.
+.
+.IP
+Initial views of rows are not presented in update2 notifications,
+but in the response object to the monitor2 request. The formatting of the
+<table-updates2> object, however, is the same in either case.
+.
+.IP "5.1. Notation"
+For <condition>, RFC 7047 only allows the use of \fB!=\fR, \fB==\fR,
+\fBincludes\fR, and \fBexcludes\fR operators with set types. Open
+vSwitch 2.4 and later extend <condition> to allow the use of \fB<\fR,
+\fB<=\fR, \fB>=\fR, and \fB>\fR operators with columns with type ``set
+of 0 or 1 integer'' and ``set of 0 or 1 real''. These conditions
+evaluate to false when the column is empty, and otherwise as described
+in RFC 7047 for integer and real types.
+.
+.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"
.
.BR ovsdb\-tool (1).
projects / cascardo / ovs.git / blobdiff