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. "<literal>host=node1 dbname=repmgr user=repmgr password=foo</literal>") 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