Read Me

FreeRADIUS rlm_acctcache Module

Author: Rob McAuley, BskyB Ltd, 11/11/2009

This module is intended to give freeradius users the ability to make real time
accounting queries using the FreeRADIUS radclient command to make requests.
All commands are issued in the 'User-Name' attribute as shown later.

It basically stores all recieved accounting information in memory hashes,
taking care to expire information that has not been updated for a period of
time. The awesome uthash macros are used to do this.

It can run in 2 modes 'active' or 'passive'.
active will allow you to use it in a normal acct server where you want to get
acks from accounting packets.
passive, will simply eat all accounting packets without replying acks. This is
great if you have a distributed acct architecture but you want any easy way to
centralize data. You will need to effectively clone/span your various acct
data streams to it though (This might need you to spoof udp source ip to avoid
radius client collisions etc).

I hope that other users find this module useful, but YMMV.

BUILDING:

This release was compiled / tested with freeradius v1.1.7, v2.0.5, uthash-1.4,
SunOS 5.10

Edit the Makefile.in to ensure RLM_CFLAGS RADIUSD_MAJOR_VERSION=2 is set if
you're not using a v1.x freeradius.
Ensure the module is listed in src/modules/stable, and do the normal
freeradius configure with '--enable-rlm_acctcache' set.


CONFIGURATION:

Default values for rlm_acctcache would look like this:

acctcache myacctcache {
	freezefile = "/var/log/freeradius/freezefile"
	bandwidthfile = "/var/log/freeradius/acctcache.log"
	loglevel = 3
	passivefeed = yes
	dumpfile = "/var/log/freeradius/acctcache.dump"
	dumpbandfile = "/var/log/freeradius/bandwidth.dump"
	cmdtok = "::"
	debugtok = "D:"
	dumpbandtok = "E:"
	cleantok = "C:"
	cleanthresh = 5400
	sleeptok = "W:"
	cleansleep = 10
	bandwtok = "B:"
	bandstat = 1
	findutok = "U:"
	finditok = "I:"
	findntok = "N:"
	statstok = "S:"
	loglvtok = "L:"
	freezetok = "Z:"
	restortok = "R:"
}


FILES: locations of various files created, modified or read by rlm_acctcache module.

"freezefile"	- location of state freeze file (default: /var/log/freeradius/freezefile). 
		  Created on demand when you want to store state.
		  Related: freezetok,restortok.

"bandwidthfile"	- location of session state change logs (default: "/var/log/freeradius/acctcache.log"). 
		  Updated every time a session is closed, expires, or 'switches' to another session (based on PW_ACCT_UNIQUE_SESSION_ID).
		  Related: bandstat, bandwtok

		  File Format (a csv file with the following fields):
		  as per 'dumpbandfile' below.

"dumpbandfile"	- location of usage dump log (default: "/var/log/freeradius/bandwidth.dump").
		  Created on demand and reports on all known sessions.
		  Related: dumpbandtok

		  File Format (a csv file with the following fields):
		  	USERNAME	- User-Name attribute
		  	UNIQSESS	- Acct-Unique-Session-Id attribute
		  	SESSIONAGE	- number of seconds since session started
		  	UPDATETIME	- unix timestamp when last acct packet was received
		  	IN_OCTETS	- Acct-Session-Input-Octets
		  	IN_GIGA_OCTETS	- Acct-Session-Input-Gigawords (maintained by either rlm_acctcache or n/w kit)
		  	OUT_OCTETS	- Acct-Session-Output-Octets
		  	OUT_GIGA_OCTETS	- Acct-Session-Output-Gigawords (maintained by either rlm_acctcache or n/w kit)
		  	ALL_STATES	- bitfield variable containing states seen (see radinfo.h - STATE_START,STATE_STOP,STATE_ALIVE)
		  	NAS_TX_SPEED	- Ascend-Xmit-Rate or cisco-avpair actual-data-rate-upstream
		  	NAS_RX_SPEED	- Ascend-Data-Rate or cisco-avpair actual-data-rate-downstream
		  	CONNECT_INFO	- Connect-Info, or Ascend-Connect-Info or cisco-avpair connect-progress
		  	DISCONNECT_CAUSE- Ascend-Disconnect-Cause or cisco-avpair ppp-disconnect-cause
		  	CLASS		- Class attribute

"dumpfile"	- location of debug dump log (default: "/var/log/freeradius/acctcache.dump").
		  Created on demand to show hash table structure. Only useful for debug
		  Related: debugtok


TOKENS: Commands that can be sent to rlm_acctcache module on-the-fly.
	
"cmdtok"	- String used in 'User-Name' attribute to allow rlm_acctcache to determine if the packet 
		  is an rlm_acctcache command or normal acct packet.
		  (default: "::")

"debugtok"	- String command used to tell rlm_acctcache to dump hash debug content to "dumpfile".
		  (default: "D:")

"dumpbandtok"	- String command used to tell rlm_acctcache to dump hash contents.
		  (default: "E:")

"cleantok"	- String command used to change cleaner timeout threshold. The cleaner logs and removes
		  sessions from hash tables if they were not updated within the supplied threshold.
		  Supply values in seconds.
		  (default: "C:")

