[ovs-dev] [PATCH v3 1/8] ovsdb: Improve documentation.
Yifeng Sun
pkusunyifeng at gmail.com
Fri Dec 15 00:01:55 UTC 2017
Thanks. It is a good reading and learning. I found a small issue in the
line below.
+ A boolean value, true if authorized insertions and authorized are
allowed,
For "insertions and authorized", maybe you are saying "insertions and
deletions".
Other than that, it looks good to me.
Reviewed-by: Yifeng Sun <pkusunyifeng at gmail.com>
On Wed, Dec 13, 2017 at 3:10 PM, Ben Pfaff <blp at ovn.org> wrote:
> Signed-off-by: Ben Pfaff <blp at ovn.org>
> ---
> Documentation/automake.mk | 5 +-
> Documentation/conf.py | 6 +
> Documentation/ref/index.rst | 3 +
> Documentation/ref/ovsdb-server.7.rst | 393 +++++++++++++++++++++++++
> Documentation/ref/ovsdb.5.rst | 125 ++++++++
> Documentation/ref/ovsdb.7.rst | 453 +++++++++++++++++++++++++++++
> NEWS | 4 +
> manpages.mk | 56 +---
> ovn/controller/ovn-controller.8.xml | 5 +-
> ovn/northd/ovn-northd.8.xml | 6 +-
> ovn/utilities/ovn-sbctl.8.in | 19 +-
> ovsdb/automake.mk | 10 +-
> ovsdb/ovsdb-client.1.in | 108 ++++---
> ovsdb/ovsdb-schemas.man | 19 ++
> ovsdb/ovsdb-server.1.in | 542 +++++-------------------------
> -----
> ovsdb/ovsdb-tool.1.in | 126 ++++----
> ovsdb/remote-active.man | 17 --
> ovsdb/remote-active.xml | 30 --
> ovsdb/remote-passive.man | 19 --
> ovsdb/remote-passive.xml | 36 ---
> ovsdb/replication-syn.man | 2 -
> ovsdb/replication.man | 23 --
> python/build/nroff.py | 15 +-
> utilities/ovs-vsctl.8.in | 21 +-
> vswitchd/ovs-vswitchd.8.in | 7 +-
> vtep/vtep-ctl.8.in | 23 +-
> 26 files changed, 1263 insertions(+), 810 deletions(-)
> create mode 100644 Documentation/ref/ovsdb-server.7.rst
> create mode 100644 Documentation/ref/ovsdb.5.rst
> create mode 100644 Documentation/ref/ovsdb.7.rst
> create mode 100644 ovsdb/ovsdb-schemas.man
> delete mode 100644 ovsdb/remote-active.man
> delete mode 100644 ovsdb/remote-active.xml
> delete mode 100644 ovsdb/remote-passive.man
> delete mode 100644 ovsdb/remote-passive.xml
> delete mode 100644 ovsdb/replication-syn.man
> delete mode 100644 ovsdb/replication.man
>
> diff --git a/Documentation/automake.mk b/Documentation/automake.mk
> index 3ea2c2cb5fe0..2b202cb2a836 100644
> --- a/Documentation/automake.mk
> +++ b/Documentation/automake.mk
> @@ -145,7 +145,10 @@ endif
> # rST formatted manpages under Documentation/ref.
> RST_MANPAGES = \
> ovs-test.8.rst \
> - ovs-vlan-test.8.rst
> + ovs-vlan-test.8.rst \
> + ovsdb-server.7.rst \
> + ovsdb.5.rst \
> + ovsdb.7.rst
>
> # The GNU standards say that these variables should control
> # installation directories for manpages in each section. Automake
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 108e679d059f..6ab144c5d1dd 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -118,6 +118,12 @@ _man_pages = [
> u'Check Linux drivers for performance, vlan and L3 tunneling
> problems'),
> ('ovs-vlan-test.8',
> u'Check Linux drivers for problems with vlan traffic'),
> + ('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/ref/index.rst b/Documentation/ref/index.rst
> index 3e2f8d5d96e0..d83b809f5e5b 100644
> --- a/Documentation/ref/index.rst
> +++ b/Documentation/ref/index.rst
> @@ -41,6 +41,9 @@ time:
>
> ovs-test.8
> ovs-vlan-test.8
> + 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
> new file mode 100644
> index 000000000000..feb093db22ae
> --- /dev/null
> +++ b/Documentation/ref/ovsdb-server.7.rst
> @@ -0,0 +1,393 @@
> +..
> + 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 Open vSwitch 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.
> +
> +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 authorized 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.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 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.
> +
> +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
> +columns with type "set of 0 or 1 integer" and "set of 0 or 1 real". 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
> new file mode 100644
> index 000000000000..db037181c5a3
> --- /dev/null
> +++ b/Documentation/ref/ovsdb.5.rst
> @@ -0,0 +1,125 @@
> +..
> + 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 Open vSwitch 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. This manpage documents the format used by Open vSwitch.
> +
> +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.
> +
> +Database files 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 JSON`` *length*
> *hash*,
> +where *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.
> diff --git a/Documentation/ref/ovsdb.7.rst b/Documentation/ref/ovsdb.7.rst
> new file mode 100644
> index 000000000000..1392ce6f72d7
> --- /dev/null
> +++ b/Documentation/ref/ovsdb.7.rst
> @@ -0,0 +1,453 @@
> +..
> + 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 Open vSwitch 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 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 a 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 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 two service models for databases: **standalone**, and
> +**active-backup**. The service models provide different compromises
> +among consistency and availability.
> +
> +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.
> +
> +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 done, 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.
> +
> +Open vSwitch 2.6 introduced support for the active-backup service model.
> +
> +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.
> +
> +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 connection from remote hosts. The most
> common
> +arrangement is to configure an 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:<ip>:<port>
> + The specified SSL or TLS <port> on the host at the given <ip>.
> +
> +tcp:<ip>:<port>
> + The specified TCP <port> on the host at the given <ip>.
> +
> +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.
> +
> +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 and
> connections
> + from IPv6 addresses are not accepted. 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 and connections from IPv6 addresses are
> not
> + accepted. 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. DNS
> names are
> +not accepted. To specify an IPv6 address, wrap it in square brackets,
> e.g.
> +``ssl:[::1]:6640``. 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.
> +
> +To restore from a backup, stop the database server or servers, overwrite
> +the database file with the backup (e.g. with ``cp``), and then
> +restart the servers.
> +
> +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.
> +
> +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.
> +
> +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`` 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
> 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 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 whose first
> +record is corrupted. 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)``.
> diff --git a/NEWS b/NEWS
> index d45904e9c1be..be9884eadeb9 100644
> --- a/NEWS
> +++ b/NEWS
> @@ -1,6 +1,10 @@
> Post-v2.8.0
> --------------------
> - NSH implementation now conforms to latest draft
> (draft-ietf-sfc-nsh-28).
> + - OVSDB:
> + * New high-level documentation in ovsdb(7).
> + * New file format documentation for developers in ovsdb(5).
> + * Protocol documentation moved from ovsdb-server(1) to
> ovsdb-server(7).
> - OVN:
> * The "requested-chassis" option for a logical switch port now
> accepts a
> chassis "hostname" in addition to a chassis "name".
> diff --git a/manpages.mk b/manpages.mk
> index d610d8862f24..7d6a507e0039 100644
> --- a/manpages.mk
> +++ b/manpages.mk
> @@ -16,11 +16,7 @@ ovn/utilities/ovn-sbctl.8: \
> lib/ssl-peer-ca-cert.man \
> lib/ssl.man \
> lib/table.man \
> - lib/vlog.man \
> - ovsdb/remote-active.man \
> - ovsdb/remote-active.man \
> - ovsdb/remote-passive.man \
> - ovsdb/remote-passive.man
> + lib/vlog.man
> ovn/utilities/ovn-sbctl.8.in:
> lib/common.man:
> lib/db-ctl-base.man:
> @@ -29,10 +25,6 @@ lib/ssl-peer-ca-cert.man:
> lib/ssl.man:
> lib/table.man:
> lib/vlog.man:
> -ovsdb/remote-active.man:
> -ovsdb/remote-active.man:
> -ovsdb/remote-passive.man:
> -ovsdb/remote-passive.man:
>
> ovsdb/ovsdb-client.1: \
> ovsdb/ovsdb-client.1.in \
> @@ -49,8 +41,7 @@ ovsdb/ovsdb-client.1: \
> lib/table.man \
> lib/vlog-syn.man \
> lib/vlog.man \
> - ovsdb/remote-active.man \
> - ovsdb/remote-passive.man
> + ovsdb/ovsdb-schemas.man
> ovsdb/ovsdb-client.1.in:
> lib/common-syn.man:
> lib/common.man:
> @@ -65,8 +56,7 @@ lib/ssl.man:
> lib/table.man:
> lib/vlog-syn.man:
> lib/vlog.man:
> -ovsdb/remote-active.man:
> -ovsdb/remote-passive.man:
> +ovsdb/ovsdb-schemas.man:
>
> ovsdb/ovsdb-server.1: \
> ovsdb/ovsdb-server.1.in \
> @@ -90,11 +80,7 @@ ovsdb/ovsdb-server.1: \
> lib/unixctl.man \
> lib/vlog-syn.man \
> lib/vlog-unixctl.man \
> - lib/vlog.man \
> - ovsdb/remote-active.man \
> - ovsdb/remote-passive.man \
> - ovsdb/replication-syn.man \
> - ovsdb/replication.man
> + lib/vlog.man
> ovsdb/ovsdb-server.1.in:
> lib/common-syn.man:
> lib/common.man:
> @@ -117,22 +103,20 @@ lib/unixctl.man:
> lib/vlog-syn.man:
> lib/vlog-unixctl.man:
> lib/vlog.man:
> -ovsdb/remote-active.man:
> -ovsdb/remote-passive.man:
> -ovsdb/replication-syn.man:
> -ovsdb/replication.man:
>
> ovsdb/ovsdb-tool.1: \
> ovsdb/ovsdb-tool.1.in \
> lib/common-syn.man \
> lib/common.man \
> lib/vlog-syn.man \
> - lib/vlog.man
> + lib/vlog.man \
> + ovsdb/ovsdb-schemas.man
> ovsdb/ovsdb-tool.1.in:
> lib/common-syn.man:
> lib/common.man:
> lib/vlog-syn.man:
> lib/vlog.man:
> +ovsdb/ovsdb-schemas.man:
>
> utilities/bugtool/ovs-bugtool.8: \
> utilities/bugtool/ovs-bugtool.8.in
> @@ -252,11 +236,7 @@ utilities/ovs-vsctl.8: \
> lib/table.man \
> lib/vconn-active.man \
> lib/vconn-passive.man \
> - lib/vlog.man \
> - ovsdb/remote-active.man \
> - ovsdb/remote-active.man \
> - ovsdb/remote-passive.man \
> - ovsdb/remote-passive.man
> + lib/vlog.man
> utilities/ovs-vsctl.8.in:
> lib/common.man:
> lib/db-ctl-base.man:
> @@ -267,10 +247,6 @@ lib/table.man:
> lib/vconn-active.man:
> lib/vconn-passive.man:
> lib/vlog.man:
> -ovsdb/remote-active.man:
> -ovsdb/remote-active.man:
> -ovsdb/remote-passive.man:
> -ovsdb/remote-passive.man:
>
> vswitchd/ovs-vswitchd.8: \
> vswitchd/ovs-vswitchd.8.in \
> @@ -287,9 +263,7 @@ vswitchd/ovs-vswitchd.8: \
> lib/vlog.man \
> ofproto/ofproto-dpif-unixctl.man \
> ofproto/ofproto-tnl-unixctl.man \
> - ofproto/ofproto-unixctl.man \
> - ovsdb/remote-active.man \
> - ovsdb/remote-passive.man
> + ofproto/ofproto-unixctl.man
> vswitchd/ovs-vswitchd.8.in:
> lib/common.man:
> lib/coverage-unixctl.man:
> @@ -305,8 +279,6 @@ lib/vlog.man:
> ofproto/ofproto-dpif-unixctl.man:
> ofproto/ofproto-tnl-unixctl.man:
> ofproto/ofproto-unixctl.man:
> -ovsdb/remote-active.man:
> -ovsdb/remote-passive.man:
>
> vtep/vtep-ctl.8: \
> vtep/vtep-ctl.8.in \
> @@ -316,11 +288,7 @@ vtep/vtep-ctl.8: \
> lib/ssl-peer-ca-cert.man \
> lib/ssl.man \
> lib/table.man \
> - lib/vlog.man \
> - ovsdb/remote-active.man \
> - ovsdb/remote-active.man \
> - ovsdb/remote-passive.man \
> - ovsdb/remote-passive.man
> + lib/vlog.man
> vtep/vtep-ctl.8.in:
> lib/common.man:
> lib/db-ctl-base.man:
> @@ -329,7 +297,3 @@ lib/ssl-peer-ca-cert.man:
> lib/ssl.man:
> lib/table.man:
> lib/vlog.man:
> -ovsdb/remote-active.man:
> -ovsdb/remote-active.man:
> -ovsdb/remote-passive.man:
> -ovsdb/remote-passive.man:
> diff --git a/ovn/controller/ovn-controller.8.xml b/ovn/controller/ovn-
> controller.8.xml
> index 5641abc7c6f3..2af3db5ab851 100644
> --- a/ovn/controller/ovn-controller.8.xml
> +++ b/ovn/controller/ovn-controller.8.xml
> @@ -55,10 +55,9 @@
> information from the local Open vSwitch's ovsdb-server instance.
> The default location is <code>db.sock</code> in the local Open
> vSwitch's "run" directory. It may be overridden by specifying the
> - <var>ovs-database</var> argument in one of the following forms:
> + <var>ovs-database</var> argument as an OVSDB active or passive
> + connection method, as described in <code>ovsdb</code>(7).
> </p>
> - <xi:include href="ovsdb/remote-active.xml" xmlns:xi="
> http://www.w3.org/2003/XInclude"/>
> - <xi:include href="ovsdb/remote-passive.xml" xmlns:xi="
> http://www.w3.org/2003/XInclude"/>
>
> <p>
> <code>ovn-controller</code> assumes it gets configuration
> diff --git a/ovn/northd/ovn-northd.8.xml b/ovn/northd/ovn-northd.8.xml
> index 27bb7c89d7b6..41fba1199510 100644
> --- a/ovn/northd/ovn-northd.8.xml
> +++ b/ovn/northd/ovn-northd.8.xml
> @@ -36,11 +36,9 @@
> </dd>
> </dl>
> <p>
> - <var>database</var> in the above options must take one of the
> following
> - forms:
> + <var>database</var> in the above options must be an OVSDB active or
> + passive connection method, as described in <code>ovsdb</code>(7).
> </p>
> - <xi:include href="ovsdb/remote-active.xml" xmlns:xi="
> http://www.w3.org/2003/XInclude"/>
> - <xi:include href="ovsdb/remote-passive.xml" xmlns:xi="
> http://www.w3.org/2003/XInclude"/>
>
> <h2>Daemon Options</h2>
> <xi:include href="lib/daemon.xml" xmlns:xi="http://www.w3.org/
> 2003/XInclude"/>
> diff --git a/ovn/utilities/ovn-sbctl.8.in b/ovn/utilities/ovn-sbctl.8.in
> index ec24da4ee754..cd43cf3beb6f 100644
> --- a/ovn/utilities/ovn-sbctl.8.in
> +++ b/ovn/utilities/ovn-sbctl.8.in
> @@ -58,11 +58,8 @@ Otherwise, the default is \fBunix:@RUNDIR@/ovnsb_db.sock\fR,
> but this
> default is unlikely to be useful outside of single-machine OVN test
> environments.
> .IP
> -\fIserver\fR must take one of the following forms:
> -.RS
> -.so ovsdb/remote-active.man
> -.so ovsdb/remote-passive.man
> -.RE
> +\fIserver\fR may be an OVSDB active or passive connection method,
> +e.g. \fBssl:192.168.10.5:6640\fR, as described in \fBovsdb\fR(7).
> .
> .IP "\fB\-\-no\-syslog\fR"
> By default, \fBovn\-sbctl\fR logs its arguments and the details of any
> @@ -210,14 +207,10 @@ Deletes the configured connection(s).
> .
> .IP "\fBset\-connection\fR [\fIaccess\-specifier\fR] \fItarget\fR\&..."
> Sets the configured manager target or targets. Each \fItarget\fR may
> -be preceded by an optional access-specifier (\fBread\-only\fR or
> -\fBread\-write\fR) and may use any of the following forms:
> -.
> -.RS
> -.so ovsdb/remote-active.man
> -.so ovsdb/remote-passive.man
> -.RE
> -
> +may be an OVSDB active or passive connection method,
> +e.g. \fBpssl:6640\fR, as described in \fBovsdb\fR(7),
> +optionally preceded by an optional access-specifier (\fBread\-only\fR or
> +\fBread\-write\fR).
> If provided, the effect of the access specifier persists for subsequent
> targets until changed by another access specifier.
> .
> diff --git a/ovsdb/automake.mk b/ovsdb/automake.mk
> index 50e5ab367eff..d040fc6de886 100644
> --- a/ovsdb/automake.mk
> +++ b/ovsdb/automake.mk
> @@ -46,15 +46,7 @@ ovsdb_libovsdb_la_CPPFLAGS = $(AM_CPPFLAGS)
> pkgconfig_DATA += \
> ovsdb/libovsdb.pc
>
> -MAN_FRAGMENTS += \
> - ovsdb/remote-active.man \
> - ovsdb/remote-passive.man \
> - ovsdb/replication.man \
> - ovsdb/replication-syn.man
> -
> -EXTRA_DIST += \
> - ovsdb/remote-active.xml \
> - ovsdb/remote-passive.xml
> +MAN_FRAGMENTS += ovsdb/ovsdb-schemas.man
>
> # ovsdb-tool
> bin_PROGRAMS += ovsdb/ovsdb-tool
> diff --git a/ovsdb/ovsdb-client.1.in b/ovsdb/ovsdb-client.1.in
> index d3dd84c3bb6a..694a7abed46d 100644
> --- a/ovsdb/ovsdb-client.1.in
> +++ b/ovsdb/ovsdb-client.1.in
> @@ -13,16 +13,18 @@
> ovsdb\-client \- command-line interface to \fBovsdb-server\fR(1)
> .
> .SH SYNOPSIS
> +.IP "Server-Level Commands:"
> \fBovsdb\-client \fR[\fIoptions\fR] \fBlist\-dbs \fR[\fIserver\fR]
> -.br
> +.IP "Database Schema Commands:"
> \fBovsdb\-client \fR[\fIoptions\fR] \fBget\-schema \fR[\fIserver\fR]
> \fR[\fIdatabase\fR]
> .br
> -\fBovsdb\-client \fR[\fIoptions\fR] \fBget\-schema\-version\fI
> \fR[\fIserver\fR] \fR[\fIdatabase\fR]
> -.br
> \fBovsdb\-client \fR[\fIoptions\fR] \fBlist\-tables\fI \fR[\fIserver\fR]
> \fR[\fIdatabase\fR]
> .br
> \fBovsdb\-client \fR[\fIoptions\fR] \fBlist\-columns\fI \fR[\fIserver\fR]
> \fR[\fIdatabase\fR] [\fItable\fR]
> +.IP "Database Version Management Commands:"
> .br
> +\fBovsdb\-client \fR[\fIoptions\fR] \fBget\-schema\-version\fI
> \fR[\fIserver\fR] \fR[\fIdatabase\fR]
> +.IP "Data Management Commands:"
> \fBovsdb\-client \fR[\fIoptions\fR] \fBtransact\fI \fR[\fIserver\fR]
> \fItransaction\fR
> .br
> \fBovsdb\-client \fR[\fIoptions\fR] \fBdump\fI \fR[\fIserver\fR]
> \fR[\fIdatabase\fR]\fR [\fItable\fR
> @@ -33,8 +35,9 @@ ovsdb\-client \- command-line interface to
> \fBovsdb-server\fR(1)
> .br
> \fBovsdb\-client \fR[\fIoptions\fR] \fBmonitor\fI \fR[\fIserver\fR]
> \fR[\fIdatabase\fR] \fBALL\fR
> .br
> -\fBovsdb\-client \fR[\fIoptions\fR] \fBmonitor-cond\fI \fR[\fIserver\fR]
> \fR[\fIdatabase\fR] \fIconditions
> +\fBovsdb\-client \fR[\fIoptions\fR] \fBmonitor\-cond\fI \fR[\fIserver\fR]
> \fR[\fIdatabase\fR] \fIconditions
> \fItable\fR [\fIcolumn\fR[\fB,\fIcolumn\fR]...]...
> +.IP "Testing Commands:"
> .br
> \fBovsdb\-client \fR[\fIoptions\fR] \fBlock\fI \fR[\fIserver\fR]
> \fIlock\fR
> .br
> @@ -42,6 +45,7 @@ ovsdb\-client \- command-line interface to
> \fBovsdb-server\fR(1)
> .br
> \fBovsdb\-client \fR[\fIoptions\fR] \fBunlock\fI \fR[\fIserver\fR]
> \fIlock\fR
> .br
> +.IP "Other Commands:"
> \fBovsdb\-client help\fR
> .IP "Output formatting options:"
> [\fB\-\-format=\fIformat\fR]
> @@ -60,40 +64,35 @@ ovsdb\-client \- command-line interface to
> \fBovsdb-server\fR(1)
> .SH DESCRIPTION
> The \fBovsdb\-client\fR program is a command-line client for
> interacting with a running \fBovsdb\-server\fR process.
> -Each command connects to an OVSDB server, which is
> -\fBunix:@RUNDIR@/db.sock\fR by default, or may be specified as
> -\fIserver\fR in one of the following forms:
> -.RS
> -.so ovsdb/remote-active.man
> -.so ovsdb/remote-passive.man
> -.RE
> +Each command connects to the specified OVSDB \fIserver\fR, which may
> +be an OVSDB active or passive connection method, as described in
> +\fBovsdb\fR(7). The default server is \fBunix:@RUNDIR@/db.sock\fR
> +and
> +the default \fIdatabase\fR is \fBOpen_vSwitch\fR.
> .PP
> -The default \fIdatabase\fR is \fBOpen_vSwitch\fR.
> +For an introduction to OVSDB and its implementation in Open vSwitch,
> +see \fBovsdb\fR(7).
> +.PP
> +The following sections describe the commands that \fBovsdb\-client\fR
> +supports.
> +.SS "Server-Level Commands"
> +Most \fBovsdb\-client\fR commands work with an individual database,
> +but these commands apply to an entire database server.
> .
> -.SS "Commands"
> -The following commands are implemented:
> .IP "\fBlist\-dbs \fR[\fIserver\fR]"
> Connects to \fIserver\fR, retrieves the list of known databases, and
> -prints them one per line. These database names are the ones that may
> -be used for \fIdatabase\fR in the following commands.
> +prints them one per line. These database names are the ones that
> +other commands may use for \fIdatabase\fR.
> +.
> +.SS "Database Schema Commands"
> +.PP
> +These commands obtain the schema from a database and print it or part
> +of it.
> .
> .IP "\fBget\-schema \fR[\fIserver\fR] \fR[\fIdatabase\fR]"
> Connects to \fIserver\fR, retrieves the schema for \fIdatabase\fR, and
> prints it in JSON format.
> .
> -.IP "\fBget\-schema\-version\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR]"
> -Connects to \fIserver\fR, retrieves the schema for \fIdatabase\fR, and
> -prints its version number on stdout. A schema version number has the form
> -\fIx\fB.\fIy\fB.\fIz\fR. See \fBovs\-vswitchd.conf.db\fR(5) for
> -details.
> -.IP
> -Schema version numbers and Open vSwitch version numbers are
> -independent.
> -.IP
> -If \fIdatabase\fR was created before schema versioning was introduced,
> -then it will not have a version number and this command will print a
> -blank line.
> -.
> .IP "\fBlist\-tables\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR]"
> Connects to \fIserver\fR, retrieves the schema for \fIdatabase\fR, and
> prints a table listing the name of each table
> @@ -105,10 +104,33 @@ prints a table listing the name and type of each
> column. If \fItable\fR is specified, only columns in that table are
> listed; otherwise, the tables include columns in all tables.
> .
> +.SS "Database Version Management Commands"
> +.so ovsdb/ovsdb-schemas.man
> +.PP
> +These commands work with different versions of OVSDB schemas and
> +databases.
> +.
> +.IP "\fBget\-schema\-version\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR]"
> +Connects to \fIserver\fR, retrieves the schema for \fIdatabase\fR, and
> +prints its version number on stdout.
> +If \fIdatabase\fR was created before schema versioning was introduced,
> +then it will not have a version number and this command will print a
> +blank line.
> +.
> +.IP "\fBget\-schema\-cksum\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR]"
> +Connects to \fIserver\fR, retrieves the schema for \fIdatabase\fR, and
> +prints its checksum on stdout. If \fIdatabase\fR does not include a
> +checksum, prints a blank line.
> +.
> +.SS "Data Management Commands"
> +.PP
> +These commands read or modify the data in a database.
> +.
> .IP "\fBtransact\fI \fR[\fIserver\fR] \fItransaction\fR"
> Connects to \fIserver\fR, sends it the specified \fItransaction\fR,
> -which must be a JSON array containing one or more valid OVSDB
> -operations, and prints the received reply on stdout.
> +which must be a JSON array appropriate for use as the \fBparams\fR to
> +a JSON-RPC \fBtransact\fR request, and prints the received reply on
> +stdout.
> .
> .IP "\fBdump\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR]\fR [\fItable
> \fR[\fIcolumn\fR...]]"
> Connects to \fIserver\fR, retrieves all of the data in \fIdatabase\fR,
> @@ -117,7 +139,7 @@ specified, only that table is retrieved. If at least
> one \fIcolumn\fR
> is specified, only those columns are retrieved.
> .
> .IP "\fBmonitor\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR] \fItable\fR
> [\fIcolumn\fR[\fB,\fIcolumn\fR]...]..."
> -.IQ "\fBmonitor-cond\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR]
> \fIconditions\fR \fItable\fR [\fIcolumn\fR[\fB,\fIcolumn\fR]...]..."
> +.IQ "\fBmonitor\-cond\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR]
> \fIconditions\fR \fItable\fR [\fIcolumn\fR[\fB,\fIcolumn\fR]...]..."
> Connects to \fIserver\fR and monitors the contents of rows that match
> conditions in
> \fItable\fR in \fIdatabase\fR. By default, the initial contents of
> \fItable\fR are
> printed, followed by each change as it occurs. If conditions empty,
> @@ -144,12 +166,12 @@ line.
> with the following change: A condition can be either a 3-element JSON
> array
> as deescribed in the RFC or a boolean value..
> .IP
> -If \fB\-\-detach\fR is used with \fBmonitor\fR or \fBmonitor-cond\fR, then
> +If \fB\-\-detach\fR is used with \fBmonitor\fR or \fBmonitor\-cond\fR,
> then
> \fBovsdb\-client\fR detaches after it has successfully received and
> printed the initial contents of \fItable\fR.
> .IP
> The \fBmonitor\fR command uses RFC 7047 "monitor" method to open a monitor
> -session with the server. The \fBmonitor-cond\fR command uses RFC 7047
> +session with the server. The \fBmonitor\-cond\fR command uses RFC 7047
> extension "monitor_cond" method. See \fBovsdb\-server\fR(1) for details.
> .IP "\fBmonitor\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR] \fBALL\fR"
> Connects to \fIserver\fR and monitors the contents of all tables in
> @@ -161,13 +183,13 @@ prints the initial database contents.
> The \fBmonitor\fR command uses RFC 7047 "monitor" method to open a monitor
> session with the server.
> .
> -.SH TESTING COMMANDS
> -The following commands are mostly of interest for testing the correctness
> +.SS "Testing commands"
> +These commands are mostly of interest for testing the correctness
> of the OVSDB server.
> .
> -.IP "\fBovsdb\-client\fR [\fIoptions\fR] \fBlock\fI \fR[\fIserver\fR]
> \fIlock\fR"
> -.IQ "\fBovsdb\-client\fR [\fIoptions\fR] \fBsteal\fI \fR[\fIserver\fR]
> \fIlock\fR"
> -.IQ "\fBovsdb\-client\fR [\fIoptions\fR] \fBunlock\fI \fR[\fIserver\fR]
> \fIlock\fR"
> +.IP "\fBlock\fI \fR[\fIserver\fR] \fIlock\fR"
> +.IQ "\fBsteal\fI \fR[\fIserver\fR] \fIlock\fR"
> +.IQ "\fBunlock\fI \fR[\fIserver\fR] \fIlock\fR"
> Connects to \fIserver\fR and issues corresponding RFC 7047 lock operations
> on \fIlock\fR. Prints json reply or subsequent update messages.
> The \fB\-\-detach\fR option causes \fBovsdb\-client\fR to detach after it
> @@ -190,13 +212,13 @@ The following options controlling output formatting:
> .so lib/table.man
> .
> .IP "\fB\-\-timestamp\fR"
> -For the \fBmonitor\fR and \fBmonitor-cond\fR commands, add a timestamp to
> each
> +For the \fBmonitor\fR and \fBmonitor\-cond\fR commands, add a timestamp
> to each
> table update. Most output formats add the timestamp on a line of its own
> just above the table. The JSON output format puts the timestamp in a
> member of the top-level JSON object named \fBtime\fR.
> .
> .SS "Daemon Options"
> -The daemon options apply only to the \fBmonitor\fR and \fBmonitor-cond\fR
> commands.
> +The daemon options apply only to the \fBmonitor\fR and
> \fBmonitor\-cond\fR commands.
> With any other command, they have no effect.
> .ds DD
> .so lib/daemon.man
> @@ -211,6 +233,6 @@ With any other command, they have no effect.
> .so lib/common.man
> .SH "SEE ALSO"
> .
> +\fBovsdb\fR(7),
> \fBovsdb\-server\fR(1),
> -\fBovsdb\-client\fR(1),
> -and the OVSDB specification.
> +\fBovsdb\-client\fR(1).
> diff --git a/ovsdb/ovsdb-schemas.man b/ovsdb/ovsdb-schemas.man
> new file mode 100644
> index 000000000000..3630d5da3dd8
> --- /dev/null
> +++ b/ovsdb/ovsdb-schemas.man
> @@ -0,0 +1,19 @@
> +.PP
> +An OVSDB schema has a schema version number, and an OVSDB database
> +embeds a particular version of an OVSDB schema. These version numbers
> +take the form \fIx\fB.\fIy\fB.\fIz\fR, e.g. \fB1.2.3\fR. The OVSDB
> +implementation does not enforce a particular version numbering scheme,
> +but schemas managed within the Open vSwitch project use the following
> +approach. Whenever the database schema is changed in a non-backward
> +compatible way (e.g. deleting a column or a table), \fIx\fR is
> +incremented (and \fIy\fR and \fIz\fR are reset to 0). When the
> +database schema is changed in a backward compatible way (e.g. adding a
> +new column), \fIy\fR is incremented (and \fIz\fR is reset to 0). When
> +the database schema is changed cosmetically (e.g. reindenting its
> +syntax), \fIz\fR is incremented.
> +.PP
> +Some OVSDB databases and schemas, especially very old ones, do not
> +have a version number.
> +.PP
> +Schema version numbers and Open vSwitch version numbers are
> +independent.
> diff --git a/ovsdb/ovsdb-server.1.in b/ovsdb/ovsdb-server.1.in
> index f1c6466ccb75..870459e5d9ac 100644
> --- a/ovsdb/ovsdb-server.1.in
> +++ b/ovsdb/ovsdb-server.1.in
> @@ -19,7 +19,10 @@ ovsdb\-server \- Open vSwitch database server
> .so lib/daemon-syn.man
> .so lib/service-syn.man
> .so lib/vlog-syn.man
> -.so ovsdb/replication-syn.man
> +.IP "Active-backup options:"
> +[\fB\-\-sync\-from=\fIserver\fR]
> +[\fB\-\-sync\-exclude-tables=\fIdb\fB:\fItable\fR[\fB,\
> fIdb\fB:\fItable\fR]...\fR]
> +[\fB\-\-active\fR]
> .so lib/ssl-syn.man
> .so lib/ssl-bootstrap-syn.man
> .so lib/ssl-peer-ca-cert-syn.man
> @@ -31,39 +34,26 @@ ovsdb\-server \- Open vSwitch database server
> The \fBovsdb\-server\fR program provides RPC interfaces to one or more
> Open vSwitch databases (OVSDBs). It supports JSON-RPC client
> connections over active or passive TCP/IP or Unix domain sockets.
> +For an introduction to OVSDB and its implementation in Open vSwitch,
> +see \fBovsdb\fR(7).
> .PP
> Each OVSDB file may be specified on the command line as \fIdatabase\fR.
> If none is specified, the default is \fB at DBDIR@/conf.db\fR. The database
> files must already have been created and initialized using, for
> example, \fBovsdb\-tool create\fR.
> -.
> -.SH "ACTIVE and BACKUP"
> -\fBovsdb\-server\fR runs either as a backup server, or as an active
> server.
> -When \fBovsdb\-server\fR is running as a backup server, all transactions
> that
> -can modify the database content, including the lock commands are rejected.
> -Active server, on the other hand, accepts all ovsdb server transactions.
> -When \fBovsdb\-server\fR role changes, all existing client connection are
> -reset, requiring clients to reconnect to the server.
> -.PP
> -By default, \fBovsdb\-server\fR runs as an active server, except when the
> -\fB\-\-sync\-from=\fIserver\fR command line option is specified and
> without
> -the \fB\-\-active\fR option. During runtime, \fBovsdb\-server\fR role
> can be switch by using appctl commands.
> .PP
> -\fBovsdb-server/connect\-active\-ovsdb\-server\fR switches
> -\fBovsdb\-server\fR into a backup server, Conversely,
> -\fBovsdb-server/disconnect\-active\-ovsdb\-server\fR switches server into
> -an active one.
> -.
> +This OVSDB implementation supports standalone and active-backup
> +databases, as well as database replication.
> +See the Service Models section of \fBovsdb\fR(7) for more information.
> .SH OPTIONS
> .
> .IP "\fB\-\-remote=\fIremote\fR"
> Adds \fIremote\fR as a connection method used by \fBovsdb\-server\fR.
> -\fIremote\fR must take one of the following forms:
> +The \fIremote\fR may be an OVSDB active or passive connection method,
> +e.g. \fBpssl:6640\fR, as described in \fBovsdb\fR(7). The following
> +additional form is also supported:
> .
> .RS
> -.so ovsdb/remote-passive.man
> -.so ovsdb/remote-active.man
> -.
> .IP "\fBdb:\fIdb\fB,\fItable\fB,\fIcolumn\fR"
> Reads additional connection methods from \fIcolumn\fR in all of the
> rows in \fItable\fR within \fIdb\fR. As the contents of \fIcolumn\fR
> changes,
> @@ -121,8 +111,50 @@ configured remotes.
> .so lib/service.man
> .SS "Logging Options"
> .so lib/vlog.man
> -.SS "Syncing Options"
> -.so ovsdb/replication.man
> +.SS "Active-Backup Options"
> +These options support the \fBovsdb\-server\fR active-backup service
> +model and database replication. By
> +default, when it serves a database in this format, \fBovsdb\-server\fR
> +runs as a standalone server. These options can configure it for
> +active-backup use:
> +.IP \(bu
> +Use \fB\-\-sync\-from=\fIserver\fR to start the server in the backup
> +role, replicating data from \fIserver\fR. When \fBovsdb\-server\fR is
> +running as a backup server, it rejects all transactions that can
> +modify the database content, including lock commands. The same form
> +can be used to configure the local database as a replica of
> +\fIserver\fR.
> +.IP \(bu
> +Use \fB\-\-sync\-from=\fIserver\fB \-\-active\fR to start the server
> +in the active role, but prepared to switch to the backup role in which
> +it would replicate data from \fIserver\fR. When \fBovsdb\-server\fR
> +runs in active mode, it allows all transactions, including those that
> +modify the database.
> +.PP
> +At runtime, management commands can change a server's role and otherwise
> +manage active-backup features. See \fBActive-Backup Commands\fR, below,
> +for more information.
> +.TP
> +\fB\-\-sync\-from=\fIserver\fR
> +Sets up \fBovsdb\-server\fR to synchronize its databases with the
> +databases in \fIserver\fR, which must be an active connection method
> +in one of the forms documented in \fBovsdb\-client\fR(1). Every
> +transaction committed by \fIserver\fR will be replicated to
> +\fBovsdb\-server\fR. This option makes \fBovsdb\-server\fR start
> +as a backup server; add \fB\-\-active\fR to make it start as an
> +active server.
> +.TP
> +\fB\-\-sync\-exclude-tables=\fIdb\fB:\fItable\fR[\fB,\fIdb\
> fB:\fItable\fR]...\fR
> +Causes the specified tables to be excluded from replication.
> +.TP
> +\fB\-\-active\fR
> +By default, \fB\-\-sync\-from\fR makes \fBovsdb\-server\fR start up as
> +a backup for \fIserver\fR. With \fB\-\-active\fR, however,
> +\fBovsdb\-server\fR starts as an active server. Use this option to
> +allow the syncing options to be specified using command line options,
> +yet start the server, as the default, active server. To switch the
> +running server to backup mode, use \fBovs-appctl(1)\fR to execute the
> +\fBovsdb\-server/connect\-active\-ovsdb\-server\fR command.
> .SS "Public Key Infrastructure Options"
> The options described below for configuring the SSL public key
> infrastructure accept a special syntax for obtaining their
> @@ -145,7 +177,7 @@ one row in \fItable\fR.)
> \fBovs\-appctl\fR(8) can send commands to a running
> \fBovsdb\-server\fR process. The currently supported commands are
> described below.
> -.SS "OVSDB\-SERVER COMMANDS"
> +.SS "\fBovsdb\-server\fR Commands"
> These commands are specific to \fBovsdb\-server\fR.
> .IP "\fBexit\fR"
> Causes \fBovsdb\-server\fR to gracefully terminate.
> @@ -210,23 +242,37 @@ again (with \fBovsdb\-server/add\-db\fR).
> Outputs a list of the currently configured databases added either through
> the command line or through the \fBovsdb\-server/add\-db\fR command.
> .
> +.SS "Active-Backup Commands"
> +.PP
> +These commands query and update the role of \fBovsdb\-server\fR within
> +an active-backup pair of servers. See \fBActive-Backup Options\fR,
> +above, and \fBActive-Backup Database Service Model\fR in
> +\fBovsdb\fR(7) for more information.
> +.
> .IP "\fBovsdb\-server/set\-active\-ovsdb\-server \fIserver"
> Sets the active \fIserver\fR from which \fBovsdb\-server\fR connects
> through
> \fBovsdb\-server/connect\-active\-ovsdb\-server\fR.
> +This overrides the \fB\-\-sync\-from\fR command-line option.
> .
> .IP "\fBovsdb\-server/get\-active\-ovsdb\-server"
> Gets the active server from which \fBovsdb\-server\fR is currently
> synchronizing
> its databases.
> .
> .IP "\fBovsdb\-server/connect\-active\-ovsdb\-server"
> -Causes \fBovsdb\-server\fR to synchronize its databases with the server
> -specified by \fBovsdb\-server/set\-active\-ovsdb\-server\fR.
> +Switches the server to a backup role. The server starts synchronizing
> +its databases with the active server specified by
> +\fBovsdb\-server/set\-active\-ovsdb\-server\fR (or the
> +\fB\-\-sync\-from\fR command-line option) and closes all existing
> +client connections, which requires clients to reconnect.
> .
> .IP "\fBovsdb\-server/disconnect\-active\-ovsdb\-server"
> -Causes \fBovsdb\-server\fR to stop synchronizing its databases with a
> active server.
> +Switches the server to an active role. The server stops synchronizing
> +its databases with an active server and closes all existing client
> +connections, which requires clients to reconnect.
> .
> .IP "\fBovsdb\-server/set\-sync\-exclude\-tables
> \fIdb\fB:\fItable\fR[\fB,\fIdb\fB:\fItable\fR]..."
> -Sets the \fItable\fR whitin \fIdb\fR that will be excluded from
> synchronization.
> +Sets the \fItable\fR within \fIdb\fR that will be excluded from
> synchronization.
> +This overrides the \fB\-\-sync\-exclude-tables\fR command-line option.
> .
> .IP "\fBovsdb\-server/get\-sync\-exclude\-tables"
> Gets the tables that are currently excluded from synchronization.
> @@ -244,438 +290,6 @@ excluded.
> .so lib/vlog-unixctl.man
> .so lib/memory-unixctl.man
> .so lib/coverage-unixctl.man
> -.SH "SPECIFICATIONS"
> -.
> -.PP
> -\fBovsdb\-server\fR implements the Open vSwitch Database (OVSDB)
> -protocol specified in RFC 7047, with the following clarifications:
> -.
> -.IP "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.
> -.
> -.IP
> -The definition of <error> allows for implementation extensions.
> -Currently \fBovsdb\-server\fR uses the following additional "error"
> -strings which might change in later releases):
> -.
> -.RS
> -.IP "\fBsyntax error\fR or \fBunknown column\fR"
> -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.
> -.IP "\fBinternal error\fR"
> -The request triggered a bug in \fBovsdb\-server\fR.
> -.IP "\fBovsdb error\fR"
> -A map or set contains a duplicate key.
> -.IP "\fBpermission error\fR"
> -The request was denied by the role-based access control extension,
> -introduced in version 2.8.
> -.RE
> -.
> -.IP "3.2. Schema Format"
> -RFC 7047 requires the "version" field in <database-schema>. Current
> -versions of \fBovsdb\-server\fR allow it to be omitted (future
> -versions are likely to require it).
> -.IP
> -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,
> -\fBovsdb\-server\fR forces columns that contain weak references to be
> -mutable.
> -.IP
> -Since version 2.8, the table name \fBRBAC_Role\fR is used internally
> -by the role-based access control extension to \fBovsdb\-server\fR 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:
> -.RS
> -.IP "\fBname\fR"
> -The role name.
> -.IP "\fBpermissions\fR"
> -A map of table name to a reference to a row in a separate permission
> -table.
> -.RE
> -.IP
> -The separate RBAC permission table has one row per access control
> -configuration and the following columns:
> -.RS
> -.IP "\fBname\fR"
> -The name of the table to which the row applies.
> -.IP "\fBauthorization\fR"
> -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.
> -.IP "\fBinsert_delete\fR"
> -A boolean value, true if authorized insertions and authorized are allowed,
> -false if no insertions or deletions are allowed.
> -.IP "\fBupdate\fR"
> -The set of columns and column:key pairs for which authorized update and
> -mutate operations should be permitted.
> -.RE
> -.
> -.IP "4. Wire Protocol"
> -The original OVSDB specifications included the following reason,
> -omitted from RFC 7047, to operate JSON-RPC directly over a stream
> -instead of over HTTP:
> -.
> -.RS
> -.IP \(bu
> -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.
> -.IP \(bu
> -HTTP is more complicated than stream connections and doesn't provide
> -any corresponding advantage.
> -.IP \(bu
> -The JSON-RPC specification for HTTP transport is incomplete.
> -.RE
> -.
> -.IP "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 "\fBRBAC_Role\fR" and the connection
> -on which the transaction request was received has an associated role
> -name (from the "\fBrole\fR" 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 \fBRBAC_Role\fR table and associated permissions table.
> -.
> -.IP "4.1.5. Monitor"
> -For backward compatibility, \fBovsdb\-server\fR currently permits a
> -single <monitor-request> to be used instead of an array; it is treated
> -as a single-element array. Future versions of \fBovsdb\-server\fR
> -might remove this compatibility feature.
> -.IP
> -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. \fBovsdb\-server\fR rejects attempt to create two
> -monitors with the same identifier.
> -.
> -.IP "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).
> -.
> -.IP
> -The monitor method described in Section 4.1.5 also applies to
> monitor_cond,
> -with the following exceptions:
> -.
> -.RS
> -.IP \(bu
> -RPC request method becomes "monitor_cond".
> -.IP \(bu
> -Reply result follows <table-updates2>, described in Section 4.1.14.
> -.IP \(bu
> -Subsequent changes are sent to the client using the "update2" monitor
> -notification, described in Section 4.1.14
> -.IP \(bu
> -Update notifications are being sent only for rows matching [<condition>*].
> -.RE
> -.
> -.IP
> -The request object has the following members:
> -.
> -.PP
> -.RS
> -.nf
> -"method": "monitor_cond"
> -"params": [<db-name>, <json-value>, <monitor-cond-requests>]
> -"id": <nonnull-json-value>
> -.fi
> -.RE
> -.
> -.IP
> -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>.
> -.
> -.IP
> -Each <monitor-cond-request> is an object with the following members:
> -.
> -.PP
> -.RS
> -.nf
> -"columns": [<column>*] optional
> -"where": [<condition>*] optional
> -"select": <monitor-select> optional
> -.fi
> -.RE
> -.
> -.IP
> -The "columns", if present, define the columns within the table to be
> monitored
> -that match conditions. If not present all columns are being monitored.
> -.
> -.IP
> -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.
> -.
> -.IP
> -<monitor-select> is an object with the following members:
> -.
> -.PP
> -.RS
> -.nf
> -"initial": <boolean> optional
> -"insert": <boolean> optional
> -"delete": <boolean> optional
> -"modify": <boolean> optional
> -.fi
> -.RE
> -.
> -.IP
> -The contents of this object specify how the columns or table are to be
> -monitored as explained in more detail below.
> -.
> -.IP
> -The response object has the following members:
> -.
> -.PP
> -.RS
> -.nf
> -"result": <table-updates2>
> -"error": null
> -"id": same "id" as request
> -.fi
> -.RE
> -.
> -.IP
> -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.
> -.
> -.IP
> -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.
> -.
> -.IP
> -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>:
> -.
> -.RS
> -.IP \(bu
> -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.
> -.IP \(bu
> -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.
> -.IP \(bu
> -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.
> -.IP \(bu
> -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.
> -.RE
> -.
> -.IP
> -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.
> -.
> -.IP "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.
> -.
> -.IP
> -The request object has the following members:
> -.
> -.IP
> -.RS
> -.nf
> -"method": "monitor_cond_change"
> -"params": [<json-value>, <json-value>, <monitor-cond-update-requests>]
> -"id": <nonnull-json-value>
> -.fi
> -.RE
> -.
> -.IP
> -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.
> -.
> -.IP
> -Each <monitor-cond-update-request> is an object with the following
> members:
> -.
> -.IP
> -.RS
> -.nf
> -"columns": [<column>*] optional
> -"where": [<condition>*] optional
> -.fi
> -.RE
> -.
> -.IP
> -The "columns" specify a new array of columns to be monitored
> -(Currently unsupported).
> -.
> -.IP
> -The "where" specify a new array of conditions to be applied to this
> monitoring
> -session.
> -.
> -.IP
> -The response object has the following members:
> -.
> -.IP
> -.RS
> -.nf
> -"result": null
> -"error": null
> -"id": same "id" as request
> -.fi
> -.RE
> -.IP
> -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.
> -.
> -.IP
> -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.
> -.
> -.IP "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:
> -.
> -.RS
> -.nf
> -"method": "update2"
> -"params": [<json-value>, <table-updates2>]
> -"id": null
> -.fi
> -.RE
> -.
> -.IP
> -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:
> -.
> -.RS
> -.IP "\(dqinitial\(dq: <row>"
> -present for "initial" updates
> -.IP "\(dqinsert\(dq: <row>"
> -present for "insert" updates
> -.IP "\(dqdelete\(dq: <row>"
> -present for "delete" updates
> -.IP "\(dqmodify\(dq: <row>"
> -present for "modify" updates
> -.RE
> -.
> -.IP
> -The format of <row> is described in Section 5.1.
> -.
> -.IP
> -<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.
> -.
> -.IP
> -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.
> -.
> -.IP
> -For columns with single value, the difference is the value of the new
> -column.
> -.
> -.IP
> -The difference between two sets are all elements that only belong
> -to one of the sets.
> -.
> -.IP
> -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.
> -.
> -.IP
> -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.
> -.
> -.IP "4.1.15. Get Server ID"
> -A new RPC method added in Open vSwitch version 2.7. The request contains
> -the following members:
> -.
> -.PP
> -.RS
> -.nf
> -"method": "get_server_id"
> -"params": null
> -"id": <nonnull-json-value>
> -.fi
> -.RE
> -.
> -.IP
> -The response object contains the following members:
> -.
> -.PP
> -.RS
> -.nf
> -"result": "<server_id>"
> -"error": null
> -"id": same "id" as request
> -.fi
> -.RE
> -.
> -.IP
> -<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.
> -.
> -.IP "5.1. Notation"
> -For <condition>, RFC 7047 only allows the use of \fB!=\fR, \fB==\fR,
> -\fBincludes\fR, and \fBexcludes\fR operators with set types. Open
> -vSwitch 2.4 and later extend <condition> to allow the use of \fB<\fR,
> -\fB<=\fR, \fB>=\fR, and \fB>\fR operators with columns with type ``set
> -of 0 or 1 integer'' and ``set of 0 or 1 real''. These conditions
> -evaluate to false when the column is empty, and otherwise as described
> -in RFC 7047 for integer and real types.
> -.
> -.IP
> -<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.
> -.
> -.IP "5.2.6. Wait"
> -.IQ "5.2.7. Commit"
> -.IQ "5.2.9. Comment"
> -RFC 7047 says that the \fBwait\fR, \fBcommit\fR, and \fBcomment\fR
> -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.
> -.
> .SH "BUGS"
> .
> In Open vSwitch before version 2.4, when \fBovsdb\-server\fR sent
> @@ -704,5 +318,7 @@ treat a \fBmonitor\fR response with a \fBresult\fR
> that contains an
> being monitored does not contain a table named \fBerror\fR).
> .
> .SH "SEE ALSO"
> -.
> -.BR ovsdb\-tool (1).
> +\fBovsdb\fR(7),
> +\fBovsdb\-tool\fR(1),
> +\fBovsdb\-server\fR(5),
> +\fBovsdb\-server\fR(7).
> diff --git a/ovsdb/ovsdb-tool.1.in b/ovsdb/ovsdb-tool.1.in
> index 8c799f4cc990..ebfd33b27163 100644
> --- a/ovsdb/ovsdb-tool.1.in
> +++ b/ovsdb/ovsdb-tool.1.in
> @@ -12,10 +12,10 @@
> ovsdb\-tool \- Open vSwitch database management utility
> .
> .SH SYNOPSIS
> +.IP "Database Creation Commands:"
> \fBovsdb\-tool \fR[\fIoptions\fR] \fBcreate \fR[\fIdb\fR [\fIschema\fR]]
> .br
> -\fBovsdb\-tool \fR[\fIoptions\fR] \fBcompact \fR[\fIdb\fR [\fItarget\fR]]
> -.br
> +.IP "Version Management Commands:"
> \fBovsdb\-tool \fR[\fIoptions\fR] \fBconvert \fR[\fIdb\fR [\fIschema
> \fR[\fItarget\fR]]]
> .br
> @@ -28,6 +28,8 @@ ovsdb\-tool \- Open vSwitch database management utility
> \fBovsdb\-tool \fR[\fIoptions\fR] \fBdb\-cksum \fR[\fIdb\fR]
> .br
> \fBovsdb\-tool \fR[\fIoptions\fR] \fBschema\-cksum \fR[\fIschema\fR]
> +.IP "Other commands:"
> +\fBovsdb\-tool \fR[\fIoptions\fR] \fBcompact \fR[\fIdb\fR [\fItarget\fR]]
> .br
> \fBovsdb\-tool \fR[\fIoptions\fR] \fBquery \fR[\fIdb\fR] \fItransaction\fR
> .br
> @@ -44,43 +46,30 @@ The \fBovsdb\-tool\fR program is a command-line tool
> for managing Open
> vSwitch database (OVSDB) files. It does not interact directly with
> running Open vSwitch database servers (instead, use
> \fBovsdb\-client\fR).
> +For an introduction to OVSDB and its implementation in Open vSwitch,
> +see \fBovsdb\fR(7).
> +.PP
> +This OVSDB implementation supports standalone and active-backup
> +database service models with a common on-disk format For a
> +specification of this format, see \fBovsdb\fR(5). For more
> +information on OVSDB service models, see the \fBService Models\fR
> +section in \fBovsdb\fR(7).
> .
> -.SS "Basic Commands"
> -.IP "\fBcreate\fI db schema\fR"
> -Reads an OVSDB schema from the file named \fIschema\fR and creates a
> -new OVSDB database file named \fIdb\fR using that schema. The new
> -database is initially empty. This command will not overwrite an
> -existing \fIdb\fR.
> -.IP
> -\fIschema\fR must contain an OVSDB schema in JSON format. Refer to
> -the OVSDB specification for details.
> +.SS "Database Creation Commands"
> +These commands create a new OVSDB database file.
> +They will not overwrite an existing database file. To
> +replace an existing database with a new one, first delete the old one.
> .
> -.IP "\fBcompact\fI db \fR[\fItarget\fR]"
> -Reads \fIdb\fR and writes a compacted version. If \fItarget\fR is
> -specified, the compacted version is written as a new file named
> -\fItarget\fR, which must not already exist. If \fItarget\fR is
> -omitted, then the compacted version of the database replaces \fIdb\fR
> -in-place.
> +.IP "\fBcreate\fI db schema\fR"
> +Use this command to create the database for controlling
> +\fBovs\-vswitchd\fR or another standalone or active-backup database.
> +It creates database file \fIdb\fR with the given \fIschema\fR, which
> +must be the name of a file that contains an OVSDB schema in JSON
> +format, as specified in the OVSDB specification. The new database is
> +initially empty.
> .
> .SS "Version Management Commands"
> -.PP
> -An OVSDB schema has a schema version number, and an OVSDB database
> -embeds a particular version of an OVSDB schema. These version numbers
> -take the form \fIx\fB.\fIy\fB.\fIz\fR, e.g. \fB1.2.3\fR. The OVSDB
> -implementation does not enforce a particular version numbering scheme,
> -but schemas managed within the Open vSwitch project use the following
> -approach. Whenever the database schema is changed in a non-backward
> -compatible way (e.g. deleting a column or a table), \fIx\fR is
> -incremented (and \fIy\fR and \fIz\fR are reset to 0). When the
> -database schema is changed in a backward compatible way (e.g. adding a
> -new column), \fIy\fR is incremented (and \fIz\fR is reset to 0). When
> -the database schema is changed cosmetically (e.g. reindenting its
> -syntax), \fIz\fR is incremented.
> -.
> -.PP
> -Some OVSDB databases and schemas, especially very old ones, do not
> -have a version number.
> -.
> +.so ovsdb/ovsdb-schemas.man
> .PP
> These commands work with different versions of OVSDB schemas and
> databases.
> @@ -91,7 +80,10 @@ Reads \fIdb\fR, translating it into to the schema
> specified in
> is specified, the translated version is written as a new file named
> \fItarget\fR, which must not already exist. If \fItarget\fR is
> omitted, then the translated version of the database replaces \fIdb\fR
> -in-place.
> +in-place. In-place conversion cannot take place if the database is
> +currently being served by \fBovsdb\-server\fR (instead, either stop
> +\fBovsdb\-server\fR first or use \fBovsdb\-client\fR's \fBconvert\fR
> +command).
> .IP
> This command can do simple ``upgrades'' and ``downgrades'' on a
> database's schema. The data in \fIdb\fR must be valid when
> @@ -100,44 +92,56 @@ interpreted under \fIschema\fR, with only one
> exception: data in
> ignored. Columns that exist in \fIschema\fR but not in \fIdb\fR are
> set to their default values. All of \fIschema\fR's constraints apply
> in full.
> -.
> +.IP
> +Some uses of this command can cause unrecoverable data loss. For
> +example, converting a database from a schema that has a given column
> +or table to one that does not will delete all data in that column or
> +table. Back up critical databases before converting them.
> +.IP
> .IP "\fBneeds\-conversion\fI db schema\fR"
> -Reads the schema embedded in \fIdb\fR and the standalone schema in
> +Reads the schema embedded in \fIdb\fR and the JSON schema from
> \fIschema\fR and compares them. If the schemas are the same, prints
> -\fBno\fR on stdout; if they differ, print \fByes\fR.
> -.
> +\fBno\fR on stdout; if they differ, prints \fByes\fR.
> +.IP
> .IP "\fBdb\-version\fI db\fR"
> .IQ "\fBschema\-version\fI schema\fR"
> Prints the version number in the schema embedded within the database
> -\fIdb\fR or in the standalone schema \fIschema\fR on stdout. A schema
> -version number has the form \fIx\fB.\fIy\fB.\fIz\fR. See
> -\fBovs\-vswitchd.conf.db\fR(5) for details.
> -.IP
> -Schema version numbers and Open vSwitch version numbers are
> -independent.
> -.IP
> +\fIdb\fR or in the JSON schema \fIschema\fR on stdout.
> If \fIschema\fR or \fIdb\fR was created before schema versioning was
> introduced, then it will not have a version number and this command
> will print a blank line.
> -.
> +.IP
> .IP "\fBdb\-cksum\fI db\fR"
> .IQ "\fBschema\-cksum\fI schema\fR"
> Prints the checksum in the schema embedded within the database
> -\fIdb\fR or of the standalone schema \fIschema\fR on stdout.
> -.IP
> +\fIdb\fR or of the JSON schema \fIschema\fR on stdout.
> If \fIschema\fR or \fIdb\fR was created before schema checksums were
> introduced, then it will not have a checksum and this command
> will print a blank line.
> -.
> +.IP
> .SS "Other Commands"
> .
> +.IP "\fBcompact\fI db \fR[\fItarget\fR]"
> +Reads \fIdb\fR and writes a compacted version. If \fItarget\fR is
> +specified, the compacted version is written as a new file named
> +\fItarget\fR, which must not already exist. If \fItarget\fR is
> +omitted, then the compacted version of the database replaces \fIdb\fR
> +in-place. This command is not needed in normal operation because
> +\fBovsdb\-server\fR from time to time automatically compacts a
> +database that grows much larger than its minimum size.
> +.IP
> +This command does not work if \fIdb\fR is currently being served by
> +\fBovsdb\-server\fR, or if it is otherwise locked for writing by
> +another process. Instead, send the \fBovsdb\-server/compact\fR
> +command to \fBovsdb\-server\fR, via \fBovs\-appctl\fR).
> +.
> .IP "[\fB\-\-rbac\-role=\fIrole\fR] \fBquery\fI db transaction\fR"
> Opens \fIdb\fR, executes \fItransaction\fR on it, and prints the
> results. The \fItransaction\fR must be a JSON array in the format of
> the \fBparams\fR array for the JSON-RPC \fBtransact\fR method, as
> described in the OVSDB specification.
> .IP
> -The \fIdb\fR is opened for read-only access, so this command may
> +This command opens \fIdb\fR for read-only access, so it may
> safely run concurrently with other database activity, including
> \fBovsdb\-server\fR and other database writers. The \fItransaction\fR
> may specify database modifications, but these will have no effect on
> @@ -152,11 +156,10 @@ and commits any changes to \fIdb\fR. The
> \fItransaction\fR must be a
> JSON array in the format of the \fBparams\fR array for the JSON-RPC
> \fBtransact\fR method, as described in the OVSDB specification.
> .IP
> -The \fIdb\fR is opened and locked for read/write access, so this
> -command will fail if the database is opened for writing by any other
> -process, including \fBovsdb\-server\fR(1). Use \fBovsdb\-client\fR(1),
> -instead, to write to a database that is served by
> -\fBovsdb\-server\fR(1).
> +This command does not work if \fIdb\fR is currently being served by
> +\fBovsdb\-server\fR, or if it is otherwise locked for writing by
> +another process. Instead, use \fBovsdb\-client\fR's \fBtransact\fR
> +command to send the query to \fBovsdb\-server\fR.
> .IP
> By default, the transaction is executed using the ``superuser'' RBAC
> role. Use \fB\-\-rbac\-role\fR to specify a different role.
> @@ -173,6 +176,11 @@ modified by each transaction. With two \fB\-m\fRs,
> \fBshow\-log\fR
> also prints the values of the columns modified by each change to a
> record.
> .
> +.IP "\fBdb\-name \fR[\fIdb\fR]"
> +.IQ "\fBschema\-name \fR[\fIschema\fR]"
> +Prints the name of the schema embedded within the database \fIdb\fR or
> +in the JSON schema \fIschema\fR on stdout.
> +.
> .SH OPTIONS
> .SS "Logging Options"
> .so lib/vlog.man
> @@ -184,6 +192,6 @@ default \fIschema\fR is \...
>
> [Message clipped]
More information about the dev
mailing list