X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=ovsdb%2Fovsdb-server.1.in;h=15382b486a48b7c714f552d7f392c50575a9ef7c;hb=HEAD;hp=a89f091959e721d46622f44ce8b332e770ba2162;hpb=cc01d0bb79103a01aa0afc3484249fd518b877ea;p=sliver-openvswitch.git diff --git a/ovsdb/ovsdb-server.1.in b/ovsdb/ovsdb-server.1.in index a89f09195..15382b486 100644 --- a/ovsdb/ovsdb-server.1.in +++ b/ovsdb/ovsdb-server.1.in @@ -1,19 +1,23 @@ .\" -*- 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 -.\" SSL peer program's name: -.ds SN ovsdb\-client . .SH NAME ovsdb\-server \- Open vSwitch database server . .SH SYNOPSIS \fBovsdb\-server\fR -\fIdatabase\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 @@ -21,13 +25,14 @@ ovsdb\-server \- Open vSwitch database server .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 . @@ -39,11 +44,10 @@ Adds \fIremote\fR as a connection method used by \fBovsdb\-server\fR. .so ovsdb/remote-passive.man .so ovsdb/remote-active.man . -.IP "\fBdb:\fItable\fB,\fIcolumn\fR" +.IP "\fBdb:\fIdb\fB,\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. +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 @@ -60,7 +64,7 @@ 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) +.IP "\fBinactivity_probe\fR (integer)" Maximum number of milliseconds of idle time on connection to client before sending an inactivity probe message. .RE @@ -68,6 +72,10 @@ client before sending an inactivity probe message. 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, @@ -80,19 +88,26 @@ 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.: .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:\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 +\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 @@ -107,9 +122,10 @@ described below. 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/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 @@ -118,8 +134,103 @@ connections to database clients and reconnect. 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/stress-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 "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 "6. IANA Considerations" +\fBovsdb\-server\fR currently defaults to its historical port number +6632. Future versions will adopt IANA-assigned port 6640 as default. + .SH "SEE ALSO" . .BR ovsdb\-tool (1).