ovsdb-server: Add new RPC "set_db_change_aware".

The _Server database recently added to ovsdb-server can be used to dump out
information about databases, but monitoring updates to _Server is not yet
very useful because for historical reasons ovsdb-server drops all of its
OVSDB connections whenever databases are added or removed or otherwise
change in some major way.  It is not a good idea to change this behavior
for all clients, because some of them rely on it, but this commit
introduces a new RPC that allows clients that understand _Server to
suppress the connection-closing behavior.

Signed-off-by: Ben Pfaff <blp@ovn.org>

1 files changed, 43 insertions, 0 deletions

diff --git a/Documentation/ref/ovsdb-server.7.rst b/Documentation/ref/ovsdb-server.7.rst
index cc625f601..2ed392fee 100644
--- a/Documentation/ref/ovsdb-server.7.rst
+++ b/Documentation/ref/ovsdb-server.7.rst
@@ -146,6 +146,19 @@ notifications (see below) to the request, it must be unique among all active
 monitors.  ``ovsdb-server`` rejects attempt to create two monitors with the
 same identifier.
 
+4.1.7 Monitor Cancellation
+--------------------------
+
+When a database monitored by a session is removed, and database change
+awareness is enabled for the session (see Section 4.1.16), the database server
+spontaneously cancels all monitors (including conditional monitors described in
+Section 4.1.12) for the removed database.  For each canceled monitor, it issues
+a notification in the following form::
+
+    "method": "monitor_canceled"
+    "params": [<json-value>]
+    "id": null
+
 4.1.12 Monitor_cond
 -------------------
 
@@ -371,6 +384,36 @@ The response object contains the following members::
 running OVSDB server process.  A fresh UUID is generated when the process
 restarts.
 
+4.1.16 Database Change Awareness
+--------------------------------
+
+RFC 7047 does not provide a way for a client to find out about some kinds of
+configuration changes, such as about databases added or removed while a client
+is connected to the server, or databases changing between read/write and
+read-only due to a transition between active and backup roles.  Traditionally,
+``ovsdb-server`` disconnects all of its clients when this happens, because this
+prompts a well-written client to reassess what is available from the server
+when it reconnects.
+
+OVS 2.9 provides a way for clients to keep track of these kinds of changes, by
+monitoring the ``Database`` table in the ``_Server`` database introduced in
+this release (see ``ovsdb-server(5)`` for details).  By itself, this does not
+suppress ``ovsdb-server`` disconnection behavior, because a client might
+monitor this database without understanding its special semantics.  Instead,
+``ovsdb-server`` provides a special request::
+
+    "method": "set_db_change_aware"
+    "params": [<boolean>]
+    "id": <nonnull-json-value>
+
+If the boolean in the request is true, it suppresses the connection-closing
+behavior for the current connection, and false restores the default behavior.
+The reply is always the same::
+
+    "result": {}
+    "error": null
+    "id": same "id" as request
+
 5.1 Notation
 ------------