mirror of
https://github.com/EnterpriseDB/repmgr.git
synced 2026-03-22 22:56:29 +00:00
283 lines
11 KiB
Plaintext
283 lines
11 KiB
Plaintext
<chapter id="repmgrd-configuration">
|
|
|
|
<indexterm>
|
|
<primary>repmgrd</primary>
|
|
<secondary>configuration</secondary>
|
|
</indexterm>
|
|
|
|
<title>repmgrd configuration</title>
|
|
|
|
<para>
|
|
<application>repmgrd</application> 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.
|
|
</para>
|
|
<para>
|
|
<application>repmgrd</application> can be configured to provide failover
|
|
capability in case the primary upstream node becomes unreachable, and/or
|
|
provide monitoring data to the &repmgr; metadatabase.
|
|
</para>
|
|
|
|
<sect1 id="repmgrd-basic-configuration">
|
|
<title>repmgrd basic configuration</title>
|
|
|
|
<para>
|
|
To use <application>repmgrd</application>, its associated function library <emphasis>must</emphasis> be
|
|
included in <filename>postgresql.conf</filename> with:
|
|
|
|
<programlisting>
|
|
shared_preload_libraries = 'repmgr'</programlisting>
|
|
</para>
|
|
<para>
|
|
Changing this setting requires a restart of PostgreSQL; for more details see
|
|
the <ulink url="https://www.postgresql.org/docs/current/static/runtime-config-client.html#GUC-SHARED-PRELOAD-LIBRARIES">PostgreSQL documentation</ulink>.
|
|
</para>
|
|
|
|
<sect2 id="repmgrd-automatic-failover-configuration">
|
|
<title>automatic failover configuration</title>
|
|
<para>
|
|
If using automatic failover, the following <application>repmgrd</application> options *must* be set in
|
|
<filename>repmgr.conf</filename> :
|
|
<programlisting>
|
|
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'</programlisting>
|
|
</para>
|
|
<para>
|
|
Adjust file paths as appropriate; we recomment specifying the full path to the &repmgr; binary.
|
|
</para>
|
|
<para>
|
|
Note that the <literal>--log-to-file</literal> option will cause
|
|
output generated by the &repmgr; command, when executed by <application>repmgrd</application>,
|
|
to be logged to the same destination configured to receive log output for <application>repmgrd</application>.
|
|
See <filename><ulink url="https://raw.githubusercontent.com/2ndQuadrant/repmgr/master/repmgr.conf.sample">repmgr.conf.sample</ulink></filename>
|
|
for further <application>repmgrd</application>-specific settings.
|
|
</para>
|
|
<para>
|
|
When <varname>failover</varname> is set to <literal>automatic</literal>, upon detecting failure
|
|
of the current primary, <application>repmgrd</application> will execute one of:
|
|
</para>
|
|
<itemizedlist spacing="compact" mark="bullet">
|
|
<listitem>
|
|
<simpara>
|
|
<varname>promote_command</varname> (if the current server is to become the new primary)
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<varname>follow_command</varname> (if the current server needs to follow another server which has
|
|
become the new primary)
|
|
</simpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<note>
|
|
<para>
|
|
These commands can be any valid shell script which results in one of these
|
|
two actions happening, but if &repmgr;'s <command>standby follow</command> or
|
|
<command>standby promote</command>
|
|
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.
|
|
</para>
|
|
</note>
|
|
|
|
<para>
|
|
The <varname>follow_command</varname> should provide the <literal>--upstream-node-id=%n</literal>
|
|
option to <command>repmgr standby follow</command>; the <literal>%n</literal> will be replaced by
|
|
<application>repmgrd</application> 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
|
|
<command>repmgr standby follow</command> will result in the node continuing to follow
|
|
the original primary.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="repmgrd-service-configuration">
|
|
<indexterm>
|
|
<primary>repmgrd</primary>
|
|
<secondary>PostgreSQL service configuration</secondary>
|
|
</indexterm>
|
|
<title>PostgreSQL service configuration</title>
|
|
<para>
|
|
If using automatic failover, currently <application>repmgrd</application> will need to execute
|
|
<link linkend="repmgr-standby-follow"><command>repmgr standby follow</command></link>
|
|
to restart PostgreSQL on standbys to have them follow a new primary.
|
|
</para>
|
|
<para>
|
|
To ensure this happens smoothly, it's essential to provide the appropriate system/service restart
|
|
command appropriate to your operating system via <varname>service_restart_command</varname>
|
|
in <filename>repmgr.conf</filename>. If you don't do this, <application>repmgrd</application>
|
|
will default to using <command>pg_ctl</command>, which can result in unexpected problems,
|
|
particularly on <application>systemd</application>-based systems.
|
|
</para>
|
|
<para>
|
|
For more details, see <xref linkend="configuration-service-commands">.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="repmgrd-monitoring-configuration">
|
|
<indexterm>
|
|
<primary>repmgrd</primary>
|
|
<secondary>monitoring configuration</secondary>
|
|
</indexterm>
|
|
<title>Monitoring configuration</title>
|
|
<para>
|
|
To enable monitoring, set:
|
|
<programlisting>
|
|
monitoring_history=yes</programlisting>
|
|
in <filename>repmgr.conf</filename>.
|
|
</para>
|
|
<para>
|
|
The default monitoring interval is 2 seconds; this value can be explicitly set using:
|
|
<programlisting>
|
|
monitor_interval_secs=<seconds></programlisting>
|
|
in <filename>repmgr.conf</filename>.
|
|
</para>
|
|
<para>
|
|
For more details on monitoring, see <xref linkend="repmgrd-monitoring">.
|
|
</para>
|
|
</sect2>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="repmgrd-daemon">
|
|
<indexterm>
|
|
<primary>repmgrd</primary>
|
|
<secondary>starting and stopping</secondary>
|
|
</indexterm>
|
|
<title>repmgrd daemon</title>
|
|
<para>
|
|
If installed from a package, the <application>repmgrd</application> can be started
|
|
via the operating system's service command, e.g. in <application>systemd</application>
|
|
using <command>systemctl</command>.
|
|
</para>
|
|
<para>
|
|
See appendix <xref linkend="appendix-packages"> for details of service commands
|
|
for different distributions.
|
|
</para>
|
|
<para>
|
|
<application>repmgrd</application> can be started manually like this:
|
|
<programlisting>
|
|
repmgrd -f /etc/repmgr.conf --pid-file /tmp/repmgrd.pid --daemonize</programlisting>
|
|
and stopped with <command>kill `cat /tmp/repmgrd.pid`</command>. Adjust paths as appropriate.
|
|
</para>
|
|
<para>
|
|
To apply configuration file changes to a running <application>repmgrd</application>
|
|
daemon, execute the operating system's service reload command (for manually started
|
|
instances, execute <command>kill -HUP `cat /tmp/repmgrd.pid`</command>).
|
|
Note that only a subset of configuration file parameters can be changed on a
|
|
running <application>repmgrd</application> daemon.
|
|
</para>
|
|
|
|
<sect2 id="repmgrd-configuration-debian-ubuntu">
|
|
<indexterm>
|
|
<primary>repmgrd</primary>
|
|
<secondary>Debian/Ubuntu and daemon configuration</secondary>
|
|
</indexterm>
|
|
<indexterm>
|
|
<primary>Debian/Ubuntu</primary>
|
|
<secondary>repmgrd daemon configuration</secondary>
|
|
</indexterm>
|
|
|
|
<title>repmgrd daemon configuration on Debian/Ubuntu</title>
|
|
|
|
<para>
|
|
If &repmgr; was installed from Debian/Ubuntu packages, additional configuration
|
|
is required before <application>repmgrd</application> is started as a daemon.
|
|
</para>
|
|
<para>
|
|
This is done via the file <filename>/etc/default/repmgrd</filename>, which by default
|
|
looks like this:
|
|
<programlisting>
|
|
# default settings for repmgrd. This file is source by /bin/sh from
|
|
# /etc/init.d/repmgrd
|
|
|
|
# disable repmgrd by default so it won't get started upon installation
|
|
# valid values: yes/no
|
|
REPMGRD_ENABLED=no
|
|
|
|
# configuration file (required)
|
|
#REPMGRD_CONF="/path/to/repmgr.conf"
|
|
|
|
# additional options
|
|
#REPMGRD_OPTS=""
|
|
|
|
# user to run repmgrd as
|
|
#REPMGRD_USER=postgres
|
|
|
|
# repmgrd binary
|
|
#REPMGRD_BIN=/usr/bin/repmgrd
|
|
|
|
# pid file
|
|
#REPMGRD_PIDFILE=/var/run/repmgrd.pid</programlisting>
|
|
</para>
|
|
<para>
|
|
Set <varname>REPMGRD_ENABLED</varname> to <literal>yes</literal>, and <varname>REPMGRD_CONF</varname>
|
|
to the <filename>repmgr.conf</filename> file you are using.
|
|
</para>
|
|
<para>
|
|
If using <application>systemd</application>, you may need to execute <command>systemctl daemon-reload</command>.
|
|
Also, if you attempted to start <application>repmgrd</application> using <command>systemctl start repmgrd</command>,
|
|
you'll need to execute <command>systemctl stop repmgrd</command>. Because that's how <application>systemd</application>
|
|
rolls.
|
|
</para>
|
|
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="repmgrd-connection-settings">
|
|
<title>repmgrd connection settings</title>
|
|
<para>
|
|
In addition to the &repmgr; configuration settings, parameters in the
|
|
<varname>conninfo</varname> string influence how &repmgr; makes a network connection to
|
|
PostgreSQL. In particular, if another server in the replication cluster
|
|
is unreachable at network level, system network settings will influence
|
|
the length of time it takes to determine that the connection is not possible.
|
|
</para>
|
|
<para>
|
|
In particular explicitly setting a parameter for <literal>connect_timeout</literal>
|
|
should be considered; the effective minimum value of <literal>2</literal>
|
|
(seconds) will ensure that a connection failure at network level is reported
|
|
as soon as possible, otherwise depending on the system settings (e.g.
|
|
<varname>tcp_syn_retries</varname> in Linux) a delay of a minute or more
|
|
is possible.
|
|
</para>
|
|
<para>
|
|
For further details on <varname>conninfo</varname> network connection
|
|
parameters, see the
|
|
<ulink url="https://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-PARAMKEYWORDS">PostgreSQL documentation</ulink>.
|
|
</para>
|
|
</sect1>
|
|
|
|
|
|
|
|
<sect1 id="repmgrd-log-rotation">
|
|
<indexterm>
|
|
<primary>log rotation</primary>
|
|
<secondary>repmgrd</secondary>
|
|
</indexterm>
|
|
|
|
<title>repmgrd log rotation</title>
|
|
<para>
|
|
To ensure the current <application>repmgrd</application> logfile
|
|
(specified in <filename>repmgr.conf</filename> with the parameter
|
|
<option>log_file</option> does not grow indefinitely, configure your
|
|
system's <command>logrotate</command> to regularly rotate it.
|
|
</para>
|
|
<para>
|
|
Sample configuration to rotate logfiles weekly with retention for
|
|
up to 52 weeks and rotation forced if a file grows beyond 100Mb:
|
|
<programlisting>
|
|
/var/log/postgresql/repmgr-9.6.log {
|
|
missingok
|
|
compress
|
|
rotate 52
|
|
maxsize 100M
|
|
weekly
|
|
create 0600 postgres postgres
|
|
}</programlisting>
|
|
</para>
|
|
</sect1>
|
|
</chapter>
|