From b241c606c07134e7a6a3f19d9a98e2faf88ad1dc Mon Sep 17 00:00:00 2001 From: Ian Barwick Date: Mon, 11 Mar 2019 14:50:33 +0900 Subject: [PATCH] doc: expand repmgrd configuration section --- doc/repmgrd-configuration.sgml | 261 +++++++++++++++++++++++---------- repmgr.conf.sample | 12 +- 2 files changed, 193 insertions(+), 80 deletions(-) diff --git a/doc/repmgrd-configuration.sgml b/doc/repmgrd-configuration.sgml index f87f953f..553bce94 100644 --- a/doc/repmgrd-configuration.sgml +++ b/doc/repmgrd-configuration.sgml @@ -36,96 +36,205 @@ - Automatic failover configuration + Required configuration for automatic failover + - If using automatic failover, the following repmgrd options *must* be set in - repmgr.conf : + The following repmgrd options must be set in + repmgr.conf: + + + + + + + + + + + + + + + + + Example: failover=automatic promote_command='/usr/bin/repmgr standby promote -f /etc/repmgr.conf --log-to-file' follow_command='/usr/bin/repmgr standby follow -f /etc/repmgr.conf --log-to-file --upstream-node-id=%n' - Adjust file paths as appropriate; alway specify the full path to the &repmgr; binary. + Details of each option are as follows: + + - - - &repmgr; will not apply when executing - or ; these can be user-defined scripts so must always be - specified with the full path. - - + + failover + + + + + can be one of automatic or manual. + + + + If is set to manual, repmgrd + will not take any action if a failover situation is detected, and the node may need to + be modified manually (e.g. by executing repmgr standby follow). + + + + + + + + + promote_command + + + + + The program or script defined in will be executed + in a failover situation when repmgrd determines that + the current node is to become the new primary node. + + + Normally is set as &repmgr;'s + repmgr standby promote command. + + + It is also possible to provide e.g. a shell script to e.g. perform user-defined tasks + before promoting the current node. In this case the script must + at some point execute repmgr standby promote + to promote the node; if this is not done, &repmgr; metadata will not be updated and + &repmgr; will no longer function reliably. + + + Example: + + promote_command='/usr/bin/repmgr standby promote -f /etc/repmgr.conf --log-to-file' + + + + Note that the --log-to-file option will cause + output generated by the &repmgr; command, when executed by repmgrd, + to be logged to the same destination configured to receive log output for repmgrd. + + + + &repmgr; will not apply when executing + or ; these can be user-defined scripts so must always be + specified with the full path. + + + + + + + + follow_command + + + + + The program or script defined in will be executed + in a failover situation when repmgrd determines that + the current node is to follow the new primary node. + + + Normally is set as &repmgr;'s + repmgr standby promote command. + + + The parameter + should provide the --upstream-node-id=%n + option to repmgr standby follow; the %n will be replaced by + repmgrd with the ID of the new primary node. If this is not provided, + repmgr standby follow 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 + repmgr standby follow will result in the node continuing to follow + the original primary. + + + It is also possible to provide e.g. a shell script to e.g. perform user-defined tasks + before promoting the current node. In this case the script must + at some point execute repmgr standby follow + to promote the node; if this is not done, &repmgr; metadata will not be updated and + &repmgr; will no longer function reliably. + + + Example: + + follow_command='/usr/bin/repmgr standby follow -f /etc/repmgr.conf --log-to-file --upstream-node-id=%n' + + + + Note that the --log-to-file option will cause + output generated by the &repmgr; command, when executed by repmgrd, + to be logged to the same destination configured to receive log output for repmgrd. + + + + &repmgr; will not apply when executing + or ; these can be user-defined scripts so must always be + specified with the full path. + + + + + + + + + + + + + Optional configuration for automatic failover + + + The following configuraton options can be used to fine-tune automatic failove: + + + + + + + connection_check_type + + + + + The option is used to select the method + repmgrd uses to determine whether the upstream node is available. + + + Possible values are: + + + + ping (default) - uses PQping() to + determine server availability + + + + + connection - determines server availability + by executing an SQL statement on the node via the existing connection + + + + + + + + - Note that the --log-to-file option will cause - output generated by the &repmgr; command, when executed by repmgrd, - to be logged to the same destination configured to receive log output for repmgrd. See repmgr.conf.sample for further repmgrd-specific settings. - - When failover is set to automatic, upon detecting failure - of the current primary, repmgrd will execute one of: - - - - - promote_command (if the current server is to become the new primary) - - - - - follow_command (if the current server needs to follow another server which has - become the new primary) - - - - - - These commands can be any valid shell script which results in one of these - two actions happening, but if &repmgr;'s standby follow or - standby promote - 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. - - - - - The follow_command should provide the --upstream-node-id=%n - option to repmgr standby follow; the %n will be replaced by - repmgrd 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 - repmgr standby follow will result in the node continuing to follow - the original primary. - - - - - connection_check_type - - Additionally, the option to enable selection of the method - repmgrd uses to determine whether the upstream node is available. - - - Possible values are: - - - - ping (default) - uses PQping() to - determine server availability - - - - - connection - determines server availability - by executing an SQL statement on the node via the existing connection - - - - diff --git a/repmgr.conf.sample b/repmgr.conf.sample index 34ebccd5..812c6804 100644 --- a/repmgr.conf.sample +++ b/repmgr.conf.sample @@ -325,10 +325,14 @@ ssh_options='-q -o ConnectTimeout=10' # Options to append to "ssh" #standby_disconnect_on_failover=false # If "true", in a failover situation wait for all standbys to # disconnect their WAL receivers before electing a new primary #sibling_nodes_disconnect_timeout=30 # If "standby_disconnect_on_failover", maximum length of time (in seconds) - # to wait for other standbys to confirm they have disconnected their - # WAL receivers -#primary_visibility_consensus=false # If "true", only continue with failover if no standbys have seen - # the primary node recently + # to wait for other standbys to confirm they have disconnected their + # WAL receivers +#primary_visibility_consensus=false # If "true", only continue with failover if no standbys have seen + # the primary node recently +#failover_validation_command= # Script to execute for an external mechanism to validate the failover + # decision made by repmgrd. One or both of the following parameter placeholders + # should be provided, which will be replaced by repmgrd with the appropriate + # value: %n (node_id), %a (node_name) #------------------------------------------------------------------------------ # service control commands