<!--
-$PostgreSQL: pgsql/doc/src/sgml/client-auth.sgml,v 1.68 2004/11/15 06:32:13 neilc Exp $
+$PostgreSQL: pgsql/doc/src/sgml/client-auth.sgml,v 1.69 2004/12/26 23:06:56 tgl Exp $
-->
<chapter id="client-authentication">
</indexterm>
<para>
- Client authentication is controlled by the file
- <filename>pg_hba.conf</filename> in the data directory, e.g.,
- <filename>/usr/local/pgsql/data/pg_hba.conf</filename>.
+ Client authentication is controlled by a configuration file,
+ which traditionally is named
+ <filename>pg_hba.conf</filename> and is stored in the database
+ cluster's data directory.
(<acronym>HBA</> stands for host-based authentication.) A default
<filename>pg_hba.conf</filename> file is installed when the data
- directory is initialized by <command>initdb</command>.
+ directory is initialized by <command>initdb</command>. It is
+ possible to place the authentication configuration file elsewhere,
+ however; see the <xref linkend="guc-hba-file"> configuration parameter.
</para>
<para>
<term><literal>hostnossl</literal></term>
<listitem>
<para>
- This record is similar to <literal>hostssl</> but with the
- opposite logic: it only matches connection attempts made over
+ This record type has the opposite logic to <literal>hostssl</>:
+ it only matches connection attempts made over
TCP/IP that do not use <acronym>SSL</acronym>.
</para>
</listitem>
The value <literal>sameuser</> specifies that the record
matches if the requested database has the same name as the
requested user. The value <literal>samegroup</> specifies that
- the requested user must a member of the group with the same
+ the requested user must be a member of the group with the same
name as the requested database. Otherwise, this is the name of
a specific <productname>PostgreSQL</productname> database.
Multiple database names can be supplied by separating them with
<term><replaceable>CIDR-address</replaceable></term>
<listitem>
<para>
- Specifies the client machine IP addresses that this record
+ Specifies the client machine IP address range that this record
matches. It contains an IP address in standard dotted decimal
notation and a CIDR mask length. (IP addresses can only be
- specified numerically, not as domain or host names.) For example,
- an IPv4 CIDR mask of 8 is equivalent to an IP mask of 255.0.0.0,
- an IPv6 CIDR mask of 64 is equivalent to an IP mask of
- ffff:ffff:ffff:ffff::. A IPv4 CIDR mask of 32 is used for single
- hosts.
+ specified numerically, not as domain or host names.) The mask
+ length indicates the number of high-order bits of the client
+ IP address that must match. Bits to the right of this must
+ be zero in the given IP address.
+ There must not be any white space between the IP address, the
+ <literal>/</literal>, and the CIDR mask length.
</para>
<para>
- A typical CIDR address is <literal>172.20.143.89/32</literal>.
- There should be no white space between the IP address, the
- <literal>/</literal>, and the CIDR mask length.
+ A typical <replaceable>CIDR-address</replaceable> is
+ <literal>172.20.143.89/32</literal> for a single host, or
+ <literal>172.20.143.0/24</literal> for a network.
+ To specify a single host, use a CIDR mask of 32 for IPv4 or
+ 128 for IPv6.
</para>
<para>
</para>
<para>
- These fields only apply to <literal>host</literal>,
+ This field only applies to <literal>host</literal>,
<literal>hostssl</literal>, and <literal>hostnossl</> records.
</para>
</listitem>
<varlistentry>
<term><replaceable>IP-address</replaceable></term>
- <term><replaceable>IP-masklen</replaceable></term>
+ <term><replaceable>IP-mask</replaceable></term>
<listitem>
<para>
- This may be used as an alternative to the
+ These fields may be used as an alternative to the
<replaceable>CIDR-address</replaceable> notation. Instead of
specifying the mask length, the actual mask is specified in a
- separate column. For example, 255.0.0.0 represents a IPv4 CIDR
- mask length of 8, and 255.255.255.255 represents a CIDR mask
- length of 32. The same matching logic is used as for a dotted
- notation <replaceable>IP-mask</replaceable>.
+ separate column. For example, <literal>255.0.0.0</> represents an IPv4
+ CIDR mask length of 8, and <literal>255.255.255.255</> represents a
+ CIDR mask length of 32.
</para>
<para>
- This field only applies to <literal>host</literal>,
+ These fields only apply to <literal>host</literal>,
<literal>hostssl</literal>, and <literal>hostnossl</> records.
</para>
</listitem>
<term><literal>trust</></term>
<listitem>
<para>
- The connection is allowed unconditionally. This method
+ Allow the connection unconditionally. This method
allows anyone that can connect to the
<productname>PostgreSQL</productname> database server to login as
any <productname>PostgreSQL</productname> user they like,
<term><literal>reject</></term>
<listitem>
<para>
- The connection is rejected unconditionally. This is useful for
+ Reject the connection unconditionally. This is useful for
<quote>filtering out</> certain hosts from a group.
</para>
</listitem>
<term><literal>md5</></term>
<listitem>
<para>
- Requires the client to supply an MD5 encrypted password for
- authentication. This is the only method that allows encrypted
- passwords to be stored in <structname>pg_shadow</structname>.
+ Require the client to supply an MD5-encrypted password for
+ authentication.
See <xref linkend="auth-password"> for details.
</para>
</listitem>
<term><literal>crypt</></term>
<listitem>
<para>
- Like the <literal>md5</literal> method but uses older <function>crypt()</>
- encryption, which is needed for pre-7.2 clients.
- <literal>md5</literal> is preferred for 7.2 and later clients.
+ Require the client to supply a <function>crypt()</>-encrypted
+ password for authentication.
+ <literal>md5</literal> is preferred for 7.2 and later clients,
+ but pre-7.2 clients only support <literal>crypt</>.
See <xref linkend="auth-password"> for details.
</para>
</listitem>
<term><literal>password</></term>
<listitem>
<para>
- Same as <literal>md5</>, but the password is sent in clear text over the
- network. This should not be used on untrusted networks.
+ Require the client to supply an unencrypted password for
+ authentication.
+ Since the password is sent in clear text over the
+ network, this should not be used on untrusted networks.
See <xref linkend="auth-password"> for details.
</para>
</listitem>
<term><literal>krb4</></term>
<listitem>
<para>
- Kerberos V4 is used to authenticate the user. This is only
+ Use Kerberos V4 to authenticate the user. This is only
available for TCP/IP connections. See <xref
linkend="kerberos-auth"> for details.
</para>
<term><literal>krb5</></term>
<listitem>
<para>
- Kerberos V5 is used to authenticate the user. This is only
+ Use Kerberos V5 to authenticate the user. This is only
available for TCP/IP connections. See <xref
linkend="kerberos-auth"> for details.
</para>
operating system) and check if the user is allowed to
connect as the requested database user by consulting the map
specified after the <literal>ident</literal> key word.
- </para>
-
- <para>
- If you use the map <literal>sameuser</literal>, the user
- names are required to be identical. If not, the map name is
- looked up in the file <filename>pg_ident.conf</filename>
- in the same directory as <filename>pg_hba.conf</filename>.
- The connection is accepted if that file contains an
- entry for this map name with the operating-system user name
- and the requested <productname>PostgreSQL</productname> user
- name.
- </para>
-
- <para>
- For local connections, this only works on machines that
- support Unix-domain socket credentials (currently
- <systemitem class=osname>Linux</>, <systemitem
- class=osname>FreeBSD</>, <systemitem class=osname>NetBSD</>,
- <systemitem class=osname>OpenBSD</>, and
- <systemitem class=osname>BSD/OS</>).
- </para>
-
- <para>
- See <xref linkend="auth-ident"> below for details.
+ See <xref linkend="auth-ident"> for details.
</para>
</listitem>
</varlistentry>
<listitem>
<para>
The meaning of this optional field depends on the chosen
- authentication method and is described in the next section.
+ authentication method. Details appear below.
</para>
</listitem>
</varlistentry>
range of allowed client IP addresses.
</para>
- <important>
- <para>
- Do not prevent the superuser from accessing the <literal>template1</literal>
- database. Various utility commands need access to <literal>template1</literal>.
- </para>
- </important>
-
<para>
The <filename>pg_hba.conf</filename> file is read on start-up and when
the main server process (<command>postmaster</>) receives a
</para>
<para>
- An example of a <filename>pg_hba.conf</filename> file is shown in
+ Some examples of <filename>pg_hba.conf</filename> entries are shown in
<xref linkend="example-pg-hba.conf">. See the next section for details on the
different authentication methods.
</para>
<example id="example-pg-hba.conf">
- <title>An example <filename>pg_hba.conf</filename> file</title>
+ <title>Example <filename>pg_hba.conf</filename> entries</title>
<programlisting>
# Allow any user on the local system to connect to any database under
# any user name using Unix-domain sockets (the default for local
# The same as the last line but using a separate netmask column
#
-# TYPE DATABASE USER CIDR-ADDRESS METHOD
+# TYPE DATABASE USER IP-ADDRESS IP-MASK METHOD
host all all 127.0.0.1 255.255.255.255 trust
# Allow any user from any host with IP address 192.168.93.x to connect
# TYPE DATABASE USER CIDR-ADDRESS METHOD
host template1 all 192.168.93.0/24 ident sameuser
-# The same as the last line but using a separate netmask column
-#
-# TYPE DATABASE USER CIDR-ADDRESS METHOD
-host template1 all 192.168.93.0 255.255.255.0 ident sameuser
-
# Allow a user from host 192.168.12.10 to connect to database
# "template1" if the user's password is correctly supplied.
#
# In the absence of preceding "host" lines, these two lines will
# reject all connection from 192.168.54.1 (since that entry will be
-# matched first), but allow Kerberos V connections from anywhere else
+# matched first), but allow Kerberos 5 connections from anywhere else
# on the Internet. The zero mask means that no bits of the host IP
# address are considered so it matches any host.
#
<sect1 id="auth-methods">
<title>Authentication methods</title>
<para>
- The following describes the authentication methods in more detail.
+ The following subsections describe the authentication methods in more detail.
</para>
<sect2 id="auth-trust">
<productname>PostgreSQL</productname> assumes that anyone who can
connect to the server is authorized to access the database with
whatever database user they specify (including the database superuser).
- Of course, restrictions placed in the <literal>user</> column still apply.
- This method should only be used when there is adequate operating system-level
- protection on connections to the server.
+ Of course, restrictions made in the <literal>database</> and
+ <literal>user</> columns still apply.
+ This method should only be used when there is adequate
+ operating-system-level protection on connections to the server.
</para>
<para>
The password-based authentication methods are <literal>md5</>,
<literal>crypt</>, and <literal>password</>. These methods operate
similarly except for the way that the password is sent across the
- connection. If you are at all concerned about password
+ connection. But only <literal>md5</> supports encrypted
+ passwords stored in <structname>pg_shadow</structname>;
+ the other two require unencrypted passwords to be stored there.
+ </para>
+
+ <para>
+ If you are at all concerned about password
<quote>sniffing</> attacks then <literal>md5</> is preferred, with
<literal>crypt</> a second choice if you must support pre-7.2
clients. Plain <literal>password</> should especially be avoided for
<productname>PostgreSQL</productname> database passwords are
separate from operating system user passwords. The password for
each database user is stored in the <literal>pg_shadow</> system
- catalog table. Passwords can be managed with the SQL
- commands <command>CREATE USER</command> and <command>ALTER
- USER</command>, e.g., <userinput>CREATE USER foo WITH PASSWORD
- 'secret';</userinput>. By default, that is, if no password has
- been set up, the stored password is null and
- password authentication will always fail for that user.
- </para>
-
- <para>
- To restrict the set of users that are allowed to connect to
- certain databases, list the users in the <replaceable>user</>
- column of <filename>pg_hba.conf</filename>, as explained in the
- previous section.
+ catalog table. Passwords can be managed with the SQL commands
+ <xref linkend="sql-createuser" endterm="sql-createuser-title"> and
+ <xref linkend="sql-alteruser" endterm="sql-alteruser-title">,
+ e.g., <userinput>CREATE USER foo WITH PASSWORD 'secret';</userinput>.
+ By default, that is, if no password has been set up, the stored password
+ is null and password authentication will always fail for that user.
</para>
</sect2>
<productname>Kerberos</productname> is an industry-standard secure
authentication system suitable for distributed computing over a public
network. A description of the <productname>Kerberos</productname> system
- is far beyond the scope of this document; in all generality it can be
+ is far beyond the scope of this document; in full generality it can be
quite complex (yet powerful). The <ulink
url="http://www.nrl.navy.mil/CCS/people/kenh/kerberos-faq.html">Kerberos
<acronym>FAQ</></ulink> or <ulink url="ftp://athena-dist.mit.edu">MIT
<para>
Make sure that your server key file is readable (and preferably
only readable) by the <productname>PostgreSQL</productname> server
- account. (See also <xref linkend="postgres-user">). The location
+ account. (See also <xref linkend="postgres-user">.) The location
of the key file is specified by the <xref
- linkend="guc-krb-server-keyfile"> run-time configuration
+ linkend="guc-krb-server-keyfile"> configuration
parameter. (See also <xref linkend="runtime-config">.) The default
is <filename>/etc/srvtab</> if you are using Kerberos 4 and
<filename>/usr/local/pgsql/etc/krb5.keytab</> (or whichever
</indexterm>
<para>
- The ident authentication method works by inspecting the client's
+ The ident authentication method works by obtaining the client's
operating system user name and determining the allowed database
- user names by using a map file that lists the permitted
- corresponding user name pairs. The determination of the client's
+ user names using a map file that lists the permitted
+ corresponding pairs of names. The determination of the client's
user name is the security-critical point, and it works differently
depending on the connection type.
</para>
<para>
On systems without <symbol>SO_PEERCRED</> requests, ident
authentication is only available for TCP/IP connections. As a
- work around, it is possible to specify the <systemitem
+ work-around, it is possible to specify the <systemitem
class="systemname">localhost</> address <systemitem
class="systemname">127.0.0.1</> and make connections to this
- address.
+ address. This method is trustworthy to the extent that you trust
+ the local ident server.
</para>
</sect3>
- <sect3>
+ <sect3 id="auth-ident-maps">
<title>Ident Maps</title>
<para>
</para>
<para>
- Ident maps
- other than <literal>sameuser</literal> are defined in the file
- <filename>pg_ident.conf</filename><indexterm><primary>pg_ident.conf</primary></indexterm>
- in the data directory, which contains lines of the general form:
+ Ident maps other than <literal>sameuser</literal> are defined in the
+ ident map file, which by default is named
+ <filename>pg_ident.conf</><indexterm><primary>pg_ident.conf</primary></indexterm>
+ and is stored in the
+ cluster's data directory. (It is possible to place the map file
+ elsewhere, however; see the <xref linkend="guc-ident-file">
+ configuration parameter.)
+ The ident map file contains lines of the general form:
<synopsis>
<replaceable>map-name</> <replaceable>ident-username</> <replaceable>database-username</>
</synopsis>
- Comments and whitespace are handled in the usual way. The
+ Comments and whitespace are handled in the same way as in
+ <filename>pg_hba.conf</>. The
<replaceable>map-name</> is an arbitrary name that will be used to
refer to this mapping in <filename>pg_hba.conf</filename>. The other
two fields specify which operating system user is allowed to connect
as which database user. The same <replaceable>map-name</> can be
used repeatedly to specify more user-mappings within a single map.
There is no restriction regarding how many database users a given
- operating system user may correspond to and vice versa.
+ operating system user may correspond to, nor vice versa.
</para>
<para>
</sect2>
<sect2 id="auth-pam">
- <title>PAM Authentication</title>
+ <title>PAM authentication</title>
<indexterm zone="auth-pam">
<primary>PAM</primary>
<literal>password</literal> except that it uses PAM (Pluggable
Authentication Modules) as the authentication mechanism. The
default PAM service name is <literal>postgresql</literal>. You can
- optionally supply you own service name after the <literal>pam</>
- key word in the file <filename>pg_hba.conf</filename>. For more information about PAM, please read
- the <ulink
+ optionally supply your own service name after the <literal>pam</>
+ key word in the file <filename>pg_hba.conf</filename>.
+
For more information about PAM, please read the <ulink
url="http://www.kernel.org/pub/linux/libs/pam/"><productname>Linux-PAM</>
Page</ulink> and the <ulink
url="http://www.sun.com/software/solaris/pam/"><systemitem
<!--
-$PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.298 2004/12/18 18:36:33 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.299 2004/12/26 23:06:56 tgl Exp $
-->
<Chapter Id="runtime">
<Para>
This chapter discusses how to set up and run the database server
- and the interactions with the operating system.
+ and its interactions with the operating system.
</para>
<sect1 id="postgres-user">
</indexterm>
<para>
- As with any other server daemon that is connected to outside world,
+ As with any other server daemon that is accessible to the outside world,
it is advisable to run <productname>PostgreSQL</productname> under a
separate user account. This user account should only own the data
that is managed by the server, and should not be shared with other
<para>
To add a Unix user account to your system, look for a command
<command>useradd</command> or <command>adduser</command>. The user
- name <systemitem>postgres</systemitem> is often used but is by no
- means required.
+ name <systemitem>postgres</systemitem> is often used, and is assumed
+ throughout this book, but you can use another name if you like.
</para>
</sect1>
<para>
Before you can do anything, you must initialize a database storage
area on disk. We call this a <firstterm>database cluster</firstterm>.
- (<acronym>SQL</acronym> uses the term catalog cluster instead.) A
- database cluster is a collection of databases is accessible by a
+ (<acronym>SQL</acronym> uses the term catalog cluster.) A
+ database cluster is a collection of databases that is managed by a
single instance of a running database server. After initialization, a
database cluster will contain a database named
<literal>template1</literal>. As the name suggests, this will be used
as a template for subsequently created databases; it should not be
- used for actual work. (See <xref linkend="managing-databases"> for information
- about creating databases.)
+ used for actual work. (See <xref linkend="managing-databases"> for
+ information about creating new databases within a cluster.)
</para>
<para>
<filename>/var/lib/pgsql/data</filename> are popular. To initialize a
database cluster, use the command <command>initdb</command>,<indexterm><primary>initdb</></> which is
installed with <productname>PostgreSQL</productname>. The desired
- file system location of your database system is indicated by the
+ file system location of your database cluster is indicated by the
<option>-D</option> option, for example
<screen>
<prompt>$</> <userinput>initdb -D /usr/local/pgsql/data</userinput>
<para>
<command>initdb</command> will refuse to run if the data directory
- looks like it it has already been initialized.</para>
+ looks like it has already been initialized.</para>
<para>
Because the data directory contains all the data stored in the
database and even become the database superuser. If you do not
trust other local users, we recommend you use one of
<command>initdb</command>'s <option>-W</option>, <option>--pwprompt</option>
- or <option>--pwfile</option> option to assign a password to the
+ or <option>--pwfile</option> options to assign a password to the
database superuser.<indexterm><primary>password</><secondary>of the
- superuser</></indexterm> After <command>initdb</command>, modify
- the <filename>pg_hba.conf</filename> file to use <literal>md5</> or
- <literal>password</> instead of <literal>trust</> authentication
+ superuser</></indexterm> Also, specify <option>-A md5</> or
+ <option>-A password</> so that the default <literal>trust</> authentication
+ mode is not used; or modify the generated <filename>pg_hba.conf</filename>
+ file after running <command>initdb</command>,
<emphasis>before</> you start the server for the first time. (Other
- approaches include using <literal>ident</literal> authentication or
- file system permissions to restrict connections. See <xref
+ reasonable approaches include using <literal>ident</literal> authentication
+ or file system permissions to restrict connections. See <xref
linkend="client-authentication"> for more information.)
</para>
<para>
The <command>postmaster</command> also takes a number of other
- command line options. For more information, see the reference page
+ command line options. For more information, see the
+ <xref linkend="app-postmaster"> reference page
and <xref linkend="runtime-config"> below.
</para>
<para>
- This shell syntax can get tedious quickly. Therefore the shell
- script wrapper
- <
command>pg_ctl</command><indexterm><primary>pg_ctl</primary></indexterm>
+ This shell syntax can get tedious quickly. Therefore the wrapper
+ program
+ <
xref linkend="app-pg-ctl"><indexterm><primary>pg_ctl</primary></indexterm>
is provided to simplify some tasks. For example:
<programlisting>
pg_ctl start -l logfile
</programlisting>
will start the server in the background and put the output into the
named log file. The <option>-D</option> option has the same meaning
- here as in the <command>postmaster</command>. <command>pg_ctl</command> is also
- capable of stopping the server.
+ here as in the <command>postmaster</command>. <command>pg_ctl</command>
+ is also capable of stopping the server.
</para>
<para>
<para>
All parameter names are case-insensitive. Every parameter takes a
- value of one of the four types: boolean, integer, floating point,
- and string. Boolean values are <literal>ON</literal>,
+ value of one of four types: boolean, integer, floating point,
+ or string. Boolean values may be written as <literal>ON</literal>,
<literal>OFF</literal>, <literal>TRUE</literal>,
<literal>FALSE</literal>, <literal>YES</literal>,
<literal>NO</literal>, <literal>1</literal>, <literal>0</literal>
- (case-insensitive) or any non-ambiguous prefix of these.
+ (all case-insensitive) or any unambiguous prefix of these.
</para>
<para>
One way to set these parameters is to edit the file
- <filename>postgresql.conf</filename><indexterm><primary>postgresql.conf</></>
- in the data directory. (A default file is installed there.) An
- example of what this file might look like is:
+ <filename>postgresql.conf</><indexterm><primary>postgresql.conf</></>,
+ which is normally kept in the data directory. (<command>initdb</>
+ installs a default copy there.) An example of what this file might look
+ like is:
<programlisting>
# This is a comment
log_connections = yes
value is optional. Whitespace is insignificant and blank lines are
ignored. Hash marks (<literal>#</literal>) introduce comments
anywhere. Parameter values that are not simple identifiers or
- numbers should be single-quoted.
+ numbers must be single-quoted.
</para>
<para>
postmaster -c log_connections=yes -c log_destination='syslog'
</programlisting>
Command-line options override any conflicting settings in
- <filename>postgresql.conf</filename>.
+ <filename>postgresql.conf</filename>. Note that this means you won't
+ be able to change the value on-the-fly by editing
+ <filename>postgresql.conf</filename>, so while the command-line
+ method may be convenient, it can cost you flexibility later.
</para>
<para>
- Occasionally it is also useful to give a command line option to
+ Occasionally it is useful to give a command line option to
one particular session only. The environment variable
<envar>PGOPTIONS</envar> can be used for this purpose on the
client side:
</programlisting>
(This works for any <application>libpq</>-based client application, not
just <application>psql</application>.) Note that this won't work for
- parameters that are fixed when the server is started, nor for
- parameters that require superuser permissions to change (not even
- if you are logging in as superuser).
+ parameters that are fixed when the server is started or that must be
+ specified in <filename>postgresql.conf</filename>.
</para>
<para>
Furthermore, it is possible to assign a set of option settings to
a user or a database. Whenever a session is started, the default
settings for the user and database involved are loaded. The
- commands <xref linkend="sql-alterdatabase"
- endterm="sql-alterdatabase-title"> and <xref
- linkend="sql-alteruser" endterm="sql-alteruser-title">,
+ commands <xref linkend="sql-alteruser" endterm="sql-alteruser-title">
+ and <xref linkend="sql-alterdatabase" endterm="sql-alterdatabase-title">,
respectively, are used to configure these settings. Per-database
settings override anything received from the
<command>postmaster</command> command-line or the configuration
<command>SET</command>: for example, if they control behavior that
cannot reasonably be changed without restarting
<productname>PostgreSQL</productname>. Also, some parameters can
- be modified via <command>SET</command> by superusers, but not by
- ordinary users.
+ be modified via <command>SET</command> or <command>ALTER</> by superusers,
+ but not by ordinary users.
</para>
<para>
<sect2 id="runtime-config-file-locations">
<title>File Locations</title>
+ <para>
+ In addition to the <filename>postgresql.conf</filename> file
+ already mentioned, <productname>PostgreSQL</productname> uses
+ two other manually-edited configuration files, which control
+ client authentication (their use is discussed in <xref
+ linkend="client-authentication">).
+ By default, all three configuration files are stored
+ in the database cluster's data directory. The options described
+ in this subsection allow the configuration files to be placed elsewhere.
+ (Doing so can ease administration. In particular it is often
+ easier to ensure that the configuration files are properly backed-up
+ when they are kept separate.)
+ </para>
+
<variablelist>
<varlistentry id="guc-data-directory" xreflabel="data_directory">
<term><varname>data_directory</varname> (<type>string</type>)</term>
</indexterm>
<listitem>
<para>
- Specifies the configuration file for host-based authentication.
+ Specifies the configuration file for host-based authentication
+ (customarily called <filename>pg_hba.conf</>).
This option can only be set at server start.
</para>
</listitem>
<listitem>
<para>
Specifies the configuration file for
- <application>ident</> authentication.
+ <application>ident</> authentication
+ (customarily called <filename>pg_ident.conf</>).
This option can only be set at server start.
</para>
</listitem>
</indexterm>
<listitem>
<para>
- Specifies that the <application>postmaster</> should create an
- additional process-id (PID) file for use by server administration
- programs.
- This option can only be set at server start.
+ Specifies the name of an additional process-id (PID) file that the
+ <application>postmaster</> should create for use by server
+ administration programs.
+ This option can only be set at server start.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
- In a default installation, none of the above options is set explicitly
- in the <filename>postgresql.conf</filename> file. Instead, the
+ In a default installation, none of the above options are set explicitly.
+ Instead, the
data directory is specified by the <option>-D</option> command-line
option or the <envar>PGDATA</envar> environment variable, and the
- configuration files are all placed within the data directory.
+ configuration files are all found within the data directory.
</para>
<para>
- It is also possible to separate the configuration files from the data
- directory, which can ease administration. (In particular it is often
- easier to ensure that the configuration files are properly backed-up
- when they are kept separate.) To do this, the <option>-D</option>
+ If you wish to keep the configuration files elsewhere than the
+ data directory, the postmaster's <option>-D</option>
command-line option or <envar>PGDATA</envar> environment variable
must point to the directory containing the configuration files,
- and the <varname>data_directory</> option is set in
+ and the <varname>data_directory</> option must be set in
<filename>postgresql.conf</filename> (or on the command line) to show
where the data directory is actually located. Notice that
- <varname>data_directory</> overrides <option>-D</option> for the location
+ <varname>data_directory</> overrides <option>-D</option> and
+ <envar>PGDATA</envar> for the location
of the data directory, but not for the location of the configuration
files.
</para>
</indexterm>
<listitem>
<para>
- Determines the number of <quote>connection slots</quote> that
+ Determines the number of connection <quote>slots</quote> that
are reserved for connections by <productname>PostgreSQL</>
superusers. At most <xref linkend="guc-max-connections">
connections can ever be active simultaneously. Whenever the
</indexterm>
<listitem>
<para>
- Sets the access permissions of the Unix-domain socket. Unix
- domain sockets use the usual Unix file system permission set.
+ Sets the access permissions of the Unix-domain socket. Unix-domain
+ sockets use the usual Unix file system permission set.
The option value is expected to be a numeric mode
specification in the form accepted by the
<function>chmod</function> and <function>umask</function>
anyone can connect. Reasonable alternatives are
<literal>0770</literal> (only user and group, see also
<varname>unix_socket_group</varname>) and <literal>0700</literal>
- (only user). (Note that actually for a Unix domain socket, only write
- permission matters and there is no point in setting or revoking
+ (only user). (Note that for a Unix-domain socket, only write
+ permission matters and so there is no point in setting or revoking
read or execute permissions.)
</para>
<para>
Specifies the <productname>Rendezvous</productname> broadcast
name. By default, the computer name is used, specified as an
- empty string ''. This option is only meaningful on platforms
- that support <productname>Rendezvous</productname>. This
+ empty string ''. This option is ignored if the server was not
+ compiled with <productname>Rendezvous</productname> support. This
option can only be set at server start.
</para>
</listitem>
</para>
<para>
- If <literal>mylib</> or <literal>mylib_init</> are not found, the
- server will fail to start.
+ If a specified library or initialization function is not found,
+ the server will fail to start.
</para>
<para>
By preloading a shared library (and initializing it if
applicable), the library startup time is avoided when the
library is first used. However, the time to start each new
- server process may increase, even if that process never
- uses the library.
+ server process may increase slightly, even if that process never
+ uses the library. So this option is recommended only for
+ libraries that will be used in most sessions.
</para>
</listitem>
</varlistentry>
</indexterm>
<listitem>
<para>
- Write a message to the server logs if checkpoints caused by
+ Write a message to the server log if checkpoints caused by
the filling of checkpoint segment files happen closer together
than this many seconds. The default is 30 seconds.
Zero turns off the warning.
file.
</para>
<para>
- It is important for the command to return a zero exit status only if
- it succeeds. Examples:
+ It is important for the command to return a zero exit status if
+ and only if it succeeds. Examples:
<programlisting>
archive_command = 'cp "%p" /mnt/server/archivedir/"%f"'
archive_command = 'copy "%p" /mnt/server/archivedir/"%f"' # Windows
<title>Planner Method Configuration</title>
<para>
- These configuration parameters provide a crude method for
+ These configuration parameters provide a crude method of
influencing the query plans chosen by the query optimizer. If
the default plan chosen by the optimizer for a particular query
is not optimal, a temporary solution may be found by using one
of these configuration parameters to force the optimizer to
- choose a better plan. Other ways to improve the quality of the
- plans chosen by the optimizer include configuring the <xref
+ choose a different plan. Turning one of these settings off
+ permanently is seldom a good idea, however.
+ Better ways to improve the quality of the
+ plans chosen by the optimizer include adjusting the <xref
linkend="runtime-config-query-constants"
endterm="runtime-config-query-constants-title">, running <xref
linkend="sql-analyze" endterm="sql-analyze-title"> more
frequently, increasing the value of the <xref
linkend="guc-default-statistics-target"> configuration parameter,
- and increasing the amount of statistics collected for a
- particular column using <command>ALTER TABLE SET
+ and increasing the amount of statistics collected for
+ specific columns using <command>ALTER TABLE SET
STATISTICS</command>.
</para>
<listitem>
<para>
Enables or disables the query planner's use of hashed
- aggregation plan types. The default is on. This is used for
- debugging the query planner.
+ aggregation plan types. The default is on.
</para>
</listitem>
</varlistentry>
<listitem>
<para>
Enables or disables the query planner's use of hash-join plan
- types. The default is on. This is used for debugging the query
- planner.
+ types. The default is on.
</para>
</listitem>
</varlistentry>
<listitem>
<para>
Enables or disables the query planner's use of index-scan plan
- types. The default is on. This is used for debugging the query
- planner.
+ types. The default is on.
</para>
</listitem>
</varlistentry>
<listitem>
<para>
Enables or disables the query planner's use of merge-join plan
- types. The default is on. This is used for debugging the query
- planner.
+ types. The default is on.
</para>
</listitem>
</varlistentry>
plans. It's not possible to suppress nested-loop joins entirely,
but turning this variable off discourages the planner from using
one if there are other methods available. The default is
- on. This is used for debugging the query planner.
+ on.
</para>
</listitem>
</varlistentry>
plan types. It's not possible to suppress sequential scans
entirely, but turning this variable off discourages the planner
from using one if there are other methods available. The
- default is on. This is used for debugging the query planner.
+ default is on.
</para>
</listitem>
</varlistentry>
steps. It's not possible to suppress explicit sorts entirely,
but turning this variable off discourages the planner from
using one if there are other methods available. The default
- is on. This is used for debugging the query planner.
+ is on.
</para>
</listitem>
</varlistentry>
<listitem>
<para>
Enables or disables the query planner's use of <acronym>TID</>
- scan plan types. The default is on. This is used for debugging
- the query planner.
+ scan plan types. The default is on.
</para>
</listitem>
</varlistentry>
message that is logged. Valid values are <literal>TERSE</>,
<literal>DEFAULT</>, and <literal>VERBOSE</>, each adding more
fields to displayed messages.
+ Only superusers can change this setting.
</para>
</listitem>
</varlistentry>
<term><literal>ERROR</literal></term>
<listitem>
<para>
- Reports an error that caused the current transaction to abort.
+ Reports an error that caused the current command to abort.
</para>
</listitem>
</varlistentry>
</indexterm>
<listitem>
<para>
- These options enable various debugging output to be sent to
- the client or server log. For each executed query, they print
+ These options enable various debugging output to be emitted.
+ For each executed query, they print
the resulting parse tree, the query rewriter output, or the
execution plan. <varname>debug_pretty_print</varname> indents
these displays to produce a more readable but much longer
output format. <varname>client_min_messages</varname> or
<varname>log_min_messages</varname> must be
- <literal>DEBUG1</literal> or lower to send the output to the
- client or server logs. These options are off by default.
+ <literal>DEBUG1</literal> or lower to actually send this output
+ to the client or the server log, respectively.
+ These options are off by default.
</para>
</listitem>
</varlistentry>
</indexterm>
<listitem>
<para>
- This outputs a line to the server logs detailing each successful
+ This outputs a line to the server log detailing each successful
connection. This is off by default, although it is probably very
useful. This option can only be set at server start or in the
<filename>postgresql.conf</filename> configuration file.
</indexterm>
<listitem>
<para>
- This outputs a line in the server logs similar to
+ This outputs a line in the server log similar to
<varname>log_connections</varname> but at session termination,
and includes the duration of the session. This is off by
default. This option can only be set at server start or in the
</indexterm>
<listitem>
<para>
- By default, connection logs only show the IP address of the
- connecting host. If you want it to show the host name you can
- turn this on, but depending on your host name resolution setup
- it might impose a non-negligible performance penalty. This
- option can only be set at server start.
+ By default, connection log messages only show the IP address of the
+ connecting host. Turning on this option causes logging of the
+ host name as well. Note that depending on your host name resolution
+ setup this might impose a non-negligible performance penalty. This
+ option can only be set at server start or in the
+ <filename>postgresql.conf</filename> file.
</para>
</listitem>
</varlistentry>
<listitem>
<para>
This parameter is normally true. When set to false, it disables
- validation of the function body string in <xref
+ validation of the function body string during <xref
linkend="sql-createfunction"
endterm="sql-createfunction-title">. Disabling validation is
occasionally useful to avoid problems such as forward
</indexterm>
<listitem>
<para>
- Aborts any statement that takes over the specified number of
+ Abort any statement that takes over the specified number of
milliseconds. A value of zero (the default) turns off the limitation.
</para>
</listitem>
The shared lock table is sized on the assumption that at most
<varname>max_locks_per_transaction</varname> *
<varname>max_connections</varname> distinct objects will need to
- be locked at any one time. The default, 64, has historically
+ be locked at any one time. (Thus, this parameter's name may be
+ confusing: it is not a hard limit on the number of locks taken
+ by any one transaction, but rather a maximum average value.)
+ The default, 64, has historically
proven sufficient, but you might need to raise this value if you
have clients that touch many different tables in a single
transaction. This option can only be set at server start.
<literal>advanced</>, <literal>extended</>, or <literal>basic</>.
The default is <literal>advanced</>. The <literal>extended</>
setting may be useful for exact backwards compatibility with
- pre-7.4 releases of <productname>PostgreSQL</>.
+ pre-7.4 releases of <productname>PostgreSQL</>. See
+ <xref linkend="posix-syntax-details"> for details.
</para>
</listitem>
</varlistentry>
<listitem>
<para>
This controls whether <command>CREATE TABLE</command> and
- <command>CREATE TABLE AS</command> will include OIDs in
+ <command>CREATE TABLE AS</command> include an OID column in
newly-created tables, if neither <literal>WITH OIDS</literal>
nor <literal>WITHOUT OIDS</literal> is specified. It also
determines whether OIDs will be included in tables created by
The following <quote>parameters</> are read-only, and are determined
when <productname>PostgreSQL</productname> is compiled or when it is
installed. As such, they have been excluded from the sample
- <filename>postgresql.conf</> file. These options determine
+ <filename>postgresql.conf</> file. These options report
various aspects of <productname>PostgreSQL</productname> behavior
that may be of interest to certain applications, particularly
administrative front-ends.
<para>
Detection of a damaged page header normally causes
<productname>PostgreSQL</> to report an error, aborting the current
- transaction. Setting <varname>zero_damaged_pages</> to true causes
+ command. Setting <varname>zero_damaged_pages</> to true causes
the system to instead report a warning, zero out the damaged page,
and continue processing. This behavior <emphasis>will destroy data</>,
namely all the rows on the damaged page. But it allows you to get
<row>
<entry><varname>SEMVMX</></>
<entry>Maximum value of semaphore</>
- <entry>at least 1000 (The default is often 32767, don't change unless asked to.)</>
+ <entry>at least 1000 (The default is often 32767, don't change unless forced to)</>
</row>
</tbody>
shared memory parameter is <varname>SHMMAX</>, the maximum size, in
bytes, of a shared memory segment. If you get an error message from
<function>shmget</> like <errorname>Invalid argument</>, it is
- possible that this limit has been exceeded. The size of the required
+ likely that this limit has been exceeded. The size of the required
shared memory segment varies both with the number of requested
buffers (<option>-B</> option) and the number of allowed connections
(<option>-N</> option), although the former is the most significant.
(You can, as a temporary solution, lower these settings to eliminate
the failure.) As a rough approximation, you can estimate the
- required segment size by multiplying the number of buffers and the
- block size (8 kB by default) plus ample overhead (at least half a
- megabyte). Any error message you might get will contain the size of
- the failed allocation request.
+ required segment size as suggested in <xref
+ linkend="sysvipc-parameters">. Any error message you might get will
+ contain the size of the failed allocation request.
+ </para>
+
+ <para>
+ Some systems also have a limit on the total amount of shared memory in
+ the system (<varname>SHMALL</>). Make sure this is large enough
+ for <productname>PostgreSQL</> plus any other applications that
+ are using shared memory segments. (Caution: <varname>SHMALL</>
+ is measured in pages rather than bytes on many systems.)
</para>
<para>
memory segments (<varname>SHMMIN</>), which should be at most
approximately 256 kB for <productname>PostgreSQL</> (it is
usually just 1). The maximum number of segments system-wide
- (<varname>SHMMNI</>) or per-process (<varname>SHMSEG</>) should
- not cause a problem unless your system has them set to zero. Some
- systems also have a limit on the total amount of shared memory in
- the system; see the platform-specific instructions below.
+ (<varname>SHMMNI</>) or per-process (<varname>SHMSEG</>) are unlikely
+ to cause a problem unless your system has them set to zero.
</para>
<para>
By default, only 4 MB of shared memory is supported. Keep in
mind that shared memory is not pageable; it is locked in RAM.
To increase the amount of shared memory supported by your
- system, add the following to your kernel configuration
- file. A <varname>SHMALL</> value of 1024 represents 4 MB of
- shared memory. The following increases the maximum shared
- memory area to 32 MB:
+ system, add something like the following to your kernel configuration
+ file:
<programlisting>
options "SHMALL=8192"
options "SHMMAX=\(SHMALL*PAGE_SIZE\)"
</programlisting>
- For those running 4.3 or later, you will probably need to increase
+ <varname>SHMALL</> is measured in 4KB pages, so a value of
+ 1024 represents 4 MB of shared memory. Therefore the above increases
+ the maximum shared memory area to 32 MB.
+ For those running 4.3 or later, you will probably also need to increase
<varname>KERNEL_VIRTUAL_MB</> above the default <literal>248</>.
Once all changes have been made, recompile the kernel, and reboot.
</para>
<formalpara>
<title>Semaphores</>
<para>
- You may need to increase the number of semaphores. By
- default, <productname>PostgreSQL</> allocates 34 semaphores,
- which is over half the default system total of 60. Set the
+ You will probably want to increase the number of semaphores
+ as well; the default system total of 60 will only allow about
+ 50 <productname>PostgreSQL</productname> connections. Set the
values you want in your kernel configuration file, e.g.:
<programlisting>
options "SEMMNI=40"
sysctl -w kern.sysv.shmall
</programlisting>
In OS X 10.3, these commands have been moved to <filename>/etc/rc</>
- and must be edited there. Note that <filename>/etc/rc</> is usually
+ and must be edited there. You'll need to reboot to make changes
+ take effect. Note that <filename>/etc/rc</> is usually
overwritten by OS X updates (such as 10.3.6 to 10.3.7) so you
should expect to have to redo your editing after each update.
</para>
+ <para>
+ <varname>SHMALL</> is measured in 4KB pages on this platform.
+ </para>
</listitem>
</varlistentry>
This is the <firstterm>Immediate Shutdown</firstterm>, which
will cause the <command>postmaster</command> process to send a
<systemitem>SIGQUIT</systemitem> to all child processes and exit
- immediately (without properly shutting itself down). The child processes
+ immediately, without properly shutting itself down. The child processes
likewise exit immediately upon receiving
<systemitem>SIGQUIT</systemitem>. This will lead to recovery (by
replaying the WAL log) upon next start-up. This is recommended
</variablelist>
</para>
- <important>
- <para>
- It is best not to use <systemitem>SIGKILL</systemitem> to shut down
- the server. This will prevent the server from releasing
- shared memory and semaphores, which may then have to be done by
- manually.
- </para>
- </important>
+ <para>
+ The <xref linkend="app-pg-ctl"> program provides a convenient
+ interface for sending these signals to shut down the server.
+ </para>
<para>
- The <acronym>PID</> of the <command>postmaster</command> process can be found using the
- <command>ps</command> program, or from the file
- <filename>postmaster.pid</filename> in the data directory. So for
+ Alternatively, you can send the signal directly using <command>kill</>.
+ The <acronym>PID</> of the <command>postmaster</command> process can be
+ found using the <command>ps</command> program, or from the file
+ <filename>postmaster.pid</filename> in the data directory. For
example, to do a fast shutdown:
<screen>
$ <userinput>kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`</userinput>
</screen>
</para>
- <para>
- The program <command>pg_ctl</command> is a shell script
- that provides a more convenient interface for shutting down the
- server.
- </para>
+
+ <important>
+ <para>
+ It is best not to use <systemitem>SIGKILL</systemitem> to shut down
+ the server. Doing so will prevent the server from releasing
+ shared memory and semaphores, which may then have to be done
+ manually before a new server can be started. Furthermore,
+ <systemitem>SIGKILL</systemitem> kills the <command>postmaster</command>
+ process without letting it relay the signal to its subprocesses,
+ so it will be necessary to kill the individual subprocesses by hand as
+ well.
+ </para>
+ </important>
</sect1>
<sect1 id="ssl-tcp">
With <acronym>SSL</> support compiled in, the
<productname>PostgreSQL</> server can be started with
<acronym>SSL</> enabled by setting the parameter
- <xref linkend="guc-ssl"> to on in <filename>postgresql.conf</>. When
+ <xref linkend="guc-ssl"> to <literal>on</> in
+ <filename>postgresql.conf</>. When
starting in <acronym>SSL</> mode, the server will look for the
files <filename>server.key</> and <filename>server.crt</> in the
- data directory, which should contain the server private key
+ data directory, which must contain the server private key
and certificate, respectively. These files must be set up correctly
before an <acronym>SSL</>-enabled server can start. If the private key is
protected with a passphrase, the server will prompt for the
<para>
The server will listen for both standard and <acronym>SSL</>
connections on the same TCP port, and will negotiate with any
- connecting client on whether to use <acronym>SSL</>. See <xref
+ connecting client on whether to use <acronym>SSL</>. By default,
+ this is at the client's option; see <xref
linkend="auth-pg-hba-conf"> about how to set up the server to
require use of <acronym>SSL</> for some or all connections.
</para>
<para>
For details on how to create your server private key and certificate,
- refer to the <productname>OpenSSL</> documentation. A simple
- self-signed certificate can be used to get started for testing, but a
- certificate signed by a certificate authority (<acronym>CA</>) (either one of the global
+ refer to the <productname>OpenSSL</> documentation. A
+ self-signed certificate can be used for testing, but a
+ certificate signed by a certificate authority (<acronym>CA</>)
+ (either one of the global
<acronym>CAs</> or a local one) should be used in production so the
client can verify the server's identity. To create a quick
self-signed certificate, use the following
One can use <application>SSH</application> to encrypt the network
connection between clients and a
<productname>PostgreSQL</productname> server. Done properly, this
- provides an adequately secure network connection.
+ provides an adequately secure network connection, even for non-SSL-capable
+ clients.
</para>
<para>
The first number in the <option>-L</option> argument, 3333, is the
port number of your end of the tunnel; it can be chosen freely. The
second number, 5432, is the remote end of the tunnel: the port
- number your server is using. The name or the address in between
+ number your server is using. The name or IP address between
the port numbers is the host with the database server you are going
to connect to. In order to connect to the database server using
this tunnel, you connect to port 3333 on the local machine:
</programlisting>
To the database server it will then look as though you are really
user <literal>joe@foo.com</literal> and it will use whatever
- authentication procedure was set up for this user. In order for the
+ authentication procedure was configured for connections from this
+ user and host. Note that the server will not think the connection is
+ SSL-encrypted, since in fact it is not encrypted between the
+ <application>SSH</application> server and the
+ <productname>PostgreSQL</productname> server. This should not pose any
+ extra security risk as long as they are on the same machine.
+ </para>
+ <para>
+ In order for the
tunnel setup to succeed you must be allowed to connect via
<command>ssh</command> as <literal>joe@foo.com</literal>, just
as if you had attempted to use <command>ssh</command> to set up a
projects / postgresql / commitdiff