| .TH htpasswd 1 "February 1997" |
| .\" Copyright (c) 1997-1999 The Apache Group. All rights reserved. |
| .\" |
| .\" Redistribution and use in source and binary forms, with or without |
| .\" modification, are permitted provided that the following conditions |
| .\" are met: |
| .\" |
| .\" 1. Redistributions of source code must retain the above copyright |
| .\" notice, this list of conditions and the following disclaimer. |
| .\" |
| .\" 2. Redistributions in binary form must reproduce the above copyright |
| .\" notice, this list of conditions and the following disclaimer in |
| .\" the documentation and/or other materials provided with the |
| .\" distribution. |
| .\" |
| .\" 3. All advertising materials mentioning features or use of this |
| .\" software must display the following acknowledgment: |
| .\" "This product includes software developed by the Apache Group |
| .\" for use in the Apache HTTP server project (http://www.apache.org/)." |
| .\" |
| .\" 4. The names "Apache Server" and "Apache Group" must not be used to |
| .\" endorse or promote products derived from this software without |
| .\" prior written permission. For written permission, please contact |
| .\" apache@apache.org. |
| .\" |
| .\" 5. Products derived from this software may not be called "Apache" |
| .\" nor may "Apache" appear in their names without prior written |
| .\" permission of the Apache Group. |
| .\" |
| .\" 6. Redistributions of any form whatsoever must retain the following |
| .\" acknowledgment: |
| .\" "This product includes software developed by the Apache Group |
| .\" for use in the Apache HTTP server project (http://www.apache.org/)." |
| .\" |
| .\" THIS SOFTWARE IS PROVIDED BY THE APACHE GROUP ``AS IS'' AND ANY |
| .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
| .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR |
| .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE APACHE GROUP OR |
| .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |
| .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT |
| .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; |
| .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
| .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, |
| .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) |
| .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED |
| .\" OF THE POSSIBILITY OF SUCH DAMAGE. |
| .\" ==================================================================== |
| .\" |
| .\" This software consists of voluntary contributions made by many |
| .\" individuals on behalf of the Apache Group and was originally based |
| .\" on public domain software written at the National Center for |
| .\" Supercomputing Applications, University of Illinois, Urbana-Champaign. |
| .\" For more information on the Apache Group and the Apache HTTP server |
| .\" project, please see <http://www.apache.org/>. |
| .SH NAME |
| htpasswd \- Create and update user authentication files |
| .SH SYNOPSIS |
| .B htpasswd |
| [ |
| .B \-c |
| ] |
| [ |
| .B \-m |
| ] |
| .I passwdfile |
| .I username |
| .br |
| .B htpasswd |
| .B \-b |
| [ |
| .B \-c |
| ] |
| [ |
| .B \-m |
| .B \-d |
| .B \-p |
| .B \-s |
| ] |
| .I passwdfile |
| .I username |
| .I password |
| .SH DESCRIPTION |
| .B htpasswd |
| is used to create and update the flat-files used to store |
| usernames and password for basic authentication of HTTP users. |
| If |
| .B 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. |
| .PP |
| Resources available from the |
| .B httpd |
| Apache web server can be restricted to just the users listed |
| in the files created by |
| .B htpasswd. |
| This program can only be used |
| when the usernames are stored in a flat-file. To use a |
| DBM database see |
| \fBdbmmanage\fP. |
| .PP |
| .B htpasswd |
| encrypts passwords using either a version of MD5 modified for Apache, |
| or the system's \fIcrypt()\fP routine. Files managed by |
| .B 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 \fIcrypt()\fP. |
| .PP |
| This manual page only lists the command line arguments. For details of |
| the directives necessary to configure user authentication in |
| .B httpd |
| see |
| the Apache manual, which is part of the Apache distribution or can be |
| found at <URL:http://www.apache.org/>. |
| .SH OPTIONS |
| .IP \-b |
| Use batch mode; \fIi.e.\fP, get the password from the command line |
| rather than prompting for it. \fBThis option should be used with |
| extreme care, since the password is clearly visible on the command |
| line.\fP |
| .IP \-c |
| Create the \fIpasswdfile\fP. If \fIpasswdfile\fP already exists, it |
| is rewritten and truncated. |
| .IP \-m |
| Use MD5 encryption for passwords. On Windows and TPF, this is the default. |
| .IP \-d |
| Use crypt() encryption for passwords. The default on all platforms but |
| Windows and TPF. Though possibly supported by |
| .B htpasswd |
| onm all platforms, it is not supported by the |
| .B httpd |
| server on Windows and TPF. |
| .IP \-s |
| Use SHA encryption for passwords. Faciliates migration from/to Netscape |
| servers using the LDAP Directory Interchange Format (ldif). |
| .IP \-p |
| Use plaintext passwords. Though |
| .B htpasswd |
| will support creation on all platofrms, the |
| .B httpd |
| deamon will only accept plain text passwords on Windows and TPF. |
| .IP \fB\fIpasswdfile\fP |
| 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. |
| .IP \fB\fIusername\fP |
| The username to create or update in \fBpasswdfile\fP. If |
| \fIusername\fP does not exist in this file, an entry is added. If it |
| does exist, the password is changed. |
| .IP \fB\fIpassword\fP |
| The plaintext password to be encrypted and stored in the file. Only used |
| with the \fI-b\fP flag. |
| .SH EXIT STATUS |
| .B htpasswd |
| returns a zero status ("true") if the username and password have |
| been successfully added or updated in the \fIpasswdfile\fP. |
| .B htpasswd |
| returns 1 if it encounters some problem accessing files, 2 if there |
| was a syntax problem with the command line, 3 if the password was |
| entered interactively and the verification entry didn't match, 4 if |
| its operation was interrupted, 5 if a value is too long (username, |
| filename, password, or final computed record), and 6 if the username |
| contains illegal characters (see the \fBRESTRICTIONS\fP section). |
| .SH EXAMPLES |
| \fBhtpasswd /usr/local/etc/apache/.htpasswd-users jsmith\fP |
| .IP |
| Adds or modifies the password for user \fIjsmith\fP. |
| The user is prompted for the password. If executed |
| on a Windows system, the password will be encrypted using the |
| modified Apache MD5 algorithm; otherwise, the system's |
| \fIcrypt()\fP routine will be used. If the file does not |
| exist, |
| .B htpasswd |
| will do nothing except return an error. |
| .LP |
| \fBhtpasswd -c /home/doe/public_html/.htpasswd jane\fP |
| .IP |
| Creates a new file and stores a record in it for user \fIjane\fP. |
| The user is prompted for the password. |
| If the file exists and cannot be read, or cannot be written, |
| it is not altered and |
| .B htpasswd |
| will display a message and return an error status. |
| .LP |
| \fBhtpasswd -mb /usr/web/.htpasswd-all jones Pwd4Steve\fP |
| .IP |
| Encrypts the password from the command line (\fIPwd4Steve\fP) using |
| the MD5 algorithm, and stores it in the specified file. |
| .LP |
| .SH SECURITY CONSIDERATIONS |
| Web password files such as those managed by |
| .B htpasswd |
| should \fBnot\fP be within the Web server's URI space -- that is, |
| they should not be fetchable with a browser. |
| .PP |
| The use of the \fI-b\fP option is discouraged, since when it is |
| used the unencrypted password appears on the command line. |
| .SH RESTRICTIONS |
| On the Windows and MPE platforms, passwords encrypted with |
| .B htpasswd |
| are limited to no more than 255 characters in length. Longer |
| passwords will be truncated to 255 characters. |
| .PP |
| The MD5 algorithm used by |
| .B htpasswd |
| is specific to the Apache software; passwords encrypted using it will not be |
| usable with other Web servers. |
| .PP |
| Usernames are limited to 255 bytes and may not include the character ':'. |
| .SH SEE ALSO |
| .BR httpd(8) |
| and the scripts in support/SHA1 which come with the distribution. |