repmgr/doc/configuration-password-management.xml

<sect1 id="configuration-password-management" xreflabel="password management">

  <title>Password Management</title>
  <indexterm>
    <primary>passwords</primary>
  </indexterm>

  <sect2 id="configuration-password-management-options" xreflabel="password management options">
  <title>Password Management Options</title>
  <indexterm>
    <primary>passwords</primary>
    <secondary>options for managing</secondary>
  </indexterm>

  <para>
    For security purposes it's desirable to protect database access using a password.
  </para>
  <para>
    PostgreSQL has three ways of providing a password:
    <itemizedlist spacing="compact" mark="bullet">

       <listitem>
         <simpara>
           including the password in the <option>conninfo</option> string
           (e.g. &quot;<literal>host=node1 dbname=repmgr user=repmgr password=foo</literal>&quot;)
         </simpara>
       </listitem>

       <listitem>
         <simpara>
           exporting the password as an environment variable (<envar>PGPASSWORD</envar>)
         </simpara>
       </listitem>

       <listitem>
         <simpara>
           storing the password in a dedicated password file
         </simpara>
       </listitem>
    </itemizedlist>
  </para>
  <para>
    We strongly advise against including the password in the <option>conninfo</option> string, as
    this will result in the database password being exposed in various places, including in the
    <filename>repmgr.conf</filename> file, the <literal>repmgr.nodes</literal> table, any output
    generated by &repmgr; which lists the node <option>conninfo</option> strings (e.g.
    <link linkend="repmgr-cluster-show">repmgr cluster show</link>) and in the &repmgr; log file,
    particularly at <option>log_level=DEBUG</option>.
  </para>
  <note>
    <para>
      Currently &repmgr; does not fully support use of the <option>password</option> option in the
      <option>conninfo</option> string.
    </para>
  </note>
  <para>
    Exporting the password as an environment variable (<envar>PGPASSWORD</envar>) is considered
    less insecure, but the PostgreSQL documentation explicitly recommends against doing this:
   <blockquote>
     <attribution><ulink url="https://www.postgresql.org/docs/current/libpq-envars.html">Environment Variables</ulink></attribution>
     <para>
       <envar>PGPASSWORD</envar> behaves the same as the <option>password</option>
       connection parameter. Use of this environment variable
       is not recommended for security reasons, as some operating systems
       allow non-root users to see process environment variables via
       <application>ps</application>; instead consider using a password file.
     </para>
    </blockquote>

  </para>
  <para>
    The most secure option for managing passwords is to use a dedicated password file; see the following
    section for more details.
  </para>

  </sect2>

  <sect2 id="configuration-password-file" xreflabel="password file">
    <title>Using a password file</title>
    <indexterm>
      <primary>pgpass</primary>
    </indexterm>

    <indexterm>
      <primary>.pgpass</primary>
    </indexterm>

    <indexterm>
      <primary>passwords</primary>
      <secondary>using a password file</secondary>
    </indexterm>

    <para>
      The most secure way of storing passwords is in a password file,
      which by default is <filename>~/.pgpass</filename>. This file
      can only be read by the system user who owns the file, and
      PostgreSQL will refuse to use the file unless read/write
      permissions are restricted to the file owner. The password(s)
      contained in the file will not be directly accessed by
      &repmgr; (or any other libpq-based client software such as <application>psql</application>).
    </para>
    <para>
       For full details see the
       <ulink url="https://www.postgresql.org/docs/current/libpq-pgpass.html">PostgreSQL password file documentation</ulink>.
    </para>
    <para>
      For use with &repmgr;, the <filename>~/.pgpass</filename> must two entries for each
      node in the replication cluster: one for the &repmgr; user who accesses the &repmgr; metadatabase,
      and one for replication connections (regardless of whether a dedicated replication user is used).
      The file must be present on each node in the replication cluster.
    </para>
    <para>
      A <filename>~/.pgpass</filename> file for a 3-node cluster where the <literal>repmgr</literal> database user
      is used for both for accessing the  &repmgr; metadatabase and for replication connections would look like this:
      <programlisting>
node1:5432:repmgr:repmgr:foo
node1:5432:replication:repmgr:foo
node2:5432:repmgr:repmgr:foo
node2:5432:replication:repmgr:foo
node3:5432:repmgr:repmgr:foo
node3:5432:replication:repmgr:foo</programlisting>
      If a dedicated replication user (here: <literal>repluser</literal>) is in use, the file would look like this:
      <programlisting>
node1:5432:repmgr:repmgr:foo
node1:5432:replication:repluser:foo
node2:5432:repmgr:repmgr:foo
node2:5432:replication:repluser:foo
node3:5432:repmgr:repmgr:foo
node3:5432:replication:repluser:foo</programlisting>

    </para>
    <note>
      <para>
        It's possible to specify an alternative location for the <filename>~/.pgpass</filename> file, either via
        the environment variable <envar>PGPASSFILE</envar>, or (from PostgreSQL 9.6) using the
        <varname>passfile</varname> parameter in connection strings.
      </para>
      <para>
        If using the <varname>passfile</varname> parameter, it's essential to ensure the file is in the same
        location on all nodes, as when connecting to a remote node, the file referenced is the one on the
        local node.
      </para>
    </note>

  </sect2>

</sect1>