Add the Ring time in the CONNECT on the queue_log and on the Manager event AgentConnect
[asterisk/asterisk.git] / doc / tex / cdrdriver.tex
1 Call data records can be stored in many different databases or even CSV text.
2
3 \section{MSSQL}
4
5         Asterisk can currently store CDRs into an MSSQL database in
6         two different ways:  cdr\_odbc or cdr\_tds
7         
8         Call Data Records can be stored using unixODBC (which requires
9         the FreeTDS package) [cdr\_odbc] or directly by using just the
10         FreeTDS package [cdr\_tds]  The following provide some
11         examples known to get asterisk working with mssql.
12
13         NOTE:  Only choose one db connector.
14
15 \subsection{ODBC using cdr\_odbc}
16         Compile, configure, and install the latest unixODBC package:
17 \begin{verbatim}
18         tar -zxvf unixODBC-2.2.9.tar.gz &&
19         cd unixODBC-2.2.9 &&
20         ./configure --sysconfdir=/etc --prefix=/usr --disable-gui &&
21         make &&
22         make install
23 \end{verbatim}
24
25         Compile, configure, and install the latest FreeTDS package:
26 \begin{verbatim}
27         tar -zxvf freetds-0.62.4.tar.gz &&
28         cd freetds-0.62.4 &&
29         ./configure --prefix=/usr --with-tdsver=7.0 \
30                  --with-unixodbc=/usr/lib &&
31         make && make install
32 \end{verbatim}
33
34         Compile, or recompile, asterisk so that it will now add support
35         for cdr\_odbc.
36 \begin{verbatim}
37         make clean && ./configure --with-odbc &&
38         make update &&
39         make &&
40         make install
41 \end{verbatim}
42
43         Setup odbc configuration files.  These are working examples
44         from my system.  You will need to modify for your setup.
45         You are not required to store usernames or passwords here.
46
47 \begin{verbatim}
48         /etc/odbcinst.ini
49            [FreeTDS]
50            Description    = FreeTDS ODBC driver for MSSQL
51            Driver         = /usr/lib/libtdsodbc.so
52            Setup          = /usr/lib/libtdsS.so
53            FileUsage      = 1
54
55         /etc/odbc.ini
56            [MSSQL-asterisk]
57            description         = Asterisk ODBC for MSSQL
58            driver              = FreeTDS
59            server              = 192.168.1.25
60            port                = 1433
61            database            = voipdb
62            tds_version         = 7.0
63            language            = us_english
64 \end{verbatim}
65
66                 Only install one database connector.  Do not confuse asterisk
67                 by using both ODBC (cdr\_odbc) and FreeTDS (cdr\_tds).
68                 This command will erase the contents of cdr\_tds.conf 
69 \begin{verbatim}
70                 [ -f /etc/asterisk/cdr_tds.conf ] > /etc/asterisk/cdr_tds.conf
71 \end{verbatim}
72                 NOTE:  unixODBC requires the freeTDS package, but asterisk does
73                 not call freeTDS directly.
74
75                 Now set up cdr\_odbc configuration files.  These are working samples
76                 from my system.  You will need to modify for your setup. Define
77                 your usernames and passwords here, secure file as well.
78 \begin{verbatim}
79                 /etc/asterisk/cdr_odbc.conf
80                    [global]
81                    dsn=MSSQL-asterisk
82                    username=voipdbuser
83                    password=voipdbpass
84                    loguniqueid=yes
85 \end{verbatim}
86                 And finally, create the 'cdr' table in your mssql database.
87 \begin{verbatim}
88                 CREATE TABLE cdr ( 
89                         [calldate]      [datetime]              NOT NULL ,
90                         [clid]          [varchar] (80)          NOT NULL ,
91                         [src]           [varchar] (80)          NOT NULL ,
92                         [dst]           [varchar] (80)          NOT NULL ,
93                         [dcontext]      [varchar] (80)          NOT NULL ,
94                         [channel]       [varchar] (80)          NOT NULL ,
95                         [dstchannel]    [varchar] (80)          NOT NULL ,
96                         [lastapp]       [varchar] (80)          NOT NULL ,
97                         [lastdata]      [varchar] (80)          NOT NULL ,
98                         [duration]      [int]                   NOT NULL ,
99                         [billsec]       [int]                   NOT NULL ,
100                         [disposition]   [varchar] (45)          NOT NULL ,
101                         [amaflags]      [int]                   NOT NULL ,
102                         [accountcode]   [varchar] (20)          NOT NULL ,
103                         [uniqueid]      [varchar] (32)          NOT NULL ,
104                         [userfield]     [varchar] (255)         NOT NULL
105                 )
106 \end{verbatim}
107                 Start asterisk in verbose mode, you should see that asterisk
108                 logs a connection to the database and will now record every
109                 call to the database when it's complete.
110
111 \subsection{TDS, using cdr\_tds}
112                 Compile, configure, and install the latest FreeTDS package:
113 \begin{verbatim}
114                    tar -zxvf freetds-0.62.4.tar.gz &&
115                    cd freetds-0.62.4 &&
116                    ./configure --prefix=/usr --with-tdsver=7.0
117                    make &&
118                    make install
119 \end{verbatim}
120                 Compile, or recompile, asterisk so that it will now add support
121                 for cdr\_tds.
122 \begin{verbatim}
123                    make clean && ./configure --with-tds &&
124                    make update &&
125                    make &&
126                    make install
127 \end{verbatim}
128                 Only install one database connector.  Do not confuse asterisk
129                 by using both ODBC (cdr\_odbc) and FreeTDS (cdr\_tds).
130                 This command will erase the contents of cdr\_odbc.conf
131 \begin{verbatim}
132                 [ -f /etc/asterisk/cdr_odbc.conf ] > /etc/asterisk/cdr_odbc.conf
133 \end{verbatim}
134                 Setup cdr\_tds configuration files.  These are working samples
135                 from my system.  You will need to modify for your setup. Define
136                 your usernames and passwords here, secure file as well.
137 \begin{verbatim}
138                 /etc/asterisk/cdr_tds.conf
139                    [global]
140                    hostname=192.168.1.25
141                    port=1433
142                    dbname=voipdb
143                    user=voipdbuser
144                    password=voipdpass
145                    charset=BIG5
146 \end{verbatim}
147                 And finally, create the 'cdr' table in your mssql database.
148 \begin{verbatim}
149                 CREATE TABLE cdr (
150                         [accountcode]   [varchar] (20)          NULL ,
151                         [src]           [varchar] (80)          NULL ,
152                         [dst]           [varchar] (80)          NULL ,
153                         [dcontext]      [varchar] (80)          NULL ,
154                         [clid]          [varchar] (80)          NULL ,
155                         [channel]       [varchar] (80)          NULL ,
156                         [dstchannel]    [varchar] (80)          NULL ,
157                         [lastapp]       [varchar] (80)          NULL ,
158                         [lastdata]      [varchar] (80)          NULL ,
159                         [start]         [datetime]              NULL ,
160                         [answer]        [datetime]              NULL ,
161                         [end]           [datetime]              NULL ,
162                         [duration]      [int]                   NULL ,
163                         [billsec]       [int]                   NULL ,
164                         [disposition]   [varchar] (20)          NULL ,
165                         [amaflags]      [varchar] (16)          NULL ,
166                         [uniqueid]      [varchar] (32)          NULL
167                 )
168 \end{verbatim}
169                 Start asterisk in verbose mode, you should see that asterisk
170                 logs a connection to the database and will now record every
171                 call to the database when it's complete.
172
173
174 \section{MYSQL}
175
176 Using MySQL for CDR records is supported by using ODBC and the cdr\_odbc module.
177
178 \section{PGSQL}
179         If you want to go directly to postgresql database, and have the cdr\_pgsql.so
180         compiled you can use the following sample setup.
181         On Debian, before compiling asterisk, just install libpqxx-dev.
182         Other distros will likely have a similiar package.
183
184         Once you have the compile done,
185         copy the sample cdr\_pgsql.conf file or create your own.
186
187         Here is a sample:
188 \begin{verbatim}
189         /etc/asterisk/cdr_pgsql.conf
190           ; Sample Asterisk config file for CDR logging to PostgresSQL
191           [global]
192           hostname=localhost
193           port=5432
194           dbname=asterisk
195           password=password
196           user=postgres
197           table=cdr
198 \end{verbatim}
199         Now create a table in postgresql for your cdrs
200
201 \begin{verbatim}
202         CREATE TABLE cdr (
203                 calldate      time               NOT NULL ,
204                 clid          varchar (80)          NOT NULL ,
205                 src           varchar (80)          NOT NULL ,
206                 dst           varchar (80)          NOT NULL ,
207                 dcontext      varchar (80)          NOT NULL ,
208                 channel       varchar (80)          NOT NULL ,
209                 dstchannel    varchar (80)          NOT NULL ,
210                 lastapp       varchar (80)          NOT NULL ,
211                 lastdata      varchar (80)          NOT NULL ,
212                 duration      int                   NOT NULL ,
213                 billsec       int                   NOT NULL ,
214                 disposition   varchar (45)          NOT NULL ,
215                 amaflags      int                   NOT NULL ,
216                 accountcode   varchar (20)          NOT NULL ,
217                 uniqueid      varchar (32)          NOT NULL ,
218                 userfield     varchar (255)         NOT NULL
219         );
220 \end{verbatim}
221
222 \section{SQLLITE}
223
224 SQLite version 2 is supported in cdr\_sqlite.
225
226 \section{RADIUS}
227
228 \subsection{What is needed}
229
230 \begin{itemize}
231         \item FreeRADIUS server
232         \item Radiusclient-ng library
233         \item Asterisk PBX
234 \end{itemize}
235
236 \begin{verbatim}
237         +--------------------+
238         |    Asterisk PBX    |
239         |                    |
240         |********************|
241         |                    |        +---------------+
242         |    RADIUS client   |------->| RADIUS server |
243         |                    |<-------| (FreeRADIUS)  |
244         +--------------------+        +---------------+
245 \end{verbatim}
246
247
248
249 \subsection{Steps to follow in order to have RADIUS support}
250
251 \subsubsection{Installation of the Radiusclient library}
252    Installation:
253 \begin{verbatim}        
254         Download the sources from:
255                 
256         http://developer.berlios.de/projects/radiusclient-ng/
257                 
258         Untar the source tarball.
259                 root@localhost:/usr/local/src# tar xvfz radiusclient-ng-0.5.2.tar.gz
260
261         Compile and install the library.
262                 root@localhost:/usr/local/src# cd radiusclient-ng-0.5.2
263                 root@localhost:/usr/local/src/radiusclient-ng-0.5.2# ./configure
264                 root@localhost:/usr/local/src/radiusclient-ng-0.5.2# make
265                 root@localhost:/usr/local/src/radiusclient-ng-0.5.2# make install
266 \end{verbatim}
267
268 \subsubsection{Configuration of the Radiusclient library}
269         
270         By default all the configuration files of the radiusclient library will
271         be in /usr/local/etc/radiusclient-ng directory.
272                 
273         File "radiusclient.conf"
274                 Open the file and find lines containing the following:
275
276                         authserver      localhost
277         
278         This is the hostname or IP address of the RADIUS server used for 
279         authentication. You will have to change this unless the server is 
280         running on the same host as your Asterisk PBX.
281
282                         acctserver      localhost
283         This is the hostname or IP address of the RADIUS server used for 
284         accounting. You will have to change this unless the server is running
285         on the same host as your Asterisk PBX.
286
287         File "servers" 
288                 
289         RADIUS protocol uses simple access control mechanism based on shared
290         secrets that allows RADIUS servers to limit access from RADIUS clients.
291                 
292         A RADIUS server is configured with a secret string and only RADIUS 
293         clients that have the same secret will be accepted.
294
295         You need to configure a shared secret for each server you have 
296         configured in radiusclient.conf file in the previous step. The shared 
297         secrets are stored in /usr/local/etc/radiusclient-ng/servers file.
298
299         Each line contains hostname of a RADIUS server and shared secret 
300         used in communication with that server. The two values are separated 
301         by white spaces. Configure shared secrets for every RADIUS server you 
302         are going to use.
303
304         File "dictionary"
305                         
306         Asterisk uses some attributes that are not included in the 
307         dictionary of radiusclient library, therefore it is necessary to add 
308         them. A file called dictionary.digium (kept in the contrib dir)
309         was created to list all new attributes used by Asterisk. 
310         Add to the end of the main dictionary file
311         /usr/local/etc/radiusclient-ng/dictionary
312         the line:
313 \begin{verbatim}
314                 \$INCLUDE /path/to/dictionary.digium
315 \end{verbatim}
316
317 \subsubsection{Install FreeRADIUS Server (Version 1.1.1)}
318  
319         Download sources tarball from:
320
321                 \url{http://freeradius.org/}
322                         
323         Untar, configure, build, and install the server:
324
325 \begin{verbatim}
326         root@localhost:/usr/local/src# tar xvfz freeradius-1.1.1.tar.gz
327         root@localhost:/usr/local/src# cd freeradius-1.1.1
328         root@localhost"/usr/local/src/freeradius-1.1.1# ./configure
329         root@localhost"/usr/local/src/freeradius-1.1.1# make
330         root@localhost"/usr/local/src/freeradius-1.1.1# make install
331 \end{verbatim}
332
333         All the configuration files of FreeRADIUS server will be in 
334         /usr/local/etc/raddb directory. 
335                 
336
337 \subsubsection{Configuration of the FreeRADIUS Server}
338                         
339         There are several files that have to be modified to configure the
340         RADIUS server. These are presented next.
341
342         File "clients.conf"
343                         
344         File /usr/local/etc/raddb/clients.conf contains description of 
345         RADIUS clients that are allowed to use the server. For each of the 
346         clients you need to specify its hostname or IP address and also a 
347         shared secret. The shared secret must be the same string you configured
348         in radiusclient library.
349
350         Example:
351 \begin{verbatim}
352                 client myhost {
353                     secret = mysecret
354                     shortname = foo
355                 }
356 \end{verbatim}  
357
358         This fragment allows access from RADIUS clients on "myhost" if they use 
359         "mysecret" as the shared secret.         
360         The file already contains an entry for localhost (127.0.0.1), so if you
361         are running the RADIUS server on the same host as your Asterisk server,
362         then modify the existing entry instead, replacing the default password.
363                 
364         File "dictionary"
365                 
366         Note : as of version 1.1.2, the dictionary.digium file ships with FreeRADIUS. 
367         The following procedure brings the dictionary.digium file to previous versions 
368         of FreeRADIUS.
369         
370         File /usr/local/etc/raddb/dictionary contains the dictionary of 
371         FreeRADIUS server. You have to add the same dictionary file 
372         (dictionary.digium), which you added to the dictionary of radiusclient-ng
373         library. You can include it into the main file, adding the following line at the
374         end of file '/usr/local/etc/raddb/dictionary':
375                 
376         \$INCLUDE /path/to/dictionary.digium
377
378         That will include the same new attribute definitions that are used 
379         in radiusclient-ng library so the client and server will understand each 
380         other. 
381
382
383 \subsubsection{Asterisk Accounting Configuration}
384
385         Compilation and installation:
386
387         The module will be compiled as long as the radiusclient-ng
388         library has been detected on your system.
389         
390         By default FreeRADIUS server will log all accounting requests into 
391         /usr/local/var/log/radius/radacct directory in form of plain text files. 
392         The server will create one file for each hostname in the directory. The 
393         following example shows how the log files look like. 
394
395         Asterisk now generates Call Detail Records. See /include/asterisk/cdr.h
396         for all the fields which are recorded. By default, records in comma 
397         separated values will be created in /var/log/asterisk/cdr-csv. 
398
399         The configuration file for cdr\_radius.so module is :
400
401         /etc/asterisk/cdr.conf 
402         This is where you can set CDR related parameters as well as the path to
403         the radiusclient-ng library configuration file.
404
405
406 \section{Logged Values}
407 \begin{verbatim}
408   "Asterisk-Acc-Code",          The account name of detail records
409   "Asterisk-Src",
410   "Asterisk-Dst",
411   "Asterisk-Dst-Ctx",           The destination context
412   "Asterisk-Clid",
413   "Asterisk-Chan",              The channel
414   "Asterisk-Dst-Chan",          (if applicable)
415   "Asterisk-Last-App",          Last application run on the channel 
416   "Asterisk-Last-Data",         Argument to the last channel 
417   "Asterisk-Start-Time",        
418   "Asterisk-Answer-Time", 
419   "Asterisk-End-Time", 
420   "Asterisk-Duration",          Duration is the whole length that the entire 
421                                 call lasted. ie. call rx'd to hangup 
422                                 "end time" minus "start time" 
423   "Asterisk-Bill-Sec",          The duration that a call was up after other 
424                                 end answered which will be <= to duration  
425                                 "end time" minus "answer time" 
426   "Asterisk-Disposition",       ANSWERED, NO ANSWER, BUSY 
427   "Asterisk-AMA-Flags",         DOCUMENTATION, BILL, IGNORE etc, specified on 
428                                 a per channel basis like accountcode. 
429   "Asterisk-Unique-ID",         Unique call identifier 
430   "Asterisk-User-Field"         User field set via SetCDRUserField 
431 \end{verbatim}