diff --git a/doc/src/sgml/ref/pg_passwd.sgml b/doc/src/sgml/ref/pg_passwd.sgml
index fff87b48c13dbbbde4a10d3d6b040d30e6a3dceb..3170104178bff4d037c2402ab526050e53903c83 100644
--- a/doc/src/sgml/ref/pg_passwd.sgml
+++ b/doc/src/sgml/ref/pg_passwd.sgml
@@ -1,153 +1,106 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/pg_passwd.sgml,v 1.3 2000/07/21 00:24:37 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/pg_passwd.sgml,v 1.4 2000/11/18 19:05:58 petere Exp $
Postgres documentation
-->
<refentry id="APP-PG-PASSWD">
+ <docinfo>
+ <date>2000-11-18</date>
+ </docinfo>
+
<refmeta>
- <refentrytitle id="APP-PG-PASSWD-TITLE">
- <application>pg_passwd</application>
- </refentrytitle>
+ <refentrytitle id="APP-PG-PASSWD-TITLE"><application>pg_passwd</application></refentrytitle>
+ <manvolnum>1</manvolnum>
<refmiscinfo>Application</refmiscinfo>
</refmeta>
+
<refnamediv>
- <refname>
- <application>pg_passwd</application>
- </refname>
- <refpurpose>
- Manipulate the flat password file
- </refpurpose>
+ <refname>pg_passwd</refname>
+ <refpurpose>Manipulate a text password file</refpurpose>
</refnamediv>
+
<refsynopsisdiv>
- <refsynopsisdivinfo>
- <date>1999-07-20</date>
- </refsynopsisdivinfo>
- <synopsis>
-pg_passwd <replaceable class="parameter">filename</replaceable>
- </synopsis>
+ <cmdsynopsis>
+ <command>pg_passwd</command>
+ <arg choice="plain"><replaceable>filename</replaceable></arg>
+ </cmdsynopsis>
</refsynopsisdiv>
- <refsect1 id="R1-APP-PG-PASSWD-1">
- <refsect1info>
- <date>1999-07-20</date>
- </refsect1info>
- <title>
- Description
- </title>
+ <refsect1 id="app-pg-passwd-description">
+ <title>Description</title>
<para>
- <application>pg_passwd</application>
- is a tool to manipulate the
- flat password file functionality of
- <productname>Postgres</productname>. This style of password
- authentication is not <emphasis>required</emphasis> in an
- installation, but is one of several supported security mechanisms.
+ <application>pg_passwd</application> is a tool to manipulate a flat
+ text password file for the purpose of using that file to control
+ the client authentication of the
+ <productname>PostgreSQL</productname> server. More information
+ about setting up this authentication mechanism can be found in the
+ <citetitle>Administrator's Guide</citetitle>.
</para>
<para>
- Specify the password file in the same style of
- <literal>Ident</literal> authentication in
- <filename>$PGDATA/pg_hba.conf</filename>:
-
- <programlisting>
-host unv 133.65.96.250 255.255.255.255 password passwd
- </programlisting>
-
- where the above line allows access from 133.65.96.250 using the passwords listed
- in <filename>$PGDATA/passwd</filename>.
- The format of the password file follows those of
- <filename>/etc/passwd</filename>
- and
- <filename>/etc/shadow</filename>.
- The first field is the user name, and the second field
- is the encrypted password.
- The rest is completely ignored.
- Thus the following three sample lines specify the same user and password pair:
-
- <programlisting>
-pg_guest:/nB7.w5Auq.BY:10031::::::
-pg_guest:/nB7.w5Auq.BY:93001:930::/home/guest:/bin/tcsh
-pg_guest:/nB7.w5Auq.BY:93001
- </programlisting>
+ The form of a text password file is one entry per line; the fields
+ of each entry are separated by colons. The first field is the user
+ name, the second field is the encrypted password. Other fields are
+ ignored (to allow password files to be shared between applications
+ that use similar formats). The functionality of the
+ <application>pg_passwd</application> utility is to enable a user to
+ interactively add entries to such a file, to alter passwords of
+ existing entries, and to take care of encrypting the passwords.
</para>
<para>
- Supply the password file to the pg_passwd command.
- In the case described above, after changing the working directory to
- <envar>PGDATA</envar>, the following command execution specifies
- the new password for <literal>pg_guest</literal>:
-
- <programlisting>
- $ pg_passwd passwd
- Username: pg_guest
- Password:
- Re-enter password:
- </programlisting>
-
- where the <literal>Password:</literal>
- and <literal>Re-enter password:</literal>
- prompts require the same password input which are not displayed
- on the terminal.
- The original password file is renamed to
- <filename>passwd.bk</filename>.
+ Supply the name of the password file as argument to the pg_passwd
+ command. To be of use for client authentication the file needs to
+ be location in the server's data directory, and the base name of
+ the file needs to be specified in the
+ <filename>pg_hba.conf</filename> access control file.
+
+<screen>
+<prompt>$</prompt> <userinput>pg_passwd /usr/local/pgsql/data/passwords</userinput>
+<computeroutput>File "/usr/local/pgsql/data/passwords" does not exist. Create? (y/n):</computeroutput> <userinput>y</userinput>
+<prompt>Username:</prompt> <userinput>guest</userinput>
+<prompt>Password:</prompt>
+<prompt>Re-enter password:</prompt>
+</screen>
+
+ where the <literal>Password:</literal> and <literal>Re-enter
+ password:</literal> prompts require the same password input which
+ is not displayed on the terminal.
</para>
<para>
- <application>psql</application>
- uses the <option>-u</option>
- option to invoke this style of
- authentication.
+ The original password file is renamed to
+ <filename>passwords.bk</filename>.
</para>
<para>
- The following lines show the sample usage of the option:
+ To make use of this password file, put a line like the following in
+ <filename>pg_hba.conf</filename>:
<programlisting>
-$ psql -h hyalos -u unv
-Username: pg_guest
-Password:
-Welcome to the POSTGRESQL interactive sql monitor:
- Please read the file COPYRIGHT for copyright terms of POSTGRESQL
- type \? for help on slash commands
- type \q to quit
- type \g or terminate with semicolon to execute query
- You are currently connected to the database: unv
-unv=>
- </programlisting>
- </para>
-
- <para>
- Perl5 authentication
- uses the new style of the <filename>Pg.pm</filename> like this:
+host unv 133.65.96.250 255.255.255.255 password passwords
+</programlisting>
- <programlisting>
-$conn = Pg::connectdb("host=hyalos dbname=unv
- user=pg_guest password=xxxxxxx");
- </programlisting>
-
- For more details, refer to
- <filename>src/interfaces/perl5/Pg.pm</filename>.
+ which would allow access from host 133.65.96.250 using the
+ passwords listed in the <filename>passwords</filename> file (and
+ only to the users listed in the file).
</para>
- <para>
- Pg{tcl,tk}sh authentication
- uses the
- <function>pg_connect</function>
- command with the
- <option>-conninfo</option>
- option thusly:
-
-<programlisting>
-% set conn [pg_connect -conninfo \\
- "host=hyalos dbname=unv \\
- user=pg_guest password=xxxxxxx "]
- </programlisting>
-
- You can list all of the keys for the option by executing the following
- command:
+ <note>
+ <para>
+ It is also useful to have entries in password file with an empty
+ password field. (This is different from an empty password.)
+ These entries cannot be managed by
+ <application>pg_passwd</application>, but it is always possible to
+ edit password files manually.
+ </para>
+ </note>
+ </refsect1>
- <programlisting>
-% puts [ pg_conndefaults]
- </programlisting>
+ <refsect1 id="app-pg-passwd-seealso">
+ <title>See also</title>
+ <para>
+ <citetitle>PostgreSQL Administrator's Guide</citetitle>
</para>
</refsect1>
</refentry>