Accounting replication with radrelay.


0. INTRODUCTION

   Often people run multiple radius servers; at least one primary and
   one backup server. When the primary goes down, most NASes detect that
   and switch to the backup server.

   That will cause your accounting packets to go the the backup
   server - and some NASes don't even switch back to the primary
   server when it comes back up.

   That means you miss accounting records or must jump through hoops
   to combine the different detail files from multiple servers. It
   also means that the session database ("radutmp", used for radwho
   and simultaneous use detection) gets out of sync.

1. REPLICATION

   Radrelay is a program that does the equivalent of tail(1) on a
   accounting detail file. Each time the server writes a packet
   to this file, radrelay reads it and sends it to a remote radius
   server. If all works well, radrelay gets replies from the remote
   server as it should. When it reaches end-of-file, it locks the
   file, renames it to <filename>.work, and waits for all it's
   accounting requests to get answered. As soon as they are
   answered, <filename.work> is deleted.

   When radrelay starts up it first checks for <filename.work>
   before it starts processing the standard detail file. This
   ensures that no packets get lost.

   Even if the primary server is down for a day, or if the secondary
   server crashes and reboots, radrelay will buffer the accounting
   packets and send them to the remote accounting server.

   Radrelay checks the "Client-IP-Address" attribute in each record,
   and if it's the same as the remote server it will not replicate
   that record to prevent loops. That means you can point radrelay
   to the primary server on the backup host, and to the backup server
   on the primary host, to have complete records on both.

2. USAGE

   First, you should make radiusd log to an extra, single detail file.
   This is probably done easiest by adding an extra instance of the
   detail module to your radiusd.conf.

   For example:

   detail detail1 {
   	detailfile = %A/%{Client-IP-Address}/detail-%Y%m
   	detailperm = 0600
   	dirperm = 0755
   }
   detail detail2 {
   	detailfile = ${radacctdir}/detail-combined
   	detailperm = 0600
   	dirperm = 0755
   	locking = yes
   }

   [...]

   accounting {
        [...]
   	detail1
        detail2
        [...]
   }

   In the above example, the instance detail1 of the detail module
   represents your original detail logging. detail2 will create a
   detail file dedicated only to radrelay. Note the use of "locking = yes",
   this is _very very_ important when using the detail module in combination
   with radrelay. It's used to keep both the detail module and radrelay
   playing nice with each other.

   Next, you need to fire up radrelay.

   For example:

   radrelay -S secret_file <server> detail-combined

   The use of -S is recommended over -s due to the fact that your secret
   won't show up with ps. You should also make sure your secret file is not
   world readable.

   If the server you are relaying to is included in your 'clients.conf' file
   using the '-n [shortname]' commandline option is probably easiest. This
   means you won't have to give the remote server address or the shared
   secret when you start radrelay.

   You should never logrotate your detail file, radrelay will take care of
   this for you.

3. REPLICATION AND PROXYING

   If you have a primary and a backup server with identical configs
   that both proxy for certain realms to other radius servers, the
   remote server might end up with duplicate accounting info - the
   accounting packet is received by the backup server, proxied to
   the remote server and replicated to the primary server, then the
   primary server proxies the same packet to the remote radius server
   again because it doesn't know that that was already done.

   To prevent this scenario, FreeRADIUS writes an extra attribute
   to the detail file if it has proxied the accounting packet, the
   vendor-specific attribute 'Freeradius-Proxied-To'. It contains the
   address of the remote radius server. Radrelay replicates this
   attribute just like any other to the primary server. If the
   primary server wants to proxy an accounting packet to a remote
   radius server, it first checks the packet to see if the
   'Freeradius-Proxied-To' attribute is present. If it is, and it
   contains the IP address of the remote radius server, it knows
   that it doesn't need to proxy this packet to the remote server
   once more. Problem solved!

4. NOTES

   Only attributes that are defined in the dictionary are replicated.
   Unknown attributes are simply ignored.

   Radrelay doesn't re-read its config files on a SIGHUP. It uses
   two config files - the dictionary (which can consist of multiple
   files ofcourse if you use $INCLUDE) and possibly the secret file.
   If you modify one of those files you need to restart radrelay.

5. CREDITS
   Original   - Miquel van Smoorenburg <miquels@cistron.nl>
		Written for the Cistron radius project.
   2002-06-09 - Simon Ekstrand <simon@routemeister.net>
		Ported to the FreeRADIUS project.