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