Apache The Definitive Guide, 3rd EditionApache: The Definitive GuideSearch this book

5.10. DBM Files on Unix

Although searching a file of usernames and passwords works perfectly well, it is apt to be rather slow once the list gets up to a couple hundred entries. To deal with this, Apache provides a better way of handling large lists by turning them into a database. You need one (not both!) of the modules that appear in the Config file as follows:

#Module db_auth_module  mod_auth_db.o 
Module dbm_auth_module mod_auth_dbm.o

Bear in mind that they correspond to different directives: AuthDBMUserFile or AuthDBUserFile. A Perl script to manage both types of database, dbmmanage, is supplied with Apache in .../src/support. To decide which type to use, you need to discover the capabilities of your Unix. Explore these by going to the command prompt and typing first:

% man db

and then:

% man dbm

Whichever method produces a manpage is the one you should use. You can also use a SQL database, employing MySQLor a third-party package to manage it.

Once you have decided which method to use, edit the Config file to include the appropriate module, and then type:

% ./Configure

and:

% make

We now have to create a database of our users: bill, ben, sonia, and daphne. Go to ... /apache/src/support, find the utility dbmmanage, and copy it into /usr/local/bin or something similar to put it on your path. This utility may be distributed without execute permission set, so, before attempting to run it, we may need to change the permissions:

% chmod +x dbmmanage

You may find, when you first try to run dbmmanage, that it complains rather puzzlingly that some unnamed file can't be found. Since dbmmanage is a Perl script, this is probably Perl, a text-handling language, and if you have not installed it, you should. It may also be necessary to change the first line of dbmmanage:

#!/usr/bin/perl5

to the correct path for Perl, if it is installed somewhere else.

If you provoke it with dbmmanage -?, you get:

Usage: dbmmanage [enc] dbname command [username [pw [group[,group] [comment]]]]

    where enc is  -d for crypt encryption (default except on Win32, Netware)
                  -m for MD5 encryption (default on Win32, Netware)
                  -s for SHA1 encryption
                  -p for plaintext

    command is one of: add|adduser|check|delete|import|update|view

    pw of . for update command retains the old password
    pw of--(or blank) for update command prompts for the password

    groups or comment of . (or blank) for update command retains old values
    groups or comment of--for update command clears the existing value
    groups or comment of--for add and adduser commands is the empty value

takes the following arguments:
dbmmanage [enc] dbname command [username [pw [group[,group] [comment]]]]

'enc' sets the encryption method:
-d for crypt (default except Win32, Netware)
-m for MD5 (default on Win32, Netware)
-s for SHA1 
-p for plaintext

So, to add our four users to a file /usr/www/APACHE3/ok_dbm/users, we type:

% dbmmanage /usr/www/APACHE3/ok_dbm/users.db adduser bill 
New password:theft
Re-type new password:theft
User bill added with password encrypted to vJACUCNeAXaQ2 using crypt

Perform the same service for ben, sonia, and daphne. The file ... /users is not editable directly, but you can see the results by typing:

% dbmmanage /usr/www/APACHE3/ok_dbm/users view
bill:vJACUCNeAXaQ2
ben:TPsuNKAtLrLSE
sonia:M9x731z82cfDo
daphne:7DBV6Yx4.vMjc

You can build a group file with dbmmanage,but because of faults in the script that we hope will have been rectified by the time readers of this edition use it, the results seem a bit odd. To add the user fred to the group cleaners, type:

% dbmmanage /usr/www/APACHE3/ok_dbm/group add fred cleaners

(Note: do not use adduser.) dbmmanagerather puzzlingly responds with the following message:

User fred added with password encrypted to cleaners using crypt

When we test this with:

% dbmmanage /usr/www/APACHE3/ok_dbm/group view

we see:

fred:cleaners

which is correct, because in a group file the name of the group goes where the encrypted password would go in a password file.

Since we have a similar file structure, we invoke DBM authentication in ... /conf/httpd.conf by commenting out:

#AuthUserFile /usr/www/APACHE3/ok_users/sales
#AuthGroupFile /usr/www/APACHE3/ok_users/groups

and inserting:

AuthDBMUserFile /usr/www/APACHE3/ok_dbm/users 
AuthDBMGroupFile /usr/www/APACHE3/ok_dbm/users

AuthDBMGroupFile is set to the samefile as the AuthDBMUserFile. What happens is that the username becomes the key in the DBM file, and the value associated with the key is password:group. To create a separate group file, a database with usernames as the key and groups as the value (with no colons in the value) would be needed.

5.10.1. AuthDBUserFile

The AuthDBUserFile directive sets the name of a DB file containing the list of users and passwords for user authentication.

AuthDBUserFile filename
directory, .htaccess

filename is the absolute path to the user file.

The user file is keyed on the username. The value for a user is the crypt( )-encrypted password, optionally followed by a colon and arbitrary data. The colon and the data following it will be ignored by the server.

5.10.1.1. Security

Make sure that the AuthDBUserFile is stored outside the document tree of the web server; do not put it in the directory that it protects. Otherwise, clients will be able to download the AuthDBUserFile.

TIP: In regards to compatibility, the implementation of dbmopen in the Apache modules reads the string length of the hashed values from the DB 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 DB files interchangeably between applications, this may be a part of the problem.

A perl script called dbmmanage is included with Apache. This program can be used to create and update DB-format password files for use with this module.

5.10.2. AuthDBMUserFile

The AuthDBMUserFile directive sets the name of a DBM file containing the list of users and passwords for user authentication.

AuthDBMUserFile filename
directory, .htaccess

filename is the absolute path to the user file.

The user file is keyed on the username. The value for a user is the crypt( )-encrypted password, optionally followed by a colon and arbitrary data. The colon and the data following it will be ignored by the server.

5.10.2.1. Security

Make sure that the AuthDBMUserFile is stored outside the document tree of the web server; do not put it in the directory that it protects. Otherwise, clients will be able to download the AuthDBMUserFile.

TIP: In regards to compatibility, 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.

A perl script called dbmmanage is included with Apache. This program can be used to create and update DBM-format password files for use with this module.



Library Navigation Links

Copyright © 2003 O'Reilly & Associates. All rights reserved.