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