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

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