doc/radrelay

   1
   2              Accounting replication with radrelay.
   3
   4
   5 0. INTRODUCTION
   6
   7    Often people run multiple radius servers; at least one primary and
   8    one backup server. When the primary goes down, most NASes detect that
   9    and switch to the backup server.
  10
  11    That will cause your accounting packets to go the the backup
  12    server - and some NASes don't even switch back to the primary
  13    server when it comes back up.
  14
  15    That means you miss accounting records or must jump through hoops
  16    to combine the different detail files from multiple servers. It
  17    also means that the session database ("radutmp", used for radwho
  18    and simultaneous use detection) gets out of sync.
  19
  20 1. REPLICATION
  21
  22    Radrelay is a program that does the equivalent of tail(1) on a
  23    accounting detail file. Each time the server writes a packet
  24    to this file, radrelay reads it and sends it to a remote radius
  25    server. If all works well, radrelay gets replies from the remote
  26    server as it should. When it reaches end-of-file, it locks the
  27    file, renames it to <filename>.work, and waits for all it's
  28    accounting requests to get answered. As soon as they are
  29    answered, <filename.work> is deleted.
  30
  31    When radrelay starts up it first checks for <filename.work>
  32    before it starts processing the standard detail file. This
  33    ensures that no packets get lost.
  34
  35    Even if the primary server is down for a day, or if the secondary
  36    server crashes and reboots, radrelay will buffer the accounting
  37    packets and send them to the remote accounting server.
  38
  39    Radrelay checks the "Client-IP-Address" attribute in each record,
  40    and if it's the same as the remote server it will not replicate
  41    that record to prevent loops. That means you can point radrelay
  42    to the primary server on the backup host, and to the backup server
  43    on the primary host, to have complete records on both.
  44
  45 2. USAGE
  46
  47    First, you should make radiusd log to an extra, single detail file.
  48    This is probably done easiest by adding an extra instance of the
  49    detail module to your radiusd.conf.
  50
  51    For example:
  52
  53    detail detail1 {
  54         detailfile = %A/%{Client-IP-Address}/detail-%Y%m
  55         detailperm = 0600
  56         dirperm = 0755
  57    }
  58    detail detail2 {
  59         detailfile = ${radacctdir}/detail-combined
  60         detailperm = 0600
  61         dirperm = 0755
  62         locking = yes
  63    }
  64
  65    [...]
  66
  67    accounting {
  68         [...]
  69         detail1
  70         detail2
  71         [...]
  72    }
  73
  74    In the above example, the instance detail1 of the detail module
  75    represents your original detail logging. detail2 will create a
  76    detail file dedicated only to radrelay. Note the use of "locking = yes",
  77    this is _very very_ important when using the detail module in combination
  78    with radrelay. It's used to keep both the detail module and radrelay
  79    playing nice with each other.
  80
  81    Next, you need to fire up radrelay.
  82
  83    For example:
  84
  85    radrelay -S secret_file <server> detail-combined
  86
  87    The use of -S is recommended over -s due to the fact that your secret
  88    won't show up with ps. You should also make sure your secret file is not
  89    world readable.
  90
  91    If the server you are relaying to is included in your 'clients.conf' file
  92    using the '-n [shortname]' commandline option is probably easiest. This
  93    means you won't have to give the remote server address or the shared
  94    secret when you start radrelay.
  95
  96    You should never logrotate your detail file, radrelay will take care of
  97    this for you.
  98
  99 3. REPLICATION AND PROXYING
 100
 101    If you have a primary and a backup server with identical configs
 102    that both proxy for certain realms to other radius servers, the
 103    remote server might end up with duplicate accounting info - the
 104    accounting packet is received by the backup server, proxied to
 105    the remote server and replicated to the primary server, then the
 106    primary server proxies the same packet to the remote radius server
 107    again because it doesn't know that that was already done.
 108
 109    To prevent this scenario, FreeRADIUS writes an extra attribute
 110    to the detail file if it has proxied the accounting packet, the
 111    vendor-specific attribute 'Freeradius-Proxied-To'. It contains the
 112    address of the remote radius server. Radrelay replicates this
 113    attribute just like any other to the primary server. If the
 114    primary server wants to proxy an accounting packet to a remote
 115    radius server, it first checks the packet to see if the
 116    'Freeradius-Proxied-To' attribute is present. If it is, and it
 117    contains the IP address of the remote radius server, it knows
 118    that it doesn't need to proxy this packet to the remote server
 119    once more. Problem solved!
 120
 121 4. NOTES
 122
 123    Only attributes that are defined in the dictionary are replicated.
 124    Unknown attributes are simply ignored.
 125
 126    Radrelay doesn't re-read its config files on a SIGHUP. It uses
 127    two config files - the dictionary (which can consist of multiple
 128    files ofcourse if you use $INCLUDE) and possibly the secret file.
 129    If you modify one of those files you need to restart radrelay.
 130
 131 5. CREDITS
 132    Original   - Miquel van Smoorenburg <miquels@cistron.nl>
 133                 Written for the Cistron radius project.
 134    2002-06-09 - Simon Ekstrand <simon@routemeister.net>
 135                 Ported to the FreeRADIUS project.
 136