From 09b8a866056578bb66c427be1de63af1c69a088e Mon Sep 17 00:00:00 2001 From: Ian Barwick Date: Thu, 19 Apr 2018 16:46:41 +0900 Subject: [PATCH] doc: improve configuration documentation With special attention to setting service commands, and extra special mention of "pg_ctlcluster" for Debian/Ubuntu users. --- doc/configuration-file-settings.sgml | 9 +- doc/configuration-service-commands.sgml | 111 ++++++++++ doc/configuration.sgml | 1 + doc/filelist.sgml | 1 + doc/repmgrd-configuration.sgml | 273 +++++++++++++----------- doc/repmgrd-monitoring.sgml | 4 + repmgr.conf.sample | 3 + 7 files changed, 270 insertions(+), 132 deletions(-) create mode 100644 doc/configuration-service-commands.sgml diff --git a/doc/configuration-file-settings.sgml b/doc/configuration-file-settings.sgml index ebf8f17d..937b54b9 100644 --- a/doc/configuration-file-settings.sgml +++ b/doc/configuration-file-settings.sgml @@ -1,10 +1,10 @@ repmgr.conf - settings + basic settings - Configuration file settings + Basic configuration file settings Each repmgr.conf file must contain the following parameters: @@ -92,7 +92,10 @@ For a full list of annotated configuration items, see the file - repmgr.conf.sample. + repmgr.conf.sample. + + + For repmgrd-specific settings, see . diff --git a/doc/configuration-service-commands.sgml b/doc/configuration-service-commands.sgml new file mode 100644 index 00000000..6e0dfa23 --- /dev/null +++ b/doc/configuration-service-commands.sgml @@ -0,0 +1,111 @@ + + + repmgr.conf + service command settings + + Service command settings + + + In some circumstances, &repmgr; (and repmgrd) need to + be able to stop, start or restart PostgreSQL. &repmgr; commands which need to do this + include repmgr standby follow, + repmgr standby switchover and + repmgr node rejoin. + + + By default, &repmgr; will use PostgreSQL's pg_ctl to control the PostgreSQL + server. However this can lead to various problems, particularly when PostgreSQL has been + installed from packages, and expecially so if systemd is in use. + + + + + + If using systemd, ensure you have RemoteIPC set to off. + See the systemd + entry in the PostgreSQL wiki for details. + + + + + + With this in mind, we recommend to always configure &repmgr; to use the + available system service commands. + + + + To do this, specify the appropriate command for each action + in repmgr.conf using the following configuration + parameters: + + service_start_command + service_stop_command + service_restart_command + service_reload_command + + + + + It's also possible to specify a service_promote_command; + 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. + + + + + To confirm which command &repmgr; will execute for each action, use + repmgr node service --list --action=..., e.g.: + + repmgr -f /etc/repmgr.conf node service --list --action=stop + repmgr -f /etc/repmgr.conf node service --list --action=start + repmgr -f /etc/repmgr.conf node service --list --action=restart + repmgr -f /etc/repmgr.conf node service --list --action=reload + + + + These commands will be executed by the system user which &repmgr; runs as (usually postgres) + and will probably require passwordless sudo access to be able to execute the command. + + + For example, using systemd on CentOS 7, the service commands can be + set as follows: + + service_start_command = 'sudo systemctl start postgresql-9.6' + service_stop_command = 'sudo systemctl stop postgresql-9.6' + service_restart_command = 'sudo systemctl restart postgresql-9.6' + service_reload_command = 'sudo systemctl reload postgresql-9.6' + and /etc/sudoers should be set as follows: + + Defaults:postgres !requiretty + postgres ALL = NOPASSWD: /usr/bin/systemctl stop postgresql-9.6, \ + /usr/bin/systemctl start postgresql-9.6, \ + /usr/bin/systemctl restart postgresql-9.6 \ + /usr/bin/systemctl reload postgresql-9.6 + + + + + pg_ctlcluster + service command settings + + + Debian/Ubuntu users: instead of calling sudo systemctl directly, use + sudo pg_ctlcluster, e.g.: + + service_start_command = 'sudo pg_ctlcluster 9.6 main start' + service_stop_command = 'sudo pg_ctlcluster 9.6 main stop' + service_restart_command = 'sudo pg_ctlcluster 9.6 main restart' + service_reload_command = 'sudo pg_ctlcluster 9.6 main reload' + and set /etc/sudoers accordingly. + + + While pg_ctlcluster should work, it's strongly recommended + to use sudo pg_ctlcluster on systemd + systems, to ensure systemd has a correct picture of + the PostgreSQL application state. + + + + + diff --git a/doc/configuration.sgml b/doc/configuration.sgml index 95585032..85e742b7 100644 --- a/doc/configuration.sgml +++ b/doc/configuration.sgml @@ -3,6 +3,7 @@ &configuration-file; &configuration-file-settings; + &configuration-service-commands; diff --git a/doc/filelist.sgml b/doc/filelist.sgml index 7fa683a3..bf6ec0da 100644 --- a/doc/filelist.sgml +++ b/doc/filelist.sgml @@ -39,6 +39,7 @@ + diff --git a/doc/repmgrd-configuration.sgml b/doc/repmgrd-configuration.sgml index 35e6c62a..9623cd67 100644 --- a/doc/repmgrd-configuration.sgml +++ b/doc/repmgrd-configuration.sgml @@ -1,63 +1,145 @@ - - repmgrd - configuration - + + repmgrd + configuration + - repmgrd configuration - - To use repmgrd, its associated function library must be - included in postgresql.conf with: + repmgrd configuration - - shared_preload_libraries = 'repmgr' - - - Changing this setting requires a restart of PostgreSQL; for more details see - the PostgreSQL documentation. - - - Additionally the following repmgrd options *must* be set in - repmgr.conf (adjust configuration file locations as appropriate): - - failover=automatic - promote_command='repmgr standby promote -f /etc/repmgr.conf --log-to-file' - follow_command='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. - 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 either - promote_command (if the current server is to become the new primary) or - follow_command (if the current serverneeds 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. - - + + repmgrd is a daemon which runs on each PostgreSQL node, + monitoring the local node, and (unless it's the primary node) the upstream server + (the primary server or with cascading replication, another standby) which it's + connected to. + + + repmgrd can be configured to provide failover + capability in case the primary upstream node becomes unreachable, and/or + provide monitoring data to the &repmgr; metadatabase. + - - 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. - + + repmgrd basic configuration + + + To use repmgrd, its associated function library must be + included in postgresql.conf with: + + + shared_preload_libraries = 'repmgr' + + + Changing this setting requires a restart of PostgreSQL; for more details see + the PostgreSQL documentation. + + + + automatic failover configuration + + If using automatic failover, the following repmgrd options *must* be set in + repmgr.conf : + + 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; we recomment specifying the full path to the &repmgr; binary. + + + 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. + + + + + + repmgrd + PostgreSQL service configuration + + PostgreSQL service configuration + + If using automatic failover, currently repmgrd will need to execute + repmgr standby follow + to restart PostgreSQL on standbys to have them follow a new primary. + + + To ensure this happens smoothly, it's essential to provide the appropriate system/service restart + command appropriate to your operating system via service_restart_command + in repmgr.conf. If you don't do this, repmgrd + will default to using pg_ctl, which can result in unexpected problems, + particularly on systemd-based systems. + + + For more details, see . + + + + + + repmgrd + monitoring configuration + + Monitoring configuration + + To enable monitoring, set: + + monitoring_history=yes + in repmgr.conf. + + + The default monitoring interval is 2 seconds; this value can be explicitly set using: + + monitor_interval_secs=<seconds> + in repmgr.conf. + + + For more details on monitoring, see . + + + + repmgrd connection settings @@ -84,86 +166,19 @@ - + + - service commands + log rotation repmgrd - repmgrd and service commands - - By default, &repmgr; will use pg_ctl to - stop, start, restart, reloadthe PostgreSQL cluster. - However, if installed from a package, particularly under - pg_ctl, it's advisable to specify - the appropriate service commands to perform these options. - - - To do this, specify the appropriate command for each action - in repmgr.conf using the following configuration - parameters: - - service_start_command - service_stop_command - service_restart_command - service_reload_command - - - - - It's also possible to specify a service_promote_command; - 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. - - - - - To confirm which command &repmgr; will execute for each action, use - repmgr node service --list --action=..., e.g.: - - repmgr -f /etc/repmgr.conf node service --list --action=stop - repmgr -f /etc/repmgr.conf node service --list --action=start - repmgr -f /etc/repmgr.conf node service --list --action=restart - repmgr -f /etc/repmgr.conf node service --list --action=reload - - - - - These commands will be executed by the system user which &repmgr; runs as (usually postgres) - and will probably require passwordless sudo access to be able to execute the command. - - - For example, using systemd on CentOS 7, the service commands can be - set as follows: - - service_start_command = 'sudo systemctl start postgresql-9.6' - service_stop_command = 'sudo systemctl stop postgresql-9.6' - service_restart_command = 'sudo systemctl restart postgresql-9.6' - and /etc/sudoers should be set as follows: - - Defaults:postgres !requiretty - postgres ALL = NOPASSWD: /usr/bin/systemctl stop postgresql-9.6, \ - /usr/bin/systemctl start postgresql-9.6, \ - /usr/bin/systemctl restart postgresql-9.6 - - - - - If using systemd, ensure you have RemoteIPC set to off. - See the systemd - entry in the PostgreSQL wiki for details. - - - - - - repmgrd log rotation - To ensure the current repmgrd logfile does not grow - indefinitely, configure your system's logrotate to - regularly rotate it. + To ensure the current repmgrd logfile + (specified in repmgr.conf with the parameter + does not grow indefinitely, configure your + system's logrotate to regularly rotate it. Sample configuration to rotate logfiles weekly with retention for diff --git a/doc/repmgrd-monitoring.sgml b/doc/repmgrd-monitoring.sgml index e20d3f07..60de86ed 100644 --- a/doc/repmgrd-monitoring.sgml +++ b/doc/repmgrd-monitoring.sgml @@ -3,6 +3,10 @@ repmgrd monitoring + + monitoring + with repmgrd + Monitoring with repmgrd diff --git a/repmgr.conf.sample b/repmgr.conf.sample index 5d9f8fd5..ac9b137c 100644 --- a/repmgr.conf.sample +++ b/repmgr.conf.sample @@ -290,6 +290,9 @@ ssh_options='-q -o ConnectTimeout=10' # Options to append to "ssh" # /usr/bin/systemctl start postgresql-9.6, \ # /usr/bin/systemctl restart postgresql-9.6 # +# Debian/Ubuntu users: use "sudo pg_ctlcluster" to execute service control commands. +# +# For more details, see: https://repmgr.org/docs/4.0/configuration-service-commands.html #service_start_command = '' #service_stop_command = ''