- Purpose
- It dramatically reduces the lookup time for a password for areas
under user authentication, where the user database is larger than a
couple hundred entries. This is what HotWired uses for its 150,000+
user database.
You can use new directives to replace a password file with a DBM. You can
also replace a group file with DBM, or combine the two. You can use other
fields in the DBM to store other user details.
- Old behaviour
- User/password lookups would search through a flat file - if that
flat file grew to more than a couple hundred entries that search would
take an unacceptibly long time. This search would occur every time
a protected page was accessed.
- New behaviour
- Provided by the mod_auth module.
DBM files, native to most Unix platform, are an implementation of
a self-maintaining hash table, where a given key maps to a stored
value. DBM files are not ascii, and not portable between operating
systems, but there is a perl tool called "dbmmanage" in the /support
directory included with the apache distribution to modify and view
(and even add a user, automatically encrypting their password) DBM
files. Apache's version uses the "ndbm" library - there are other
libraries, but this was chosen as it's the one implemented on most
systems and the one Perl uses by default when binding a DBM file to an
associative array. Be sure you are using ndbm and not GNU's "gdbm" if
you run into trouble.
On some systems, when you open a DBM file named "filename", it will
actually create two files, "filename.dir" and "filename.pag". Other
systems will create a "filename.db". For the purposes of this
documentation, when we refer to a DBM filename, it's to the root name,
i.e. "filename". The "keys" of the DBM file are the usernames, and
the "values" mapped to those keys are the encrypted passwords.
- Configuration
- To activate it, you might have to compile it with -lndbm set in
the EXTRA_LIBS variable in the Configuration file. You also need to
uncomment the line in the Configuration file:
Module dbm_auth_module mod_auth_dbm.o
- Syntax: User File
-
This module creates a new directive,
"AuthDBMUserFile",
which can be dropped in place of
"AuthUserFile" in your
configuration file or .htaccess files. The argument to that directive is the
DBM filename.
I.e.
AuthDBMUserFile /www/passwords
These passwords are encrypted using standard Unix crypt(), which the
utility "dbmmanage" can handle with the "adduser" option.
Each entry in a DBM file has a key and a value. For the password file
the key is the username. The value is the standard Unix crypt()
password. The value field can also contain other data which is
ignored during password checks; this data must be separated from the
password with a colon character (":")
The "dbmmanage" utility supplied with Apache can be used to add and
remove users and encrypt passwords.
- Syntax: Group File
-
A new keyword, "AuthDBMGroupFile", can be
dropped in place of
"AuthGroupFile" in your
configuration or .htaccess files. The argument to that keyword is the DBM
filename.
I.e.
AuthDBMGroupFile /www/groups
Each entry in a DBM file has a key and a value. For the group file
the key is the username. The value is a list of group names that
user is a member of; separated from each other with commas (,).
Note that there must be no whitespace within the value and the value must
never contain any colon characters (:).
- Important Note:
- Versions of Apache up to and including 0.8.14
will crash with this format of group file. To use group files with an
earlier version the DBM value needs to have a colon inserted before the
list of groups for each user. I.e. use ":admin" instead of "admin".
- Combining Group and Password DBM files
-
In some cases it is easier to manage a single database which contains
both the password and group details for each user. This simplifies any
support programs that need to be written: they now only have to deal with
writing to and locking a single DBM file. This can be accomplished by
first setting the group and password files to point to the same DBM.
AuthDBMGroupFile /www/userbase
AuthDBMUserFile /www/userbase
The key for the single DBM is the username. The value consists of
Unix Crypted Password : List of Groups [ : (ignored) ]
The password section contains the Unix crypt() password as before. This
is followed by a colon and the comma separated list of groups. Other
data may optionally be left in the DBM file after another colon; it
is ignored by the authentication module.
This is what telescope.org
uses for its combined password and group database.
- Important compatibility note:
- The implementation of "dbmopen" in the apache modules reads the
string length of the hashed values from the dbm data structures,
rather than relying upon the string being NULL-appended. Some
applications, such as the Netscape web server, rely upon the string
being NULL-appended, so if you are having trouble using dbm files
interchangeably between applications this may be a part of the
problem.
