/ 
FreeRADIUS-Database-0.06
River stage zero No dependents
/ FreeRADIUS::Database

NAME

FreeRADIUS::Database - RADIUS user, client and database manager.

SYNOPSIS

 use FreeRADIUS::Database;

 # create a new object, using the default configuration file

 my $radius = FreeRADIUS::Database->new();

 # create a new object, with an alternate config file

 my $radius = FreeRADIUS::Database->new({ config => '/path/to/config.file' });

 # aggregate yesterday's radacct data

 $radius->aggregate_daily();

 # aggregate a specific day of radacct data

 $radius->aggregate_daily({ day => '2009-06-12' });

 # aggregate radacct table by month (operates on month that was yesterday)

 $radius->aggregate_monthly();

 # aggregate monthly for a specific month

 $radius->aggregate_monthly({ month => '2009-06' });

 # rewrite the NAS IP Addresses in the radacct table into their named class
 # without doing aggregation

 $radius->update_ras_name({ day => '2009-06-01' });

 # get a users daily aggregated totals

 my $href = $radius->daily_login_totals({ 
                               username => 'un',
                               nas      => 'nasipaddress',
                               day      => 'YYYY-MM-DD',
                           });
   
 # get a users monthly aggregated bandwidth/time totals

 my $aoh = $radius->monthly_login_totals({
                               username    => 'un',
                               nas         => 'nasipaddress',
                               month       => 'YY-MM',
                               num_months  => 12, # default 11, max 36
                           });

 # get a user's hours used (month)

 my $float = $radius->month_hours_used({
                               username    => 'un',
                               nas         => 'nasipaddress',  # defaults to 'dialup'
                               month       => 'YYYY-MM',       # defaults to today's month
                           });

DESCRIPTION

This module contains methods to manage numerous aspects of a RADIUS database.

It aids in user and password management, producing statistics, and provides maintenance and mangement control of the backend MySQL database.

METHODS

new({ config => FILE })

Instantiates a new FreeRADIUS::Database object.

The default configuration file can be overridden in two ways. The first is sending in a 'config' parameter with the alternate configuration file name. This parameter must be supplied within a hash reference.

You can also override the default configuration file location by setting the FREERADIUS_DATABASE_CONFIG environment variable prior to making the call to new().

If a configuration file can not be found or read, or the object can not be created, the return will be undef.

aggregate_daily ( { day => DAY } )

This method is for the daily RADIUS database maintenance.

It's standard order of operation is as follows:

- update the names of the NASs in the radacct table in the RADIUS database, if ras_classification is set in the configuration file** - clears out any existing data in the aggregate_daily table for the day being worked on (in the event multiple runs in a single day are performed) - aggregates the daily RADIUS accounting from radacct table, and writes it into the aggregate_daily table

** this variable can be overridden if the named parameter 'classify' is passed in.

If the optional parameter day is specified, the method will run for that day. The day parameter is a DateTime object, after being called as such: $datetime->ymd().

If the day parameter is not passed in, the working day will be set to yesterday.

Returns 0 upon completion/success.

aggregate_monthly ( { month => $month } )

This method aggregates the daily totals into monthly aggregates into the 'aggregate_monthly' database table.

If supplied, the 'month' parameter will be used as the month to operate on. The month must be specified as such: YYYY-MM-DD.

Returns 0 upon success.

archive_radacct( { month => $month } )

Copies the data for the month specified in the 'month' parameter from the 'radacct' table into a newly created archive table 'radacct_YYYY-MM'. Note that the 'month' parameter must be supplied as YYYY-MM.

If the 'month' parameter is not specified, the method will work three months previous to the current one by default. Change the configuration file directive 'months_after_archive' to override this default.

Returns 0 upon completion.

daily_login_totals ({ NAME => VALUE })

Retrieves the login totals for a user on a particular NAS or NAS class on a particular day. It is particularly handy if you are classifying NASs.

The parameters are passed in within a hash reference:

