CGI::Builder::Auth::Realm - Database of HTTPD Security Realms
# pull out the definition of the "members" realm
$realms = new CGI::Builder::Auth::Realm(-config_file=>'/home/httpd/conf/realms.conf');
$def = $realms->realm(-realm=>'members');
# show info about the realm
print "realm name = ", $def->name,"\n";
print "user database = ", $def->userdb,"\n";
print "group database = ", $def->groupdb,"\n";
print "user type = ", $def->usertype,"\n";
print "group type = ", $def->grouptype,"\n";
print "web server type = ",$def->server,"\n";
print "cryptography = ", $def->crypt,"\n";
print "other fields = ", $def->fields,"\n";
# Connect to the database for the realm,
# returning a CGI::Builder::Auth::RealmManager object.
$database = $def->connect(-writable=>1);
Pay no attention to that man behind the curtain! Move along, nothing to see here!
This module was originally part of the HTTPD-User-Manage collection, which is available on CPAN. If you want to use it, go download that package. This module is used as part of the internal implementation of CGI::Builder::Auth. The original documentation is preserved here in this release for historical purposes. The software has been hacked and this documentation is not guaranteed to be correct. The module may disappear from the CGI::Builder::Auth distribution in a future release. Do not use it directly or rely on it.
CGI::Builder::Auth::Realm defines high level security realms to be used in conjunction with Apache, Netscape and NCSA Web servers. You define the realms in a central configuration file, and access their underlying databases via this module and the CGI::Builder::Auth::RealmManager library. This allows automated tools to change user passwords, groups and other information without regard to the underlying database implementation.
Important note: Do not use these modules to adjust the Unix password or group files. They do not have the same format as the Web access databases.
A typical configuration file is shown below. It is human readable and similar in form to conventional Apache and NCSA HTTPD configuration files. Directives are separated from their arguments by white space (tabs or spaces), and comments begin with hash marks (#). By convention, the standard configuration file is named "realms.conf", but you can give it any name you prefer.
# realms.conf <Realm main> Type text Authentication Basic Users /home/httpd/security/passwd Groups /home/httpd/security/group </Realm>
<Realm development> Type DBM Authentication Basic Users /home/httpd/security/devel.passwd Groups /home/httpd/security/devel.group </Realm>
<Realm email@example.com> Type text Authentication Digest Users /home/httpd/1.1/passwd Groups /home/httpd/1.1/group </Realm>
<Realm subscriptions> Type MSQL Authentication Basic Database web_accounts@localhost Users table=users uid=name passwd=pass Groups table=groups group=group Fields Name Age:i Paid:s1 </Realm>
realms.conf is made up of one or more <Realm> sections. The opening <Realm> tag must contain the realm's name, which can be any set of non-whitespace characters. Each section contains directives that tells the module what type of authentication to use for the realm, what type of database to use, and where to find the files or database tables used for the realm. The users and groups defined in one realm are independent of those defined in another, giving you a lot of flexibility in setting up access control for your site.
The example shown here defines four different security realms. The first, named "main", uses human readable text files and the Basic Authentication protocol. The second, "development", also uses Basic Authentication, but stores users and groups in DBM files rather than in text files. The realm named "firstname.lastname@example.org" uses Digest Authentication on top of textfiles. By convention, Digest realms look like e-mail addresses, but you don't have to follow this convention. The last realm definition uses Basic Authentication on top of an mSQL database.
The directives allowed within a <Realm> section are listed here:
Directive Example Param Description Type DBM Database type Authentication Basic Authentication scheme Users /etc/httpd/passwd Path to user database Groups /etc/httpd/group Path to group database Database email@example.com Location of mSQL db Server NCSA Type of server Driver mSQL DBI driver Fields name age paid Additional user fields Mode 0644 Mode for new files Default Default realm
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."
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, it's a physical path to a file on your system. If the database file doesn't 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:
Users table=table_name uid=user_field password=password_field
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
Here's an example of a valid directive in which the user ID field is given a width of 40:
Users table=Members uid=Name:40 password=Pass
mSQL tables are not created automatically. You have to define them yourself (using the msql application) before using them.
This is the path to the file or database table that holds group assignments. If you don't 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 doesn't 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
Groups table=table_name group=group_field
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 don't 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.
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." Example:
If no server is specified, "apache" is assumed. If your server is not on this list, try "ncsa".
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 (it's assumed to be a "Y" or "N"):
Fields Name Age:i Paid:s1
Other fields may be present in the database. The Fields directive tells the user_manage script which fields should be made visible to the user interface.
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-r--r--).
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. CGI::Builder::Auth::Realm parses the configuration file, maintains lists of realms, responds to inquiries about realms, and opens up connections to realms' underlying databases. CGI::Builder::Auth::RealmDef defines the object that holds information about a particular realm.
$realms = CGI::Builder::Auth::Realm->new(-config=>'/path/to/config/file');
Create a new set of realm definitions from the given configuration file.
$exists = $realms->exists(-realm=>'subscribers');
Returns true if the named realm exists. Otherwise returns undef. Arguments:
-realm Name of the realm.
An alternative form is to use the name of the realm without the named argument:
$exists = $realms->exists('subscribers');
@realms = $realms->list();
Returns the list of realm names defined in the configuration file.
$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');
$database = $realms->connect(-realm=>'subscribers',
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.
$realmdef = CGI::Builder::Auth::RealmDef->new('subscribers');
Create a new RealmDef and assign it a name. This method is usually called internally.
$name = $realmdef->name();
Return the name of this realm.
$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.
$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 = $realmdef->mode();
Return the mode for creating the database file.
$database = $realmdef->database();
Return the database name and host (SQL databases only).
$fields = $realmdef->fields();
Return the additional field definition line (SQL databases only). No additional parsing is performed.
$type = $realmdef->usertype();
Return the type of the user/password database, for example "NDBM".
$type = $realmdef->grouptype();
Return the type of the group database, for example "NDBM".
$authentication = $realmdef->authentication();
Returns the authentication in use for this realm. May be either "Basic" or "Digest".
$server = $realmdef->server();
Return the type of Web server this realm is designed for.
$crypt = $realmdef->crypt();
Return the cryptography type for this realm, either "crypt" or "MD5".
$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
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
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
$database = $realmdef->connect(-writable=>1,
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.
-writable Open read/write if true.
-mode Override file creation mode.
-server Override server type.
CGI::Builder::Auth::RealmManager(3) CGI::Builder::Auth::UserAdmin(3) CGI::Builder::Auth::GroupAdmin(3), CGI::Builder::Auth::Authen(3)
Lincoln Stein <firstname.lastname@example.org>
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.
To install CGI::Builder::Auth::RealmDef, copy and paste the appropriate command in to your terminal.
perl -MCPAN -e shell
For more information on module installation, please visit the detailed CPAN module installation guide.