diff --git a/doc/configuration-file-service-commands.sgml b/doc/configuration-file-service-commands.sgml
index fee173d0..30d30933 100644
--- a/doc/configuration-file-service-commands.sgml
+++ b/doc/configuration-file-service-commands.sgml
@@ -50,10 +50,18 @@
- It's also possible to specify a service_promote_command;
- this overrides any value contained in the setting promote_command.
+ It's also possible to specify a service_promote_command.
This is intended for systems which provide a package-level promote command,
- such as Debian's pg_ctlcluster.
+ such as Debian's pg_ctlcluster, to promote the
+ PostgreSQL from standby to primary.
+
+
+ If your packaging system does not provide such a command, it can be left empty,
+ and &repmgr; will generate the appropriate `pg_ctl ... promote` command.
+
+
+ Do not confuse this with promote_command, which is used
+ by repmgrd to execute .
diff --git a/doc/repmgrd-configuration.sgml b/doc/repmgrd-configuration.sgml
index eebe308f..70e5b168 100644
--- a/doc/repmgrd-configuration.sgml
+++ b/doc/repmgrd-configuration.sgml
@@ -34,6 +34,25 @@
the PostgreSQL documentation.
+
+ To apply configuration file changes to a running repmgrd
+ daemon, execute the operating system's rrepmgrd service reload command
+ (see for examples),
+ or for instances which were manually started, execute kill -HUP, e.g.
+ kill -HUP `cat /tmp/repmgrd.pid`.
+
+
+
+ Check the repmgrd log to see what changes were
+ applied, or if any issues were encountered when reloading the configuration.
+
+
+
+ Note that only a subset of configuration file parameters can be changed on a
+ running repmgrd daemon.
+
+
+
automatic failover configuration
@@ -162,13 +181,6 @@
repmgrd -f /etc/repmgr.conf --pid-file /tmp/repmgrd.pid
and stopped with kill `cat /tmp/repmgrd.pid`. Adjust paths as appropriate.
-
- To apply configuration file changes to a running repmgrd
- daemon, execute the operating system's service reload command (for manually started
- instances, execute kill -HUP `cat /tmp/repmgrd.pid`).
- Note that only a subset of configuration file parameters can be changed on a
- running repmgrd daemon.
-
diff --git a/repmgr.conf.sample b/repmgr.conf.sample
index 07395c90..135f72d7 100644
--- a/repmgr.conf.sample
+++ b/repmgr.conf.sample
@@ -280,11 +280,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
@@ -338,11 +338,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
diff --git a/repmgrd-physical.c b/repmgrd-physical.c
index 286ba9ab..c083f614 100644
--- a/repmgrd-physical.c
+++ b/repmgrd-physical.c
@@ -162,8 +162,8 @@ do_physical_node_check(void)
if (config_file_options.failover == FAILOVER_AUTOMATIC)
{
/*
- * check that promote/follow commands are defined, otherwise repmgrd
- * won't be able to perform any useful action
+ * Check that "promote_command" and "follow_command" are defined, otherwise repmgrd
+ * won't be able to perform any useful action in a failover situation.
*/
bool required_param_missing = false;
@@ -175,14 +175,24 @@ do_physical_node_check(void)
if (config_file_options.service_promote_command[0] != '\0')
{
/*
- * if repmgrd executes "service_promote_command" directly,
- * repmgr metadata won't get updated
+ * "service_promote_command" is *not* a substitute for "promote_command";
+ * it is intended for use in those systems (e.g. Debian) where there's a service
+ * level promote command (e.g. pg_ctlcluster).
+ *
+ * "promote_command" should either execute "repmgr standby promote" directly, or
+ * a script which executes "repmgr standby promote". This is essential, as the
+ * repmgr metadata is updated by "repmgr standby promote".
+ *
+ * "service_promote_command", if set, will be executed by "repmgr standby promote",
+ * but never by repmgrd.
+ *
*/
log_hint(_("\"service_promote_command\" is set, but can only be executed by \"repmgr standby promote\""));
}
required_param_missing = true;
}
+
if (config_file_options.follow_command[0] == '\0')
{
log_error(_("\"follow_command\" must be defined in the configuration file"));
@@ -2063,7 +2073,7 @@ promote_self(void)
return FAILOVER_STATE_PROMOTION_FAILED;
}
- /* the presence of either of this command has been established already */
+ /* the presence of this command has been established already */
promote_command = config_file_options.promote_command;
log_debug("promote command is:\n \"%s\"",