]>
Commit | Line | Data |
---|---|---|
f7f62235 | 1 | .\" -*- nroff -*- |
b421d2af BP |
2 | .de IQ |
3 | . br | |
4 | . ns | |
5 | . IP "\\$1" | |
6 | .. | |
d2cb6c95 | 7 | .TH ovsdb\-server 1 "@VERSION@" "Open vSwitch" "Open vSwitch Manual" |
a946ed39 | 8 | .\" This program's name: |
f7f62235 BP |
9 | .ds PN ovsdb\-server |
10 | . | |
11 | .SH NAME | |
12 | ovsdb\-server \- Open vSwitch database server | |
13 | . | |
14 | .SH SYNOPSIS | |
15 | \fBovsdb\-server\fR | |
b4e8d170 | 16 | [\fIdatabase\fR]\&... |
a946ed39 BP |
17 | [\fB\-\-remote=\fIremote\fR]\&... |
18 | [\fB\-\-run=\fIcommand\fR] | |
19 | .so lib/daemon-syn.man | |
42dd41ef | 20 | .so lib/service-syn.man |
a946ed39 | 21 | .so lib/vlog-syn.man |
812560d7 BP |
22 | .so lib/ssl-syn.man |
23 | .so lib/ssl-bootstrap-syn.man | |
a946ed39 BP |
24 | .so lib/unixctl-syn.man |
25 | .so lib/common-syn.man | |
f7f62235 BP |
26 | . |
27 | .SH DESCRIPTION | |
b4e8d170 BP |
28 | The \fBovsdb\-server\fR program provides RPC interfaces to one or more |
29 | Open vSwitch databases (OVSDBs). It supports JSON-RPC client | |
30 | connections over active or passive TCP/IP or Unix domain sockets. | |
f7f62235 | 31 | .PP |
b4e8d170 BP |
32 | Each OVSDB file may be specified on the command line as \fIdatabase\fR. |
33 | If none is specified, the default is \fB@DBDIR@/conf.db\fR. The database | |
34 | files must already have been created and initialized using, for | |
29701194 | 35 | example, \fBovsdb\-tool create\fR. |
f7f62235 BP |
36 | . |
37 | .SH OPTIONS | |
38 | . | |
0b1fae1b BP |
39 | .IP "\fB\-\-remote=\fIremote\fR" |
40 | Adds \fIremote\fR as a connection method used by \fBovsdb\-server\fR. | |
41 | \fIremote\fR must take one of the following forms: | |
f7f62235 BP |
42 | . |
43 | .RS | |
9467fe62 BP |
44 | .so ovsdb/remote-passive.man |
45 | .so ovsdb/remote-active.man | |
a976b2ec | 46 | . |
fb6de52c | 47 | .IP "\fBdb:\fIdb\fB,\fItable\fB,\fIcolumn\fR" |
a976b2ec | 48 | Reads additional connection methods from \fIcolumn\fR in all of the |
fb6de52c GS |
49 | rows in \fItable\fR within \fIdb\fR. As the contents of \fIcolumn\fR changes, |
50 | \fBovsdb\-server\fR also adds and drops connection methods accordingly. | |
94db5407 BP |
51 | .IP |
52 | If \fIcolumn\fR's type is string or set of strings, then the | |
53 | connection methods are taken directly from the column. The connection | |
54 | methods in the column must have one of the forms described above. | |
55 | .IP | |
56 | If \fIcolumn\fR's type is UUID or set of UUIDs and references a table, | |
57 | then each UUID is looked up in the referenced table to obtain a row. | |
58 | The following columns in the row, if present and of the correct type, | |
59 | configure a connection method. Any additional columns are ignored. | |
60 | .RS | |
61 | .IP "\fBtarget\fR (string)" | |
62 | Connection method, in one of the forms described above. This column | |
63 | is mandatory: if it is missing or empty then no connection method can | |
64 | be configured. | |
65 | .IP "\fBmax_backoff\fR (integer)" | |
66 | Maximum number of milliseconds to wait between connection attempts. | |
b4e8d170 | 67 | .IP "\fBinactivity_probe\fR (integer)" |
94db5407 BP |
68 | Maximum number of milliseconds of idle time on connection to |
69 | client before sending an inactivity probe message. | |
70 | .RE | |
71 | .IP | |
72 | It is an error for \fIcolumn\fR to have another type. | |
f7f62235 BP |
73 | .RE |
74 | . | |
9f33227d BP |
75 | .IP |
76 | To connect or listen on multiple connection methods, use multiple | |
77 | \fB\-\-remote\fR options. | |
78 | . | |
475afa1b BP |
79 | .IP "\fB\-\-run=\fIcommand\fR]" |
80 | Ordinarily \fBovsdb\-server\fR runs forever, or until it is told to | |
81 | exit (see \fBRUNTIME MANAGEMENT COMMANDS\fR below). With this option, | |
82 | \fBovsdb\-server\fR instead starts a shell subprocess running | |
83 | \fIcommand\fR. When the subprocess terminates, \fBovsdb\-server\fR | |
84 | also exits gracefully. If the subprocess exits normally with exit | |
85 | code 0, then \fBovsdb\-server\fR exits with exit code 0 also; | |
86 | otherwise, it exits with exit code 1. | |
87 | .IP | |
88 | This option can be useful where a database server is needed only to | |
89 | run a single command, e.g.: | |
4e312e69 | 90 | .B "ovsdb\-server \-\-remote=punix:socket \-\-run='ovsdb\-client dump unix:socket Open_vSwitch'" |
41064650 GS |
91 | .IP |
92 | This option is not supported on Windows platform. | |
f7f62235 | 93 | .SS "Daemon Options" |
a7ff9bd7 BP |
94 | .ds DD \ |
95 | \fBovsdb\-server\fR detaches only after it starts listening on all \ | |
96 | configured remotes. | |
f7f62235 | 97 | .so lib/daemon.man |
42dd41ef GS |
98 | .SS "Service Options" |
99 | .so lib/service.man | |
f7f62235 BP |
100 | .SS "Logging Options" |
101 | .so lib/vlog.man | |
ac300505 | 102 | .SS "Public Key Infrastructure Options" |
78876719 BP |
103 | The options described below for configuring the SSL public key |
104 | infrastructure accept a special syntax for obtaining their | |
105 | configuration from the database. If any of these options is given | |
fb6de52c | 106 | \fBdb:\fIdb\fB,\fItable\fB,\fIcolumn\fR as its argument, then the |
4206b80f | 107 | actual file name is read from the specified \fIcolumn\fR in \fItable\fR |
fb6de52c | 108 | within the \fIdb\fR database. The \fIcolumn\fR must have type |
4206b80f HM |
109 | string or set of strings. The first nonempty string in the table is taken |
110 | as the file name. (This means that ordinarily there should be at most | |
78876719 | 111 | one row in \fItable\fR.) |
9467fe62 | 112 | .so lib/ssl.man |
a976b2ec | 113 | .so lib/ssl-bootstrap.man |
f7f62235 | 114 | .SS "Other Options" |
7b38bdc8 | 115 | .so lib/unixctl.man |
f7f62235 BP |
116 | .so lib/common.man |
117 | .SH "RUNTIME MANAGEMENT COMMANDS" | |
118 | \fBovs\-appctl\fR(8) can send commands to a running | |
119 | \fBovsdb\-server\fR process. The currently supported commands are | |
120 | described below. | |
4e312e69 | 121 | .SS "OVSDB\-SERVER COMMANDS" |
475afa1b BP |
122 | These commands are specific to \fBovsdb\-server\fR. |
123 | .IP "\fBexit\fR" | |
124 | Causes \fBovsdb\-server\fR to gracefully terminate. | |
b4e8d170 BP |
125 | .IP "\fBovsdb\-server/compact\fR [\fIdb\fR]\&..." |
126 | Compacts each database \fIdb\fR in-place. If no \fIdb\fR is | |
127 | specified, compacts every database in-place. Databases are also | |
128 | automatically compacted occasionally. | |
31d0b6c9 BP |
129 | . |
130 | .IP "\fBovsdb\-server/reconnect\fR" | |
131 | Makes \fBovsdb\-server\fR drop all of the JSON\-RPC | |
132 | connections to database clients and reconnect. | |
133 | .IP | |
134 | This command might be useful for debugging issues with database | |
135 | clients. | |
136 | . | |
b421d2af BP |
137 | .IP "\fBovsdb\-server/add\-remote \fIremote\fR" |
138 | Adds a remote, as if \fB\-\-remote=\fIremote\fR had been specified on | |
139 | the \fBovsdb\-server\fR command line. (If \fIremote\fR is already a | |
140 | remote, this command succeeds without changing the configuration.) | |
141 | . | |
142 | .IP "\fBovsdb\-server/remove\-remote \fIremote\fR" | |
143 | Removes the specified \fIremote\fR from the configuration, failing | |
144 | with an error if \fIremote\fR is not configured as a remote. This | |
145 | command only works with remotes that were named on \fB\-\-remote\fR or | |
146 | \fBovsdb\-server/add\-remote\fR, that is, it will not remove remotes | |
147 | added indirectly because they were read from the database by | |
fb6de52c | 148 | configuring a \fBdb:\fIdb\fB,\fItable\fB,\fIcolumn\fR remote. |
b421d2af | 149 | (You can remove a database source with \fBovsdb\-server/remove\-remote |
fb6de52c | 150 | \fBdb:\fIdb\fB,\fItable\fB,\fIcolumn\fR, but not individual |
b421d2af BP |
151 | remotes found indirectly through the database.) |
152 | . | |
153 | .IP "\fBovsdb\-server/list\-remotes" | |
154 | Outputs a list of the currently configured remotes named on | |
155 | \fB\-\-remote\fR or \fBovsdb\-server/add\-remote\fR, that is, it does | |
156 | not list remotes added indirectly because they were read from the | |
157 | database by configuring a | |
fb6de52c | 158 | \fBdb:\fIdb\fB,\fItable\fB,\fIcolumn\fR remote. |
b421d2af | 159 | . |
0a3b723b BP |
160 | .IP "\fBovsdb\-server/add\-db \fIdatabase\fR" |
161 | Adds the \fIdatabase\fR to the running \fBovsdb\-server\fR. The database | |
162 | file must already have been created and initialized using, for example, | |
163 | \fBovsdb\-tool create\fR. | |
164 | . | |
165 | .IP "\fBovsdb\-server/remove\-db \fIdatabase\fR" | |
166 | Removes \fIdatabase\fR from the running \fBovsdb\-server\fR. \fIdatabase\fR | |
167 | must be a database name as listed by \fBovsdb-server/list\-dbs\fR. | |
168 | .IP | |
169 | If a remote has been configured that points to the specified | |
170 | \fIdatabase\fR (e.g. \fB\-\-remote=db:\fIdatabase\fB,\fR... on the | |
171 | command line), then it will be disabled until another database with | |
172 | the same name is added again (with \fBovsdb\-server/add\-db\fR). | |
173 | .IP | |
174 | Any public key infrastructure options specified through this database | |
175 | (e.g. \fB\-\-private\-key=db:\fIdatabase,\fR... on the command line) | |
176 | will be disabled until another database with the same name is added | |
177 | again (with \fBovsdb\-server/add\-db\fR). | |
178 | . | |
179 | .IP "\fBovsdb\-server/list\-dbs" | |
180 | Outputs a list of the currently configured databases added either through | |
181 | the command line or through the \fBovsdb\-server/add\-db\fR command. | |
182 | . | |
f7f62235 | 183 | .so lib/vlog-unixctl.man |
149ff68a | 184 | .so lib/memory-unixctl.man |
a5f607bc | 185 | .so lib/coverage-unixctl.man |
c70a7767 BP |
186 | .SH "SPECIFICATIONS" |
187 | . | |
188 | .PP | |
189 | \fBovsdb\-server\fR implements the Open vSwitch Database (OVSDB) | |
190 | protocol specified in RFC 7047, with the following clarifications: | |
191 | . | |
192 | .IP "3.1. JSON Usage" | |
193 | RFC 4627 says that names within a JSON object should be unique. | |
194 | The Open vSwitch JSON parser discards all but the last value | |
195 | for a name that is specified more than once. | |
196 | . | |
197 | .IP "3.2. Schema Format" | |
198 | RFC 7047 requires the "version" field in <database-schema>. Current | |
199 | versions of \fBovsdb\-server\fR allow it to be omitted (future | |
200 | versions are likely to require it). | |
201 | . | |
202 | .IP "4. Wire Protocol" | |
203 | The original OVSDB specifications included the following reason, | |
204 | omitted from RFC 7047, to operate JSON-RPC directly over a stream | |
205 | instead of over HTTP: | |
206 | . | |
207 | .RS | |
208 | .IP \(bu | |
209 | JSON-RPC is a peer-to-peer protocol, but HTTP is a client-server | |
210 | protocol, which is a poor match. Thus, JSON-RPC over HTTP requires | |
211 | the client to periodically poll the server to receive server requests. | |
212 | .IP \(bu | |
213 | HTTP is more complicated than stream connections and doesn't provide | |
214 | any corresponding advantage. | |
215 | .IP \(bu | |
216 | The JSON-RPC specification for HTTP transport is incomplete. | |
217 | .RE | |
218 | . | |
219 | .IP "4.1.5. Monitor" | |
220 | For backward compatibility, \fBovsdb\-server\fR currently permits a | |
221 | single <monitor-request> to be used instead of an array; it is treated | |
222 | as a single-element array. Future versions of \fBovsdb\-server\fR | |
223 | might remove this compatibility feature. | |
224 | .IP | |
225 | Because the <json-value> parameter is used to match subsequent update | |
226 | notifications (see below) to the request, it must be unique among all | |
227 | active monitors. \fBovsdb\-server\fR rejects attempt to create two | |
228 | monitors with the same identifier. | |
229 | . | |
230 | .IP "6. IANA Considerations" | |
231 | \fBovsdb\-server\fR currently defaults to its historical port number | |
232 | 6632. Future versions will adopt IANA-assigned port 6640 as default. | |
233 | ||
f7f62235 BP |
234 | .SH "SEE ALSO" |
235 | . | |
236 | .BR ovsdb\-tool (1). |