radiusContext README
$Revision: 1.21 $
tummy.com, ltd.
Copyright (c) 1998-2001 Sean Reifschneider, tummy.com, ltd.
All rights reserved.

radiusContext Home Page: http://www.tummy.com/radiusContext/
radiusContext FTP: ftp.tummy.com:/pub/tummy/radiusContext/

INTRODUCTION

radiusContext is a RADIUS accounting log analysis package modeled after the
radiusreport package (http://www.tibus.net/pgregg/projects/radiusreport/).
However, it's meant to deal with a few short-comings of radiusreport, but
of course has a few of it's own:

   ADVANTAGES
      Uses roughly 10% of the memory.  On 260MB of logs, uses 50MB RAM
            and around 320MB disc space (not counting logs).  radiusreport
            I had to kill after it used 128MB RAM and 256MB swap.
      Produces easier-to-read reports.
      Produces more correct reports (users with 5 minutes on-time aren't
            reported as 300+ hours).
      Produces indices of report data.
      Produces text and HTML output, other output methods can be plugged
            in in a modular way.
      Faster (up to 10x) on processing log-files that don't fit in memory.
      Incremental parsing of log files (process them every day, and generate
            month-to-date reports for example)

   DISADVANTAGES
      *REQUIRES* Python 1.5 (see http://www.python.org/), which many systems
            won't already have installed.
      For log-files that fit completely in memory, radiusContext is about
            half as fast.
      On a Pentium II 300 machine with 128MB RAM, a 1.2 million line detail
            file (containing 160 thousand accounting entries) can be
            processed in 12 minutes (1673 lines or 108 records per second).
            This includes parsing and report generation.  radiusreport can
            do the same report in 6 minutes.
      radiusContext supports MERIT and Livingston-format accounting logs at
            the moment.  The modular approach should mean that additional
            formats can be supported easily.

SUPPORTED RADIUS SERVERS

Here is a (likely incomplete) list of RADIUS servers that radiusContext is
known to work with:

	Cistron
	Livingston
	MERIT

It basicly works with any RADIUS server that writes data out in the typical
"detail" accounting format.  See "README.FORMAT" for more information on what
that format looks like and samples of what your detail files should look like.
It also contains information on how to convert other formats of data to
something radiusContext can handle.

QUICK START

radiusContext generates a usage report based on one or more RADIUS detail
files.  This of course requires you to *HAVE* those detail files in your
possession.  They're typicly called "detail", search for them on your
system.  Once you have them, you can generate a sample report by doing:

   raddetail detailfilename
   mkdir reportdir
   stdreport --reportdir reportdir

Now you should have a report in the directory "reportdir".  Note that you
can run "raddetail" multiple times and/or list multiple detail files on the
command line.  Duplicate data in these files is (effectively) ignored, so
you can run this regularly to pick up new data.

GETTING STARTED

radiusContext creates a database called "SessionData" in the current
directory.  This name can be specified using the "-d" option to the
commands.  Data is processed in two stages, importing of the data into
the database (which can be done incrementally) and report generation.

To create the database, use "raddetail".  The detail file names can be
specified on the command-line ("raddetail detail1"), or can be piped
from standard input ("gunzip <detail1.gz | raddetail").  Now, to create
the report run "mkdir report" and "stdreport -D report".  You will end
up with text, rawtext, CSV, and HTML files in a subdirectory called
"report".  There is an "index" and "index.html" file created which
includes an overall report.  The "index.html" file has hyper-links to
the detail files.

OVERVIEW

radiusContext runs in two stages.  The first stage parses the detail
file and adds the records to a database.  This stage can be run however
often you want, with whatever data you have.  For example you could
run it daily...  Then if you want to produce monthly reports, remove
or rename the database after the last run of the month.  This phase
only requires about 5% of the database size in RAM, and is quite
disc-intensive.

NOTE: radiusContext *ONLY* uses the STOP records.  If a session is started
at 23:00 one day and ends at 01:00 the next day, and you've rotated the
log file at 00:00...  The stop record is picked up in the next run and the
2 hours are added to the user's report.

The second stage takes the database and generates a report.  This stage
can be fairly lengthy, so you probably want to run it at night, and
no more often than once a day.  Memory used during this phase is
roughly 15% of the database size, though I'm planning on making it
even more stingy in the future.  This phase is also quite disk-bounded,
so while it doesn't use much processor time, your discs may be very
busy.

Reports are generated in both HTML and text form.  Other back-ends
can be created and plugged in quite easily.

OUTPUT FORMATS

radiusContext can generate reports in the following formats:

   text:    Text-based index and user files.  Designed to be easy for a
            human to read on paper or a text-based terminal.  Generated
            files have no extension by default ("user" and "index").

   html:    HTML files suitable for viewing in a table-capable browser.
            The index is broken up into sub-tables with 100 users in
            each to speed display.  Generated files have an ".html"
            extension by default ("user.html"" and "index.html").

   htmlascend:
            HTML files which have extra Ascend fields and processing.
            Note that this is mutually exclusive of the regular HTML
            output.  If you specify htmlascend, html should not be listed.

   raw:     Similar to the text format above, except numbers are expressed
            in seconds and bytes instead of being converted to human-readable
            formats.  These files are meant to be used for sorting using
            "sort" to order the table.  Dates in the user file are always
            fully expressed instead of only when they change.  Generated
            files have a ".raw" extension by default ("user.raw" and
            "index.raw")

   csv:     Similar to raw, but in "comma seperated value" format instead of
            white-space seperated.  Includes headers but lacks summary
            information.  Meant for importing into a database or spreadsheet.

At the current time, they are all built all the time.  This doesn't
actually create a larger overhead (generating only HTML output isn't 4
times faster).

By default, all formats will be generated.  This can be overridden
by using the '-g' or '--generate' option listing the formats you wish
to generate:

   stdreport -g text -g html --generate raw

or:

   stdreport -g text -g htmlascend --generate raw

The above generates reports in text, html, and raw formats.

SWITCHES

raddetail takes the following command-line switches:

   [ -d | --database <file> ]       Specify database file name.
   [ -v | --version  ]              Display program version.
   [ -h | -? | --help  ]            Display this usage message.

stdreport takes the following command-line switches:

   [ -d | --database <file> ]       Specify database file name.
   [ -D | --reportdir <dir> ]       Specify report directory name.
   [ -g | --generate <type> ]       Select reports to generate.
                                    (May be used several times).
   [ -C | --csvreportdir <dir> ]    Specify CSV directory name.
   [ -H | --htmlreportdir <dir> ]   Specify HTML directory name.
   [ -A | --htmlascendreportdir <dir> ]
                                    Specify HTML-Ascend directory.
   [ -T | --textreportdir <dir> ]   Specify text directory name.
   [ -R | --rawreportdir <dir> ]    Specify RAW directory name.
   [ -s | --split-num <n> ]         Second-level report dirs are
                                    the first 'n' chars of login.
   [ -u | --user  ] <user name>     Limit report to <user> (may be
                                    specified multiple times)
   [ -v | --version  ]              Display program version.
   [ -h | -? | --help  ]            Display this usage message.

USAGE

   Package: radiusContext


   Code to analyze and report on RADIUS (Remote Authentication Dial In User
   Services) accounting logs.  Automatically detects Livingston and
   MERIT format logs.

   raddetail [ -d | --database <file>] [ -v | --version ] 
      [ -h | -? | --help] <logfilename>
      
      Creates a database called "SessionData", or named with the -d switch
      from the accounting logs <logfilename>.
   

   stdreport [ -d | --database <file> ] [ -D | --reportdir <dir> ]
      [ -C | --csvreportdir <dir> ] [ -H | --htmlreportdir <dir> ]
      [ -T | --textreportdir <dir> ] [ -R | --rawreportdir <dir> ]
      [ -u | --user <user name> ] [ -s | --split-num <n> ]
      [ -v | --version ] [ -h | -? | --help]

      Creates the reports from the database created by "raddetail".

   generator.py
      The report generating interface. Uses genhtml.py, gencsv.py,
      genraw.py, and gentext.py to generate HTML, CSV, raw and text reports.

   radiussupp.py
      Supporting routines: secsTable, secsToStr, bytesToStr, tryDivide,
      longToStr

LICENSE

radiusContext is Copyright (c) 1998-2000 by Sean Reifschneider, tummy.com, ltd.
All rights reserved.

radiusContext@tummy.com
http://www.tummy.com/radiusContext
ftp:///ftp.tummy.com/pub/tummy/radiusContext/

radiusContext is Open Source Software (www.opensource.org). 

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

0. Copyright Inclusion: All redistributions of source code must retain the
above copyright notice, this list of conditions and the following disclaimer.

1. Free Redistribution: radiusContext may be redistributed by anyone for a 
fee or for free as a component of an aggregate software distribution 
containing programs from several different sources.

2. Source Code: radiusContext includes source code, and must be distributed
with source code. If it is distributed without source code, tummy.com, ltd.'s
ftp site must be mentioned prominently as the location of the source code.

3. Derived Works: Works derived from radiusContext, or modifications to 
radiusContext must be distributed under the same terms as this original license. 
4. Integrity of The Author's Source Code: Any works derived from radiusContext,
or modifications to radiusContext must be distributed as source and "patch"
files. This is to ensure that changes made to radiusContext are clearly
specified as such, and the authorship of such changes is clearly identified.
Patched versions of radiusContext must use a name which identifies them
as such.

5. No Discrimination Against Persons or Groups: This license applies to
everyone equally, and does not discriminate in any way.

6. No Discriminiation Against Fields of Endeavor: This license applies to 
all uses in any field of endeavour equally.

7. Distribution of License: This license, and all rights associated with it
is assigned upon redistribution of radiusContext without the need for
execution of an additonal licence by those parties.

8. License not Specific to a Product: The rights attached to radiusContext
do not depend upon it being part of any specific distribution or product,
and specifically prohibit the restriction of this license based on being
part of any entity.

9. Advertising Requirement: All advertising materials mentioning features
or use of this software must display the following acknowledgement:
      
      This product includes software developed by tummy.com, ltd. and its
      contributors.

10. Neither the name of tummy.com, ltd., nor Sean Reifschneider, nor the
names of its contributors may be used to endorse or promote products derived
from this software without prior written permission from tummy.com, ltd.
or Sean Reifschneider.

DISCLAIMER

THIS SOFTWARE IS PROVIDED BY tummy.com, ltd., Sean Reifschneider 
AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, 
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY 
AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
tummy.com, ltd., Sean Reifschneider OR CONTRIBUTORS BE LIABLE FOR ANY 
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.