/ 
HTTPD-Tools-0.52
/ HTTPD::UserAdmin

NAME

HTTPD::UserAdmin - Management of HTTP server user databases

SYNOPSIS

require HTTPD::UserAdmin

DESCRIPTION

This software is meant to provide a generic interface that hides the inconsistencies across HTTP server implementations of user and group databases.

METHODS

new ()

Here's where we find out what's different about your server.

Some examples:

    @DBM = (DBType => 'DBM',
	    DB     => '.htpasswd',
	    Server => 'apache');

    $user = new HTTPD::UserAdmin @DBM;

This creates an object who's database is a DBM file named '.htpasswd', in a format that the Apache server understands.

    @Text = (DBType => 'Text',
	     DB     => '.htpasswd',
	     Server => 'ncsa');

    $user = new HTTPD::UserAdmin @Text;

This creates an object who's database is a plain text file named '.htpasswd', in a format that the NCSA server understands.

    @SQL =  (DBType =>    "SQL",          
	     Host =>      "",             #server hostname 
	     DB =>        "www",          #database name
	     User =>      "", 	  	  #database login name	    
	     Auth =>      "",             #database login password
	     Driver =>    "mSQL",         #driver for DBI
	     Server =>    "apache",       #HTTP server type, not required
	     UserTable => "www-users",    #table with field names below
	     NameField => "user",         #field for the name
	     PasswordField => "password", #field for the password
	     );

    $user = new HTTPD::UserAdmin @SQL;

This creates an object who's mSQL database is named 'www', with a schema that the Apache server (extention) understands.

Full list of constructor attributes:

Note: Attribute names are case-insensitive

DBType - The type of database, one of 'DBM', 'Text', or 'SQL' (Default is 'DBM')

DB - The database name (Default is '.htpasswd' for DBM & Text databases)

Server - HTTP server name (Default is the generic class, that works with NCSA, Apache and possibly others)

Note: run 'perl t/support.t matrix' to see what support is currently availible

Encrypt - One of 'crypt' or 'MD5', defaults to 'crypt'

Locking - Boolean, Lock Text and DBM files (Default is true)

Path - Relative DB files are resolved to this value (Default is '.')

Debug - Boolean, Turn on debug mode

Specific to DBM files:

DBMF - The DBM file implementation to use (Default is 'NDBM')

Flags - The read, write and create flags. There are four modes: rwc - the default, open for reading, writing and creating. rw - open for reading and writing. r - open for reading only. w - open for writing only.

Mode - The file creation mode, defaults to '0644'

Specific to DBI: We talk to an SQL server via Tim Bunce's DBI switch, for more info see: http://www.hermetica.com/technologia/DBI/

Host - Server hostname

User - Database login name

Auth - Database login password

Driver - Driver for DBI (Default is 'mSQL')

UserTable - Table with field names below

NameField - Field for the name (Default is 'user')

PasswordField - Field for the password (Default is 'password')

From here on out, things should look the same for everyone.

add($username,$password[,$noenc,@fields])

Add a user.

If $noenc is true, the password is not encrypted, useful for copying/converting, or if you just prefer to store passwords in plain text.

Fails if $username exists in the database

    if($user->add('dougm', 'secret')) {
	print "You have the power!\n";
    }

You may need to pass additional fields, such as the user's real name. This depends on your server of course.

$user->add('JoeUser', 'try2guess', '', 'Joseph A. User');

delete($username)

Delete a user

    if($user->delete('dougm')) {
	print "He's gone\n";
    }

exists($username)

True if $username is found in the database

    if($user->exists('dougm')) {
	die "oh no!";
    }

password()

Returns the encrypted password for a user

$passwd = $user->password("dougm");

Useful for copying users to another database.

list()

Returns a list of usernames in the current database

@users = $user->list

update($username,$password)

Update $username with a new $password

    if($user->update('dougm', 'idunno')) {
	print "Updated\n";
    }

group()

Short cut for creating an HTTPD::GroupAdmin object. All applicable attributes are inherited, but can be overridden.

$group = $user->group(NAME => 'www-group');

(See HTTPD::GroupAdmin)

convert(@Attributes)

Convert a database.

$dbmuser = $user->convert(@Apache);

lock([$timeout]) =head2 unlock()

These methods give you control of the locking mechanism.

$user = new HTTPD::UserAdmin (Locking => 0); #turn off auto-locking
$user->lock; #lock the object's database
$user->add($username,$passwd); #write while file is locked
$user->unlock; release the lock

db($dbname);

Select a different database.

$olddb = $user->db($newdb);
print "Now we're reading and writing '$newdb', done with '$olddb'n\";

Message Digest User Databases

Currently, you can store user info in a format for servers who understand Message Digest Authentication. Here's an example:

$user = new HTTPD::UserAdmin (DB => '.htdigest', Encrypt => 'MD5');

($username,$realm,$password) = ('JoeUser', 'SomePlace', '14me');


#The checksum contains more info that just a password
$user->add($username, "$username:$realm:$password");
$user->update($username, "$username:$realm:newone");


$info = $user->password($username);
($realm, $checksum) = split(":", $info);

$user->delete($username);

See <URL:http://hoohoo.ncsa.uiuc.edu/docs/howto/md5_auth.html> for NCSA's implementation.

So, it's a little more work, but don't worry, a nicer interface is on the way.

SEE ALSO

HTTPD::GroupAdmin, HTTPD::Authen

AUTHOR

Doug MacEachern <dougm@osf.org>

Copyright (c) 1996, Doug MacEachern, OSF Research Institute

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.