|Type||This directive specifies the database type. It can be any of text, DBM, DB, or SQL. Although these are the only databases currently recognized by Apache, other Unix DBM-like formats, including GDBM, and SDBM are recognized for future compatibility. You may use MSQL as an alias for SQL.|
|Authentication||This directives specifies the type of authentication to use. It can be either Basic or Digest.|
This is the path to the file or database table that holds user names
and passwords. For everything but SQL databases, its a physical path
to a file on your system. If the database file doesnt exist (and the
process has sufficient privileges), it will be created. For example:
For mSQL databases, the value of the directive should have the format:
The value of table is the name of the table in which to look for the user. The value of uid and password are the fields in which Apache will look for the user ID and password. For lookup efficiency, the uid field should be defined as the primary key field in mSQL.
You may optionally place a colon and field width after any of the table names. These field widths are used as hints by the user_manage script to create a nicely-laid out fill-out form. If not provided, reasonable defaults are assumed
Heres an example of a valid directive in which the user ID field is given a width of 40:
This is the path to the file or database table that holds group
assignments. If you dont need groups, just leave the directive out.
For everything but MSQL databases, the argument physical path to a
file on your system. If the database file doesnt exist (and the
process has sufficient privileges), it will be created. For example:
For mSQL databases, the directive points to a previously-defined table and field in the database in the format
The value of table is the name of the table in which to look up the user. The value of group is the field in which Apache find the group that the user belongs to. Apache will look for the user name in the same field as declared in the Users directive, so dont declare another uid field here. You can use the same table for both Users and Groups, or use separate ones. In the latter case, you can have several records for each user, allowing the one user to belong to multiple groups.
As for the User directive, you can provide an optional field width for the group field when using mSQL databases.
|Database||This directive is valid for SQL databases only and indicates where the authentication database can be found. It should be in the format database@host. If the hostname is omitted, localhost is assumed. For mSQL databases, performance will be much better if database and Web server are on the same machine because in this case, the client and server use a Unix socket to communicate rather than a TCP/IP socket.|
Web servers differ slightly in the format of the users and groups
databases. This directive indicates which server you are using.
Recognized values include apache, ncsa, cern and netscape.
If no server is specified, apache is assumed. If your server is not on this list, try ncsa.
|Driver||For SQL databases only, this directive specifies what DBD (database driver) module to use. It defaults to mSQL. You can use any database for which a DBD module is available. You must also, of course, compile and configure the Web server to correctly use the driver.|
This directive lists other fields that can be found in the user table.
These fields can then be read and set automatically by the user_manage
application. Note that this works reliably in SQL databases only.
Large fields, or fields that contain the = character, will fail when
applied to text or DBM files.
This directive expects a list of field names in the format name[:type][width]. The field type and width are hints used by the user_manage application to format the field values correctly. The type can be one of i, for an integer value, s for a string value and f for a floating point number. If not specified, the field is assumed to be of type string. The field value must be an integer.
In this example, we define three fields named Name, Age and Paid. The first is a string value of default length. The second is an integer. The third is a string of length one (its assumed to be a Y or N):
|Mode||This directive sets the mode that Realm.pm will use to create the database files, if it needs to. The mode should be in octal form. This value can be overriden with the -mode argument in the connect() method. The default is 0644 (-rw-rr--).|
|Default||If this directive is present, the current realm becomes the default to use when no realm is explicitly indicated. If no section in the configuration file contains this directive, the first defined realm becomes the default. It is a fatal error for Default to appear in more than one section.|
There are two closely tied classes in Realm.pm. HTTPD::Realm parses the configuration file, maintains lists of realms, responds to inquiries about realms, and opens up connections to realms underlying databases. HTTPD::RealmDef defines the object that holds information about a particular realm.
new() $realms = HTTPD::Realm->new(-config=>/path/to/config/file);
Create a new set of realm definitions from the given configuration file.
exists() $exists = $realms->exists(-realm=>subscribers);
-realm Name of the realm.
An alternative form is to use the name of the realm without the named argument:
$exists = $realms->exists(subscribers);
list() @realms = $realms->list();
Returns the list of realm names defined in the configuration file.
realm() $realmdef = $realms->realm(-realm=>subscribers);
Returns the RealmDef object that defines the realm. See the discussion below for more details. An alternative form is to use the name of the realm alone:
$realmdef = $realms->realm(subscribers);
connect() $database = $realms->connect(-realm=>subscribers, -writable=>1, -mode=>0600);
Connect to the named realm, returning a database handle (actually, a RealmManager object). Recognized named arguments are:
-realm Name of the realm. -mode Mode with which to create file, if necessary. -writable Whether this realm is to be writable.
By default, realms are opened read-only. If you choose to open it for writing, you can provide a mode for creting the file, overriding the mode defined in the configuration file. If the realm is not listed in the configuration file, this routine returns undef.
new() $realmdef = HTTPD::RealmDef->new(subscribers);
Create a new RealmDef and assign it a name. This method is usually called internally.
name() $name = $realmdef->name();
Return the name of this realm.
userdb() $userdata = $realmdef->userdb();
Return the path to the user database defined in the configuration file. For non-SQL databases, this is the path to the database or text file. For SQL databases, this is the table and field definition line. You can get a pre-parsed version of this information using SQLdata(), see below.
groupdb() $groupdata = $realmdef->groupdb();
Return the path to the group database defined in the configuration file. For non-SQL databases, this is the path to the database or text file. For SQL databases, this is the table and field definition line. You can get a pre-parsed version of this information using SQLdata(),
mode() $mode = $realmdef->mode();
Return the mode for creating the database file.
database() $database = $realmdef->database();
Return the database name and host (SQL databases only).
Return the additional field definition line (SQL databases only). No additional parsing is performed.
usertype() $type = $realmdef->usertype();
Return the type of the user/password database, for example NDBM.
grouptype() $type = $realmdef->grouptype();
Return the type of the group database, for example NDBM.
authentication() $authentication = $realmdef->authentication();
Returns the authentication in use for this realm. May be either Basic or Digest.
server() $server = $realmdef->server();
Return the type of Web server this realm is designed for.
crypt() $crypt = $realmdef->crypt();
Return the cryptography type for this realm, either crypt or MD5.
SQLdata() $data = $realmdef->SQLdata();
For SQL databases only, return the parsed information from the Users and Groups directives. The value returned is an associative array containing the following fields:
database name of the SQL database host name of the SQL database host dblogin dbpassword usertable name of the SQL table containing users & passwords grouptable name of the SQL table containing groups userfield name of the field containing the user ID groupuserfield groupfield name of the field containing the group name passwdfield name of the field containing the encrypted password userfield_len length of the user ID field groupfield_len length of the group field passwdfield_len length of the password field
connect() $database = $realmdef->connect(-writable=>1, -mode=>0600, -server=>ncsa);
Establish a connection to the realm database, returning a RealmManager object. You can open up a connection read-only or read-write. Optional arguments allow you to the values of the Mode and Server directives.
Lincoln Stein <email@example.com>
Copyright (c) 1997, Lincoln D. Stein
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
|perl v5.20.3||HTTPD::REALM (3)||2003-01-16|