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

FreeBSD Manual Pages

  
 
  

home | help
HTTPD::RealmManager(3)User Contributed Perl DocumentatioHTTPD::RealmManager(3)

NAME
       HTTPD::RealmManager - Manage HTTPD server security realms

SYNOPSIS
	   use HTTPD::RealmManager;

	   # open up the database (could also use HTTPD::Realm::connect())
	   $database = HTTPD::RealmManager->open(-config_file=>'/home/httpd/conf/realms.conf',
						 -realm=>'members',
						 -writable=>1);

	   # List functions
	   @users = $database->users();
	   @groups = $database->groups();

	   # Information about users and groups:
	   print "Lincoln's groups are @group\n"
	       if @group = $database->group(-user=>'lincoln');

	   print "Lincoln is a subscriber\n"
	       if $database->match_group(-user=>'lincoln',-group=>'subscribers');

	   print "Lincoln's password is	$pass\n"
	       if $pass	= $database->passwd(-user=>'lincoln');

	   print "Intruder alert.\n"
	       unless $database->match_passwd(-user=>'lincoln',
					      -password=>'xyzzy');

	   $lincoln_info = $database->get_fields(-user=>'lincoln');
	   print "Lincoln's full name is $lincoln_info->{Name}\n";

	   print "The subscribers are @members.\n"
	       if @members = $database->members(-group=>'subscribers');

	   # Database updates
	   print "Added	Fred.\n"
	       if $database->set_passwd(-user=>'fred',
					-password=>'sssh!',
					-fields=>{Name=>'Fred Smith',
						  Nationality=>'French'});

	   print "Assigned Fred	to 'subscribers' and 'VIPs'\n"
	       if $database->set_group(-user=>'fred',
				       -group=>['subscribers','VIPs']);

	  print	"Changed Fred's	nationality.\n"
	       if $database->set_fields(-user=>'fred',
					-fields=>{Nationality=>'German'});

	   print "Fred is now gone.\n"
	       if $database->delete_user(-user=>'fred');

	   print "VIP group is now gone.\n"
	       if $database->delete_group(-group=>'VIPs');

	   print "Uh oh.  An error occurred: ",$database->errstr,"\n"
	       if $database->errstr;

DESCRIPTION
       HTTPD::RealmManager provides a high-level, unified view onto the	many
       access control databases	used by	Apache,	Netscape, NCSA httpd, CERN and
       other Web servers.  It works hand-in-hand with HTTPD::Realm, which
       provides	access to a standard configuration file	for describing
       security	database setups.  Internally, HTTPD::Realm uses	Doug
       MacEachern's HTTPD-Tools	modules	for database access and	locking.

       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.

