1OVSDB-SERVER(7) Open vSwitch OVSDB-SERVER(7)
2
6 ovsdb-server - Open vSwitch Database Server Protocol
7
9 ovsdb-server implements the Open vSwitch Database (OVSDB) protocol
10 specified in RFC 7047. This document provides clarifications for how
11 ovsdb-server implements the protocol and describes the extensions that
12 it provides beyond RFC 7047. Numbers in section headings refer to cor‐
13 responding sections in RFC 7047.
14 3.1 JSON Usage
16 RFC 4627 says that names within a JSON object should be unique. The
17 Open vSwitch JSON parser discards all but the last value for a name
18 that is specified more than once.
19 The definition of <error> allows for implementation extensions. Cur‐
21 rently ovsdb-server uses the following additional error strings (which
22 might change in later releases):
23 syntax error or unknown column
25 The request could not be parsed as an OVSDB request. An addi‐
26 tional syntax member, whose value is a string that contains
27 JSON, may narrow down the particular syntax that could not be
28 parsed.
29 internal error
31 The request triggered a bug in ovsdb-server.
32 ovsdb error
34 A map or set contains a duplicate key.
35 permission error
37 The request was denied by the role-based access control exten‐
38 sion, introduced in version 2.8.
39 3.2 Schema Format
41 RFC 7047 requires the version field in <database-schema>. Current ver‐
42 sions of ovsdb-server allow it to be omitted (future versions are
43 likely to require it).
44 RFC 7047 allows columns that contain weak references to be immutable.
46 This raises the issue of the behavior of the weak reference when the
47 rows that it references are deleted. Since version 2.6, ovsdb-server
48 forces columns that contain weak references to be mutable.
49 Since version 2.8, the table name RBAC_Role is used internally by the
51 role-based access control extension to ovsdb-server and should not be
52 used for purposes other than defining mappings of role names to table
53 access permissions. This table has one row per role name and the fol‐
54 lowing columns:
55 name The role name.
57 permissions
59 A map of table name to a reference to a row in a separate per‐
60 mission table.
61 The separate RBAC permission table has one row per access control con‐
63 figuration and the following columns:
64 name The name of the table to which the row applies.
66 authorization
68 The set of column names and column:key pairs to be compared with
69 the client ID in order to determine the authorization status of
70 the requested operation.
71 insert_delete
73 A boolean value, true if authorized insertions and deletions are
74 allowed, false if no insertions or deletions are allowed.
75 update The set of columns and column:key pairs for which authorized
77 update and mutate operations should be permitted.
78 4 Wire Protocol
80 The original OVSDB specifications included the following reasons, omit‐
81 ted from RFC 7047, to operate JSON-RPC directly over a stream instead
82 of over HTTP:
83 · JSON-RPC is a peer-to-peer protocol, but HTTP is a client-server pro‐
85 tocol, which is a poor match. Thus, JSON-RPC over HTTP requires the
86 client to periodically poll the server to receive server requests.
87 · HTTP is more complicated than stream connections and doesn’t provide
89 any corresponding advantage.
90 · The JSON-RPC specification for HTTP transport is incomplete.
92 4.1.3 Transact
94 Since version 2.8, role-based access controls can be applied to opera‐
95 tions within a transaction that would modify the contents of the data‐
96 base (these operations include row insert, row delete, column update,
97 and column mutate). Role-based access controls are applied when the
98 database schema contains a table with the name RBAC_Role and the con‐
99 nection on which the transaction request was received has an associated
100 role name (from the role column in the remote connection table). When
101 role-based access controls are enabled, transactions that are otherwise
102 well-formed may be rejected depending on the client’s role, ID, and the
103 contents of the RBAC_Role table and associated permissions table.
104 4.1.5 Monitor
106 For backward compatibility, ovsdb-server currently permits a single
107 <monitor-request> to be used instead of an array; it is treated as a
108 single-element array. Future versions of ovsdb-server might remove
109 this compatibility feature.
110 Because the <json-value> parameter is used to match subsequent update
112 notifications (see below) to the request, it must be unique among all
113 active monitors. ovsdb-server rejects attempt to create two monitors
114 with the same identifier.
115 When a given client sends a transact request that changes a table that
117 the same client is monitoring, ovsdb-server always sends the update (or
118 update2 or update3) for these changes before it sends the reply to the
119 transact request. Thus, when a client receives a transact reply, it
120 can know immediately what changes (if any) the transaction made. (If
121 ovsdb-server might use the other order, then a client that wishes to
122 act on based on the results of its own transactions would not know when
123 this was guaranteed to have taken place.)
124 4.1.7 Monitor Cancellation
126 When a database monitored by a session is removed, and database change
127 awareness is enabled for the session (see Section 4.1.16), the database
128 server spontaneously cancels all monitors (including conditional moni‐
129 tors described in Section 4.1.12) for the removed database. For each
130 canceled monitor, it issues a notification in the following form:
131 "method": "monitor_canceled"
133 "params": [<json-value>]
134 "id": null
135 4.1.12 Monitor_cond
137 A new monitor method added in Open vSwitch version 2.6. The moni‐
138 tor_cond request enables a client to replicate subsets of tables within
139 an OVSDB database by requesting notifications of changes to rows match‐
140 ing one of the conditions specified in where by receiving the specified
141 contents of these rows when table updates occur. monitor_cond also
142 allows a more efficient update notifications by receiving <ta‐
143 ble-updates2> notifications (described below).
144 The monitor method described in Section 4.1.5 also applies to moni‐
146 tor_cond, with the following exceptions:
147 · RPC request method becomes monitor_cond.
149 · Reply result follows <table-updates2>, described in Section 4.1.14.
151 · Subsequent changes are sent to the client using the update2 monitor
153 notification, described in Section 4.1.14
154 · Update notifications are being sent only for rows matching [<condi‐
156 tion>*].
157 The request object has the following members:
159 "method": "monitor_cond"
161 "params": [<db-name>, <json-value>, <monitor-cond-requests>]
162 "id": <nonnull-json-value>
163 The <json-value> parameter is used to match subsequent update notifica‐
165 tions (see below) to this request. The <monitor-cond-requests> object
166 maps the name of the table to an array of <monitor-cond-request>.
167 Each <monitor-cond-request> is an object with the following members:
169 "columns": [<column>*] optional
171 "where": [<condition>*] optional
172 "select": <monitor-select> optional
173 The columns, if present, define the columns within the table to be mon‐
175 itored that match conditions. If not present, all columns are moni‐
176 tored.
177 The where, if present, is a JSON array of <condition> and boolean val‐
179 ues. If not present or condition is an empty array, implicit True will
180 be considered and updates on all rows will be sent.
181 <monitor-select> is an object with the following members:
183 "initial": <boolean> optional
185 "insert": <boolean> optional
186 "delete": <boolean> optional
187 "modify": <boolean> optional
188 The contents of this object specify how the columns or table are to be
190 monitored as explained in more detail below.
191 The response object has the following members:
193 "result": <table-updates2>
195 "error": null
196 "id": same "id" as request
197 The <table-updates2> object is described in detail in Section 4.1.14.
199 It contains the contents of the tables for which initial rows are
200 selected. If no tables initial contents are requested, then result is
201 an empty object.
202 Subsequently, when changes to a specified table that match one of the
204 conditions in <monitor-cond-request> are committed, the changes are
205 automatically sent to the client using the update2 monitor notification
206 (see Section 4.1.14). This monitoring persists until the JSON-RPC ses‐
207 sion terminates or until the client sends a monitor_cancel JSON-RPC
208 request.
209 Each <monitor-cond-request> specifies one or more conditions and the
211 manner in which the rows that match the conditions are to be monitored.
212 The circumstances in which an update notification is sent for a row
213 within the table are determined by <monitor-select>:
214 · If initial is omitted or true, every row in the original table that
216 matches one of the conditions is sent as part of the response to the
217 monitor_cond request.
218 · If insert is omitted or true, update notifications are sent for rows
220 newly inserted into the table that match conditions or for rows modi‐
221 fied in the table so that their old version does not match the condi‐
222 tion and new version does.
223 · If delete is omitted or true, update notifications are sent for rows
225 deleted from the table that match conditions or for rows modified in
226 the table so that their old version does match the conditions and new
227 version does not.
228 · If modify is omitted or true, update notifications are sent whenever
230 a row in the table that matches conditions in both old and new ver‐
231 sion is modified.
232 Both monitor and monitor_cond sessions can exist concurrently. However,
234 monitor and monitor_cond shares the same <json-value> parameter space;
235 it must be unique among all monitor and monitor_cond sessions.
236 4.1.13 Monitor_cond_change
238 The monitor_cond_change request enables a client to change an existing
239 monitor_cond replication of the database by specifying a new condition
240 and columns for each replicated table. Currently changing the columns
241 set is not supported.
242 The request object has the following members:
244 "method": "monitor_cond_change"
246 "params": [<json-value>, <json-value>, <monitor-cond-update-requests>]
247 "id": <nonnull-json-value>
248 The <json-value> parameter should have a value of an existing condi‐
250 tional monitoring session from this client. The second <json-value> in
251 params array is the requested value for this session. This value is
252 valid only after monitor_cond_change is committed. A user can use these
253 values to distinguish between update messages before conditions update
254 and after. The <monitor-cond-update-requests> object maps the name of
255 the table to an array of <monitor-cond-update-request>. Monitored
256 tables not included in <monitor-cond-update-requests> retain their cur‐
257 rent conditions.
258 Each <monitor-cond-update-request> is an object with the following mem‐
260 bers:
261 "columns": [<column>*] optional
263 "where": [<condition>*] optional
264 The columns specify a new array of columns to be monitored, although
266 this feature is not yet supported.
267 The where specify a new array of conditions to be applied to this moni‐
269 toring session.
270 The response object has the following members:
272 "result": null
274 "error": null
275 "id": same "id" as request
276 Subsequent <table-updates2> notifications are described in detail in
278 Section 4.1.14 in the RFC. If insert contents are requested by origi‐
279 nal monitor_cond request, <table-updates2> will contain rows that match
280 the new condition and do not match the old condition. If deleted con‐
281 tents are requested by origin monitor request, <table-updates2> will
282 contain any matched rows by old condition and not matched by the new
283 condition.
284 Changes according to the new conditions are automatically sent to the
286 client using the update2 monitor notification. An update, if any, as a
287 result of a condition change, will be sent to the client before the
288 reply to the monitor_cond_change request.
289 4.1.14 Update2 notification
291 The update2 notification is sent by the server to the client to report
292 changes in tables that are being monitored following a monitor_cond
293 request as described above. The notification has the following members:
294 "method": "update2"
296 "params": [<json-value>, <table-updates2>]
297 "id": null
298 The <json-value> in params is the same as the value passed as the
300 <json-value> in params for the corresponding monitor request. <ta‐
301 ble-updates2> is an object that maps from a table name to a <ta‐
302 ble-update2>. A <table-update2> is an object that maps from row’s UUID
303 to a <row-update2> object. A <row-update2> is an object with one of the
304 following members:
305 "initial": <row>
307 present for initial updates
308 "insert": <row>
310 present for insert updates
311 "delete": <row>
313 present for delete updates
314 "modify": <row>"
316 present for modify updates
317 The format of <row> is described in Section 5.1.
319 <row> is always a null object for a delete update. In initial and
321 insert updates, <row> omits columns whose values equal the default
322 value of the column type.
323 For a modify update, <row> contains only the columns that are modified.
325 <row> stores the difference between the old and new value for those
326 columns, as described below.
327 For columns with single value, the difference is the value of the new
329 column.
330 The difference between two sets are all elements that only belong to
332 one of the sets.
333 The difference between two maps are all key-value pairs whose keys
335 appears in only one of the maps, plus the key-value pairs whose keys
336 appear in both maps but with different values. For the latter ele‐
337 ments, <row> includes the value from the new column.
338 Initial views of rows are not presented in update2 notifications, but
340 in the response object to the monitor_cond request. The formatting of
341 the <table-updates2> object, however, is the same in either case.
342 4.1.15 Monitor_cond_since
344 A new monitor method added in Open vSwitch version 2.12. The moni‐
345 tor_cond_since request enables a client to request changes that hap‐
346 pened after a specific transaction id. A client can use this feature to
347 request only latest changes after a server connection reset instead of
348 re-transfer all data from the server again.
349 The monitor_cond method described in Section 4.1.12 also applies to
351 monitor_cond_since, with the following exceptions:
352 · RPC request method becomes monitor_cond_since.
354 · Reply result includes extra parameters.
356 · Subsequent changes are sent to the client using the update3 monitor
358 notification, described in Section 4.1.16
359 The request object has the following members:
361 "method": "monitor_cond_since"
363 "params": [<db-name>, <json-value>, <monitor-cond-requests>, <last-txn-id>]
364 "id": <nonnull-json-value>
365 The <last-txn-id> parameter is the transaction id that identifies the
367 latest data the client already has, and it requests server to send
368 changes AFTER this transaction (exclusive).
369 All other parameters are the same as monitor_cond method.
371 The response object has the following members:
373 "result": [<found>, <last-txn-id>, <table-updates2>]
375 "error": null
376 "id": same "id" as request
377 The <found> is a boolean value that tells if the <last-txn-id>
379 requested by client is found in server’s history or not. If true, the
380 changes after that version up to current is sent. Otherwise, all data
381 is sent.
382 The <last-txn-id> is the transaction id that identifies the latest
384 transaction included in the changes in <table-updates2> of this
385 response, so that client can keep tracking. If there is no change
386 involved in this response, it is the same as the <last-txn-id> in the
387 request if <found> is true, or zero uuid if <found> is false. If the
388 server does not support transaction uuid, it will be zero uuid as well.
389 All other parameters are the same as in response object of monitor_cond
391 method.
392 Like in monitor_cond, subsequent changes that match conditions in <mon‐
394 itor-cond-request> are automatically sent to the client, but using
395 update3 monitor notification (see Section 4.1.16), instead of update2.
396 4.1.16 Update3 notification
398 The update3 notification is sent by the server to the client to report
399 changes in tables that are being monitored following a moni‐
400 tor_cond_since request as described above. The notification has the
401 following members:
402 "method": "update3"
404 "params": [<json-value>, <last-txn-id>, <table-updates2>]
405 "id": null
406 The <last-txn-id> is the same as described in the response object of
408 monitor_cond_since.
409 All other parameters are the same as in update2 monitor notification
411 (see Section 4.1.14).
412 4.1.17 Get Server ID
414 A new RPC method added in Open vSwitch version 2.7. The request con‐
415 tains the following members:
416 "method": "get_server_id"
418 "params": null
419 "id": <nonnull-json-value>
420 The response object contains the following members:
422 "result": "<server_id>"
424 "error": null
425 "id": same "id" as request
426 <server_id> is JSON string that contains a UUID that uniquely identi‐
428 fies the running OVSDB server process. A fresh UUID is generated when
429 the process restarts.
430 4.1.18 Database Change Awareness
432 RFC 7047 does not provide a way for a client to find out about some
433 kinds of configuration changes, such as about databases added or
434 removed while a client is connected to the server, or databases chang‐
435 ing between read/write and read-only due to a transition between active
436 and backup roles. Traditionally, ovsdb-server disconnects all of its
437 clients when this happens, because this prompts a well-written client
438 to reassess what is available from the server when it reconnects.
439 OVS 2.9 provides a way for clients to keep track of these kinds of
441 changes, by monitoring the Database table in the _Server database
442 introduced in this release (see ovsdb-server(5) for details). By
443 itself, this does not suppress ovsdb-server disconnection behavior,
444 because a client might monitor this database without understanding its
445 special semantics. Instead, ovsdb-server provides a special request:
446 "method": "set_db_change_aware"
448 "params": [<boolean>]
449 "id": <nonnull-json-value>
450 If the boolean in the request is true, it suppresses the connec‐
452 tion-closing behavior for the current connection, and false restores
453 the default behavior. The reply is always the same:
454 "result": {}
456 "error": null
457 "id": same "id" as request
458 4.1.19 Schema Conversion
460 Open vSwitch 2.9 adds a new JSON-RPC request to convert an online data‐
461 base from one schema to another. The request contains the following
462 members:
463 "method": "convert"
465 "params": [<db-name>, <database-schema>]
466 "id": <nonnull-json-value>
467 Upon receipt, the server converts database <db-name> to schema <data‐
469 base-schema>. The schema’s name must be <db-name>. The conversion is
470 atomic, consistent, isolated, and durable. The data in the database
471 must be valid when interpreted under <database-schema>, with only one
472 exception: data for tables and columns that do not exist in the new
473 schema are ignored. Columns that exist in <database-schema> but not in
474 the database are set to their default values. All of the new schema’s
475 constraints apply in full.
476 If the conversion is successful, the server notifies clients that use
478 the set_db_change_aware RPC introduced in Open vSwitch 2.9 and cancels
479 their outstanding transactions and monitors. The server disconnects
480 other clients, enabling them to notice the change when they reconnect.
481 The server sends the following reply:
482 "result": {}
484 "error": null
485 "id": same "id" as request
486 If the conversion fails, then the server sends an error reply in the
488 following form:
489 "result": null
491 "error": [<error>]
492 "id": same "id" as request
493 5.1 Notation
495 For <condition>, RFC 7047 only allows the use of !=, ==, includes, and
496 excludes operators with set types. Open vSwitch 2.4 and later extend
497 <condition> to allow the use of <, <=, >=, and > operators with a col‐
498 umn with type “set of 0 or 1 integer” and an integer argument, and with
499 “set of 0 or 1 real” and a real argument. These conditions evaluate to
500 false when the column is empty, and otherwise as described in RFC 7047
501 for integer and real types.
502 <condition> is specified in Section 5.1 in the RFC with the following
504 change: A condition can be either a 3-element JSON array as described
505 in the RFC or a boolean value. In case of an empty array an implicit
506 true boolean value will be considered.
507 5.2.6 Wait, 5.2.7 Commit, 5.2.9 Comment
509 RFC 7047 says that the wait, commit, and comment operations have no
510 corresponding result object. This is not true. Instead, when such an
511 operation is successful, it yields a result object with no members.
512
514 The Open vSwitch Development Community
515
517 2020, The Open vSwitch Development Community
5182.12 Jan 29, 2020 OVSDB-SERVER(7)