idnits 2.17.1 draft-pfaff-ovsdb-proto-04.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 : ---------------------------------------------------------------------------- No issues found here. 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 (October 3, 2013) is 3852 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: 2 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: April 6, 2014 October 3, 2013 7 The Open vSwitch Database Management Protocol 8 draft-pfaff-ovsdb-proto-04 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. The Open vSwitch project includes open source OVSDB client 20 and server implementations. 22 Status of this Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on April 6, 2014. 39 Copyright Notice 41 Copyright (c) 2013 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 3 58 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 59 2. System Overview . . . . . . . . . . . . . . . . . . . . . . . 4 60 3. OVSDB Structure . . . . . . . . . . . . . . . . . . . . . . . 5 61 3.1. JSON Usage . . . . . . . . . . . . . . . . . . . . . . . . 6 62 3.2. Schema Format . . . . . . . . . . . . . . . . . . . . . . 7 63 4. Wire Protocol . . . . . . . . . . . . . . . . . . . . . . . . 12 64 4.1. RPC Methods . . . . . . . . . . . . . . . . . . . . . . . 12 65 4.1.1. List Databases . . . . . . . . . . . . . . . . . . . . 12 66 4.1.2. Get Schema . . . . . . . . . . . . . . . . . . . . . . 13 67 4.1.3. Transact . . . . . . . . . . . . . . . . . . . . . . . 13 68 4.1.4. Cancel . . . . . . . . . . . . . . . . . . . . . . . . 16 69 4.1.5. Monitor . . . . . . . . . . . . . . . . . . . . . . . 16 70 4.1.6. Update Notification . . . . . . . . . . . . . . . . . 18 71 4.1.7. Monitor Cancellation . . . . . . . . . . . . . . . . . 19 72 4.1.8. Lock Operations . . . . . . . . . . . . . . . . . . . 19 73 4.1.9. Locked Notification . . . . . . . . . . . . . . . . . 21 74 4.1.10. Stolen Notification . . . . . . . . . . . . . . . . . 21 75 4.1.11. Echo . . . . . . . . . . . . . . . . . . . . . . . . . 22 76 5. Database Operations . . . . . . . . . . . . . . . . . . . . . 22 77 5.1. Notation . . . . . . . . . . . . . . . . . . . . . . . . . 22 78 5.2. Operations . . . . . . . . . . . . . . . . . . . . . . . . 26 79 5.2.1. Insert . . . . . . . . . . . . . . . . . . . . . . . . 26 80 5.2.2. Select . . . . . . . . . . . . . . . . . . . . . . . . 27 81 5.2.3. Update . . . . . . . . . . . . . . . . . . . . . . . . 28 82 5.2.4. Mutate . . . . . . . . . . . . . . . . . . . . . . . . 29 83 5.2.5. Delete . . . . . . . . . . . . . . . . . . . . . . . . 30 84 5.2.6. Wait . . . . . . . . . . . . . . . . . . . . . . . . . 30 85 5.2.7. Commit . . . . . . . . . . . . . . . . . . . . . . . . 31 86 5.2.8. Abort . . . . . . . . . . . . . . . . . . . . . . . . 31 87 5.2.9. Comment . . . . . . . . . . . . . . . . . . . . . . . 31 88 5.2.10. Assert . . . . . . . . . . . . . . . . . . . . . . . . 32 89 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 32 90 7. Security Considerations . . . . . . . . . . . . . . . . . . . 32 91 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 33 92 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 33 93 9.1. Normative References . . . . . . . . . . . . . . . . . . . 33 94 9.2. Informative References . . . . . . . . . . . . . . . . . . 33 95 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 33 97 1. Introduction 99 In virtualized server environments, it is typically required to use a 100 vswitch (virtual switch) to forward traffic between different virtual 101 machines (VMs) on the same physical host, and between VMs and the 102 physical network. Open vSwitch [OVS] is an open source software 103 switch designed to be used as a vswitch in such environments. Open 104 vSwitch (OVS) is open to programmatic extension and control using 105 OpenFlow [OF-SPEC] and the OVSDB (Open vSwitch Database) management 106 protocol. This document defines the OVSDB management protocol. The 107 Open vSwitch project includes open source OVSDB client and server 108 implementations. 110 The OVSDB management protocol uses JSON[RFC4627] for its wire format, 111 and is based on JSON-RPC version 1.0 [JSON-RPC]. 113 The schema of the Open vSwitch database is documented in [DB-SCHEMA]. 114 This document specifies the protocol for interacting with that 115 database for the purposes of managing and configuring Open vSwitch 116 instances. The protocol specified in this document also provides 117 means for discovering the schema in use, as described in 118 Section 4.1.2. 120 The OVSDB management protocol is intended to allow programmatic 121 access to the Open vSwitch database as documented in [DB-SCHEMA]. 122 This database holds the configuration for one Open vSwitch daemon. 123 As currently defined, this information describes the switching 124 behavior of a virtual switch and does not describe the behavior or 125 configuration of a routing system. In the event that the schema is 126 extended in a future release to cover elements of the routing system, 127 implementers and operators need to be aware of the work of the IETF's 128 I2RS working group that specifies protocols and data models for real- 129 time or event driven interaction with the routing system. 131 1.1. Requirements Language 133 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 134 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 135 document are to be interpreted as described in[RFC2119]. 137 1.2. Terminology 139 UUID: Universally Unique Identifier. A 128-bit identifier that is 140 unique in space and time [DCE]. 142 OVS: Open vSwitch. An open source virtual switch. 144 OVSDB: The database that is used for the purpose of configuring 145 OVS instances. 147 JSON: Javascript Object Notation [RFC4627]. 149 JSON-RPC: JSON Remote Procedure Call [JSON-RPC]. 151 Durable: Reliably written to non-volatile storage (e.g. disk). 152 OVSDB supports the option to specify whether transactions are 153 durable or not. 155 Note that the JSON specification [RFC4627] provides precise 156 definitions of a number of important terms such as JSON values, 157 objects, arrays, numbers, and strings. In all cases, this document 158 uses the definitions from [RFC4627]. 160 2. System Overview 162 Figure 1 illustrates the main components of Open vSwitch and the 163 interfaces to a control and management cluster. An OVS instance 164 comprises a database server (ovsdb-server), a vswitch daemon (ovs- 165 vswitchd), and, optionally, a module that performs fast path 166 forwarding. The "management and control cluster" consists of some 167 number of managers and controllers. Managers use the OVSDB 168 management protocol to manage OVS instances. An OVS instance is 169 managed by at least one manager. Controllers use OpenFlow to install 170 flow state in OpenFlow switches. An OVS instance can support 171 multiple logical datapaths, referred to as bridges. There is at 172 least one controller for each OpenFlow bridge. 174 The OVSDB management interface is used to perform management and 175 configuration operations on the OVS instance. Compared to OpenFlow, 176 OVSDB management operations occur at a relatively long timescale. 177 Examples of operations that are supported by OVSDB include: 179 o Creation, modification and deletion of OpenFlow datapaths 180 (bridges), of which there may be many in a single OVS instance; 182 o Configuration of the set of controllers to which an OpenFlow 183 datapath should connect; 185 o Configuration of the set of managers to which the OVSDB server 186 should connect; 188 o Creation, modification and deletion of ports on OpenFlow 189 datapaths; 191 o Creation, modification and deletion of tunnel interfaces on 192 OpenFlow datapaths; 194 o Creation, modification and deletion of queues; 196 o Configuration of QoS (quality of service) policies, and attachment 197 of those policies to queues; 199 o Collection of statistics. 201 OVSDB does not perform per-flow operations, leaving those instead to 202 OpenFlow. 204 +----------------------+ 205 | Control & | 206 | Management | 207 | Cluster | 208 +----------------------+ 209 | \ 210 | OVSDB \ OpenFlow 211 | Mgmt \ 212 | \ 213 +============================================+ 214 | +--------------+ +--------------+ | 215 | | | | | | 216 | | ovsdb-server |-------| ovs-vswitchd | | 217 | | | | | | 218 | +--------------+ +--------------+ | 219 | | | 220 | +----------------+ | 221 | | Forwarding Path| | 222 | +----------------+ | 223 +============================================+ 225 Figure 1: Open vSwitch Interfaces 227 Further information about the usage of the OVSDB management protocol 228 is provided in [DB-SCHEMA]. 230 3. OVSDB Structure 232 This section outlines the overall structure of databases in OVSDB. 233 As described here, the database is reasonably generic. For the 234 complete and current description of the database schema as used in 235 OVS, refer to [DB-SCHEMA]. See also Section 4.1.2 for information on 236 how the OVSDB protocol may be used to discover the schema currently 237 in use. 239 3.1. JSON Usage 241 OVSDB uses JSON [RFC4627] for both its schema format and its wire 242 protocol format. The JSON implementation in Open vSwitch has the 243 following limitations: 245 o Null bytes (\u0000) SHOULD NOT be used in strings. 247 o Only UTF-8 encoding is supported. 249 The descriptions below use the following shorthand notations for JSON 250 values. Terminology follows [RFC4627]. 252 A JSON string. Any Unicode string is allowed. 253 Implementations SHOULD disallow null bytes. 255 A JSON string matching [a-zA-Z_][a-zA-Z0-9_]*. s that 256 begin with _ are reserved to the implementation and MUST NOT be 257 used by the user. 259 A JSON string that contains a version number that 260 matches [0-9]+\.[0-9]+\.[0-9]+ 262 A JSON true or false value. 264 A JSON number. 266 A JSON number with an integer value, within the range 267 -(2**63)...+(2**63)-1. 269 Any JSON value. 271 Any JSON value except null. 273 A JSON object with the following members: 275 "error": required 276 "details": optional 278 The value of the "error" member is a short string, specified in 279 this document, that broadly indicates the class of the error. 280 Most "error" strings are specific to contexts described 281 elsewhere in this document, but the following "error" strings 282 may appear in any context where an is permitted: 284 "error": "resources exhausted" The operation requires more 285 resources (memory, disk, CPU, etc.) than are currently 286 available to the database server. 288 "error": "I/O error" Problems accessing the disk, network, or 289 other required resources prevented the operation from 290 completing. 292 Database implementations MAY use "error" strings not specified 293 in this document to indicate errors that do not fit into any of 294 the specified categories. Optionally, an MAY include a 295 "details" member, whose value is a string that describes the 296 error in more detail for the benefit of a human user or 297 administrator. This document does not specify the format or 298 content of the "details" string. An MAY also have 299 other members that describe the error in more detail. This 300 document does not specify the names or values of these members. 302 3.2. Schema Format 304 An Open vSwitch configuration database consists of a set of tables, 305 each of which has a number of columns and zero or more rows. A 306 schema for the database is represented by , as 307 described below. 309 310 A JSON object with the following members: 312 "name": required 313 "version": required 314 "cksum": optional 315 "tables": {: , ...} required 317 The "name" identifies the database as a whole. It must be 318 provided to most JSON-RPC requests to identify the database being 319 operated on. The value of "tables" is a JSON object whose names 320 are table names and whose values are s. 322 The "version" reports the version of the database schema. It is 323 REQUIRED to be present. Open vSwitch semantics for "version" are 324 described in [DB-SCHEMA]. Other schemas may use it differently. 326 The "cksum" optionally reports an implementation-defined checksum 327 for the database schema. Its use is primarily as a tool for 328 schema developers, and clients SHOULD ignore it. 330 The value of "tables" is a JSON object whose names are table names 331 and whose values are s. 333 334 A JSON object with the following members: 336 "columns": {: , ...} required 337 "maxRows": optional 338 "isRoot": optional 339 "indexes": [*] optional 341 The value of "columns" is a JSON object whose names are column 342 names and whose values are s. 344 Every table has the following columns whose definitions are not 345 included in the schema: 347 "_uuid": This column, which contains exactly one UUID value, is 348 initialized to a random value by the database engine when it 349 creates a row. It is read-only, and its value never changes 350 during the lifetime of a row. 352 "_version": Like "_uuid", this column contains exactly one UUID 353 value, initialized to a random value by the database engine 354 when it creates a row, and it is read-only. However, its value 355 changes to a new random value whenever any other field in the 356 row changes. Furthermore, its value is ephemeral: when the 357 database is closed and reopened, or when the database process 358 is stopped and then started again, each "_version" also changes 359 to a new random value. 361 If "maxRows" is specified, as a positive integer, it limits the 362 maximum number of rows that may be present in the table. This is 363 a "deferred" constraint, enforced only at transaction commit time 364 (see the "transact" request below). If "maxRows" is not 365 specified, the size of the table is limited only by the resources 366 available to the database server. "maxRows" constraints are 367 enforced after unreferenced rows are deleted from tables with a 368 false "isRoot". 370 The "isRoot" boolean is used to determine whether rows in the 371 table require strong references from other rows to avoid garbage 372 collection. (See the discussion of "strong" and "weak" references 373 below in the description of base types.) If "isRoot" is specified 374 as true, then rows in the table exist independent of any 375 references (they can be thought of as part of the "root set" in a 376 garbage collector). If "isRoot" is omitted or specified as false, 377 then any given row in the table may exist only when there is at 378 least one reference to it, with refType "strong", from a different 379 row (in the same table or a different table). This is a 380 "deferred" action: unreferenced rows in the table are deleted just 381 before transaction commit. 383 For compatibility with schemas created before "isRoot" was 384 introduced, if "isRoot" is omitted or false in every in a given , then every table is part of 386 the root set. 388 If "indexes" is specified, it must be an array of zero or more 389 s. A is an array of one or more strings, 390 each of which names a column. Each is a set of 391 columns whose values, taken together within any given row, must be 392 unique within the table. This is a "deferred" constraint, 393 enforced only at transaction commit time, after unreferenced rows 394 are deleted and dangling weak references are removed. Ephemeral 395 columns may not be part of indexes. 397 398 A JSON object with the following members: 400 "type": required 401 "ephemeral": optional 402 "mutable": optional 404 The "type" specifies the type of data stored in this column. 406 If "ephemeral" is specified as true, then this column's values are 407 not guaranteed to be durable; they may be lost when the database 408 restarts. A column whose type (either key or value) is a strong 409 reference to a table that is not part of the root set is always 410 durable, regardless of this value. (Otherwise, restarting the 411 database could lose entire rows.) 413 If "mutable" is specified as false, then this column's values may 414 not be modified after they are initially set with the "insert" 415 operation. 417 418 The type of a database column. Either an or a JSON 419 object that describes the type of a database column, with the 420 following members: 422 "key": required 423 "value": optional 424 "min": optional 425 "max": or "unlimited" optional 427 If "min" or "max" is not specified, each defaults to 1. If "max" 428 is specified as "unlimited", then there is no specified maximum 429 number of elements, although the implementation will enforce some 430 limit. After considering defaults, "min" must be exactly 0 or 431 exactly 1, "max" must be at least 1, and "max" must be greater 432 than or equal to "min". 434 If "min" and "max" are both 1 and "value" is not specified, the 435 type is the scalar type specified by "key". 437 If "min" is not 1 or "max" is not 1, or both, and "value" is not 438 specified, the type is a set of scalar type "key". 440 If "value" is specified, the type is a map from type "key" to type 441 "value". 443 444 The type of a key or value in a database column. Either an 445 or a JSON object with the following members: 447 "type": required 448 "enum": optional 449 "minInteger": optional, integers only 450 "maxInteger": optional, integers only 451 "minReal": optional, reals only 452 "maxReal": optional, reals only 453 "minLength": optional, strings only 454 "maxLength": optional, strings only 455 "refTable": optional, uuids only 456 "refType": "strong" or "weak" optional, only with "refTable" 458 An by itself is equivalent to a JSON object with a 459 single member "type" whose value is the . 461 "enum" may be specified as a whose type is a set of one or 462 more values specified for the member "type". If "enum" is 463 specified, then the valid values of the are limited to 464 those in the . 466 "enum" is mutually exclusive with the following constraints. 468 If "type" is "integer", then "minInteger" or "maxInteger" or both 469 may also be specified, restricting the valid integer range. If 470 both are specified, then the maxInteger must be greater than or 471 equal to minInteger. 473 If "type" is "real", then "minReal" or "maxReal" or both may also 474 be specified, restricting the valid real range. If both are 475 specified, then the maxReal must be greater than or equal to 476 minReal. 478 If "type" is "string", then "minLength" and "maxLength" or both 479 may be specified, restricting the valid length of value strings. 480 If both are specified, then maxLength must be greater than or 481 equal to minLength. String length is measured in characters. 483 If "type" is "uuid", then "refTable", if present, must be the name 484 of a table within this database. If "refTable" is specified, then 485 "refType" may also be specified. If "refTable" is set, the effect 486 depends on "refType": 488 * If "refType" is "strong" or if "refType" is omitted, the 489 allowed UUIDs are limited to UUIDs for rows in the named table. 491 * If "refType" is "weak", then any UUIDs are allowed, but UUIDs 492 that do not correspond to rows in the named table will be 493 automatically deleted. When this situation arises in a map, 494 both the key and the value will be deleted from the map. 496 "refTable" constraints are "deferred" constraints: they are 497 enforced only at transaction commit time (see the "transact" 498 request below). The other constraints on are 499 "immediate", enforced immediately by each operation. 501 502 One of the strings "integer", "real", "boolean", "string", or 503 "uuid", representing the specified scalar type. 505 4. Wire Protocol 507 The database wire protocol is implemented in JSON-RPC 1.0 [JSON-RPC]. 508 While the spec of JSON-RPC allows a range of transports, 509 implementations of this specification SHOULD operate directly over 510 TCP. See Section 6 for discussion of the TCP port. 512 4.1. RPC Methods 514 The following subsections describe the RPC methods that are 515 supported. As described in the JSON-RPC 1.0 specification, each 516 request comprises a string containing the name of the method, a 517 (possibly null) array of parameters to pass to the method, and a 518 request ID, which can be used to match the response to the request. 519 Each response comprises a result object (non-null in the event of a 520 successful invocation), an error object (non-null in the event of an 521 error), and the ID of the matching request. More details on each 522 method, its parameters and results are described below. 524 An OVSDB server MUST implement all of the following methods. An 525 OVSDB client MUST implement the "Echo" method, and is otherwise free 526 to implement whichever methods suit the implementation's needs. 528 The operations that may be performed on the OVS database using these 529 methods (e.g., the "Transact" method) are described in Section 5. 531 4.1.1. List Databases 533 This operation retrieves an array whose elements are the names of the 534 databases that can be accessed over this management protocol 535 connection. 537 The request object contains the following members: 539 o "method": "list_dbs" 541 o "params": [] 543 o "id": 545 The response object contains the following members: 547 o "result": [,...] 549 o "error": null 551 o "id": same "id" as request 553 4.1.2. Get Schema 555 This operation retrieves a that describes hosted 556 database . 558 The request object contains the following members: 560 o "method": "get_schema" 562 o "params": [] 564 o "id": 566 The response object contains the following members: 568 o "result": 570 o "error": null 572 o "id": same "id" as request 574 In the event that the database named in the request does not exist, 575 the server sends a JSON-RPC error response of the following form: 577 o "result": null 579 o "error": "unknown database" 581 o "id": same "id" as request 583 4.1.3. Transact 585 This RPC method causes the database server to execute a series of 586 operations in the specified order on a given database. 588 The request object contains the following members: 590 o "method": "transact" 592 o "params": [, *] 594 o "id": 596 The value of "id" MUST be unique among all in-flight transactions 597 within the current JSON-RPC session. Otherwise, the server may 598 return a JSON-RPC error. 600 The "params" array for this method consists of a that 601 identifies the database to which the transaction applies, followed by 602 zero or more JSON objects, each of which represents a single database 603 operation. Section 5 describes the valid operations. The database 604 server executes each of the specified operations in the specified 605 order, except that if an operation fails, then the remaining 606 operations are not executed. The set of operations is executed as a 607 single atomic, consistent, isolated transaction. The transaction is 608 committed if and only if every operation succeeds. Durability of the 609 commit is not guaranteed unless the "commit" operation, with 610 "durable" set to true, is included in the operation set. See 611 Section 5 for more discussion of the database operations. 613 The response object contains the following members: 615 o "result": [*] 617 o "error": null 619 o "id": same "id" as request 621 Regardless of whether errors occur in the database operations, the 622 response is always a JSON-RPC response with null "error" and a 623 "result" member that is an array with the same number of elements as 624 "params". Each element of the "result" array corresponds to the same 625 element of the "params" array. The "result" array elements may be 626 interpreted as follows: 628 o A JSON object that does not contain an "error" member indicates 629 that the operation completed successfully. The specific members 630 of the object are specified below in the descriptions of 631 individual operations. Some operations do not produce any 632 results, in which case the object will have no members. 634 o An indicates that the matching operation completed with an 635 error. 637 o A JSON null value indicates that the operation was not attempted 638 because a prior operation failed. 640 In general, "result" contains some number of successful results, 641 possibly followed by an error, in turn followed by enough JSON null 642 values to match the number of elements in "params". There is one 643 exception: if all of the operations succeed, but the results cannot 644 be committed, then "result" will have one more element than "params", 645 with the additional element being an . In this case, the 646 possible "error" strings include the following: 648 "error": "referential integrity violation" 650 When the commit was attempted, a column's value referenced the 651 UUID for a row that did not exist in the table named by the 652 column's key or value "refTable" that has a "refType" 653 of "strong". (This can be caused by inserting a row that 654 references a nonexistent row, by deleting a row that is still 655 referenced by another row, by specifying the UUID for a row in the 656 wrong table, and other ways.) 658 "error": "constraint violation" 660 A number of situations can arise in which the attempted commit 661 would lead to a constraint on the database being violated. (See 662 Section 3.2 for more discussion of constraints.) These situations 663 include: 665 * The number of rows in a table exceeds the maximum number 666 permitted by the table's "maxRows" value. 668 * Two or more rows in a table had the same values in the columns 669 that comprise an index. 671 * A column with a key or value "refTable" whose 672 "refType" is "weak" became empty due to deletion(s), and this 673 column is not allowed to be empty because its has a 674 "min" of 1. Such deletions may be the result of rows that it 675 referenced being deleted (or never having existed, if the 676 column's row was inserted within the transaction). 678 "error": "resources exhausted" 680 The operation requires more resources (memory, disk, CPU, etc.) 681 than are currently available to the database server. 683 "error": "I/O error" 685 Problems accessing the disk, network, or other required resources 686 prevented the operation from completing. 688 If "params" contains one or more "wait" operations, then the 689 transaction may take an arbitrary amount of time to complete. The 690 database implementation MUST be capable of accepting, executing, and 691 replying to other transactions and other JSON-RPC requests while a 692 transaction or transactions containing "wait" operations are 693 outstanding on the same or different JSON-RPC sessions. 695 4.1.4. Cancel 697 The "cancel" method is a JSON-RPC notification, i.e. no matching 698 response is provided. It instructs the database server to 699 immediately complete or cancel the "transact" request whose "id" is 700 the same as the notification's "params" value. The notification 701 object has the following members: 703 o "method": "cancel" 705 o "params": [the "id" for an outstanding request] 707 o "id": null 709 If the "transact" request can be completed immediately, then the 710 server sends a response in the form described for "transact", above 711 (Section 4.1.3). Otherwise, the server sends a JSON-RPC error 712 response of the following form: 714 o "result": null 716 o "error": "canceled" 718 o "id": the "id" member of the canceled request. 720 The "cancel" notification itself has no reply. 722 4.1.5. Monitor 724 The "monitor" request enables a client to replicate tables or subsets 725 of tables within an OVSDB database by requesting notifications of 726 changes to those tables and by receiving the complete initial state 727 of a table or a subset of a table. The request object has the 728 following members: 730 o "method": "monitor" 732 o "params": [, , ] 734 o "id": 736 The parameter is used to match subsequent update 737 notifications (see below) to this request. The 738 object maps the name of the table to be monitored to an array of 739 objects. 741 Each is an object with the following members: 743 "columns": [*] optional 744 "select": optional 746 The columns, if present, define the columns within the table to be 747 monitored. is an object with the following members: 748 "initial": optional 749 "insert": optional 750 "delete": optional 751 "modify": optional 753 The contents of this object specify how the columns or table are to 754 be monitored, as explained in more detail below. 756 The response object has the following members: 758 o "result": 760 o "error": null 762 o "id": same "id" as request 764 The object is described in detail in Section 4.1.6. 765 It contains the contents of the tables for which "initial" rows are 766 selected. If no tables' initial contents are requested, then 767 "result" is an empty object. 769 Subsequently, when changes to the specified tables are committed, the 770 changes are automatically sent to the client using the "update" 771 monitor notification (see Section 4.1.6). This monitoring persists 772 until the JSON-RPC session terminates or until the client sends a 773 "monitor_cancel" JSON-RPC request. 775 Each specifies one or more columns and the manner 776 in which the columns (or the entire table) are to be monitored. The 777 "columns" member specifies the columns whose values are monitored. 778 It MUST NOT contain duplicates. If "columns" is omitted, all columns 779 in the table, except for "_uuid", are monitored. The circumstances 780 in which an "update" notification is sent for a row within the table 781 are determined by : 783 o If "initial" is omitted or true, every row in the table is sent as 784 part of the response to the "monitor" request. 786 o If "insert" is omitted or true, "update" notifications are sent 787 for rows newly inserted into the table. 789 o If "delete" is omitted or true, "update" notifications are sent 790 for rows deleted from the table. 792 o If "modify" is omitted or true, "update" notifications are sent 793 whenever a row in the table is modified. 795 If there is more than one in an array of them, then 796 each in the array should specify both "columns" and 797 "select", and the "columns" MUST be non-overlapping sets. 799 4.1.6. Update Notification 801 The "update" notification is sent by the server to the client to 802 report changes in tables that are being monitored following a 803 "monitor" request as described above. The notification has the 804 following members: 806 o "method": "update" 808 o "params": [, ] 810 o "id": null 812 The in "params" is the same as the value passed as the 813 in "params" for the corresponding "monitor" request. 814 is an object that maps from a table name to a . A is an object that maps from the row's UUID 816 to a object. A is an object with the 817 following members: 818 "old": present for "delete" and "modify" updates 819 "new": present for "initial", "insert", and "modify" updates 821 The format of is described in Section 5.1. 823 Each table in which one or more rows has changed (or whose initial 824 view is being presented) is represented in "updates". Each row that 825 has changed (or whose initial view is being presented) is represented 826 in its as a member with its name taken from the row's 827 _uuid member. The corresponding value is a : 829 o The "old" member is present for "delete" and "modify" updates. 830 For "delete" updates, each monitored column is included. For 831 "modify" updates, the prior value of each monitored column whose 832 value has changed is included (monitored columns that have not 833 changed are represented in "new"). 835 o The "new" member is present for "initial", "insert", and "modify" 836 updates. For "initial" and "insert" updates, each monitored 837 column is included. For "modify" updates, the new value of each 838 monitored column is included. 840 Note that initial views of rows are not presented in update 841 notifications, but in the response object to the monitor request. 842 The formatting of the object is the same in either 843 case however. 845 4.1.7. Monitor Cancellation 847 The "monitor_cancel" request cancels a previously issued monitor 848 request. The request object members are: 850 o "method": "monitor_cancel" 852 o "params": [] 854 o "id": 856 The in "params" matches the in "params" for 857 the ongoing "monitor" request that is to be canceled. No more 858 "update" messages will be sent for this table monitor. The response 859 to this request has the following members: 861 o "result": {} 863 o "error": null 865 o "id": the request "id" member 867 In the event that a monitor cancellation request refers to an unknown 868 monitor request, an error response with the following members is 869 returned: 871 o "result": null 873 o "error": "unknown monitor" 875 o "id": the request "id" member 877 4.1.8. Lock Operations 879 Three RPC methods, "lock", "steal", and "unlock", provide support to 880 clients to perform locking operations on the database. The database 881 server supports an arbitrary number of locks, each of which is 882 identified by a client-defined id. At any given time, each lock may 883 have at most one owner. The precise usage of a lock is determined by 884 the client. For example, a set of clients may agree that a certain 885 table can only be written by the owner of a certain lock. OVSDB 886 itself does not enforce any restrictions on how locks are used - it 887 simply ensures that a lock has at most one owner. 889 The RPC request objects have the following members: 891 o "method": "lock", "steal", or "unlock" 893 o "params": [] 895 o "id": 897 The response depends on the request, and has the following members: 899 o "result": {"locked": boolean} for "lock" 901 o "result": {"locked": true} for "steal" 903 o "result": {} for "unlock" 905 o "error": null 907 o "id": same "id" as request 909 The three methods operate as follows: 911 o "lock": The database will assign this client ownership of the lock 912 as soon as it becomes available. When multiple clients request 913 the same lock, they will receive it in first-come, first served 914 order. 916 o "steal": The database immediately assigns this client ownership of 917 the lock. If there is an existing owner, it loses ownership. 919 o "unlock": If the client owns the lock, releases it. If the client 920 has requested ownership of the lock, this cancels the request. 922 (Closing or otherwise disconnecting a database client connection 923 unlocks all of its locks.) 925 For any given lock, the client MUST alternate "lock" or "steal" 926 operations with "unlock" operations. That is, if the previous 927 operation on a lock was "lock" or "steal", it MUST be followed by an 928 "unlock" operation, and vice versa. 930 For a "lock" operation, the "locked" member in the response object is 931 true if the lock has already been acquired, false if another client 932 holds the lock and the client's request for it was queued. In the 933 latter case, the client will be notified later with a "locked" 934 message (Section 4.1.9) when acquisition succeeds. 936 These requests complete and send a response quickly, without waiting. 938 The "locked" and "stolen" notifications (see below) report 939 asynchronous changes to ownership. 941 Note that the scope of a lock is a database server, not a database 942 hosted by that server. A client may choose to implement a naming 943 convention, such as "__", which can effectively 944 limit the scope of a lock to a particular database. 946 4.1.9. Locked Notification 948 The "locked" notification is provided to notify a client that it has 949 been granted a lock it had previously request a lock with the "lock" 950 method described above. The notification has the following members: 952 o "method": "locked" 954 o "params": [] 956 o "id": null 958 "Params" contains the name of the lock that was given in the "lock" 959 request. The notified client now owns the lock named in "params". 961 The database server sends this notification after the reply to the 962 corresponding "lock" request (but only if the "locked" member of the 963 response was false), and before the reply to the client's subsequent 964 "unlock" request. 966 4.1.10. Stolen Notification 968 The "stolen" notification is provided to notify a client, which had 969 previously obtained a lock, that another client has stolen ownership 970 of that lock. The notification has the following members: 972 o "method": "stolen" 974 o "params": [] 976 o "id": null 978 The notified client no longer owns the lock named in "params". The 979 client MUST still issue an "unlock" request before performing any 980 subsequent "lock" or "steal" operation on the lock. 982 If the client originally obtained the lock through a "lock" request, 983 then it will automatically regain the lock later after the client 984 that stole it releases it. (The database server will send the client 985 a "locked" notification at that point to let it know.) 986 If the client originally obtained the lock through a "steal" request, 987 the database server won't automatically reassign it ownership of the 988 lock when it later becomes available. To regain ownership, the 989 client must "unlock" and then "lock" or "steal" the lock again. 991 4.1.11. Echo 993 The "echo" method can be used by both clients and servers to verify 994 the liveness of a database connection. It MUST be implemented by 995 both clients and servers. The members of the request are: 997 o "method": "echo" 999 o "params": JSON array with any contents 1001 o "id": 1003 The response object has the following members: 1005 o "result": same as "params" 1007 o "error": null 1009 o "id": the request "id" member 1011 5. Database Operations 1013 This section describes the operations that may be specified in the 1014 "transact" method described in Section 4.1.3. 1016 5.1. Notation 1018 We introduce the following notation for the discussion of operations. 1020 1021 An that names a database. The valid s can be 1022 obtained using a "list_dbs" request. The is taken from 1023 the "name" member of . 1025 1026 An that names a table. 1028 1029 An that names a table column. 1031 1032 A JSON object that describes a table row or a subset of a table 1033 row. Each member is the name of a table column paired with the 1034 of that column. 1036 1037 A JSON value that represents the value of a column in a table row, 1038 one of , a , or a . 1040 1041 A JSON value that represents a scalar value for a column, one of 1042 , , , , . 1044 1045 Either an , representing a set with exactly one element, or 1046 a 2-element JSON array that represents a database set value. The 1047 first element of the array must be the string "set" and the second 1048 element must be an array of zero or more s giving the values 1049 in the set. All of the s must have the same type. 1051 1052 A 2-element JSON array that represents a database map value. The 1053 first element of the array must be the string "map" and the second 1054 element must be an array of zero or more s giving the values 1055 in the map. All of the s must have the same key and value 1056 types. 1057 (JSON objects are not used to represent because JSON only 1058 allows string names in an object.) 1060 1061 A 2-element JSON array that represents a pair within a database 1062 map. The first element is an that represents the key, the 1063 second element is an that represents the value. 1065 1066 A 2-element JSON array that represents a UUID. The first element 1067 of the array must be the string "uuid" and the second element must 1068 be a 36-character string giving the UUID in the format described 1069 by RFC 4122. For example, the following represents the 1070 UUID 550e8400-e29b-41d4-a716-446655440000: 1072 ["uuid", "550e8400-e29b-41d4-a716-446655440000"] 1074 1075 A 2-element JSON array that represents the UUID of a row inserted 1076 in an "insert" operation within the same transaction. The first 1077 element of the array must be the string "named-uuid" and the 1078 second element should be the specified as the "uuid-name" for 1079 an "insert" operation within the same transaction. For example, 1080 if an "insert" operation within this transaction specifies a 1081 "uuid-name" of "myrow", the following represents the 1082 UUID created by that operation: 1084 ["named-uuid", "myrow"] 1086 A may be used anywhere a is valid. This 1087 enables a single transaction to both insert a new row and then 1088 refer to that row using the "uuid-name" that was associated with 1089 that row when it was inserted. Note that the "uuid-name" is only 1090 meaningful within the scope of a single transaction. 1092 1093 A 3-element JSON array of the form [, , ] 1094 that represents a test on a column value. Except as otherwise 1095 specified below, MUST have the same type as . The 1096 meaning depends on the type of : 1098 integer or real 1099 must be "<", "<=", "==", "!=", ">=", ">", 1100 "includes", or "excludes". 1102 The test is true if the column's value satisfies the relation 1103 , e.g. if the column has value 1 and 1104 is 2, the test is true if is "<", "<=" or "!=", but 1105 not otherwise. 1107 "includes" is equivalent to "=="; "excludes" is equivalent to 1108 "!=". 1110 boolean or string or uuid 1111 must be "!=", "==", "includes", or "excludes". 1113 If is "==" or "includes", the test is true if the 1114 column's value equals . If is "!=" or 1115 "excludes", the test is inverted. 1117 set or map 1118 must be "!=", "==", "includes", or "excludes". 1120 If is "==", the test is true if the column's value 1121 contains exactly the same values (for sets) or pairs (for 1122 maps). If is "!=", the test is inverted. 1124 If is "includes", the test is true if the column's 1125 value contains all of the values (for sets) or pairs (for maps) 1126 in . The column's value may also contain other values 1127 or pairs. 1129 If is "excludes", the test is true if the column's 1130 value does not contain any of the values (for sets) or pairs 1131 (for maps) in . The column's value may contain other 1132 values or pairs not in . 1134 If is "includes" or "excludes", then the required 1135 type of is slightly relaxed, in that it may have fewer 1136 than the minimum number of elements specified by the column's 1137 type. If is "excludes", then the required type is 1138 additionally relaxed in that may have more than the 1139 maximum number of elements specified by the column's type. 1140 One of "<", "<=", "==", "!=", ">=", ">", "includes", 1141 "excludes". 1143 1144 One of "<", "<=", "==", "!=", ">=", ">", "includes", "excludes". 1146 1147 A 3-element JSON array of the form [, , ] 1148 that represents a change to a column value. Except as otherwise 1149 specified below, must have the same type as . The 1150 meaning depends on the type of : 1152 integer or real 1153 must be "+=", "-=", "*=", "/=" or (integer only) 1154 "%=". The value of is changed to the sum, difference, 1155 product, quotient, or remainder, respectively, of and 1156 . 1158 Constraints on are ignored when parsing . 1160 boolean or string or uuid 1161 No valid s are currently defined for these types. 1163 set 1164 Any valid for the set's element type may be applied 1165 to the set, in which case the mutation is applied to each 1166 member of the set individually. must be a scalar value 1167 of the same type as the set's element type, except that 1168 constraints are ignored when parsing . 1170 If is "insert", then each of the values in the set in 1171 is added to if it is not already present. The 1172 required type of is slightly relaxed, in that it may 1173 have fewer than the minimum number of elements specified by the 1174 column's type. 1176 If is "delete", then each of the values in the set in 1177 is removed from if it is present there. The 1178 required type is slightly relaxed in that may have more 1179 or less than the maximum number of elements specified by the 1180 column's type. 1182 map 1183 must be "insert" or "delete". 1185 If is "insert", then each of the key-value pairs in 1186 the map in is added to only if its key is not 1187 already present. The required type of is slightly 1188 relaxed, in that it may have fewer than the minimum number of 1189 elements specified by the column's type. 1191 If is "delete", then may have the same type 1192 as (a map type) or it may be a set whose element type 1193 is the same as 's key type: 1195 + If is a map, the mutation deletes each key-value 1196 pair in whose key and value equal one of the key- 1197 value pairs in . 1199 + If is a set, the mutation deletes each key-value 1200 pair in whose key equals one of the values in 1201 . 1203 For "delete", may have any number of elements, 1204 regardless of restrictions on the number of elements in 1205 . 1207 1208 One of "+=", "-=", "*=", "/=", "%=", "insert", "delete". 1210 5.2. Operations 1212 The operations that may be performed as part of a "transact" RPC 1213 request (see Section 4.1.3) are described in the following sections. 1214 Each of these operations is a JSON object that may be included as one 1215 of the elements of the "params" array that is one of the elements of 1216 the "transact" request. The details of each object, its semantics, 1217 results, and possible errors are described below. 1219 5.2.1. Insert 1221 The "insert" object contains the following members: 1223 "op": "insert" required 1224 "table":
required 1225 "row": required 1226 "uuid-name": optional 1228 The corresponding result object contains the following member: 1230 "uuid": 1232 The operation inserts "row" into "table". If "row" does not specify 1233 values for all the columns in "table", those columns receive default 1234 values. The default value for a column depends on its type. The 1235 default for a column whose specifies a "min" of 0 is an empty 1236 set or empty map. Otherwise, the default is a single value or a 1237 single key-value pair, whose value(s) depend on its : 1239 o "integer" or "real": 0 1241 o "boolean": false 1243 o "string": "" (the empty string) 1245 o "uuid": 00000000-0000-0000-0000-000000000000 1247 The new row receives a new, randomly generated UUID. If "uuid-name" 1248 is supplied, then it is an error if is not unique among the 1249 "uuid-name"s supplied on all the "insert" operations within this 1250 transaction. The UUID for the new row is returned as the "uuid" 1251 member of the result. 1253 The errors that may be returned are as follows: 1255 "error": "duplicate uuid-name" 1256 The same "uuid-name" appears on another "insert" operation within 1257 this transaction. 1259 "error": "constraint violation" 1260 One of the values in "row" does not satisfy the immediate 1261 constraints for its column's . This error will occur 1262 for columns that are not explicitly set by "row" if the default 1263 value does not satisfy the column's constraints. 1265 5.2.2. Select 1267 The "select" object contains the following members: 1269 "op": "select" required 1270 "table":
required 1271 "where": [*] required 1272 "columns": [*] optional 1274 The corresponding result object contains the following member: 1276 "rows": [*] 1278 The operation searches "table" for rows that match all the conditions 1279 specified in "where". If "where" is an empty array, every row in 1280 "table" is selected. 1282 The "rows" member of the result is an array of objects. Each object 1283 corresponds to a matching row, with each column specified in 1284 "columns" as a member, the column's name as the member name and its 1285 value as the member value. If "columns" is not specified, all the 1286 table's columns are included (including the internally generated 1287 "_uuid" and "_version" columns). If two rows of the result have the 1288 same values for all included columns, only one copy of that row is 1289 included in "rows". Specifying "_uuid" within "columns" will avoid 1290 dropping duplicates, since every row has a unique UUID. 1292 The ordering of rows within "rows" is unspecified. 1294 5.2.3. Update 1296 The "update" object contains the following members: 1297 "op": "update" required 1298 "table":
required 1299 "where": [*] required 1300 "row": required 1302 The corresponding result object contains the following member: 1304 "count": 1306 The operation updates rows in a table. It searches "table" for rows 1307 that match all the conditions specified in "where". For each 1308 matching row, it changes the value of each column specified in "row" 1309 to the value for that column specified in "row". The "_uuid" and 1310 "_version" columns of a table may not be directly updated with this 1311 operation. Columns designated read-only in the schema also may not 1312 be updated. 1314 The "count" member of the result specifies the number of rows that 1315 matched. 1317 The error that may be returned is: 1319 "error": "constraint violation" 1320 One of the values in "row" does not satisfy the immediate 1321 constraints for its column's . 1323 5.2.4. Mutate 1325 The "mutate" object contains the following members: 1326 "op": "mutate" required 1327 "table":
required 1328 "where": [*] required 1329 "mutations": [*] required 1331 The corresponding result object contains the following member: 1333 "count": 1335 The operation mutates rows in a table. It searches "table" for rows 1336 that match all the conditions specified in "where". For each 1337 matching row, it mutates its columns as specified by each 1338 in "mutations", in the order specified. 1340 The "_uuid" and "_version" columns of a table may not be directly 1341 modified with this operation. Columns designated read-only in the 1342 schema also may not be updated. 1344 The "count" member of the result specifies the number of rows that 1345 matched. 1347 The errors that may be returned are: 1349 "error": "domain error" 1350 The result of the mutation is not mathematically defined, e.g. 1351 division by zero. 1353 "error": "range error" 1354 The result of the mutation is not representable within the 1355 database's format, e.g. an integer result outside the range 1356 INT64_MIN...INT64_MAX or a real result outside the range 1357 -DBL_MAX...DBL_MAX. 1359 "error": "constraint violation" 1360 The mutation caused the column's value to violate a constraint, 1361 e.g. it caused a column to have more or fewer values than are 1362 allowed, an arithmetic operation caused a set or map to have 1363 duplicate elements, or it violated a constraint specified by a 1364 column's . 1366 5.2.5. Delete 1368 The "delete" object contains the following members: 1369 "op": "delete" required 1370 "table":
required 1371 "where": [*] required 1373 The corresponding result object contains the following member: 1375 "count": 1377 The operation deletes all the rows from "table" that match all the 1378 conditions specified in "where". The "count" member of the result 1379 specifies the number of deleted rows. 1381 5.2.6. Wait 1383 The "wait" object contains the following members: 1384 "op": "wait" required 1385 "timeout": optional 1386 "table":
required 1387 "where": [*] required 1388 "columns": [*] required 1389 "until": "==" or "!=" required 1390 "rows": [*] required 1392 There is no corresponding result object. 1394 The operation waits until a condition becomes true. 1396 If "until" is "==", it checks whether the query on "table" specified 1397 by "where" and "columns", which is evaluated in the same way as 1398 specified for "select", returns the result set specified by "rows". 1399 If it does, then the operation completes successfully. Otherwise, 1400 the entire transaction rolls back. It is automatically restarted 1401 later, after a change in the database makes it possible for the 1402 operation to succeed. The client will not receive a response until 1403 the operation permanently succeeds or fails. 1405 If "until" is "!=", the sense of the test is negated. That is, as 1406 long as the query on "table" specified by "where" and "columns" 1407 returns "rows", the transaction will be rolled back and restarted 1408 later. 1410 If "timeout" is specified, then the transaction aborts after the 1411 specified number of milliseconds. The transaction is guaranteed to 1412 be attempted at least once before it aborts. A "timeout" of 0 will 1413 abort the transaction on the first mismatch. 1415 The error that may be returned is: 1417 "error": "timed out" 1418 The "timeout" was reached before the transaction was able to 1419 complete. 1421 5.2.7. Commit 1423 The "commit" object contains the following members: 1424 "op": "commit" required 1425 "durable": required 1427 There is no corresponding result object. 1429 If "durable" is specified as true, then the transaction, if it 1430 commits, will be stored durably (to disk) before the reply is sent to 1431 the client. This operation with "durable" set to false is 1432 effectively a no-op. 1434 The error that may be returned is: 1436 "error": "not supported" 1437 When "durable" is true, this database implementation does not 1438 support durable commits. 1440 5.2.8. Abort 1442 The "abort" object contains the following member: 1443 "op": "abort" required 1445 There is no corresponding result object (the operation never 1446 succeeds). 1448 The operation aborts the entire transaction with an error. This may 1449 be useful for testing. 1451 The error that will be returned is: 1453 "error": " aborted" 1454 This operation always fails with this error. 1456 5.2.9. Comment 1458 The "comment" object contains the following members: 1459 "op": "comment" required 1460 "comment": required 1462 There is no corresponding result object. 1464 The operation provides information to a database administrator on the 1465 purpose of a transaction. The ovsdb-server implementation, for 1466 example, adds comments in transactions that modify the database to 1467 the database journal. This can be helpful in debugging, e.g. when 1468 there are multiple clients writing to a database. An example of this 1469 can be seen in the ovs-vsctl tool, a command line tool that interacts 1470 with ovsdb-server. When performing operations on the database, it 1471 includes the command that was invoked (e.g. "ovs-vsctl add-br br0") 1472 as a comment in the transaction, which can then be seen in the 1473 journal alongside the changes that were made to the tables in the 1474 database. 1476 5.2.10. Assert 1478 The assert object contains the following members: 1479 "op": "assert" required 1480 "lock": required 1482 Result object has no members. 1484 The assert operation causes the transaction to be aborted if the 1485 client does not own the lock named . 1487 The error that may be returned is: 1489 "error": "not owner" 1490 The client does not own the named lock. 1492 6. IANA Considerations 1494 IANA has assigned TCP port 6640 for this protocol. Earlier 1495 implementations of OVSDB used another port number, but compliant 1496 implementations should use the IANA-assigned number. 1498 IANA is requested to update the reference for port 6640 when this 1499 document is published as an RFC. 1501 7. Security Considerations 1503 The main security issue that needs to be addressed for the OVSDB 1504 protocol is the authentication, integrity, and privacy of 1505 communications between a client and server implementing this 1506 protocol. To provide such protection, an OVSDB connection SHOULD be 1507 secured using Transport Layer Security (TLS) [RFC5246]. The precise 1508 details of how clients and servers authenticate each other is highly 1509 dependent on the operating environment. It is often the case that 1510 OVSDB clients and servers operate in a tightly controlled 1511 environment, e.g., on machines in a single data center where they 1512 communicate on an isolated management network. 1514 8. Acknowledgements 1516 Thanks to Jeremy Stribling and Justin Pettit for their helpful input 1517 to this document. 1519 9. References 1521 9.1. Normative References 1523 [DCE] "DCE: Remote Procedure Call", Open Group CAE 1524 Specification C309, ISBN 1-85912-041-5, August 1994. 1526 [JSON-RPC] 1527 "JSON-RPC Specification, Version 1.0", 1528 . 1530 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1531 Requirement Levels", BCP 14, RFC 2119, March 1997. 1533 [RFC4627] Crockford, D., "The application/json Media Type for 1534 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 1536 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1537 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1539 9.2. Informative References 1541 [DB-SCHEMA] 1542 "Open vSwitch Database Schema", 1543 . 1545 [OF-SPEC] "OpenFlow Switch Specification, version 1.3", . 1549 [OVS] "Open vSwitch", . 1551 Authors' Addresses 1553 Ben Pfaff 1554 VMware, Inc. 1555 3401 Hillview Ave. 1556 Palo Alto, CA 94304 1557 USA 1559 Email: blp@nicira.com 1561 Bruce Davie (editor) 1562 VMware, Inc. 1563 3401 Hillview Ave. 1564 Palo Alto, CA 94304 1565 USA 1567 Email: bsd@nicira.com