<chapter id="repmgrd-configuration">

 <indexterm>
   <primary>repmgrd</primary>
   <secondary>configuration</secondary>
 </indexterm>

 <title>repmgrd configuration</title>
 <para>
  To use <application>repmgrd</application>, its associated function library must 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>
 <para>
  Additionally the following <application>repmgrd</application> options *must* be set in
  <filename>repmgr.conf</filename> (adjust configuration file locations as appropriate):
  <programlisting>
    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'</programlisting>
 </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>repmgr.conf.sample</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
  <varname>promote_command</varname> or <varname>follow_command</varname>,
  depending on whether the current server is to become the new primary, or
  needs to follow another server which has become the new primary. Note that
  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>
 <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>
 <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">
  <title>repmgrd log rotation</title>
  <para>
   To ensure the current <application>repmgrd</application> logfile 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>
