Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
HTTPD::Realm(3)	      User Contributed Perl Documentation      HTTPD::Realm(3)

       HTTPD::Realm - Database of HTTPD	Security Realms

	   use HTTPD::Realm;

	   # pull out the definition of	the "members" realm
	   $realms = new HTTPD::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 HTTPD::RealmManager object.
	   $database = $def->connect(-writable=>1);

       HTTPD::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 HTTPD::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

       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/	</Realm>

	       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 "" 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

       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 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:

	     Users /home/httpd/security/passwd

	   For mSQL databases, the value of the	directive should have the

	      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

	     Groups /home/httpd/security/groups

	   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."

	      Server cern

	   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

	   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

	   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 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	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.

	      $realms =	HTTPD::Realm->new(-config=>'/path/to/config/file');

	   Create a new	set of realm definitions from the given	configuration

	      $exists =	$realms->exists(-realm=>'subscribers');

	   Returns true	if the named realm exists.  Otherwise returns undef.

	      -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

	     $realmdef = HTTPD::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

		   $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.

       HTTPD::RealmManager(3) HTTPD::UserAdmin(3) HTTPD::GroupAdmin(3),

       Lincoln Stein <>

       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.32.0			  2003-01-16		       HTTPD::Realm(3)


Want to link to this manual page? Use this URL:

home | help