1<sect1 id="configuration-password-management" xreflabel="password management">
2
3  <title>Password Management</title>
4  <indexterm>
5    <primary>passwords</primary>
6  </indexterm>
7
8  <sect2 id="configuration-password-management-options" xreflabel="password management options">
9  <title>Password Management Options</title>
10  <indexterm>
11    <primary>passwords</primary>
12    <secondary>options for managing</secondary>
13  </indexterm>
14
15  <para>
16    For security purposes it's desirable to protect database access using a password.
17  </para>
18  <para>
19    PostgreSQL has three ways of providing a password:
20    <itemizedlist spacing="compact" mark="bullet">
21
22       <listitem>
23         <simpara>
24           including the password in the <option>conninfo</option> string
25           (e.g. &quot;<literal>host=node1 dbname=repmgr user=repmgr password=foo</literal>&quot;)
26         </simpara>
27       </listitem>
28
29       <listitem>
30         <simpara>
31           exporting the password as an environment variable (<envar>PGPASSWORD</envar>)
32         </simpara>
33       </listitem>
34
35       <listitem>
36         <simpara>
37           storing the password in a dedicated password file
38         </simpara>
39       </listitem>
40    </itemizedlist>
41  </para>
42  <para>
43    We strongly advise against including the password in the <option>conninfo</option> string, as
44    this will result in the database password being exposed in various places, including in the
45    <filename>repmgr.conf</filename> file, the <literal>repmgr.nodes</literal> table, any output
46    generated by &repmgr; which lists the node <option>conninfo</option> strings (e.g.
47    <link linkend="repmgr-cluster-show">repmgr cluster show</link>) and in the &repmgr; log file,
48    particularly at <option>log_level=DEBUG</option>.
49  </para>
50  <note>
51    <para>
52      Currently &repmgr; does not fully support use of the <option>password</option> option in the
53      <option>conninfo</option> string.
54    </para>
55  </note>
56  <para>
57    Exporting the password as an environment variable (<envar>PGPASSWORD</envar>) is considered
58    less insecure, but the PostgreSQL documentation explicitly recommends against doing this:
59   <blockquote>
60     <attribution><ulink url="https://www.postgresql.org/docs/current/libpq-envars.html">Environment Variables</ulink></attribution>
61     <para>
62       <envar>PGPASSWORD</envar> behaves the same as the <option>password</option>
63       connection parameter. Use of this environment variable
64       is not recommended for security reasons, as some operating systems
65       allow non-root users to see process environment variables via
66       <application>ps</application>; instead consider using a password file.
67     </para>
68    </blockquote>
69
70  </para>
71  <para>
72    The most secure option for managing passwords is to use a dedicated password file; see the following
73    section for more details.
74  </para>
75
76  </sect2>
77
78  <sect2 id="configuration-password-file" xreflabel="password file">
79    <title>Using a password file</title>
80    <indexterm>
81      <primary>pgpass</primary>
82    </indexterm>
83
84    <indexterm>
85      <primary>.pgpass</primary>
86    </indexterm>
87
88    <indexterm>
89      <primary>passwords</primary>
90      <secondary>using a password file</secondary>
91    </indexterm>
92
93    <para>
94      The most secure way of storing passwords is in a password file,
95      which by default is <filename>~/.pgpass</filename>. This file
96      can only be read by the system user who owns the file, and
97      PostgreSQL will refuse to use the file unless read/write
98      permissions are restricted to the file owner. The password(s)
99      contained in the file will not be directly accessed by
100      &repmgr; (or any other libpq-based client software such as <application>psql</application>).
101    </para>
102    <para>
103       For full details see the
104       <ulink url="https://www.postgresql.org/docs/current/libpq-pgpass.html">PostgreSQL password file documentation</ulink>.
105    </para>
106    <para>
107      For use with &repmgr;, the <filename>~/.pgpass</filename> must two entries for each
108      node in the replication cluster: one for the &repmgr; user who accesses the &repmgr; metadatabase,
109      and one for replication connections (regardless of whether a dedicated replication user is used).
110      The file must be present on each node in the replication cluster.
111    </para>
112    <para>
113      A <filename>~/.pgpass</filename> file for a 3-node cluster where the <literal>repmgr</literal> database user
114      is used for both for accessing the  &repmgr; metadatabase and for replication connections would look like this:
115      <programlisting>
116node1:5432:repmgr:repmgr:foo
117node1:5432:replication:repmgr:foo
118node2:5432:repmgr:repmgr:foo
119node2:5432:replication:repmgr:foo
120node3:5432:repmgr:repmgr:foo
121node3:5432:replication:repmgr:foo</programlisting>
122      If a dedicated replication user (here: <literal>repluser</literal>) is in use, the file would look like this:
123      <programlisting>
124node1:5432:repmgr:repmgr:foo
125node1:5432:replication:repluser:foo
126node2:5432:repmgr:repmgr:foo
127node2:5432:replication:repluser:foo
128node3:5432:repmgr:repmgr:foo
129node3:5432:replication:repluser:foo</programlisting>
130      If you are planning to use the <option>-S</option>/<option>--superuser</option> option,
131      there must also be an entry enabling the superuser to connect to the &repmgr; database.
132      Assuming the superuser is <literal>postgres</literal>, the file would look like this:
133        <programlisting>
134node1:5432:repmgr:repmgr:foo
135node1:5432:repmgr:postgres:foo
136node1:5432:replication:repluser:foo
137node2:5432:repmgr:repmgr:foo
138node2:5432:repmgr:postgres:foo
139node2:5432:replication:repluser:foo
140node3:5432:repmgr:repmgr:foo
141node3:5432:repmgr:postgres:foo
142node3:5432:replication:repluser:foo</programlisting>
143    </para>
144
145    <para>
146      The <filename>~/.pgpass</filename> file can be simplified with the use of wildcards if
147      there is no requirement to restrict provision of passwords to particular hosts, ports
148      or databases. The preceding file could then be formatted like this:
149        <programlisting>
150*:*:*:repmgr:foo
151*:*:*:postgres:foo
152</programlisting>
153    </para>
154
155    <note>
156      <para>
157        It's possible to specify an alternative location for the <filename>~/.pgpass</filename> file, either via
158        the environment variable <envar>PGPASSFILE</envar>, or (from PostgreSQL 9.6) using the
159        <varname>passfile</varname> parameter in connection strings.
160      </para>
161      <para>
162        If using the <varname>passfile</varname> parameter, it's essential to ensure the file is in the same
163        location on all nodes, as when connecting to a remote node, the file referenced is the one on the
164        local node.
165      </para>
166      <para>
167        Additionally, you <emphasis>must</emphasis> specify the passfile location in <filename>repmgr.conf</filename>
168        with the <option>passfile</option> option so &repmgr; can write the correct path when creating the
169        <option>primary_conninfo</option> parameter for replication configuration on standbys.
170      </para>
171    </note>
172
173  </sect2>
174
175</sect1>
176