Merged revisions 58931 via svnmerge from

https://origsvn.digium.com/svn/asterisk/branches/1.4

........
r58931 | russell | 2007-03-15 17:25:12 -0500 (Thu, 15 Mar 2007) | 13 lines

Merge changes from svn/asterisk/team/russell/LaTeX_docs.

* Convert most of the doc directory into a single LaTeX formatted document
  so that we can generate a PDF, HTML, or other formats from this
  information.
* Add a CLI command to dump the application documentation into LaTeX format
  which will only be include if the configure script is run with 
  --enable-dev-mode.
* The PDF turned out to be close to 1 MB, so it is not included.  However, you
  can simply run "make asterisk.pdf" to generate it yourself.  We may include
  it in release tarballs or have automatically generated ones on the web site,
  but that has yet to be decided.

........


git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@58932 65c4cc65-6c06-0410-ace0-fbb531ad65f3

1 files changed, 431 insertions, 0 deletions

diff --git a/doc/cdrdriver.tex b/doc/cdrdriver.tex
new file mode 100644
index 000000000..00c99daea
--- /dev/null
+++ b/doc/cdrdriver.tex
@@ -0,0 +1,431 @@
+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{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}
+
+	Compile, configure, and install the latest FreeTDS package:
+\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}
+
+	Compile, or recompile, asterisk so that it will now add support
+	for cdr\_odbc.
+\begin{verbatim}
+	make clean && ./configure --with-odbc &&
+	make update &&
+	make &&
+	make install
+\end{verbatim}
+
+	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{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}
+
+		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{verbatim}
+		[ -f /etc/asterisk/cdr_tds.conf ] > /etc/asterisk/cdr_tds.conf
+\end{verbatim}
+		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{verbatim}
+		/etc/asterisk/cdr_odbc.conf
+		   [global]
+		   dsn=MSSQL-asterisk
+		   username=voipdbuser
+		   password=voipdbpass
+		   loguniqueid=yes
+\end{verbatim}
+		And finally, create the 'cdr' table in your mssql database.
+\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}
+		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{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}
+                Compile, or recompile, asterisk so that it will now add support
+                for cdr\_tds.
+\begin{verbatim}
+                   make clean && ./configure --with-tds &&
+                   make update &&
+                   make &&
+                   make install
+\end{verbatim}
+                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{verbatim}
+		[ -f /etc/asterisk/cdr_odbc.conf ] > /etc/asterisk/cdr_odbc.conf
+\end{verbatim}
+                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{verbatim}
+                /etc/asterisk/cdr_tds.conf
+		   [global]
+		   hostname=192.168.1.25
+		   port=1433
+		   dbname=voipdb
+		   user=voipdbuser
+		   password=voipdpass
+		   charset=BIG5
+\end{verbatim}
+                And finally, create the 'cdr' table in your mssql database.
+\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}
+                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{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}
+        Now create a table in postgresql for your cdrs
+
+\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}
+
+\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}
+   Installation:
+\begin{verbatim}	
+	Download the sources from:
+		
+	http://developer.berlios.de/projects/radiusclient-ng/
+		
+	Untar the source tarball.
+		root@localhost:/usr/local/src# tar xvfz radiusclient-ng-0.5.2.tar.gz
+
+	Compile and install the library.
+		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 /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.
+
+	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 /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.
+
+	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
+	/usr/local/etc/radiusclient-ng/dictionary
+	the line:
+\begin{verbatim}
+		\$INCLUDE /path/to/dictionary.digium
+\end{verbatim}
+
+\subsubsection{Install FreeRADIUS Server (Version 1.1.1)}
+ 
+	Download sources tarball from:
+
+		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 /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 /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 '/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 
+	/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 /include/asterisk/cdr.h
+	for all the fields which are recorded. By default, records in comma 
+	separated values will be created in /var/log/asterisk/cdr-csv. 
+
+	The configuration file for cdr\_radius.so module is :
+
+        /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}