NAME

RADIUS::UserFile - Perl extension for manipulating a RADIUS users file.

SYNOPSIS

  use RADIUS::UserFile;

  my $users = new RADIUS::UserFile 
                  File => '/etc/raddb/users',
                  Check_Items => [ qw(Password Calling-Station-Id) ];

  $users->load('/usr/local/etc/radius/users');
  
  $users->add(Who        => 'joeuser',
              Attributes => { key1 => 'val1', key2 => 'val2' },
              Comment    => 'Created on '. scalar localtime);
    
  $users->update(File => '/etc/raddb/users',
                 Who => qw(joeuser janeuser));

  print $users->format('joeuser');

REQUIRES

Perl5.004, Fcntl, File::Copy, Tie::IxHash

EXPORTS

Nothing

DESCRIPTION

This module provides methods for reading information from and modifying a RADIUS users text file.

PACKAGE METHODS

new RADIUS::UserFile

new RADIUS::UserFile(File => $USERS_FILE, Who => $USER, Check_Items => [ @CHECK_ITEMS ])

new RADIUS::UserFile(File => $USERS_FILE, Who => [ @USERS ], Check_Items => [ @CHECK_ITEMS ])

Creates and returns a new RADIUS::UserFile object.

File specifies the RADIUS users file to load (e.g. "/etc/raddb/users"). If no file is specified, one isn't loaded; in this case, the load() method can be used to retrieve any user data. If an error occurred while reading File, 0 is returned instead.

Who limits the retrieval of user information to the list of users specified. A single user can be named using a string, or a set of users can be passed as a reference to an array. If Who is left undefined, all users will be loaded.

Check_Items is a reference to a list of attributes that should be included in the first line of the record. By default, this list includes: "Password", "Auth-Type", "Called-Station-Id", "Calling-Station-Id", "Client-Port-DNIS", and "Expiration".

OBJECT METHODS

->add(Who => $USER, Attributes => \%ATTRS, Comment => $TEXT, Debug => level)

Adds information about the named user. This information will henceforth be available through users, attributes, comment, etc. Any comments are automatically prefixed with "# ". Attributes should be specified as a reference to a hash; each value should either be an array ref or a string. On success, 1 is returned. On error, 0 is returned and STDERR gets an appropriate message. The debug level is used by the debug function described below.

->attributes($USER)

Returns a list of defined attributes for the specified user. If the user doesn't exist, undef is returned.

->comment($USER)

Returns a string representing the comments that would prefix the given user's entry in the users file. If the user doesn't exist, undef is returned.

->debug(level, @messages)

Prints out the list of strings in @messages if the debug level is >= level.

->dump($USER)

Prints out the attributes of the named user, in alphabetical order. $self is returned.

->files

Returns a list of files from which we have read user attributes. The list is sorted according to the order in which the files were read. If no files have yet been read successfully, an empty array is returned.

->format($USER)

Returns a string containing the attributes of the named user, prefixed by any comments, according to the format required for the RADIUS users file. If the user doesn't exist, an empty string is returned.

->load(File => $USERS_FILE, Who => $USER)

->load(File => $USERS_FILE, Who => \@USERS)

Loads the contents of the specified RADIUS users file. The name of the file is stored in a first-in, last-out stack enumerating which "databases" have been loaded (see files()). The RADIUS::UserFile object is returned. The options are the same as described in new(). If a user already exists and further info is read about that user from the specified file, the new information is just added to what is already known. On success, 1 is returned; on failure, 0 is returned and an appropriate message is sent to STDERR.

->read_users($USERS_FILE, $USER)

->read_users($USERS_FILE, \@USERS)

Reads in the contents of the specified RADIUS users file, and returns a pair of hashes: one indexed by user name, with each element containing a hash of (attribute name => [ values ]) pairs; and another also indexed by user name, containing the comments that immediately preceded that user's file entry. The options are the same as in new(). Each comment value is a string. Each user attribute value is a ref to an array of strings. This is mainly designed as a utility function to be used by new() and load(), and doesn't affect the calling object. On failure, 0 is returned.

->remove($USER ...)

Deletes the specified users from the object. The list of users successfully deleted is returned.

->removed()

Returns a list of users that have been removed from the object.

->update(File => $USERS_FILE, Who => \@USERS)

Updates user attributes in a RADIUS users file. If the file is specified, its contents are updated; otherwise, the last file read is modified. If a list of users is provided, only their entries are updated; otherwise, all known users are. All users to be "updated" are printed using the results of format. Other users are printed as found. It should be noted that some extra newlines can be left in a file with this method: if an empty line follows a given record that has been remove()d, then it will still be there in the file being updated. On success, non-zero is returned. On failure, 0 is returned and STDERR gets an appropriate message.

->user($USER)

Returns a ref to a hash representing the attributes of the named user. If the user doesn't exist, undef is returned.

->usernames

Returns a ref to an anonymous array of strings representing the users about which we have attributes defined. If no users are defined, a ref to an empty anonymous array is returned.

->users

Returns a ref to a hash of user hashes, where each user hash is a set of (attribute name => value) pairs. This is the actual data stored in the object, so use with caution.

->values($USER, $ATTRIBUTE)

Returns an array of strings representing the values for the named attribute of the given user. If the user or attribute doesn't exist, undef is returned.

AUTHOR

Copyright (c) 2001 O'Shaughnessy Evans <oevans@cpan.org>. All rights reserved. This version is distributed under the same terms as Perl itself (i.e. it's free), so enjoy.

Thanks to Burkhard Weeber, James Golovich, Peter Bannis, and others for contributions and comments that have improved this software.

SEE ALSO

RADIUS::Packet, RADIUS::Dictionary, Authen::Radius.