diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
index 14f1a4ad2a3b9312d861b57cd7b374003ae7be20..932b5acc0f75335b1aa3a036d8a1718cf50f5d8a 100644
--- a/doc/src/sgml/client-auth.sgml
+++ b/doc/src/sgml/client-auth.sgml
@@ -1,4 +1,6 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.30 2001/11/28 20:49:09 petere Exp $ -->
+<!--
+$Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.31 2001/12/27 21:37:34 tgl Exp $
+-->
<chapter id="client-authentication">
<title>Client Authentication</title>
@@ -437,9 +439,53 @@ local all md5 admins
<sect1 id="auth-methods">
<title>Authentication methods</title>
<para>
- The following describes the authentication methods in detail.
+ The following describes the authentication methods in more detail.
</para>
+ <sect2 id="auth-trust">
+ <title>Trust authentication</title>
+
+ <para>
+ When <literal>trust</> authentication is specified,
+ <productname>PostgreSQL</productname> assumes that anyone who can
+ connect to the postmaster is authorized to access the database as
+ whatever database user he specifies (including the database superuser).
+ This method should only be used when there is adequate system-level
+ protection on connections to the postmaster port.
+ </para>
+
+ <para>
+ <literal>trust</> authentication is appropriate and very convenient
+ for local connections on a single-user workstation. It is usually
+ <emphasis>not</> appropriate by itself on a multi-user machine.
+ However, you may be able to use <literal>trust</> even on a multi-user
+ machine, if you restrict access to the postmaster's socket file using
+ filesystem permissions. To do this, set the parameter
+ <varname>unix_socket_permissions</varname> (and possibly
+ <varname>unix_socket_group</varname>) in <filename>postgresql.conf</>,
+ as described in <xref linkend="runtime-config-general">. Or you could
+ set <varname>unix_socket_directory</varname> to place the socket file
+ in a suitably restricted directory.
+ </para>
+
+ <para>
+ Setting filesystem permissions only helps for Unix-socket connections.
+ Local TCP connections are not restricted by it; therefore, if you want
+ to use permissions for local security, remove the <literal>host ...
+ 127.0.0.1 ...</> line from <filename>pg_hba.conf</>, or change it to a
+ non-<literal>trust</> authentication method.
+ </para>
+
+ <para>
+ <literal>trust</> authentication is only suitable for TCP connections
+ if you trust every user on every machine that is allowed to connect
+ to the postmaster by the <filename>pg_hba.conf</> lines that specify
+ <literal>trust</>. It is seldom reasonable to use <literal>trust</>
+ for any TCP connections other than those from localhost (127.0.0.1).
+ </para>
+
+ </sect2>
+
<sect2 id="auth-password">
<title>Password authentication</title>
@@ -450,6 +496,18 @@ local all md5 admins
<primary>MD5</>
</indexterm>
+ <para>
+ Password-based authentication methods include <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 <quote>sniffing</>
+ attacks then <literal>md5</> is preferred, with <literal>crypt</> a
+ second choice if you must support obsolete clients. Plain
+ <literal>password</> should especially be avoided for connections over
+ the open Internet (unless you use SSL, SSH, or other communications
+ security wrappers around the connection).
+ </para>
+
<para>
<productname>PostgreSQL</productname> database passwords are separate from
operating system user passwords. Ordinarily, the password for each
@@ -652,7 +710,7 @@ local all md5 admins
On systems supporting <symbol>SO_PEERCRED</symbol> requests for Unix-domain sockets,
ident authentication can also be applied to local connections. In this
case, no security risk is added by using ident authentication; indeed
- it is a preferable choice for such a system.
+ it is a preferable choice for local connections on such a system.
</para>
<para>
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index aafb3025bb7686468e7c9446f6ab35f80d5da39e..687045e37d912adcd4ecbe9a2538808a30525e87 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.99 2001/11/28 20:49:10 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.100 2001/12/27 21:37:34 tgl Exp $
-->
<Chapter Id="runtime">
@@ -57,7 +57,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.99 2001/11/28 20:49:10 pet
through a single instance of a running database server. After
initialization, a database cluster will contain one database named
<literal>template1</literal>. As the name suggests, this will be used
- as a template for any subsequently created database; it should not be
+ as a template for subsequently created databases; it should not be
used for actual work.
</para>
@@ -65,7 +65,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.99 2001/11/28 20:49:10 pet
In file system terms, a database cluster will be a single directory
under which all data will be stored. We call this the <firstterm>data
directory</firstterm> or <firstterm>data area</firstterm>. It is
- completely up to you where you choose to store your data, there is no
+ completely up to you where you choose to store your data. There is no
default, although locations such as
<filename>/usr/local/pgsql/data</filename> or
<filename>/var/lib/pgsql/data</filename> are popular. To initialize a
@@ -76,7 +76,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.99 2001/11/28 20:49:10 pet
<screen>
<prompt>$</> <userinput>initdb -D /usr/local/pgsql/data</userinput>
</screen>
- Note that you must execute this command while being logged in to
+ Note that you must execute this command while being logged into
the <productname>PostgreSQL</productname> user account, which is described in the previous
section.
</para>
@@ -113,22 +113,25 @@ postgres$ <userinput>initdb -D /usr/local/pgsql/data</userinput>
<para>
Because the data directory contains all the data stored in the
- database it is essential that it be well secured from unauthorized
+ database, it is essential that it be well secured from unauthorized
access. <command>initdb</command> therefore revokes access
permissions from everyone but the <productname>PostgreSQL</productname> user account.
</para>
<para>
However, while the directory contents are secure, the default
- <filename>pg_hba.conf</filename> authentication of
- <literal>trust</literal> allows any local user to become the
- superuser and connect to the database. If you don't trust your local
- users, we recommend you use the <command>initdb</command> option
+ <filename>pg_hba.conf</filename> authentication method of
+ <literal>trust</literal> allows any local user to connect to the database
+ and even become the database superuser. If you don't trust other local
+ users, we recommend you use <command>initdb</command>'s option
<option>-W</option> or <option>--pwprompt</option> to assign a
- password to the superuser and modify your
- <filename>pg_hba.conf</filename> accordingly. (Another option:
- Your operating system may support <literal>ident</literal> for
- local connections.)
+ password to the database superuser. After <command>initdb</command>,
+ modify <filename>pg_hba.conf</filename> to use <literal>md5</> or
+ <literal>password</>, instead of <literal>trust</>, authentication
+ <emphasis>before</> you first start the postmaster. (Other, possibly
+ more convenient approaches include using <literal>ident</literal>
+ authentication or filesystem permissions to restrict connections. See
+ <xref linkend="client-authentication"> for more information.)
</para>
<para>
@@ -172,7 +175,7 @@ NOTICE: Initializing database with en_US collation order.
$ <userinput>postmaster -D /usr/local/pgsql/data</userinput>
</screen>
which will leave the server running in the foreground. This must
- again be done while logged in to the <productname>PostgreSQL</productname> user account. Without
+ again be done while logged into the <productname>PostgreSQL</productname> user account. Without
a <option>-D</option>, the server will try to use the data
directory in the environment variable <envar>PGDATA</envar>; if
neither of these works it will fail.
@@ -2287,7 +2290,7 @@ default:\
<para>
On <productname>Linux</productname>
<filename>/proc/sys/fs/file-max</filename> determines the
- maximum number of files that the kernel will allocate. It can
+ maximum number of open files that the kernel will support. It can
be changed by writing a different number into the file or by
adding an assignment in <filename>/etc/sysctl.conf</filename>.
The maximum limit of files per process is fixed at the time the
@@ -2315,6 +2318,16 @@ default:\
is perhaps what you want, but on dedicated servers you may want to
raise this limit.
</para>
+
+ <para>
+ On the other side of the coin, some systems allow individual
+ processes to open large numbers of files; if more than a few processes
+ do so then the system-wide limit can easily be exceeded. If you find
+ this happening, and don't want to alter the system-wide limit, you
+ can set <productname>PostgreSQL</productname>'s
+ <varname>max_files_per_process</varname> configuration parameter
+ to limit its consumption of open files.
+ </para>
</sect2>
</sect1>