docs: expand witness documentation

doc/configuration.sgml

@@ -12,13 +12,13 @@
 
     <title>repmgr user permissions</title>
     <para>
-      &repmgr; will create an extension in the BDR database containing objects
+      &repmgr; will create an extension database containing objects
       for administering &repmgr; metadata. The user defined in the <varname>conninfo</varname>
       setting must be able to access all objects. Additionally, superuser permissions
       are required to install the &repmgr; extension. The easiest way to do this
       is create the &repmgr; user as a superuser, however if this is not
       desirable, the &repmgr; user can be created as a normal user and a
-      superuser specified with <literal>--superuser</literal> when registering a BDR node.
+      superuser specified with <literal>--superuser</literal> when registering a &repmgr; node.
     </para>
   </sect1>
 </chapter>

doc/configuring-witness-server.sgml

@@ -0,0 +1,86 @@
+<chapter id="using-witness-server">
+ <indexterm>
+  <primary>witness server</primary>
+  <seealso>Using a witness server with repmgrd</seealso>
+ </indexterm>
+
+
+ <title>Using a witness server</title>
+ <para>
+   A <xref linkend="witness-server"> is a normal PostgreSQL instance which
+   is not part of the streaming replication cluster; its purpose is, if a
+   failover situation occurs, to provide proof that the primary server
+   itself is unavailable.
+ </para>
+
+ <para>
+   A typical use case for a witness server is a two-node streaming replication
+   setup, where the primary and standby are in different locations (data centres).
+   By creating a witness server in the same location as the primary, if the primary
+   becomes unavailable  it's possible for the standby to decide whether it can
+   promote itself without risking a "split brain" scenario: if it can't see either the
+   witness or the primary server, it's likely there's a network-level interruption
+   and it should not promote itself. If it can seen the witness but not the primary,
+   this proves there is no network interruption and the primary itself is unavailable,
+   and it can therefore promote itself (and ideally take action to fence the
+   former primary).
+ </para>
+ <para>
+   For more complex replication scenarios,e.g. with multiple datacentres, it may
+   be preferable to use location-based failover, which ensures that only nodes
+   in the same location as the primary will ever be promotion candidates;
+   see <xref linkend="repmgrd-network-split"> for more details.
+ </para>
+
+ <note>
+   <simpara>
+     A witness server will only be useful if <application>repmgrd</application>
+     is in use.
+   </simpara>
+ </note>
+
+ <sect1 id="creating-witness-server">
+   <title>Creating a witness server</title>
+ <para>
+   To create a witness server, set up a normal PostgreSQL instance on a server
+   in the same physical location as the cluster's primary server.
+ </para>
+ <para>
+   This instance should *not* be on the same physical host as the primary server,
+   as otherwise if the primary server fails due to hardware issues, the witness
+   server will be lost too.
+ </para>
+ <note>
+   <simpara>
+     &repmgr; 3.3 and earlier provided a <command>repmgr create witness</command>
+     command, which would automatically create a PostgreSQL instance. However
+     this often resulted in an unsatisfactory, hard-to-customise instance.
+   </simpara>
+ </note>
+ <para>
+   The witness server should be configured in the same way as a normal
+   &repmgr; node; see section <xref linkend="configuration">.
+ </para>
+ <para>
+   Register the witness server with <xref linkend="repmgr-witness-register">.
+   This will create the &repmgr; extension on the witness server, and make
+   a copy of the &repmgr; metadata.
+ </para>
+ <note>
+   <simpara>
+    As the witness server is not part of the replication cluster, further
+    changes to the &repmgr; metadata will be synchronised by
+    <application>repmgrd</application>.
+   </simpara>
+ </note>
+ <para>
+   Once the witness server has been configured, <application>repmgrd</application>
+   should be started; for more details see <xref linkend="repmgrd-witness-server">.
+ </para>
+
+ <para>
+  To unregister a witness server, use <xref linkend="repmgr-witness-unregister">.
+ </para>
+
+ </sect1>
+</chapter>

doc/filelist.sgml

@@ -43,6 +43,8 @@
 <!ENTITY promoting-standby  SYSTEM "promoting-standby.sgml">
 <!ENTITY follow-new-primary  SYSTEM "follow-new-primary.sgml">
 <!ENTITY switchover  SYSTEM "switchover.sgml">
+<!ENTITY configuring-witness-server SYSTEM "configuring-witness-server.sgml">
+
 <!ENTITY event-notifications  SYSTEM "event-notifications.sgml">
 <!ENTITY upgrading-repmgr  SYSTEM "upgrading-repmgr.sgml">
 

doc/follow-new-primary.sgml

@@ -1,4 +1,4 @@
-<chapter id="follow-new-primary" xreflabel="Following a new primary">
+<chapter id="follow-new-primary">
  <indexterm>
   <primary>Following a new primary</primary>
   <seealso>repmgr standby follow</seealso>

doc/overview.sgml

@@ -87,6 +87,30 @@
       </simpara>
      </listitem>
     </varlistentry>
+   <varlistentry id="witness-server">
+     <term>witness server</term>
+     <listitem>
+      <para>
+        &repmgr; provides functionality to set up a so-called "witness server" to
+        assist in determining a new primary 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.
+      </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 primary; this is to prevent a "split-brain" situation where an isolated
+        location interprets a network outage as a failure of the (remote) primary 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>
@@ -145,31 +169,6 @@
       </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 primary 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 primary; this is to prevent a "split-brain" situation where an isolated
-        location interprets a network outage as a failure of the (remote) primary 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>

doc/repmgr-witness-register.sgml

@@ -1,6 +1,7 @@
-<refentry id="repmgr-witness-register" xreflabel="repmgr witness register">
+<refentry id="repmgr-witness-register">
   <indexterm>
     <primary>repmgr witness register</primary>
+    <seealso>witness server</seealso>
   </indexterm>
 
   <refmeta>

doc/repmgr.sgml

@@ -73,6 +73,7 @@
   &promoting-standby;
   &follow-new-primary;
   &switchover;
+  &configuring-witness-server;
   &event-notifications;
   &upgrading-repmgr;
  </part>

doc/repmgrd-network-split.sgml

@@ -1,4 +1,4 @@
-<chapter id="repmgrd-network-split">
+<chapter id="repmgrd-network-split" xreflabel="Handling network splits with repmgrd">
  <indexterm>
    <primary>repmgrd</primary>
    <secondary>network splits</secondary>

doc/repmgrd-witness-server.sgml

@@ -1,4 +1,4 @@
-<chapter id="repmgrd-witness-server">
+<chapter id="repmgrd-witness-server" xreflabel="Using a witness server with repmgrd">
  <indexterm>
    <primary>repmgrd</primary>
    <secondary>witness server</secondary>
@@ -23,9 +23,9 @@
    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
+   be set up using <xref linkend="repmgr-witness-register">. Note that it only
-   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.
+   <application>repmgrd</application>; the witness server will require its own
+   <application>repmgrd</application> instance.
  </para>
 </chapter>