METHODS
       HTTPD::RealmManager provides the	following class	and instance methods.

       new()
	      $db = HTTPD::RealmManager->new(-realm    => $realm_def,
					     -writable => 1,
					     -mode     => 0644,
					     -server   => 'ncsa');

	   The new() class method creates a new	connection to the database
	   indicated by	the indicated HTTPD::RealmDef object.  Ordinarily it
	   will	be more	convenient to use the open() method (below) or
	   HTTPD::RealmDef::connect().	Only the -realm	argument is mandatory.
	   The others are optional and will default to reasonable values.

	   If successful, the function result is an HTTPD::RealmManager
	   object, which you can treat as a handle to the database.

	   Arguments:

	      -realm	  Realm	definition.  See HTTPD::Realm(3).
	      -writable	  If true, open	database for writing.
	      -mode	  Override file	creation mode.
	      -server	  Override server type.

       open()
	      $db = HTTPD::RealmManager->open(-realm	   => 'subscribers',
					      -config_file => '/home/httpd/conf/realms.conf',
					      -writable	=> 1,
					      -mode	=> 0644,
					      -server	=> 'ncsa');

	   The open() class method creates a new connection to the database
	   given the indicated configuration file and realm name.  Internally
	   it first creates an HTTPD::Realm object, then queries it for	the
	   named realm,	passing	this result to new().  This is probably	the
	   easiest way to create a new connection.

	   Only	the -realm and -config_file arguments are mandatory.  The
	   others are optional and will	default	to reasonable values.

	   If successful, the function result is an HTTPD::RealmManager
	   object, which you can treat as a handle to the database.

	   Arguments:

	      -config_file Path	to realm configuration file. See HTTPD::Realm(3).
	      -realm	   Realm name.
	      -writable	   If true, open database for writing.
	      -config	   An alias for	-config_file.
	      -mode	   Override file creation mode.
	      -server	   Override server type.

       close()
	     $db->close()

	   When	you are	done with the database you should close() it.  This
	   will	commit changes and tidy	up.

       users()
	      @users = $db->users();

	   Return all users known to this database as a	(potentially very
	   long) list.

       groups()
	      @groups =	$db->groups()

	   Return all groups known to this database as a (potentially very
	   long) list.

       group()
	      @groups =	$db->group(-user=>'username');
	      $boolean = $db->group(-user=>'username',-group=>'groupname');

	   This	method returns information about the groups that a user
	   belongs to.	Called with the	name of	the user only, it returns a
	   list	of all the groups the user is a	member of.  Called with	both a
	   user	and a group name, it returns a boolean value indicating
	   whether the user belongs to the group.

	   Arguments:

	      -user	Name of	the user
	      -group	Name of	the group
	      -name	An alias for -user
	      -grp	An alias for -group

	   You can also	call this method with the positional parameters
	   (user,group), as in:

	      @groups =	$db->group('username');

       match_group()
	      $boolean = $db->match_group(-user=>'username',-group=>'groupname');

	   This	method is identical to the group() function, except that it
	   requires a group name to be provided.

       passwd()
	      $password	= $db->passwd(-user=>'username');
	      $boolean = $db->passwd(-user=>'username',-password=>'password');

	   Called with a user name this	method returns his encrypted password.
	   Called with a user name and an unencrypted password,	this routine
	   returns a boolean indicating	whether	this password matches the
	   stored password.

	   Arguments:

	      -user	 Name of the user
	      -password	 Password to check against (optional)
	      -name	 Alias for -user
	      -passwd	 Alias for -password

	   You can also	call this routine using	positional arguments, where
	   the first argument is the user name and the second is the password
	   to try:

	       print "You're OK" if $db->password('Fred','Open sesame');

       password()
	      $password	= $db->password(-user=>'username');
	      $boolean = $db->password(-user=>'username',-password=>'password');

	   An alias for	passwd(), just to make things interesting.

       match_passwd()
	      $boolean = $db->match_passwd(-user=>'username',-password=>'password');

	   This	method is identical to the two-argument	form of	passwd(),
	   except that it requires a trial password to be provided.

       match()
	      $boolean = $db->match(-user=>'username',-password=>'password');

	   This	method is an alias for match_passwd(), just to make things
	   interesting.

       get_fields()
	      $fields =	$db->get_fields(-user=>'username',
					-fields=>\@list_of_fields);

	   The user database can contain additional information	about the user
	   in the form of name/value pairs.  This method provides access to
	   these "additional fields."

	   get_fields()	accepts	a user name and	optionally a list of the
	   fields to retrieve.	If no field list is provided, it will retrieve
	   all fields defined in the security realm configuration file (see
	   HTTPD::Realm	(3)).  In practice, it is rarely necessary to limit
	   the fields that are retrieved unless	you are	accessing a SQL
	   database table containing an	unusually large	number of fields.

	   Arguments:

	      -user    Name of user
	      -fields  List reference to fields	to retrieve (optional)
	      -name    Alias for -user
	      -field   Alias for -fields

	   The return value is a hash reference.  You can retrieve the actual
	   values like this:

	      $fields =	$db->get_fields(-user=>'fred');
	      print $fields->{'Full_Name'};

       set_passwd()
	      $resultcode = $db->set_passwd(-user=>'username',
					    -password=>'password',
					    -fields=>\%extra_fields);

	   set_passwd()	sets the user's	password and/or	additional field
	   information.	 If the	user does not already exist in the database,
	   he is created.  The method requires the username and	one or more of
	   the new password and	a hash reference to additional user fields.
	   If either the password or the additional fields are absent, they
	   will	be unchanged.

	   When	setting	field values, the old and new values are merged.  To
	   delete a previous field value, you must explicitly set it to	undef
	   in the hash reference.  Otherwise the previous value	will be
	   retained.

	   A result code of true indicates a successful	update.	 The method
	   will	fail unless the	database is opened for writing.

	   Arguments:

	       -user	  Name of the user to update
	       -password  New password
	       -fields	  Hash ref to the fields to update
	       -name	  Alias	for -user
	       -passwd	  Alias	for -password
	       -gcos	  Alias	for -fields

       set_password()
	      $resultcode = $db->set_password(-user=>'username',
					      -password=>'password',
					      -fields=>\%extra_fields);

	   This	is an alias for	set_passwd(), just to make life	interesting.

       set_fields()
	      $resultcode = $db->set_fields(-user=>'username',
					    -fields=>\%extra_fields);

	   set_fields()	allows you to adjust the extra field information about
	   the designated user.	 Its functionality is identical	to
	   set_passwd(), but the name is a little more appropriate.  This
	   method requires a user name and a hash reference containing new
	   field values.

	   When	setting	field values, the old and new values are merged.  To
	   delete a previous field value, you must explicitly set it to	undef
	   in the hash reference.  Otherwise the previous value	will be
	   retained.

	   Arguments:

	       -user	  Name of the user to update
	       -fields	  Hash ref to the fields to update
	       -name	  Alias	for -user
	       -gcos	  Alias	for -fields

	   A true result code indicates	that the database was successfully
	   updated.  The database must be writable for this method to succeed.

       set_group()
	      $resultcode = $db->set_group(-user=>'username',
					   -group=>\@list_of_groups);

	   This	method allows you to set the list of groups that a user
	   belongs to without changing any other information about him or her.
	   It expects a	user name and a	list reference pointing	to the groups
	   to assign the user to.  The user will be removed from any groups he
	   previously participated in.

	   Arguments:

	       -user	  Name of the user to update
	       -group	  List of groups to assign user	to
	       -name	  Alias	for -user
	       -grp	  Alias	for -group

	   A true result code indicates	that the database was successfully
	   updated.  The database must be writable for this method to succeed.

       delete_user()
	      $resultcode = $db->delete_user(-user=>'username');

	   Delete the user and all his associated information from the
	   database.  If there are any empty groups after this deletion, they
	   are removed as well.	 This operation	is irreversible.

	   Arguments:

	       -user	  Name of the user to remove
	       -name	  Alias	for -user

	   A true result code indicates	that the database was successfully
	   updated.  The database must be writable for this method to succeed.

	   You may also	call this method with a	single positional argument:

	      $resultcode = $db->delete_user('username');

       delete_group()
	      $resultcode = $db->delete_group(-group=>'groupname');

	   Delete the group from the database.	Users who participate in the
	   deleted group are not deleted.  However, they may find themselves
	   orphaned (not participating in any groups).

	   Arguments:

	       -group	   Name	of the user to remove
	       -grp	   Alias for -group

	   A true result code indicates	that the database was successfully
	   updated.  The database must be writable for this method to succeed.

	   You may also	call this method with a	single positional argument:

	      $resultcode = $db->delete_group('groupname');

       errstr()
	      $error = $db->errstr();

	   This	method returns a string	describing the last error encountered
	   by RealmManager.pm.	It is not reset	by successful function calls,
	   so its contents are only valid after	a method returns a false
	   result code.

SEE ALSO
       HTTPD::Realm(3) HTTPD::UserAdmin(3) HTTPD::GroupAdmin(3),
       HTTPD::Authen(3)

AUTHOR
       Lincoln Stein <lstein@cshl.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.

perl v5.32.0			  2003-01-16		HTTPD::RealmManager(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=HTTPD::RealmManager&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help