X-Git-Url: http://git.cascardo.eti.br/?a=blobdiff_plain;f=ovsdb%2Fovsdb-server.1.in;h=6c857294c675a23a4df8bf6f3537d2505294468c;hb=600766e877efa2713b9c87d127f7190d8ab48da9;hp=4c6ceddde3c71989e67db04fb21f8abd9eca9bfc;hpb=c69ee87c10818267f991236201150b1fa51ae519;p=cascardo%2Fovs.git diff --git a/ovsdb/ovsdb-server.1.in b/ovsdb/ovsdb-server.1.in index 4c6ceddde..6c857294c 100644 --- a/ovsdb/ovsdb-server.1.in +++ b/ovsdb/ovsdb-server.1.in @@ -1,5 +1,11 @@ .\" -*- 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 @@ -7,20 +13,27 @@ ovsdb\-server \- Open vSwitch database server . .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 . @@ -31,20 +44,327 @@ Adds \fIremote\fR as a connection method used by \fBovsdb\-server\fR. .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 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 . 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 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 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 , 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 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": [, ] +"id": null +.fi +.RE +. +.IP +The in "params" is the same as the value passed as the + in "params" for the corresponding "monitor" request. + is an object that maps from a table name to a . +A is an object that maps from row's UUID to a object. A is an object with one of the following members: +. +.RS +.IP "\(dqinitial\(dq: " +present for "initial" updates +.IP "\(dqinsert\(dq: " +present for "insert" updates +.IP "\(dqdelete\(dq: " +present for "delete" updates +.IP "\(dqmodify\(dq: " +present for "modify" updates +.RE +. +.IP +The format of is described in Section 5.1. +. +.IP + is always a null object for a "delete" update. In "initial" and +"insert" updates, omits columns whose values equal the default +value of the column type. +. +.IP +For a "modify" update, contains only the columns that are modified. + 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, 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 + object, however, is the same in either case. +. +.IP "5.1. Notation" +For , 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 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).