71b7530e66d857d4a3a7a09890290770974cdd41
[asterisk/asterisk.git] / 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 necesarry to add 
85                 them. A file called dictionary.asterisk was created to list all new 
86                 attributes used by Asterisk. Add into file
87                 /usr/local/etc/radiusclient-ng/dictionary
88                 the line:
89
90                         $INCLUDE /path/to/dictionary.asterisk
91
92  2.FreeRADIUS Server
93         2.a Installation
94                         
95                 Download sources tarball from:
96
97                         http://freeradius.org/
98                         
99                 Untar, configure, build, and install the server:
100
101                                 root@localhost:/usr/local/src# tar xvfz freeradius-1.1.1.tar.gz
102                                 root@localhost:/usr/local/src# cd freeradius-1.1.1
103                                 root@localhost"/usr/local/src/freeradius-1.1.1# ./configure
104                                 root@localhost"/usr/local/src/freeradius-1.1.1# make
105                                 root@localhost"/usr/local/src/freeradius-1.1.1# make install
106
107                 All the configuration files of FreeRADIUS server will be in 
108                 /usr/local/etc/raddb directory. 
109                 
110
111         2.b Configuration
112                         
113                 There are several file that have to be modified to configure the
114                 RADIUS server. These are presented next.
115
116                 File "clients.conf"
117                         
118                 File /usr/local/etc/raddb/clients.conf contains description of 
119                 RADIUS clients that are allowed to use the server. For each of the 
120                 clients you need to specify its hostname or IP address and also a 
121                 shared secret. The shared secret must be the same string you configured
122                 in radiusclient library.
123
124                 Example:
125                         client myhost {
126                             secret = mysecret
127                             shortname = foo
128                         }
129                 
130                 This fragment allows access from RADIUS clients on "myhost" if they use 
131                 "mysecret" as the shared secret.         
132                 The file already contains an entry for localhost (127.0.0.1), so if you
133                 are running the RADIUS server on the same host as your Asterisk server,
134                 then modify the existing entry instead, replacing the default password.
135
136                 File "dictionary"
137                         
138                 File /usr/local/etc/raddb/dictionary contains the dictionary of 
139                 FreeRADIUS server. You have to add the same dictionary file 
140                 (dictionary.asterisk), which you added to the dictionary of radiusclient-ng
141                 library. You can include it into the main file, adding the following line at the
142                 end of file '/usr/local/etc/raddb/dictionary':
143                         
144                         $INCLUDE /path/to/dictionary.digium
145
146                 That will include the same new attribute definitions that are used 
147                 in radiusclient-ng library so the client and server will understand each 
148                 other. 
149
150
151  3. Asterisk Accounting Configuration
152
153         Compilation and installation:
154         The module will be compiled as long as the radiusclient-ng
155         library has been detected on your system.
156         
157         By default FreeRADIUS server will log all accounting requests into 
158         /usr/local/var/log/radius/radacct directory in form of plain text files. 
159         The server will create one file for each hostname in the directory. The 
160         following example shows how the log files look like. 
161
162         Asterisk now generates Call Detail Records. See /include/asterisk/cdr.h
163         for all the fields which are recorded. By default, records in comma 
164         separated values will be created in /var/log/asterisk/cdr-csv. 
165
166         The configuration file for cdr_radius.so module is :
167
168         /etc/asterisk/cdr.conf 
169         This is where you can set CDR related parameters as well as the path to
170         the radiusclient-ng library configuration file.
171
172
173  4. Logged Values
174
175   "Asterisk-Acc-Code",          The account name of detail records
176   "Asterisk-Src",
177   "Asterisk-Dst",
178   "Asterisk-Dst-Ctx",           The destination context
179   "Asterisk-Clid",
180   "Asterisk-Chan",              The channel
181   "Asterisk-Dst-Chan",          (if applicable)
182   "Asterisk-Last-App",          Last application run on the channel 
183   "Asterisk-Last-Data",         Argument to the last channel 
184   "Asterisk-Start-Time",        
185   "Asterisk-Answer-Time", 
186   "Asterisk-End-Time", 
187   "Asterisk-Duration",          Duration is the whole length that the entire 
188                                 call lasted. ie. call rx'd to hangup 
189                                 "end time" minus "start time" 
190   "Asterisk-Bill-Sec",          The duration that a call was up after other 
191                                 end answered which will be <= to duration  
192                                 "end time" minus "answer time" 
193   "Asterisk-Disposition",       ANSWERED, NO ANSWER, BUSY 
194   "Asterisk-AMA-Flags",         DOCUMENTATION, BILL, IGNORE etc, specified on 
195                                 a per channel basis like accountcode. 
196   "Asterisk-Unique-ID",         Unique call identifier 
197   "Asterisk-User-Field"         User field set via SetCDRUserField 
198