HTTPD::UserAdmin(3)

NAME
HTTPD::UserAdmin - Management of HTTP server user databases

SYNOPSIS
    use 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 whose database is a plain text file named '.htpasswd', in a format that the NCSA server understands.

        @SQL =  (DBType =>    "SQL",
                 Host =>      "",             #server hostname
                 Port =>      "",             #server port
                 DB =>        "www",          #database name
                 User =>      "",             #database login name
                 Auth =>      "",             #database login password
                 Encrypt =>   "crypt",        #encryption method
                 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', 'MD5', or 'none' (no encryption. 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

    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.

    Specific to DBM files:

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

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

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

    Host - Server hostname

    Port - Server port

    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,[@fields])
add($username,$password,\%fields)
    Add a user.

    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');

    You can also pass a set of field name/value pairs in the form of a hash ref. Example

       $user->add('JoeUser','try2guess','',
                            {'Name'=>'Joseph A. User','Credit_limit'=>2000});

delete($username)
    Delete a user

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

suspend($username)
    Suspend a user

        if($user->suspend('dougm')) {
            print "Account suspended\n";
        }

unsuspend($username)
    Unsuspend a suspended user

        if($user->unsuspend('dougm')) {
            print "Account restored to normal\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.

fetch($username,@fields)
        Fetch a list of field values from the indicated user.  Field names may
        be provided as a list or as an array reference.  The return value is a
        reference to a hash containing the field/value pairs.

list()
    Returns a list of usernames in the current database

        @users = $user->list

update($username,$password)
update($username,$password,\%fields) SQL only
    Update $username with a new $password

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

    With SQL servers, you can update other fields in the table by passing a hash reference:

           $user->update('dougm','idunno',{'credit_limit'=>1000});

    An undefined value in the password field will leave the field unchanged.

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])
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\";

flags([$flags])
    Get or set read, write, create flags.

commit
    Commit changes to disk (for Text files).

Message Digest User Databases
Currently, you can store user info in a format for servers who support 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(3), HTTPD::Authen(3)

AUTHOR
Doug MacEachern <dougm@osf.org>

Copyright (c) 1996, Doug MacEachern

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