Automatically create new buddy upon reception of a presence stanza of
[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] (32)          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] (32)          NULL
189                 )
190 \end{verbatim}
191 \end{astlisting}
192                 Start asterisk in verbose mode, you should see that asterisk
193                 logs a connection to the database and will now record every
194                 call to the database when it's complete.
195
196
197 \section{MYSQL}
198
199 Using MySQL for CDR records is supported by using ODBC and the cdr\_odbc module.
200
201 \section{PGSQL}
202         If you want to go directly to postgresql database, and have the cdr\_pgsql.so
203         compiled you can use the following sample setup.
204         On Debian, before compiling asterisk, just install libpqxx-dev.
205         Other distros will likely have a similiar package.
206
207         Once you have the compile done,
208         copy the sample cdr\_pgsql.conf file or create your own.
209
210         Here is a sample:
211 \begin{astlisting}
212 \begin{verbatim}
213         /etc/asterisk/cdr_pgsql.conf
214           ; Sample Asterisk config file for CDR logging to PostgresSQL
215           [global]
216           hostname=localhost
217           port=5432
218           dbname=asterisk
219           password=password
220           user=postgres
221           table=cdr
222 \end{verbatim}
223 \end{astlisting}
224         Now create a table in postgresql for your cdrs
225 \begin{astlisting}
226 \begin{verbatim}
227         CREATE TABLE cdr (
228                 calldate      time               NOT NULL ,
229                 clid          varchar (80)          NOT NULL ,
230                 src           varchar (80)          NOT NULL ,
231                 dst           varchar (80)          NOT NULL ,
232                 dcontext      varchar (80)          NOT NULL ,
233                 channel       varchar (80)          NOT NULL ,
234                 dstchannel    varchar (80)          NOT NULL ,
235                 lastapp       varchar (80)          NOT NULL ,
236                 lastdata      varchar (80)          NOT NULL ,
237                 duration      int                   NOT NULL ,
238                 billsec       int                   NOT NULL ,
239                 disposition   varchar (45)          NOT NULL ,
240                 amaflags      int                   NOT NULL ,
241                 accountcode   varchar (20)          NOT NULL ,
242                 uniqueid      varchar (32)          NOT NULL ,
243                 userfield     varchar (255)         NOT NULL
244         );
245 \end{verbatim}
246 \end{astlisting}
247
248 \section{SQLLITE}
249
250 SQLite version 2 is supported in cdr\_sqlite.
251
252 \section{RADIUS}
253
254 \subsection{What is needed}
255
256 \begin{itemize}
257         \item FreeRADIUS server
258         \item Radiusclient-ng library
259         \item Asterisk PBX
260 \end{itemize}
261
262 \begin{verbatim}
263         +--------------------+
264         |    Asterisk PBX    |
265         |                    |
266         |********************|
267         |                    |        +---------------+
268         |    RADIUS client   |------->| RADIUS server |
269         |                    |<-------| (FreeRADIUS)  |
270         +--------------------+        +---------------+
271 \end{verbatim}
272
273
274
275 \subsection{Steps to follow in order to have RADIUS support}
276
277 \subsubsection{Installation of the Radiusclient library}
278
279         Download the sources from       
280         \url{http://developer.berlios.de/projects/radiusclient-ng/}
281                 
282         Untar the source tarball:
283
284 \begin{verbatim}
285         root@localhost:/usr/local/src# tar xvfz radiusclient-ng-0.5.2.tar.gz
286 \end{verbatim}
287
288         Compile and install the library:
289
290 \begin{verbatim}
291         root@localhost:/usr/local/src# cd radiusclient-ng-0.5.2
292         root@localhost:/usr/local/src/radiusclient-ng-0.5.2# ./configure
293         root@localhost:/usr/local/src/radiusclient-ng-0.5.2# make
294         root@localhost:/usr/local/src/radiusclient-ng-0.5.2# make install
295 \end{verbatim}
296
297 \subsubsection{Configuration of the Radiusclient library}
298         
299         By default all the configuration files of the radiusclient library will
300         be in \path{/usr/local/etc/radiusclient-ng} directory.
301                 
302         File "radiusclient.conf"
303                 Open the file and find lines containing the following:
304
305                         authserver      localhost
306         
307         This is the hostname or IP address of the RADIUS server used for
308         authentication. You will have to change this unless the server is
309         running on the same host as your Asterisk PBX.
310
311                         acctserver      localhost
312
313         This is the hostname or IP address of the RADIUS server used for
314         accounting. You will have to change this unless the server is running
315         on the same host as your Asterisk PBX.
316
317         \textbf{File "servers"}
318                 
319         RADIUS protocol uses simple access control mechanism based on shared
320         secrets that allows RADIUS servers to limit access from RADIUS clients.
321                 
322         A RADIUS server is configured with a secret string and only RADIUS
323         clients that have the same secret will be accepted.
324
325         You need to configure a shared secret for each server you have
326         configured in radiusclient.conf file in the previous step. The shared
327         secrets are stored in \path{/usr/local/etc/radiusclient-ng/servers} file.
328
329         Each line contains hostname of a RADIUS server and shared secret
330         used in communication with that server. The two values are separated
331         by white spaces. Configure shared secrets for every RADIUS server you
332         are going to use.
333
334         \textbf{File "dictionary"}
335                         
336         Asterisk uses some attributes that are not included in the
337         dictionary of radiusclient library, therefore it is necessary to add
338         them. A file called dictionary.digium (kept in the contrib dir)
339         was created to list all new attributes used by Asterisk.
340         Add to the end of the main dictionary file
341         \path{/usr/local/etc/radiusclient-ng/dictionary} the line:
342
343                 \$INCLUDE /path/to/dictionary.digium
344
345 \subsubsection{Install FreeRADIUS Server (Version 1.1.1)}
346
347         Download sources tarball from:
348
349                 \url{http://freeradius.org/}
350                         
351         Untar, configure, build, and install the server:
352
353 \begin{verbatim}
354         root@localhost:/usr/local/src# tar xvfz freeradius-1.1.1.tar.gz
355         root@localhost:/usr/local/src# cd freeradius-1.1.1
356         root@localhost"/usr/local/src/freeradius-1.1.1# ./configure
357         root@localhost"/usr/local/src/freeradius-1.1.1# make
358         root@localhost"/usr/local/src/freeradius-1.1.1# make install
359 \end{verbatim}
360
361         All the configuration files of FreeRADIUS server will be in
362         /usr/local/etc/raddb directory.
363                 
364
365 \subsubsection{Configuration of the FreeRADIUS Server}
366                         
367         There are several files that have to be modified to configure the
368         RADIUS server. These are presented next.
369
370         File "clients.conf"
371                         
372         File \path{/usr/local/etc/raddb/clients.conf} contains description of
373         RADIUS clients that are allowed to use the server. For each of the
374         clients you need to specify its hostname or IP address and also a
375         shared secret. The shared secret must be the same string you configured
376         in radiusclient library.
377
378         Example:
379 \begin{verbatim}
380                 client myhost {
381                     secret = mysecret
382                     shortname = foo
383                 }
384 \end{verbatim}  
385
386         This fragment allows access from RADIUS clients on "myhost" if they use
387         "mysecret" as the shared secret.        
388         The file already contains an entry for localhost (127.0.0.1), so if you
389         are running the RADIUS server on the same host as your Asterisk server,
390         then modify the existing entry instead, replacing the default password.
391                 
392         File "dictionary"
393                 
394         Note: as of version 1.1.2, the dictionary.digium file ships with FreeRADIUS.
395         The following procedure brings the dictionary.digium file to previous versions
396         of FreeRADIUS.
397         
398         File \path{/usr/local/etc/raddb/dictionary} contains the dictionary of
399         FreeRADIUS server. You have to add the same dictionary file
400         (dictionary.digium), which you added to the dictionary of radiusclient-ng
401         library. You can include it into the main file, adding the following line at the
402         end of file \path{/usr/local/etc/raddb/dictionary}:
403                 
404         \$INCLUDE /path/to/dictionary.digium
405
406         That will include the same new attribute definitions that are used
407         in radiusclient-ng library so the client and server will understand each
408         other.
409
410
411 \subsubsection{Asterisk Accounting Configuration}
412
413         Compilation and installation:
414
415         The module will be compiled as long as the radiusclient-ng
416         library has been detected on your system.
417         
418         By default FreeRADIUS server will log all accounting requests into
419         \path{/usr/local/var/log/radius/radacct} directory in form of plain text files.
420         The server will create one file for each hostname in the directory. The
421         following example shows how the log files look like.
422
423         Asterisk now generates Call Detail Records. See \path{/include/asterisk/cdr.h}
424         for all the fields which are recorded. By default, records in comma
425         separated values will be created in \path{/var/log/asterisk/cdr-csv}.
426
427         The configuration file for cdr\_radius.so module is \path{/etc/asterisk/cdr.conf}
428         
429         This is where you can set CDR related parameters as well as the path to
430         the radiusclient-ng library configuration file.
431
432
433 \section{Logged Values}
434 \begin{verbatim}
435   "Asterisk-Acc-Code",          The account name of detail records
436   "Asterisk-Src",
437   "Asterisk-Dst",
438   "Asterisk-Dst-Ctx",           The destination context
439   "Asterisk-Clid",
440   "Asterisk-Chan",              The channel
441   "Asterisk-Dst-Chan",          (if applicable)
442   "Asterisk-Last-App",          Last application run on the channel
443   "Asterisk-Last-Data",         Argument to the last channel
444   "Asterisk-Start-Time",
445   "Asterisk-Answer-Time",
446   "Asterisk-End-Time",
447   "Asterisk-Duration",          Duration is the whole length that the entire
448                                 call lasted. ie. call rx'd to hangup
449                                 "end time" minus "start time"
450   "Asterisk-Bill-Sec",          The duration that a call was up after other
451                                 end answered which will be <= to duration
452                                 "end time" minus "answer time"
453   "Asterisk-Disposition",         ANSWERED, NO ANSWER, BUSY
454   "Asterisk-AMA-Flags",         DOCUMENTATION, BILL, IGNORE etc, specified on
455                                 a per channel basis like accountcode.
456   "Asterisk-Unique-ID",         Unique call identifier
457   "Asterisk-User-Field"         User field set via SetCDRUserField
458 \end{verbatim}