"sleeptok"	- String command used to change delay between cleaner runs, or start the cleaner thread
		  when using forked radius daemon (see examples section).
		  Supply values in seconds.
		  (default: "W:")

"bandwtok"	- String command used to switch on/off bandwidth stat logging to "bandwidthfile".
                  Supply binary value.
		  (default: "B:")

"findutok"	- String command used to query for a users information.
		  (default: "U:")

"finditok"	- String command used to query for client ip information.
		  (default: "I:")

"findntok"	- String command used to query for nas port information.
		  (default: "N:")

"statstok"	- String command used to request hash statistics. 
		  (default: "S:")

		  Stats will be logged and returned in a comma-delimeted 'FIELD:VALUE' list in the 'Connect-Info' attribute
		  with the following csv fields:

		  	S:'unix timestamp recording rlm_acctcache start time'
		  	R:'runtime in seconds'
		  	TP:'total accouting packets received'
		  	TC:'total command packets received'
		  	I:'unix timestamp recording last stats request time'
		  	IP:'interim accounting packets received since last stats request'
		  	IC:'interim command packets received since last stats request'
		  	UM:'number of entries in the username hash map'
		  	CM:'number of entries in the client ip hash map'
		  	NM:'number of entries in the nasport hash map'
		  	UMC:'unix timestamp recording last time username hash map was cleaned'
		  	UMO:'number of username hash map entries kept during last clean'
		  	UMN:'number of username hash map entries purged during last clean'
		  	CMC:'unix timestamp recording last time client ip hash map was cleaned'
		  	CMO:'number of client ip hash map entries kept during last clean'
		  	CMN:'number of client ip hash map entries purged during last clean'
		  	NMC:'unix timestamp recording last time nasport hash map was cleaned'
		  	NMO:'number of nasport hash map entries kept during last clean'
		  	NMN:'number of nasport hash map entries purged during last clean'

			eg: Connect-Info = "S:1250245013,R:2686645,TP:3522141860,TC:764,I:1250245013,IP:3522141856,IC:764,UM:1735838,CM:1741769,NM:1536979,UMC:1252931632,UMO:1735626,UMN:161,CMC:1252931642,CMO:1741621,CMN:169,NMC:1252931652,NMO:1536940,NMN:124"

		  ('rtrstats.pl' script shows an example of how to obtain these stats)

"loglvtok"	- String command used to change "loglevel".
		  (default: "L:")

"freezetok"	- String commmand used to store rlm_acctcache state to "freezefile". 
		  (default: "Z:")

		  This can be used to shutdown the freeradius daemon afterwards or continue processing.
		  Sending "Z:0" will allow processing to continue after storing state.
		  Sending "Z:1" will cause freeradius to shutdown after storing state.

"restortok"	-  String command used to restore rlm_acctcache state from "freezefile".
		  Recent memory based information will not be overwritten. This can be handy to restore state 
		  from a different server.
		  (default: "R:")


CONTROL VARIABLES: Variables used to alter rlm_acctcache processing

"loglevel"	- Initial level of cleaner / command logging. bitfield variable:
		  bit 1 => log cleaner process
		  bit 2 => log command actions
		  (default: "3")

"passivefeed"	- silently eat accounting packets or not.
		  yes => dont ACK accounting packets.
		  no  => send ACK, ie use in normal accounting server.
		  (default: "yes")

"cleanthresh"	- Initial timeout threshold for cleaner. Value in seconds.
		  (default: "5400")

"cleansleep"	- Initial delay between cleaner runs. Value in seconds.
		  (default: "10")

"bandstat"	- Initial value for bandwidth logging enable. Binary value.
		  (default: "1")


Some example usage:

# change cleaner thread sleep, or start cleaner thread when using forked radius daemon:
# (typically you would add this to any freeradius init script you have to ensure the cleaner starts)
echo "User-Name = ::W:30" | radclient -t 1 -r 1 -x -d /etc/raddb server_ip:1813 acct secret

# change cleaner threshold to expire sessions not updated for more than 1 hour:
echo "User-Name = ::C:3600" | radclient -t 1 -r 1 -x -d /etc/raddb server_ip:1813 acct secret

# Search for details on a user:
echo "User-Name = ::U:rob.mcauley@realm" | radclient -t 1 -r 1 -x -d /etc/raddb server_ip:1813 acct secret

# Search for details for a given client ip:
echo "User-Name = ::I:192.168.0.1" | radclient -t 1 -r 1 -x -d /etc/raddb server_ip:1813 acct secret

# Search for details for a given NAS (1.2.3.4) / NAS port (999):
echo "User-Name = ::N:1.2.3.4:999" | radclient -t 1 -r 1 -x -d /etc/raddb server_ip:1813 acct secret

# Store hash table contents to "freefile" without exiting:
echo "User-Name = ::Z:" | radclient -t 1 -r 1 -x -d /etc/raddb server_ip:1813 acct secret

# Restore hash table contents from "freefile":
echo "User-Name = ::R:" | radclient -t 1 -r 1 -x -d /etc/raddb server_ip:1813 acct secret

---------------------------------------------------------------------------------------------------------
Using 2 separate "dumpbandfile" files over a time period and "bandwidthfile" contents covering the same period,
per user data usage can be worked out using the provided 'bandwitdh_calc.pl' script.