Many doc directory improvements, including:
[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
253         Download the sources from       
254         \url{http://developer.berlios.de/projects/radiusclient-ng/}
255                 
256         Untar the source tarball:
257
258 \begin{verbatim}
259         root@localhost:/usr/local/src# tar xvfz radiusclient-ng-0.5.2.tar.gz
260 \end{verbatim}
261
262         Compile and install the library:
263
264 \begin{verbatim}
265         root@localhost:/usr/local/src# cd radiusclient-ng-0.5.2
266         root@localhost:/usr/local/src/radiusclient-ng-0.5.2# ./configure
267         root@localhost:/usr/local/src/radiusclient-ng-0.5.2# make
268         root@localhost:/usr/local/src/radiusclient-ng-0.5.2# make install
269 \end{verbatim}
270
271 \subsubsection{Configuration of the Radiusclient library}
272         
273         By default all the configuration files of the radiusclient library will
274         be in \path{/usr/local/etc/radiusclient-ng} directory.
275                 
276         File "radiusclient.conf"
277                 Open the file and find lines containing the following:
278
279                         authserver      localhost
280         
281         This is the hostname or IP address of the RADIUS server used for 
282         authentication. You will have to change this unless the server is 
283         running on the same host as your Asterisk PBX.
284
285                         acctserver      localhost
286
287         This is the hostname or IP address of the RADIUS server used for 
288         accounting. You will have to change this unless the server is running
289         on the same host as your Asterisk PBX.
290
291         \textbf{File "servers"} 
292                 
293         RADIUS protocol uses simple access control mechanism based on shared
294         secrets that allows RADIUS servers to limit access from RADIUS clients.
295                 
296         A RADIUS server is configured with a secret string and only RADIUS 
297         clients that have the same secret will be accepted.
298
299         You need to configure a shared secret for each server you have 
300         configured in radiusclient.conf file in the previous step. The shared 
301         secrets are stored in \path{/usr/local/etc/radiusclient-ng/servers} file.
302
303         Each line contains hostname of a RADIUS server and shared secret 
304         used in communication with that server. The two values are separated 
305         by white spaces. Configure shared secrets for every RADIUS server you 
306         are going to use.
307
308         \textbf{File "dictionary"}
309                         
310         Asterisk uses some attributes that are not included in the 
311         dictionary of radiusclient library, therefore it is necessary to add 
312         them. A file called dictionary.digium (kept in the contrib dir)
313         was created to list all new attributes used by Asterisk. 
314         Add to the end of the main dictionary file
315         \path{/usr/local/etc/radiusclient-ng/dictionary} the line:
316
317                 \$INCLUDE /path/to/dictionary.digium
318
319 \subsubsection{Install FreeRADIUS Server (Version 1.1.1)}
320  
321         Download sources tarball from:
322
323                 \url{http://freeradius.org/}
324                         
325         Untar, configure, build, and install the server:
326
327 \begin{verbatim}
328         root@localhost:/usr/local/src# tar xvfz freeradius-1.1.1.tar.gz
329         root@localhost:/usr/local/src# cd freeradius-1.1.1
330         root@localhost"/usr/local/src/freeradius-1.1.1# ./configure
331         root@localhost"/usr/local/src/freeradius-1.1.1# make
332         root@localhost"/usr/local/src/freeradius-1.1.1# make install
333 \end{verbatim}
334
335         All the configuration files of FreeRADIUS server will be in 
336         /usr/local/etc/raddb directory. 
337                 
338
339 \subsubsection{Configuration of the FreeRADIUS Server}
340                         
341         There are several files that have to be modified to configure the
342         RADIUS server. These are presented next.
343
344         File "clients.conf"
345                         
346         File \path{/usr/local/etc/raddb/clients.conf} contains description of 
347         RADIUS clients that are allowed to use the server. For each of the 
348         clients you need to specify its hostname or IP address and also a 
349         shared secret. The shared secret must be the same string you configured
350         in radiusclient library.
351
352         Example:
353 \begin{verbatim}
354                 client myhost {
355                     secret = mysecret
356                     shortname = foo
357                 }
358 \end{verbatim}  
359
360         This fragment allows access from RADIUS clients on "myhost" if they use 
361         "mysecret" as the shared secret.         
362         The file already contains an entry for localhost (127.0.0.1), so if you
363         are running the RADIUS server on the same host as your Asterisk server,
364         then modify the existing entry instead, replacing the default password.
365                 
366         File "dictionary"
367                 
368         Note: as of version 1.1.2, the dictionary.digium file ships with FreeRADIUS. 
369         The following procedure brings the dictionary.digium file to previous versions 
370         of FreeRADIUS.
371         
372         File \path{/usr/local/etc/raddb/dictionary} contains the dictionary of 
373         FreeRADIUS server. You have to add the same dictionary file 
374         (dictionary.digium), which you added to the dictionary of radiusclient-ng
375         library. You can include it into the main file, adding the following line at the
376         end of file \path{/usr/local/etc/raddb/dictionary}:
377                 
378         \$INCLUDE /path/to/dictionary.digium
379
380         That will include the same new attribute definitions that are used 
381         in radiusclient-ng library so the client and server will understand each 
382         other. 
383
384
385 \subsubsection{Asterisk Accounting Configuration}
386
387         Compilation and installation:
388
389         The module will be compiled as long as the radiusclient-ng
390         library has been detected on your system.
391         
392         By default FreeRADIUS server will log all accounting requests into 
393         \path{/usr/local/var/log/radius/radacct} directory in form of plain text files. 
394         The server will create one file for each hostname in the directory. The 
395         following example shows how the log files look like. 
396
397         Asterisk now generates Call Detail Records. See \path{/include/asterisk/cdr.h}
398         for all the fields which are recorded. By default, records in comma 
399         separated values will be created in \path{/var/log/asterisk/cdr-csv}. 
400
401         The configuration file for cdr\_radius.so module is \path{/etc/asterisk/cdr.conf}
402          
403         This is where you can set CDR related parameters as well as the path to
404         the radiusclient-ng library configuration file.
405
406
407 \section{Logged Values}
408 \begin{verbatim}
409   "Asterisk-Acc-Code",          The account name of detail records
410   "Asterisk-Src",
411   "Asterisk-Dst",
412   "Asterisk-Dst-Ctx",           The destination context
413   "Asterisk-Clid",
414   "Asterisk-Chan",              The channel
415   "Asterisk-Dst-Chan",          (if applicable)
416   "Asterisk-Last-App",          Last application run on the channel 
417   "Asterisk-Last-Data",         Argument to the last channel 
418   "Asterisk-Start-Time",        
419   "Asterisk-Answer-Time", 
420   "Asterisk-End-Time", 
421   "Asterisk-Duration",          Duration is the whole length that the entire 
422                                 call lasted. ie. call rx'd to hangup 
423                                 "end time" minus "start time" 
424   "Asterisk-Bill-Sec",          The duration that a call was up after other 
425                                 end answered which will be <= to duration  
426                                 "end time" minus "answer time" 
427   "Asterisk-Disposition",         ANSWERED, NO ANSWER, BUSY 
428   "Asterisk-AMA-Flags",         DOCUMENTATION, BILL, IGNORE etc, specified on 
429                                 a per channel basis like accountcode. 
430   "Asterisk-Unique-ID",         Unique call identifier 
431   "Asterisk-User-Field"         User field set via SetCDRUserField 
432 \end{verbatim}