From patchwork Sun Oct 30 13:29:51 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stephen Finucane X-Patchwork-Id: 688930 X-Patchwork-Delegate: rbryant@redhat.com Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from archives.nicira.com (archives.nicira.com [96.126.127.54]) by ozlabs.org (Postfix) with ESMTP id 3t6JLX3jGqz9t1T for ; Mon, 31 Oct 2016 00:31:48 +1100 (AEDT) Authentication-Results: ozlabs.org; dkim=fail reason="key not found in DNS" (0-bit key; unprotected) header.d=that.guru header.i=@that.guru header.b=Af3Wve6i; dkim-atps=neutral Received: from archives.nicira.com (localhost [127.0.0.1]) by archives.nicira.com (Postfix) with ESMTP id BD55010543; Sun, 30 Oct 2016 06:31:47 -0700 (PDT) X-Original-To: dev@openvswitch.org Delivered-To: dev@openvswitch.org Received: from mx1e3.cudamail.com (mx1.cudamail.com [69.90.118.67]) by archives.nicira.com (Postfix) with ESMTPS id D1B4D10542 for ; Sun, 30 Oct 2016 06:31:45 -0700 (PDT) Received: from bar5.cudamail.com (localhost [127.0.0.1]) by mx1e3.cudamail.com (Postfix) with ESMTPS id 659C242037A for ; Sun, 30 Oct 2016 07:31:45 -0600 (MDT) X-ASG-Debug-ID: 1477834304-09eadd0f96242a00001-byXFYA Received: from mx1-pf1.cudamail.com ([192.168.24.1]) by bar5.cudamail.com with ESMTP id rTx78xkfwRG1RTla (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NO) for ; Sun, 30 Oct 2016 07:31:44 -0600 (MDT) X-Barracuda-Envelope-From: stephen@that.guru X-Barracuda-RBL-Trusted-Forwarder: 192.168.24.1 Received: from unknown (HELO bumble.birch.relay.mailchannels.net) (23.83.209.25) by mx1-pf1.cudamail.com with ESMTPS (DHE-RSA-AES256-SHA encrypted); 30 Oct 2016 13:31:44 -0000 Received-SPF: none (mx1-pf1.cudamail.com: domain at that.guru does not designate permitted sender hosts) X-Barracuda-Apparent-Source-IP: 23.83.209.25 X-Barracuda-RBL-IP: 23.83.209.25 X-Sender-Id: mxroute|x-authuser|stephen@that.guru Received: from relay.mailchannels.net (localhost [127.0.0.1]) by relay.mailchannels.net (Postfix) with ESMTP id E61A7E0147 for ; Sun, 30 Oct 2016 13:31:42 +0000 (UTC) Received: from one.mxroute.com (ip-10-120-4-226.us-west-2.compute.internal [10.120.4.226]) by relay.mailchannels.net (Postfix) with ESMTPA id 4A1E5E0ACD for ; Sun, 30 Oct 2016 13:31:42 +0000 (UTC) X-Sender-Id: mxroute|x-authuser|stephen@that.guru Received: from one.mxroute.com ([UNAVAILABLE]. [10.28.138.177]) (using TLSv1.2 with cipher DHE-RSA-AES256-GCM-SHA384) by 0.0.0.0:2500 (trex/5.7.8); Sun, 30 Oct 2016 13:31:42 +0000 X-MC-Relay: Neutral X-MailChannels-SenderId: mxroute|x-authuser|stephen@that.guru X-MailChannels-Auth-Id: mxroute X-MC-Loop-Signature: 1477834302624:1240383443 X-MC-Ingress-Time: 1477834302623 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=that.guru; s=default; h=References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From: Sender:Reply-To:MIME-Version:Content-Type:Content-Transfer-Encoding: Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender: Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=JmmMy/V6Oa4DfTpI47qmf8M40UyR5UApKn6XeN79nQw=; b=Af3Wve6irxdVJ21Dal8SEJnI/X Jzaq6vXDtlaWTw6Ro1HNI1lKNZykNBGNO/gJLj+Vd2gYChJE6zof+9t/b6PcKeENFAvu6R5iwSyYd 4SFSOLWYm26xPiBUnmR7UWlrsM/p+pQ6veQRGwU+xhIaaO7qs9mHyrFNHLryqEzA5qreU2dS3fdvh IW9jfFW6KfATygmTXwkWjW/nPAEvnj8UEWM0+D2qXd2qykb5+mz0dCntAXPcDxT33ttI6MyUubQM0 FaJRP6LeLyT2P4nRByXS6RZpsxM9tzkMA8jM2oZ4pJtXCQ/mNBL0x0o1cS1uTMaefbRKUTFF34df5 O6YpEfOA==; X-CudaMail-Envelope-Sender: stephen@that.guru From: Stephen Finucane To: dev@openvswitch.org X-CudaMail-MID: CM-E1-1029006367 X-CudaMail-DTE: 103016 X-CudaMail-Originating-IP: 23.83.209.25 Date: Sun, 30 Oct 2016 13:29:51 +0000 X-ASG-Orig-Subj: [##CM-E1-1029006367##][PATCH 05/23] doc: Convert OVSDB-replication to rST Message-Id: <1477834209-11414-6-git-send-email-stephen@that.guru> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1477834209-11414-1-git-send-email-stephen@that.guru> References: <1477834209-11414-1-git-send-email-stephen@that.guru> X-OutGoing-Spam-Status: No, score=-6.2 X-AuthUser: stephen@that.guru X-Barracuda-Connect: UNKNOWN[192.168.24.1] X-Barracuda-Start-Time: 1477834304 X-Barracuda-Encrypted: ECDHE-RSA-AES256-GCM-SHA384 X-Barracuda-URL: https://web.cudamail.com:443/cgi-mod/mark.cgi X-Virus-Scanned: by bsmtpd at cudamail.com X-Barracuda-BRTS-Status: 1 X-Barracuda-Spam-Score: 1.10 X-Barracuda-Spam-Status: No, SCORE=1.10 using global scores of TAG_LEVEL=3.5 QUARANTINE_LEVEL=1000.0 KILL_LEVEL=4.0 tests=BSF_SC0_MV0713, BSF_SC5_MJ1963, DKIM_SIGNED, RDNS_NONE X-Barracuda-Spam-Report: Code version 3.2, rules version 3.2.3.34168 Rule breakdown below pts rule name description ---- ---------------------- -------------------------------------------------- 0.00 DKIM_SIGNED Domain Keys Identified Mail: message has a signature 0.10 RDNS_NONE Delivered to trusted network by a host with no rDNS 0.50 BSF_SC0_MV0713 Custom rule MV0713 0.50 BSF_SC5_MJ1963 Custom Rule MJ1963 Subject: [ovs-dev] [PATCH 05/23] doc: Convert OVSDB-replication to rST X-BeenThere: dev@openvswitch.org X-Mailman-Version: 2.1.16 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: dev-bounces@openvswitch.org Sender: "dev" Signed-off-by: Stephen Finucane --- Documentation/OVSDB-replication.md | 152 ------------------------------- Documentation/OVSDB-replication.rst | 172 ++++++++++++++++++++++++++++++++++++ Documentation/automake.mk | 2 +- 3 files changed, 173 insertions(+), 153 deletions(-) delete mode 100644 Documentation/OVSDB-replication.md create mode 100644 Documentation/OVSDB-replication.rst diff --git a/Documentation/OVSDB-replication.md b/Documentation/OVSDB-replication.md deleted file mode 100644 index a9ab5cc..0000000 --- a/Documentation/OVSDB-replication.md +++ /dev/null @@ -1,152 +0,0 @@ -OVSDB replication implementation --------------------------------- - -Overview -======== - -Given two Open vSwitch databases with the same schema, OVSDB -replication keeps these databases in the same state, i.e. each of the -databases have the same contents at any given time even if they are -not running in the same host. This document elaborates on the -implementation details to provide this functionality. - -Terminology -=========== - -- Source of truth database: database whose content will be replicated - to another database. - -- Active server: ovsdb-server providing RPC interface to the source of - truth database. - -- Standby server: ovsdb-server providing RPC interface to the database - that is not the source of truth. - -Design -====== - -The overall design of replication consists of one ovsdb-server (active server) -communicating the state of its databases to another ovsdb-server -(standby server) so that the latter keep its own databases in that same state. -To achieve this, the standby server acts as a client of the active -server, in the sense that it sends a monitor request to keep up to date with -the changes in the active server databases. When a notification from the -active server arrives, the standby server executes the necessary set of -operations so its databases reach the same state as the the active server -databases. Below is the design represented as a diagram. - - +--------------+ replication +--------------+ - | Active |<-------------------| Standby | - | OVSDB-server | | OVSDB-server | - +--------------+ +--------------+ - | | - | | - +-------+ +-------+ - | SoT | | | - | OVSDB | | OVSDB | - +-------+ +-------+ - -Setting up the replication -========================== - -To initiate the replication process, the standby server must be executed -indicating the location of the active server via the command line option -"--sync-from=server", where server can take any form described in the -ovsdb-client manpage and it must specify an active connection type (tcp, unix, -ssl). This option will cause the standby server to attempt to send a monitor -request to the active server in every main loop iteration, until the active -server responds. - -When sending a monitor request the standby server is doing the following: - -1. Erase the content of the databases for which it is providing a RPC -interface. - -2. Open the jsonrpc channel to communicate with the active server. - -3. Fetch all the databases located in the active server. - -4. For each database with the same schema in both the active and - standby servers: construct and send a monitor request message - specifying the tables that will be monitored (i.e all the tables on - the database except the ones blacklisted*). - -5. Set the standby database to the current state of the active - database. - -Once the monitor request message is sent, the standby server will continuously -receive notifications of changes occurring to the tables specified in the -request. The process of handling this notifications is detailed in the next -section. - -*A set of tables that will be excluded from replication can be -configure as a blacklist of tables via the command line option -"--sync-exclude-tables=db:table[,db:table]...", where db corresponds -to the database where the table resides. - -Replication process -=================== - -The replication process consists on handling the update notifications received -in the standby server caused by the monitor request that was previously sent to -the active server. In every loop iteration, the standby server attempts to -receive a message from the active server which can be an error, an echo -message (used to keep the connection alive) or an update notification. In case -the message is a fatal error, the standby server will disconnect from the -active without dropping the replicated data. If it is an echo message, the -standby server will reply with an echo message as well. If the message is an -update notification, the following process occurs: - -1. Create a new transaction. - -2. Get the \ object from the "params" member of the - notification. - -3. For each \ in the \ object do: - - 1. For each \ in \ check what kind of - operation should be executed according to the following criteria about - the presence of the object members: - - - If "old" member is not present, execute an insert operation - using \ from the "new" member. - - - If "old" member is present and "new" member is not present, - execute a delete operation using \ from the "old" - member - - - If both "old" and "new" members are present, execute an - update operation using \ from the "new" member. - -4. Commit the transaction. - -If an error occurs during the replication process, all replication is -restarted by resending a new monitor request as described in the section -"Setting up the replication". - - -Runtime management commands -=========================== - -Runtime management commands can be sent to a running standby server via -ovs-appctl in order to configure the replication functionality. The available -commands are the following. - -- ovsdb-server/set-remote-ovsdb-server {server}: sets the name of the active - server. - -- ovsdb-server/get-remote-ovsdb-server: gets the name of the active server - -- ovsdb-server/connect-remote-ovsdb-server: causes the server to attempt to - send a monitor request every main loop iteration. - -- ovsdb-server/disconnect-remote-ovsdb-server: closes the jsonrpc channel - between the active server and frees the memory used for the replication - configuration. - -- ovsdb-server/set-sync-exclude-tables {db:table,...}: sets the tables list - that will be excluded from being replicated. - -- ovsdb-server/get-sync-excluded-tables: gets the tables list that is - currently excluded from replication. - diff --git a/Documentation/OVSDB-replication.rst b/Documentation/OVSDB-replication.rst new file mode 100644 index 0000000..d8f94f4 --- /dev/null +++ b/Documentation/OVSDB-replication.rst @@ -0,0 +1,172 @@ +.. + 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 Replication Implementation +================================ + +Given two Open vSwitch databases with the same schema, OVSDB replication keeps +these databases in the same state, i.e. each of the databases have the same +contents at any given time even if they are not running in the same host. This +document elaborates on the implementation details to provide this +functionality. + +Terminology +----------- + +Source of truth database + database whose content will be replicated to another database. + +Active server + ovsdb-server providing RPC interface to the source of truth database. + +Standby server + ovsdb-server providing RPC interface to the database that is not the source + of truth. + +Design +------ + +The overall design of replication consists of one ovsdb-server (active server) +communicating the state of its databases to another ovsdb-server (standby +server) so that the latter keep its own databases in that same state. To +achieve this, the standby server acts as a client of the active server, in the +sense that it sends a monitor request to keep up to date with the changes in +the active server databases. When a notification from the active server +arrives, the standby server executes the necessary set of operations so its +databases reach the same state as the the active server databases. Below is the +design represented as a diagram.:: + + +--------------+ replication +--------------+ + | Active |<-------------------| Standby | + | OVSDB-server | | OVSDB-server | + +--------------+ +--------------+ + | | + | | + +-------+ +-------+ + | SoT | | | + | OVSDB | | OVSDB | + +-------+ +-------+ + +Setting Up The Replication +-------------------------- + +To initiate the replication process, the standby server must be executed +indicating the location of the active server via the command line option +``--sync-from=server``, where server can take any form described in the +ovsdb-client manpage and it must specify an active connection type (tcp, unix, +ssl). This option will cause the standby server to attempt to send a monitor +request to the active server in every main loop iteration, until the active +server responds. + +When sending a monitor request the standby server is doing the following: + +1. Erase the content of the databases for which it is providing a RPC + interface. + +2. Open the jsonrpc channel to communicate with the active server. + +3. Fetch all the databases located in the active server. + +4. For each database with the same schema in both the active and standby + servers: construct and send a monitor request message specifying the tables + that will be monitored (i.e all the tables on the database except the ones + blacklisted [*]). + +5. Set the standby database to the current state of the active database. + +Once the monitor request message is sent, the standby server will continuously +receive notifications of changes occurring to the tables specified in the +request. The process of handling this notifications is detailed in the next +section. + +[*] A set of tables that will be excluded from replication can be configure as +a blacklist of tables via the command line option +``--sync-exclude-tables=db:table[,db:table]...``, where db corresponds to the +database where the table resides. + +Replication Process +------------------- + +The replication process consists on handling the update notifications received +in the standby server caused by the monitor request that was previously sent to +the active server. In every loop iteration, the standby server attempts to +receive a message from the active server which can be an error, an echo message +(used to keep the connection alive) or an update notification. In case the +message is a fatal error, the standby server will disconnect from the active +without dropping the replicated data. If it is an echo message, the standby +server will reply with an echo message as well. If the message is an update +notification, the following process occurs: + +1. Create a new transaction. + +2. Get the ```` object from the ``params`` member of the + notification. + +3. For each ```` in the ```` object do: + + 1. For each ```` in ```` check what kind of + operation should be executed according to the following criteria + about the presence of the object members: + + - If ``old`` member is not present, execute an insert operation using + ```` from the ``new`` member. + + - If ``old`` member is present and ``new`` member is not present, + execute a delete operation using ```` from the ``old`` member + + - If both ``old`` and ``new`` members are present, execute an update + operation using ```` from the ``new`` member. + +4. Commit the transaction. + + If an error occurs during the replication process, all replication is + restarted by resending a new monitor request as described in the section + "Setting up the replication". + +Runtime Management Commands +--------------------------- + +Runtime management commands can be sent to a running standby server via +ovs-appctl in order to configure the replication functionality. The available +commands are the following. + +``ovsdb-server/set-remote-ovsdb-server {server}`` + sets the name of the active server + +``ovsdb-server/get-remote-ovsdb-server`` + gets the name of the active server + +``ovsdb-server/connect-remote-ovsdb-server`` + causes the server to attempt to send a monitor request every main loop + iteration + +``ovsdb-server/disconnect-remote-ovsdb-server`` + closes the jsonrpc channel between the active server and frees the memory + used for the replication configuration. + +``ovsdb-server/set-sync-exclude-tables {db:table,...}`` + sets the tables list that will be excluded from being replicated + +``ovsdb-server/get-sync-excluded-tables`` + gets the tables list that is currently excluded from replication diff --git a/Documentation/automake.mk b/Documentation/automake.mk index d6849e8..77c39f1 100644 --- a/Documentation/automake.mk +++ b/Documentation/automake.mk @@ -2,5 +2,5 @@ docs += \ Documentation/committer-responsibilities.rst \ Documentation/committer-grant-revocation.rst \ Documentation/group-selection-method-property.txt \ - Documentation/OVSDB-replication.md \ + Documentation/OVSDB-replication.rst \ Documentation/release-process.rst