From a4e79d33afcaf1158dd85d601912a4fa7bc06abf Mon Sep 17 00:00:00 2001
From: Ian Barwick <ian@2ndquadrant.com>
Date: Thu, 5 Oct 2017 13:40:13 +0900
Subject: [PATCH] Initial repmgrd documentation

---
 doc/filelist.sgml                   |  4 +++
 doc/repmgr.sgml                     |  6 ++++
 doc/repmgrd-automatic-failover.sgml | 12 +++++++
 doc/repmgrd-configuration.sgml      | 51 +++++++++++++++++++++++++++++
 4 files changed, 73 insertions(+)
 create mode 100644 doc/repmgrd-automatic-failover.sgml
 create mode 100644 doc/repmgrd-configuration.sgml

diff --git a/doc/filelist.sgml b/doc/filelist.sgml
index c1bed9cb..6587bc05 100644
--- a/doc/filelist.sgml
+++ b/doc/filelist.sgml
@@ -43,6 +43,10 @@
 <!ENTITY promoting-standby  SYSTEM "promoting-standby.sgml">
 <!ENTITY follow-new-primary  SYSTEM "follow-new-primary.sgml">
 <!ENTITY switchover  SYSTEM "switchover.sgml">
+
+<!ENTITY repmgrd-automatic-failover SYSTEM "repmgrd-automatic-failover.sgml">
+<!ENTITY repmgrd-configuration SYSTEM "repmgrd-configuration.sgml">
+
 <!ENTITY repmgr-primary-register SYSTEM "repmgr-primary-register.sgml">
 <!ENTITY repmgr-primary-unregister SYSTEM "repmgr-primary-unregister.sgml">
 <!ENTITY repmgr-standby-clone SYSTEM "repmgr-standby-clone.sgml">
diff --git a/doc/repmgr.sgml b/doc/repmgr.sgml
index 1d498ae4..5a79167a 100644
--- a/doc/repmgr.sgml
+++ b/doc/repmgr.sgml
@@ -75,6 +75,12 @@
   &switchover;
  </part>
 
+ <part id="using-repmgrd">
+  <title>Using repmgrd</title>
+  &repmgrd-automatic-failover;
+  &repmgrd-configuration;
+ </part>
+
  <part id="repmgr-command-reference">
   <title>repmgr command reference</title>
 
diff --git a/doc/repmgrd-automatic-failover.sgml b/doc/repmgrd-automatic-failover.sgml
new file mode 100644
index 00000000..8c28deca
--- /dev/null
+++ b/doc/repmgrd-automatic-failover.sgml
@@ -0,0 +1,12 @@
+<chapter id="repmgrd-automatic-failover" xreflabel="Automatic failover with repmgrd">
+ <title>Automatic failover with repmgrd</title>
+
+ <para>
+  <command>repmgrd</command> is a management and monitoring daemon which runs
+  on each node in a replication cluster. It can automate actions such as
+  failover and updating standbys to follow the new primary, as well as
+  providing monitoring information about the state of each standby.
+ </para>
+
+
+</chapter>
diff --git a/doc/repmgrd-configuration.sgml b/doc/repmgrd-configuration.sgml
new file mode 100644
index 00000000..621161d4
--- /dev/null
+++ b/doc/repmgrd-configuration.sgml
@@ -0,0 +1,51 @@
+<chapter id="repmgrd-configuration">
+ <title>repmgrd configuration</title>
+ <para>
+  To use <command>repmgrd</command>, its associated function library must be
+  included in <filename>postgresql.conf</filename> with:
+
+  <programlisting>
+    shared_preload_libraries = 'repmgr'</programlisting>
+ </para>
+ <para>
+  Changing this setting requires a restart of PostgreSQL; for more details see
+  the <ulink url="https://www.postgresql.org/docs/current/static/runtime-config-client.html#GUC-SHARED-PRELOAD-LIBRARIES">PostgreSQL documentation</ulink>.
+ </para>
+ <para>
+  Additionally the following <command>repmgrd</command> options *must* be set in
+  <filename>repmgr.conf</filename> (adjust configuration file locations as appropriate):
+  <programlisting>
+    failover=automatic
+    promote_command='repmgr standby promote -f /etc/repmgr.conf --log-to-file'
+    follow_command='repmgr standby follow -f /etc/repmgr.conf --log-to-file --upstream-node-id=%n'</programlisting>
+ </para>
+ <para>
+  Note that the <literal>--log-to-file</literal> option will cause
+  output generated by the &repmgr; command, when executed by <command>repmgrd</command>,
+  to be logged to the same destination configured to receive log output for <command>repmgrd</command>.
+  See <filename>repmgr.conf.sample</filename> for further <command>repmgrd</command>-specific settings.
+ </para>
+ <para>
+  When <varname>failover</varname> is set to <literal>automatic</literal>, upon detecting failure
+  of the current  primary, <command>repmgrd</command> will execute one of
+  <varname>promote_command</varname> or <varname>follow_command</varname>,
+  depending on whether the current server is to become the new primary, or
+  needs to follow another server which has become the new primary. Note that
+  these commands can be any valid shell script which results in one of these
+  two actions happening, but if &repmgr;'s <command>standby follow</command> or
+  <command>standby promote</command>
+  commands are not executed (either directly as shown here, or from a script which
+  performs other actions), the &repmgr; metadata will not be updated and
+  &repmgr; will no longer function reliably.
+ </para>
+ <para>
+  The <varname>follow_command</varname> should provide the <literal>--upstream-node-id=%n</literal>
+  option to <command>repmgr standby follow</command>; the <literal>%n</literal> will be replaced by
+  <command>repmgrd</command> with the ID of the new primary node. If this is not provided, &repmgr;
+  will attempt to determine the new primary by itself, but  if the
+  original primary comes back online after the new primary is promoted, there is a risk that
+  <command>repmgr standby follow</command> will result in the node continuing to follow
+  the original primary.
+ </para>
+
+</chapter>