doc: Add RFC documents

1 files changed, 1963 insertions, 0 deletions

diff --git a/doc/rfc/rfc7047.txt b/doc/rfc/rfc7047.txt
new file mode 100644
index 0000000..b5ae247
--- /dev/null
+++ b/doc/rfc/rfc7047.txt
@@ -0,0 +1,1963 @@
+
+
+
+
+
+
+Independent Submission                                          B. Pfaff
+Request for Comments: 7047                                 B. Davie, Ed.
+Category: Informational                                     VMware, Inc.
+ISSN: 2070-1721                                            December 2013
+
+
+             The Open vSwitch Database Management Protocol
+
+Abstract
+
+   Open vSwitch is an open-source software switch designed to be used as
+   a vswitch (virtual switch) in virtualized server environments.  A
+   vswitch forwards traffic between different virtual machines (VMs) on
+   the same physical host and also forwards traffic between VMs and the
+   physical network.  Open vSwitch is open to programmatic extension and
+   control using OpenFlow and the OVSDB (Open vSwitch Database)
+   management protocol.  This document defines the OVSDB management
+   protocol.  The Open vSwitch project includes open-source OVSDB client
+   and server implementations.
+
+Status of This Memo
+
+   This document is not an Internet Standards Track specification; it is
+   published for informational purposes.
+
+   This is a contribution to the RFC Series, independently of any other
+   RFC stream.  The RFC Editor has chosen to publish this document at
+   its discretion and makes no statement about its value for
+   implementation or deployment.  Documents approved for publication by
+   the RFC Editor are not a candidate for any level of Internet
+   Standard; see Section 2 of RFC 5741.
+
+   Information about the current status of this document, any errata,
+   and how to provide feedback on it may be obtained at
+   http://www.rfc-editor.org/info/rfc7047.
+
+Copyright Notice
+
+   Copyright (c) 2013 IETF Trust and the persons identified as the
+   document authors.  All rights reserved.
+
+   This document is subject to BCP 78 and the IETF Trust's Legal
+   Provisions Relating to IETF Documents
+   (http://trustee.ietf.org/license-info) in effect on the date of
+   publication of this document.  Please review these documents
+   carefully, as they describe your rights and restrictions with respect
+   to this document.
+
+
+
+
+Pfaff & Davie                 Informational                     [Page 1]
+
+RFC 7047                OVSDB Management Protocol          December 2013
+
+
+Table of Contents
+
+   1. Introduction ....................................................3
+      1.1. Requirements Language ......................................3
+      1.2. Terminology ................................................3
+   2. System Overview .................................................4
+   3. OVSDB Structure .................................................5
+      3.1. JSON Usage .................................................6
+      3.2. Schema Format ..............................................7
+   4. Wire Protocol ..................................................12
+      4.1. RPC Methods ...............................................12
+           4.1.1. List Databases .....................................12
+           4.1.2. Get Schema .........................................13
+           4.1.3. Transact ...........................................13
+           4.1.4. Cancel .............................................16
+           4.1.5. Monitor ............................................16
+           4.1.6. Update Notification ................................18
+           4.1.7. Monitor Cancellation ...............................19
+           4.1.8. Lock Operations ....................................19
+           4.1.9. Locked Notification ................................21
+           4.1.10. Stolen Notification ...............................21
+           4.1.11. Echo ..............................................22
+   5. Database Operations ............................................22
+      5.1. Notation ..................................................22
+      5.2. Operations ................................................27
+           5.2.1. Insert .............................................27
+           5.2.2. Select .............................................28
+           5.2.3. Update .............................................29
+           5.2.4. Mutate .............................................29
+           5.2.5. Delete .............................................30
+           5.2.6. Wait ...............................................31
+           5.2.7. Commit .............................................32
+           5.2.8. Abort ..............................................32
+           5.2.9. Comment ............................................32
+           5.2.10. Assert ............................................33
+   6. IANA Considerations ............................................33
+   7. Security Considerations ........................................33
+   8. Acknowledgements ...............................................34
+   9. References .....................................................34
+      9.1. Normative References ......................................34
+      9.2. Informative References ....................................34
+
+
+
+
+
+
+
+
+
+
+Pfaff & Davie                 Informational                     [Page 2]
+
+RFC 7047                OVSDB Management Protocol          December 2013
+
+
+1.  Introduction
+
+   In virtualized server environments, it is typically required to use a
+   vswitch (virtual switch) to forward traffic between different virtual
+   machines (VMs) on the same physical host and between VMs and the
+   physical network.  Open vSwitch [OVS] is an open-source software
+   switch designed to be used as a vswitch in such environments.  Open
+   vSwitch (OVS) is open to programmatic extension and control using
+   OpenFlow [OF-SPEC] and the OVSDB (Open vSwitch Database) management
+   protocol.  This document defines the OVSDB management protocol.  The
+   Open vSwitch project includes open-source OVSDB client and server
+   implementations.
+
+   The OVSDB management protocol uses JSON [RFC4627] for its wire format
+   and is based on JSON-RPC version 1.0 [JSON-RPC].
+
+   The schema of the Open vSwitch database is documented in [DB-SCHEMA].
+   This document specifies the protocol for interacting with that
+   database for the purposes of managing and configuring Open vSwitch
+   instances.  The protocol specified in this document also provides
+   means for discovering the schema in use, as described in
+   Section 4.1.2.
+
+   The OVSDB management protocol is intended to allow programmatic
+   access to the Open vSwitch database as documented in [DB-SCHEMA].
+   This database holds the configuration for one Open vSwitch daemon.
+   As currently defined, this information describes the switching
+   behavior of a virtual switch and does not describe the behavior or
+   configuration of a routing system.  In the event that the schema is
+   extended in a future release to cover elements of the routing system,
+   implementers and operators need to be aware of the work of the IETF's
+   I2RS working group that specifies protocols and data models for real-
+   time or event driven interaction with the routing system.
+
+1.1.  Requirements Language
+
+   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+   document are to be interpreted as described in [RFC2119].
+
+1.2.  Terminology
+
+   UUID:       Universally Unique Identifier.  A 128-bit identifier that
+               is unique in space and time [DCE].
+
+   OVS:        Open vSwitch.  An open-source virtual switch.
+
+
+
+
+
+Pfaff & Davie                 Informational                     [Page 3]
+
+RFC 7047                OVSDB Management Protocol          December 2013
+
+
+   OVSDB:      The database that is used for the purpose of configuring
+               OVS instances.
+
+   JSON:       Javascript Object Notation [RFC4627].
+
+   JSON-RPC:   JSON Remote Procedure Call [JSON-RPC].
+
+   Durable:    Reliably written to non-volatile storage (e.g., disk).
+               OVSDB supports the option to specify whether or not
+               transactions are durable.
+
+   Note that the JSON specification [RFC4627] provides precise
+   definitions of a number of important terms such as JSON values,
+   objects, arrays, numbers, and strings.  In all cases, this document
+   uses the definitions from [RFC4627].
+
+2.  System Overview
+
+   Figure 1 illustrates the main components of Open vSwitch and the
+   interfaces to a control and management cluster.  An OVS instance
+   comprises a database server (ovsdb-server), a vswitch daemon
+   (ovs-vswitchd), and, optionally, a module that performs fast-path
+   forwarding.  The "management and control cluster" consists of some
+   number of managers and controllers.  Managers use the OVSDB
+   management protocol to manage OVS instances.  An OVS instance is
+   managed by at least one manager.  Controllers use OpenFlow to install
+   flow state in OpenFlow switches.  An OVS instance can support
+   multiple logical datapaths, referred to as "bridges".  There is at
+   least one controller for each OpenFlow bridge.
+
+   The OVSDB management interface is used to perform management and
+   configuration operations on the OVS instance.  Compared to OpenFlow,
+   OVSDB management operations occur on a relatively long timescale.
+   Examples of operations that are supported by OVSDB include:
+
+   o  Creation, modification, and deletion of OpenFlow datapaths
+      (bridges), of which there may be many in a single OVS instance;
+
+   o  Configuration of the set of controllers to which an OpenFlow
+      datapath should connect;
+
+   o  Configuration of the set of managers to which the OVSDB server
+      should connect;
+
+   o  Creation, modification, and deletion of ports on OpenFlow
+      datapaths;
+
+
+
+
+
+Pfaff & Davie                 Informational                     [Page 4]
+
+RFC 7047                OVSDB Management Protocol          December 2013
+
+
+   o  Creation, modification, and deletion of tunnel interfaces on
+      OpenFlow datapaths;
+
+   o  Creation, modification, and deletion of queues;
+
+   o  Configuration of QoS (quality of service) policies and attachment
+      of those policies to queues; and
+
+   o  Collection of statistics.
+
+   OVSDB does not perform per-flow operations, leaving those instead to
+   OpenFlow.
+
+          +----------------------+
+          |      Control &       |
+          |     Management       |
+          |      Cluster         |
+          +----------------------+
+             |                \
+             | OVSDB           \ OpenFlow
+             | Mgmt             \
+             |                   \
+       +============================================+
+       | +--------------+       +--------------+    |
+       | |              |       |              |    |
+       | | ovsdb-server |-------| ovs-vswitchd |    |
+       | |              |       |              |    |
+       | +--------------+       +--------------+    |
+       |                               |            |
+       |                        +----------------+  |
+       |                        | Forwarding Path|  |
+       |                        +----------------+  |
+       +============================================+
+
+                     Figure 1: Open vSwitch Interfaces
+
+   Further information about the usage of the OVSDB management protocol
+   is provided in [DB-SCHEMA].
+
+3.  OVSDB Structure
+
+   This section outlines the overall structure of databases in OVSDB.
+   As described here, the database is reasonably generic.  For the
+   complete and current description of the database schema as used in
+   OVS, refer to [DB-SCHEMA].  See also Section 4.1.2 for information on
+   how the OVSDB management protocol may be used to discover the schema
+   currently in use.
+
+
+
+
+Pfaff & Davie                 Informational                     [Page 5]
+
+RFC 7047                OVSDB Management Protocol          December 2013
+
+
+3.1.  JSON Usage
+
+   OVSDB uses JSON [RFC4627] for both its schema format and its wire
+   protocol format.  The JSON implementation in Open vSwitch has the
+   following limitations:
+
+   o  Null bytes (\u0000) SHOULD NOT be used in strings.
+
+   o  Only UTF-8 encoding is supported.
+
+   The descriptions below use the following shorthand notations for JSON
+   values.  Terminology follows [RFC4627].
+
+   <string>
+      A JSON string.  Any Unicode string is allowed.  Implementations
+      SHOULD disallow null bytes.
+
+   <id>
+      A JSON string matching [a-zA-Z_][a-zA-Z0-9_]*. <id>s that begin
+      with _ are reserved to the implementation and MUST NOT be used by
+      the user.
+
+   <version>
+      A JSON string that contains a version number that matches [0-9]+
+      \.[0-9]+\.[0-9]+
+
+   <boolean>
+      A JSON true or false value.
+
+   <number>
+      A JSON number.
+
+   <integer>
+      A JSON number with an integer value, within the range -(2**63)...+
+      (2**63)-1.
+
+   <json-value>
+      Any JSON value.
+
+   <nonnull-json-value>
+      Any JSON value except null.
+
+   <error>
+      A JSON object with the following members:
+
+           "error": <string>          required
+           "details": <string>        optional
+
+
+
+
+Pfaff & Davie                 Informational                     [Page 6]
+
+RFC 7047                OVSDB Management Protocol          December 2013
+
+
+      The value of the "error" member is a short string, specified in
+      this document, that broadly indicates the class of the error.
+      Most "error" strings are specific to contexts described elsewhere
+      in this document, but the following "error" strings may appear in
+      any context where an <error> is permitted:
+
+      "error": "resources exhausted"
+         The operation requires more resources (memory, disk, CPU, etc.)
+         than are currently available to the database server.
+
+      "error": "I/O error"
+         Problems accessing the disk, network, or other required
+         resources prevented the operation from completing.
+
+      Database implementations MAY use "error" strings not specified in
+      this document to indicate errors that do not fit into any of the
+      specified categories.  Optionally, an <error> MAY include a
+      "details" member, whose value is a string that describes the error
+      in more detail for the benefit of a human user or administrator.
+      This document does not specify the format or content of the
+      "details" string.  An <error> MAY also have other members that
+      describe the error in more detail.  This document does not specify
+      the names or values of these members.
+
+3.2.  Schema Format
+
+   An Open vSwitch configuration database consists of a set of tables,
+   each of which has a number of columns and zero or more rows.  A
+   schema for the database is represented by <database-schema>, as
+   described below.
+
+   <database-schema>
+      A JSON object with the following members:
+
+           "name": <id>                            required
+           "version": <version>                    required
+           "cksum": <string>                       optional
+           "tables": {<id>: <table-schema>, ...}   required
+
+      The "name" identifies the database as a whole.  It must be
+      provided to most JSON-RPC requests to identify the database being
+      operated on.
+
+      The "version" reports the version of the database schema.  It is
+      REQUIRED to be present.  Open vSwitch semantics for "version" are
+      described in [DB-SCHEMA].  Other schemas may use it differently.
+
+
+
+
+
+Pfaff & Davie                 Informational                     [Page 7]
+
+RFC 7047                OVSDB Management Protocol          December 2013
+
+
+      The "cksum" optionally reports an implementation-defined checksum
+      for the database schema.  Its use is primarily as a tool for
+      schema developers, and clients SHOULD ignore it.
+
+      The value of "tables" is a JSON object whose names are table names
+      and whose values are <table-schema>s.
+
+   <table-schema>
+      A JSON object with the following members:
+
+         "columns": {<id>: <column-schema>, ...}   required
+         "maxRows": <integer>                      optional
+         "isRoot": <boolean>                       optional
+         "indexes": [<column-set>*]                optional
+
+      The value of "columns" is a JSON object whose names are column
+      names and whose values are <column-schema>s.
+
+      Every table has the following columns whose definitions are not
+      included in the schema:
+
+         "_uuid": This column, which contains exactly one UUID value, is
+         initialized to a random value by the database engine when it
+         creates a row.  It is read-only, and its value never changes
+         during the lifetime of a row.
+
+         "_version": Like "_uuid", this column contains exactly one UUID
+         value, initialized to a random value by the database engine
+         when it creates a row, and it is read-only.  However, its value
+         changes to a new random value whenever any other field in the
+         row changes.  Furthermore, its value is ephemeral: when the
+         database is closed and reopened, or when the database process
+         is stopped and then started again, each "_version" also changes
+         to a new random value.
+
+      If "maxRows" is specified, as a positive integer, it limits the
+      maximum number of rows that may be present in the table.  This is
+      a "deferred" constraint, enforced only at transaction commit time
+      (see the "transact" request in Section 4.1.3).  If "maxRows" is
+      not specified, the size of the table is limited only by the
+      resources available to the database server. "maxRows" constraints
+      are enforced after unreferenced rows are deleted from tables with
+      a false "isRoot".
+
+      The "isRoot" boolean is used to determine whether rows in the
+      table require strong references from other rows to avoid garbage
+      collection.  (See the discussion of "strong" and "weak" references
+      below in the description of <base-type>.)  If "isRoot" is
+
+
+
+Pfaff & Davie                 Informational                     [Page 8]
+
+RFC 7047                OVSDB Management Protocol          December 2013
+
+
+      specified as true, then rows in the table exist independent of any
+      references (they can be thought of as part of the "root set" in a
+      garbage collector).  If "isRoot" is omitted or specified as false,
+      then any given row in the table may exist only when there is at
+      least one reference to it, with refType "strong", from a different
+      row (in the same table or a different table).  This is a
+      "deferred" action: unreferenced rows in the table are deleted just
+      before transaction commit.
+
+      For compatibility with schemas created before "isRoot" was
+      introduced, if "isRoot" is omitted or false in every
+      <table-schema> in a given <database-schema>, then every table is
+      part of the root set.
+
+      If "indexes" is specified, it must be an array of zero or more
+      <column-set>s.  A <column-set> is an array of one or more strings,
+      each of which names a column.  Each <column-set> is a set of
+      columns whose values, taken together within any given row, must be
+      unique within the table.  This is a "deferred" constraint,
+      enforced only at transaction commit time, after unreferenced rows
+      are deleted and dangling weak references are removed.  Ephemeral
+      columns may not be part of indexes.
+
+   <column-schema>
+      A JSON object with the following members:
+
+         "type": <type>                            required
+         "ephemeral": <boolean>                    optional
+         "mutable": <boolean>                      optional
+
+      The "type" specifies the type of data stored in this column.
+
+      If "ephemeral" is specified as true, then this column's values are
+      not guaranteed to be durable; they may be lost when the database
+      restarts.  A column whose type (either key or value) is a strong
+      reference to a table that is not part of the root set is always
+      durable, regardless of this value.  (Otherwise, restarting the
+      database could lose entire rows.)
+
+      If "mutable" is specified as false, then this column's values may
+      not be modified after they are initially set with the "insert"
+      operation.
+
+   <type>
+      The type of a database column.  Either an <atomic-type> or a JSON
+      object that describes the type of a database column, with the
+      following members:
+
+
+
+
+Pfaff & Davie                 Informational                     [Page 9]
+
+RFC 7047                OVSDB Management Protocol          December 2013
+
+
+         "key": <base-type>                 required
+         "value": <base-type>               optional
+         "min": <integer>                   optional
+         "max": <integer> or "unlimited"    optional
+
+      If "min" or "max" is not specified, each defaults to 1.  If "max"
+      is specified as "unlimited", then there is no specified maximum
+      number of elements, although the implementation will enforce some
+      limit.  After considering defaults, "min" must be exactly 0 or
+      exactly 1, "max" must be at least 1, and "max" must be greater
+      than or equal to "min".
+
+      If "min" and "max" are both 1 and "value" is not specified, the
+      type is the scalar type specified by "key".
+
+      If "min" is not 1 or "max" is not 1, or both, and "value" is not
+      specified, the type is a set of scalar type "key".
+
+      If "value" is specified, the type is a map from type "key" to type
+      "value".
+
+   <base-type>
+      The type of a key or value in a database column.  Either an
+      <atomic-type> or a JSON object with the following members:
+
+         "type": <atomic-type>            required
+         "enum": <value>                  optional
+         "minInteger": <integer>          optional, integers only
+         "maxInteger": <integer>          optional, integers only
+         "minReal": <real>                optional, reals only
+         "maxReal": <real>                optional, reals only
+         "minLength": <integer>           optional, strings only
+         "maxLength": <integer>           optional, strings only
+         "refTable": <id>                 optional, UUIDs only
+         "refType": "strong" or "weak"    optional, only with "refTable"
+
+      An <atomic-type> by itself is equivalent to a JSON object with a
+      single member "type" whose value is the <atomic-type>.
+
+      "enum" may be specified as a <value> whose type is a set of one or
+      more values specified for the member "type".  If "enum" is
+      specified, then the valid values of the <base-type> are limited to
+      those in the <value>.
+
+
+
+
+
+
+
+
+Pfaff & Davie                 Informational                    [Page 10]
+
+RFC 7047                OVSDB Management Protocol          December 2013
+
+
+      "enum" is mutually exclusive with the following constraints:
+
+         If "type" is "integer", then "minInteger" or "maxInteger" or
+         both may also be specified, restricting the valid integer
+         range.  If both are specified, then "maxInteger" must be
+         greater than or equal to "minInteger".
+
+         If "type" is "real", then "minReal" or "maxReal" or both may
+         also be specified, restricting the valid real range.  If both
+         are specified, then "maxReal" must be greater than or equal to
+         "minReal".
+
+         If "type" is "string", then "minLength" and "maxLength" or both
+         may be specified, restricting the valid length of value
+         strings.  If both are specified, then "maxLength" must be
+         greater than or equal to "minLength".  String length is
+         measured in characters.
+
+         If "type" is "uuid", then "refTable", if present, must be the
+         name of a table within this database.  If "refTable" is
+         specified, then "refType" may also be specified.  If "refTable"
+         is set, the effect depends on "refType":
+
+         +  If "refType" is "strong" or if "refType" is omitted, the
+            allowed UUIDs are limited to UUIDs for rows in the named
+            table.
+
+         +  If "refType" is "weak", then any UUIDs are allowed, but
+            UUIDs that do not correspond to rows in the named table will
+            be automatically deleted.  When this situation arises in a
+            map, both the key and the value will be deleted from the
+            map.
+
+      "refTable" constraints are "deferred" constraints: they are
+      enforced only at transaction commit time (see the "transact"
+      request in Section 4.1.3).  The other constraints on <base-type>
+      are "immediate", enforced immediately by each operation.
+
+   <atomic-type>
+      One of the strings "integer", "real", "boolean", "string", or
+      "uuid", representing the specified scalar type.
+
+
+
+
+
+
+
+
+
+
+Pfaff & Davie                 Informational                    [Page 11]
+
+RFC 7047                OVSDB Management Protocol          December 2013
+
+
+4.  Wire Protocol
+
+   The database wire protocol is implemented in JSON-RPC 1.0 [JSON-RPC].
+   While the JSON-RPC specification allows a range of transports,
+   implementations of this specification SHOULD operate directly over
+   TCP.  See Section 6 for discussion of the TCP port.
+
+4.1.  RPC Methods
+
+   The following subsections describe the RPC methods that are
+   supported.  As described in the JSON-RPC 1.0 specification, each
+   request comprises a string containing the name of the method, a
+   (possibly null) array of parameters to pass to the method, and a
+   request ID, which can be used to match the response to the request.
+   Each response comprises a result object (non-null in the event of a
+   successful invocation), an error object (non-null in the event of an
+   error), and the ID of the matching request.  More details on each
+   method, its parameters, and its results are described below.
+
+   An OVSDB server MUST implement all of the following methods.  An
+   OVSDB client MUST implement the "Echo" method and is otherwise free
+   to implement whichever methods suit the implementation's needs.
+
+   The operations that may be performed on the OVS database using these
+   methods (e.g., the "transact" method) are described in Section 5.
+
+4.1.1.  List Databases
+
+   This operation retrieves an array whose elements are the names of the
+   databases that can be accessed over this management protocol
+   connection.
+
+   The request object contains the following members:
+
+   o  "method": "list_dbs"
+
+   o  "params": []
+
+   o  "id": <nonnull-json-value>
+
+   The response object contains the following members:
+
+   o  "result": [<db-name>,...]
+
+   o  "error": null
+
+   o  "id": same "id" as request
+
+
+
+
+Pfaff & Davie                 Informational                    [Page 12]
+
+RFC 7047                OVSDB Management Protocol          December 2013
+
+
+4.1.2.  Get Schema
+
+   This operation retrieves a <database-schema> that describes hosted
+   database <db-name>.
+
+   The request object contains the following members:
+
+   o  "method": "get_schema"
+
+   o  "params": [<db-name>]
+
+   o  "id": <nonnull-json-value>
+
+   The response object contains the following members:
+
+   o  "result": <database-schema>
+
+   o  "error": null
+
+   o  "id": same "id" as request
+
+   In the event that the database named in the request does not exist,
+   the server sends a JSON-RPC error response of the following form:
+
+   o  "result": null
+
+   o  "error": "unknown database"
+
+   o  "id": same "id" as request
+
+4.1.3.  Transact
+
+   This RPC method causes the database server to execute a series of
+   operations in the specified order on a given database.
+
+   The request object contains the following members:
+
+   o  "method": "transact"
+
+   o  "params": [<db-name>, <operation>*]
+
+   o  "id": <nonnull-json-value>
+
+   The value of "id" MUST be unique among all in-flight transactions
+   within the current JSON-RPC session.  Otherwise, the server may
+   return a JSON-RPC error.
+
+
+
+
+
+Pfaff & Davie                 Informational                    [Page 13]
+
+RFC 7047                OVSDB Management Protocol          December 2013
+
+
+   The "params" array for this method consists of a <db-name> that
+   identifies the database to which the transaction applies, followed by
+   zero or more JSON objects, each of which represents a single database
+   operation.  Section 5 describes the valid operations.  The database
+   server executes each of the specified operations in the specified
+   order, except if an operation fails, then the remaining operations
+   are not executed.  The set of operations is executed as a single
+   atomic, consistent, isolated transaction.  The transaction is
+   committed if and only if every operation succeeds.  Durability of the
+   commit is not guaranteed unless the "commit" operation, with
+   "durable" set to true, is included in the operation set.  See
+   Section 5 for more discussion of the database operations.
+
+   The response object contains the following members:
+
+   o  "result": [<object>*]
+
+   o  "error": null
+
+   o  "id": same "id" as request
+
+   Regardless of whether errors occur in the database operations, the
+   response is always a JSON-RPC response with null "error" and a
+   "result" member that is an array with the same number of elements as
+   "params".  Each element of the "result" array corresponds to the same
+   element of the "params" array.  The "result" array elements may be
+   interpreted as follows:
+
+   o  A JSON object that does not contain an "error" member indicates
+      that the operation completed successfully.  The specific members
+      of the object are specified below in the descriptions of
+      individual operations.  Some operations do not produce any
+      results, in which case the object will have no members.
+
+   o  An <error> indicates that the matching operation completed with an
+      error.
+
+   o  A JSON null value indicates that the operation was not attempted
+      because a prior operation failed.
+
+   In general, "result" contains some number of successful results,
+   possibly followed by an error, in turn followed by enough JSON null
+   values to match the number of elements in "params".  There is one
+   exception: if all of the operations succeed, but the results cannot
+   be committed, then "result" will have one more element than "params",
+   with the additional element being an <error>.  In this case, the
+   possible "error" strings include the following:
+
+
+
+
+Pfaff & Davie                 Informational                    [Page 14]
+
+RFC 7047                OVSDB Management Protocol          December 2013
+
+
+   "error": "referential integrity violation"
+      When the commit was attempted, a column's value referenced the
+      UUID for a row that did not exist in the table named by the
+      column's <base-type> key or value "refTable" that has a "refType"
+      of "strong".  (This can be caused by inserting a row that
+      references a nonexistent row, by deleting a row that is still
+      referenced by another row, by specifying the UUID for a row in the
+      wrong table, and other ways.)
+
+   "error": "constraint violation"
+      A number of situations can arise in which the attempted commit
+      would lead to a constraint on the database being violated.  (See
+      Section 3.2 for more discussion of constraints.)  These situations
+      include:
+
+      *  The number of rows in a table exceeds the maximum number
+         permitted by the table's "maxRows" value.
+
+      *  Two or more rows in a table had the same values in the columns
+         that comprise an index.
+
+      *  A column with a <base-type> key or value "refTable" whose
+         "refType" is "weak" became empty due to deletion(s), and this
+         column is not allowed to be empty because its <type> has a
+         "min" of 1.  Such deletions may be the result of rows that it
+         referenced being deleted (or never having existed, if the
+         column's row was inserted within the transaction).
+
+   "error": "resources exhausted"
+      The operation requires more resources (memory, disk, CPU, etc.)
+      than are currently available to the database server.
+
+   "error": "I/O error"
+      Problems accessing the disk, network, or other required resources
+      prevented the operation from completing.
+
+   If "params" contains one or more "wait" operations, then the
+   transaction may take an arbitrary amount of time to complete.  The
+   database implementation MUST be capable of accepting, executing, and
+   replying to other transactions and other JSON-RPC requests while a
+   transaction or transactions containing "wait" operations are
+   outstanding on the same or different JSON-RPC sessions.
+
+
+
+
+
+
+
+
+
+Pfaff & Davie                 Informational                    [Page 15]
+
+RFC 7047                OVSDB Management Protocol          December 2013
+
+
+4.1.4.  Cancel
+
+   The "cancel" method is a JSON-RPC notification, i.e., no matching
+   response is provided.  It instructs the database server to
+   immediately complete or cancel the "transact" request whose "id" is
+   the same as the notification's "params" value.  The notification
+   object has the following members:
+
+   o  "method": "cancel"
+
+   o  "params": [the "id" for an outstanding request]
+
+   o  "id": null
+
+   If the "transact" request can be completed immediately, then the
+   server sends a response in the form described for "transact"
+   (Section 4.1.3).  Otherwise, the server sends a JSON-RPC error
+   response of the following form:
+
+   o  "result": null
+
+   o  "error": "canceled"
+
+   o  "id": the "id" member of the canceled request.
+
+   The "cancel" notification itself has no reply.
+
+4.1.5.  Monitor
+
+   The "monitor" request enables a client to replicate tables or subsets
+   of tables within an OVSDB database by requesting notifications of
+   changes to those tables and by receiving the complete initial state
+   of a table or a subset of a table.  The request object has the
+   following members:
+
+   o  "method": "monitor"
+
+   o  "params": [<db-name>, <json-value>, <monitor-requests>]
+
+   o  "id": <nonnull-json-value>
+
+   The <json-value> parameter is used to match subsequent update
+   notifications (see below) to this request.  The <monitor-requests>
+   object maps the name of the table to be monitored to an array of
+   <monitor-request> objects.
+
+
+
+
+
+
+Pfaff & Davie                 Informational                    [Page 16]
+
+RFC 7047                OVSDB Management Protocol          December 2013
+
+
+   Each <monitor-request> is an object with the following members:
+
+       "columns": [<column>*]            optional
+       "select": <monitor-select>        optional
+
+   The columns, if present, define the columns within the table to be
+   monitored. <monitor-select> is an object with the following members:
+
+       "initial": <boolean>              optional
+       "insert": <boolean>               optional
+       "delete": <boolean>               optional
+       "modify": <boolean>               optional
+
+   The contents of this object specify how the columns or table are to
+   be monitored, as explained in more detail below.
+
+   The response object has the following members:
+
+   o  "result": <table-updates>
+
+   o  "error": null
+
+   o  "id": same "id" as request
+
+   The <table-updates> object is described in detail in Section 4.1.6.
+   It contains the contents of the tables for which "initial" rows are
+   selected.  If no tables' initial contents are requested, then
+   "result" is an empty object.
+
+   Subsequently, when changes to the specified tables are committed, the
+   changes are automatically sent to the client using the "update"
+   monitor notification (see Section 4.1.6).  This monitoring persists
+   until the JSON-RPC session terminates or until the client sends a
+   "monitor_cancel" JSON-RPC request.
+
+   Each <monitor-request> specifies one or more columns and the manner
+   in which the columns (or the entire table) are to be monitored.  The
+   "columns" member specifies the columns whose values are monitored.
+   It MUST NOT contain duplicates.  If "columns" is omitted, all columns
+   in the table, except for "_uuid", are monitored.  The circumstances
+   in which an "update" notification is sent for a row within the table
+   are determined by <monitor-select>:
+
+   o  If "initial" is omitted or true, every row in the table is sent as
+      part of the response to the "monitor" request.
+
+   o  If "insert" is omitted or true, "update" notifications are sent
+      for rows newly inserted into the table.
+
+
+
+Pfaff & Davie                 Informational                    [Page 17]
+
+RFC 7047                OVSDB Management Protocol          December 2013
+
+
+   o  If "delete" is omitted or true, "update" notifications are sent
+      for rows deleted from the table.
+
+   o  If "modify" is omitted or true, "update" notifications are sent
+      whenever a row in the table is modified.
+
+   If there is more than one <monitor-request> in an array, then each
+   <monitor-request> in the array should specify both "columns" and
+   "select", and the "columns" MUST be non-overlapping sets.
+
+4.1.6.  Update Notification
+
+   The "update" notification is sent by the server to the client to
+   report changes in tables that are being monitored following a
+   "monitor" request as described above.  The notification has the
+   following members:
+
+   o  "method": "update"
+
+   o  "params": [<json-value>, <table-updates>]
+
+   o  "id": null
+
+   The <json-value> in "params" is the same as the value passed as the
+   <json-value> in "params" for the corresponding "monitor" request.
+   <table-updates> is an object that maps from a table name to a
+   <table-update>.  A <table-update> is an object that maps from the
+   row's UUID to a <row-update> object.  A <row-update> is an object
+   with the following members:
+
+    "old": <row>   present for "delete" and "modify" updates
+    "new": <row>   present for "initial", "insert", and "modify" updates
+
+   The format of <row> is described in Section 5.1.
+
+   Each table in which one or more rows has changed (or whose initial
+   view is being presented) is represented in <table-updates>.  Each row
+   that has changed (or whose initial view is being presented) is
+   represented in its <table-update> as a member with its name taken
+   from the row's "_uuid" member.  The corresponding value is a
+   <row-update>:
+
+   o  The "old" member is present for "delete" and "modify" updates.
+      For "delete" updates, each monitored column is included.  For
+      "modify" updates, the prior value of each monitored column whose
+      value has changed is included (monitored columns that have not
+      changed are represented in "new").
+
+
+
+
+Pfaff & Davie                 Informational                    [Page 18]
+
+RFC 7047                OVSDB Management Protocol          December 2013
+
+
+   o  The "new" member is present for "initial", "insert", and "modify"
+      updates.  For "initial" and "insert" updates, each monitored
+      column is included.  For "modify" updates, the new value of each
+      monitored column is included.
+
+   Note that initial views of rows are not presented in update
+   notifications, but in the response object to the monitor request.
+   The formatting of the <table-updates> object, however, is the same in
+   either case.
+
+4.1.7.  Monitor Cancellation
+
+   The "monitor_cancel" request cancels a previously issued monitor
+   request.  The request object members are:
+
+   o  "method": "monitor_cancel"
+
+   o  "params": [<json-value>]
+
+   o  "id": <nonnull-json-value>
+
+   The <json-value> in "params" matches the <json-value> in "params" for
+   the ongoing "monitor" request that is to be canceled.  No more
+   "update" messages will be sent for this table monitor.  The response
+   to this request has the following members:
+
+   o  "result": {}
+
+   o  "error": null
+
+   o  "id": the request "id" member
+
+   In the event that a monitor cancellation request refers to an unknown
+   monitor request, an error response with the following members is
+   returned:
+
+   o  "result": null
+
+   o  "error": "unknown monitor"
+
+   o  "id": the request "id" member
+
+4.1.8.  Lock Operations
+
+   Three RPC methods, "lock", "steal", and "unlock", provide support to
+   clients to perform locking operations on the database.  The database
+   server supports an arbitrary number of locks, each of which is
+   identified by a client-defined ID.  At any given time, each lock may
+
+
+
+Pfaff & Davie                 Informational                    [Page 19]
+
+RFC 7047                OVSDB Management Protocol          December 2013
+
+
+   have at most one owner.  The precise usage of a lock is determined by
+   the client.  For example, a set of clients may agree that a certain
+   table can only be written by the owner of a certain lock.  OVSDB
+   itself does not enforce any restrictions on how locks are used -- it
+   simply ensures that a lock has at most one owner.
+
+   The RPC request objects have the following members:
+
+   o  "method": "lock", "steal", or "unlock"
+
+   o  "params": [<id>]
+
+   o  "id": <nonnull-json-value>
+
+   The response depends on the request and has the following members:
+
+   o  "result": {"locked": boolean} for "lock"
+
+   o  "result": {"locked": true} for "steal"
+
+   o  "result": {} for "unlock"
+
+   o  "error": null
+
+   o  "id": same "id" as request
+
+   The three methods operate as follows:
+
+   o  "lock": The database will assign this client ownership of the lock
+      as soon as it becomes available.  When multiple clients request
+      the same lock, they will receive it in first-come, first-served
+      order.
+
+   o  "steal": The database immediately assigns this client ownership of
+      the lock.  If there is an existing owner, it loses ownership.
+
+   o  "unlock": If the client owns the lock, this operation releases it.
+      If the client has requested ownership of the lock, this cancels
+      the request.
+
+      (Closing or otherwise disconnecting a database client connection
+      unlocks all of its locks.)
+
+   For any given lock, the client MUST alternate "lock" or "steal"
+   operations with "unlock" operations.  That is, if the previous
+   operation on a lock was "lock" or "steal", it MUST be followed by an
+   "unlock" operation, and vice versa.
+
+
+
+
+Pfaff & Davie                 Informational                    [Page 20]
+
+RFC 7047                OVSDB Management Protocol          December 2013
+
+
+   For a "lock" operation, the "locked" member in the response object is
+   true if the lock has already been acquired and false if another
+   client holds the lock and the client's request for it was queued.  In
+   the latter case, the client will be notified later with a "locked"
+   message (Section 4.1.9) when acquisition succeeds.
+
+   These requests complete and send a response quickly, without waiting.
+   The "locked" and "stolen" notifications (see below) report
+   asynchronous changes to ownership.
+
+   Note that the scope of a lock is a database server, not a database
+   hosted by that server.  A client may choose to implement a naming
+   convention, such as "<db-name>__<lock-name>", which can effectively
+   limit the scope of a lock to a particular database.
+
+4.1.9.  Locked Notification
+
+   The "locked" notification is provided to notify a client that it has
+   been granted a lock that it had previously requested with the "lock"
+   method described above.  The notification has the following members:
+
+   o  "method": "locked"
+
+   o  "params": [<id>]
+
+   o  "id": null
+
+   "Params" contains the name of the lock that was given in the "lock"
+   request.  The notified client now owns the lock named in "params".
+
+   The database server sends this notification after the reply to the
+   corresponding "lock" request (but only if the "locked" member of the
+   response was false) and before the reply to the client's subsequent
+   "unlock" request.
+
+4.1.10.  Stolen Notification
+
+   The "stolen" notification is provided to notify a client, which had
+   previously obtained a lock, that another client has stolen ownership
+   of that lock.  The notification has the following members:
+
+   o  "method": "stolen"
+
+   o  "params": [<id>]
+
+   o  "id": null
+
+
+
+
+
+Pfaff & Davie                 Informational                    [Page 21]
+
+RFC 7047                OVSDB Management Protocol          December 2013
+
+
+   The notified client no longer owns the lock named in "params".  The
+   client MUST still issue an "unlock" request before performing any
+   subsequent "lock" or "steal" operation on the lock.
+
+   If the client originally obtained the lock through a "lock" request,
+   then it will automatically regain the lock later after the client
+   that stole it releases it.  (The database server will send the client
+   a "locked" notification at that point to let it know.)
+
+   If the client originally obtained the lock through a "steal" request,
+   the database server won't automatically reassign it ownership of the
+   lock when it later becomes available.  To regain ownership, the
+   client must "unlock" and then "lock" or "steal" the lock again.
+
+4.1.11.  Echo
+
+   The "echo" method can be used by both clients and servers to verify
+   the liveness of a database connection.  It MUST be implemented by
+   both clients and servers.  The members of the request are:
+
+   o  "method": "echo"
+
+   o  "params": JSON array with any contents
+
+   o  "id": <json-value>
+
+   The response object has the following members:
+
+   o  "result": same as "params"
+
+   o  "error": null
+
+   o  "id": the request "id" member
+
+5.  Database Operations
+
+   This section describes the operations that may be specified in the
+   "transact" method described in Section 4.1.3.
+
+5.1.  Notation
+
+   We introduce the following notation for the discussion of operations.
+
+    <db-name>
+      An <id> that names a database.  The valid <db-name>s can be
+      obtained using a "list_dbs" request.  The <db-name> is taken from
+      the "name" member of <database-schema>.
+
+
+
+
+Pfaff & Davie                 Informational                    [Page 22]
+
+RFC 7047                OVSDB Management Protocol          December 2013
+
+
+   <table>
+      An <id> that names a table.
+
+   <column>
+      An <id> that names a table column.
+
+   <row>
+      A JSON object that describes a table row or a subset of a table
+      row.  Each member is the name of a table column paired with the
+      <value> of that column.
+
+   <value>
+      A JSON value that represents the value of a column in a table row,
+      one of <atom>, <set>, or <map>.
+
+   <atom>
+      A JSON value that represents a scalar value for a column, one of
+      <string>, <number>, <boolean>, <uuid>, or <named-uuid>.
+
+   <set>
+      Either an <atom>, representing a set with exactly one element, or
+      a 2-element JSON array that represents a database set value.  The
+      first element of the array must be the string "set", and the
+      second element must be an array of zero or more <atom>s giving the
+      values in the set.  All of the <atom>s must have the same type.
+
+   <map>
+      A 2-element JSON array that represents a database map value.  The
+      first element of the array must be the string "map", and the
+      second element must be an array of zero or more <pair>s giving the
+      values in the map.  All of the <pair>s must have the same key and
+      value types.
+
+      (JSON objects are not used to represent <map> because JSON only
+      allows string names in an object.)
+
+   <pair>
+      A 2-element JSON array that represents a pair within a database
+      map.  The first element is an <atom> that represents the key, and
+      the second element is an <atom> that represents the value.
+
+
+
+
+
+
+
+
+
+
+
+Pfaff & Davie                 Informational                    [Page 23]
+
+RFC 7047                OVSDB Management Protocol          December 2013
+
+
+   <uuid>
+      A 2-element JSON array that represents a UUID.  The first element
+      of the array must be the string "uuid", and the second element
+      must be a 36-character string giving the UUID in the format
+      described by RFC 4122 [RFC4122].  For example, the following
+      <uuid> represents the UUID 550e8400-e29b-41d4-a716-446655440000:
+
+      ["uuid", "550e8400-e29b-41d4-a716-446655440000"]
+
+   <named-uuid>
+      A 2-element JSON array that represents the UUID of a row inserted
+      in an "insert" operation within the same transaction.  The first
+      element of the array must be the string "named-uuid", and the
+      second element should be the <id> specified as the "uuid-name" for
+      an "insert" operation within the same transaction.  For example,
+      if an "insert" operation within this transaction specifies a
+      "uuid-name" of "myrow", the following <named-uuid> represents the
+      UUID created by that operation:
+
+      ["named-uuid", "myrow"]
+
+      A <named-uuid> may be used anywhere a <uuid> is valid.  This
+      enables a single transaction to both insert a new row and then
+      refer to that row using the "uuid-name" that was associated with
+      that row when it was inserted.  Note that the "uuid-name" is only
+      meaningful within the scope of a single transaction.
+
+   <condition>
+      A 3-element JSON array of the form [<column>, <function>, <value>]
+      that represents a test on a column value.  Except as otherwise
+      specified below, <value> MUST have the same type as <column>.  The
+      meaning depends on the type of <column>:
+
+      integer or real
+         <function> must be "<", "<=", "==", "!=", ">=", ">",
+         "includes", or "excludes".
+
+         The test is true if the column's value satisfies the relation
+         <function> <value>, e.g., if the column has value 1 and <value>
+         is 2, the test is true if <function> is "<", "<=", or "!=", but
+         not otherwise.
+
+         "includes" is equivalent to "=="; "excludes" is equivalent to
+         "!=".
+
+
+
+
+
+
+
+Pfaff & Davie                 Informational                    [Page 24]
+
+RFC 7047                OVSDB Management Protocol          December 2013
+
+
+      boolean or string or uuid
+         <function> must be "!=", "==", "includes", or "excludes".
+
+         If <function> is "==" or "includes", the test is true if the
+         column's value equals <value>.  If <function> is "!=" or
+         "excludes", the test is inverted.
+
+      set or map
+         <function> must be "!=", "==", "includes", or "excludes".
+
+         If <function> is "==", the test is true if the column's value
+         contains exactly the same values (for sets) or pairs (for
+         maps).  If <function> is "!=", the test is inverted.
+
+         If <function> is "includes", the test is true if the column's
+         value contains all of the values (for sets) or pairs (for maps)
+         in <value>.  The column's value may also contain other values
+         or pairs.
+
+         If <function> is "excludes", the test is true if the column's
+         value does not contain any of the values (for sets) or pairs
+         (for maps) in <value>.  The column's value may contain other
+         values or pairs not in <value>.
+
+         If <function> is "includes" or "excludes", then the required
+         type of <value> is slightly relaxed, in that it may have fewer
+         than the minimum number of elements specified by the column's
+         type.  If <function> is "excludes", then the required type is
+         additionally relaxed in that <value> may have more than the
+         maximum number of elements specified by the column's type.
+
+   <function>
+      One of "<", "<=", "==", "!=", ">=", ">", "includes", or
+      "excludes".
+
+   <mutation>
+      A 3-element JSON array of the form [<column>, <mutator>, <value>]
+      that represents a change to a column value.  Except as otherwise
+      specified below, <value> must have the same type as <column>.  The
+      meaning depends on the type of <column>:
+
+      integer or real
+         <mutator> must be "+=", "-=", "*=", "/=", or (integer only)
+         "%=".  The value of <column> is changed to the sum, difference,
+         product, quotient, or remainder, respectively, of <column> and
+         <value>.
+
+         Constraints on <column> are ignored when parsing <value>.
+
+
+
+Pfaff & Davie                 Informational                    [Page 25]
+
+RFC 7047                OVSDB Management Protocol          December 2013
+
+
+      boolean, string, or uuid
+         No valid <mutator>s are currently defined for these types.
+
+      set
+         Any <mutator> valid for the set's element type may be applied
+         to the set, in which case the mutation is applied to each
+         member of the set individually. <value> must be a scalar value
+         of the same type as the set's element type, except that
+         constraints are ignored when parsing <value>.
+
+         If <mutator> is "insert", then each of the values in the set in
+         <value> is added to <column> if it is not already present.  The
+         required type of <value> is slightly relaxed, in that it may
+         have fewer than the minimum number of elements specified by the
+         column's type.
+
+         If <mutator> is "delete", then each of the values in the set in
+         <value> is removed from <column> if it is present there.  The
+         required type is slightly relaxed in that <value> may have more
+         or less than the maximum number of elements specified by the
+         column's type.
+
+      map
+         <mutator> must be "insert" or "delete".
+
+         If <mutator> is "insert", then each of the key-value pairs in
+         the map in <value> is added to <column> only if its key is not
+         already present.  The required type of <value> is slightly
+         relaxed, in that it may have fewer than the minimum number of
+         elements specified by the column's type.
+
+         If <mutator> is "delete", then <value> may have the same type
+         as <column> (a map type), or it may be a set whose element type
+         is the same as <column>'s key type:
+
+         +  If <value> is a map, the mutation deletes each key-value
+            pair in <column> whose key and value equal one of the key-
+            value pairs in <value>.
+
+         +  If <value> is a set, the mutation deletes each key-value
+            pair in <column> whose key equals one of the values in
+            <value>.
+
+         For "delete", <value> may have any number of elements,
+         regardless of restrictions on the number of elements in
+         <column>.
+
+
+
+
+
+Pfaff & Davie                 Informational                    [Page 26]
+
+RFC 7047                OVSDB Management Protocol          December 2013
+
+
+   <mutator>
+      One of "+=", "-=", "*=", "/=", "%=", "insert", or "delete".
+
+5.2.  Operations
+
+   The operations that may be performed as part of a "transact" RPC
+   request (see Section 4.1.3) are described in the following
+   subsections.  Each of these operations is a JSON object that may be
+   included as one of the elements of the "params" array that is one of
+   the elements of the "transact" request.  The details of each object,
+   its semantics, results, and possible errors are described below.
+
+5.2.1.  Insert
+
+   The "insert" object contains the following members:
+
+      "op": "insert"          required
+      "table": <table>        required
+      "row": <row>            required
+      "uuid-name": <id>       optional
+
+   The corresponding result object contains the following member:
+
+      "uuid": <uuid>
+
+   The operation inserts "row" into "table".  If "row" does not specify
+   values for all the columns in "table", those columns receive default
+   values.  The default value for a column depends on its type.  The
+   default for a column whose <type> specifies a "min" of 0 is an empty
+   set or empty map.  Otherwise, the default is a single value or a
+   single key-value pair, whose value(s) depend on its <atomic-type>:
+
+   o  "integer" or "real": 0
+
+   o  "boolean": false
+
+   o  "string": "" (the empty string)
+
+   o  "uuid": 00000000-0000-0000-0000-000000000000
+
+   The new row receives a new, randomly generated UUID.  If "uuid-name"
+   is supplied, then it is an error if <id> is not unique among the
+   "uuid-name"s supplied on all the "insert" operations within this
+   transaction.  The UUID for the new row is returned as the "uuid"
+   member of the result.
+
+
+
+
+
+
+Pfaff & Davie                 Informational                    [Page 27]
+
+RFC 7047                OVSDB Management Protocol          December 2013
+
+
+   The errors that may be returned are as follows:
+
+   "error": "duplicate uuid-name"
+      The same "uuid-name" appears on another "insert" operation within
+      this transaction.
+
+   "error": "constraint violation"
+      One of the values in "row" does not satisfy the immediate
+      constraints for its column's <base-type>.  This error will occur
+      for columns that are not explicitly set by "row" if the default
+      value does not satisfy the column's constraints.
+
+5.2.2.  Select
+
+   The "select" object contains the following members:
+
+      "op": "select"                required
+      "table": <table>              required
+      "where": [<condition>*]       required
+      "columns": [<column>*]        optional
+
+   The corresponding result object contains the following member:
+
+      "rows": [<row>*]
+
+   The operation searches "table" for rows that match all the conditions
+   specified in "where".  If "where" is an empty array, every row in
+   "table" is selected.
+
+   The "rows" member of the result is an array of objects.  Each object
+   corresponds to a matching row, with each column specified in
+   "columns" as a member, the column's name as the member name, and its
+   value as the member value.  If "columns" is not specified, all the
+   table's columns are included (including the internally generated
+   "_uuid" and "_version" columns).  If two rows of the result have the
+   same values for all included columns, only one copy of that row is
+   included in "rows".  Specifying "_uuid" within "columns" will avoid
+   dropping duplicates, since every row has a unique UUID.
+
+   The ordering of rows within "rows" is unspecified.
+
+
+
+
+
+
+
+
+
+
+
+Pfaff & Davie                 Informational                    [Page 28]
+
+RFC 7047                OVSDB Management Protocol          December 2013
+
+
+5.2.3.  Update
+
+   The "update" object contains the following members:
+
+      "op": "update"                required
+      "table": <table>              required
+      "where": [<condition>*]       required
+      "row": <row>                  required
+
+   The corresponding result object contains the following member:
+
+      "count": <integer>
+
+   The operation updates rows in a table.  It searches "table" for rows
+   that match all the conditions specified in "where".  For each
+   matching row, it changes the value of each column specified in "row"
+   to the value for that column specified in "row".  The "_uuid" and
+   "_version" columns of a table may not be directly updated with this
+   operation.  Columns designated read-only in the schema also may not
+   be updated.
+
+   The "count" member of the result specifies the number of rows that
+   matched.
+
+   The error that may be returned is:
+
+   "error": "constraint violation"
+      One of the values in "row" does not satisfy the immediate
+      constraints for its column's <base-type>.
+
+5.2.4.  Mutate
+
+   The "mutate" object contains the following members:
+
+      "op":  "mutate"               required
+      "table": <table>              required
+      "where": [<condition>*]       required
+      "mutations": [<mutation>*]    required
+
+   The corresponding result object contains the following member:
+
+      "count": <integer>
+
+   The operation mutates rows in a table.  It searches "table" for rows
+   that match all the conditions specified in "where".  For each
+   matching row, it mutates its columns as specified by each <mutation>
+   in "mutations", in the order specified.
+
+
+
+
+Pfaff & Davie                 Informational                    [Page 29]
+
+RFC 7047                OVSDB Management Protocol          December 2013
+
+
+   The "_uuid" and "_version" columns of a table may not be directly
+   modified with this operation.  Columns designated read-only in the
+   schema also may not be updated.
+
+   The "count" member of the result specifies the number of rows that
+   matched.
+
+   The errors that may be returned are:
+
+   "error":  "domain error"
+      The result of the mutation is not mathematically defined, e.g.,
+      division by zero.
+
+   "error":  "range error"
+      The result of the mutation is not representable within the
+      database's format, e.g., an integer result outside the range
+      INT64_MIN...INT64_MAX or a real result outside the range
+      -DBL_MAX...DBL_MAX.
+
+   "error": "constraint violation"
+      The mutation caused the column's value to violate a constraint,
+      e.g., it caused a column to have more or fewer values than are
+      allowed, an arithmetic operation caused a set or map to have
+      duplicate elements, or it violated a constraint specified by a
+      column's <base-type>.
+
+5.2.5.  Delete
+
+   The "delete" object contains the following members:
+
+      "op":  "delete"               required
+      "table": <table>              required
+      "where": [<condition>*]       required
+
+   The corresponding result object contains the following member:
+
+      "count": <integer>
+
+   The operation deletes all the rows from "table" that match all the
+   conditions specified in "where".  The "count" member of the result
+   specifies the number of deleted rows.
+
+
+
+
+
+
+
+
+
+
+Pfaff & Davie                 Informational                    [Page 30]
+
+RFC 7047                OVSDB Management Protocol          December 2013
+
+
+5.2.6.  Wait
+
+   The "wait" object contains the following members:
+
+      "op": "wait"                        required
+      "timeout": <integer>                optional
+      "table": <table>                    required
+      "where": [<condition>*]             required
+      "columns": [<column>*]              required
+      "until": "==" or "!="               required
+      "rows": [<row>*]                    required
+
+   There is no corresponding result object.
+
+   The operation waits until a condition becomes true.
+
+   If "until" is "==", it checks whether the query on "table" specified
+   by "where" and "columns", which is evaluated in the same way as
+   specified for "select", returns the result set specified by "rows".
+   If it does, then the operation completes successfully.  Otherwise,
+   the entire transaction rolls back.  It is automatically restarted
+   later, after a change in the database makes it possible for the
+   operation to succeed.  The client will not receive a response until
+   the operation permanently succeeds or fails.
+
+   If "until" is "!=", the sense of the test is negated.  That is, as
+   long as the query on "table" specified by "where" and "columns"
+   returns "rows", the transaction will be rolled back and restarted
+   later.
+
+   If "timeout" is specified, then the transaction aborts after the
+   specified number of milliseconds.  The transaction is guaranteed to
+   be attempted at least once before it aborts.  A "timeout" of 0 will
+   abort the transaction on the first mismatch.
+
+   The error that may be returned is:
+
+   "error":  "timed out"
+      The "timeout" was reached before the transaction was able to
+      complete.
+
+
+
+
+
+
+
+
+
+
+
+Pfaff & Davie                 Informational                    [Page 31]
+
+RFC 7047                OVSDB Management Protocol          December 2013
+
+
+5.2.7.  Commit
+
+   The "commit" object contains the following members:
+
+      "op": "commit"                      required
+      "durable": <boolean>                required
+
+   There is no corresponding result object.
+
+   If "durable" is specified as true, then the transaction, if it
+   commits, will be stored durably (to disk) before the reply is sent to
+   the client.  This operation with "durable" set to false is
+   effectively a no-op.
+
+   The error that may be returned is:
+
+   "error": "not supported"
+      When "durable" is true, this database implementation does not
+      support durable commits.
+
+5.2.8.  Abort
+
+   The "abort" object contains the following member:
+
+      "op":  "abort"                      required
+
+   There is no corresponding result object (the operation never
+   succeeds).
+
+   The operation aborts the entire transaction with an error.  This may
+   be useful for testing.
+
+   The error that will be returned is:
+
+   "error": "aborted"
+      This operation always fails with this error.
+
+5.2.9.  Comment
+
+   The "comment" object contains the following members:
+
+      "op": "comment"                    required
+      "comment": <string>                required
+
+   There is no corresponding result object.
+
+
+
+
+
+
+Pfaff & Davie                 Informational                    [Page 32]
+
+RFC 7047                OVSDB Management Protocol          December 2013
+
+
+   The operation provides information to a database administrator on the
+   purpose of a transaction.  The ovsdb-server implementation, for
+   example, adds comments in transactions that modify the database to
+   the database journal.  This can be helpful in debugging, e.g., when
+   there are multiple clients writing to a database.  An example of this
+   can be seen in the ovs-vsctl tool, a command line tool that interacts
+   with ovsdb-server.  When performing operations on the database, it
+   includes the command that was invoked (e.g., "ovs-vsctl add-br br0")
+   as a comment in the transaction, which can then be seen in the
+   journal alongside the changes that were made to the tables in the
+   database.
+
+5.2.10.  Assert
+
+   The assert object contains the following members:
+
+      "op": "assert"                     required
+      "lock": <id>                       required
+
+   Result object has no members.
+
+   The assert operation causes the transaction to be aborted if the
+   client does not own the lock named <id>.
+
+   The error that may be returned is:
+
+   "error": "not owner"
+      The client does not own the named lock.
+
+6.  IANA Considerations
+
+   IANA has assigned TCP port 6640 for this protocol.  Earlier
+   implementations of OVSDB used another port number, but compliant
+   implementations should use the IANA-assigned number.
+
+   IANA has updated the reference for port 6640 to point to this
+   document.
+
+7.  Security Considerations
+
+   The main security issue that needs to be addressed for the OVSDB
+   protocol is the authentication, integrity, and privacy of
+   communications between a client and server implementing this
+   protocol.  To provide such protection, an OVSDB connection SHOULD be
+   secured using Transport Layer Security (TLS) [RFC5246].  The precise
+   details of how clients and servers authenticate each other is highly
+   dependent on the operating environment.  It is often the case that
+
+
+
+
+Pfaff & Davie                 Informational                    [Page 33]
+
+RFC 7047                OVSDB Management Protocol          December 2013
+
+
+   OVSDB clients and servers operate in a tightly controlled
+   environment, e.g., on machines in a single data center where they
+   communicate on an isolated management network.
+
+8.  Acknowledgements
+
+   Thanks to Jeremy Stribling and Justin Pettit for their helpful input
+   to this document.
+
+9.  References
+
+9.1.  Normative References
+
+   [DCE]        "DCE: Remote Procedure Call", Open Group CAE
+                Specification C309, ISBN 1-85912-041-5, August 1994.
+
+   [JSON-RPC]   "JSON-RPC Specification, Version 1.0",
+                <http://json-rpc.org/wiki/specification>.
+
+   [RFC2119]    Bradner, S., "Key words for use in RFCs to Indicate
+                Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+   [RFC4122]    Leach, P., Mealling, M., and R. Salz, "A Universally
+                Unique IDentifier (UUID) URN Namespace", RFC 4122,
+                July 2005.
+
+   [RFC4627]    Crockford, D., "The application/json Media Type for
+                JavaScript Object Notation (JSON)", RFC 4627, July 2006.
+
+   [RFC5246]    Dierks, T. and E. Rescorla, "The Transport Layer
+                Security (TLS) Protocol Version 1.2", RFC 5246,
+                August 2008.
+
+9.2.  Informative References
+
+   [DB-SCHEMA]  "Open vSwitch Database Schema",
+                <http://openvswitch.org/ovs-vswitchd.conf.db.5.pdf>.
+
+   [OF-SPEC]    Open Networking Foundation, "OpenFlow Switch
+                Specification, version 1.3.3", October 2013,
+                <https://www.opennetworking.org>.
+
+   [OVS]        "Open vSwitch", <http://openvswitch.org/>.
+
+
+
+
+
+
+
+
+Pfaff & Davie                 Informational                    [Page 34]
+
+RFC 7047                OVSDB Management Protocol          December 2013
+
+
+Authors' Addresses
+
+   Ben Pfaff
+   VMware, Inc.
+   3401 Hillview Ave.
+   Palo Alto, CA  94304
+   USA
+
+   EMail: blp@nicira.com
+
+
+   Bruce Davie (editor)
+   VMware, Inc.
+   3401 Hillview Ave.
+   Palo Alto, CA  94304
+   USA
+
+   EMail: bsd@nicira.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Pfaff & Davie                 Informational                    [Page 35]
+