username    => STRING
nas         => STRING
date        => 'YYYY-MM-DD'
raw         => BOOL # optional

The first three are mandatory. The 'raw' parameter is optional. If present and set to true, upload and download will be multiplied into MB/GB, and duration will be multiplied into hours, instead of bytes, bytes and seconds respectively.

If no data is found, the return is undef. Otherwise, returns a hash reference with 'date', 'upload', 'download', and 'duration' as it's keys.

monthly_login_totals ( { NAME => VALUE } )

This method retrieves the monthly aggregate login times/bandwidth used for a particular user. It is designed in such a way that 'update_ras_name()' must be being used.

The parameters are passed in as a hash reference:

username    => STRING
nas         => STRING
month       => YYYY-MM  # optional
num_months  => INTEGER  # optional

The username parameter is mandatory. The 'nas' is a string that consists of one of the 'RAS classifications' specified in the configuration file, a NAS IP address, or a NAS name.

The 'num_months' parameter is optional, and must be an integer between 1 and 36. if this parameter is absent, the default will be 11. This parameter is negated by the 'month' parameter. If 'num_months' is out of range, 'undef' will be returned.

If 'month' is passed in, it must be in the form YYYY-MM. This will do a lookup for that single month only.

Returns an array reference of hash references, in order to integrate with numerous templating system's TMPL_LOOP structure. Each hash reference is in the following format:

month    => 'Jan 2009',
upload   => MB or GB decimal
download => MB or GB decimal
duration => hours decimal

Returns undef if no rows are found in the database table.

month_hours_used ( { NAME => VALUE } )

Returns the number of hours used for an individual user's plan for any given month.

Parameters must be passed in as a hash reference as such:

username    => $username,   # mandatory
nas         => $class,      # NAS class or IP
month       => YYYY-MM,     # optional

If month is not passed in, we will default to the current month. If 'class' is not passed in, we will default to 'dialup'.

Returns the number of hours used, in a two point decimal format. If no entries could be found in the database, returns undef.

_create_archive_table ( { tablename => $tablename } )

Creates an archive table in the RADIUS MySQL database. The 'tablename' parameter is mandatory. It makes sense to use 'radacct_YYYY-MM' as the name of the table.

Returns 1 upon success.

date ( { get => VALUE, datetime => $datetime } )

Returns a date string or object.

The 'get' hashref parameter can take either day, month or year as valid values.

If year is specified, returns the string 'YYYY'. If 'month' is specified, the return is 'YYYY-MM'. For day, returns 'YYYY-MM-DD'.

The method will generate a 'now' DateTime object to work with, unless a pre-created DateTime object is passed in with the optional 'datetime' parameter.

Returns a DateTime object of the present date/time if no parameters are passed in.

The program terminates via croak() if the 'get' parameter is passed in with an invalid value.

password( { NAME => VALUE })

This method acts as both a getter and a setter for a user's RADIUS password.

The parameters are passed in as a hash reference in the following form:

username    => 'username',
password    => 'password'

The username parameter is mandatory. If it is not passed in, or is not found the return is undef, otherwise the current user password is returned.

If the password parameter is passed in along with the username, the current user's password will be overwritten with the new value, and the new value will be returned.

update_ras_name( { day => $day } )

This method rewrites the NASIPAddress in the RADIUS database's radacct table. Generally, it is used to classify groups of RAS IP addresses and assign them a name. For example, you can group all of your ADSL RASs IP addresses into logical groups for UBB.

The day parameter is mandatory, and must be a DateTime object, after being called with $datetime->ymd(). This method will operate on the date specified in the DateTime object.

This method is handy for calling in a loop context to iterate over past data.

See the accompanying update_nas_ip_address script in the distributions src/utilities directory.

Returns 0 upon completion/success.

SEE ALSO

AUTHOR

Steve Bertrand, <steveb@cpan.org>

COPYRIGHT

Copyright (C) 2012 by Steve Bertrand

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.9 or, at your option, any later version of Perl 5 you may have available.