Manual Page: htpasswd

NAME
     htpasswd - Create and update user authentication files

SYNOPSIS
     htpasswd [ -c ] [ -m | -d | -s | -p ] passwdfile username
     htpasswd -b [ -c ] [ -m | -d | -s | -p ] passwdfile username
     password
     htpasswd -n [ -m | -d | -s | -p ] username
     htpasswd -nb [ -m | -d | -s | -p ] username password

DESCRIPTION
     htpasswd is used to create and update the flat-files used to
     store  usernames  and  password  for basic authentication of
     HTTP users.  If htpasswd cannot access a file, such  as  not
     being  able to write to the output file or not being able to
     read the file in order to update it,  it  returns  an  error
     status and makes no changes.

     Resources available from the httpd Apache web server can  be
     restricted  to just the users listed in the files created by
     htpasswd. This program can only manage usernames  and  pass-
     words  stored  in  a  flat-file.  It can encrypt and display
     password information for use in other types of data  stores,
     though.  To use a DBM database see dbmmanage.

     htpasswd encrypts passwords using either a  version  of  MD5
     modified for Apache, or the system's crypt() routine.  Files
     managed by htpasswd may contain  both  types  of  passwords;
     some  user  records  may  have MD5-encrypted passwords while
     others in the same file may have  passwords  encrypted  with
     crypt().

     This manual page only lists the command line arguments.  For
     details  of  the  directives  necessary  to  configure  user
     authentication in httpd see the Apache manual, which is part
     of   the   Apache   distribution   or   can   be   found  at
     <URL:http://www.apache.org/>.

OPTIONS
     -b   Use batch mode; i.e., get the password from the command
          line  rather  than prompting for it. This option should
          be used  with  extreme  care,  since  the  password  is
          clearly visible on the command line.

     -c   Create the passwdfile. If passwdfile already exists, it
          is rewritten and truncated.  This option cannot be com-
          bined with the -n option.

     -n   Display the results  on  standard  output  rather  than
          updating  a  file.  This is useful for generating pass-
          word records acceptable  to  Apache  for  inclusion  in
          non-text  data  stores.  This option changes the syntax
          of the command  line,  since  the  passwdfile  argument
          (usually  the first one) is omitted.  It cannot be com-
          bined with the -c option.

     -m   Use Apache's  modified  MD5  algorithm  for  passwords.
          Passwords  encrypted with this algorithm are transport-
          able to any platform (Windows, Unix, BeOS,  et  cetera)
          running  Apache  1.3.9  or  later.  On Windows and TPF,
          this flag is the default.

     -d   Use crypt() encryption for passwords.  The  default  on
          all platforms but Windows and TPF. Though possibly sup-
          ported by htpasswd on all platforms,  it  is  not  sup-
          ported by the httpd server on Windows and TPF.

     -s   Use SHA encryption for passwords. Faciliates  migration
          from/to  Netscape  servers  using  the  LDAP  Directory
          Interchange Format (ldif).

     -p   Use plaintext passwords. Though htpasswd  will  support
          creation  on  all platforms, the httpd deamon will only
          accept plain text passwords on Windows and TPF.

     passwdfile
          Name of the file to contain the user name and password.
          If  -c  is  given,  this file is created if it does not
          already exist, or rewritten and truncated  if  it  does
          exist.

     username
          The username to create  or  update  in  passwdfile.  If
          username  does  not  exist  in  this  file, an entry is
          added. If it does exist, the password is changed.

     password
          The plaintext password to be encrypted  and  stored  in
          the file.  Only used with the -b flag.

EXIT STATUS
     htpasswd returns a zero status ("true") if the username  and
     password  have  been  successfully  added  or updated in the
     passwdfile.  htpasswd returns 1 if it encounters some  prob-
     lem  accessing  files,  2 if there was a syntax problem with
     the command line, 3 if the  password  was  entered  interac-
     tively  and  the  verification  entry didn't match, 4 if its
     operation was interrupted, 5 if a value is too  long  (user-
     name,  filename,  password, or final computed record), and 6
     if the username contains illegal characters  (see  the  RES-
     TRICTIONS section).

EXAMPLES
     htpasswd /usr/local/etc/apache/.htpasswd-users jsmith

          Adds or modifies the password for user jsmith. The user
          is prompted for the password.  If executed on a Windows
          system, the password will be encrypted using the  modi-
          fied  Apache  MD5  algorithm;  otherwise,  the system's
          crypt() routine will be used.  If  the  file  does  not
          exist, htpasswd will do nothing except return an error.

     htpasswd -c /home/doe/public_html/.htpasswd jane

          Creates a new file and stores a record in it  for  user
          jane.   The  user is prompted for the password.  If the
          file exists and cannot be read, or cannot  be  written,
          it  is  not altered and htpasswd will display a message
          and return an error status.

     htpasswd -mb /usr/web/.htpasswd-all jones Pwd4Steve

          Encrypts the password from the command line (Pwd4Steve)
          using the MD5 algorithm, and stores it in the specified
          file.

SECURITY CONSIDERATIONS
     Web password files such as those managed by htpasswd  should
     not  be  within  the Web server's URI space -- that is, they
     should not be fetchable with a browser.

     The use of the -b option is discouraged, since  when  it  is
     used the unencrypted password appears on the command line.

RESTRICTIONS
     On the Windows and MPE platforms, passwords  encrypted  with
     htpasswd  are  limited  to  no  more  than 255 characters in
     length.  Longer passwords will be truncated to  255  charac-
     ters.

     The MD5 algorithm used by htpasswd is specific to the Apache
     software;  passwords  encrypted  using it will not be usable
     with other Web servers.

     Usernames are limited to 255 bytes and may not  include  the
     character ':'.

SEE ALSO
     httpd(8) and the scripts in support/SHA1 which come with the
     distribution.

Apache HTTP Server Version 1.3