diff options
Diffstat (limited to 'trunk/doc/tex/cdrdriver.tex')
| -rw-r--r-- | trunk/doc/tex/cdrdriver.tex | 458 |
1 files changed, 458 insertions, 0 deletions
diff --git a/trunk/doc/tex/cdrdriver.tex b/trunk/doc/tex/cdrdriver.tex new file mode 100644 index 000000000..174df5b68 --- /dev/null +++ b/trunk/doc/tex/cdrdriver.tex @@ -0,0 +1,458 @@ +Call data records can be stored in many different databases or even CSV text. + +\section{MSSQL} + + Asterisk can currently store CDRs into an MSSQL database in + two different ways: cdr\_odbc or cdr\_tds + + Call Data Records can be stored using unixODBC (which requires + the FreeTDS package) [cdr\_odbc] or directly by using just the + FreeTDS package [cdr\_tds] The following provide some + examples known to get asterisk working with mssql. + + NOTE: Only choose one db connector. + +\subsection{ODBC using cdr\_odbc} + Compile, configure, and install the latest unixODBC package: +\begin{astlisting} +\begin{verbatim} + tar -zxvf unixODBC-2.2.9.tar.gz && + cd unixODBC-2.2.9 && + ./configure --sysconfdir=/etc --prefix=/usr --disable-gui && + make && + make install +\end{verbatim} +\end{astlisting} + + Compile, configure, and install the latest FreeTDS package: +\begin{astlisting} +\begin{verbatim} + tar -zxvf freetds-0.62.4.tar.gz && + cd freetds-0.62.4 && + ./configure --prefix=/usr --with-tdsver=7.0 \ + --with-unixodbc=/usr/lib && + make && make install +\end{verbatim} +\end{astlisting} + + Compile, or recompile, asterisk so that it will now add support + for cdr\_odbc. +\begin{astlisting} +\begin{verbatim} + make clean && ./configure --with-odbc && + make update && + make && + make install +\end{verbatim} +\end{astlisting} + + Setup odbc configuration files. These are working examples + from my system. You will need to modify for your setup. + You are not required to store usernames or passwords here. +\begin{astlisting} +\begin{verbatim} + /etc/odbcinst.ini + [FreeTDS] + Description = FreeTDS ODBC driver for MSSQL + Driver = /usr/lib/libtdsodbc.so + Setup = /usr/lib/libtdsS.so + FileUsage = 1 + + /etc/odbc.ini + [MSSQL-asterisk] + description = Asterisk ODBC for MSSQL + driver = FreeTDS + server = 192.168.1.25 + port = 1433 + database = voipdb + tds_version = 7.0 + language = us_english +\end{verbatim} +\end{astlisting} + + Only install one database connector. Do not confuse asterisk + by using both ODBC (cdr\_odbc) and FreeTDS (cdr\_tds). + This command will erase the contents of cdr\_tds.conf +\begin{astlisting} +\begin{verbatim} + [ -f /etc/asterisk/cdr_tds.conf ] > /etc/asterisk/cdr_tds.conf +\end{verbatim} +\end{astlisting} + NOTE: unixODBC requires the freeTDS package, but asterisk does + not call freeTDS directly. + + Now set up cdr\_odbc configuration files. These are working samples + from my system. You will need to modify for your setup. Define + your usernames and passwords here, secure file as well. +\begin{astlisting} +\begin{verbatim} + /etc/asterisk/cdr_odbc.conf + [global] + dsn=MSSQL-asterisk + username=voipdbuser + password=voipdbpass + loguniqueid=yes +\end{verbatim} +\end{astlisting} + And finally, create the 'cdr' table in your mssql database. +\begin{astlisting} +\begin{verbatim} + CREATE TABLE cdr ( + [calldate] [datetime] NOT NULL , + [clid] [varchar] (80) NOT NULL , + [src] [varchar] (80) NOT NULL , + [dst] [varchar] (80) NOT NULL , + [dcontext] [varchar] (80) NOT NULL , + [channel] [varchar] (80) NOT NULL , + [dstchannel] [varchar] (80) NOT NULL , + [lastapp] [varchar] (80) NOT NULL , + [lastdata] [varchar] (80) NOT NULL , + [duration] [int] NOT NULL , + [billsec] [int] NOT NULL , + [disposition] [varchar] (45) NOT NULL , + [amaflags] [int] NOT NULL , + [accountcode] [varchar] (20) NOT NULL , + [uniqueid] [varchar] (32) NOT NULL , + [userfield] [varchar] (255) NOT NULL + ) +\end{verbatim} +\end{astlisting} + Start asterisk in verbose mode, you should see that asterisk + logs a connection to the database and will now record every + call to the database when it's complete. + +\subsection{TDS, using cdr\_tds} + Compile, configure, and install the latest FreeTDS package: +\begin{astlisting} +\begin{verbatim} + tar -zxvf freetds-0.62.4.tar.gz && + cd freetds-0.62.4 && + ./configure --prefix=/usr --with-tdsver=7.0 + make && + make install +\end{verbatim} +\end{astlisting} + Compile, or recompile, asterisk so that it will now add support + for cdr\_tds. +\begin{astlisting} +\begin{verbatim} + make clean && ./configure --with-tds && + make update && + make && + make install +\end{verbatim} +\end{astlisting} + Only install one database connector. Do not confuse asterisk + by using both ODBC (cdr\_odbc) and FreeTDS (cdr\_tds). + This command will erase the contents of cdr\_odbc.conf +\begin{astlisting} +\begin{verbatim} + [ -f /etc/asterisk/cdr_odbc.conf ] > /etc/asterisk/cdr_odbc.conf +\end{verbatim} +\end{astlisting} + Setup cdr\_tds configuration files. These are working samples + from my system. You will need to modify for your setup. Define + your usernames and passwords here, secure file as well. +\begin{astlisting} +\begin{verbatim} + /etc/asterisk/cdr_tds.conf + [global] + hostname=192.168.1.25 + port=1433 + dbname=voipdb + user=voipdbuser + password=voipdpass + charset=BIG5 +\end{verbatim} +\end{astlisting} + And finally, create the 'cdr' table in your mssql database. +\begin{astlisting} +\begin{verbatim} + CREATE TABLE cdr ( + [accountcode] [varchar] (20) NULL , + [src] [varchar] (80) NULL , + [dst] [varchar] (80) NULL , + [dcontext] [varchar] (80) NULL , + [clid] [varchar] (80) NULL , + [channel] [varchar] (80) NULL , + [dstchannel] [varchar] (80) NULL , + [lastapp] [varchar] (80) NULL , + [lastdata] [varchar] (80) NULL , + [start] [datetime] NULL , + [answer] [datetime] NULL , + [end] [datetime] NULL , + [duration] [int] NULL , + [billsec] [int] NULL , + [disposition] [varchar] (20) NULL , + [amaflags] [varchar] (16) NULL , + [uniqueid] [varchar] (32) NULL + ) +\end{verbatim} +\end{astlisting} + Start asterisk in verbose mode, you should see that asterisk + logs a connection to the database and will now record every + call to the database when it's complete. + + +\section{MYSQL} + +Using MySQL for CDR records is supported by using ODBC and the cdr\_odbc module. + +\section{PGSQL} + If you want to go directly to postgresql database, and have the cdr\_pgsql.so + compiled you can use the following sample setup. + On Debian, before compiling asterisk, just install libpqxx-dev. + Other distros will likely have a similiar package. + + Once you have the compile done, + copy the sample cdr\_pgsql.conf file or create your own. + + Here is a sample: +\begin{astlisting} +\begin{verbatim} + /etc/asterisk/cdr_pgsql.conf + ; Sample Asterisk config file for CDR logging to PostgresSQL + [global] + hostname=localhost + port=5432 + dbname=asterisk + password=password + user=postgres + table=cdr +\end{verbatim} +\end{astlisting} + Now create a table in postgresql for your cdrs +\begin{astlisting} +\begin{verbatim} + CREATE TABLE cdr ( + calldate time NOT NULL , + clid varchar (80) NOT NULL , + src varchar (80) NOT NULL , + dst varchar (80) NOT NULL , + dcontext varchar (80) NOT NULL , + channel varchar (80) NOT NULL , + dstchannel varchar (80) NOT NULL , + lastapp varchar (80) NOT NULL , + lastdata varchar (80) NOT NULL , + duration int NOT NULL , + billsec int NOT NULL , + disposition varchar (45) NOT NULL , + amaflags int NOT NULL , + accountcode varchar (20) NOT NULL , + uniqueid varchar (32) NOT NULL , + userfield varchar (255) NOT NULL + ); +\end{verbatim} +\end{astlisting} + +\section{SQLLITE} + +SQLite version 2 is supported in cdr\_sqlite. + +\section{RADIUS} + +\subsection{What is needed} + +\begin{itemize} + \item FreeRADIUS server + \item Radiusclient-ng library + \item Asterisk PBX +\end{itemize} + +\begin{verbatim} + +--------------------+ + | Asterisk PBX | + | | + |********************| + | | +---------------+ + | RADIUS client |------->| RADIUS server | + | |<-------| (FreeRADIUS) | + +--------------------+ +---------------+ +\end{verbatim} + + + +\subsection{Steps to follow in order to have RADIUS support} + +\subsubsection{Installation of the Radiusclient library} + + Download the sources from + \url{http://developer.berlios.de/projects/radiusclient-ng/} + + Untar the source tarball: + +\begin{verbatim} + root@localhost:/usr/local/src# tar xvfz radiusclient-ng-0.5.2.tar.gz +\end{verbatim} + + Compile and install the library: + +\begin{verbatim} + root@localhost:/usr/local/src# cd radiusclient-ng-0.5.2 + root@localhost:/usr/local/src/radiusclient-ng-0.5.2# ./configure + root@localhost:/usr/local/src/radiusclient-ng-0.5.2# make + root@localhost:/usr/local/src/radiusclient-ng-0.5.2# make install +\end{verbatim} + +\subsubsection{Configuration of the Radiusclient library} + + By default all the configuration files of the radiusclient library will + be in \path{/usr/local/etc/radiusclient-ng} directory. + + File "radiusclient.conf" + Open the file and find lines containing the following: + + authserver localhost + + This is the hostname or IP address of the RADIUS server used for + authentication. You will have to change this unless the server is + running on the same host as your Asterisk PBX. + + acctserver localhost + + This is the hostname or IP address of the RADIUS server used for + accounting. You will have to change this unless the server is running + on the same host as your Asterisk PBX. + + \textbf{File "servers"} + + RADIUS protocol uses simple access control mechanism based on shared + secrets that allows RADIUS servers to limit access from RADIUS clients. + + A RADIUS server is configured with a secret string and only RADIUS + clients that have the same secret will be accepted. + + You need to configure a shared secret for each server you have + configured in radiusclient.conf file in the previous step. The shared + secrets are stored in \path{/usr/local/etc/radiusclient-ng/servers} file. + + Each line contains hostname of a RADIUS server and shared secret + used in communication with that server. The two values are separated + by white spaces. Configure shared secrets for every RADIUS server you + are going to use. + + \textbf{File "dictionary"} + + Asterisk uses some attributes that are not included in the + dictionary of radiusclient library, therefore it is necessary to add + them. A file called dictionary.digium (kept in the contrib dir) + was created to list all new attributes used by Asterisk. + Add to the end of the main dictionary file + \path{/usr/local/etc/radiusclient-ng/dictionary} the line: + + \$INCLUDE /path/to/dictionary.digium + +\subsubsection{Install FreeRADIUS Server (Version 1.1.1)} + + Download sources tarball from: + + \url{http://freeradius.org/} + + Untar, configure, build, and install the server: + +\begin{verbatim} + root@localhost:/usr/local/src# tar xvfz freeradius-1.1.1.tar.gz + root@localhost:/usr/local/src# cd freeradius-1.1.1 + root@localhost"/usr/local/src/freeradius-1.1.1# ./configure + root@localhost"/usr/local/src/freeradius-1.1.1# make + root@localhost"/usr/local/src/freeradius-1.1.1# make install +\end{verbatim} + + All the configuration files of FreeRADIUS server will be in + /usr/local/etc/raddb directory. + + +\subsubsection{Configuration of the FreeRADIUS Server} + + There are several files that have to be modified to configure the + RADIUS server. These are presented next. + + File "clients.conf" + + File \path{/usr/local/etc/raddb/clients.conf} contains description of + RADIUS clients that are allowed to use the server. For each of the + clients you need to specify its hostname or IP address and also a + shared secret. The shared secret must be the same string you configured + in radiusclient library. + + Example: +\begin{verbatim} + client myhost { + secret = mysecret + shortname = foo + } +\end{verbatim} + + This fragment allows access from RADIUS clients on "myhost" if they use + "mysecret" as the shared secret. + The file already contains an entry for localhost (127.0.0.1), so if you + are running the RADIUS server on the same host as your Asterisk server, + then modify the existing entry instead, replacing the default password. + + File "dictionary" + + Note: as of version 1.1.2, the dictionary.digium file ships with FreeRADIUS. + The following procedure brings the dictionary.digium file to previous versions + of FreeRADIUS. + + File \path{/usr/local/etc/raddb/dictionary} contains the dictionary of + FreeRADIUS server. You have to add the same dictionary file + (dictionary.digium), which you added to the dictionary of radiusclient-ng + library. You can include it into the main file, adding the following line at the + end of file \path{/usr/local/etc/raddb/dictionary}: + + \$INCLUDE /path/to/dictionary.digium + + That will include the same new attribute definitions that are used + in radiusclient-ng library so the client and server will understand each + other. + + +\subsubsection{Asterisk Accounting Configuration} + + Compilation and installation: + + The module will be compiled as long as the radiusclient-ng + library has been detected on your system. + + By default FreeRADIUS server will log all accounting requests into + \path{/usr/local/var/log/radius/radacct} directory in form of plain text files. + The server will create one file for each hostname in the directory. The + following example shows how the log files look like. + + Asterisk now generates Call Detail Records. See \path{/include/asterisk/cdr.h} + for all the fields which are recorded. By default, records in comma + separated values will be created in \path{/var/log/asterisk/cdr-csv}. + + The configuration file for cdr\_radius.so module is \path{/etc/asterisk/cdr.conf} + + This is where you can set CDR related parameters as well as the path to + the radiusclient-ng library configuration file. + + +\section{Logged Values} +\begin{verbatim} + "Asterisk-Acc-Code", The account name of detail records + "Asterisk-Src", + "Asterisk-Dst", + "Asterisk-Dst-Ctx", The destination context + "Asterisk-Clid", + "Asterisk-Chan", The channel + "Asterisk-Dst-Chan", (if applicable) + "Asterisk-Last-App", Last application run on the channel + "Asterisk-Last-Data", Argument to the last channel + "Asterisk-Start-Time", + "Asterisk-Answer-Time", + "Asterisk-End-Time", + "Asterisk-Duration", Duration is the whole length that the entire + call lasted. ie. call rx'd to hangup + "end time" minus "start time" + "Asterisk-Bill-Sec", The duration that a call was up after other + end answered which will be <= to duration + "end time" minus "answer time" + "Asterisk-Disposition", ANSWERED, NO ANSWER, BUSY + "Asterisk-AMA-Flags", DOCUMENTATION, BILL, IGNORE etc, specified on + a per channel basis like accountcode. + "Asterisk-Unique-ID", Unique call identifier + "Asterisk-User-Field" User field set via SetCDRUserField +\end{verbatim} |