[ovs-dev] [PATCH ovn 4/7] documentation: Remove unused ovsdb manpages
numans at ovn.org
numans at ovn.org
Fri May 8 06:04:54 UTC 2020
From: Dave Tucker <dave at dtucker.co.uk>
Submitted-at: https://github.com/ovn-org/ovn/pull/38
Signed-off-by: Dave Tucker <dave at dtucker.co.uk>
Signed-off-by: Numan Siddique <numans at 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
More information about the dev
mailing list