1 <?xml version='1.0' encoding='UTF-8' ?>
2 <!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
4 <!-- $LastChangedRevision$ -->
7 Licensed to the Apache Software Foundation (ASF) under one or more
8 contributor license agreements. See the NOTICE file distributed with
9 this work for additional information regarding copyright ownership.
10 The ASF licenses this file to You under the Apache License, Version 2.0
11 (the "License"); you may not use this file except in compliance with
12 the License. You may obtain a copy of the License at
14 http://www.apache.org/licenses/LICENSE-2.0
16 Unless required by applicable law or agreed to in writing, software
17 distributed under the License is distributed on an "AS IS" BASIS,
18 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19 See the License for the specific language governing permissions and
20 limitations under the License.
23 <manualpage metafile="htpasswd.xml.meta">
24 <parentdocument href="./">Programs</parentdocument>
26 <title>htpasswd - Manage user files for basic authentication</title>
29 <p><code>htpasswd</code> is used to create and update the flat-files used to
30 store usernames and password for basic authentication of HTTP users. If
31 <code>htpasswd</code> cannot access a file, such as not being able to write
32 to the output file or not being able to read the file in order to update it,
33 it returns an error status and makes no changes.</p>
35 <p>Resources available from the Apache HTTP server can be restricted to
36 just the users listed in the files created by <code>htpasswd</code>. This
37 program can only manage usernames and passwords stored in a flat-file. It
38 can encrypt and display password information for use in other types of data
39 stores, though. To use a DBM database see <program>dbmmanage</program>.</p>
41 <p><code>htpasswd</code> encrypts passwords using either a version of MD5
42 modified for Apache, or the system's <code>crypt()</code> routine. Files
43 managed by <code>htpasswd</code> may contain both types of passwords; some
44 user records may have MD5-encrypted passwords while others in the same file
45 may have passwords encrypted with <code>crypt()</code>.</p>
47 <p>This manual page only lists the command line arguments. For details of
48 the directives necessary to configure user authentication in
49 <program>httpd</program> see the Apache manual, which is part of the
50 Apache distribution or can be found at <a href="http://httpd.apache.org"
51 >http://httpd.apache.org/</a>.</p>
53 <seealso><program>httpd</program></seealso>
54 <seealso>The scripts in support/SHA1 which come with the
55 distribution.</seealso>
57 <section id="synopsis"><title>Synopsis</title>
58 <p><code><strong>htpasswd</strong>
59 [ -<strong>c</strong> ]
60 [ -<strong>m</strong> ]
61 [ -<strong>D</strong> ] <var>passwdfile</var> <var>username</var></code></p>
63 <p><code><strong>htpasswd</strong> -<strong>b</strong>
64 [ -<strong>c</strong> ]
65 [ -<strong>m</strong> |
69 [ -<strong>D</strong> ] <var>passwdfile</var> <var>username</var>
70 <var>password</var></code></p>
72 <p><code><strong>htpasswd</strong> -<strong>n</strong>
73 [ -<strong>m</strong> |
76 -<strong>p</strong> ] <var>username</var></code></p>
78 <p><code><strong>htpasswd</strong> -<strong>nb</strong>
79 [ -<strong>m</strong> |
82 -<strong>p</strong> ] <var>username</var> <var>password</var></code></p>
85 <section id="options"><title>Options</title>
87 <dt><code>-b</code></dt>
88 <dd>Use batch mode; <em>i.e.</em>, get the password from the command line
89 rather than prompting for it. This option should be used with extreme care,
90 since <strong>the password is clearly visible</strong> on the command
93 <dt><code>-c</code></dt>
94 <dd>Create the <var>passwdfile</var>. If <var>passwdfile</var> already
95 exists, it is rewritten and truncated. This option cannot be combined with
96 the <code>-n</code> option.</dd>
98 <dt><code>-n</code></dt>
99 <dd>Display the results on standard output rather than updating a file.
100 This is useful for generating password records acceptable to Apache for
101 inclusion in non-text data stores. This option changes the syntax of the
102 command line, since the <var>passwdfile</var> argument (usually the first
103 one) is omitted. It cannot be combined with the <code>-c</code> option.</dd>
105 <dt><code>-m</code></dt>
106 <dd>Use MD5 encryption for passwords. On Windows, Netware and TPF, this is
109 <dt><code>-d</code></dt>
110 <dd>Use <code>crypt()</code> encryption for passwords. The default on all
111 platforms but Windows, Netware and TPF. Though possibly supported by
112 <code>htpasswd</code> on all platforms, it is not supported by the
113 <program>httpd</program> server on Windows, Netware and TPF.</dd>
115 <dt><code>-s</code></dt>
116 <dd>Use SHA encryption for passwords. Facilitates migration from/to Netscape
117 servers using the LDAP Directory Interchange Format (ldif).</dd>
119 <dt><code>-p</code></dt>
120 <dd>Use plaintext passwords. Though <code>htpasswd</code> will support
121 creation on all platforms, the <program>httpd</program> daemon will
122 only accept plain text passwords on Windows, Netware and TPF.</dd>
124 <dt><code>-D</code></dt>
125 <dd>Delete user. If the username exists in the specified htpasswd file, it
126 will be deleted.</dd>
128 <dt><code><var>passwdfile</var></code></dt>
129 <dd>Name of the file to contain the user name and password. If
130 <code>-c</code> is given, this file is created if it does not already exist,
131 or rewritten and truncated if it does exist.</dd>
133 <dt><code><var>username</var></code></dt>
134 <dd>The username to create or update in <var>passwdfile</var>. If
135 <var>username</var> does not exist in this file, an entry is added. If it
136 does exist, the password is changed.</dd>
138 <dt><code><var>password</var></code></dt>
139 <dd>The plaintext password to be encrypted and stored in the file. Only
140 used with the <code>-b</code> flag.</dd>
144 <section id="exit"><title>Exit Status</title>
145 <p><code>htpasswd</code> returns a zero status ("true") if the username and
146 password have been successfully added or updated in the
147 <var>passwdfile</var>. <code>htpasswd</code> returns <code>1</code> if it
148 encounters some problem accessing files, <code>2</code> if there was a
149 syntax problem with the command line, <code>3</code> if the password was
150 entered interactively and the verification entry didn't match,
151 <code>4</code> if its operation was interrupted, <code>5</code> if a value
152 is too long (username, filename, password, or final computed record),
153 <code>6</code> if the username contains illegal characters (see the
154 <a href="#restrictions">Restrictions section</a>), and <code>7</code>
155 if the file is not a valid password file.</p>
158 <section id="examples"><title>Examples</title>
160 htpasswd /usr/local/etc/apache/.htpasswd-users jsmith
163 <p>Adds or modifies the password for user <code>jsmith</code>. The user
164 is prompted for the password. If executed on a Windows system, the password
165 will be encrypted using the modified Apache MD5 algorithm; otherwise, the
166 system's <code>crypt()</code> routine will be used. If the file does not
167 exist, <code>htpasswd</code> will do nothing except return an error.</p>
170 htpasswd -c /home/doe/public_html/.htpasswd jane
173 <p>Creates a new file and stores a record in it for user <code>jane</code>.
174 The user is prompted for the password. If the file exists and cannot be
175 read, or cannot be written, it is not altered and <code>htpasswd</code>
176 will display a message and return an error status.</p>
179 htpasswd -mb /usr/web/.htpasswd-all jones Pwd4Steve
182 <p>Encrypts the password from the command line (<code>Pwd4Steve</code>)
183 using the MD5 algorithm, and stores it in the specified file.</p>
186 <section id="security"><title>Security Considerations</title>
187 <p>Web password files such as those managed by <code>htpasswd</code> should
188 <em>not</em> be within the Web server's URI space -- that is, they should
189 not be fetchable with a browser.</p>
191 <p>This program is not safe as a setuid executable. Do <em>not</em> make it
194 <p>The use of the <code>-b</code> option is discouraged, since when it is
195 used the unencrypted password appears on the command line.</p>
197 <p>When using the <code>crypt()</code> algorithm, note that only the first
198 8 characters of the password are used to form the password. If the supplied
199 password is longer, the extra characters will be silently discarded.</p>
201 <p>The SHA encryption format does not use salting: for a given password,
202 there is only one encrypted representation. The <code>crypt()</code> and
203 MD5 formats permute the representation by prepending a random salt string,
204 to make dictionary attacks against the passwords more difficult.</p>
207 <section id="restrictions"><title>Restrictions</title>
208 <p>On the Windows and MPE platforms, passwords encrypted with
209 <code>htpasswd</code> are limited to no more than <code>255</code>
210 characters in length. Longer passwords will be truncated to 255
213 <p>The MD5 algorithm used by <code>htpasswd</code> is specific to the Apache
214 software; passwords encrypted using it will not be usable with other Web
217 <p>Usernames are limited to <code>255</code> bytes and may not include the
218 character <code>:</code>.</p>