| <?xml version='1.0' encoding='UTF-8' ?> |
| <!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd"> |
| <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?> |
| <!-- $LastChangedRevision$ --> |
| |
| <!-- |
| 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. |
| --> |
| |
| <manualpage metafile="dbmmanage.xml.meta"> |
| <parentdocument href="./">Programs</parentdocument> |
| |
| <title>dbmmanage - Manage user authentication files in DBM format</title> |
| |
| <summary> |
| <p><code>dbmmanage</code> is used to create and update the DBM format files |
| used to store usernames and password for basic authentication of HTTP users |
| via <module>mod_authn_dbm</module>. |
| Resources available from the Apache HTTP server can be restricted to just |
| the users listed in the files created by <code>dbmmanage</code>. This |
| program can only be used when the usernames are stored in a DBM file. To |
| use a flat-file database see <program>htpasswd</program>.</p> |
| |
| <p>Another tool to maintain a DBM password database is |
| <program>htdbm</program>.</p> |
| |
| <p>This manual page only lists the command line arguments. For details of |
| the directives necessary to configure user authentication in |
| <program>httpd</program> see the httpd manual, which is part of |
| the Apache distribution or can be found at <a |
| href="http://httpd.apache.org/">http://httpd.apache.org/</a>.</p> |
| </summary> |
| <seealso><program>httpd</program></seealso> |
| <seealso><program>htdbm</program></seealso> |
| <seealso><module>mod_authn_dbm</module></seealso> |
| <seealso><module>mod_authz_dbm</module></seealso> |
| |
| <section id="synopsis"><title>Synopsis</title> |
| <p><code><strong>dbmmanage</strong> [ <var>encoding</var> ] |
| <var>filename</var> add|adduser|check|delete|update |
| <var>username</var> |
| [ <var>encpasswd</var> |
| [ <var>group</var>[,<var>group</var>...] |
| [ <var>comment</var> ] ] ]</code></p> |
| |
| <p><code><strong>dbmmanage</strong> <var>filename</var> |
| view [ <var>username</var> ]</code></p> |
| |
| <p><code><strong>dbmmanage</strong> <var>filename</var> import</code></p> |
| </section> |
| |
| <section id="options"><title>Options</title> |
| <dl> |
| <dt><code><var>filename</var></code></dt> |
| <dd>The filename of the DBM format file. Usually without the extension |
| <code>.db</code>, <code>.pag</code>, or <code>.dir</code>.</dd> |
| |
| <dt><code><var>username</var></code></dt> |
| <dd>The user for which the operations are performed. The <var>username</var> |
| may not contain a colon (<code>:</code>).</dd> |
| |
| <dt><code><var>encpasswd</var></code></dt> |
| <dd>This is the already encrypted password to use for the |
| <code>update</code> and <code>add</code> commands. You may use a hyphen |
| (<code>-</code>) if you want to get prompted for the password, but fill |
| in the fields afterwards. Additionally when using the <code>update</code> |
| command, a period (<code>.</code>) keeps the original password |
| untouched.</dd> |
| |
| <dt><code><var>group</var></code></dt> |
| <dd>A group, which the user is member of. A groupname may not contain a |
| colon (<code>:</code>). You may use a hyphen (<code>-</code>) if you don't |
| want to assign the user to a group, but fill in the comment field. |
| Additionally when using the <code>update</code> command, a period |
| (<code>.</code>) keeps the original groups untouched.</dd> |
| |
| <dt><code><var>comment</var></code></dt> |
| <dd>This is the place for your opaque comments about the user, like |
| realname, mailaddress or such things. The server will ignore this |
| field.</dd> |
| </dl> |
| |
| <section id="options.encodings"><title>Encodings</title> |
| <dl> |
| <dt><code>-d</code></dt> |
| <dd>crypt encryption (default, except on Win32, Netware)</dd> |
| |
| <dt><code>-m</code></dt> |
| <dd>MD5 encryption (default on Win32, Netware)</dd> |
| |
| <dt><code>-s</code></dt> |
| <dd>SHA1 encryption</dd> |
| |
| <dt><code>-p</code></dt> |
| <dd>plaintext (<em>not recommended</em>)</dd> |
| </dl> |
| </section> |
| |
| <section id="options.commands"><title>Commands</title> |
| <dl> |
| <dt><code>add</code></dt> |
| <dd>Adds an entry for <var>username</var> to <var>filename</var> using the |
| encrypted password <var>encpasswd</var>. |
| |
| <example>dbmmanage passwords.dat add rbowen foKntnEF3KSXA</example> |
| </dd> |
| |
| <dt><code>adduser</code></dt> |
| <dd>Asks for a password and then adds an entry for <var>username</var> to |
| <var>filename</var>. |
| |
| <example>dbmmanage passwords.dat adduser krietz</example> |
| </dd> |
| |
| <dt><code>check</code></dt> |
| <dd>Asks for a password and then checks if <var>username</var> is in |
| <var>filename</var> and if it's password matches the specified one. |
| |
| <example>dbmmanage passwords.dat check rbowen</example> |
| </dd> |
| |
| <dt><code>delete</code></dt> |
| <dd>Deletes the <var>username</var> entry from <var>filename</var>. |
| |
| <example>dbmmanage passwords.dat delete rbowen</example> |
| </dd> |
| |
| <dt><code>import</code></dt> |
| <dd>Reads <code><var>username</var>:<var>password</var></code> entries |
| (one per line) from <code>STDIN</code> and adds them to |
| <var>filename</var>. The passwords already have to be crypted.</dd> |
| |
| <dt><code>update</code></dt> |
| <dd>Same as the <code>adduser</code> command, except that it makes |
| sure <var>username</var> already exists in <var>filename</var>. |
| |
| <example>dbmmanage passwords.dat update rbowen</example> |
| </dd> |
| |
| <dt><code>view</code></dt> |
| <dd>Just displays the contents of the DBM file. If you specify a |
| <var>username</var>, it displays the particular record only. |
| |
| <example>dbmmanage passwords.dat view</example> |
| </dd> |
| </dl> |
| </section> |
| </section> |
| |
| <section id="bugs"><title>Bugs</title> |
| <p>One should be aware that there are a number of different DBM file formats |
| in existence, and with all likelihood, libraries for more than one format |
| may exist on your system. The three primary examples are SDBM, NDBM, the GNU |
| project's GDBM, and Berkeley DB 2. Unfortunately, all these libraries use |
| different file formats, and you must make sure that the file format used |
| by <var>filename</var> is the same format that <code>dbmmanage</code> |
| expects to see. <code>dbmmanage</code> currently has no way of determining |
| what type of DBM file it is looking at. If used against the wrong format, |
| will simply return nothing, or may create a different DBM file with a |
| different name, or at worst, it may corrupt the DBM file if you were |
| attempting to write to it.</p> |
| |
| <p><code>dbmmanage</code> has a list of DBM format preferences, defined by |
| the <code>@AnyDBM::ISA</code> array near the beginning of the program. Since |
| we prefer the Berkeley DB 2 file format, the order in which |
| <code>dbmmanage</code> will look for system libraries is Berkeley DB 2, |
| then NDBM, then GDBM and then SDBM. The first library found will be the |
| library <code>dbmmanage</code> will attempt to use for all DBM file |
| transactions. This ordering is slightly different than the standard |
| <code>@AnyDBM::ISA</code> ordering in Perl, as well as the ordering used by |
| the simple <code>dbmopen()</code> call in Perl, so if you use any other |
| utilities to manage your DBM files, they must also follow this preference |
| ordering. Similar care must be taken if using programs in other languages, |
| like C, to access these files.</p> |
| |
| <p>One can usually use the <code>file</code> program supplied with most |
| Unix systems to see what format a DBM file is in.</p> |
| </section> |
| |
| </manualpage> |