@@ -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
@@ -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)
@@ -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:
new file mode 100644
@@ -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.
new file mode 100644
@@ -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.
new file mode 100644
@@ -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)``.
@@ -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".
@@ -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:
@@ -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
@@ -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"/>
@@ -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.
.
@@ -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
@@ -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
+For an introduction to OVSDB and its implementation in Open vSwitch,
+see \fBovsdb\fR(7).
.PP
-The default \fIdatabase\fR is \fBOpen_vSwitch\fR.
+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,28 @@ 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.
+.
+.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 +134,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 +161,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 +178,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 +207,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 +228,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).
new file mode 100644
@@ -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.
@@ -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@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).
@@ -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 \fB@pkgdatadir@/vswitch.ovsschema\fR. The
\fBhelp\fR command also displays these defaults.
.SH "SEE ALSO"
.
+\fBovsdb\fR(7),
\fBovsdb\-server\fR(1),
-\fBovsdb\-client\fR(1),
-and the OVSDB specification.
+\fBovsdb\-client\fR(1).
deleted file mode 100644
@@ -1,17 +0,0 @@
-.IP "\fBssl:\fIip\fB:\fIport\fR"
-.IQ "\fBtcp:\fIip\fB:\fIport\fR"
-The given SSL or plain TCP \fIport\fR on the host at the given
-\fIip\fR, which must be expressed as an IP address (not a DNS name) in
-IPv4 or IPv6 address format. If \fIip\fR is an IPv6 address, then
-wrap \fIip\fR with square brackets, e.g.: \fBssl:[::1]:6640\fR. On
-Linux, use \fB%\fIdevice\fR to designate a scope for IPv6 link-level
-addresses, e.g. \fBssl:[fe80::1234%eth0]:6653\fR. For \fBssl\fR, the
-\fB\-\-private\-key\fR, \fB\-\-certificate\fR, and \fB\-\-ca\-cert\fR
-options are mandatory.
-.
-.IP "\fBunix:\fIfile\fR"
-On POSIX, connect to the Unix domain server socket named \fIfile\fR.
-.IP
-On Windows, connect to a local named pipe that is represented by a file
-created in the path \fIfile\fR to mimic the behavior of a Unix domain
-socket.
deleted file mode 100644
@@ -1,30 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<dl>
- <dt><code>ssl:</code><var>ip</var><code>:</code><var>port</var></dt>
- <dd>
- The specified SSL <var>port</var> on the host at the given <var>ip</var>,
- which must be expressed as an IP address (not a DNS name) in IPv4 or IPv6
- address format. If <var>ip</var> is an IPv6 address, then wrap
- <var>ip</var> with square brackets, e.g.: <code>ssl:[::1]:6640</code>.
- The <code>--private-key</code>, <code>--certificate</code>, and
- <code>--ca-cert</code> options are mandatory when this form is used.
- </dd>
- <dt><code>tcp:</code><var>ip</var><code>:</code><var>port</var></dt>
- <dd>
- Connect to the given TCP <var>port</var> on <var>ip</var>, where
- <var>ip</var> can be an IPv4 or IPv6 address. If <var>ip</var> is an
- IPv6 address, then wrap <var>ip</var> with square brackets, e.g.:
- <code>tcp:[::1]:6640</code>.
- </dd>
- <dt><code>unix:</code><var>file</var></dt>
- <dd>
- <p>
- On POSIX, connect to the Unix domain server socket named <var>file</var>.
- </p>
- <p>
- On Windows, connect to a local named pipe that is represented by a file
- created in the path <var>file</var> to mimic the behavior of a Unix
- domain socket.
- </p>
- </dd>
-</dl>
deleted file mode 100644
@@ -1,19 +0,0 @@
-.IP "\fBpssl:\fIport\fR[\fB:\fIip\fR]"
-.IQ "\fBptcp:\fIport\fR[\fB:\fIip\fR]"
-Listen on the given SSL or TCP \fIport\fR for a connection. By
-default, connections are not bound to a particular local IP address
-and it listens only on IPv4 (but not IPv6) addresses, but specifying
-\fIip\fR limits connections to those from the given \fIip\fR, either
-IPv4 or IPv6 address. If \fIip\fR is an IPv6 address, then wrap
-\fIip\fR with square brackets, e.g.: \fBpssl:6640:[::1]\fR. On Linux,
-use \fB%\fIdevice\fR to designate a scope for IPv6 link-level
-addresses, e.g. \fBpssl:6653:[fe80::1234%eth0]\fR. For \fBpssl\fR,
-the \fB\-\-private\-key\fR, \fB\-\-certificate\fR, and
-\fB\-\-ca\-cert\fR options are mandatory.
-.
-.IP "\fBpunix:\fIfile\fR"
-On POSIX, listen on the Unix domain server socket named \fIfile\fR for a
-connection.
-.IP
-On Windows, listen on a local named pipe. A file is created in the
-path \fIfile\fR to mimic the behavior of a Unix domain socket.
deleted file mode 100644
@@ -1,36 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<dl>
- <dt><code>pssl:</code><var>port</var><code>:</code><var>ip</var></dt>
- <dd>
- Listen on the given SSL <var>port</var> for a connection. By default,
- connections are not bound to a particular local IP address and
- it listens only on IPv4 (but not IPv6) addresses, but
- specifying <var>ip</var> limits connections to those from the given
- <var>ip</var>, either IPv4 or IPv6 address. If <var>ip</var> is
- an IPv6 address, then wrap <var>ip</var> with square brackets, e.g.:
- <code>pssl:6640:[::1]</code>. The <code>--private-key</code>,
- <code>--certificate</code>, and <code>--ca-cert</code> options are
- mandatory when this form is used.
- </dd>
- <dt><code>ptcp:</code><var>port</var><code>:</code><var>ip</var></dt>
- <dd>
- Listen on the given TCP <var>port</var> for a connection. By default,
- connections are not bound to a particular local IP address and
- it listens only on IPv4 (but not IPv6) addresses, but
- <var>ip</var> may be specified to listen only for connections to the given
- <var>ip</var>, either IPv4 or IPv6 address. If <var>ip</var> is
- an IPv6 address, then wrap <var>ip</var> with square brackets, e.g.:
- <code>ptcp:6640:[::1]</code>.
- </dd>
- <dt><code>punix:</code><var>file</var></dt>
- <dd>
- <p>
- On POSIX, listen on the Unix domain server socket named <var>file</var>
- for a connection.
- </p>
- <p>
- On Windows, listen on a local named pipe. A file is created in the path
- <var>file</var> to mimic the behavior of a Unix domain socket.
- </p>
- </dd>
-</dl>
deleted file mode 100644
@@ -1,2 +0,0 @@
-.IP "Syncing options:"
-[\fB\-\-sync\-from=\fIserver\fR]
deleted file mode 100644
@@ -1,23 +0,0 @@
-The following options allow \fBovsdb\-server\fR to synchronize its databases
-with another running \fBovsdb\-server\fR.
-.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:table[,db:table]...\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.
@@ -80,23 +80,24 @@ def inline_xml_to_nroff(node, font, to_upper=False, newline='\n'):
s += inline_xml_to_nroff(child, r'\fB', to_upper, newline)
return s + font
elif node.tagName == 'ref':
- s = r'\fB'
if node.hasAttribute('column'):
- s += node.attributes['column'].nodeValue
+ s = node.attributes['column'].nodeValue
if node.hasAttribute('key'):
s += ':' + node.attributes['key'].nodeValue
elif node.hasAttribute('table'):
- s += node.attributes['table'].nodeValue
+ s = node.attributes['table'].nodeValue
elif node.hasAttribute('group'):
- s += node.attributes['group'].nodeValue
+ s = node.attributes['group'].nodeValue
elif node.hasAttribute('db'):
- s += node.attributes['db'].nodeValue
+ s = node.attributes['db'].nodeValue
elif node.hasAttribute('field'):
- s += node.attributes['field'].nodeValue
+ s = node.attributes['field'].nodeValue
+ elif node.hasAttribute('section'):
+ s = node.attributes['section'].nodeValue
else:
raise error.Error("'ref' lacks required attributes: %s"
% list(node.attributes.keys()))
- return s + font
+ return r'\fB' + re.sub(r'\s+', ' ', s) + font
elif node.tagName in ['var', 'dfn', 'i', 'cite']:
s = r'\fI'
for child in node.childNodes:
@@ -78,14 +78,9 @@ the global options by \fB\-\-\fR.
.
.IP "\fB\-\-db=\fIserver\fR"
Sets \fIserver\fR as the database server that \fBovs\-vsctl\fR
-contacts to query or modify configuration. The default is
-\fBunix:@RUNDIR@/db.sock\fR. \fIserver\fR must take one of the
-following forms:
-.RS
-.so ovsdb/remote-active.man
-.so ovsdb/remote-passive.man
-.RE
-.
+contacts to query or modify configuration. \fIserver\fR may be an
+OVSDB active or passive connection method, as described in
+\fBovsdb\fR(7). The default is \fBunix:@RUNDIR@/db.sock\fR.
.IP "\fB\-\-no\-wait\fR"
Prevents \fBovs\-vsctl\fR from waiting for \fBovs\-vswitchd\fR to
reconfigure itself according to the modified database. This
@@ -410,13 +405,9 @@ Prints the configured manager(s).
Deletes the configured manager(s).
.
.IP "\fBset\-manager\fR \fItarget\fR\&..."
-Sets the configured manager target or targets. Each \fItarget\fR may
-use any of the following forms:
-.
-.RS
-.so ovsdb/remote-active.man
-.so ovsdb/remote-passive.man
-.RE
+Sets the configured manager target or targets.
+Each \fItarget\fR may be an OVSDB active or passive connection method,
+e.g. \fBpssl:6640\fR, as described in \fBovsdb\fR(7).
.
.SS "SSL Configuration"
When \fBovs\-vswitchd\fR is configured to connect over SSL for management or
@@ -19,10 +19,9 @@ A daemon that manages and controls any number of Open vSwitch switches
on the local machine.
.PP
The \fIdatabase\fR argument specifies how \fBovs\-vswitchd\fR connects
-to \fBovsdb\-server\fR. The default is \fBunix:@RUNDIR@/db.sock\fR.
-The following forms are accepted:
-.so ovsdb/remote-active.man
-.so ovsdb/remote-passive.man
+to \fBovsdb\-server\fR. \fIdatabase\fR may be an OVSDB active or
+passive connection method, as described in \fBovsdb\fR(7). The
+default is \fBunix:@RUNDIR@/db.sock\fR.
.PP
\fBovs\-vswitchd\fR retrieves its configuration from \fIdatabase\fR at
startup. It sets up Open vSwitch datapaths and then operates
@@ -52,15 +52,10 @@ command line has options, then those options must be separated from
the global options by \fB\-\-\fR.
.
.IP "\fB\-\-db=\fIserver\fR"
-Sets \fIserver\fR as the database server that \fBvtep\-ctl\fR
-contacts to query or modify configuration. The default is
-\fBunix:@RUNDIR@/db.sock\fR. \fIserver\fR must take one of the
-following forms:
-.RS
-.so ovsdb/remote-active.man
-.so ovsdb/remote-passive.man
-.RE
-.
+Sets \fIserver\fR as the database server that \fBvtep\-ctl\fR contacts
+to query or modify configuration. \fIserver\fR may be an OVSDB active
+or passive connection method, as described in \fBovsdb\fR(7). The
+default is \fBunix:@RUNDIR@/db.sock\fR.
.IP "\fB\-\-no\-syslog\fR"
By default, \fBvtep\-ctl\fR logs its arguments and the details of any
changes that it makes to the system log. This option disables this
@@ -336,13 +331,9 @@ Prints the configured manager(s).
Deletes the configured manager(s).
.
.IP "\fBset\-manager\fR \fItarget\fR\&..."
-Sets the configured manager target or targets. Each \fItarget\fR may
-use any of the following forms:
-.
-.RS
-.so ovsdb/remote-active.man
-.so ovsdb/remote-passive.man
-.RE
+Sets the configured manager target or targets.
+Each \fItarget\fR may be an OVSDB active or passive connection method,
+e.g. \fBpssl:6640\fR, as described in \fBovsdb\fR(7).
.
.SS "Database Commands"
.
Signed-off-by: Ben Pfaff <blp@ovn.org> --- v1->v2: Rebase with minor changes. 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 | 103 ++++--- 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, 1258 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