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 4.1.7 Monitor Cancellation
117 When a database monitored by a session is removed, and database change
118 awareness is enabled for the session (see Section 4.1.16), the database
119 server spontaneously cancels all monitors (including conditional moni‐
120 tors described in Section 4.1.12) for the removed database. For each
121 canceled monitor, it issues a notification in the following form:
122 "method": "monitor_canceled"
124 "params": [<json-value>]
125 "id": null
126 4.1.12 Monitor_cond
128 A new monitor method added in Open vSwitch version 2.6. The moni‐
129 tor_cond request enables a client to replicate subsets of tables within
130 an OVSDB database by requesting notifications of changes to rows match‐
131 ing one of the conditions specified in where by receiving the specified
132 contents of these rows when table updates occur. monitor_cond also
133 allows a more efficient update notifications by receiving <ta‐
134 ble-updates2> notifications (described below).
135 The monitor method described in Section 4.1.5 also applies to moni‐
137 tor_cond, with the following exceptions:
138 · RPC request method becomes monitor_cond.
140 · Reply result follows <table-updates2>, described in Section 4.1.14.
142 · Subsequent changes are sent to the client using the update2 monitor
144 notification, described in Section 4.1.14
145 · Update notifications are being sent only for rows matching [<condi‐
147 tion>*].
148 The request object has the following members:
150 "method": "monitor_cond"
152 "params": [<db-name>, <json-value>, <monitor-cond-requests>]
153 "id": <nonnull-json-value>
154 The <json-value> parameter is used to match subsequent update notifica‐
156 tions (see below) to this request. The <monitor-cond-requests> object
157 maps the name of the table to an array of <monitor-cond-request>.
158 Each <monitor-cond-request> is an object with the following members:
160 "columns": [<column>*] optional
162 "where": [<condition>*] optional
163 "select": <monitor-select> optional
164 The columns, if present, define the columns within the table to be mon‐
166 itored that match conditions. If not present, all columns are moni‐
167 tored.
168 The where, if present, is a JSON array of <condition> and boolean val‐
170 ues. If not present or condition is an empty array, implicit True will
171 be considered and updates on all rows will be sent.
172 <monitor-select> is an object with the following members:
174 "initial": <boolean> optional
176 "insert": <boolean> optional
177 "delete": <boolean> optional
178 "modify": <boolean> optional
179 The contents of this object specify how the columns or table are to be
181 monitored as explained in more detail below.
182 The response object has the following members:
184 "result": <table-updates2>
186 "error": null
187 "id": same "id" as request
188 The <table-updates2> object is described in detail in Section 4.1.14.
190 It contains the contents of the tables for which initial rows are
191 selected. If no tables initial contents are requested, then result is
192 an empty object.
193 Subsequently, when changes to a specified table that match one of the
195 conditions in <monitor-cond-request> are committed, the changes are
196 automatically sent to the client using the update2 monitor notification
197 (see Section 4.1.14). This monitoring persists until the JSON-RPC ses‐
198 sion terminates or until the client sends a monitor_cancel JSON-RPC
199 request.
200 Each <monitor-cond-request> specifies one or more conditions and the
202 manner in which the rows that match the conditions are to be monitored.
203 The circumstances in which an update notification is sent for a row
204 within the table are determined by <monitor-select>:
205 · If initial is omitted or true, every row in the original table that
207 matches one of the conditions is sent as part of the response to the
208 monitor_cond request.
209 · If insert is omitted or true, update notifications are sent for rows
211 newly inserted into the table that match conditions or for rows modi‐
212 fied in the table so that their old version does not match the condi‐
213 tion and new version does.
214 · If delete is omitted or true, update notifications are sent for rows
216 deleted from the table that match conditions or for rows modified in
217 the table so that their old version does match the conditions and new
218 version does not.
219 · If modify is omitted or true, update notifications are sent whenever
221 a row in the table that matches conditions in both old and new ver‐
222 sion is modified.
223 Both monitor and monitor_cond sessions can exist concurrently. However,
225 monitor and monitor_cond shares the same <json-value> parameter space;
226 it must be unique among all monitor and monitor_cond sessions.
227 4.1.13 Monitor_cond_change
229 The monitor_cond_change request enables a client to change an existing
230 monitor_cond replication of the database by specifying a new condition
231 and columns for each replicated table. Currently changing the columns
232 set is not supported.
233 The request object has the following members:
235 "method": "monitor_cond_change"
237 "params": [<json-value>, <json-value>, <monitor-cond-update-requests>]
238 "id": <nonnull-json-value>
239 The <json-value> parameter should have a value of an existing condi‐
241 tional monitoring session from this client. The second <json-value> in
242 params array is the requested value for this session. This value is
243 valid only after monitor_cond_change is committed. A user can use these
244 values to distinguish between update messages before conditions update
245 and after. The <monitor-cond-update-requests> object maps the name of
246 the table to an array of <monitor-cond-update-request>. Monitored
247 tables not included in <monitor-cond-update-requests> retain their cur‐
248 rent conditions.
249 Each <monitor-cond-update-request> is an object with the following mem‐
251 bers:
252 "columns": [<column>*] optional
254 "where": [<condition>*] optional
255 The columns specify a new array of columns to be monitored, although
257 this feature is not yet supported.
258 The where specify a new array of conditions to be applied to this moni‐
260 toring session.
261 The response object has the following members:
263 "result": null
265 "error": null
266 "id": same "id" as request
267 Subsequent <table-updates2> notifications are described in detail in
269 Section 4.1.14 in the RFC. If insert contents are requested by origi‐
270 nal monitor_cond request, <table-updates2> will contain rows that match
271 the new condition and do not match the old condition. If deleted con‐
272 tents are requested by origin monitor request, <table-updates2> will
273 contain any matched rows by old condition and not matched by the new
274 condition.
275 Changes according to the new conditions are automatically sent to the
277 client using the update2 monitor notification. An update, if any, as a
278 result of a condition change, will be sent to the client before the
279 reply to the monitor_cond_change request.
280 4.1.14 Update2 notification
282 The update2 notification is sent by the server to the client to report
283 changes in tables that are being monitored following a monitor_cond
284 request as described above. The notification has the following members:
285 "method": "update2"
287 "params": [<json-value>, <table-updates2>]
288 "id": null
289 The <json-value> in params is the same as the value passed as the
291 <json-value> in params for the corresponding monitor request. <ta‐
292 ble-updates2> is an object that maps from a table name to a <ta‐
293 ble-update2>. A <table-update2> is an object that maps from row’s UUID
294 to a <row-update2> object. A <row-update2> is an object with one of the
295 following members:
296 "initial": <row>
298 present for initial updates
299 "insert": <row>
301 present for insert updates
302 "delete": <row>
304 present for delete updates
305 "modify": <row>"
307 present for modify updates
308 The format of <row> is described in Section 5.1.
310 <row> is always a null object for a delete update. In initial and
312 insert updates, <row> omits columns whose values equal the default
313 value of the column type.
314 For a modify update, <row> contains only the columns that are modified.
316 <row> stores the difference between the old and new value for those
317 columns, as described below.
318 For columns with single value, the difference is the value of the new
320 column.
321 The difference between two sets are all elements that only belong to
323 one of the sets.
324 The difference between two maps are all key-value pairs whose keys
326 appears in only one of the maps, plus the key-value pairs whose keys
327 appear in both maps but with different values. For the latter ele‐
328 ments, <row> includes the value from the new column.
329 Initial views of rows are not presented in update2 notifications, but
331 in the response object to the monitor_cond request. The formatting of
332 the <table-updates2> object, however, is the same in either case.
333 4.1.15 Get Server ID
335 A new RPC method added in Open vSwitch version 2.7. The request con‐
336 tains the following members:
337 "method": "get_server_id"
339 "params": null
340 "id": <nonnull-json-value>
341 The response object contains the following members:
343 "result": "<server_id>"
345 "error": null
346 "id": same "id" as request
347 <server_id> is JSON string that contains a UUID that uniquely identi‐
349 fies the running OVSDB server process. A fresh UUID is generated when
350 the process restarts.
351 4.1.16 Database Change Awareness
353 RFC 7047 does not provide a way for a client to find out about some
354 kinds of configuration changes, such as about databases added or
355 removed while a client is connected to the server, or databases chang‐
356 ing between read/write and read-only due to a transition between active
357 and backup roles. Traditionally, ovsdb-server disconnects all of its
358 clients when this happens, because this prompts a well-written client
359 to reassess what is available from the server when it reconnects.
360 OVS 2.9 provides a way for clients to keep track of these kinds of
362 changes, by monitoring the Database table in the _Server database
363 introduced in this release (see ovsdb-server(5) for details). By
364 itself, this does not suppress ovsdb-server disconnection behavior,
365 because a client might monitor this database without understanding its
366 special semantics. Instead, ovsdb-server provides a special request:
367 "method": "set_db_change_aware"
369 "params": [<boolean>]
370 "id": <nonnull-json-value>
371 If the boolean in the request is true, it suppresses the connec‐
373 tion-closing behavior for the current connection, and false restores
374 the default behavior. The reply is always the same:
375 "result": {}
377 "error": null
378 "id": same "id" as request
379 4.1.17 Schema Conversion
381 Open vSwitch 2.9 adds a new JSON-RPC request to convert an online data‐
382 base from one schema to another. The request contains the following
383 members:
384 "method": "convert"
386 "params": [<db-name>, <database-schema>]
387 "id": <nonnull-json-value>
388 Upon receipt, the server converts database <db-name> to schema <data‐
390 base-schema>. The schema’s name must be <db-name>. The conversion is
391 atomic, consistent, isolated, and durable. The data in the database
392 must be valid when interpreted under <database-schema>, with only one
393 exception: data for tables and columns that do not exist in the new
394 schema are ignored. Columns that exist in <database-schema> but not in
395 the database are set to their default values. All of the new schema’s
396 constraints apply in full.
397 If the conversion is successful, the server notifies clients that use
399 the set_db_change_aware RPC introduced in Open vSwitch 2.9 and cancels
400 their outstanding transactions and monitors. The server disconnects
401 other clients, enabling them to notice the change when they reconnect.
402 The server sends the following reply:
403 "result": {}
405 "error": null
406 "id": same "id" as request
407 If the conversion fails, then the server sends an error reply in the
409 following form:
410 "result": null
412 "error": [<error>]
413 "id": same "id" as request
414 5.1 Notation
416 For <condition>, RFC 7047 only allows the use of !=, ==, includes, and
417 excludes operators with set types. Open vSwitch 2.4 and later extend
418 <condition> to allow the use of <, <=, >=, and > operators with columns
419 with type “set of 0 or 1 integer” and “set of 0 or 1 real”. These con‐
420 ditions evaluate to false when the column is empty, and otherwise as
421 described in RFC 7047 for integer and real types.
422 <condition> is specified in Section 5.1 in the RFC with the following
424 change: A condition can be either a 3-element JSON array as described
425 in the RFC or a boolean value. In case of an empty array an implicit
426 true boolean value will be considered.
427 5.2.6 Wait, 5.2.7 Commit, 5.2.9 Comment
429 RFC 7047 says that the wait, commit, and comment operations have no
430 corresponding result object. This is not true. Instead, when such an
431 operation is successful, it yields a result object with no members.
432
434 The Open vSwitch Development Community
435
437 2016, The Open vSwitch Development Community
4382.10 Nov 11, 2018 OVSDB-SERVER(7)