Add support for logging CDR recrods to a radius server (issue #6639, phsultan)

 - with contributions from miconda, jcollie, and sb
 - branch maintained by oej
Thanks everyone!


git-svn-id: http://svn.digium.com/svn/asterisk/trunk@29094 f38db490-d61c-443f-a65b-d21fe96a405b

1 files changed, 198 insertions, 0 deletions

diff --git a/doc/radius.txt b/doc/radius.txt
new file mode 100644
index 000000000..71b7530e6
--- /dev/null
+++ b/doc/radius.txt
@@ -0,0 +1,198 @@
+Call Detail Recording to RADIUS Server
+======================================
+
+
+Configuration of Asterisk to send CDRs to (Free)RADIUS servers.
+
+
+A. What is needed :
+	* FreeRADIUS server
+	* Radiusclient-ng library
+	* Asterisk PBX
+
+
+	+--------------------+
+        |    Asterisk PBX    |
+        |                    |
+        |********************|
+	|                    |        +---------------+
+        |    RADIUS client   |------->| RADIUS server |
+	|                    |<-------| (FreeRADIUS)  |
+	+--------------------+        +---------------+
+
+
+
+
+B. Steps to follow in order to have RADIUS support:
+
+ 1.Radiusclient library  
+	1.a Installation
+		
+		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
+
+ 	1.b	Configuration
+	
+		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 necesarry to add 
+		them. A file called dictionary.asterisk was created to list all new 
+		attributes used by Asterisk. Add into file
+		/usr/local/etc/radiusclient-ng/dictionary
+		the line:
+
+			$INCLUDE /path/to/dictionary.asterisk
+
+ 2.FreeRADIUS Server
+ 	2.a Installation
+			
+		Download sources tarball from:
+
+			http://freeradius.org/
+			
+ 		Untar, configure, build, and install the server:
+
+				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
+
+		All the configuration files of FreeRADIUS server will be in 
+		/usr/local/etc/raddb directory. 
+		
+
+ 	2.b Configuration
+			
+		There are several file 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:
+			client myhost {
+			    secret = mysecret
+			    shortname = foo
+			}
+		
+		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"
+			
+		File /usr/local/etc/raddb/dictionary contains the dictionary of 
+		FreeRADIUS server. You have to add the same dictionary file 
+		(dictionary.asterisk), 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. 
+
+
+ 3. 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.
+
+
+ 4. Logged Values
+
+  "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 
+