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 up‐
77 date 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 al‐
142 lows a more efficient update notifications by receiving <table-up‐
143 dates2> 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 se‐
200 lected. If no tables initial contents are requested, then result is an
201 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 au‐
205 tomatically 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 re‐
208 quest.
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 ta‐
256 bles 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": {}
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 or update3 monitor notification depending on
287 the monitor method. An update, if any, as a result of a condition
288 change, will be sent to the client before the reply to the moni‐
289 tor_cond_change request.
290 4.1.14 Update2 notification
292 The update2 notification is sent by the server to the client to report
293 changes in tables that are being monitored following a monitor_cond re‐
294 quest as described above. The notification has the following members:
295 "method": "update2"
297 "params": [<json-value>, <table-updates2>]
298 "id": null
299 The <json-value> in params is the same as the value passed as the
301 <json-value> in params for the corresponding monitor request. <ta‐
302 ble-updates2> is an object that maps from a table name to a <table-up‐
303 date2>. A <table-update2> is an object that maps from row’s UUID to a
304 <row-update2> object. A <row-update2> is an object with one of the fol‐
305 lowing members:
306 "initial": <row>
308 present for initial updates
309 "insert": <row>
311 present for insert updates
312 "delete": <row>
314 present for delete updates
315 "modify": <row>"
317 present for modify updates
318 The format of <row> is described in Section 5.1.
320 <row> is always a null object for a delete update. In initial and in‐
322 sert updates, <row> omits columns whose values equal the default value
323 of the column type.
324 For a modify update, <row> contains only the columns that are modified.
326 <row> stores the difference between the old and new value for those
327 columns, as described below.
328 For columns with single value, the difference is the value of the new
330 column.
331 The difference between two sets are all elements that only belong to
333 one of the sets.
334 The difference between two maps are all key-value pairs whose keys ap‐
336 pears in only one of the maps, plus the key-value pairs whose keys ap‐
337 pear in both maps but with different values. For the latter elements,
338 <row> includes the value from the new column.
339 Initial views of rows are not presented in update2 notifications, but
341 in the response object to the monitor_cond request. The formatting of
342 the <table-updates2> object, however, is the same in either case.
343 4.1.15 Monitor_cond_since
345 A new monitor method added in Open vSwitch version 2.12. The moni‐
346 tor_cond_since request enables a client to request changes that hap‐
347 pened after a specific transaction id. A client can use this feature to
348 request only latest changes after a server connection reset instead of
349 re-transfer all data from the server again.
350 The monitor_cond method described in Section 4.1.12 also applies to
352 monitor_cond_since, with the following exceptions:
353 • RPC request method becomes monitor_cond_since.
355 • Reply result includes extra parameters.
357 • Subsequent changes are sent to the client using the update3 monitor
359 notification, described in Section 4.1.16
360 The request object has the following members:
362 "method": "monitor_cond_since"
364 "params": [<db-name>, <json-value>, <monitor-cond-requests>, <last-txn-id>]
365 "id": <nonnull-json-value>
366 The <last-txn-id> parameter is the transaction id that identifies the
368 latest data the client already has, and it requests server to send
369 changes AFTER this transaction (exclusive).
370 All other parameters are the same as monitor_cond method.
372 The response object has the following members:
374 "result": [<found>, <last-txn-id>, <table-updates2>]
376 "error": null
377 "id": same "id" as request
378 The <found> is a boolean value that tells if the <last-txn-id> re‐
380 quested by client is found in server’s history or not. If true, the
381 changes after that version up to current is sent. Otherwise, all data
382 is sent.
383 The <last-txn-id> is the transaction id that identifies the latest
385 transaction included in the changes in <table-updates2> of this re‐
386 sponse, so that client can keep tracking. If there is no change in‐
387 volved in this response, it is the same as the <last-txn-id> in the re‐
388 quest if <found> is true, or zero uuid if <found> is false. If the
389 server does not support transaction uuid, it will be zero uuid as well.
390 All other parameters are the same as in response object of monitor_cond
392 method.
393 Like in monitor_cond, subsequent changes that match conditions in <mon‐
395 itor-cond-request> are automatically sent to the client, but using up‐
396 date3 monitor notification (see Section 4.1.16), instead of update2.
397 4.1.16 Update3 notification
399 The update3 notification is sent by the server to the client to report
400 changes in tables that are being monitored following a moni‐
401 tor_cond_since request as described above. The notification has the
402 following members:
403 "method": "update3"
405 "params": [<json-value>, <last-txn-id>, <table-updates2>]
406 "id": null
407 The <last-txn-id> is the same as described in the response object of
409 monitor_cond_since.
410 All other parameters are the same as in update2 monitor notification
412 (see Section 4.1.14).
413 4.1.17 Get Server ID
415 A new RPC method added in Open vSwitch version 2.7. The request con‐
416 tains the following members:
417 "method": "get_server_id"
419 "params": null
420 "id": <nonnull-json-value>
421 The response object contains the following members:
423 "result": "<server_id>"
425 "error": null
426 "id": same "id" as request
427 <server_id> is JSON string that contains a UUID that uniquely identi‐
429 fies the running OVSDB server process. A fresh UUID is generated when
430 the process restarts.
431 4.1.18 Database Change Awareness
433 RFC 7047 does not provide a way for a client to find out about some
434 kinds of configuration changes, such as about databases added or re‐
435 moved while a client is connected to the server, or databases changing
436 between read/write and read-only due to a transition between active and
437 backup roles. Traditionally, ovsdb-server disconnects all of its
438 clients when this happens, because this prompts a well-written client
439 to reassess what is available from the server when it reconnects.
440 OVS 2.9 provides a way for clients to keep track of these kinds of
442 changes, by monitoring the Database table in the _Server database in‐
443 troduced in this release (see ovsdb-server(5) for details). By itself,
444 this does not suppress ovsdb-server disconnection behavior, because a
445 client might monitor this database without understanding its special
446 semantics. Instead, ovsdb-server provides a special request:
447 "method": "set_db_change_aware"
449 "params": [<boolean>]
450 "id": <nonnull-json-value>
451 If the boolean in the request is true, it suppresses the connec‐
453 tion-closing behavior for the current connection, and false restores
454 the default behavior. The reply is always the same:
455 "result": {}
457 "error": null
458 "id": same "id" as request
459 4.1.19 Schema Conversion
461 Open vSwitch 2.9 adds a new JSON-RPC request to convert an online data‐
462 base from one schema to another. The request contains the following
463 members:
464 "method": "convert"
466 "params": [<db-name>, <database-schema>]
467 "id": <nonnull-json-value>
468 Upon receipt, the server converts database <db-name> to schema <data‐
470 base-schema>. The schema’s name must be <db-name>. The conversion is
471 atomic, consistent, isolated, and durable. The data in the database
472 must be valid when interpreted under <database-schema>, with only one
473 exception: data for tables and columns that do not exist in the new
474 schema are ignored. Columns that exist in <database-schema> but not in
475 the database are set to their default values. All of the new schema’s
476 constraints apply in full.
477 If the conversion is successful, the server notifies clients that use
479 the set_db_change_aware RPC introduced in Open vSwitch 2.9 and cancels
480 their outstanding transactions and monitors. The server disconnects
481 other clients, enabling them to notice the change when they reconnect.
482 The server sends the following reply:
483 "result": {}
485 "error": null
486 "id": same "id" as request
487 If the conversion fails, then the server sends an error reply in the
489 following form:
490 "result": null
492 "error": [<error>]
493 "id": same "id" as request
494 5.1 Notation
496 For <condition>, RFC 7047 only allows the use of !=, ==, includes, and
497 excludes operators with set types. Open vSwitch 2.4 and later extend
498 <condition> to allow the use of <, <=, >=, and > operators with a col‐
499 umn with type “set of 0 or 1 integer” and an integer argument, and with
500 “set of 0 or 1 real” and a real argument. These conditions evaluate to
501 false when the column is empty, and otherwise as described in RFC 7047
502 for integer and real types.
503 <condition> is specified in Section 5.1 in the RFC with the following
505 change: A condition can be either a 3-element JSON array as described
506 in the RFC or a boolean value. In case of an empty array an implicit
507 true boolean value will be considered.
508 5.2.1 Insert
510 As an extension, Open vSwitch 2.13 and later allow an optional uuid
511 member to specify the UUID for the new row. The specified UUID must be
512 unique within the table when it is inserted and not the UUID of a row
513 previously deleted within the transaction. If the UUID violates these
514 rules, then the operation fails with a duplicate uuid error.
515 5.2.6 Wait, 5.2.7 Commit, 5.2.9 Comment
517 RFC 7047 says that the wait, commit, and comment operations have no
518 corresponding result object. This is not true. Instead, when such an
519 operation is successful, it yields a result object with no members.
520
522 The Open vSwitch Development Community
523
525 2016-2022, The Open vSwitch Development Community
5262.17 Mar 28, 2022 OVSDB-SERVER(7)