From 192f8ff3c2de79a2fa8fa31e341a97da09907dbf Mon Sep 17 00:00:00 2001 From: Ian Barwick Date: Wed, 18 Mar 2020 15:16:00 +0900 Subject: [PATCH] doc: add section about password management This is briefly covered in the section about cloning, but is hard to find. --- doc/configuration-password-management.xml | 135 ++++++++++++++++++++++ doc/configuration.xml | 1 + doc/filelist.xml | 1 + 3 files changed, 137 insertions(+) create mode 100644 doc/configuration-password-management.xml diff --git a/doc/configuration-password-management.xml b/doc/configuration-password-management.xml new file mode 100644 index 00000000..4a6a2c0b --- /dev/null +++ b/doc/configuration-password-management.xml @@ -0,0 +1,135 @@ + + + Password Management + + passwords + + + + Password Management Options + + passwords + options for managing + + + + For security purposes it's desirable to protect database access using a password. + + + PostgreSQL has three ways of providing a password: + + + + + including the password in the string + (e.g. "host=node1 dbname=repmgr user=repmgr password=foo") + + + + + + exporting the password as an environment variable (PGPASSWORD) + + + + + + storing the password in a dedicated password file + + + + + + We strongly advise against including the password in the string, as + this will result in the database password being exposed in various places, including in the + repmgr.conf file, the repmgr.nodes table, any output + generated by &repmgr; which lists the node strings (e.g. + repmgr cluster show) and in the &repmgr; log file, + particularly at . + + + + Currently &repmgr; does not fully support use of the option in the + string. + + + + Exporting the password as an environment variable (PGPASSWORD) is considered + less insecure, but the PostgreSQL documentation explicitly recommends against doing this: +
+ Environment Variables + + PGPASSWORD behaves the same as the + 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 + ps; instead consider using a password file. + +
+ + + + The most secure option for managing passwords is to use a dedicated password file; see the following + section for more details. + + + + + + Using a password file + + pgpass + + + + .pgpass + + + + passwords + using a password file + + + + The most secure way of storing passwords is in a password file, + which by default is ~/.pgpass. 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 psql). + + + For full details see the + PostgreSQL password file documentation. + + + For use with &repmgr;, the ~/.pgpass 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. + + + A ~/.pgpass file for a 3-node cluster where the repmgr database user + is used for both for accessing the &repmgr; metadatabase and for replication connections would look like this: + +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 + If a dedicated replication user (here: repluser) is in use, the file would look like this: + +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 + + + + + + diff --git a/doc/configuration.xml b/doc/configuration.xml index fe94919d..1abe8982 100644 --- a/doc/configuration.xml +++ b/doc/configuration.xml @@ -319,5 +319,6 @@ &configuration-file-log-settings; &configuration-file-service-commands; &configuration-permissions; + &configuration-password-management; diff --git a/doc/filelist.xml b/doc/filelist.xml index 2bd25272..c948addb 100644 --- a/doc/filelist.xml +++ b/doc/filelist.xml @@ -22,6 +22,7 @@ +