From bdb82d3aba7af2cab929bdc6001528904dde64b0 Mon Sep 17 00:00:00 2001
From: Ian Barwick <barwick@gmail.com>
Date: Fri, 17 Nov 2017 08:51:21 +0900
Subject: [PATCH] docs: add initial witness server documentation

---
 doc/filelist.sgml               |  1 +
 doc/overview.sgml               | 25 +++++++++++++++++++++++++
 doc/repmgr.sgml                 |  1 +
 doc/repmgrd-witness-server.sgml | 31 +++++++++++++++++++++++++++++++
 4 files changed, 58 insertions(+)
 create mode 100644 doc/repmgrd-witness-server.sgml

diff --git a/doc/filelist.sgml b/doc/filelist.sgml
index 0e7fe69a..9ec8c197 100644
--- a/doc/filelist.sgml
+++ b/doc/filelist.sgml
@@ -53,6 +53,7 @@
 <!ENTITY repmgrd-degraded-monitoring SYSTEM "repmgrd-degraded-monitoring.sgml">
 <!ENTITY repmgrd-cascading-replication SYSTEM "repmgrd-cascading-replication.sgml">
 <!ENTITY repmgrd-network-split SYSTEM "repmgrd-network-split.sgml">
+<!ENTITY repmgrd-witness-server SYSTEM "repmgrd-witness-server.sgml">
 <!ENTITY repmgrd-bdr SYSTEM "repmgrd-bdr.sgml">
 
 <!ENTITY repmgr-primary-register SYSTEM "repmgr-primary-register.sgml">
diff --git a/doc/overview.sgml b/doc/overview.sgml
index a216501b..248deb6e 100644
--- a/doc/overview.sgml
+++ b/doc/overview.sgml
@@ -145,6 +145,31 @@
       </para>
      </listitem>
     </varlistentry>
+    <varlistentry>
+     <term>witness server</term>
+     <listitem>
+      <para>
+        &repmgr; provides functionality to set up a so-called "witness server" to
+        assist in determining a new master server in a failover situation with more
+        than one standby. The witness server itself is not part of the replication
+        cluster, although it does contain a copy of the repmgr metadata schema
+        (see below).
+      </para>
+      <para>
+        The purpose of a witness server is to provide a "casting vote" where servers
+        in the replication cluster are split over more than one location. In the event
+        of a loss of connectivity between locations, the presence or absence of
+        the witness server will decide whether a server at that location is promoted
+        to master; this is to prevent a "split-brain" situation where an isolated
+        location interprets a network outage as a failure of the (remote) master and
+        promotes a (local) standby.
+      </para>
+      <para>
+        A witness server only needs to be created if <application>repmgrd</application>
+        is in use.
+      </para>
+     </listitem>
+    </varlistentry>
    </variablelist>
   </para>
  </sect1>
diff --git a/doc/repmgr.sgml b/doc/repmgr.sgml
index 18a269eb..f4c2401e 100644
--- a/doc/repmgr.sgml
+++ b/doc/repmgr.sgml
@@ -84,6 +84,7 @@
   &repmgrd-demonstration;
   &repmgrd-cascading-replication;
   &repmgrd-network-split;
+  &repmgrd-witness-server;
   &repmgrd-degraded-monitoring;
   &repmgrd-monitoring;
   &repmgrd-bdr;
diff --git a/doc/repmgrd-witness-server.sgml b/doc/repmgrd-witness-server.sgml
new file mode 100644
index 00000000..2ae39539
--- /dev/null
+++ b/doc/repmgrd-witness-server.sgml
@@ -0,0 +1,31 @@
+<chapter id="repmgrd-witness-server">
+ <indexterm>
+   <primary>repmgrd</primary>
+   <secondary>witness server</secondary>
+ </indexterm>
+
+ <title>Using a witness server with repmgrd</title>
+ <para>
+   In a situation caused e.g. by a network interruption between two
+   data centres, it's important to avoid a "split-brain" situation where
+   both sides of the network assume they are the active segment and the
+   side without an active master unilaterally promotes one of its standbys.
+ </para>
+ <para>
+   To prevent this situation happening, it's essential to ensure that one
+   network segment has a "voting majority", so other segments will know
+   they're in the minority and not attempt to promote a new master. Where
+   an odd number of servers exists, this is not an issue. However, if each
+   network has an even number of nodes, it's necessary to provide some way
+   of ensuring a majority, which is where the witness server becomes useful.
+ </para>
+ <para>
+   This is not a fully-fledged standby node and is not integrated into
+   replication, but it effectively represents the "casting vote" when
+   deciding which network segment has a majority. A witness server can
+   be set up using `repmgr witness create` (see below for details) and
+   can run on a dedicated server or an existing node. Note that it only
+   makes sense to create a witness server in conjunction with running
+   `repmgrd`; the witness server will require its own `repmgrd` instance.
+ </para>
+</chapter>