| .TH htpasswd 1 "February 2004" |
| .\" Licensed to the Apache Software Foundation (ASF) under one or more |
| .\" contributor license agreements. See the NOTICE file distributed with |
| .\" this work for additional information regarding copyright ownership. |
| .\" The ASF licenses this file to You under the Apache License, Version 2.0 |
| .\" (the "License"); you may not use this file except in compliance with |
| .\" the License. You may obtain a copy of the License at |
| .\" |
| .\" http://www.apache.org/licenses/LICENSE-2.0 |
| .\" |
| .\" Unless required by applicable law or agreed to in writing, software |
| .\" distributed under the License is distributed on an "AS IS" BASIS, |
| .\" WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| .\" See the License for the specific language governing permissions and |
| .\" limitations under the License. |
| .\" |
| .SH NAME |
| htpasswd \- Create and update user authentication files |
| .SH SYNOPSIS |
| .B htpasswd |
| [ |
| .B \-c |
| ] |
| [ |
| .B \-m |
| | |
| .B \-d |
| | |
| .B \-s |
| | |
| .B \-p |
| ] |
| .I passwdfile |
| .I username |
| .br |
| .B htpasswd |
| .B \-b |
| [ |
| .B \-c |
| ] |
| [ |
| .B \-m |
| | |
| .B \-d |
| | |
| .B \-s |
| | |
| .B \-p |
| ] |
| .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://httpd.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 Apache's modified MD5 algorithm for passwords. Passwords encrypted |
| with this algorithm are transportable to any platform (Windows, Unix, |
| BeOS, et cetera) running Apache 1.3.9 or later. On Windows and TPF, |
| this flag 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. 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 platforms, 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. |
