From 63242e2277ac4afc39e52ffc7030abad09df2929 Mon Sep 17 00:00:00 2001 From: Ian Barwick Date: Mon, 16 Jul 2018 14:40:04 +0900 Subject: [PATCH] doc: update documentation of "promote_command" and "service_promote_command" The documentation implied it would override "promote_command", which is not the case. "promote_command" is used by repmgrd to execute "repmgr standby promote" (either directly or via a custom script). "service_promote_command" can be set to specify a package-level service command to promote the local PostgreSQL instance from standby to primary, e.g. Debian's pg_ctlcluster. If set, this will be executed by "repmgr standby promote". Also update code comments to clarify usage. Related to GitHub #473. --- doc/configuration-file-service-commands.sgml | 14 ++++++++--- doc/repmgrd-configuration.sgml | 26 ++++++++++++++------ repmgr.conf.sample | 14 +++++------ repmgrd-physical.c | 20 +++++++++++---- 4 files changed, 52 insertions(+), 22 deletions(-) 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\"",