repmgr/doc/configuration-file-optional-settings.xml

<sect1 id="configuration-file-optional-settings" xreflabel="optional configuration file settings">

  <title>Optional configuration file settings</title>

  <indexterm>
    <primary>repmgr.conf</primary>
    <secondary>optional settings</secondary>
  </indexterm>

  <note>
    <simpara>
      This section documents a subset of optional configuration settings; for a full
      and annotated view of all configuration options see the
      <ulink url="https://raw.githubusercontent.com/EnterpriseDB/repmgr/master/repmgr.conf.sample">sample repmgr.conf file</ulink>
    </simpara>
  </note>

  <variablelist>


    <varlistentry id="repmgr-conf-config-directory" xreflabel="config_directory">
      <term><varname>config_directory</varname> (<type>string</type>)
        <indexterm>
          <primary><varname>config_directory</varname> configuration file parameter</primary>
        </indexterm>
      </term>
      <listitem>
        <para>
          If PostgreSQL configuration files are located outside the data
	  directory, specify the directory where the main
	  <filename>postgresql.conf</filename> file is located.
        </para>
        <para>
          This enables explicit provision of an external configuration file
          directory, which if set will be passed to <command>pg_ctl</command> as the
          <option>-D</option> parameter. Otherwise <command>pg_ctl</command> will
          default to using the data directory, which will cause some operations
          to fail if the configuration files are not present there.
        </para>
        <note>
          <para>
           This is implemented primarily for feature completeness and for
           development/testing purposes. Users who have installed &repmgr; from
           a package should <emphasis>not</emphasis> rely on  to stop/start/restart PostgreSQL,
           instead they should set the appropriate <option>service_..._command</option>
           for their operating system. For more details see
           <xref linkend="configuration-file-service-commands"/>.
          </para>
        </note>
      </listitem>
    </varlistentry>

    <varlistentry id="repmgr-conf-replication-user" xreflabel="replication_user">
      <term><varname>replication_user</varname> (<type>string</type>)
        <indexterm>
          <primary><varname>replication_user</varname> configuration file parameter</primary>
        </indexterm>
      </term>
      <listitem>
        <para>
          PostgreSQL user to make replication connections with.
          If not set defaults, to the user defined in <xref linkend="repmgr-conf-conninfo"/>.
        </para>
      </listitem>
    </varlistentry>



    <varlistentry id="repmgr-conf-replication-type" xreflabel="replication_type">
      <term><varname>replication_type</varname> (<type>string</type>)
        <indexterm>
          <primary><varname>replication_type</varname> configuration file parameter</primary>
        </indexterm>
      </term>
      <listitem>
        <para>
          Must be <literal>physical</literal> (the default).
        </para>
      </listitem>
    </varlistentry>

    <varlistentry id="repmgr-conf-location" xreflabel="location">
      <term><varname>location</varname> (<type>string</type>)
        <indexterm>
          <primary><varname>location</varname> configuration file parameter</primary>
        </indexterm>
      </term>
      <listitem>
        <para>
          An arbitrary string defining the location of the node; this
	  is used during failover to check visibility of the
	  current primary node.
        </para>
        <para>
          For more details see <xref linkend="repmgrd-network-split"/>.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry id="repmgr-conf-use-replication-slots" xreflabel="use_replication_slots">
      <term><varname>use_replication_slots</varname> (<type>boolean</type>)
        <indexterm>
          <primary><varname>use_replication_slots</varname> configuration file parameter</primary>
        </indexterm>
      </term>
      <listitem>
        <para>
          Whether to use physical replication slots.
        </para>
        <note>
          <para>
	    When using replication slots,
	    <varname>max_replication_slots</varname> should be configured for
	    at least the number of standbys which will connect
	    to the primary.
          </para>
        </note>
      </listitem>
    </varlistentry>

    <varlistentry id="repmgr-conf-ssh-options" xreflabel="ssh_options">
      <term><varname>ssh_options</varname> (<type>string</type>)
        <indexterm>
          <primary><varname>ssh_options</varname> configuration file parameter</primary>
        </indexterm>
      </term>
      <listitem>
        <para>
          Options to append to the <command>ssh</command> command when executed
          by &repmgr;.
        </para>
        <para>
          We recommend adding <literal>-q</literal> to suppress any superfluous
          SSH chatter such as login banners, and also an explicit
          <option>ConnectTimeout</option> value,
          e.g.:
<programlisting>
ssh_options='-q -o ConnectTimeout=10'</programlisting>
        </para>
      </listitem>
    </varlistentry>

    <varlistentry id="repmgr-conf-pg-bindir" xreflabel="pg_bindir">
      <term><varname>pg_bindir</varname> (<type>string</type>)
        <indexterm>
          <primary><varname>pg_bindir</varname> configuration file parameter</primary>
        </indexterm>
      </term>
      <listitem>
        <para>
          Path to the PostgreSQL binary directory (location of <application>pg_ctl</application>,
          <application>pg_basebackup</application> etc.). Only required
	  if these are not in the system <varname>PATH</varname>.
        </para>
        <tip>
          <para>
            When &repmgr; is executed via <application>SSH</application> (e.g. when running
            <command><link linkend="repmgr-standby-switchover">repmgr standby switchover</link></command>,
            <command><link linkend="repmgr-cluster-matrix">repmgr cluster matrix</link></command> or
            <command><link linkend="repmgr-cluster-crosscheck">repmgr cluster crosscheck</link></command>,
            or if it is executed as cronjob), a login shell will not be used and only the
            default system <varname>PATH</varname> will be set. Therefore it's recommended to set
            <varname>pg_bindir</varname> so &repmgr; can correctly invoke binaries on a remote
            system and avoid potential path issues.
          </para>
        </tip>

        <para>
          Debian/Ubuntu users: you will probably need to  set this to the directory where
          <application>pg_ctl</application> is located, e.g. <filename>/usr/lib/postgresql/9.6/bin/</filename>.
        </para>
        <para>
          <emphasis>NOTE</emphasis>: <varname>pg_bindir</varname> is only used when &repmgr; directly
	  executes PostgreSQL binaries; any user-defined scripts
	  <emphasis>must</emphasis> be specified with the full path.
        </para>

      </listitem>
    </varlistentry>
  </variablelist>

  <tip>
    <simpara>
      See the <ulink url="https://raw.githubusercontent.com/EnterpriseDB/repmgr/master/repmgr.conf.sample">sample repmgr.conf file</ulink>
      for a full and annotated view of all configuration options.
    </simpara>
  </tip>

</sect1>