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