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