.so lib/daemon-syn.man
.so lib/service-syn.man
.so lib/vlog-syn.man
+.so ovsdb/replication-syn.man
.so lib/ssl-syn.man
.so lib/ssl-bootstrap-syn.man
+.so lib/ssl-peer-ca-cert-syn.man
.so lib/unixctl-syn.man
.so lib/common-syn.man
.
.so lib/service.man
.SS "Logging Options"
.so lib/vlog.man
+.SS "Syncing Options"
+.so ovsdb/replication.man
.SS "Public Key Infrastructure Options"
The options described below for configuring the SSL public key
infrastructure accept a special syntax for obtaining their
one row in \fItable\fR.)
.so lib/ssl.man
.so lib/ssl-bootstrap.man
+.so lib/ssl-peer-ca-cert.man
.SS "Other Options"
.so lib/unixctl.man
.so lib/common.man
Causes \fBovsdb\-server\fR to gracefully terminate.
.IP "\fBovsdb\-server/compact\fR [\fIdb\fR]\&..."
Compacts each database \fIdb\fR in-place. If no \fIdb\fR is
-specified, compacts every database in-place. Databases are also
-automatically compacted occasionally.
+specified, compacts every database in-place. A database is also
+compacted automatically when a transaction is logged if it is over 4
+times as large as its previous compacted size (and at least 10 MB),
+but not before 100 commits have been added or 10 minutes have elapsed
+since the last compaction.
.
.IP "\fBovsdb\-server/reconnect\fR"
Makes \fBovsdb\-server\fR drop all of the JSON\-RPC
Outputs a list of the currently configured databases added either through
the command line or through the \fBovsdb\-server/add\-db\fR command.
.
+.IP "\fBovsdb\-server/set\-remote\-ovsdb\-server \fIserver"
+Sets the remote \fIserver\fR from which \fBovsdb\-server\fR connects through
+\fBovsdb\-server/connect\-remote\-ovsdb\-server\fR.
+.
+.IP "\fBovsdb\-server/get\-remote\-ovsdb\-server"
+Gets the remote server from which \fBovsdb\-server\fR is currently synchronizing
+its databases.
+.
+.IP "\fBovsdb\-server/connect\-remote\-ovsdb\-server"
+Causes \fBovsdb\-server\fR to synchronize its databases with the server
+specified by \fBovsdb\-server/set\-remote\-ovsdb\-server\fR.
+.
+.IP "\fBovsdb\-server/disconnect\-remote\-ovsdb\-server"
+Causes \fBovsdb\-server\fR to stop synchronizing its databases with a remote server.
+.
+.IP "\fBovsdb\-server/set\-sync\-excluded\-tables \fIdb\fB:\fItable\fR[\fB,\fIdb\fB:\fItable\fR]..."
+Sets the \fItable\fR whitin \fIdb\fR that will be excluded from synchronization.
+.
+.IP "\fBovsdb\-server/get\-sync\-excluded\-tables"
+Gets the tables that are currently excluded from synchronization.
+.
.so lib/vlog-unixctl.man
.so lib/memory-unixctl.man
.so lib/coverage-unixctl.man
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 "4. Wire Protocol"
The original OVSDB specifications included the following reason,
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>.
+.
+.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 "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
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.
+.
+.SH "BUGS"
+.
+In Open vSwitch before version 2.4, when \fBovsdb\-server\fR sent
+JSON-RPC error responses to some requests, it incorrectly formulated
+them with the \fBresult\fR and \fBerror\fR swapped, so that the
+response appeared to indicate success (with a nonsensical result)
+rather than an error. The requests that suffered from this problem
+were:
+.
+.IP \fBtransact\fR
+.IQ \fBget_schema\fR
+Only if the request names a nonexistent database.
+.IP \fBmonitor\fR
+.IQ \fBlock\fR
+.IQ \fBunlock\fR
+In all error cases.
+.
+.PP
+Of these cases, the only error that a well-written application is
+likely to encounter in practice is \fBmonitor\fR of tables or columns
+that do not exist, in an situation where the application has been
+upgraded but the old database schema is still temporarily in use. To
+handle this situation gracefully, we recommend that clients should
+treat a \fBmonitor\fR response with a \fBresult\fR that contains an
+\fBerror\fR key-value pair as an error (assuming that the database
+being monitored does not contain a table named \fBerror\fR).
+.
.SH "SEE ALSO"
.
.BR ovsdb\-tool (1).
projects / cascardo / ovs.git / blobdiff