idnits 2.17.1 draft-pfaff-ovsdb-proto-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 4 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (February 20, 2013) is 4082 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) Summary: 3 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group B. Pfaff 3 Internet-Draft B. Davie, Ed. 4 Intended status: Informational VMware, Inc. 5 Expires: August 24, 2013 February 20, 2013 7 The Open vSwitch Database Management Protocol 8 draft-pfaff-ovsdb-proto-01 10 Abstract 12 Open vSwitch is an open source software switch designed to be used as 13 a vswitch (virtual switch) in virtualized server environments. A 14 vswitch forwards traffic between different virtual machines (VMs) on 15 the same physical host and also forwards traffic between VMs and the 16 physical network. Open vSwitch is open to programmatic extension and 17 control using OpenFlow and the OVSDB (Open vSwitch Database) 18 management protocol. This document defines the OVSDB management 19 protocol. 21 Status of this Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on August 24, 2013. 38 Copyright Notice 40 Copyright (c) 2013 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 56 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 3 57 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 58 2. System Overview . . . . . . . . . . . . . . . . . . . . . . . 4 59 3. OVSDB Structure . . . . . . . . . . . . . . . . . . . . . . . 5 60 3.1. JSON Usage . . . . . . . . . . . . . . . . . . . . . . . . 5 61 3.2. Schema Format . . . . . . . . . . . . . . . . . . . . . . 7 62 4. Wire Protocol . . . . . . . . . . . . . . . . . . . . . . . . 11 63 4.1. RPC Methods . . . . . . . . . . . . . . . . . . . . . . . 11 64 4.1.1. List Databases . . . . . . . . . . . . . . . . . . . . 12 65 4.1.2. Get Schema . . . . . . . . . . . . . . . . . . . . . . 12 66 4.1.3. Transact . . . . . . . . . . . . . . . . . . . . . . . 12 67 4.1.4. Cancel . . . . . . . . . . . . . . . . . . . . . . . . 15 68 4.1.5. Monitor . . . . . . . . . . . . . . . . . . . . . . . 15 69 4.1.6. Update Notification . . . . . . . . . . . . . . . . . 17 70 4.1.7. Monitor Cancellation . . . . . . . . . . . . . . . . . 18 71 4.1.8. Lock Operations . . . . . . . . . . . . . . . . . . . 18 72 4.1.9. Locked Notification . . . . . . . . . . . . . . . . . 20 73 4.1.10. Stolen Notification . . . . . . . . . . . . . . . . . 20 74 4.1.11. Echo . . . . . . . . . . . . . . . . . . . . . . . . . 21 75 5. Database Operations . . . . . . . . . . . . . . . . . . . . . 21 76 5.1. Notation . . . . . . . . . . . . . . . . . . . . . . . . . 21 77 5.2. Operations . . . . . . . . . . . . . . . . . . . . . . . . 25 78 5.2.1. Insert . . . . . . . . . . . . . . . . . . . . . . . . 25 79 5.2.2. Select . . . . . . . . . . . . . . . . . . . . . . . . 26 80 5.2.3. Update . . . . . . . . . . . . . . . . . . . . . . . . 27 81 5.2.4. Mutate . . . . . . . . . . . . . . . . . . . . . . . . 27 82 5.2.5. Delete . . . . . . . . . . . . . . . . . . . . . . . . 28 83 5.2.6. Wait . . . . . . . . . . . . . . . . . . . . . . . . . 29 84 5.2.7. Commit . . . . . . . . . . . . . . . . . . . . . . . . 30 85 5.2.8. Abort . . . . . . . . . . . . . . . . . . . . . . . . 30 86 5.2.9. Comment . . . . . . . . . . . . . . . . . . . . . . . 30 87 5.2.10. Assert . . . . . . . . . . . . . . . . . . . . . . . . 31 88 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31 89 7. Security Considerations . . . . . . . . . . . . . . . . . . . 31 90 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 31 91 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 32 92 9.1. Normative References . . . . . . . . . . . . . . . . . . . 32 93 9.2. Informative References . . . . . . . . . . . . . . . . . . 32 94 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 32 96 1. Introduction 98 In virtualized server environments, it is typically required to use a 99 vswitch (virtual switch) to forward traffic between different virtual 100 machines (VMs) on the same physical host, and between VMs and the 101 physical network. Open vSwitch [OVS] is an open source software 102 switch designed to be used as a vswitch in such environments. Open 103 vSwitch (OVS) is open to programmatic extension and control using 104 OpenFlow [OF-SPEC] and the OVSDB (Open vSwitch Database) management 105 protocol. This document defines the OVSDB management protocol. 107 The OVSDB management protocol uses JSON[RFC4627] for its wire format, 108 and is based on JSON-RPC version 1.0 [JSON-RPC]. 110 The schema of the Open vSwitch database is documented in [DB-SCHEMA]. 111 This document specifies the protocol for interacting with that 112 database for the purposes of managing and configuring Open vSwitch 113 instances. The protocol specified in this document also provides 114 means for discovering the schema in use, as described in 115 Section 4.1.2. 117 1.1. Requirements Language 119 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 120 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 121 document are to be interpreted as described in[RFC2119]. 123 1.2. Terminology 125 UUID: Universally Unique Identifier. A 128-bit identifier that is 126 unique in space and time [DCE]. 128 OVS: Open vSwitch. An open source virtual switch. 130 OVSDB: The database that is used for the purpose of configuring 131 OVS instances. 133 JSON: Javascript Object Notation [RFC4627]. 135 JSON-RPC: JSON Remote Procedure Call [JSON-RPC]. 137 Note that the JSON specification [RFC4627] provides precise 138 definitions of a number of important terms such as JSON values, 139 objects, arrays, numbers, and strings. In all cases, this document 140 uses the definitions from [RFC4627]. 142 2. System Overview 144 Figure 1 illustrates the main components of Open vSwitch and the 145 interfaces to a control and management cluster. An OVS instance 146 comprises a database server (ovsdb-server), a vswitch daemon (ovs- 147 vswitchd), and, optionally, a module that performs fast path 148 forwarding. The "management and control cluster" consists of some 149 number of managers and controllers. Managers use the OVSDB 150 management protocol to manage OVS instances. An OVS instance is 151 managed by at least one manager. Controllers use OpenFlow to install 152 flow state in OpenFlow switches. An OVS instance can support 153 multiple logical datapaths, referred to as bridges. There is at 154 least one controller for each OpenFlow bridge. 156 The OVSDB management interface is used to perform management and 157 configuration operations on the OVS instance. Compared to OpenFlow, 158 OVSDB management operations occur at a relatively long timescale. 159 Examples of operations that are supported by OVSDB include: 161 o Creation, modification and deletion of OpenFlow datapaths 162 (bridges), of which there may be many in a single OVS instance; 164 o Configuration of the set of controllers to which an OpenFlow 165 datapath should connect; 167 o Configuration of the set of managers to which the OVSDB server 168 should connect; 170 o Creation, modification and deletion of ports on OpenFlow 171 datapaths; 173 o Creation, modification and deletion of tunnel interfaces on 174 OpenFlow datapaths; 176 o Creation, modification and deletion of queues; 178 o Configuration of QoS (quality of service) policies, and attachment 179 of those policies to queues; 181 o Collection of statistics. 183 OVSDB does not perform per-flow operations, leaving those instead to 184 OpenFlow. 186 +----------------------+ 187 | Control & | 188 | Management | 189 | Cluster | 190 +----------------------+ 191 | \ 192 | OVSDB \ OpenFlow 193 | Mgmt \ 194 | \ 195 +============================================+ 196 | +--------------+ +--------------+ | 197 | | | | | | 198 | | ovsdb-server |-------| ovs-vswitchd | | 199 | | | | | | 200 | +--------------+ +--------------+ | 201 | | | 202 | +----------------+ | 203 | | Forwarding Path| | 204 | +----------------+ | 205 +============================================+ 207 Figure 1: Open vSwitch Interfaces 209 Further information about the usage of the OVSDB management protocol 210 is provided in [DB-SCHEMA]. 212 3. OVSDB Structure 214 This section outlines the overall structure of databases in OVSDB. 215 As described here, the database is reasonably generic. For the 216 complete and current description of the database schema as used in 217 OVS, refer to [DB-SCHEMA]. See also Section 4.1.2 for information on 218 how the OVSDB protocol may be used to discover the schema currently 219 in use. 221 3.1. JSON Usage 223 OVSDB uses JSON [RFC4627] for both its schema format and its wire 224 protocol format. The JSON implementation in Open vSwitch has the 225 following limitations: 227 o Null bytes (\u0000) SHOULD NOT be used in strings. 229 o Only UTF-8 encoding is supported. 231 The descriptions below use the following shorthand notations for JSON 232 values. Terminology follows [RFC4627]. 234 A JSON string. Any Unicode string is allowed. 235 Implementations SHOULD disallow null bytes. 237 A JSON string matching [a-zA-Z_][a-zA-Z0-9_]*. s that 238 begin with _ are reserved to the implementation and MUST NOT be 239 used by the user. 241 A JSON string that contains a version number that 242 matches [0-9]+\.[0-9]+\.[0-9]+ 244 A JSON true or false value. 246 A JSON number. 248 A JSON number with an integer value, within the range 249 -(2**63)...+(2**63)-1. 251 Any JSON value. 253 Any JSON value except null. 255 A JSON object with the following members: 257 "error": required 258 "details": optional 260 The value of the "error" member is a short string, specified in 261 this document, that broadly indicates the class of the error. 262 Most "error" strings are specific to contexts described 263 elsewhere in this document, but the following "error" strings 264 may appear in any context where an is permitted: 266 "error": "resources exhausted" The operation requires more 267 resources (memory, disk, CPU, etc.) than are currently 268 available to the database server. 270 "error": "I/O error" Problems accessing the disk, network, or 271 other required resources prevented the operation from 272 completing. 274 Database implementations MAY use "error" strings not specified 275 in this document to indicate errors that do not fit into any of 276 the specified categories. Optionally, an MAY include a 277 "details" member, whose value is a string that describes the 278 error in more detail for the benefit of a human user or 279 administrator. This document does not specify the format or 280 content of the "details" string. An MAY also have 281 other members that describe the error in more detail. This 282 document does not specify the names or values of these members. 284 3.2. Schema Format 286 An Open vSwitch configuration database consists of a set of tables, 287 each of which has a number of columns and zero or more rows. A 288 schema for the database is represented by , as 289 described below. 291 292 A JSON object with the following members: 294 "name": required 295 "version": required 296 "cksum": optional 297 "tables": {: , ...} required 299 The "name" identifies the database as a whole. It must be 300 provided to most JSON-RPC requests to identify the database being 301 operated on. The value of "tables" is a JSON object whose names 302 are table names and whose values are s. 304 The "version" reports the version of the database schema. It is 305 required to be present. Open vSwitch semantics for "version" are 306 described in [DB-SCHEMA]. Other schemas may use it differently. 308 The "cksum" optionally reports an implementation-defined checksum 309 for the database schema. 311 The value of "tables" is a JSON object whose names are table names 312 and whose values are s. 314 315 A JSON object with the following members: 317 "columns": {: , ...} required 318 "maxRows": optional 319 "isRoot": optional 320 "indexes": [*] optional 322 The value of "columns" is a JSON object whose names are column 323 names and whose values are s. 325 Every table has the following columns whose definitions are not 326 included in the schema: 328 "_uuid": This column, which contains exactly one UUID value, is 329 initialized to a random value by the database engine when it 330 creates a row. It is read-only, and its value never changes 331 during the lifetime of a row. 333 "_version": Like "_uuid", this column contains exactly one UUID 334 value, initialized to a random value by the database engine 335 when it creates a row, and it is read-only. However, its value 336 changes to a new random value whenever any other field in the 337 row changes. Furthermore, its value is ephemeral: when the 338 database is closed and reopened, or when the database process 339 is stopped and then started again, each "_version" also changes 340 to a new random value. 342 If "maxRows" is specified, as a positive integer, it limits the 343 maximum number of rows that may be present in the table. This is 344 a "deferred" constraint, enforced only at transaction commit time 345 (see the "transact" request below). If "maxRows" is not 346 specified, the size of the table is limited only by the resources 347 available to the database server. "maxRows" constraints are 348 enforced after unreferenced rows are deleted from tables with a 349 false "isRoot". 351 The "isRoot" boolean is used to determine whether rows in the 352 table require strong references from other rows to avoid garbage 353 collection. (See the discussion of "strong" and "weak" references 354 below in the description of base types.) If "isRoot" is specified 355 as true, then rows in the table exist independent of any 356 references (they can be thought of as part of the "root set" in a 357 garbage collector). If "isRoot" is omitted or specified as false, 358 then any given row in the table may exist only when there is at 359 least one reference to it, with refType "strong", from a different 360 row (in the same table or a different table). This is a 361 "deferred" action: unreferenced rows in the table are deleted just 362 before transaction commit. 364 For compatibility with schemas created before "isRoot" was 365 introduced, if "isRoot" is omitted or false in every in a given , then every table is part of 367 the root set. 369 If "indexes" is specified, it must be an array of zero or more 370 s. A is an array of one or more strings, 371 each of which names a column. Each is a set of 372 columns whose values, taken together within any given row, must be 373 unique within the table. This is a "deferred" constraint, 374 enforced only at transaction commit time, after unreferenced rows 375 are deleted and dangling weak references are removed. Ephemeral 376 columns may not be part of indexes. 378 379 A JSON object with the following members: 381 "type": required 382 "ephemeral": optional 383 "mutable": optional 385 The "type" specifies the type of data stored in this column. 387 If "ephemeral" is specified as true, then this column's values are 388 not guaranteed to be durable; they may be lost when the database 389 restarts. A column whose type (either key or value) is a strong 390 reference to a table that is not part of the root set is always 391 durable, regardless of this value. (Otherwise, restarting the 392 database could lose entire rows.) 394 If "mutable" is specified as false, then this column's values may 395 not be modified after they are initially set with the "insert" 396 operation. 398 399 The type of a database column. Either an or a JSON 400 object that describes the type of a database column, with the 401 following members: 403 "key": required 404 "value": optional 405 "min": optional 406 "max": or "unlimited" optional 408 If "min" or "max" is not specified, each defaults to 1. If "max" 409 is specified as "unlimited", then there is no specified maximum 410 number of elements, although the implementation will enforce some 411 limit. After considering defaults, "min" must be exactly 0 or 412 exactly 1, "max" must be at least 1, and "max" must be greater 413 than or equal to "min". 415 If "min" and "max" are both 1 and "value" is not specified, the 416 type is the scalar type specified by "key". 418 If "min" is not 1 or "max" is not 1, or both, and "value" is not 419 specified, the type is a set of scalar type "key". 421 If "value" is specified, the type is a map from type "key" to type 422 "value". 424 425 The type of a key or value in a database column. Either an 426 or a JSON object with the following members: 428 "type": required 429 "enum": optional 430 "minInteger": optional, integers only 431 "maxInteger": optional, integers only 432 "minReal": optional, reals only 433 "maxReal": optional, reals only 434 "minLength": optional, strings only 435 "maxLength": optional, strings only 436 "refTable": optional, uuids only 437 "refType": "strong" or "weak" optional, only with "refTable" 439 An by itself is equivalent to a JSON object with a 440 single member "type" whose value is the . 442 "enum" may be specified as a whose type is a set of one or 443 more values specified for the member "type". If "enum" is 444 specified, then the valid values of the are limited to 445 those in the . 447 "enum" is mutually exclusive with the following constraints. 449 If "type" is "integer", then "minInteger" or "maxInteger" or both 450 may also be specified, restricting the valid integer range. If 451 both are specified, then the maxInteger must be greater than or 452 equal to minInteger. 454 If "type" is "real", then "minReal" or "maxReal" or both may also 455 be specified, restricting the valid real range. If both are 456 specified, then the maxReal must be greater than or equal to 457 minReal. 459 If "type" is "string", then "minLength" and "maxLength" or both 460 may be specified, restricting the valid length of value strings. 461 If both are specified, then maxLength must be greater than or 462 equal to minLength. String length is measured in characters. 464 If "type" is "uuid", then "refTable", if present, must be the name 465 of a table within this database. If "refTable" is specified, then 466 "refType" may also be specified. If "refTable" is set, the effect 467 depends on "refType": 469 * If "refType" is "strong" or if "refType" is omitted, the 470 allowed UUIDs are limited to UUIDs for rows in the named table. 472 * If "refType" is "weak", then any UUIDs are allowed, but UUIDs 473 that do not correspond to rows in the named table will be 474 automatically deleted. 476 "refTable" constraints are "deferred" constraints: they are 477 enforced only at transaction commit time (see the "transact" 478 request below). The other constraints on are 479 "immediate", enforced immediately by each operation. 481 482 One of the strings "integer", "real", "boolean", "string", or 483 "uuid", representing the specified scalar type. 485 4. Wire Protocol 487 The database wire protocol is implemented in JSON-RPC 1.0 [JSON-RPC]. 488 While the spec of JSON-RPC allows a range of transports, 489 implementations of this specification SHOULD operate directly over 490 TCP. See Section 6 for discussion of the TCP port. 492 4.1. RPC Methods 494 The following subsections describe the RPC methods that are 495 supported. As described in the JSON-RPC 1.0 specification, each 496 request comprises a string containing the name of the method, a 497 (possibly null) array of parameters to pass to the method, and a 498 request ID, which can be used to match the response to the request. 499 Each response comprises a result object (non-null in the event of a 500 successful invocation), an error object (non-null in the event of an 501 error), and the ID of the matching request. More details on each 502 method, its parameters and results are described below. 504 The operations that may be performed on the OVS database using these 505 methods (e.g., the "Transact" method) are described in Section 5. 507 4.1.1. List Databases 509 This operation retrieves an array whose elements are the names of the 510 databases that can be accessed over this management protocol 511 connection. 513 The request object contains the following members: 515 o "method": "list_dbs" 517 o "params": [] 519 o "id": 521 The response object contains the following members: 523 o "result": [,...] 525 o "error": null 527 o "id": same "id" as request 529 4.1.2. Get Schema 531 This operation retrieves a that describes hosted 532 database . 534 The request object contains the following members: 536 o "method": "get_schema" 538 o "params": [] 540 o "id": 542 The response object contains the following members: 544 o "result": 546 o "error": null 548 o "id": same "id" as request 550 4.1.3. Transact 552 This RPC method causes the database server to execute a series of 553 operations in the specified order on a given database. 555 The request object contains the following members: 557 o "method": "transact" 559 o "params": [, *] 561 o "id": 563 The value of "id" MUST be unique among all in-flight transactions 564 within the current JSON-RPC session. Otherwise, the server may 565 return a JSON-RPC error. 567 The "params" array for this method consists of a that 568 identifies the database to which the transaction applies, followed by 569 zero or more JSON objects, each of which represents a single database 570 operation. Section 5 describes the valid operations. The database 571 server executes each of the specified operations in the specified 572 order, except that if an operation fails, then the remaining 573 operations are not executed. The set of operations is executed as a 574 single atomic, consistent, isolated transaction. The transaction is 575 committed only if every operation succeeds. Durability of the commit 576 is not guaranteed unless the "commit" operation, with "durable" set 577 to true, is included in the operation set. See Section 5 for more 578 discussion of the database operations. 580 The response object contains the following members: 582 o "result": [*] 584 o "error": null 586 o "id": same "id" as request 588 Regardless of whether errors occur in the database operations, the 589 response is always a JSON-RPC response with null "error" and a 590 "result" member that is an array with the same number of elements as 591 "params". Each element of the "result" array corresponds to the same 592 element of the "params" array. The "result" array elements may be 593 interpreted as follows: 595 o A JSON object that does not contain an "error" member indicates 596 that the operation completed successfully. The specific members 597 of the object are specified below in the descriptions of 598 individual operations. Some operations do not produce any 599 results, in which case the object will have no members. 601 o An indicates that the matching operation completed with an 602 error. 604 o A JSON null value indicates that the operation was not attempted 605 because a prior operation failed. 607 In general, "result" contains some number of successful results, 608 possibly followed by an error, in turn followed by enough JSON null 609 values to match the number of elements in "params". There is one 610 exception: if all of the operations succeed, but the results cannot 611 be committed, then "result" will have one more element than "params", 612 with the additional element being an . In this case, the 613 possible "error" strings include the following: 615 "error": "referential integrity violation" 617 When the commit was attempted, a column's value referenced the 618 UUID for a row that did not exist in the table named by the 619 column's key or value "refTable" that has a "refType" 620 of "strong". (This can be caused by inserting a row that 621 references a nonexistent row, by deleting a row that is still 622 referenced by another row, by specifying the UUID for a row in the 623 wrong table, and other ways.) 625 "error": "constraint violation" 627 A number of situations can arise in which the attempted commit 628 would lead to a constraint on the database being violated. (See 629 Section 3.2 for more discussion of constraints.) These situations 630 include: 632 * The number of rows in a table exceeds the maximum number 633 permitted by the table's "maxRows" value. 635 * Two or more rows in a table had the same values in the columns 636 that comprise an index. 638 * A column with a key or value "refTable" whose 639 "refType" is "weak" became empty due to deletion(s), and this 640 column is not allowed to be empty because its has a 641 "min" of 1. Such deletions may be the result of rows that it 642 referenced being deleted (or never having existed, if the 643 column's row was inserted within the transaction). 645 "error": "resources exhausted" 647 The operation requires more resources (memory, disk, CPU, etc.) 648 than are currently available to the database server. 650 "error": "I/O error" 651 Problems accessing the disk, network, or other required resources 652 prevented the operation from completing. 654 If "params" contains one or more "wait" operations, then the 655 transaction may take an arbitrary amount of time to complete. The 656 database implementation MUST be capable of accepting, executing, and 657 replying to other transactions and other JSON-RPC requests while a 658 transaction or transactions containing "wait" operations are 659 outstanding on the same or different JSON-RPC sessions. 661 4.1.4. Cancel 663 The "cancel" method is a JSON-RPC notification, i.e. no matching 664 response is provided. It instructs the database server to 665 immediately complete or cancel the "transact" request whose "id" is 666 the same as the notification's "params" value. The notification 667 object has the following members: 669 o "method": "cancel" 671 o "params": [the "id" for an outstanding request] 673 o "id": null 675 If the "transact" request can be completed immediately, then the 676 server sends a response in the form described for "transact", above 677 (Section 4.1.3). Otherwise, the server sends a JSON-RPC error 678 response of the following form: 680 o "result": null 682 o "error": "canceled" 684 o "id": the "id" member of the canceled request. 686 The "cancel" notification itself has no reply. 688 4.1.5. Monitor 690 The "monitor" request enables a client to replicate tables or subsets 691 of tables within an OVSDB database by requesting notifications of 692 changes to those tables and by receiving the complete initial state 693 of a table or a subset of a table. The request object has the 694 following members: 696 o "method": "monitor" 697 o "params": [, , ] 699 o "id": 701 The parameter is used to match subsequent update 702 notifications (see below) to this request. The 703 object maps the name of the table to be monitored to an array of 704 objects. 706 Each is an object with the following members: 707 "columns": [*] optional 708 "select": optional 710 The columns, if present, define the columns within the table to be 711 monitored. is an object with the following members: 712 "initial": optional 713 "insert": optional 714 "delete": optional 715 "modify": optional 717 The contents of this object specify how the columns or table are to 718 be monitored, as explained in more detail below. 720 The response object has the following members: 722 o "result": 724 o "error": null 726 o "id": same "id" as request 728 The object is described in detail in Section 4.1.6. 729 It contains the contents of the tables for which "initial" rows are 730 selected. If no tables' initial contents are requested, then 731 "result" is an empty object. 733 Subsequently, when changes to the specified tables are committed, the 734 changes are automatically sent to the client using the "update" 735 monitor notification (see Section 4.1.6). This monitoring persists 736 until the JSON-RPC session terminates or until the client sends a 737 "monitor_cancel" JSON-RPC request. 739 Each specifies one or more columns and the manner 740 in which the columns (or the entire table) are to be monitored. The 741 "columns" member specifies the columns whose values are monitored. 742 It MUST NOT contain duplicates. If "columns" is omitted, all columns 743 in the table, except for "_uuid", are monitored. The circumstances 744 in which an "update" notification is sent for a row within the table 745 are determined by : 747 o If "initial" is omitted or true, every row in the table is sent as 748 part of the response to the "monitor" request. 750 o If "insert" is omitted or true, "update" notifications are sent 751 for rows newly inserted into the table. 753 o If "delete" is omitted or true, "update" notifications are sent 754 for rows deleted from the table. 756 o If "modify" is omitted or true, "update" notifications are sent 757 whenever a row in the table is modified. 759 If there is more than one in an array of them, then 760 each in the array should specify both "columns" and 761 "select", and the "columns" MUST be non-overlapping sets. 763 4.1.6. Update Notification 765 The "update" notification is sent by the server to the client to 766 report changes in tables that are being monitored following a 767 "monitor" request as described above. The notification has the 768 following members: 770 o "method": "update" 772 o "params": [, ] 774 o "id": null 776 The in "params" is the same as the value passed as the 777 in "params" for the corresponding "monitor" request. 778 is an object that maps from a table name to a . A is an object that maps from the row's UUID 780 to a object. A is an object with the 781 following members: 782 "old": present for "delete" and "modify" updates 783 "new": present for "initial", "insert", and "modify" updates 785 Each table in which one or more rows has changed (or whose initial 786 view is being presented) is represented in "updates". Each row that 787 has changed (or whose initial view is being presented) is represented 788 in its as a member with its name taken from the row's 789 _uuid member. The corresponding value is a : 791 o The "old" member is present for "delete" and "modify" updates. 792 For "delete" updates, each monitored column is included. For 793 "modify" updates, the prior value of each monitored column whose 794 value has changed is included (monitored columns that have not 795 changed are represented in "new"). 797 o The "new" member is present for "initial", "insert", and "modify" 798 updates. For "initial" and "insert" updates, each monitored 799 column is included. For "modify" updates, the new value of each 800 monitored column is included. 802 Note that initial views of rows are not presented in update 803 notifications, but in the response object to the monitor request. 804 The formatting of the object is the same in either 805 case however. 807 4.1.7. Monitor Cancellation 809 The "monitor_cancel" request cancels a previously issued monitor 810 request. The request object members are: 812 o "method": "monitor_cancel" 814 o "params": [] 816 o "id": 818 The in "params" matches the in "params" for 819 the ongoing "monitor" request that is to be canceled. No more 820 "update" messages will be sent for this table monitor. The response 821 to this request has the following members: 823 o "result": {} 825 o "error": null 827 o "id": the request "id" member 829 4.1.8. Lock Operations 831 Three RPC methods, "lock", "steal", and "unlock", allow a client to 832 perform locking operations on the database. The database server 833 supports an arbitrary number of locks, each of which is identified by 834 a client-defined id. At any given time, each lock may have at most 835 one owner. The RPC request objects have the following members: 837 o "method": "lock", "steal", or "unlock" 839 o "params": [] 840 o "id": 842 The response depends on the request, and has the following members: 844 o "result": {"locked": boolean} for "lock" 846 o "result": {"locked": true} for "steal" 848 o "result": {} for "unlock" 850 o "error": null 852 o "id": same "id" as request 854 The three methods operate as follows: 856 o "lock": The database will assign this client ownership of the lock 857 as soon as it becomes available. When multiple clients request 858 the same lock, they will receive it in first-come, first served 859 order. 861 o "steal": The database immediately assigns this client ownership of 862 the lock. If there is an existing owner, it loses ownership. 864 o "unlock": If the client owns the lock, releases it. If the client 865 is waiting to obtain the lock, this cancels the request and stops 866 waiting. 868 (Closing or otherwise disconnecting a database client connection 869 unlocks all of its locks.) 871 For any given lock, the client MUST alternate "lock" or "steal" 872 operations with "unlock" operations. That is, if the previous 873 operation on a lock was "lock" or "steal", it MUST be followed by an 874 "unlock" operation, and vice versa. 876 For a "lock" operation, the "locked" member in the response object is 877 true if the lock has already been acquired, false if another client 878 holds the lock and the client's request for it was queued. In the 879 latter case, the client will be notified later with a "locked" 880 message (Section 4.1.9) when acquisition succeeds. 882 These requests complete and send a response quickly, without waiting. 883 The "locked" and "stolen" notifications (see below) report 884 asynchronous changes to ownership. 886 Note that the scope of a lock is a database server, not a database 887 hosted by that server. A client may choose to implement a naming 888 convention, such as "__", which can effectively 889 limit the scope of a lock to a particular database. 891 4.1.9. Locked Notification 893 The "locked" notification is provided to notify a client that it has 894 been granted a lock it had previously request a lock with the "lock" 895 method described above. The notification has the following members: 897 o "method": "locked" 899 o "params": [] 901 o "id": null 903 "Params" contains the name of the lock that was given in the "lock" 904 request. The notified client now owns the lock named in "params". 906 The database server sends this notification after the reply to the 907 corresponding "lock" request (but only if the "locked" member of the 908 response was false), and before the reply to the client's subsequent 909 "unlock" request. 911 4.1.10. Stolen Notification 913 The "stolen" notification is provided to notify a client, which had 914 previously obtained a lock, that another client has stolen ownership 915 of that lock. The notification has the following members: 917 o "method": "stolen" 919 o "params": [] 921 o "id": null 923 The notified client no longer owns the lock named in "params". The 924 client MUST still issue an "unlock" request before performing any 925 subsequent "lock" or "steal" operation on the lock. 927 If the client originally obtained the lock through a "lock" request, 928 then it will automatically regain the lock later after the client 929 that stole it releases it. (The database server will send the client 930 a "locked" notification at that point to let it know.) 932 If the client originally obtained the lock through a "steal" request, 933 the database server won't automatically reassign it ownership of the 934 lock when it later becomes available. To regain ownership, the 935 client must "unlock" and then "lock" or "steal" the lock again. 937 4.1.11. Echo 939 The "echo" method can be used by both clients and servers to verify 940 the liveness of a database connection. It MUST be implemented by 941 both clients and servers. The members of the request are: 943 o "method": "echo" 945 o "params": JSON array with any contents 947 o "id": 949 The response object has the following members: 951 o "result": same as "params" 953 o "error": null 955 o "id": the request "id" member 957 5. Database Operations 959 This section describes the operations that may be specified in the 960 "transact" method described in Section 4.1.3. 962 5.1. Notation 964 We introduce the following notation for the discussion of operations. 966 967 An that names a database. The valid s can be 968 obtained using a "list-db" request. The is taken from 969 the "name" member of . 971 972 An that names a table. 974 975 An that names a table column. 977 978 A JSON object that describes a table row or a subset of a table 979 row. Each member is the name of a table column paired with the 980 of that column. 982 983 A JSON value that represents the value of a column in a table row, 984 one of , a , or a . 986 987 A JSON value that represents a scalar value for a column, one of 988 , , , , . 990 991 Either an , representing a set with exactly one element, or 992 a 2-element JSON array that represents a database set value. The 993 first element of the array must be the string "set" and the second 994 element must be an array of zero or more s giving the values 995 in the set. All of the s must have the same type. 997 998 A 2-element JSON array that represents a database map value. The 999 first element of the array must be the string "map" and the second 1000 element must be an array of zero or more s giving the values 1001 in the map. All of the s must have the same key and value 1002 types. 1003 (JSON objects are not used to represent because JSON only 1004 allows string names in an object.) 1006 1007 A 2-element JSON array that represents a pair within a database 1008 map. The first element is an that represents the key, the 1009 second element is an that represents the value. 1011 1012 A 2-element JSON array that represents a UUID. The first element 1013 of the array must be the string "uuid" and the second element must 1014 be a 36-character string giving the UUID in the format described 1015 by RFC 4122. For example, the following represents the 1016 UUID 550e8400-e29b-41d4-a716-446655440000: 1018 ["uuid", "550e8400-e29b-41d4-a716-446655440000"] 1020 1021 A 2-element JSON array that represents the UUID of a row inserted 1022 in an "insert" operation within the same transaction. The first 1023 element of the array must be the string "named-uuid" and the 1024 second element should be the specified as the "uuid-name" for 1025 an "insert" operation within the same transaction. For example, 1026 if an "insert" operation within this transaction specifies a 1027 "uuid-name" of "myrow", the following represents the 1028 UUID created by that operation: 1030 ["named-uuid", "myrow"] 1032 A may be used anywhere a is valid. 1034 1035 A 3-element JSON array of the form [, , ] 1036 that represents a test on a column value. Except as otherwise 1037 specified below, MUST have the same type as . The 1038 meaning depends on the type of : 1040 integer or real 1041 must be "<", "<=", "==", "!=", ">=", ">", 1042 "includes", or "excludes". 1044 The test is true if the column's value satisfies the relation 1045 , e.g. if the column has value 1 and 1046 is 2, the test is true if is "<", "<=" or "!=", but 1047 not otherwise. 1049 "includes" is equivalent to "=="; "excludes" is equivalent to 1050 "!=". 1052 boolean or string or uuid 1053 must be "!=", "==", "includes", or "excludes". 1055 If is "==" or "includes", the test is true if the 1056 column's value equals . If is "!=" or 1057 "excludes", the test is inverted. 1059 set or map 1060 must be "!=", "==", "includes", or "excludes". 1062 If is "==", the test is true if the column's value 1063 contains exactly the same values (for sets) or pairs (for 1064 maps). If is "!=", the test is inverted. 1066 If is "includes", the test is true if the column's 1067 value contains all of the values (for sets) or pairs (for maps) 1068 in . The column's value may also contain other values 1069 or pairs. 1071 If is "excludes", the test is true if the column's 1072 value does not contain any of the values (for sets) or pairs 1073 (for maps) in . The column's value may contain other 1074 values or pairs not in . 1076 If is "includes" or "excludes", then the required 1077 type of is slightly relaxed, in that it may have fewer 1078 than the minimum number of elements specified by the column's 1079 type. If is "excludes", then the required type is 1080 additionally relaxed in that may have more than the 1081 maximum number of elements specified by the column's type. 1082 One of "<", "<=", "==", "!=", ">=", ">", "includes", 1083 "excludes". 1085 1086 One of "<", "<=", "==", "!=", ">=", ">", "includes", "excludes". 1088 1089 A 3-element JSON array of the form [, , ] 1090 that represents a change to a column value. Except as otherwise 1091 specified below, must have the same type as . The 1092 meaning depends on the type of : 1094 integer or real 1095 must be "+=", "-=", "*=", "/=" or (integer only) 1096 "%=". The value of is changed to the sum, difference, 1097 product, quotient, or remainder, respectively, of and 1098 . 1100 Constraints on are ignored when parsing . 1102 boolean or string or uuid 1103 No valid s are currently defined for these types. 1105 set 1106 Any valid for the set's element type may be applied 1107 to the set, in which case the mutation is applied to each 1108 member of the set individually. must be a scalar value 1109 of the same type as the set's element type, except that 1110 constraints are ignored. 1112 If is "insert", then each of the values in the set in 1113 is added to if it is not already present. The 1114 required type of is slightly relaxed, in that it may 1115 have fewer than the minimum number of elements specified by the 1116 column's type. 1118 If is "delete", then each of the values in the set in 1119 is removed from if it is present there. The 1120 required type is slightly relaxed in that may have more 1121 or less than the maximum number of elements specified by the 1122 column's type. 1124 map 1125 must be "insert" or "delete". 1127 If is "insert", then each of the key-value pairs in 1128 the map in is added to only if its key is not 1129 already present. The required type of is slightly 1130 relaxed, in that it may have fewer than the minimum number of 1131 elements specified by the column's type. 1133 If is "delete", then may have the same type 1134 as (a map type) or it may be a set whose element type 1135 is the same as 's key type: 1137 + If is a map, the mutation deletes each key-value 1138 pair in whose key and value equal one of the key- 1139 value pairs in . 1141 + If is a set, the mutation deletes each key-value 1142 pair in whose key equals one of the values in 1143 . 1145 For "delete", may have any number of elements, 1146 regardless of restrictions on the number of elements in 1147 . 1149 1150 One of "+=", "-=", "*=", "/=", "%=", "insert", "delete". 1152 5.2. Operations 1154 The operations that may be performed as part of a "transact" RPC 1155 request (see Section 4.1.3) are described in the following sections. 1156 Each of these operations is a JSON object that may be included as one 1157 of the elements of the "params" array that is one of the elements of 1158 the "transact" request. The details of each object, its semantics, 1159 results, and possible errors are described below. 1161 5.2.1. Insert 1163 The "insert" object contains the following members: 1164 "op": "insert" required 1165 "table":
required 1166 "row": required 1167 "uuid-name": optional 1169 The corresponding result object contains the following member: 1171 "uuid": 1173 The operation inserts "row" into "table". If "row" does not specify 1174 values for all the columns in "table", those columns receive default 1175 values. The default value for a column depends on its type. The 1176 default for a column whose specifies a "min" of 0 is an empty 1177 set or empty map. Otherwise, the default is a single value or a 1178 single key-value pair, whose value(s) depend on its : 1180 o "integer" or "real": 0 1182 o "boolean": false 1184 o "string": "" (the empty string) 1186 o "uuid": 00000000-0000-0000-0000-000000000000 1188 The new row receives a new, randomly generated UUID. If "uuid-name" 1189 is supplied, then it is an error if is not unique among the 1190 "uuid-name"s supplied on all the "insert" operations within this 1191 transaction. The UUID for the new row is returned as the "uuid" 1192 member of the result. 1194 The errors that may be returned are as follows: 1196 "error": "duplicate uuid-name" 1197 The same "uuid-name" appears on another "insert" operation within 1198 this transaction. 1200 "error": "constraint violation" 1201 One of the values in "row" does not satisfy the immediate 1202 constraints for its column's . This error will occur 1203 for columns that are not explicitly set by "row" if the default 1204 value does not satisfy the column's constraints. 1206 5.2.2. Select 1208 The "select" object contains the following members: 1209 "op": "select" required 1210 "table":
required 1211 "where": [*] required 1212 "columns": [*] optional 1214 The corresponding result object contains the following member: 1216 "rows": [*] 1218 The operation searches "table" for rows that match all the conditions 1219 specified in "where". If "where" is an empty array, every row in 1220 "table" is selected. 1222 The "rows" member of the result is an array of objects. Each object 1223 corresponds to a matching row, with each column specified in 1224 "columns" as a member, the column's name as the member name and its 1225 value as the member value. If "columns" is not specified, all the 1226 table's columns are included. If two rows of the result have the 1227 same values for all included columns, only one copy of that row is 1228 included in "rows". Specifying "_uuid" within "columns" will avoid 1229 dropping duplicates, since every row has a unique UUID. 1231 The ordering of rows within "rows" is unspecified. 1233 5.2.3. Update 1235 The "update" object contains the following members: 1236 "op": "update" required 1237 "table":
required 1238 "where": [*] required 1239 "row": required 1241 The corresponding result object contains the following member: 1243 "count": 1245 The operation updates rows in a table. It searches "table" for rows 1246 that match all the conditions specified in "where". For each 1247 matching row, it changes the value of each column specified in "row" 1248 to the value for that column specified in "row". The "_uuid" and 1249 "_version" columns of a table may not be directly updated with this 1250 operation. Columns designated read-only in the schema also may not 1251 be updated. 1253 The "count" member of the result specifies the number of rows that 1254 matched. 1256 The error that may be returned is: 1258 "error": "constraint violation" 1259 One of the values in "row" does not satisfy the immediate 1260 constraints for its column's . 1262 5.2.4. Mutate 1264 The "mutate" object contains the following members: 1266 "op": "mutate" required 1267 "table":
required 1268 "where": [*] required 1269 "mutations": [*] required 1271 The corresponding result object contains the following member: 1273 "count": 1275 The operation mutates rows in a table. It searches "table" for rows 1276 that match all the conditions specified in "where". For each 1277 matching row, it mutates its columns as specified by each 1278 in "mutations", in the order specified. 1280 The "_uuid" and "_version" columns of a table may not be directly 1281 modified with this operation. Columns designated read-only in the 1282 schema also may not be updated. 1284 The "count" member of the result specifies the number of rows that 1285 matched. 1287 The errors that may be returned are: 1289 "error": "domain error" 1290 The result of the mutation is not mathematically defined, e.g. 1291 division by zero. 1293 "error": "range error" 1294 The result of the mutation is not representable within the 1295 database's format, e.g. an integer result outside the range 1296 INT64_MIN...INT64_MAX or a real result outside the range 1297 -DBL_MAX...DBL_MAX. 1299 "error": "constraint violation" 1300 The mutation caused the column's value to violate a constraint, 1301 e.g. it caused a column to have more or fewer values than are 1302 allowed, an arithmetic operation caused a set or map to have 1303 duplicate elements, or it violated a constraint specified by a 1304 column's . 1306 5.2.5. Delete 1308 The "delete" object contains the following members: 1309 "op": "delete" required 1310 "table":
required 1311 "where": [*] required 1313 The corresponding result object contains the following member: 1315 "count": 1317 The operation deletes all the rows from "table" that match all the 1318 conditions specified in "where". The "count" member of the result 1319 specifies the number of deleted rows. 1321 5.2.6. Wait 1323 The "wait" object contains the following members: 1324 "op": "wait" required 1325 "timeout": optional 1326 "table":
required 1327 "where": [*] required 1328 "columns": [*] required 1329 "until": "==" or "!=" required 1330 "rows": [*] required 1332 There is no corresponding result object. 1334 The operation waits until a condition becomes true. 1336 If "until" is "==", it checks whether the query on "table" specified 1337 by "where" and "columns", which is evaluated in the same way as 1338 specified for "select", returns the result set specified by "rows". 1339 If it does, then the operation completes successfully. Otherwise, 1340 the entire transaction rolls back. It is automatically restarted 1341 later, after a change in the database makes it possible for the 1342 operation to succeed. The client will not receive a response until 1343 the operation permanently succeeds or fails. 1345 If "until" is "!=", the sense of the test is negated. That is, as 1346 long as the query on "table" specified by "where" and "columns" 1347 returns "rows", the transaction will be rolled back and restarted 1348 later. 1350 If "timeout" is specified, then the transaction aborts after the 1351 specified number of milliseconds. The transaction is guaranteed to 1352 be attempted at least once before it aborts. A "timeout" of 0 will 1353 abort the transaction on the first mismatch. 1355 The errors that may be returned are: 1357 "error": "not supported" 1358 One or more of the columns in this table do not support triggers. 1359 This error will not occur if "timeout" is 0. 1361 "error": "timed out" 1362 The "timeout" was reached before the transaction was able to 1363 complete. 1365 5.2.7. Commit 1367 The "commit" object contains the following members: 1368 "op": "commit" required 1369 "durable": required 1371 There is no corresponding result object. 1373 If "durable" is specified as true, then the transaction, if it 1374 commits, will be stored durably (to disk) before the reply is sent to 1375 the client. 1377 The error that may be returned is: 1379 "error": "not supported" 1380 When "durable" is true, this database implementation does not 1381 support durable commits. 1383 5.2.8. Abort 1385 The "abort" object contains the following member: 1386 "op": "abort" required 1388 There is no corresponding result object (the operation never 1389 succeeds). 1391 The operation aborts the entire transaction with an error. This may 1392 be useful for testing. 1394 The error that will be returned is: 1396 "error": " aborted" 1397 This operation always fails with this error. 1399 5.2.9. Comment 1401 The "comment" object contains the following members: 1402 "op": "comment" required 1403 "comment": required 1405 There is no corresponding result object. 1407 The operation provides information to a database administrator on the 1408 purpose of a transaction. The OVSDB server, for example, adds 1409 comments in transactions that modify the database to the database 1410 journal. 1412 5.2.10. Assert 1414 The assert object contains the following members: 1415 "op": "assert" required 1416 "lock": required 1418 Result object has no members. 1420 The assert operation causes the transaction to be aborted if the 1421 client does not own the lock named . 1423 The error that may be returned is: 1425 "error": "not owner" 1426 The client does not own the named lock. 1428 6. IANA Considerations 1430 This document requests the assignment of a TCP port in the User Port 1431 range. The value that has been used in the past is 6632. 1433 7. Security Considerations 1435 The main security issue that needs to be addressed for the OVSDB 1436 protocol is the authentication, integrity, and privacy of 1437 communications between a client and server implementing this 1438 protocol. To provide such protection, an OVSDB connection SHOULD be 1439 secured using Transport Layer Security (TLS) [RFC5246]. The precise 1440 details of how clients and servers authenticate each other is highly 1441 dependent on the operating environment. It is often the case that 1442 OVSDB clients and servers operate in a tightly controlled 1443 environment, e.g., on machines in a single data center where they 1444 communicate on a isolated management network. 1446 8. Acknowledgements 1448 Thanks to Jeremy Stribling and Justin Pettit for their helpful input 1449 to this document. 1451 9. References 1452 9.1. Normative References 1454 [DCE] "DCE: Remote Procedure Call", Open Group CAE 1455 Specification C309, ISBN 1-85912-041-5, August 1994. 1457 [JSON-RPC] 1458 "JSON-RPC Specification, Version 1.0", 1459 . 1461 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1462 Requirement Levels", BCP 14, RFC 2119, March 1997. 1464 [RFC4627] Crockford, D., "The application/json Media Type for 1465 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 1467 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1468 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1470 9.2. Informative References 1472 [DB-SCHEMA] 1473 "Open vSwitch Database Schema", 1474 . 1476 [OF-SPEC] "OpenFlow Switch Specification, version 1.3", . 1480 [OVS] "Open vSwitch", . 1482 Authors' Addresses 1484 Ben Pfaff 1485 VMware, Inc. 1486 3401 Hillview Ave. 1487 Palo Alto, CA 94304 1488 USA 1490 Email: blp@nicira.com 1491 Bruce Davie (editor) 1492 VMware, Inc. 1493 3401 Hillview Ave. 1494 Palo Alto, CA 94304 1495 USA 1497 Email: bsd@nicira.com