| .TH htpasswd 1 "May 2000" |
| .\" The Apache Software License, Version 1.1 |
| .\" |
| .\" Copyright (c) 2000-2002 The Apache Software Foundation. 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. The end-user documentation included with the redistribution, |
| .\" if any, must include the following acknowledgment: |
| .\" "This product includes software developed by the |
| .\" Apache Software Foundation (http://www.apache.org/)." |
| .\" Alternately, this acknowledgment may appear in the software itself, |
| .\" if and wherever such third-party acknowledgments normally appear. |
| .\" |
| .\" 4. The names "Apache" and "Apache Software Foundation" 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 name, without prior written |
| .\" permission of the Apache Software Foundation. |
| .\" |
| .\" THIS SOFTWARE IS PROVIDED ``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 SOFTWARE FOUNDATION 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 Software Foundation. For more |
| .\" information on the Apache Software Foundation, 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 |
| .br |
| .B htpasswd |
| .B \-n |
| [ |
| .B \-m |
| | |
| .B \-d |
| | |
| .B \-s |
| | |
| .B \-p |
| ] |
| .I username |
| .br |
| .B htpasswd |
| .B \-nb |
| [ |
| .B \-m |
| | |
| .B \-d |
| | |
| .B \-s |
| | |
| .B \-p |
| ] |
| .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 manage usernames and passwords |
| 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 |
| \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. This option cannot be combined with |
| the \fB-n\fP option. |
| .IP \-n |
| Display the results on standard output rather than updating a file. |
| This is useful for generating password records acceptable to Apache |
| for inclusion in non-text data stores. This option changes the |
| syntax of the command line, since the \fIpasswdfile\fP argument |
| (usually the first one) is omitted. It cannot be combined with |
| the \fB-c\fP option. |
| .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 |
| on all platforms, it is not supported by the |
| .B httpd |
| server on Windows and TPF. |
| .IP \-s |
| Use SHA encryption for passwords. Facilitates 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 platforms, the |
| .B httpd |
| daemon 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. |