]>
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 |
ae671c5f | 22 | .so ovsdb/replication-syn.man |
812560d7 BP |
23 | .so lib/ssl-syn.man |
24 | .so lib/ssl-bootstrap-syn.man | |
5bf6cbd6 | 25 | .so lib/ssl-peer-ca-cert-syn.man |
e18a1d08 | 26 | .so lib/ssl-connect-syn.man |
a946ed39 BP |
27 | .so lib/unixctl-syn.man |
28 | .so lib/common-syn.man | |
f7f62235 BP |
29 | . |
30 | .SH DESCRIPTION | |
b4e8d170 BP |
31 | The \fBovsdb\-server\fR program provides RPC interfaces to one or more |
32 | Open vSwitch databases (OVSDBs). It supports JSON-RPC client | |
33 | connections over active or passive TCP/IP or Unix domain sockets. | |
f7f62235 | 34 | .PP |
b4e8d170 BP |
35 | Each OVSDB file may be specified on the command line as \fIdatabase\fR. |
36 | If none is specified, the default is \fB@DBDIR@/conf.db\fR. The database | |
37 | files must already have been created and initialized using, for | |
29701194 | 38 | example, \fBovsdb\-tool create\fR. |
f7f62235 | 39 | . |
60e0cd04 | 40 | .SH "ACTIVE and BACKUP" |
e51879e9 AZ |
41 | \fBovsdb\-server\fR runs either as a backup server, or as an active server. |
42 | When \fBovsdb\-server\fR is running as a backup server, all transactions that | |
43 | can modify the database content, including the lock commands are rejected. | |
44 | Active server, on the other hand, accepts all ovsdb server transactions. | |
45 | When \fBovsdb\-server\fR role changes, all existing client connection are | |
46 | reset, requiring clients to reconnect to the server. | |
47 | .PP | |
48 | By default, \fBovsdb\-server\fR runs as an active server, except when the | |
60e0cd04 AZ |
49 | \fB\-\-sync\-from=\fIserver\fR command line option is specified and without |
50 | the \fB\-\-no\-sync option\fR. During runtime, \fBovsdb\-server\fR role can be switch by using appctl commands. | |
e51879e9 AZ |
51 | .PP |
52 | \fBovsdb-server/connect\-active\-ovsdb\-server\fR switches | |
60e0cd04 AZ |
53 | \fBovsdb\-server\fR into a backup server, Conversely, |
54 | \fBovsdb-server/disconnect\-active\-ovsdb\-server\fR switches server into | |
e51879e9 AZ |
55 | an active one. |
56 | . | |
f7f62235 BP |
57 | .SH OPTIONS |
58 | . | |
0b1fae1b BP |
59 | .IP "\fB\-\-remote=\fIremote\fR" |
60 | Adds \fIremote\fR as a connection method used by \fBovsdb\-server\fR. | |
61 | \fIremote\fR must take one of the following forms: | |
f7f62235 BP |
62 | . |
63 | .RS | |
9467fe62 BP |
64 | .so ovsdb/remote-passive.man |
65 | .so ovsdb/remote-active.man | |
a976b2ec | 66 | . |
fb6de52c | 67 | .IP "\fBdb:\fIdb\fB,\fItable\fB,\fIcolumn\fR" |
a976b2ec | 68 | Reads additional connection methods from \fIcolumn\fR in all of the |
fb6de52c GS |
69 | rows in \fItable\fR within \fIdb\fR. As the contents of \fIcolumn\fR changes, |
70 | \fBovsdb\-server\fR also adds and drops connection methods accordingly. | |
94db5407 BP |
71 | .IP |
72 | If \fIcolumn\fR's type is string or set of strings, then the | |
73 | connection methods are taken directly from the column. The connection | |
74 | methods in the column must have one of the forms described above. | |
75 | .IP | |
76 | If \fIcolumn\fR's type is UUID or set of UUIDs and references a table, | |
77 | then each UUID is looked up in the referenced table to obtain a row. | |
78 | The following columns in the row, if present and of the correct type, | |
79 | configure a connection method. Any additional columns are ignored. | |
80 | .RS | |
81 | .IP "\fBtarget\fR (string)" | |
82 | Connection method, in one of the forms described above. This column | |
83 | is mandatory: if it is missing or empty then no connection method can | |
84 | be configured. | |
85 | .IP "\fBmax_backoff\fR (integer)" | |
86 | Maximum number of milliseconds to wait between connection attempts. | |
b4e8d170 | 87 | .IP "\fBinactivity_probe\fR (integer)" |
94db5407 BP |
88 | Maximum number of milliseconds of idle time on connection to |
89 | client before sending an inactivity probe message. | |
9c1a1182 LR |
90 | .IP "\fBread_only\fR (boolean)" |
91 | If true, only read-only transactions are allowed on this connection. | |
94db5407 BP |
92 | .RE |
93 | .IP | |
94 | It is an error for \fIcolumn\fR to have another type. | |
f7f62235 BP |
95 | .RE |
96 | . | |
9f33227d BP |
97 | .IP |
98 | To connect or listen on multiple connection methods, use multiple | |
99 | \fB\-\-remote\fR options. | |
100 | . | |
475afa1b BP |
101 | .IP "\fB\-\-run=\fIcommand\fR]" |
102 | Ordinarily \fBovsdb\-server\fR runs forever, or until it is told to | |
103 | exit (see \fBRUNTIME MANAGEMENT COMMANDS\fR below). With this option, | |
104 | \fBovsdb\-server\fR instead starts a shell subprocess running | |
105 | \fIcommand\fR. When the subprocess terminates, \fBovsdb\-server\fR | |
106 | also exits gracefully. If the subprocess exits normally with exit | |
107 | code 0, then \fBovsdb\-server\fR exits with exit code 0 also; | |
108 | otherwise, it exits with exit code 1. | |
109 | .IP | |
110 | This option can be useful where a database server is needed only to | |
111 | run a single command, e.g.: | |
4e312e69 | 112 | .B "ovsdb\-server \-\-remote=punix:socket \-\-run='ovsdb\-client dump unix:socket Open_vSwitch'" |
41064650 GS |
113 | .IP |
114 | This option is not supported on Windows platform. | |
f7f62235 | 115 | .SS "Daemon Options" |
a7ff9bd7 BP |
116 | .ds DD \ |
117 | \fBovsdb\-server\fR detaches only after it starts listening on all \ | |
118 | configured remotes. | |
f7f62235 | 119 | .so lib/daemon.man |
42dd41ef GS |
120 | .SS "Service Options" |
121 | .so lib/service.man | |
f7f62235 BP |
122 | .SS "Logging Options" |
123 | .so lib/vlog.man | |
ae671c5f MC |
124 | .SS "Syncing Options" |
125 | .so ovsdb/replication.man | |
ac300505 | 126 | .SS "Public Key Infrastructure Options" |
78876719 BP |
127 | The options described below for configuring the SSL public key |
128 | infrastructure accept a special syntax for obtaining their | |
129 | configuration from the database. If any of these options is given | |
fb6de52c | 130 | \fBdb:\fIdb\fB,\fItable\fB,\fIcolumn\fR as its argument, then the |
4206b80f | 131 | actual file name is read from the specified \fIcolumn\fR in \fItable\fR |
fb6de52c | 132 | within the \fIdb\fR database. The \fIcolumn\fR must have type |
4206b80f HM |
133 | string or set of strings. The first nonempty string in the table is taken |
134 | as the file name. (This means that ordinarily there should be at most | |
78876719 | 135 | one row in \fItable\fR.) |
9467fe62 | 136 | .so lib/ssl.man |
a976b2ec | 137 | .so lib/ssl-bootstrap.man |
5bf6cbd6 | 138 | .so lib/ssl-peer-ca-cert.man |
e18a1d08 ER |
139 | .SS "SSL Connection Options" |
140 | .so lib/ssl-connect.man | |
f7f62235 | 141 | .SS "Other Options" |
7b38bdc8 | 142 | .so lib/unixctl.man |
f7f62235 BP |
143 | .so lib/common.man |
144 | .SH "RUNTIME MANAGEMENT COMMANDS" | |
145 | \fBovs\-appctl\fR(8) can send commands to a running | |
146 | \fBovsdb\-server\fR process. The currently supported commands are | |
147 | described below. | |
4e312e69 | 148 | .SS "OVSDB\-SERVER COMMANDS" |
475afa1b BP |
149 | These commands are specific to \fBovsdb\-server\fR. |
150 | .IP "\fBexit\fR" | |
151 | Causes \fBovsdb\-server\fR to gracefully terminate. | |
b4e8d170 BP |
152 | .IP "\fBovsdb\-server/compact\fR [\fIdb\fR]\&..." |
153 | Compacts each database \fIdb\fR in-place. If no \fIdb\fR is | |
448b2003 BP |
154 | specified, compacts every database in-place. A database is also |
155 | compacted automatically when a transaction is logged if it is over 4 | |
156 | times as large as its previous compacted size (and at least 10 MB), | |
157 | but not before 100 commits have been added or 10 minutes have elapsed | |
158 | since the last compaction. | |
31d0b6c9 BP |
159 | . |
160 | .IP "\fBovsdb\-server/reconnect\fR" | |
161 | Makes \fBovsdb\-server\fR drop all of the JSON\-RPC | |
162 | connections to database clients and reconnect. | |
163 | .IP | |
164 | This command might be useful for debugging issues with database | |
165 | clients. | |
166 | . | |
b421d2af BP |
167 | .IP "\fBovsdb\-server/add\-remote \fIremote\fR" |
168 | Adds a remote, as if \fB\-\-remote=\fIremote\fR had been specified on | |
169 | the \fBovsdb\-server\fR command line. (If \fIremote\fR is already a | |
170 | remote, this command succeeds without changing the configuration.) | |
171 | . | |
172 | .IP "\fBovsdb\-server/remove\-remote \fIremote\fR" | |
173 | Removes the specified \fIremote\fR from the configuration, failing | |
174 | with an error if \fIremote\fR is not configured as a remote. This | |
175 | command only works with remotes that were named on \fB\-\-remote\fR or | |
176 | \fBovsdb\-server/add\-remote\fR, that is, it will not remove remotes | |
177 | added indirectly because they were read from the database by | |
fb6de52c | 178 | configuring a \fBdb:\fIdb\fB,\fItable\fB,\fIcolumn\fR remote. |
b421d2af | 179 | (You can remove a database source with \fBovsdb\-server/remove\-remote |
fb6de52c | 180 | \fBdb:\fIdb\fB,\fItable\fB,\fIcolumn\fR, but not individual |
b421d2af BP |
181 | remotes found indirectly through the database.) |
182 | . | |
183 | .IP "\fBovsdb\-server/list\-remotes" | |
184 | Outputs a list of the currently configured remotes named on | |
185 | \fB\-\-remote\fR or \fBovsdb\-server/add\-remote\fR, that is, it does | |
186 | not list remotes added indirectly because they were read from the | |
187 | database by configuring a | |
fb6de52c | 188 | \fBdb:\fIdb\fB,\fItable\fB,\fIcolumn\fR remote. |
b421d2af | 189 | . |
0a3b723b BP |
190 | .IP "\fBovsdb\-server/add\-db \fIdatabase\fR" |
191 | Adds the \fIdatabase\fR to the running \fBovsdb\-server\fR. The database | |
192 | file must already have been created and initialized using, for example, | |
193 | \fBovsdb\-tool create\fR. | |
194 | . | |
195 | .IP "\fBovsdb\-server/remove\-db \fIdatabase\fR" | |
196 | Removes \fIdatabase\fR from the running \fBovsdb\-server\fR. \fIdatabase\fR | |
197 | must be a database name as listed by \fBovsdb-server/list\-dbs\fR. | |
198 | .IP | |
199 | If a remote has been configured that points to the specified | |
200 | \fIdatabase\fR (e.g. \fB\-\-remote=db:\fIdatabase\fB,\fR... on the | |
201 | command line), then it will be disabled until another database with | |
202 | the same name is added again (with \fBovsdb\-server/add\-db\fR). | |
203 | .IP | |
204 | Any public key infrastructure options specified through this database | |
205 | (e.g. \fB\-\-private\-key=db:\fIdatabase,\fR... on the command line) | |
206 | will be disabled until another database with the same name is added | |
207 | again (with \fBovsdb\-server/add\-db\fR). | |
208 | . | |
209 | .IP "\fBovsdb\-server/list\-dbs" | |
210 | Outputs a list of the currently configured databases added either through | |
211 | the command line or through the \fBovsdb\-server/add\-db\fR command. | |
212 | . | |
f53d7518 AZ |
213 | .IP "\fBovsdb\-server/set\-active\-ovsdb\-server \fIserver" |
214 | Sets the active \fIserver\fR from which \fBovsdb\-server\fR connects through | |
215 | \fBovsdb\-server/connect\-active\-ovsdb\-server\fR. | |
9dc05cdc | 216 | . |
f53d7518 AZ |
217 | .IP "\fBovsdb\-server/get\-active\-ovsdb\-server" |
218 | Gets the active server from which \fBovsdb\-server\fR is currently synchronizing | |
9dc05cdc MC |
219 | its databases. |
220 | . | |
f53d7518 | 221 | .IP "\fBovsdb\-server/connect\-active\-ovsdb\-server" |
9dc05cdc | 222 | Causes \fBovsdb\-server\fR to synchronize its databases with the server |
f53d7518 | 223 | specified by \fBovsdb\-server/set\-active\-ovsdb\-server\fR. |
9dc05cdc | 224 | . |
f53d7518 AZ |
225 | .IP "\fBovsdb\-server/disconnect\-active\-ovsdb\-server" |
226 | Causes \fBovsdb\-server\fR to stop synchronizing its databases with a active server. | |
9dc05cdc | 227 | . |
60e0cd04 | 228 | .IP "\fBovsdb\-server/set\-sync\-exclude\-tables \fIdb\fB:\fItable\fR[\fB,\fIdb\fB:\fItable\fR]..." |
9dc05cdc MC |
229 | Sets the \fItable\fR whitin \fIdb\fR that will be excluded from synchronization. |
230 | . | |
60e0cd04 | 231 | .IP "\fBovsdb\-server/get\-sync\-exclude\-tables" |
9dc05cdc MC |
232 | Gets the tables that are currently excluded from synchronization. |
233 | . | |
60e0cd04 AZ |
234 | .IP "\fBovsdb\-server/sync\-status" |
235 | Prints a summary of replication run time information. The \fBstate\fR | |
236 | information is always provided, indicating whether the server is running | |
237 | in the \fIactive\fR or the \fIbackup\fR mode. | |
238 | When running in backup mode, replication connection status, which | |
239 | can be either \fIconnecting\fR, \fIreplicating\fR or \fIerror\fR, are shown. | |
240 | When the connection is in \fIreplicating\fR state, further output shows | |
241 | the list of databases currently replicating, and the tables that are | |
242 | excluded. | |
243 | . | |
f7f62235 | 244 | .so lib/vlog-unixctl.man |
149ff68a | 245 | .so lib/memory-unixctl.man |
a5f607bc | 246 | .so lib/coverage-unixctl.man |
c70a7767 BP |
247 | .SH "SPECIFICATIONS" |
248 | . | |
249 | .PP | |
250 | \fBovsdb\-server\fR implements the Open vSwitch Database (OVSDB) | |
251 | protocol specified in RFC 7047, with the following clarifications: | |
252 | . | |
253 | .IP "3.1. JSON Usage" | |
254 | RFC 4627 says that names within a JSON object should be unique. | |
255 | The Open vSwitch JSON parser discards all but the last value | |
256 | for a name that is specified more than once. | |
257 | . | |
639b6d9c BP |
258 | .IP |
259 | The definition of <error> allows for implementation extensions. | |
260 | Currently \fBovsdb\-server\fR uses the following additional "error" | |
261 | strings which might change in later releases): | |
262 | . | |
263 | .RS | |
264 | .IP "\fBsyntax error\fR or \fBunknown column\fR" | |
265 | The request could not be parsed as an OVSDB request. An additional | |
266 | "syntax" member, whose value is a string that contains JSON, may | |
267 | narrow down the particular syntax that could not be parsed. | |
268 | .IP "\fBinternal error\fR" | |
269 | The request triggered a bug in \fBovsdb\-server\fR. | |
270 | .IP "\fBovsdb error\fR" | |
271 | A map or set contains a duplicate key. | |
d6db7b3c LR |
272 | .IP "\fBpermission error\fR" |
273 | The request was denied by the role-based access control extension, | |
274 | introduced in version 2.8. | |
639b6d9c BP |
275 | .RE |
276 | . | |
c70a7767 BP |
277 | .IP "3.2. Schema Format" |
278 | RFC 7047 requires the "version" field in <database-schema>. Current | |
279 | versions of \fBovsdb\-server\fR allow it to be omitted (future | |
280 | versions are likely to require it). | |
3df35842 BP |
281 | .IP |
282 | RFC 7047 allows columns that contain weak references to be immutable. | |
283 | This raises the issue of the behavior of the weak reference when the | |
284 | rows that it references are deleted. Since version 2.6, | |
285 | \fBovsdb\-server\fR forces columns that contain weak references to be | |
286 | mutable. | |
d6db7b3c LR |
287 | .IP |
288 | Since version 2.8, the table name \fBRBAC_Role\fR is used internally | |
289 | by the role-based access control extension to \fBovsdb\-server\fR and | |
290 | should not be used for purposes other than defining mappings of role | |
291 | names to table access permissions. This table has one row per role | |
292 | name and the following columns: | |
293 | .RS | |
294 | .IP "\fBname\fR" | |
295 | The role name. | |
296 | .IP "\fBpermissions\fR" | |
297 | A map of table name to a reference to a row in a separate permission | |
298 | table. | |
299 | .RE | |
300 | .IP | |
301 | The separate RBAC permission table has one row per access control | |
302 | configuration and the following columns: | |
303 | .RS | |
304 | .IP "\fBname\fR" | |
305 | The name of the table to which the row applies. | |
306 | .IP "\fBauthorization\fR" | |
307 | The set of column names and column:key pairs to be compared with | |
308 | the client ID in order to determine the authorization status of | |
309 | the requested operation. | |
310 | .IP "\fBinsert_delete\fR" | |
311 | A boolean value, true if authorized insertions and authorized are allowed, | |
312 | false if no insertions or deletions are allowed. | |
313 | .IP "\fBupdate\fR" | |
314 | The set of columns and column:key pairs for which authorized update and | |
315 | mutate operations should be permitted. | |
316 | .RE | |
c70a7767 BP |
317 | . |
318 | .IP "4. Wire Protocol" | |
319 | The original OVSDB specifications included the following reason, | |
320 | omitted from RFC 7047, to operate JSON-RPC directly over a stream | |
321 | instead of over HTTP: | |
322 | . | |
323 | .RS | |
324 | .IP \(bu | |
325 | JSON-RPC is a peer-to-peer protocol, but HTTP is a client-server | |
326 | protocol, which is a poor match. Thus, JSON-RPC over HTTP requires | |
327 | the client to periodically poll the server to receive server requests. | |
328 | .IP \(bu | |
329 | HTTP is more complicated than stream connections and doesn't provide | |
330 | any corresponding advantage. | |
331 | .IP \(bu | |
332 | The JSON-RPC specification for HTTP transport is incomplete. | |
333 | .RE | |
334 | . | |
d6db7b3c LR |
335 | .IP "4.1.3. Transact" |
336 | Since version 2.8, role-based access controls can be applied to operations | |
337 | within a transaction that would modify the contents of the database | |
338 | (these operations include row insert, row delete, column update, and | |
339 | column mutate). Role-based access controls are applied when the database | |
340 | schema contains a table with the name "\fBRBAC_Role\fR" and the connection | |
341 | on which the transaction request was received has an associated role | |
342 | name (from the "\fBrole\fR" column in the remote connection table). When | |
343 | role-based access controls are enabled, transactions that are otherwise | |
344 | well-formed may be rejected depending on the client's role, ID, and the | |
345 | contents of the \fBRBAC_Role\fR table and associated permissions table. | |
346 | . | |
c70a7767 BP |
347 | .IP "4.1.5. Monitor" |
348 | For backward compatibility, \fBovsdb\-server\fR currently permits a | |
349 | single <monitor-request> to be used instead of an array; it is treated | |
350 | as a single-element array. Future versions of \fBovsdb\-server\fR | |
351 | might remove this compatibility feature. | |
352 | .IP | |
353 | Because the <json-value> parameter is used to match subsequent update | |
354 | notifications (see below) to the request, it must be unique among all | |
355 | active monitors. \fBovsdb\-server\fR rejects attempt to create two | |
356 | monitors with the same identifier. | |
357 | . | |
71cdf7cd | 358 | .IP "4.1.12. Monitor_cond" |
845a1187 | 359 | A new monitor method added in Open vSwitch version 2.6. The monitor_cond |
71cdf7cd LS |
360 | request enables a client to replicate subsets of tables within an OVSDB |
361 | database by requesting notifications of changes to rows matching one of | |
362 | the conditions specified in "where" by receiving the specified contents | |
363 | of these rows when table updates occur. Monitor_cond also allows a more | |
364 | efficient update notifications by receiving table-updates2 notifications | |
365 | (described below). | |
366 | . | |
52553aea | 367 | .IP |
71cdf7cd LS |
368 | The monitor method described in Section 4.1.5 also applies to monitor_cond, |
369 | with the following exceptions: | |
52553aea AZ |
370 | . |
371 | .RS | |
372 | .IP \(bu | |
71cdf7cd | 373 | RPC request method becomes "monitor_cond". |
52553aea | 374 | .IP \(bu |
71cdf7cd | 375 | Reply result follows <table-updates2>, described in Section 4.1.14. |
52553aea AZ |
376 | .IP \(bu |
377 | Subsequent changes are sent to the client using the "update2" monitor | |
71cdf7cd LS |
378 | notification, described in Section 4.1.14 |
379 | .IP \(bu | |
380 | Update notifications are being sent only for rows matching [<condition>*]. | |
381 | .RE | |
382 | . | |
383 | .IP | |
384 | The request object has the following members: | |
385 | . | |
386 | .PP | |
387 | .RS | |
388 | .nf | |
389 | "method": "monitor_cond" | |
390 | "params": [<db-name>, <json-value>, <monitor-cond-requests>] | |
391 | "id": <nonnull-json-value> | |
392 | .fi | |
393 | .RE | |
394 | . | |
395 | .IP | |
396 | The <json-value> parameter is used to match subsequent update notifications | |
397 | (see below) to this request. The <monitor-cond-requests> object maps the name | |
398 | of the table to an array of <monitor-cond-request>. | |
399 | . | |
400 | .IP | |
401 | Each <monitor-cond-request> is an object with the following members: | |
402 | . | |
403 | .PP | |
404 | .RS | |
405 | .nf | |
406 | "columns": [<column>*] optional | |
407 | "where": [<condition>*] optional | |
408 | "select": <monitor-select> optional | |
409 | .fi | |
410 | .RE | |
411 | . | |
412 | .IP | |
413 | The "columns", if present, define the columns within the table to be monitored | |
414 | that match conditions. If not present all columns are being monitored. | |
415 | . | |
416 | .IP | |
417 | The "where" if present is a JSON array of <condition> and boolean values. If not | |
418 | present or condition is an empty array, implicit True will be considered and | |
419 | updates on all rows will be sent. | |
420 | . | |
421 | .IP | |
422 | <monitor-select> is an object with the following members: | |
423 | . | |
424 | .PP | |
425 | .RS | |
426 | .nf | |
427 | "initial": <boolean> optional | |
428 | "insert": <boolean> optional | |
429 | "delete": <boolean> optional | |
430 | "modify": <boolean> optional | |
431 | .fi | |
432 | .RE | |
433 | . | |
434 | .IP | |
435 | The contents of this object specify how the columns or table are to be | |
436 | monitored as explained in more detail below. | |
437 | . | |
438 | .IP | |
439 | The response object has the following members: | |
440 | . | |
441 | .PP | |
442 | .RS | |
443 | .nf | |
444 | "result": <table-updates2> | |
445 | "error": null | |
446 | "id": same "id" as request | |
447 | .fi | |
448 | .RE | |
449 | . | |
450 | .IP | |
451 | The <table-updates2> object is described in detail in Section 4.1.14. It | |
452 | contains the contents of the tables for which "initial" rows are selected. | |
453 | If no tables initial contents are requested, then "result" is an empty object. | |
454 | . | |
455 | .IP | |
456 | Subsequently, when changes to a specified table that match one of the conditions | |
457 | in monitor-cond-request are committed, the changes are automatically sent to the | |
458 | client using the "update2" monitor notification (see Section 4.1.14). This | |
459 | monitoring persists until the JSON-RPC session terminates or until the client | |
460 | sends a "monitor_cancel" JSON-RPC request. | |
461 | . | |
462 | .IP | |
463 | Each <monitor-cond-request> specifies one or more conditions and the manner in | |
464 | which the rows that match the conditions are to be monitored. The circumstances in | |
465 | which an "update" notification is sent for a row within the table are determined by | |
466 | <monitor-select>: | |
467 | . | |
468 | .RS | |
469 | .IP \(bu | |
470 | If "initial" is omitted or true, every row in the original table that matches one of | |
471 | the conditions is sent as part of the response to the "monitor_cond" request. | |
472 | .IP \(bu | |
473 | If "insert" is omitted or true, "update" notifications are sent for rows newly | |
474 | inserted into the table that match conditions or for rows modified in the table | |
475 | so that their old version does not match the condition and new version does. | |
476 | .IP \(bu | |
477 | If "delete" is omitted or true, "update" notifications are sent for rows deleted | |
478 | from the table that match conditions or for rows modified in the table so that | |
479 | their old version does match the conditions and new version does not. | |
480 | .IP \(bu | |
481 | If "modify" is omitted or true, "update" notifications are sent whenever a row in | |
482 | the table that matches conditions in both old and new version is modified. | |
52553aea AZ |
483 | .RE |
484 | . | |
485 | .IP | |
71cdf7cd LS |
486 | Both monitor and monitor_cond sessions can exist concurrently. However, |
487 | monitor and monitor_cond shares the same <json-value> parameter space; it | |
488 | must be unique among all monitor and monitor_cond sessions. | |
52553aea | 489 | . |
845a1187 LS |
490 | .IP "4.1.13. Monitor_cond_change" |
491 | The "monitor_cond_change" request enables a client to change an existing | |
492 | "monitor_cond" replication of the database by specifying a new condition | |
493 | and columns for each replicated table. Currently changing the columns set | |
494 | is not supported. | |
495 | . | |
496 | .IP | |
497 | The request object has the following members: | |
498 | . | |
499 | .IP | |
500 | .RS | |
501 | .nf | |
502 | "method": "monitor_cond_change" | |
503 | "params": [<json-value>, <json-value>, <monitor-cond-update-requests>] | |
504 | "id": <nonnull-json-value> | |
505 | .fi | |
506 | .RE | |
507 | . | |
508 | .IP | |
509 | The <json-value> parameter should have a value of an existing conditional | |
510 | monitoring session from this client. The second <json-value> in params array | |
511 | is the requested value for this session. This value is valid only after | |
512 | "monitor_cond_change" is committed. A user can use these values to distinguish | |
513 | between update messages before conditions update and after. The | |
514 | <monitor-cond-update-requests> object maps the name of the table to an array of | |
515 | <monitor-cond-update-request>. | |
516 | . | |
517 | .IP | |
518 | Each <monitor-cond-update-request> is an object with the following members: | |
519 | . | |
520 | .IP | |
521 | .RS | |
522 | .nf | |
523 | "columns": [<column>*] optional | |
524 | "where": [<condition>*] optional | |
525 | .fi | |
526 | .RE | |
527 | . | |
528 | .IP | |
529 | The "columns" specify a new array of columns to be monitored | |
530 | (Currently unsupported). | |
531 | . | |
532 | .IP | |
533 | The "where" specify a new array of conditions to be applied to this monitoring | |
534 | session. | |
535 | . | |
536 | .IP | |
537 | The response object has the following members: | |
538 | . | |
539 | .IP | |
540 | .RS | |
541 | .nf | |
542 | "result": null | |
543 | "error": null | |
544 | "id": same "id" as request | |
545 | .fi | |
546 | .RE | |
547 | .IP | |
548 | Subsequent <table-updates2> notifications are described in detail in Section | |
549 | 4.1.14 in the RFC. If insert contents are requested by original monitor_cond | |
550 | request, <table-updates2> will contain rows that match the new condition and | |
551 | do not match the old condition. | |
552 | If deleted contents are requested by origin monitor request, <table-updates2> | |
553 | will contain any matched rows by old condition and not matched by the new | |
554 | condition. | |
555 | . | |
556 | .IP | |
557 | Changes according to the new conditions are automatically sent to the client | |
558 | using the "update2" monitor notification. An update, if any, as a result of a | |
559 | condition change, will be sent to the client before the reply to the | |
560 | "monitor_cond_change" request. | |
561 | . | |
71cdf7cd | 562 | .IP "4.1.14. Update2 notification" |
52553aea | 563 | The "update2" notification is sent by the server to the client to report |
71cdf7cd | 564 | changes in tables that are being monitored following a "monitor_cond" request |
52553aea AZ |
565 | as described above. The notification has the following members: |
566 | . | |
567 | .RS | |
568 | .nf | |
569 | "method": "update2" | |
570 | "params": [<json-value>, <table-updates2>] | |
571 | "id": null | |
572 | .fi | |
573 | .RE | |
574 | . | |
575 | .IP | |
576 | The <json-value> in "params" is the same as the value passed as the | |
577 | <json-value> in "params" for the corresponding "monitor" request. | |
578 | <table-updates2> is an object that maps from a table name to a <table-update2>. | |
71cdf7cd LS |
579 | A <table-update2> is an object that maps from row's UUID to a <row-update2> |
580 | object. A <row-update2> is an object with one of the following members: | |
52553aea AZ |
581 | . |
582 | .RS | |
583 | .IP "\(dqinitial\(dq: <row>" | |
584 | present for "initial" updates | |
585 | .IP "\(dqinsert\(dq: <row>" | |
586 | present for "insert" updates | |
587 | .IP "\(dqdelete\(dq: <row>" | |
588 | present for "delete" updates | |
589 | .IP "\(dqmodify\(dq: <row>" | |
590 | present for "modify" updates | |
591 | .RE | |
592 | . | |
593 | .IP | |
594 | The format of <row> is described in Section 5.1. | |
595 | . | |
596 | .IP | |
597 | <row> is always a null object for a "delete" update. In "initial" and | |
598 | "insert" updates, <row> omits columns whose values equal the default | |
599 | value of the column type. | |
600 | . | |
601 | .IP | |
602 | For a "modify" update, <row> contains only the columns that are modified. | |
603 | <row> stores the difference between the old and new value for those columns, | |
604 | as described below. | |
605 | . | |
606 | .IP | |
607 | For columns with single value, the difference is the value of the new | |
608 | column. | |
609 | . | |
610 | .IP | |
611 | The difference between two sets are all elements that only belong | |
612 | to one of the sets. | |
613 | . | |
614 | .IP | |
615 | The difference between two maps are all key-value pairs whose keys | |
616 | appears in only one of the maps, plus the key-value pairs whose keys | |
617 | appear in both maps but with different values. For the latter | |
618 | elements, <row> includes the value from the new column. | |
619 | . | |
620 | .IP | |
621 | Initial views of rows are not presented in update2 notifications, | |
71cdf7cd LS |
622 | but in the response object to the monitor_cond request. The formatting |
623 | of the <table-updates2> object, however, is the same in either case. | |
52553aea | 624 | . |
05ac209a AZ |
625 | .IP "4.1.15. Get Server ID" |
626 | A new RPC method added in Open vSwitch version 2.7. The request contains | |
627 | the following members: | |
628 | . | |
629 | .PP | |
630 | .RS | |
631 | .nf | |
632 | "method": "get_server_id" | |
633 | "params": null | |
634 | "id": <nonnull-json-value> | |
635 | .fi | |
636 | .RE | |
637 | . | |
638 | .IP | |
639 | The response object contains the following members: | |
640 | . | |
641 | .PP | |
642 | .RS | |
643 | .nf | |
644 | "result": "<server_id>" | |
645 | "error": null | |
646 | "id": same "id" as request | |
647 | .fi | |
648 | .RE | |
649 | . | |
650 | .IP | |
651 | <server_id> is JSON string that contains a UUID that uniquely identifies | |
652 | the running OVSDB server process. A fresh UUID is generated when the | |
653 | process restarts. | |
654 | . | |
09e25603 TW |
655 | .IP "5.1. Notation" |
656 | For <condition>, RFC 7047 only allows the use of \fB!=\fR, \fB==\fR, | |
657 | \fBincludes\fR, and \fBexcludes\fR operators with set types. Open | |
658 | vSwitch 2.4 and later extend <condition> to allow the use of \fB<\fR, | |
659 | \fB<=\fR, \fB>=\fR, and \fB>\fR operators with columns with type ``set | |
660 | of 0 or 1 integer'' and ``set of 0 or 1 real''. These conditions | |
661 | evaluate to false when the column is empty, and otherwise as described | |
662 | in RFC 7047 for integer and real types. | |
508624b6 | 663 | . |
ae9cab37 LS |
664 | .IP |
665 | <condition> is specified in Section 5.1 in the RFC with the following change: | |
666 | A condition can be either a 3-element JSON array as described in the RFC or a | |
667 | boolean value. In case of an empty array an implicit true boolean value will be | |
668 | considered. | |
669 | . | |
970a7e91 BP |
670 | .IP "5.2.6. Wait" |
671 | .IQ "5.2.7. Commit" | |
672 | .IQ "5.2.9. Comment" | |
673 | RFC 7047 says that the \fBwait\fR, \fBcommit\fR, and \fBcomment\fR | |
674 | operations have no corresponding result object. This is not true. | |
675 | Instead, when such an operation is successful, it yields a result | |
676 | object with no members. | |
677 | . | |
508624b6 BP |
678 | .SH "BUGS" |
679 | . | |
680 | In Open vSwitch before version 2.4, when \fBovsdb\-server\fR sent | |
681 | JSON-RPC error responses to some requests, it incorrectly formulated | |
682 | them with the \fBresult\fR and \fBerror\fR swapped, so that the | |
683 | response appeared to indicate success (with a nonsensical result) | |
684 | rather than an error. The requests that suffered from this problem | |
685 | were: | |
686 | . | |
687 | .IP \fBtransact\fR | |
688 | .IQ \fBget_schema\fR | |
689 | Only if the request names a nonexistent database. | |
690 | .IP \fBmonitor\fR | |
691 | .IQ \fBlock\fR | |
692 | .IQ \fBunlock\fR | |
693 | In all error cases. | |
694 | . | |
695 | .PP | |
696 | Of these cases, the only error that a well-written application is | |
697 | likely to encounter in practice is \fBmonitor\fR of tables or columns | |
698 | that do not exist, in an situation where the application has been | |
699 | upgraded but the old database schema is still temporarily in use. To | |
700 | handle this situation gracefully, we recommend that clients should | |
701 | treat a \fBmonitor\fR response with a \fBresult\fR that contains an | |
702 | \fBerror\fR key-value pair as an error (assuming that the database | |
703 | being monitored does not contain a table named \fBerror\fR). | |
704 | . | |
f7f62235 BP |
705 | .SH "SEE ALSO" |
706 | . | |
707 | .BR ovsdb\-tool (1). |