Expand on description of when to use or not use TRUST auth method.

doc/src/sgml/client-auth.sgml

-<!-- $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>

doc/src/sgml/runtime.sgml

 <!--
-$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>