doc/radius.txt

   1 Call Detail Recording to RADIUS Server
   2 ======================================
   3
   4
   5 Configuration of Asterisk to send CDRs to (Free)RADIUS servers.
   6
   7
   8 A. What is needed :
   9         * FreeRADIUS server
  10         * Radiusclient-ng library
  11         * Asterisk PBX
  12
  13
  14         +--------------------+
  15         |    Asterisk PBX    |
  16         |                    |
  17         |********************|
  18         |                    |        +---------------+
  19         |    RADIUS client   |------->| RADIUS server |
  20         |                    |<-------| (FreeRADIUS)  |
  21         +--------------------+        +---------------+
  22
  23
  24
  25
  26 B. Steps to follow in order to have RADIUS support:
  27
  28  1.Radiusclient library
  29         1.a Installation
  30
  31                 Download the sources from:
  32
  33                 http://developer.berlios.de/projects/radiusclient-ng/
  34
  35                 Untar the source tarball.
  36                         root@localhost:/usr/local/src# tar xvfz radiusclient-ng-0.5.2.tar.gz
  37
  38                 Compile and install the library.
  39                         root@localhost:/usr/local/src# cd radiusclient-ng-0.5.2
  40                         root@localhost:/usr/local/src/radiusclient-ng-0.5.2# ./configure
  41                         root@localhost:/usr/local/src/radiusclient-ng-0.5.2# make
  42                         root@localhost:/usr/local/src/radiusclient-ng-0.5.2# make install
  43
  44         1.b     Configuration
  45
  46                 By default all the configuration files of the radiusclient library will
  47                 be in /usr/local/etc/radiusclient-ng directory.
  48
  49                 File "radiusclient.conf"
  50                         Open the file and find lines containing the following:
  51
  52                                 authserver      localhost
  53
  54                 This is the hostname or IP address of the RADIUS server used for
  55                 authentication. You will have to change this unless the server is
  56                 running on the same host as your Asterisk PBX.
  57
  58                                 acctserver      localhost
  59
  60                 This is the hostname or IP address of the RADIUS server used for
  61                 accounting. You will have to change this unless the server is running
  62                 on the same host as your Asterisk PBX.
  63
  64                 File "servers"
  65
  66                 RADIUS protocol uses simple access control mechanism based on shared
  67                 secrets that allows RADIUS servers to limit access from RADIUS clients.
  68
  69                 A RADIUS server is configured with a secret string and only RADIUS
  70                 clients that have the same secret will be accepted.
  71
  72                 You need to configure a shared secret for each server you have
  73                 configured in radiusclient.conf file in the previous step. The shared
  74                 secrets are stored in /usr/local/etc/radiusclient-ng/servers file.
  75
  76                 Each line contains hostname of a RADIUS server and shared secret
  77                 used in communication with that server. The two values are separated
  78                 by white spaces. Configure shared secrets for every RADIUS server you
  79                 are going to use.
  80
  81                 File "dictionary"
  82
  83                 Asterisk uses some attributes that are not included in the
  84                 dictionary of radiusclient library, therefore it is necessary to add
  85                 them. A file called dictionary.digium (kept in the contrib dir)
  86                 was created to list all new attributes used by Asterisk.
  87                 Add to the end of the main dictionary file
  88                 /usr/local/etc/radiusclient-ng/dictionary
  89                 the line:
  90
  91                         $INCLUDE /path/to/dictionary.digium
  92
  93  2.FreeRADIUS Server (Version 1.1.1)
  94         2.a Installation
  95
  96                 Download sources tarball from:
  97
  98                         http://freeradius.org/
  99
 100                 Untar, configure, build, and install the server:
 101
 102                                 root@localhost:/usr/local/src# tar xvfz freeradius-1.1.1.tar.gz
 103                                 root@localhost:/usr/local/src# cd freeradius-1.1.1
 104                                 root@localhost"/usr/local/src/freeradius-1.1.1# ./configure
 105                                 root@localhost"/usr/local/src/freeradius-1.1.1# make
 106                                 root@localhost"/usr/local/src/freeradius-1.1.1# make install
 107
 108                 All the configuration files of FreeRADIUS server will be in
 109                 /usr/local/etc/raddb directory.
 110
 111
 112         2.b Configuration
 113
 114                 There are several file that have to be modified to configure the
 115                 RADIUS server. These are presented next.
 116
 117                 File "clients.conf"
 118
 119                 File /usr/local/etc/raddb/clients.conf contains description of
 120                 RADIUS clients that are allowed to use the server. For each of the
 121                 clients you need to specify its hostname or IP address and also a
 122                 shared secret. The shared secret must be the same string you configured
 123                 in radiusclient library.
 124
 125                 Example:
 126                         client myhost {
 127                             secret = mysecret
 128                             shortname = foo
 129                         }
 130
 131                 This fragment allows access from RADIUS clients on "myhost" if they use
 132                 "mysecret" as the shared secret.
 133                 The file already contains an entry for localhost (127.0.0.1), so if you
 134                 are running the RADIUS server on the same host as your Asterisk server,
 135                 then modify the existing entry instead, replacing the default password.
 136
 137                 File "dictionary"
 138
 139                 Note : as of version 1.1.2, the dictionary.digium file ships with FreeRADIUS.
 140                 The following procedure brings the dictionary.digium file to previous versions
 141                 of FreeRADIUS.
 142
 143                 File /usr/local/etc/raddb/dictionary contains the dictionary of
 144                 FreeRADIUS server. You have to add the same dictionary file
 145                 (dictionary.digium), which you added to the dictionary of radiusclient-ng
 146                 library. You can include it into the main file, adding the following line at the
 147                 end of file '/usr/local/etc/raddb/dictionary':
 148
 149                         $INCLUDE /path/to/dictionary.digium
 150
 151                 That will include the same new attribute definitions that are used
 152                 in radiusclient-ng library so the client and server will understand each
 153                 other.
 154
 155
 156  3. Asterisk Accounting Configuration
 157
 158         Compilation and installation:
 159         The module will be compiled as long as the radiusclient-ng
 160         library has been detected on your system.
 161
 162         By default FreeRADIUS server will log all accounting requests into
 163         /usr/local/var/log/radius/radacct directory in form of plain text files.
 164         The server will create one file for each hostname in the directory. The
 165         following example shows how the log files look like.
 166
 167         Asterisk now generates Call Detail Records. See /include/asterisk/cdr.h
 168         for all the fields which are recorded. By default, records in comma
 169         separated values will be created in /var/log/asterisk/cdr-csv.
 170
 171         The configuration file for cdr_radius.so module is :
 172
 173         /etc/asterisk/cdr.conf
 174         This is where you can set CDR related parameters as well as the path to
 175         the radiusclient-ng library configuration file.
 176
 177
 178  4. Logged Values
 179
 180   "Asterisk-Acc-Code",          The account name of detail records
 181   "Asterisk-Src",
 182   "Asterisk-Dst",
 183   "Asterisk-Dst-Ctx",           The destination context
 184   "Asterisk-Clid",
 185   "Asterisk-Chan",              The channel
 186   "Asterisk-Dst-Chan",          (if applicable)
 187   "Asterisk-Last-App",          Last application run on the channel
 188   "Asterisk-Last-Data",         Argument to the last channel
 189   "Asterisk-Start-Time",
 190   "Asterisk-Answer-Time",
 191   "Asterisk-End-Time",
 192   "Asterisk-Duration",          Duration is the whole length that the entire
 193                                 call lasted. ie. call rx'd to hangup
 194                                 "end time" minus "start time"
 195   "Asterisk-Bill-Sec",          The duration that a call was up after other
 196                                 end answered which will be <= to duration
 197                                 "end time" minus "answer time"
 198   "Asterisk-Disposition",       ANSWERED, NO ANSWER, BUSY
 199   "Asterisk-AMA-Flags",         DOCUMENTATION, BILL, IGNORE etc, specified on
 200                                 a per channel basis like accountcode.
 201   "Asterisk-Unique-ID",         Unique call identifier
 202   "Asterisk-User-Field"         User field set via SetCDRUserField
 203