mirror of
https://github.com/EnterpriseDB/repmgr.git
synced 2026-03-24 15:46:29 +00:00
5398fd2d22
Basically any setting which can contain a user-defined script *must* have the full path set, even if it's repmgr being executed. We could potentially apply some heuristics to detect if the first item in the setting is "repmgr" (or more precisely repmgrd's program name), but this will require some careful thought and testing that it works as intended.
366 lines
15 KiB
Plaintext
366 lines
15 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 via <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>
|
|
|
|
<para>
|
|
To apply configuration file changes to a running <application>repmgrd</application>
|
|
daemon, execute the operating system's r<application>repmgrd</application> service reload command
|
|
(see <xref linkend="appendix-packages"> for examples),
|
|
or for instances which were manually started, execute <command>kill -HUP</command>, e.g.
|
|
<command>kill -HUP `cat /tmp/repmgrd.pid`</command>.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
Check the <application>repmgrd</application> log to see what changes were
|
|
applied, or if any issues were encountered when reloading the configuration.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
Note that only a subset of configuration file parameters can be changed on a
|
|
running <application>repmgrd</application> daemon.
|
|
</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; alway specify the full path to the &repmgr; binary.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
&repmgr; will not apply <option>pg_bindir</option> when executing <option>promote_command</option>
|
|
or <option>follow_command</option>; these can be user-defined scripts so must always be
|
|
specified with the full path.
|
|
</para>
|
|
</note>
|
|
|
|
<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-file-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</programlisting>
|
|
and stopped with <command>kill `cat /tmp/repmgrd.pid`</command>. Adjust paths as appropriate.
|
|
</para>
|
|
|
|
<sect2 id="repmgrd-pid-file" xreflabel="repmgrd's PID file">
|
|
<indexterm>
|
|
<primary>repmgrd</primary>
|
|
<secondary>PID file</secondary>
|
|
</indexterm>
|
|
<indexterm>
|
|
<primary>PID file</primary>
|
|
<secondary>repmgrd</secondary>
|
|
</indexterm>
|
|
<title>repmgrd's PID file</title>
|
|
<para>
|
|
<application>repmgrd</application> will generate a PID file by default.
|
|
</para>
|
|
<note>
|
|
<simpara>
|
|
This is a behaviour change from previous versions (earlier than 4.1), where
|
|
the PID file had to be explicitly specified with the command line
|
|
parameter <option> --pid-file</option>.
|
|
</simpara>
|
|
</note>
|
|
<para>
|
|
The PID file can be specified in <filename>repmgr.conf</filename> with the configuration
|
|
parameter <varname>repmgrd_pid_file</varname>.
|
|
</para>
|
|
<para>
|
|
It can also be specified on the command line (as in previous versions) with
|
|
the command line parameter <option>--pid-file</option>. Note this will override
|
|
any value set in <filename>repmgr.conf</filename> with <varname>repmgrd_pid_file</varname>.
|
|
<option>--pid-file</option> may be deprecated in future releases.
|
|
</para>
|
|
<para>
|
|
If a PID file location was specified by the package maintainer, <application>repmgrd</application>
|
|
will use that. This only applies if &repmgr; was installed from a package and the package
|
|
maintainer has specified the PID file location.
|
|
</para>
|
|
<para>
|
|
If none of the above apply, <application>repmgrd</application> will create a PID file
|
|
in the operating system's temporary directory (das etermined by the environment variable
|
|
<varname>TMPDIR</varname>, or if that is not set, will use <filename>/tmp</filename>).
|
|
</para>
|
|
<para>
|
|
To prevent a PID file being generated at all, provide the command line option
|
|
<option>--no-pid-file</option>.
|
|
</para>
|
|
<para>
|
|
To see which PID file <application>repmgrd</application> would use, execute <application>repmgrd</application>
|
|
with the option <option>--show-pid-file</option>. <application>repmgrd</application>
|
|
will not start if this option is provided. Note that the value shown is the
|
|
file <application>repmgrd</application> would use next time it starts, and is
|
|
not necessarily the PID file currently in use.
|
|
</para>
|
|
</sect2>
|
|
|
|
<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>
|
|
|
|
<indexterm>
|
|
<primary>repmgrd</primary>
|
|
<secondary>log rotation</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/repmgr/repmgrd.log {
|
|
missingok
|
|
compress
|
|
rotate 52
|
|
maxsize 100M
|
|
weekly
|
|
create 0600 postgres postgres
|
|
postrotate
|
|
/usr/bin/killall -HUP repmgrd
|
|
endscript
|
|
}</programlisting>
|
|
</para>
|
|
|
|
</sect1>
|
|
</chapter>
|