GENWiki

Premier IT Outsourcing and Support Services within the UK

User Tools

Site Tools

Problem, Formatting or Query -  Send Feedback

Was this page helpful?-10+1


rfc:rfc7047

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]

/data/webs/external/dokuwiki/data/pages/rfc/rfc7047.txt · Last modified: 2013/12/16 23:46 (external edit)