<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/pg_passwd.sgml,v 1.8 2001/09/03 12:57:50 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>
  <manvolnum>1</manvolnum>
  <refmiscinfo>Application</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>pg_passwd</refname>
  <refpurpose>change a secondary password file</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
  <cmdsynopsis>
   <command>pg_passwd</command>
   <arg choice="plain"><replaceable>filename</replaceable></arg>
  </cmdsynopsis>
 </refsynopsisdiv>

 <refsect1 id="app-pg-passwd-description">
  <title>Description</title>
  <para>
   <application>pg_passwd</application> is a tool for manipulating flat
   text password files. These files can control 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>
   The format 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). <application>pg_passwd</application>
   enables users to interactively add entries to such a file, to alter
   passwords of existing entries, and to encrypt such passwords.
  </para>

  <para>
   Supply the name of the password file as argument to the
   <application>pg_passwd</application> command. To be used by
   PostgreSQL, the file needs to be located 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.  Note that the password is limited
   to eight useful characters by restrictions of the standard crypt(3)
   library routine.
  </para>

  <para>
   The original password file is renamed to
   <filename>passwords.bk</filename>.
  </para>

  <para>
   To make use of this password file, put a line like the following in
   <filename>pg_hba.conf</filename>:

<programlisting>
host  mydb     133.65.96.250   255.255.255.255 password passwords
</programlisting>

   which would allow access to database mydb from host 133.65.96.250 using
   the passwords listed in the <filename>passwords</filename> file (and
   only to the users listed in that file).
  </para>

  <note>
   <para>
    It is also useful to have entries in a password file with empty
    password fields. (This is different from an empty password.) Such
    entries allow you to restrict users who can access the system. These
    entries cannot be managed by <application>pg_passwd</application>,
    but you can edit password files manually.
   </para>
  </note>
 </refsect1>

 <refsect1 id="app-pg-passwd-seealso">
  <title>See also</title>
  <para>
   <citetitle>PostgreSQL Administrator's Guide</citetitle>
  </para>
 </refsect1>
</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-ecat-files:nil
End:
-->
