<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<section id="acc" xmlns:xi="http://www.w3.org/2001/XInclude">
    <sectioninfo>
	<authorgroup>
	    <author>
		<firstname>Jiri</firstname>
		<surname>Kuthan</surname>
		<affiliation><orgname>iptel.org</orgname></affiliation>
		<email>jiri@iptel.org</email>
	    </author>
	</authorgroup>

	<copyright>
	    <year>2002</year>
	    <year>2003</year>
	    <holder>FhG FOKUS</holder>
	</copyright>

    </sectioninfo>

    <title>Acc Module</title>
    
    <section id="overview">
	<title>Overview</title>
	<para>
	    acc module is used to report on transactions to syslog,
	    <abbrev>SQL</abbrev> and <acronym>RADIUS</acronym>.
	</para>
	<para>
	    To report on a transaction using syslog, use "setflag" to mark a
	    transaction you are interested in with a flag, load accounting
	    module and set its "log_flag" to the same flag number. The acc
	    module will then report on completed transaction to syslog. A
	    typical usage of the module takes no acc-specific script command --
	    the functionality binds invisibly through transaction processing.
	    Script writers just need to mark the transaction for accounting
	    with proper setflag.
	</para>
	<para>
	    What is printed depends on module's "log_fmt" parameter. It's a
	    string with characters specifying which parts of request should be
	    printed:
	    <itemizedlist>
		<listitem>
		    <para>c = Call-Id</para>
		</listitem>
		<listitem>
		    <para>d = To tag (Dst)</para>
		</listitem>
		<listitem>
		    <para>f = From</para>
		</listitem>
		<listitem>
		    <para>i = Inbound Request-URI</para>
		</listitem>
		<listitem>
		    <para>m = Method</para>
		</listitem>
		<listitem>
		    <para>o = Outbound Request-URI</para>
		</listitem>
		<listitem>
		    <para>r = fRom</para>
		</listitem>
		<listitem>
		    <para>s = Status</para>
		</listitem>
		<listitem>
		    <para>t = To</para>
		</listitem>
		<listitem>
		    <para>u = digest Username</para>
		</listitem>
		<listitem>
		    <para>p = username Part of inbound Request-URI</para>
		</listitem>
	    </itemizedlist>
	    If a value is not present in request, "n/a" is accounted instead.
	</para>
	<note>
	    <itemizedlist>
		<listitem>
		    <para>
			A single INVITE may produce multiple accounting reports
			-- that's due to SIP forking feature
		    </para>
		</listitem>
		<listitem>
		    <para>
			Subsequent ACKs and other requests do not hit the
			server and can't be accounted unless record-routing is
			enforced. The ACKs assert very little useful
			information anyway and reporting on INVITE's 200 makes
			most accounting scenarios happy.
		    </para>
		</listitem>
		<listitem>
		    <para>
			There is no session accounting -- ser maintains no
			sessions. If one needs to correlate INVITEs with BYEs
			for example for purpose of billing, then it is better
			done in the entity which collects accounting
			information. Otherwise, SIP server would have to become
			sessions-stateful, which would very badly impact its
			scalability.
		    </para>
		</listitem>
		<listitem>
		    <para>
			If a UA fails in middle of conversation, a proxy will
			never learn it.  In general, a better practice is to
			account from an end-device (such as PSTN gateway),
			which best knows about call status (including media
			status and PSTN status in case of the gateway).
		    </para>
		</listitem>
	    </itemizedlist>
	</note>
	<para>
	    Support for SQL and RADIUS works analogously. You need to enable it
	    by recompiling the module with properly set defines. Uncomment the
	    SQL_ACC and RAD_ACC lines in
	    <filename>modules/acc/Makefile</filename>. To compile SQL support,
	    you need to have mysqlclient package on your system. To compile
	    RADIUS support, you need to have radiusclient installed on your
	    system (version 0.5.0 or higher is required) which is available
	    from
	    <ulink url='http://developer.berlios.de/projects/radiusclient-ng/'>
	    http://developer.berlios.de/projects/radiusclient-ng/</ulink>. The
	    radius client needs to be configured properly. To do so, use the
	    template in <filename>sip_router/etc/radiusclient.conf</filename>
	    and make sure that module's <varname>radius_config</varname>
	    parameter points to its location.
	    <!-- FIXME In particular, accounting secret
	    must match that one configured in server and proper dictionary is
	    used (one is available in ). -->
	    Uses along with <ulink
	    url="http://www.freeradius.org">FreeRADIUS</ulink> and <ulink
	    url="http://www.open.com.au/radiator">Radiator</ulink> servers have
	    been reported to us.
	</para>
	<para>
	    Both mysql and radius libraries must be dynamically linkable. You
	    need to configure your OS so that SER, when started, will find
	    them. Typically, you do so by manipulating LD_LIBRARY_PATH
	    environment variable or configuring ld.so.
	</para>
	<example>
	    <title>General Example</title>
	    <programlisting>
<![CDATA[
loadmodule "modules/acc/acc.so"
modparam("acc", "log_level", 1)
modparam("acc", "log_flag", 1)

if (uri=~"sip:+49") /* calls to Germany */ {
    if (!proxy_authorize("iptel.org" /* realm */,
                         "subscriber" /* table name */))  {
        proxy_challenge("iptel.org" /* realm */, "0" /* no qop */ );
        break;
    }

    if (method=="INVITE" & !check_from()) {
        log("from!=digest\n");
        sl_send_reply("403","Forbidden");
        break;
    }

    setflag(1); /* set for accounting (the same value as in log_flag!)
    t_relay(); 	/* enter stateful mode now */
};
]]>
	    </programlisting>
	</example>
    </section>

    <section id="dependencies">
	<title>Dependencies</title>
	<para>
	    The module depends on the following modules (in the other words the listed modules
	    must be loaded before this module):
	    <itemizedlist>
		<listitem>
		    <formalpara>
			<title>tm</title>
			<para>Transaction Manager</para>
		    </formalpara>
		</listitem>
		<listitem>
		    <formalpara>
			<title>A database module (mysql,postgres,dbtext)</title>
			<para>If compiled with database support.</para>
		    </formalpara>
		</listitem>
	    </itemizedlist>
	</para>
    </section>
    
    <xi:include href="params.xml"/>
    <xi:include href="functions.xml"/>
    
</section>
    
