/ 
RADIUS_XMLParser_1.0
/ RADIUS::XMLParser

NAME

RADIUS::XMLParser - Radius log file XML convertor

SYNOPSIS

    use RADIUS::XMLParser;

my @logs = qw(radius.log);
my @labels = qw(
Event-Timestamp
User-Name
File
);

my $radius = RADIUS::XMLParser->new(
	DEBUG=>1, 
	DAYSFORORPHAN=>1, 
	AUTOPURGE=>0, 
	ALLEVENTS=>1, 
	XMLENCODING=>"us-ascii", 
	OUTPUTDIR=>'/tmp/radius', 
	LABELS=>\@labels
	) or die "Cannot create Parser: $!";
	
my $result = $radius->group(\@logs);

DESCRIPTION

This module will extract and sort any supported events included in a given radius log file. Events will be grouped by their session ID and converted into XML sessions. At this time, supported events are the following:

START
INTERIM-UPDATE
STOP

On first step, any event will be stored on different hash tables (with SessionID a unique key). Then, for each STOP event, the respective START and INTERIM will be retrieved

[OPTIONAL] Each found START / INTERIM event will be removed from hash, and final hash will be stored on disk.
[OPTIONAL] Only the newest START / INTERIM events will be kept. Oldest ones will be considered as orphan events and will be dropped

Final XML will get the following structure:

<sessions>
   <session sessionId=$sessionId>
      <start></start>
      <interims>
         <interim id1></interim>
      </interims>
      <stop></stop>
   </session>
</sessions>

Constructor

USAGE:
my $z = RADIUS::XMLParser->new([%params]);
PARAMETERS:

See "Options" for a full list of the options available for this method

RETURN:

A radius parser blessed reference

Options

DEBUG

Boolean (0 by default) enabling Debug mode. Regarding the amount of lines in a given Radius log file, debug is split into several levels (1,5,10,15).

LABELS

Array reference of labels user would like to see converted into XML.

For instance:

my @labels = qw(
Acct-Output-Packets
NAS-IP-Address
Event-Timestamp);

Will result on the following XML
<stop>
	<Acct-Output-Packets></Acct-Output-Packets>
	<NAS-IP-Address></NAS-IP-Address>
	<Event-Timestamp></Event-Timestamp>
</stop>

If LABELS is not supplied, all the found Key / Values will be written. Else, only these labels will be written. FYI, Gettings few LABELS is significantly faster.. Think of it when dealing with large files !

AUTOPURGE

Boolean (0 by default) that will purge stored hash reference (Start + Interim) before being used for Event lookup. Newest events will be kept, oldest will be dropped. Threshold is defined by below parameter DAYSFORORPHAN

DAYSFORORPHAN

Number of days user would like to keep the orphan Start + Interim events. Default is 1 day; any event older than 1 day will be dropped. AUTOPURGE must be set to true

OUTPUTDIR

Output directory where XML file will be created Default is '/tmp'

ALLEVENTS

Boolean (0 by default). If 1, all events will be written, including Start, Interim and Stop "orphan" records. Orphan hash should be empty after processing. If 0, only the events Stop will be written together with the respective Start / Interims for the same session ID. Orphan hash should not be empty after processing.

XMLENCODING

Only utf-8 and us-ascii are supported

ORPHANDIR

Default directory for orphan hash tables stored structure Default is '/tmp'

CONTROLDATA

Boolean (0 by default) Print out hash table in order to control data structure These data structure will be written on files, under ORPHANDIR directory

Methods

$z->group(\@logs)

The group will parse all logs in array reference @logs. For each log file, events will be retrieved, sorted and grouped by their unique sessionId. Then, each file will be converted into a XML format.

USAGE:
	my $return = $z->group(\@logs);
PARAMETER:

@logs: All the radius log file that will be parsed. Actually it might save some precious time to parse several logs instead of one by one. (orphan hash events will be loaded only once).

GIVE:
$self->convert();

For each provided log, an XML will be generated.

RETURN:

The number of found errors.

EXAMPLE

my @logs = qw(../etc/radius.log);
my @labels = qw(Event-Timestamp User-Name File);


my $radius = RADIUS::XMLParser->new(
	DEBUG=>1, 
	DAYSFORORPHAN=>1, 
	AUTOPURGE=>0, 
	ALLEVENTS=>1, 
	XMLENCODING=>"us-ascii", 
	OUTPUTDIR=>'/tmp/radius',
	LABELS=>\@labels);
	
my $result = $radius->group(\@logs);

The generated XML will look like the following:

<session sessionId="d537cca0d43c95dc">
  <start>
   <Event-Timestamp>1334560899</Event-Timestamp>
   <User-Name>41794077013</User-Name>
   <File>radius.log</File>
  </start>
  <interims>
   <interim id="1">
    <Event-Timestamp>1334561024</Event-Timestamp>
    <User-Name>41794077013</User-Name>
    <File>radius.log</File>
   </interim>
   <interim id="2">
    <Event-Timestamp>1334561087</Event-Timestamp>
    <User-Name>41794077013</User-Name>
    <File>radius.log</File>
   </interim>
  </interims>
  <stop>
   <Event-Timestamp>1334561314</Event-Timestamp>
   <User-Name>41794077013</User-Name>
   <File>radius.log</File>
  </stop>
 </session>

AUTHOR

Antoine Amend <amend.antoine@gmail.com>

MODIFICATION HISTORY

See the Changes file.

COPYRIGHT AND LICENSE

Copyright (c) 2012 Antoine Amend. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.