> On Dec 8, 2017, at 7:56 PM, Ben Pfaff <[email protected]> wrote: > > diff --git a/Documentation/ref/ovsdb-server.7.rst > b/Documentation/ref/ovsdb-server.7.rst > new file mode 100644 > index 000000000000..feb093db22ae > --- /dev/null > +++ b/Documentation/ref/ovsdb-server.7.rst > > +============ > +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.
I didn't notice immediately that the following section numbers mapped directly to RFC 7047. It might be worth making it more explicit for people who are slow like me. > +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): > ... > +``ovsdb error`` > + A map or set contains a duplicate key. Is this the only thing "ovsdb error" can mean? It sounds very generic for such a specific issue. > +``insert_delete`` > + A boolean value, true if authorized insertions and authorized are > allowed, > + false if no insertions or deletions are allowed. I assume "deletions" is missing after that second "authorized". > diff --git a/Documentation/ref/ovsdb.5.rst b/Documentation/ref/ovsdb.5.rst > new file mode 100644 > index 000000000000..db037181c5a3 > --- /dev/null > +++ b/Documentation/ref/ovsdb.5.rst > ... > +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>: Is there a reason not to use "<" and ">" directly? > + > +<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. Same here. > diff --git a/Documentation/ref/ovsdb.7.rst b/Documentation/ref/ovsdb.7.rst > new file mode 100644 > index 000000000000..1392ce6f72d7 > --- /dev/null > +++ b/Documentation/ref/ovsdb.7.rst > ... > +The OVSDB protocol specification allows independent, interoperable > +implementations of OVSDB to be developed. Open vSwitch includes a OVSDB > server s/a OVSDB/an OVSDB/ > +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 I assume you mean "delete a column or a table". > +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. This last sentence repeats the information two paragraphs back. I think you can drop one. > +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. Do you mean "down" instead of "done"? > +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. The active-backup description implies in its first sentence that it's limited to a pair of servers. Is that true? Does replication support multiple replicas? If so, it might be worth mentioning that here, since the scale-out benefits will be greater. > +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 s/connection/connections/ > +arrangement is to configure an an OVSDB server with passive connection > methods Duplicate "an"s. > +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. That dot should probably be a ">". > +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. For these two connection methods, it sounds like IPv6 is not supported. Do people need to specify an IPv6 address to bind to for it to work? It might be worth clarifying. > +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. This is the first I think different file formats is mentioned. Are active-backup configurations using a different format? Or is that coming with clustering? > diff --git a/ovsdb/ovsdb-server.1.in b/ovsdb/ovsdb-server.1.in > index f1c6466ccb75..870459e5d9ac 100644 > --- a/ovsdb/ovsdb-server.1.in > +++ b/ovsdb/ovsdb-server.1.in > > @@ -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: I think you can drop "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. Not a big deal, but this seems to describe the same thing multiple times. For example, the first two sections are very similar to the text later that actually describe the arguments. > diff --git a/ovsdb/ovsdb-tool.1.in b/ovsdb/ovsdb-tool.1.in > index 8c799f4cc990..ebfd33b27163 100644 > --- a/ovsdb/ovsdb-tool.1.in > +++ b/ovsdb/ovsdb-tool.1.in > > . > -.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 Is there more than one creation command? The title and use of "these" and they" indicate there are. Maybe it's coming with clustering? If so, it's not worth changing in the interim. Acked-by: Justin Pettit <[email protected]> --Justin _______________________________________________ dev mailing list [email protected] https://mail.openvswitch.org/mailman/listinfo/ovs-dev
