From: Dave Tucker <d...@dtucker.co.uk> Submitted-at: https://github.com/ovn-org/ovn/pull/38 Signed-off-by: Dave Tucker <d...@dtucker.co.uk> Signed-off-by: Numan Siddique <num...@ovn.org> --- Documentation/automake.mk | 5 +- Documentation/conf.py | 6 - .../contributing/documentation-style.rst | 2 +- Documentation/ref/index.rst | 3 - Documentation/ref/ovsdb-server.7.rst | 545 --------------- Documentation/ref/ovsdb.5.rst | 308 --------- Documentation/ref/ovsdb.7.rst | 650 ------------------ 7 files changed, 2 insertions(+), 1517 deletions(-) delete mode 100644 Documentation/ref/ovsdb-server.7.rst delete mode 100644 Documentation/ref/ovsdb.5.rst delete mode 100644 Documentation/ref/ovsdb.7.rst
diff --git a/Documentation/automake.mk b/Documentation/automake.mk index ca1fb1222..e0f39b33f 100644 --- a/Documentation/automake.mk +++ b/Documentation/automake.mk @@ -98,10 +98,7 @@ endif # rules. # rST formatted manpages under Documentation/ref. -RST_MANPAGES = \ - ovsdb-server.7.rst \ - ovsdb.5.rst \ - ovsdb.7.rst +RST_MANPAGES = # rST formatted manpages that we don't want to install because they # document stuff that only works with a build tree, not with an diff --git a/Documentation/conf.py b/Documentation/conf.py index c7949b73e..f072a4879 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -116,12 +116,6 @@ html_static_path = ['_static'] _man_pages = [ ('ovn-sim.1', u'Open Virtual Network simulator environment'), - ('ovsdb-server.7', - u'Open vSwitch Database Server Protocol'), - ('ovsdb.5', - u'Open vSwitch Database (File Formats)'), - ('ovsdb.7', - u'Open vSwitch Database (Overview)'), ] # Generate list of (path, name, description, [author, ...], section) diff --git a/Documentation/internals/contributing/documentation-style.rst b/Documentation/internals/contributing/documentation-style.rst index e86fcf19c..1c44fbb57 100644 --- a/Documentation/internals/contributing/documentation-style.rst +++ b/Documentation/internals/contributing/documentation-style.rst @@ -341,7 +341,7 @@ In addition to the above, man pages have some specific requirements: - The man page must be included in the list of man page documents found in `conf.py`__ -Refer to existing man pages, such as :doc:`/ref/ovsdb-server.7` for a worked +Refer to existing man pages, such as :doc:`/ref/ovn-sim.1` for a worked example. __ http://www.sphinx-doc.org/en/stable/domains.html#directive-program diff --git a/Documentation/ref/index.rst b/Documentation/ref/index.rst index ecb181c6f..124388977 100644 --- a/Documentation/ref/index.rst +++ b/Documentation/ref/index.rst @@ -40,9 +40,6 @@ time: :maxdepth: 3 ovn-sim.1 - ovsdb-server.7 - ovsdb.5 - ovsdb.7 The remainder are still in roff format can be found below: diff --git a/Documentation/ref/ovsdb-server.7.rst b/Documentation/ref/ovsdb-server.7.rst deleted file mode 100644 index d47f7ad85..000000000 --- a/Documentation/ref/ovsdb-server.7.rst +++ /dev/null @@ -1,545 +0,0 @@ -.. - Copyright (c) 2017 Nicira, Inc. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - - Convention for heading levels in OVN documentation: - - ======= Heading 0 (reserved for the title in a document) - ------- Heading 1 - ~~~~~~~ Heading 2 - +++++++ Heading 3 - ''''''' Heading 4 - - Avoid deeper levels because they do not render well. - -============ -ovsdb-server -============ - -Description -=========== - -``ovsdb-server`` implements the Open vSwitch Database (OVSDB) protocol -specified in RFC 7047. This document provides clarifications for how -``ovsdb-server`` implements the protocol and describes the extensions that it -provides beyond RFC 7047. Numbers in section headings refer to corresponding -sections in RFC 7047. - -3.1 JSON Usage --------------- - -RFC 4627 says that names within a JSON object should be unique. -The Open vSwitch JSON parser discards all but the last value -for a name that is specified more than once. - -The definition of <error> allows for implementation extensions. -Currently ``ovsdb-server`` uses the following additional ``error`` -strings (which might change in later releases): - -``syntax error`` or ``unknown column`` - The request could not be parsed as an OVSDB request. An additional - ``syntax`` member, whose value is a string that contains JSON, may narrow - down the particular syntax that could not be parsed. - -``internal error`` - The request triggered a bug in ``ovsdb-server``. - -``ovsdb error`` - A map or set contains a duplicate key. - -``permission error`` - The request was denied by the role-based access control extension, - introduced in version 2.8. - -3.2 Schema Format ------------------ - -RFC 7047 requires the ``version`` field in <database-schema>. Current versions -of ``ovsdb-server`` allow it to be omitted (future versions are likely to -require it). - -RFC 7047 allows columns that contain weak references to be immutable. This -raises the issue of the behavior of the weak reference when the rows that it -references are deleted. Since version 2.6, ``ovsdb-server`` forces columns -that contain weak references to be mutable. - -Since version 2.8, the table name ``RBAC_Role`` is used internally by the -role-based access control extension to ``ovsdb-server`` and should not be used -for purposes other than defining mappings of role names to table access -permissions. This table has one row per role name and the following columns: - -``name`` - The role name. - -``permissions`` - A map of table name to a reference to a row in a separate permission table. - -The separate RBAC permission table has one row per access control -configuration and the following columns: - -``name`` - The name of the table to which the row applies. - -``authorization`` - The set of column names and column:key pairs to be compared with the client - ID in order to determine the authorization status of the requested - operation. - -``insert_delete`` - A boolean value, true if authorized insertions and deletions are allowed, - false if no insertions or deletions are allowed. - -``update`` - The set of columns and column:key pairs for which authorized update and - mutate operations should be permitted. - -4 Wire Protocol ---------------- - -The original OVSDB specifications included the following reasons, omitted from -RFC 7047, to operate JSON-RPC directly over a stream instead of over HTTP: - -* JSON-RPC is a peer-to-peer protocol, but HTTP is a client-server protocol, - which is a poor match. Thus, JSON-RPC over HTTP requires the client to - periodically poll the server to receive server requests. - -* HTTP is more complicated than stream connections and doesn't provide any - corresponding advantage. - -* The JSON-RPC specification for HTTP transport is incomplete. - -4.1.3 Transact --------------- - -Since version 2.8, role-based access controls can be applied to operations -within a transaction that would modify the contents of the database (these -operations include row insert, row delete, column update, and column -mutate). Role-based access controls are applied when the database schema -contains a table with the name ``RBAC_Role`` and the connection on which the -transaction request was received has an associated role name (from the ``role`` -column in the remote connection table). When role-based access controls are -enabled, transactions that are otherwise well-formed may be rejected depending -on the client's role, ID, and the contents of the ``RBAC_Role`` table and -associated permissions table. - -4.1.5 Monitor -------------- - -For backward compatibility, ``ovsdb-server`` currently permits a single -<monitor-request> to be used instead of an array; it is treated as a -single-element array. Future versions of ``ovsdb-server`` might remove this -compatibility feature. - -Because the <json-value> parameter is used to match subsequent update -notifications (see below) to the request, it must be unique among all active -monitors. ``ovsdb-server`` rejects attempt to create two monitors with the -same identifier. - -4.1.7 Monitor Cancellation --------------------------- - -When a database monitored by a session is removed, and database change -awareness is enabled for the session (see Section 4.1.16), the database server -spontaneously cancels all monitors (including conditional monitors described in -Section 4.1.12) for the removed database. For each canceled monitor, it issues -a notification in the following form:: - - "method": "monitor_canceled" - "params": [<json-value>] - "id": null - -4.1.12 Monitor_cond -------------------- - -A new monitor method added in Open vSwitch version 2.6. The ``monitor_cond`` -request enables a client to replicate subsets of tables within an OVSDB -database by requesting notifications of changes to rows matching one of the -conditions specified in ``where`` by receiving the specified contents of these -rows when table updates occur. ``monitor_cond`` also allows a more efficient -update notifications by receiving <table-updates2> notifications (described -below). - -The ``monitor`` method described in Section 4.1.5 also applies to -``monitor_cond``, with the following exceptions: - -* RPC request method becomes ``monitor_cond``. - -* Reply result follows <table-updates2>, described in Section 4.1.14. - -* Subsequent changes are sent to the client using the ``update2`` monitor - notification, described in Section 4.1.14 - -* Update notifications are being sent only for rows matching [<condition>*]. - - -The request object has the following members:: - - "method": "monitor_cond" - "params": [<db-name>, <json-value>, <monitor-cond-requests>] - "id": <nonnull-json-value> - -The <json-value> parameter is used to match subsequent update notifications -(see below) to this request. The <monitor-cond-requests> object maps the name -of the table to an array of <monitor-cond-request>. - -Each <monitor-cond-request> is an object with the following members:: - - "columns": [<column>*] optional - "where": [<condition>*] optional - "select": <monitor-select> optional - -The ``columns``, if present, define the columns within the table to be -monitored that match conditions. If not present, all columns are monitored. - -The ``where``, if present, is a JSON array of <condition> and boolean values. -If not present or condition is an empty array, implicit True will be considered -and updates on all rows will be sent. - -<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:: - - "result": <table-updates2> - "error": null - "id": same "id" as request - -The <table-updates2> object is described in detail in Section 4.1.14. 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 a specified table that match one of the -conditions in <monitor-cond-request> are committed, the changes are -automatically sent to the client using the ``update2`` monitor notification -(see Section 4.1.14). This monitoring persists until the JSON-RPC session -terminates or until the client sends a ``monitor_cancel`` JSON-RPC request. - -Each <monitor-cond-request> specifies one or more conditions and the manner in -which the rows that match the conditions are to be monitored. The -circumstances in which an ``update`` notification is sent for a row within the -table are determined by <monitor-select>: - -* If ``initial`` is omitted or true, every row in the original table that - matches one of the conditions is sent as part of the response to the - ``monitor_cond`` request. - -* If ``insert`` is omitted or true, update notifications are sent for rows - newly inserted into the table that match conditions or for rows modified in - the table so that their old version does not match the condition and new - version does. - -* If ``delete`` is omitted or true, update notifications are sent for rows - deleted from the table that match conditions or for rows modified in the - table so that their old version does match the conditions and new version - does not. - -* If ``modify`` is omitted or true, update notifications are sent whenever a - row in the table that matches conditions in both old and new version is - modified. - -Both ``monitor`` and ``monitor_cond`` sessions can exist concurrently. However, -``monitor`` and ``monitor_cond`` shares the same <json-value> parameter space; -it must be unique among all ``monitor`` and ``monitor_cond`` sessions. - -4.1.13 Monitor_cond_change --------------------------- - -The ``monitor_cond_change`` request enables a client to change an existing -``monitor_cond`` replication of the database by specifying a new condition and -columns for each replicated table. Currently changing the columns set is not -supported. - -The request object has the following members:: - - "method": "monitor_cond_change" - "params": [<json-value>, <json-value>, <monitor-cond-update-requests>] - "id": <nonnull-json-value> - -The <json-value> parameter should have a value of an existing conditional -monitoring session from this client. The second <json-value> in params array is -the requested value for this session. This value is valid only after -``monitor_cond_change`` is committed. A user can use these values to -distinguish between update messages before conditions update and after. The -<monitor-cond-update-requests> object maps the name of the table to an array of -<monitor-cond-update-request>. Monitored tables not included in -<monitor-cond-update-requests> retain their current conditions. - -Each <monitor-cond-update-request> is an object with the following members:: - - "columns": [<column>*] optional - "where": [<condition>*] optional - -The ``columns`` specify a new array of columns to be monitored, although this -feature is not yet supported. - -The ``where`` specify a new array of conditions to be applied to this -monitoring session. - -The response object has the following members:: - - "result": null - "error": null - "id": same "id" as request - -Subsequent <table-updates2> notifications are described in detail in Section -4.1.14 in the RFC. If insert contents are requested by original monitor_cond -request, <table-updates2> will contain rows that match the new condition and do -not match the old condition. If deleted contents are requested by origin -monitor request, <table-updates2> will contain any matched rows by old -condition and not matched by the new condition. - -Changes according to the new conditions are automatically sent to the client -using the ``update2`` monitor notification. An update, if any, as a result of -a condition change, will be sent to the client before the reply to the -``monitor_cond_change`` request. - -4.1.14 Update2 notification ---------------------------- - -The ``update2`` notification is sent by the server to the client to report -changes in tables that are being monitored following a ``monitor_cond`` request -as described above. The notification has the following members:: - - "method": "update2" - "params": [<json-value>, <table-updates2>] - "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-updates2> is an object that maps from a table name to a <table-update2>. -A <table-update2> is an object that maps from row's UUID to a <row-update2> -object. A <row-update2> is an object with one of the following members: - -``"initial": <row>`` - present for ``initial`` updates - -``"insert": <row>`` - present for ``insert`` updates - -``"delete": <row>`` - present for ``delete`` updates - -``"modify": <row>"`` - present for ``modify`` updates - -The format of <row> is described in Section 5.1. - -<row> is always a null object for a ``delete`` update. In ``initial`` and -``insert`` updates, <row> omits columns whose values equal the default value of -the column type. - -For a ``modify`` update, <row> contains only the columns that are modified. -<row> stores the difference between the old and new value for those columns, as -described below. - -For columns with single value, the difference is the value of the new column. - -The difference between two sets are all elements that only belong to one of the -sets. - -The difference between two maps are all key-value pairs whose keys appears in -only one of the maps, plus the key-value pairs whose keys appear in both maps -but with different values. For the latter elements, <row> includes the value -from the new column. - -Initial views of rows are not presented in update2 notifications, but in the -response object to the ``monitor_cond`` request. The formatting of the -<table-updates2> object, however, is the same in either case. - -4.1.15 Monitor_cond_since -------------------------- - -A new monitor method added in Open vSwitch version 2.12. The -``monitor_cond_since`` request enables a client to request changes that -happened after a specific transaction id. A client can use this feature to -request only latest changes after a server connection reset instead of -re-transfer all data from the server again. - -The ``monitor_cond`` method described in Section 4.1.12 also applies to -``monitor_cond_since``, with the following exceptions: - -* RPC request method becomes ``monitor_cond_since``. - -* Reply result includes extra parameters. - -* Subsequent changes are sent to the client using the ``update3`` monitor - notification, described in Section 4.1.16 - -The request object has the following members:: - - "method": "monitor_cond_since" - "params": [<db-name>, <json-value>, <monitor-cond-requests>, <last-txn-id>] - "id": <nonnull-json-value> - -The <last-txn-id> parameter is the transaction id that identifies the latest -data the client already has, and it requests server to send changes AFTER this -transaction (exclusive). - -All other parameters are the same as ``monitor_cond`` method. - -The response object has the following members:: - - "result": [<found>, <last-txn-id>, <table-updates2>] - "error": null - "id": same "id" as request - -The <found> is a boolean value that tells if the <last-txn-id> requested by -client is found in server's history or not. If true, the changes after that -version up to current is sent. Otherwise, all data is sent. - -The <last-txn-id> is the transaction id that identifies the latest transaction -included in the changes in <table-updates2> of this response, so that client -can keep tracking. If there is no change involved in this response, it is the -same as the <last-txn-id> in the request if <found> is true, or zero uuid if -<found> is false. If the server does not support transaction uuid, it will -be zero uuid as well. - -All other parameters are the same as in response object of ``monitor_cond`` -method. - -Like in ``monitor_cond``, subsequent changes that match conditions in -<monitor-cond-request> are automatically sent to the client, but using -``update3`` monitor notification (see Section 4.1.16), instead of ``update2``. - -4.1.16 Update3 notification ---------------------------- - -The ``update3`` notification is sent by the server to the client to report -changes in tables that are being monitored following a ``monitor_cond_since`` -request as described above. The notification has the following members:: - - "method": "update3" - "params": [<json-value>, <last-txn-id>, <table-updates2>] - "id": null - -The <last-txn-id> is the same as described in the response object of -``monitor_cond_since``. - -All other parameters are the same as in ``update2`` monitor notification (see -Section 4.1.14). - -4.1.17 Get Server ID --------------------- - -A new RPC method added in Open vSwitch version 2.7. The request contains the -following members:: - - "method": "get_server_id" - "params": null - "id": <nonnull-json-value> - -The response object contains the following members:: - - "result": "<server_id>" - "error": null - "id": same "id" as request - -<server_id> is JSON string that contains a UUID that uniquely identifies the -running OVSDB server process. A fresh UUID is generated when the process -restarts. - -4.1.18 Database Change Awareness --------------------------------- - -RFC 7047 does not provide a way for a client to find out about some kinds of -configuration changes, such as about databases added or removed while a client -is connected to the server, or databases changing between read/write and -read-only due to a transition between active and backup roles. Traditionally, -``ovsdb-server`` disconnects all of its clients when this happens, because this -prompts a well-written client to reassess what is available from the server -when it reconnects. - -OVS 2.9 provides a way for clients to keep track of these kinds of changes, by -monitoring the ``Database`` table in the ``_Server`` database introduced in -this release (see ``ovsdb-server(5)`` for details). By itself, this does not -suppress ``ovsdb-server`` disconnection behavior, because a client might -monitor this database without understanding its special semantics. Instead, -``ovsdb-server`` provides a special request:: - - "method": "set_db_change_aware" - "params": [<boolean>] - "id": <nonnull-json-value> - -If the boolean in the request is true, it suppresses the connection-closing -behavior for the current connection, and false restores the default behavior. -The reply is always the same:: - - "result": {} - "error": null - "id": same "id" as request - -4.1.19 Schema Conversion ------------------------- - -Open vSwitch 2.9 adds a new JSON-RPC request to convert an online database from -one schema to another. The request contains the following members:: - - "method": "convert" - "params": [<db-name>, <database-schema>] - "id": <nonnull-json-value> - -Upon receipt, the server converts database <db-name> to schema -<database-schema>. The schema's name must be <db-name>. The conversion is -atomic, consistent, isolated, and durable. The data in the database must be -valid when interpreted under <database-schema>, with only one exception: data -for tables and columns that do not exist in the new schema are ignored. -Columns that exist in <database-schema> but not in the database are set to -their default values. All of the new schema's constraints apply in full. - -If the conversion is successful, the server notifies clients that use the -``set_db_change_aware`` RPC introduced in Open vSwitch 2.9 and cancels their -outstanding transactions and monitors. The server disconnects other clients, -enabling them to notice the change when they reconnect. The server sends the -following reply:: - - "result": {} - "error": null - "id": same "id" as request - -If the conversion fails, then the server sends an error reply in the following -form:: - - "result": null - "error": [<error>] - "id": same "id" as request - -5.1 Notation ------------- - -For <condition>, RFC 7047 only allows the use of ``!=``, ``==``, ``includes``, -and ``excludes`` operators with set types. Open vSwitch 2.4 and later extend -<condition> to allow the use of ``<``, ``<=``, ``>=``, and ``>`` operators with -a column with type "set of 0 or 1 integer" and an integer argument, and with -"set of 0 or 1 real" and a real argument. These conditions evaluate to false -when the column is empty, and otherwise as described in RFC 7047 for integer -and real types. - -<condition> is specified in Section 5.1 in the RFC with the following change: A -condition can be either a 3-element JSON array as described in the RFC or a -boolean value. In case of an empty array an implicit true boolean value will be -considered. - -5.2.6 Wait, 5.2.7 Commit, 5.2.9 Comment ---------------------------------------- - -RFC 7047 says that the ``wait``, ``commit``, and ``comment`` operations have no -corresponding result object. This is not true. Instead, when such an -operation is successful, it yields a result object with no members. diff --git a/Documentation/ref/ovsdb.5.rst b/Documentation/ref/ovsdb.5.rst deleted file mode 100644 index 33f2583b8..000000000 --- a/Documentation/ref/ovsdb.5.rst +++ /dev/null @@ -1,308 +0,0 @@ -.. - Copyright (c) 2017 Nicira, Inc. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - - Convention for heading levels in OVN documentation: - - ======= Heading 0 (reserved for the title in a document) - ------- Heading 1 - ~~~~~~~ Heading 2 - +++++++ Heading 3 - ''''''' Heading 4 - - Avoid deeper levels because they do not render well. - -===== -ovsdb -===== - -Description -=========== - -OVSDB, the Open vSwitch Database, is a database system whose network protocol -is specified by RFC 7047. The RFC does not specify an on-disk storage format. -The OVSDB implementation in Open vSwitch implements two storage formats: one -for standalone (and active-backup) databases, and the other for clustered -databases. This manpage documents both of these formats. - -Most users do not need to be concerned with this specification. Instead, -to manipulate OVSDB files, refer to `ovsdb-tool(1)`. For an -introduction to OVSDB as a whole, read `ovsdb(7)`. - -OVSDB files explicitly record changes that are implied by the database schema. -For example, the OVSDB "garbage collection" feature means that when a client -removes the last reference to a garbage-collected row, the database server -automatically removes that row. The database file explicitly records the -deletion of the garbage-collected row, so that the reader does not need to -infer it. - -OVSDB files do not include the values of ephemeral columns. - -Standalone and clustered database files share the common structure described -here. They are text files encoded in UTF-8 with LF (U+000A) line ends, -organized as append-only series of records. Each record consists of 2 lines of -text. - -The first line in each record has the format ``OVSDB <magic> <length> <hash>``, -where <magic> is ``JSON`` for standalone databases or ``CLUSTER`` for clustered -databases, <length> is a positive decimal integer, and <hash> is a SHA-1 -checksum expressed as 40 hexadecimal digits. Words in the first line must be -separated by exactly one space. - -The second line must be exactly *length* bytes long (including the LF) and its -SHA-1 checksum (including the LF) must match *hash* exactly. The line's -contents must be a valid JSON object as specified by RFC 4627. Strings in the -JSON object must be valid UTF-8. To ensure that the second line is exactly one -line of text, the OVSDB implementation expresses any LF characters within a -JSON string as ``\n``. For the same reason, and to save space, the OVSDB -implementation does not "pretty print" the JSON object with spaces and LFs. -(The OVSDB implementation tolerates LFs when reading an OVSDB database file, as -long as *length* and *hash* are correct.) - -JSON Notation -------------- - -We use notation from RFC 7047 here to describe the JSON data in records. -In addition to the notation defined there, we add the following: - -<raw-uuid> - A 36-character JSON string that contains a UUID in the format described by - RFC 4122, e.g. ``"550e8400-e29b-41d4-a716-446655440000"`` - -Standalone Format ------------------ - -The first record in a standalone database contains the JSON schema for the -database, as specified in RFC 7047. Only this record is mandatory (a -standalone file that contains only a schema represents an empty database). - -The second and subsequent records in a standalone database are transaction -records. Each record may have the following optional special members, -which do not have any semantics but are often useful to administrators -looking through a database log with ``ovsdb-tool show-log``: - -``"_date": <integer>`` - The time at which the transaction was committed, as an integer number of - milliseconds since the Unix epoch. Early versions of OVSDB counted seconds - instead of milliseconds; these can be detected by noticing that their - values are less than 2**32. - - OVSDB always writes a ``_date`` member. - -``"_comment": <string>`` - A JSON string that specifies the comment provided in a transaction - ``comment`` operation. If a transaction has multiple ``comment`` - operations, OVSDB concatenates them into a single ``_comment`` member, - separated by a new-line. - - OVSDB only writes a ``_comment`` member if it would be a nonempty string. - -Each of these records also has one or more additional members, each of which -maps from the name of a database table to a <table-txn>: - -<table-txn> - A JSON object that describes the effects of a transaction on a database - table. Its names are <raw-uuid>s for rows in the table and its values are - <row-txn>s. - -<row-txn> - Either ``null``, which indicates that the transaction deleted this row, or - a JSON object that describes how the transaction inserted or modified the - row, whose names are the names of columns and whose values are <value>s - that give the column's new value. - - For new rows, the OVSDB implementation omits columns whose values have the - default values for their types defined in RFC 7047 section 5.2.1; for - modified rows, the OVSDB implementation omits columns whose values are - unchanged. - -Clustered Format ----------------- - -The clustered format has the following additional notation: - -<uint64> - A JSON integer that represents a 64-bit unsigned integer. The OVS JSON - implementation only supports integers in the range -2**63 through 2**63-1, - so 64-bit unsigned integer values from 2**63 through 2**64-1 are expressed - as negative numbers. - -<address> - A JSON string that represents a network address to support clustering, in - the ``<protocol>:<ip>:<port>`` syntax described in ``ovsdb-tool(1)``. - -<servers> - A JSON object whose names are <raw-uuid>s that identify servers and - whose values are <address>es that specify those servers' addresses. - -<cluster-txn> - A JSON array with two elements: - - 1. The first element is either a <database-schema> or ``null``. A - <database-schema> element is always present in the first record of a - clustered database to indicate the database's initial schema. If it is - not ``null`` in a later record, it indicates a change of schema for the - database. - - 2. The second element is either a transaction record in the format - described under ``Standalone Format'' above, or ``null``. - - When a schema is present, the transaction record is relative to an empty - database. That is, a schema change effectively resets the database to - empty and the transaction record represents the full database contents. - This allows readers to be ignorant of the full semantics of schema change. - -The first record in a clustered database contains the following members, -all of which are required: - -``"server_id": <raw-uuid>`` - The server's own UUID, which must be unique within the cluster. - -``"local_address": <address>`` - The address on which the server listens for connections from other - servers in the cluster. - -``name": <id>`` - The database schema name. It is only important when a server is in the - process of joining a cluster: a server will only join a cluster if the - name matches. (If the database schema name were unique, then we would - not also need a cluster ID.) - -``"cluster_id": <raw-uuid>`` - The cluster's UUID. The all-zeros UUID is not a valid cluster ID. - -``"prev_term": <uint64>`` and ``"prev_index": <uint64>`` - The Raft term and index just before the beginning of the log. - -``"prev_servers": <servers>`` - The set of one or more servers in the cluster at index "prev_index" and - term "prev_term". It might not include this server, if it was not the - initial server in the cluster. - -``"prev_data": <json-value>`` and ``"prev_eid": <raw-uuid>`` - A snapshot of the data in the database at index "prev_index" and term - "prev_term", and the entry ID for that data. The snapshot must contain a - schema. - -The second and subsequent records, if present, in a clustered database -represent changes to the database, to the cluster state, or both. There are -several types of these records. The most important types of records directly -represent persistent state described in the Raft specification: - -Entry - A Raft log entry. - -Term - The start of a new term. - -Vote - The server's vote for a leader in the current term. - -The following additional types of records aid debugging and troubleshooting, -but they do not affect correctness. - -Leader - Identifies a newly elected leader for the current term. - -Commit Index - An update to the server's ``commit_index``. - -Note - A human-readable description of some event. - -The table below identifies the members that each type of record contains. -"yes" indicates that a member is required, "?" that it is optional, blank that -it is forbidden, and [1] that ``data`` and ``eid`` must be either both present -or both absent. - -============ ===== ==== ==== ====== ============ ==== -member Entry Term Vote Leader Commit Index Note -============ ===== ==== ==== ====== ============ ==== -comment ? ? ? ? ? ? -term yes yes yes yes -index yes -servers ? -data [1] -eid [1] -vote yes -leader yes -commit_index yes -note yes -============ ===== ==== ==== ====== ============ ==== - -The members are: - -``"comment": <string>`` - A human-readable string giving an administrator more information about - the reason a record was emitted. - -``"term": <uint64>`` - The term in which the activity occurred. - -``"index": <uint64>`` - The index of a log entry. - -``"servers": <servers>`` - Server configuration in a log entry. - -``"data": <json-value>`` - The data in a log entry. - -``"eid": <raw-uuid>`` - Entry ID in a log entry. - -``"vote": <raw-uuid>`` - The server ID for which this server voted. - -``"leader": <raw-uuid>`` - The server ID of the server. Emitted by both leaders and followers when a - leader is elected. - -``"commit_index": <uint64>`` - Updated ``commit_index`` value. - -``"note": <string>`` - One of a few special strings indicating important events. The currently - defined strings are: - - ``"transfer leadership"`` - This server transferred leadership to a different server (with details - included in ``comment``). - - ``"left"`` - This server finished leaving the cluster. (This lets subsequent - readers know that the server is not part of the cluster and should not - attempt to connect to it.) - -Joining a Cluster -~~~~~~~~~~~~~~~~~ - -In addition to general format for a clustered database, there is also a special -case for a database file created by ``ovsdb-tool join-cluster``. Such a file -contains exactly one record, which conveys the information passed to the -``join-cluster`` command. It has the following members: - -``"server_id": <raw-uuid>`` and ``"local_address": <address>`` and ``"name": <id>`` - These have the same semantics described above in the general description - of the format. - -``"cluster_id": <raw-uuid>`` - This is provided only if the user gave the ``--cid`` option to - ``join-cluster``. It has the same semantics described above. - -``"remote_addresses"; [<address>*]`` - One or more remote servers to contact for joining the cluster. - -When the server successfully joins the cluster, the database file is replaced -by one described in `Clustered Format`_. diff --git a/Documentation/ref/ovsdb.7.rst b/Documentation/ref/ovsdb.7.rst deleted file mode 100644 index 87b9445cf..000000000 --- a/Documentation/ref/ovsdb.7.rst +++ /dev/null @@ -1,650 +0,0 @@ -.. - Copyright (c) 2017 Nicira, Inc. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - - Convention for heading levels in OVN documentation: - - ======= Heading 0 (reserved for the title in a document) - ------- Heading 1 - ~~~~~~~ Heading 2 - +++++++ Heading 3 - ''''''' Heading 4 - - Avoid deeper levels because they do not render well. - -===== -ovsdb -===== - -Description -=========== - -OVSDB, the Open vSwitch Database, is a network-accessible database system. -Schemas in OVSDB specify the tables in a database and their columns' types and -can include data, uniqueness, and referential integrity constraints. OVSDB -offers atomic, consistent, isolated, durable transactions. RFC 7047 specifies -the JSON-RPC based protocol that OVSDB clients and servers use to communicate. - -The OVSDB protocol is well suited for state synchronization because it -allows each client to monitor the contents of a whole database or a subset -of it. Whenever a monitored portion of the database changes, the server -tells the client what rows were added or modified (including the new -contents) or deleted. Thus, OVSDB clients can easily keep track of the -newest contents of any part of the database. - -While OVSDB is general-purpose and not particularly specialized for use with -Open vSwitch, Open vSwitch does use it for multiple purposes. The leading use -of OVSDB is for configuring and monitoring ``ovs-vswitchd(8)``, the Open -vSwitch switch daemon, using the schema documented in -``ovs-vswitchd.conf.db(5)``. The Open Virtual Network (OVN) sub-project of OVS -uses two OVSDB schemas, documented in ``ovn-nb(5)`` and ``ovn-sb(5)``. -Finally, Open vSwitch includes the "VTEP" schema, documented in -``vtep(5)`` that many third-party hardware switches support for -configuring VXLAN, although OVS itself does not directly use this schema. - -The OVSDB protocol specification allows independent, interoperable -implementations of OVSDB to be developed. Open vSwitch includes an OVSDB -server implementation named ``ovsdb-server(1)``, which supports several -protocol extensions documented in its manpage, and a basic command-line OVSDB -client named ``ovsdb-client(1)``, as well as OVSDB client libraries for C and -for Python. Open vSwitch documentation often speaks of these OVSDB -implementations in Open vSwitch as simply "OVSDB," even though that is distinct -from the OVSDB protocol; we make the distinction explicit only when it might -otherwise be unclear from the context. - -In addition to these generic OVSDB server and client tools, Open vSwitch -includes tools for working with databases that have specific schemas: -``ovs-vsctl`` works with the ``ovs-vswitchd`` configuration database, -``vtep-ctl`` works with the VTEP database, ``ovn-nbctl`` works with -the OVN Northbound database, and so on. - -RFC 7047 specifies the OVSDB protocol but it does not specify an on-disk -storage format. Open vSwitch includes ``ovsdb-tool(1)`` for working with its -own on-disk database formats. The most notable feature of this format is that -``ovsdb-tool(1)`` makes it easy for users to print the transactions that have -changed a database since the last time it was compacted. This feature is often -useful for troubleshooting. - -Schemas -======= - -Schemas in OVSDB have a JSON format that is specified in RFC 7047. They -are often stored in files with an extension ``.ovsschema``. An -on-disk database in OVSDB includes a schema and data, embedding both into a -single file. The Open vSwitch utility ``ovsdb-tool`` has commands -that work with schema files and with the schemas embedded in database -files. - -An Open vSwitch schema has three important identifiers. The first is its -name, which is also the name used in JSON-RPC calls to identify a database -based on that schema. For example, the schema used to configure Open -vSwitch has the name ``Open_vSwitch``. Schema names begin with a -letter or an underscore, followed by any number of letters, underscores, or -digits. The ``ovsdb-tool`` commands ``schema-name`` and -``db-name`` extract the schema name from a schema or database -file, respectively. - -An OVSDB schema also has a version of the form ``x.y.z`` e.g. ``1.2.3``. -Schemas managed within the Open vSwitch project manage version numbering in the -following way (but OVSDB does not mandate this approach). Whenever we change -the database schema in a non-backward compatible way (e.g. when we delete a -column or a table), we increment <x> and set <y> and <z> to 0. When we change -the database schema in a backward compatible way (e.g. when we add a new -column), we increment <y> and set <z> to 0. When we change the database schema -cosmetically (e.g. we reindent its syntax), we increment <z>. The -``ovsdb-tool`` commands ``schema-version`` and ``db-version`` extract the -schema version from a schema or database file, respectively. - -Very old OVSDB schemas do not have a version, but RFC 7047 mandates it. - -An OVSDB schema optionally has a "checksum." RFC 7047 does not specify the use -of the checksum and recommends that clients ignore it. Open vSwitch uses the -checksum to remind developers to update the version: at build time, if the -schema's embedded checksum, ignoring the checksum field itself, does not match -the schema's content, then it fails the build with a recommendation to update -the version and the checksum. Thus, a developer who changes the schema, but -does not update the version, receives an automatic reminder. In practice this -has been an effective way to ensure compliance with the version number policy. -The ``ovsdb-tool`` commands ``schema-cksum`` and ``db-cksum`` extract the -schema checksum from a schema or database file, respectively. - -Service Models -============== - -OVSDB supports three service models for databases: **standalone**, -**active-backup**, and **clustered**. The service models provide different -compromises among consistency, availability, and partition tolerance. They -also differ in the number of servers required and in terms of performance. The -standalone and active-backup database service models share one on-disk format, -and clustered databases use a different format, but the OVSDB programs work -with both formats. ``ovsdb(5)`` documents these file formats. - -RFC 7047, which specifies the OVSDB protocol, does not mandate or specify -any particular service model. - -The following sections describe the individual service models. - -Standalone Database Service Model ---------------------------------- - -A **standalone** database runs a single server. If the server stops running, -the database becomes inaccessible, and if the server's storage is lost or -corrupted, the database's content is lost. This service model is appropriate -when the database controls a process or activity to which it is linked via -"fate-sharing." For example, an OVSDB instance that controls an Open vSwitch -virtual switch daemon, ``ovs-vswitchd``, is a standalone database because a -server failure would take out both the database and the virtual switch. - -To set up a standalone database, use ``ovsdb-tool create`` to -create a database file, then run ``ovsdb-server`` to start the -database service. - -To configure a client, such as ``ovs-vswitchd`` or ``ovs-vsctl``, to use a -standalone database, configure the server to listen on a "connection method" -that the client can reach, then point the client to that connection method. -See `Connection Methods`_ below for information about connection methods. - -Active-Backup Database Service Model ------------------------------------- - -An **active-backup** database runs two servers (on different hosts). At any -given time, one of the servers is designated with the **active** role and the -other the **backup** role. An active server behaves just like a standalone -server. A backup server makes an OVSDB connection to the active server and -uses it to continuously replicate its content as it changes in real time. -OVSDB clients can connect to either server but only the active server allows -data modification or lock transactions. - -Setup for an active-backup database starts from a working standalone database -service, which is initially the active server. On another node, to set up a -backup server, create a database file with the same schema as the active -server. The initial contents of the database file do not matter, as long as -the schema is correct, so ``ovsdb-tool create`` will work, as will copying the -database file from the active server. Then use -``ovsdb-server --sync-from=<active>`` to start the backup server, where -<active> is an OVSDB connection method (see `Connection Methods`_ below) that -connects to the active server. At that point, the backup server will fetch a -copy of the active database and keep it up-to-date until it is killed. - -When the active server in an active-backup server pair fails, an administrator -can switch the backup server to an active role with the ``ovs-appctl`` command -``ovsdb-server/disconnect-active-ovsdb-server``. Clients then have read/write -access to the now-active server. Of course, administrators are slow to respond -compared to software, so in practice external management software detects the -active server's failure and changes the backup server's role. For example, the -"Integration Guide for Centralized Control" in the Open vSwitch documentation -describes how to use Pacemaker for this purpose in OVN. - -Suppose an active server fails and its backup is promoted to active. If the -failed server is revived, it must be started as a backup server. Otherwise, if -both servers are active, then they may start out of sync, if the database -changed while the server was down, and they will continue to diverge over time. -This also happens if the software managing the database servers cannot reach -the active server and therefore switches the backup to active, but other hosts -can reach both servers. These "split-brain" problems are unsolvable in general -for server pairs. - -Compared to a standalone server, the active-backup service model -somewhat increases availability, at a risk of split-brain. It adds -generally insignificant performance overhead. On the other hand, the -clustered service model, discussed below, requires at least 3 servers -and has greater performance overhead, but it avoids the need for -external management software and eliminates the possibility of -split-brain. - -Open vSwitch 2.6 introduced support for the active-backup service model. - -Clustered Database Service Model --------------------------------- - -A **clustered** database runs across 3 or 5 or more database servers (the -**cluster**) on different hosts. Servers in a cluster automatically -synchronize writes within the cluster. A 3-server cluster can remain available -in the face of at most 1 server failure; a 5-server cluster tolerates up to 2 -failures. Clusters larger than 5 servers will also work, with every 2 added -servers allowing the cluster to tolerate 1 more failure, but write performance -decreases. The number of servers should be odd: a 4- or 6-server cluster -cannot tolerate more failures than a 3- or 5-server cluster, respectively. - -To set up a clustered database, first initialize it on a single node by running -``ovsdb-tool create-cluster``, then start ``ovsdb-server``. Depending on its -arguments, the ``create-cluster`` command can create an empty database or copy -a standalone database's contents into the new database. - -To configure a client, such as ``ovn-controller`` or ``ovn-sbctl``, to use a -clustered database, first configure all of the servers to listen on a -connection method that the client can reach, then point the client to all of -the servers' connection methods, comma-separated. See `Connection Methods`_, -below, for more detail. - -Open vSwitch 2.9 introduced support for the clustered service model. - -How to Maintain a Clustered Database -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To add a server to a cluster, run ``ovsdb-tool join-cluster`` on the new server -and start ``ovsdb-server``. To remove a running server from a cluster, use -``ovs-appctl`` to invoke the ``cluster/leave`` command. When a server fails -and cannot be recovered, e.g. because its hard disk crashed, or to otherwise -remove a server that is down from a cluster, use ``ovs-appctl`` to invoke -``cluster/kick`` to make the remaining servers kick it out of the cluster. - -The above methods for adding and removing servers only work for healthy -clusters, that is, for clusters with no more failures than their maximum -tolerance. For example, in a 3-server cluster, the failure of 2 servers -prevents servers joining or leaving the cluster (as well as database access). -To prevent data loss or inconsistency, the preferred solution to this problem -is to bring up enough of the failed servers to make the cluster healthy again, -then if necessary remove any remaining failed servers and add new ones. If -this cannot be done, though, use ``ovs-appctl`` to invoke ``cluster/leave ---force`` on a running server. This command forces the server to which it is -directed to leave its cluster and form a new single-node cluster that contains -only itself. The data in the new cluster may be inconsistent with the former -cluster: transactions not yet replicated to the server will be lost, and -transactions not yet applied to the cluster may be committed. Afterward, any -servers in its former cluster will regard the server to have failed. - -Once a server leaves a cluster, it may never rejoin it. Instead, create a new -server and join it to the cluster. - -The servers in a cluster synchronize data over a cluster management protocol -that is specific to Open vSwitch; it is not the same as the OVSDB protocol -specified in RFC 7047. For this purpose, a server in a cluster is tied to a -particular IP address and TCP port, which is specified in the ``ovsdb-tool`` -command that creates or joins the cluster. The TCP port used for clustering -must be different from that used for OVSDB clients. To change the port or -address of a server in a cluster, first remove it from the cluster, then add it -back with the new address. - -To upgrade the ``ovsdb-server`` processes in a cluster from one version of Open -vSwitch to another, upgrading them one at a time will keep the cluster healthy -during the upgrade process. (This is different from upgrading a database -schema, which is covered later under `Upgrading or Downgrading a Database`_.) - -Clustered OVSDB does not support the OVSDB "ephemeral columns" feature. -``ovsdb-tool`` and ``ovsdb-client`` change ephemeral columns into persistent -ones when they work with schemas for clustered databases. Future versions of -OVSDB might add support for this feature. - -Understanding Cluster Consistency -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To ensure consistency, clustered OVSDB uses the Raft algorithm described in -Diego Ongaro's Ph.D. thesis, "Consensus: Bridging Theory and Practice". In an -operational Raft cluster, at any given time a single server is the "leader" and -the other nodes are "followers". Only the leader processes transactions, but a -transaction is only committed when a majority of the servers confirm to the -leader that they have written it to persistent storage. - -In most database systems, read and write access to the database happens through -transactions. In such a system, Raft allows a cluster to present a strongly -consistent transactional interface. OVSDB uses conventional transactions for -writes, but clients often effectively do reads a different way, by asking the -server to "monitor" a database or a subset of one on the client's behalf. -Whenever monitored data changes, the server automatically tells the client what -changed, which allows the client to maintain an accurate snapshot of the -database in its memory. Of course, at any given time, the snapshot may be -somewhat dated since some of it could have changed without the change -notification yet being received and processed by the client. - -Given this unconventional usage model, OVSDB also adopts an unconventional -clustering model. Each server in a cluster acts independently for the purpose -of monitors and read-only transactions, without verifying that data is -up-to-date with the leader. Servers forward transactions that write to the -database to the leader for execution, ensuring consistency. This has the -following consequences: - -* Transactions that involve writes, against any server in the cluster, are - linearizable if clients take care to use correct prerequisites, which is the - same condition required for linearizability in a standalone OVSDB. - (Actually, "at-least-once" consistency, because OVSDB does not have a session - mechanism to drop duplicate transactions if a connection drops after the - server commits it but before the client receives the result.) - -* Read-only transactions can yield results based on a stale version of the - database, if they are executed against a follower. Transactions on the - leader always yield fresh results. (With monitors, as explained above, a - client can always see stale data even without clustering, so clustering does - not change the consistency model for monitors.) - -* Monitor-based (or read-heavy) workloads scale well across a cluster, because - clustering OVSDB adds no additional work or communication for reads and - monitors. - -* A write-heavy client should connect to the leader, to avoid the overhead of - followers forwarding transactions to the leader. - -* When a client conducts a mix of read and write transactions across more than - one server in a cluster, it can see inconsistent results because a read - transaction might read stale data whose updates have not yet propagated from - the leader. By default, ``ovn-sbctl`` and similar utilities connect to the - cluster leader to avoid this issue. - - The same might occur for transactions against a single follower except that - the OVSDB server ensures that the results of a write forwarded to the leader - by a given server are visible at that server before it replies to the - requesting client. - -* If a client uses a database on one server in a cluster, then another server - in the cluster (perhaps because the first server failed), the client could - observe stale data. Clustered OVSDB clients, however, can use a column in - the ``_Server`` database to detect that data on a server is older than data - that the client previously read. The OVSDB client library in Open vSwitch - uses this feature to avoid servers with stale data. - -Database Replication -==================== - -OVSDB can layer **replication** on top of any of its service models. -Replication, in this context, means to make, and keep up-to-date, a read-only -copy of the contents of a database (the ``replica``). One use of replication -is to keep an up-to-date backup of a database. A replica used solely for -backup would not need to support clients of its own. A set of replicas that do -serve clients could be used to scale out read access to the primary database. - -A database replica is set up in the same way as a backup server in an -active-backup pair, with the difference that the replica is never promoted to -an active role. - -A database can have multiple replicas. - -Open vSwitch 2.6 introduced support for database replication. - -Connection Methods -================== - -An OVSDB **connection method** is a string that specifies how to make a -JSON-RPC connection between an OVSDB client and server. Connection methods are -part of the Open vSwitch implementation of OVSDB and not specified by RFC 7047. -``ovsdb-server`` uses connection methods to specify how it should listen for -connections from clients and ``ovsdb-client`` uses them to specify how it -should connect to a server. Connections in the opposite direction, where -``ovsdb-server`` connects to a client that is configured to listen for an -incoming connection, are also possible. - -Connection methods are classified as **active** or **passive**. An active -connection method makes an outgoing connection to a remote host; a passive -connection method listens for connections from remote hosts. The most common -arrangement is to configure an OVSDB server with passive connection methods and -clients with active ones, but the OVSDB implementation in Open vSwitch supports -the opposite arrangement as well. - -OVSDB supports the following active connection methods: - -ssl:<host>:<port> - The specified SSL or TLS <port> on the given <host>. - -tcp:<host>:<port> - The specified TCP <port> on the given <host>. - -unix:<file> - On Unix-like systems, connect to the Unix domain server socket named - <file>. - - On Windows, connect to a local named pipe that is represented by a file - created in the path <file> to mimic the behavior of a Unix domain socket. - -<method1>,<method2>,...,<methodN> - For a clustered database service to be highly available, a client must be - able to connect to any of the servers in the cluster. To do so, specify - connection methods for each of the servers separated by commas (and - optional spaces). - - In theory, if machines go up and down and IP addresses change in the right - way, a client could talk to the wrong instance of a database. To avoid - this possibility, add ``cid:<uuid>`` to the list of methods, where <uuid> - is the cluster ID of the desired database cluster, as printed by - ``ovsdb-tool db-cid``. This feature is optional. - -OVSDB supports the following passive connection methods: - -pssl:<port>[:<ip>] - Listen on the given TCP <port> for SSL or TLS connections. By default, - connections are not bound to a particular local IP address. Specifying - <ip> limits connections to those from the given IP. - -ptcp:<port>[:<ip>] - Listen on the given TCP <port>. By default, connections are not bound to a - particular local IP address. Specifying <ip> limits connections to those - from the given IP. - -punix:<file> - On Unix-like systems, listens for connections on the Unix domain socket - named <file>. - - On Windows, listens on a local named pipe, creating a named pipe - <file> to mimic the behavior of a Unix domain socket. - -All IP-based connection methods accept IPv4 and IPv6 addresses. To specify an -IPv6 address, wrap it in square brackets, e.g. ``ssl:[::1]:6640``. Passive -IP-based connection methods by default listen for IPv4 connections only; use -``[::]`` as the address to accept both IPv4 and IPv6 connections, -e.g. ``pssl:6640:[::]``. DNS names are also accepted if built with unbound -library. On Linux, use ``%<device>`` to designate a scope for IPv6 link-level -addresses, e.g. ``ssl:[fe80::1234%eth0]:6653``. - -The <port> may be omitted from connection methods that use a port number. The -default <port> for TCP-based connection methods is 6640, e.g. ``pssl:`` is -equivalent to ``pssl:6640``. In Open vSwitch prior to version 2.4.0, the -default port was 6632. To avoid incompatibility between older and newer -versions, we encourage users to specify a port number. - -The ``ssl`` and ``pssl`` connection methods requires additional configuration -through ``--private-key``, ``--certificate``, and ``--ca-cert`` command line -options. Open vSwitch can be built without SSL support, in which case these -connection methods are not supported. - -Database Life Cycle -=================== - -This section describes how to handle various events in the life cycle of -a database using the Open vSwitch implementation of OVSDB. - -Creating a Database -------------------- - -Creating and starting up the service for a new database was covered -separately for each database service model in the `Service -Models`_ section, above. - -Backing Up and Restoring a Database ------------------------------------ - -OVSDB is often used in contexts where the database contents are not -particularly valuable. For example, in many systems, the database for -configuring ``ovs-vswitchd`` is essentially rebuilt from scratch -at boot time. It is not worthwhile to back up these databases. - -When OVSDB is used for valuable data, a backup strategy is worth -considering. One way is to use database replication, discussed above in -`Database Replication`_ which keeps an online, up-to-date -copy of a database, possibly on a remote system. This works with all OVSDB -service models. - -A more common backup strategy is to periodically take and store a snapshot. -For the standalone and active-backup service models, making a copy of the -database file, e.g. using ``cp``, effectively makes a snapshot, and because -OVSDB database files are append-only, it works even if the database is being -modified when the snapshot takes place. This approach does not work for -clustered databases. - -Another way to make a backup, which works with all OVSDB service models, is to -use ``ovsdb-client backup``, which connects to a running database server and -outputs an atomic snapshot of its schema and content, in the same format used -for standalone and active-backup databases. - -Multiple options are also available when the time comes to restore a database -from a backup. For the standalone and active-backup service models, one option -is to stop the database server or servers, overwrite the database file with the -backup (e.g. with ``cp``), and then restart the servers. Another way, which -works with any service model, is to use ``ovsdb-client restore``, which -connects to a running database server and replaces the data in one of its -databases by a provided snapshot. The advantage of ``ovsdb-client restore`` is -that it causes zero downtime for the database and its server. It has the -downside that UUIDs of rows in the restored database will differ from those in -the snapshot, because the OVSDB protocol does not allow clients to specify row -UUIDs. - -None of these approaches saves and restores data in columns that the schema -designates as ephemeral. This is by design: the designer of a schema only -marks a column as ephemeral if it is acceptable for its data to be lost -when a database server restarts. - -Clustering and backup serve different purposes. Clustering increases -availability, but it does not protect against data loss if, for example, a -malicious or malfunctioning OVSDB client deletes or tampers with data. - -Changing Database Service Model -------------------------------- - -Use ``ovsdb-tool create-cluster`` to create a clustered database from the -contents of a standalone database. Use ``ovsdb-tool backup`` to create a -standalone database from the contents of a clustered database. - -Upgrading or Downgrading a Database ------------------------------------ - -The evolution of a piece of software can require changes to the schemas of the -databases that it uses. For example, new features might require new tables or -new columns in existing tables, or conceptual changes might require a database -to be reorganized in other ways. In some cases, the easiest way to deal with a -change in a database schema is to delete the existing database and start fresh -with the new schema, especially if the data in the database is easy to -reconstruct. But in many other cases, it is better to convert the database -from one schema to another. - -The OVSDB implementation in Open vSwitch has built-in support for some simple -cases of converting a database from one schema to another. This support can -handle changes that add or remove database columns or tables or that eliminate -constraints (for example, changing a column that must have exactly one value -into one that has one or more values). It can also handle changes that add -constraints or make them stricter, but only if the existing data in the -database satisfies the new constraints (for example, changing a column that has -one or more values into a column with exactly one value, if every row in the -column has exactly one value). The built-in conversion can cause data loss in -obvious ways, for example if the new schema removes tables or columns, or -indirectly, for example by deleting unreferenced rows in tables that the new -schema marks for garbage collection. - -Converting a database can lose data, so it is wise to make a backup beforehand. - -To use OVSDB's built-in support for schema conversion with a standalone or -active-backup database, first stop the database server or servers, then use -``ovsdb-tool convert`` to convert it to the new schema, and then restart the -database server. - -OVSDB also supports online database schema conversion for any of its database -service models. To convert a database online, use ``ovsdb-client convert``. -The conversion is atomic, consistent, isolated, and durable. ``ovsdb-server`` -disconnects any clients connected when the conversion takes place (except -clients that use the ``set_db_change_aware`` Open vSwitch extension RPC). Upon -reconnection, clients will discover that the schema has changed. - -Schema versions and checksums (see Schemas_ above) can give hints about whether -a database needs to be converted to a new schema. If there is any question, -though, the ``needs-conversion`` command on ``ovsdb-tool`` and ``ovsdb-client`` -can provide a definitive answer. - -Working with Database History ------------------------------ - -Both on-disk database formats that OVSDB supports are organized as a stream of -transaction records. Each record describes a change to the database as a list -of rows that were inserted or deleted or modified, along with the details. -Therefore, in normal operation, a database file only grows, as each change -causes another record to be appended at the end. Usually, a user has no need -to understand this file structure. This section covers some exceptions. - -Compacting Databases --------------------- - -If OVSDB database files were truly append-only, then over time they would grow -without bound. To avoid this problem, OVSDB can **compact** a database file, -that is, replace it by a new version that contains only the current database -contents, as if it had been inserted by a single transaction. From time to -time, ``ovsdb-server`` automatically compacts a database that grows much larger -than its minimum size. - -Because ``ovsdb-server`` automatically compacts databases, it is usually not -necessary to compact them manually, but OVSDB still offers a few ways to do it. -First, ``ovsdb-tool compact`` can compact a standalone or active-backup -database that is not currently being served by ``ovsdb-server`` (or otherwise -locked for writing by another process). To compact any database that is -currently being served by ``ovsdb-server``, use ``ovs-appctl`` to send the -``ovsdb-server/compact`` command. Each server in an active-backup or clustered -database maintains its database file independently, so to compact all of them, -issue this command separately on each server. - -Viewing History ---------------- - -The ``ovsdb-tool`` utility's ``show-log`` command displays the transaction -records in an OVSDB database file in a human-readable format. By default, it -shows minimal detail, but adding the option ``-m`` once or twice increases the -level of detail. In addition to the transaction data, it shows the time and -date of each transaction and any "comment" added to the transaction by the -client. The comments can be helpful for quickly understanding a transaction; -for example, ``ovs-vsctl`` adds its command line to the transactions that it -makes. - -The ``show-log`` command works with both OVSDB file formats, but the details of -the output format differ. For active-backup and clustered databases, the -sequence of transactions in each server's log will differ, even at points when -they reflect the same data. - -Truncating History ------------------- - -It may occasionally be useful to "roll back" a database file to an earlier -point. Because of the organization of OVSDB records, this is easy to do. -Start by noting the record number <i> of the first record to delete in -``ovsdb-tool show-log`` output. Each record is two lines of plain text, so -trimming the log is as simple as running ``head -n <j>``, where <j> = 2 * <i>. - -Corruption ----------- - -When ``ovsdb-server`` opens an OVSDB database file, of any kind, it reads as -many transaction records as it can from the file until it reaches the end of -the file or it encounters a corrupted record. At that point it stops reading -and regards the data that it has read to this point as the full contents of the -database file, effectively rolling the database back to an earlier point. - -Each transaction record contains an embedded SHA-1 checksum, which the server -verifies as it reads a database file. It detects corruption when a checksum -fails to verify. Even though SHA-1 is no longer considered secure for use in -cryptography, it is acceptable for this purpose because it is not used to -defend against malicious attackers. - -The first record in a standalone or active-backup database file specifies the -schema. ``ovsdb-server`` will refuse to work with a database where this record -is corrupted, or with a clustered database file with corruption in the first -few records. Delete and recreate such a database, or restore it from a backup. - -When ``ovsdb-server`` adds records to a database file in which it detected -corruption, it first truncates the file just after the last good record. - -See Also -======== - -RFC 7047, "The Open vSwitch Database Management Protocol." - -Open vSwitch implementations of generic OVSDB functionality: -``ovsdb-server(1)``, ``ovsdb-client(1)``, ``ovsdb-tool(1)``. - -Tools for working with databases that have specific OVSDB schemas: -``ovs-vsctl(8)``, ``vtep-ctl(8)``, ``ovn-nbctl(8)``, ``ovn-sbctl(8)``. - -OVSDB schemas for Open vSwitch and related functionality: -``ovs-vswitchd.conf.db(5)``, ``vtep(5)``, ``ovn-nb(5)``, ``ovn-sb(5)``. -- 2.26.2 _______________________________________________ dev mailing list d...@openvswitch.org https://mail.openvswitch.org/mailman/listinfo/ovs-dev