| Network Working Group | B. Pfaff |
| Internet-Draft | B. Davie, Ed. |
| Intended status: Informational | VMware, Inc. |
| Expires: March 14, 2014 | September 10, 2013 |
The Open vSwitch Database Management Protocol
draft-pfaff-ovsdb-proto-03
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.
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."
This Internet-Draft will expire on March 14, 2014.
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. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
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 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 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].
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].
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 at a relatively long timescale. Examples of operations that are supported by OVSDB include:
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].
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 protocol may be used to discover the schema currently in use.
OVSDB uses JSON [RFC4627] for both its schema format and its wire protocol format. The JSON implementation in Open vSwitch has the following limitations:
"error": <string> required
"details": <string> optional
The descriptions below use the following shorthand notations for JSON values. Terminology follows [RFC4627].
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.
"name": <id> required
"version": <version> required
"cksum": <string> optional
"tables": {<id>: <table-schema>, ...} required
"columns": {<id>: <column-schema>, ...} required
"maxRows": <integer> optional
"isRoot": <boolean> optional
"indexes": [<column-set>*] optional
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 below). 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".
"type": <type> required
"ephemeral": <boolean> optional
"mutable": <boolean> optional
"key": <base-type> required
"value": <base-type> optional
"min": <integer> optional
"max": <integer> or "unlimited" optional
"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"
"refTable" constraints are "deferred" constraints: they are enforced only at transaction commit time (see the "transact" request below). The other constraints on <base-type> are "immediate", enforced immediately by each operation.
The database wire protocol is implemented in JSON-RPC 1.0 [JSON-RPC]. While the spec of JSON-RPC allows a range of transports, implementations of this specification SHOULD operate directly over TCP. See Section 6 for discussion of the TCP port.
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 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.
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:
The response object contains the following members:
This operation retrieves a <database-schema> that describes hosted database <db-name>.
The request object contains the following members:
The response object contains the following members:
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:
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:
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.
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 that 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:
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:
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:
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.
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:
If the "transact" request can be completed immediately, then the server sends a response in the form described for "transact", above (Section 4.1.3). Otherwise, the server sends a JSON-RPC error response of the following form:
The "cancel" notification itself has no reply.
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:
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.
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:
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.
The <table-updates> object is described in detail in
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>:
If there is more than one <monitor-request> in an array of them, then each <monitor-request> in the array should specify both "columns" and "select", and the "columns" MUST be non-overlapping sets.
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:
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 "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>:
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 is the same in either case however.
The "monitor_cancel" request cancels a previously issued monitor request. The request object members are:
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:
In the event that a monitor cancellation request refers to an unknown monitor request, an error response with the following members is returned:
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 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:
The response depends on the request, and has the following members:
The three methods operate as follows:
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.
For a "lock" operation, the "locked" member in the response object is true if the lock has already been acquired, 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.
The "locked" notification is provided to notify a client that it has been granted a lock it had previously request a lock with the "lock" method described above. The notification has the following members:
"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.
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:
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.
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:
The response object has the following members:
This section describes the operations that may be specified in the "transact" method described in Section 4.1.3.
We introduce the following notation for the discussion of operations.
For "delete", <value> may have any number of elements, regardless of restrictions on the number of elements in <column>.
The operations that may be performed as part of a "transact" RPC request (see Section 4.1.3) are described in the following sections. 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.
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:
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>:
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.
The errors that may be returned are as follows:
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:
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.
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:
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:
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:
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.
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:
The "delete" object contains the following members:
"op": "delete" required
"table": <table> required
"where": [<condition>*] required
The corresponding result object contains the following member:
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.
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:
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:
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:
The "comment" object contains the following members:
"op": "comment" required
"comment": <string> required
There is no corresponding result object.
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.
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:
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.
This document requires no further IANA action.
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 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.
Thanks to Jeremy Stribling and Justin Pettit for their helpful input to this document.
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. |
| [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. |
| [JSON-RPC] | JSON-RPC Specification, Version 1.0", . | , "
| [DCE] | DCE: Remote Procedure Call", Open Group CAE Specification C309, ISBN 1-85912-041-5, August 1994. | , "
| [OVS] | Open vSwitch", . | , "
| [DB-SCHEMA] | Open vSwitch Database Schema", . | , "
| [OF-SPEC] | OpenFlow Switch Specification, version 1.3", . | , "