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 Copyright 2003-2005 The Apache Software Foundation or its licensors, as
10 Licensed under the Apache License, Version 2.0 (the "License");
11 you may not use this file except in compliance with the License.
12 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="htdbm.xml.meta">
24 <parentdocument href="./">Programs</parentdocument>
26 <title>htdbm - Manipulate DBM password databases</title>
29 <p><code>htdbm</code> is used to manipulate the DBM format files used to
30 store usernames and password for basic authentication of HTTP users via
31 <module>mod_auth_dbm</module>. See the <program>dbmmanage</program>
32 documentation for more information about these DBM files.</p>
34 <seealso><program>httpd</program></seealso>
35 <seealso><program>dbmmanage</program></seealso>
36 <seealso><module>mod_auth_dbm</module></seealso>
38 <section id="synopsis"><title>Synopsis</title>
39 <p><code><strong>htdbm</strong>
40 [ -<strong>T</strong><var>DBTYPE</var> ]
41 [ -<strong>c</strong> ]
42 [ -<strong>m</strong> |
46 [ -<strong>t</strong> ]
47 [ -<strong>v</strong> ]
48 [ -<strong>x</strong> ]
49 <var>filename</var> <var>username</var></code></p>
51 <p><code><strong>htdbm</strong> -<strong>b</strong>
52 [ -<strong>T</strong><var>DBTYPE</var> ]
53 [ -<strong>c</strong> ]
54 [ -<strong>m</strong> |
58 [ -<strong>t</strong> ]
59 [ -<strong>v</strong> ]
60 <var>filename</var> <var>username</var> <var>password</var></code></p>
62 <p><code><strong>htdbm</strong> -<strong>n</strong>
63 [ -<strong>c</strong> ]
64 [ -<strong>m</strong> |
68 [ -<strong>t</strong> ]
69 [ -<strong>v</strong> ]
70 <var>username</var></code></p>
72 <p><code><strong>htdbm</strong> -<strong>nb</strong>
73 [ -<strong>c</strong> ]
74 [ -<strong>m</strong> |
78 [ -<strong>t</strong> ]
79 [ -<strong>v</strong> ]
80 <var>username</var> <var>password</var></code></p>
82 <p><code><strong>htdbm</strong> -<strong>v</strong>
83 [ -<strong>T</strong><var>DBTYPE</var> ]
84 [ -<strong>c</strong> ]
85 [ -<strong>m</strong> |
89 [ -<strong>t</strong> ]
90 [ -<strong>v</strong> ]
91 <var>filename</var> <var>username</var></code></p>
93 <p><code><strong>htdbm</strong> -<strong>vb</strong>
94 [ -<strong>T</strong><var>DBTYPE</var> ]
95 [ -<strong>c</strong> ]
96 [ -<strong>m</strong> |
100 [ -<strong>t</strong> ]
101 [ -<strong>v</strong> ]
102 <var>filename</var> <var>username</var> <var>password</var></code></p>
104 <p><code><strong>htdbm</strong> -<strong>x</strong>
105 [ -<strong>T</strong><var>DBTYPE</var> ]
106 [ -<strong>m</strong> |
107 -<strong>d</strong> |
108 -<strong>p</strong> |
109 -<strong>s</strong> ]
110 <var>filename</var> <var>username</var></code></p>
112 <p><code><strong>htdbm</strong> -<strong>l</strong>
113 [ -<strong>T</strong><var>DBTYPE</var> ]
117 <section id="options"><title>Options</title>
119 <dt><code>-b</code></dt>
120 <dd>Use batch mode; <em>i.e.</em>, get the password from the command line
121 rather than prompting for it. This option should be used with extreme care,
122 since <strong>the password is clearly visible</strong> on the command
125 <dt><code>-c</code></dt>
126 <dd>Create the <var>passwdfile</var>. If <var>passwdfile</var> already
127 exists, it is rewritten and truncated. This option cannot be combined with
128 the <code>-n</code> option.</dd>
130 <dt><code>-n</code></dt>
131 <dd>Display the results on standard output rather than updating a
132 database. This option changes the syntax of the command line, since the
133 <var>passwdfile</var> argument (usually the first one) is omitted. It
134 cannot be combined with the <code>-c</code> option.</dd>
136 <dt><code>-m</code></dt>
137 <dd>Use MD5 encryption for passwords. On Windows, Netware and TPF, this is
140 <dt><code>-d</code></dt>
141 <dd>Use <code>crypt()</code> encryption for passwords. The default on all
142 platforms but Windows, Netware and TPF. Though possibly supported by
143 <code>htdbm</code> on all platforms, it is not supported by the
144 <program>httpd</program> server on Windows, Netware and TPF.</dd>
146 <dt><code>-s</code></dt>
147 <dd>Use SHA encryption for passwords. Facilitates migration from/to Netscape
148 servers using the LDAP Directory Interchange Format (ldif).</dd>
150 <dt><code>-p</code></dt>
151 <dd>Use plaintext passwords. Though <code>htdbm</code> will support
152 creation on all platforms, the <program>httpd</program> daemon will
153 only accept plain text passwords on Windows, Netware and TPF.</dd>
155 <dt><code>-l</code></dt>
156 <dd>Print each of the usernames and comments from the database on
159 <dt><code>-t</code></dt>
160 <dd>Interpret the final parameter as a comment. When this option is
161 specified, an additional string can be appended to the command line; this
162 string will be stored in the "Comment" field of the database, associated
163 with the specified username.</dd>
165 <dt><code>-v</code></dt>
166 <dd>Verify the username and password. The program will print a message
167 indicating whether the supplied password is valid. If the password is
168 invalid, the program exits with error code 3.</dd>
170 <dt><code>-x</code></dt>
171 <dd>Delete user. If the username exists in the specified DBM file, it
172 will be deleted.</dd>
174 <dt><code><var>filename</var></code></dt>
175 <dd>The filename of the DBM format file. Usually without the extension
176 <code>.db</code>, <code>.pag</code>, or <code>.dir</code>. If
177 <code>-c</code> is given, the DBM file is created if it does not already
178 exist, or updated if it does exist.</dd>
180 <dt><code><var>username</var></code></dt>
181 <dd>The username to create or update in <var>passwdfile</var>. If
182 <var>username</var> does not exist in this file, an entry is added. If it
183 does exist, the password is changed.</dd>
185 <dt><code><var>password</var></code></dt>
186 <dd>The plaintext password to be encrypted and stored in the DBM file.
187 Used only with the <code>-b</code> flag.</dd>
189 <dt><code>-T<var>DBTYPE</var></code></dt>
190 <dd>Type of DBM file (SDBM, GDBM, DB, or "default").</dd>
194 <section id="bugs"><title>Bugs</title>
195 <p>One should be aware that there are a number of different DBM file
196 formats in existence, and with all likelihood, libraries for more than
197 one format may exist on your system. The three primary examples are
198 SDBM, NDBM, GNU GDBM, and Berkeley/Sleepycat DB 2/3/4. Unfortunately,
199 all these libraries use different file formats, and you must make sure
200 that the file format used by <var>filename</var> is the same format that
201 <code>htdbm</code> expects to see. <code>htdbm</code> currently has
202 no way of determining what type of DBM file it is looking at. If used
203 against the wrong format, will simply return nothing, or may create a
204 different DBM file with a different name, or at worst, it may corrupt
205 the DBM file if you were attempting to write to it.</p>
207 <p>One can usually use the <code>file</code> program supplied with most
208 Unix systems to see what format a DBM file is in.</p>
211 <section id="exit"><title>Exit Status</title>
212 <p><code>htdbm</code> returns a zero status ("true") if the username and
213 password have been successfully added or updated in the DBM File.
214 <code>htdbm</code> returns <code>1</code> if it encounters some problem
215 accessing files, <code>2</code> if there was a syntax problem with the
216 command line, <code>3</code> if the password was entered interactively and
217 the verification entry didn't match, <code>4</code> if its operation was
218 interrupted, <code>5</code> if a value is too long (username, filename,
219 password, or final computed record), <code>6</code> if the username
220 contains illegal characters (see the <a href="#restrictions">Restrictions
221 section</a>), and <code>7</code> if the file is not a valid DBM password
225 <section id="examples"><title>Examples</title>
227 htdbm /usr/local/etc/apache/.htdbm-users jsmith
230 <p>Adds or modifies the password for user <code>jsmith</code>. The user
231 is prompted for the password. If executed on a Windows system, the password
232 will be encrypted using the modified Apache MD5 algorithm; otherwise, the
233 system's <code>crypt()</code> routine will be used. If the file does not
234 exist, <code>htdbm</code> will do nothing except return an error.</p>
237 htdbm -c /home/doe/public_html/.htdbm jane
240 <p>Creates a new file and stores a record in it for user <code>jane</code>.
241 The user is prompted for the password. If the file exists and cannot be
242 read, or cannot be written, it is not altered and <code>htdbm</code>
243 will display a message and return an error status.</p>
246 htdbm -mb /usr/web/.htdbm-all jones Pwd4Steve
249 <p>Encrypts the password from the command line (<code>Pwd4Steve</code>)
250 using the MD5 algorithm, and stores it in the specified file.</p>
253 <section id="security"><title>Security Considerations</title>
254 <p>Web password files such as those managed by <code>htdbm</code> should
255 <em>not</em> be within the Web server's URI space -- that is, they should
256 not be fetchable with a browser.</p>
258 <p>The use of the <code>-b</code> option is discouraged, since when it is
259 used the unencrypted password appears on the command line.</p>
262 <section id="restrictions"><title>Restrictions</title>
263 <p>On the Windows and MPE platforms, passwords encrypted with
264 <code>htdbm</code> are limited to no more than <code>255</code>
265 characters in length. Longer passwords will be truncated to 255
268 <p>The MD5 algorithm used by <code>htdbm</code> is specific to the Apache
269 software; passwords encrypted using it will not be usable with other Web
272 <p>Usernames are limited to <code>255</code> bytes and may not include the
273 character <code>:</code>.</p>