diff options
author | Tom Lane <tgl@sss.pgh.pa.us> | 2010-04-21 03:32:53 +0000 |
---|---|---|
committer | Tom Lane <tgl@sss.pgh.pa.us> | 2010-04-21 03:32:53 +0000 |
commit | a2c3931a244b67115a0eac1ee5fde9eb7cb4e42c (patch) | |
tree | 29ce8f4c20563cde96048a4e562b2456a159aa28 /doc/src | |
parent | a3c6d105752c28dbd19d0558733a2157e6ab55e0 (diff) | |
download | postgresql-a2c3931a244b67115a0eac1ee5fde9eb7cb4e42c.tar.gz postgresql-a2c3931a244b67115a0eac1ee5fde9eb7cb4e42c.zip |
Fix pg_hba.conf matching so that replication connections only match records
with database = replication. The previous coding would allow them to match
ordinary records too, but that seems like a recipe for security breaches.
Improve the messages associated with no-such-pg_hba.conf entry to report
replication connections as such, since that's now a critical aspect of
whether the connection matches. Make some cursory improvements in the related
documentation, too.
Diffstat (limited to 'doc/src')
-rw-r--r-- | doc/src/sgml/client-auth.sgml | 18 | ||||
-rw-r--r-- | doc/src/sgml/high-availability.sgml | 45 | ||||
-rw-r--r-- | doc/src/sgml/recovery-config.sgml | 45 |
3 files changed, 58 insertions, 50 deletions
diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml index 38b13954ea5..d2f30a47c4e 100644 --- a/doc/src/sgml/client-auth.sgml +++ b/doc/src/sgml/client-auth.sgml @@ -1,4 +1,4 @@ -<!-- $PostgreSQL: pgsql/doc/src/sgml/client-auth.sgml,v 1.136 2010/04/03 07:22:53 petere Exp $ --> +<!-- $PostgreSQL: pgsql/doc/src/sgml/client-auth.sgml,v 1.137 2010/04/21 03:32:53 tgl Exp $ --> <chapter id="client-authentication"> <title>Client Authentication</title> @@ -75,13 +75,14 @@ <para> The general format of the <filename>pg_hba.conf</filename> file is a set of records, one per line. Blank lines are ignored, as is any - text after the <literal>#</literal> comment character. A record is made + text after the <literal>#</literal> comment character. + Records cannot be continued across lines. + A record is made up of a number of fields which are separated by spaces and/or tabs. Fields can contain white space if the field value is quoted. - Quoting one of the keywords in database or username field (e.g "all" - or "replication") makes the name lose its special character, and just - match a database or username with that name. Records cannot be - continued across lines. + Quoting one of the keywords in a database or username field (e.g., + <literal>all</> or <literal>replication</>) makes the word lose its special + character, and just match a database or user with that name. </para> <para> @@ -185,7 +186,8 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable> name as the requested database. (<literal>samegroup</> is an obsolete but still accepted spelling of <literal>samerole</>.) The value <literal>replication</> specifies that the record - matches if streaming replication is requested. + matches if a replication connection is requested (note that + replication connections do not specify any particular database). Otherwise, this is the name of a specific <productname>PostgreSQL</productname> database. Multiple database names can be supplied by separating them with @@ -241,7 +243,7 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable> Typical examples of a <replaceable>CIDR-address</replaceable> are <literal>172.20.143.89/32</literal> for a single host, or <literal>172.20.143.0/24</literal> for a small network, or - <literal>10.6.0.0/16</literal> for a larger one. + <literal>10.6.0.0/16</literal> for a larger one. <literal>0.0.0.0/0</literal> (<quote>all balls</>) represents all addresses. To specify a single host, use a CIDR mask of 32 for IPv4 or 128 for IPv6. In a network address, do not omit trailing zeroes. diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml index d2a8ea77998..766d223bd2b 100644 --- a/doc/src/sgml/high-availability.sgml +++ b/doc/src/sgml/high-availability.sgml @@ -1,4 +1,4 @@ -<!-- $PostgreSQL: pgsql/doc/src/sgml/high-availability.sgml,v 1.61 2010/04/20 11:15:06 rhaas Exp $ --> +<!-- $PostgreSQL: pgsql/doc/src/sgml/high-availability.sgml,v 1.62 2010/04/21 03:32:53 tgl Exp $ --> <chapter id="high-availability"> <title>High Availability, Load Balancing, and Replication</title> @@ -617,7 +617,7 @@ protocol to make nodes agree on a serializable transactional order. </sect2> <sect2 id="preparing-master-for-standby"> - <title>Preparing Master for Standby Servers</title> + <title>Preparing the Master for Standby Servers</title> <para> Set up continuous archiving on the primary to an archive directory @@ -629,9 +629,13 @@ protocol to make nodes agree on a serializable transactional order. </para> <para> - If you want to use streaming replication, set up authentication to allow - streaming replication connections and set <varname>max_wal_senders</> in - the configuration file of the primary server. + If you want to use streaming replication, set up authentication on the + primary server to allow replication connections from the standby + server(s); that is, provide a suitable entry or entries in + <filename>pg_hba.conf</> with the database field set to + <literal>replication</>. Also ensure <varname>max_wal_senders</> is set + to a sufficiently large value in the configuration file of the primary + server. </para> <para> @@ -641,7 +645,7 @@ protocol to make nodes agree on a serializable transactional order. </sect2> <sect2 id="standby-server-setup"> - <title>Setting up the standby server</title> + <title>Setting Up a Standby Server</title> <para> To set up the standby server, restore the base backup taken from primary @@ -656,7 +660,7 @@ protocol to make nodes agree on a serializable transactional order. <para> Do not use pg_standby or similar tools with the built-in standby mode described here. <varname>restore_command</> should return immediately - if the file does not exist, the server will retry the command again if + if the file does not exist; the server will retry the command again if necessary. See <xref linkend="log-shipping-alternative"> for using tools like pg_standby. </para> @@ -776,22 +780,20 @@ trigger_file = '/path/to/trigger_file' <sect3 id="streaming-replication-authentication"> <title>Authentication</title> <para> - It is very important that the access privilege for replication be setup - properly so that only trusted users can read the WAL stream, because it is - easy to extract privileged information from it. + It is very important that the access privileges for replication be set up + so that only trusted users can read the WAL stream, because it is + easy to extract privileged information from it. Standby servers must + authenticate to the primary as a superuser account. + So a role with the <literal>SUPERUSER</> and <literal>LOGIN</> + privileges needs to be created on the primary. </para> <para> - Only the superuser is allowed to connect to the primary as the replication - standby. So a role with the <literal>SUPERUSER</> and <literal>LOGIN</> - privileges needs to be created in the primary. - </para> - <para> - Client authentication for replication is controlled by the + Client authentication for replication is controlled by a <filename>pg_hba.conf</> record specifying <literal>replication</> in the <replaceable>database</> field. For example, if the standby is running on host IP <literal>192.168.1.100</> and the superuser's name for replication is <literal>foo</>, the administrator can add the following line to the - <filename>pg_hba.conf</> file on the primary. + <filename>pg_hba.conf</> file on the primary: <programlisting> # Allow the user "foo" from host 192.168.1.100 to connect to the primary @@ -809,18 +811,13 @@ host replication foo 192.168.1.100/32 md5 port <literal>5432</literal>, the superuser's name for replication is <literal>foo</>, and the password is <literal>foopass</>, the administrator can add the following line to the <filename>recovery.conf</> file on the - standby. + standby: <programlisting> # The standby connects to the primary that is running on host 192.168.1.50 # and port 5432 as the user "foo" whose password is "foopass". primary_conninfo = 'host=192.168.1.50 port=5432 user=foo password=foopass' </programlisting> - - You do not need to specify <literal>database=replication</> in the - <varname>primary_conninfo</varname>. The required option will be added - automatically. If you mention the database parameter at all within - <varname>primary_conninfo</varname> then a FATAL error will be raised. </para> </sect3> @@ -1959,7 +1956,7 @@ mv /tmp/pg_control /path/to/backup/data/global <filename>pg_control</> contains the location where WAL replay will begin after restoring from the backup; backing it up first ensures that it points to the last restartpoint when the backup started, not - some later restartpoint that happened while files were copied to the + some later restartpoint that happened while files were copied to the backup. </para> </listitem> diff --git a/doc/src/sgml/recovery-config.sgml b/doc/src/sgml/recovery-config.sgml index 85d3b7eb3fb..58fa5b0b107 100644 --- a/doc/src/sgml/recovery-config.sgml +++ b/doc/src/sgml/recovery-config.sgml @@ -1,4 +1,4 @@ -<!-- $PostgreSQL: pgsql/doc/src/sgml/recovery-config.sgml,v 2.4 2010/04/07 10:58:49 heikki Exp $ --> +<!-- $PostgreSQL: pgsql/doc/src/sgml/recovery-config.sgml,v 2.5 2010/04/21 03:32:53 tgl Exp $ --> <chapter Id="recovery-config"> <title>Recovery Configuration</title> @@ -10,12 +10,10 @@ </indexterm> <para> - This chapter describes the settings available in - <filename>recovery.conf</> file. They apply only for the duration of - the recovery. (A sample file, <filename>share/recovery.conf.sample</>, - exists in the installation's <filename>share/</> directory.) They must - be reset for any subsequent recovery you wish to perform. They cannot - be changed once recovery has begun. + This chapter describes the settings available in the + <filename>recovery.conf</> file. They apply only for the duration of the + recovery. They must be reset for any subsequent recovery you wish to + perform. They cannot be changed once recovery has begun. </para> <para> @@ -26,6 +24,11 @@ value, write two quotes (<literal>''</>). </para> + <para> + A sample file, <filename>share/recovery.conf.sample</>, + is provided in the installation's <filename>share/</> directory. + </para> + <sect1 id="archive-recovery-settings"> <title>Archive recovery settings</title> @@ -208,9 +211,10 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows <para> Specifies whether to start the <productname>PostgreSQL</> server as a standby. If this parameter is <literal>on</>, the server will - not end recovery when the end of archived WAL is reached, but - will keep trying to continue recovery using <varname>restore_command</> - and by connecting to the primary server as specified by the + not stop recovery when the end of archived WAL is reached, but + will keep trying to continue recovery by fetching new WAL segments + using <varname>restore_command</> + and/or by connecting to the primary server as specified by the <varname>primary_conninfo</> setting. </para> </listitem> @@ -229,14 +233,19 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows defaults are used. </para> <para> - The built-in replication requires that a host name (or host address) - or port number which the primary server listens on be - specified in this string. Also ensure that a role with - the <literal>SUPERUSER</> and <literal>LOGIN</> privileges on the - primary is set (see - <xref linkend="streaming-replication-authentication">). Note that - the password needs to be set if the primary demands password - authentication. + The connection string should specify the host name (or address) + of the primary server, as well as the port number if it is not + the same as the standby server's default. + Also specify a user name corresponding to a role that has the + <literal>SUPERUSER</> and <literal>LOGIN</> privileges on the + primary (see + <xref linkend="streaming-replication-authentication">). + A password needs to be provided too, if the primary demands password + authentication. (The password can be provided either in + the <varname>primary_conninfo</varname> string or in a separate + <filename>~/.pgpass</> file on the standby server.) + Do not specify a database name in the + <varname>primary_conninfo</varname> string. </para> <para> This setting has no effect if <varname>standby_mode</> is <literal>off</>. |