From 4589b8d439986e92e87198b85c6f6c3e703ea80f Mon Sep 17 00:00:00 2001
From: Ian Barwick <ian@2ndquadrant.com>
Date: Mon, 16 Jul 2018 14:55:07 +0900
Subject: [PATCH] doc: update documentation of "promote_command" and
 "service_promote_command"

See commit 63242e2277ac4afc39e52ffc7030abad09df2929
---
 doc/configuration-service-commands.sgml | 16 ++++++++++++----
 doc/repmgrd-configuration.sgml          | 25 ++++++++++++++++++-------
 repmgr.conf.sample                      | 14 +++++++-------
 3 files changed, 37 insertions(+), 18 deletions(-)

diff --git a/doc/configuration-service-commands.sgml b/doc/configuration-service-commands.sgml
index e783d821..d99c3945 100644
--- a/doc/configuration-service-commands.sgml
+++ b/doc/configuration-service-commands.sgml
@@ -47,16 +47,24 @@
     service_restart_command
     service_reload_command</programlisting>
   </para>
-
   <note>
     <para>
-      It's also possible to specify a <varname>service_promote_command</varname>;
-      this overrides any value contained in the setting <varname>promote_command</varname>.
+      It's also possible to specify a <varname>service_promote_command</varname>.
       This is intended for systems which provide a package-level promote command,
-      such as Debian's <application>pg_ctlcluster</application>.
+      such as Debian's <application>pg_ctlcluster</application>, to promote the
+      PostgreSQL from standby to primary.
+    </para>
+    <para>
+      If your packaging system does not provide such a command, it can be left empty,
+      and &repmgr; will generate the appropriate <command>pg_ctl ... promote</command> command.
+    </para>
+    <para>
+      Do not confuse this with <varname>promote_command</varname>, which is used
+      by <application>repmgrd</application> to execute <xref linkend="repmgr-standby-promote">.
     </para>
   </note>
 
+
   <para>
     To confirm which command &repmgr; will execute for each action, use
     <command>repmgr node service --list --action=...</command>, e.g.:
diff --git a/doc/repmgrd-configuration.sgml b/doc/repmgrd-configuration.sgml
index 7f046d47..2d390519 100644
--- a/doc/repmgrd-configuration.sgml
+++ b/doc/repmgrd-configuration.sgml
@@ -34,6 +34,24 @@
       the <ulink url="https://www.postgresql.org/docs/current/static/runtime-config-client.html#GUC-SHARED-PRELOAD-LIBRARIES">PostgreSQL documentation</ulink>.
     </para>
 
+    <para>
+      To apply configuration file changes to a running <application>repmgrd</application>
+      daemon, execute the operating system's r<application>repmgrd</application> service reload command
+      (see <xref linkend="appendix-packages"> for examples),
+      or for instances  which were manually started, execute <command>kill -HUP</command>, e.g.
+      <command>kill -HUP `cat /tmp/repmgrd.pid`</command>.
+    </para>
+    <note>
+      <para>
+        Check the <application>repmgrd</application> log to see what changes were
+        applied, or if any issues were encountered when reloading the configuration.
+      </para>
+    </note>
+    <para>
+      Note that only a subset of configuration file parameters can be changed on a
+      running <application>repmgrd</application> daemon.
+    </para>
+
     <sect2 id="repmgrd-automatic-failover-configuration">
       <title>automatic failover configuration</title>
       <para>
@@ -162,13 +180,6 @@
         repmgrd -f /etc/repmgr.conf --pid-file /tmp/repmgrd.pid --daemonize</programlisting>
       and stopped with <command>kill `cat /tmp/repmgrd.pid`</command>. Adjust paths as appropriate.
     </para>
-    <para>
-      To apply configuration file changes to a running <application>repmgrd</application>
-      daemon, execute the operating system's service reload command (for manually started
-      instances, execute <command>kill -HUP `cat /tmp/repmgrd.pid`</command>).
-      Note that only a subset of configuration file parameters can be changed on a
-      running <application>repmgrd</application> daemon.
-    </para>
 
     <sect2 id="repmgrd-configuration-debian-ubuntu">
       <indexterm>
diff --git a/repmgr.conf.sample b/repmgr.conf.sample
index 35deee44..713eab1f 100644
--- a/repmgr.conf.sample
+++ b/repmgr.conf.sample
@@ -253,11 +253,11 @@ ssh_options='-q -o ConnectTimeout=10'	# Options to append to "ssh"
 					# primary (or other upstream node)
 #reconnect_interval=10			# Interval between attempts  to reconnect to an unreachable
 					# primary (or other upstream node)
-#promote_command=			# command to execute when promoting a new primary; use something like:
+#promote_command=			# command repmgrd executes when promoting a new primary; use something like:
 					#
 					#     repmgr standby promote -f /etc/repmgr.conf
 					#
-#follow_command=			# command to execute when instructing a standby to follow a new primary;
+#follow_command=			# command repmgrd executes when instructing a standby to follow a new primary;
 					# use something like:
 					#
 					#     repmgr standby follow -f /etc/repmgr.conf -W --upstream-node-id=%n
@@ -310,11 +310,11 @@ ssh_options='-q -o ConnectTimeout=10'	# Options to append to "ssh"
 #service_stop_command = ''
 #service_restart_command = ''
 #service_reload_command = ''
-#service_promote_command = ''		# Note: this overrides any value contained in the setting
-					# "promote_command". This is intended for systems which
-					# provide a package-level promote command, such as Debian's
-					# "pg_ctlcluster"
-
+#service_promote_command = ''		# This parameter is intended for systems which provide a
+					# package-level promote command, such as Debian's
+					# "pg_ctlcluster". *IMPORTANT*: it is *not* a substitute
+					# for "promote_command"; do not use "repmgr standby promote"
+					# (or a script which executes "repmgr standby promote") here.
 
 #------------------------------------------------------------------------------
 # Status check thresholds