# DBM Files for User Authentication

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.