X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=ovsdb%2Fovsdb-server.1.in;h=15382b486a48b7c714f552d7f392c50575a9ef7c;hb=c5cf10598f8c9f4428291e9df3ecd72a05fb1ccf;hp=17c955e37336d0e78c86afe39f9bf808932d8942;hpb=5f55c39b21e69025045437ffbd3bb98fe6ce2e89;p=sliver-openvswitch.git diff --git a/ovsdb/ovsdb-server.1.in b/ovsdb/ovsdb-server.1.in index 17c955e37..15382b486 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,21 +13,26 @@ ovsdb\-server \- Open vSwitch database server . .SH SYNOPSIS \fBovsdb\-server\fR -\fIdatabase\fR -[\fB--remote=\fIremote\fR]\&... -[\fB--run=\fIcommand\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/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 . @@ -32,7 +43,38 @@ 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 @@ -45,23 +87,150 @@ 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'" +.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 .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" +.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 "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).