<!-- Acc Module User's Guide -->

<chapter>

	<title>&adminguide;</title>

	<section id="overview" xreflabel="Overview">
	<title>Overview</title>
	<para>
		The ACC module is used to account transaction information to different
		backends such as syslog, <abbrev>SQL</abbrev>,
		<acronym>AAA</acronym>.
	</para>
	<para>
		To account a transaction and to choose which set of backends to be
		used, the script writer only has to mark the transaction for
		accounting by using the <xref linkend="func_do_accounting"/> script function.
		Note that the function is not actually doing the accounting at that
		very time, it is just setting a marker - the actual accounting
		will be done later when the transaction or dialog will be
		completed.
		</para>
		<para>
		Even so, the module allows the script writer to force accounting on the
		spot in special cases via some other script functions.
	</para>
	<para>
		The accounting module will log by default a fixed set of attributes
		for the transaction - if you customize your accounting by adding more
		information to be logged, please see the next chapter about extra
		accounting - <xref linkend="ACC-extra-id"/>.
	</para>
	<para>
		The fixed minimal accounting information is:
		<itemizedlist>
		<listitem>
			<para>Request Method name</para>
		</listitem>
		<listitem>
			<para>From header TAG parameter</para>
		</listitem>
		<listitem>
			<para>To header TAG parameter</para>
		</listitem>
		<listitem>
			<para>Call-Id</para>
		</listitem>
		<listitem>
			<para>3-digit Status code from final reply</para>
		</listitem>
		<listitem>
			<para>Reason phrase from final reply</para>
		</listitem>
		<listitem>
			<para>Timestamp when transaction was completed</para>
		</listitem>
		</itemizedlist>
		If a value is not present in the request, the empty string is accounted
		instead.
	</para>
	<para>
		Note that:
		<itemizedlist>
		<listitem>
			<para>
			A single INVITE may produce multiple accounting reports -- that's
			most likely due to the SIP forking feature.
			</para>
		</listitem>
		<listitem>
			<para>
			Since version 2.2, all flags used for accounting have been replaced
			with the do_accounting() function. No need to worry anymore whether
			you have set the flags or not, or be confused by various flag names,
			now you only have to call the function and it will do all the work
			for you.
			</para>
		</listitem>
		<listitem>
			<para>
			&osips; now supports session/dialog accounting. It can
			automatically correlate INVITEs with BYEs for generating proper CDRs,
			for example for billing purposes.
			</para>
		</listitem>
		<listitem>
			<para>
			If a UA fails in the middle of a conversation, a proxy will never
			find out about 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>
	</para>
	<para>
		The SQL, Event Interface and AAA backend support are compiled in the
		module.
	</para>
	<para>
	A very comprehensive description of how the accounting module works in
	terms accounting scope, accounting events and accounting backends can
	be found in this online <ulink url="https://www.opensips.org/Documentation/Tutorials-Advanced-Accounting/">Advanced Accounting Tutorial</ulink>.
	</para>
	<section>
		<title>General Example</title>
		<programlisting format="linespecific">
loadmodule "modules/acc/acc.so"

if ($ru=~"sip:+40") /* calls to Romania */ {
    if (!proxy_authorize("sip_domain.net" /* realm */,
    "subscriber" /* table name */))  {
        proxy_challenge("sip_domain.net" /* realm */, "0" /* no qop */ );
        exit;
    }

    if (is_method("INVITE") &amp;&amp; $au!=$fU) {
        xlog("FROM URI != digest username\n");
        sl_send_reply(403,"Forbidden");
    }

    do_accounting("log"); /* set for accounting via syslog */
    t_relay(); /* enter stateful mode now */
};
</programlisting>
	</section>
	</section>

	<section id="ACC-extra-id">
		<title>Extra accounting</title>
		<section id="overview_extra" xreflabel="Overview: Extra IDs">
			<title>Overview</title>
			<para>
			Along the static default information, the ACC module
			allows dynamic selection of extra information to be logged using
			the acc_extra pseudovariable. This allows you to log any
			pseudo-variable (AVPs, parts of the request, parts of the reply, etc).
			</para>
		</section>
		<section>
			<title>Definitions and syntax</title>
			<para>
			Selection of extra information is done via
			<emphasis>extra_field</emphasis> parameter by specifying tags
			and log_names for the additional information. This information is
			defined via acc_extra pseudovariable, referenced with the define
			tag. If the tag is not specified, its value will be considered
			to be the same as the log_value. Accounting backend(log, db, aaa, evi)
			is specified at the beginning of the definition, separated by ':' from
			the rest. The syntax of the parameter is:
			</para>
			<itemizedlist>
				<listitem><para><emphasis>
				backend : tag -> log_name (';'tag -> log_name)*
				</emphasis></para></listitem>
				<listitem><para><emphasis>
				backend : tag (';' tag)*
				</emphasis></para></listitem>
			</itemizedlist>
			<para>
				Extra values are consistent during the whole call. Setting a
			value during a request, will cause it to remain visible during all replies. Also,
			concerning CDR logging, setting a value on the initial INVITE will
			result in having that value throughout the dialog.
			</para>
			<para>
			Via <emphasis>log_name</emphasis> you define how/where the
			<emphasis>data</emphasis> will be logged. Its meaning depends
			of the accounting support which is used:
			<itemizedlist>
				<listitem><para><emphasis>LOG accounting</emphasis> - log_name
				will be just printed along with the data in <emphasis>
				log_name=data</emphasis> format;
				</para></listitem>
				<listitem><para><emphasis>DB accounting</emphasis> - log_name
				will be the name of the DB column where the data will be
				stored.<emphasis>IMPORTANT</emphasis>: add in db
				<emphasis>acc</emphasis> table the columns corresponding to
				each extra data;
				</para></listitem>
				<listitem><para><emphasis>AAA accounting</emphasis> -
				log_name will be the AVP name used for packing the data into
				AAA message. The log_name will be translated to AVP number
				via the dictionary. <emphasis>IMPORTANT</emphasis>: add in
				AAA dictionary the <emphasis>log_name</emphasis> attribute.
				</para></listitem>
				<listitem><para><emphasis>Events accounting</emphasis> -
				log_name will be the name of the parameter in the event raised.
				</para></listitem>
			</itemizedlist>
			</para>
		</section>
		<section>
			<title>How it works</title>
			<para>
				Declaring an extra in the format of
<programlisting>
modparam("acc", "extra_fields", "log: a -> test_a")
</programlisting>
				will enable you to set the value for <emphasis>test_a</emphasis> field
				of the log only by setting <emphasis>$acc_extra(a)</emphasis> variable.
				Otherwise, the field shall be logged with no value(null).
			</para>
		</section>
		<section>
			<title>Radius accounting dependencies</title>
			<para>
				If radius accounting is used, except from a radius client library which is mandatory,
				<emphasis role='bold'>dictionary.rfc2866</emphasis> must be included for the module
				to work properly.</para>
		</section>
	</section>

	<section id="multi-call-legs">
		<title>Multi Call-Legs accounting</title>
		<section id="overview_multi_call_legs" xreflabel="Overview: Multi Call Legs">
			<title>Overview</title>
			<para>
			A SIP call can have multiple legs due forwarding actions. For
			example user A calls user B which forwards the call to user C.
			There is only one SIP call but with 2 legs ( A to B and B to C).
			Accounting the legs of a call is required for proper billing of
			the calls (if C is a PSTN number and the call is billed, user B
			must pay for the call - as last party modifing the call
			destination-, and not A - as initiator of the call. Call
			forwarding on server is only one example which shows the
			necessity of the having an accounting engine with multiple legs
			support.
			</para>
		</section>
		<section>
			<title>Configuration</title>
			<para>
				First how it works: The idea is to have a variable to store
			a set of values for each leg. The meaning of
			the variable content is strictly decided by the script writer - it can
			be the origin and source of the leg, its status or any other
			related information. By default there is defined only one leg. Script
			writer has to decide when is the time to create a new leg, by using
			<emphasis>acc_new_leg()</emphasis> script function. When creating a new
			leg, all the values for that leg will be set to NULL by default.
			</para>
			<para>
			When the accounting information for the call will be written/sent,
			all the call-leg pairs will be added.
			</para>
			<para>
			By default, the multiple call-leg support is disabled - it can be
			enabled just by setting <emphasis>acc_leg</emphasis> variable
			<varname>leg_fields</varname> module parameter. Note that
			the last one only makes sense only for CDRs that are generated
			automatically by &osips;.
			</para>
			</section>
		<section>
			<title>Logged data</title>
			<para>
				For each call, all the values from the <emphasis>acc_leg</emphasis>
				variable will be logged. How the information will be actually
			logged, depends of the data backend:
			</para>
			<itemizedlist>
				<listitem>
				<para><emphasis>syslog</emphasis> -- all leg-sets will be added
				to one record string as acc_leg(leg1)=xxx, acc_leg(leg2)=xxxx ,... sets.
				</para>
				</listitem>
				<listitem>
				<para><emphasis>database</emphasis> -- each pair will be
				separately logged (due DB data structure constraints); several
				records will be written, the difference between them being
				only the fields corresponding to the call-leg info.
				</para>
				<note><para>You will need to add in your DB (all acc related
				tables) the colums for call-leg info (a column for each leg value
				of the set).
				</para></note>
				</listitem>
				<listitem>
				<para><emphasis>AAA</emphasis> -- all sets will be added
				to the same AAA accounting message as AAA AVPs - for each
				call-leg a set of AAA AVPs will be added (corresponding
				to the per-leg set)
				</para>
				<note><para>You will need to add in your dictionary the
				AAA AVPs used in call-leg set definition.
				</para></note>
				</listitem>
				<listitem>
				<para><emphasis>events</emphasis> -- each pair will appear as a
				different parameter-value pair in the event. Similar to the
				database behavior, multiple events will be raised, and the only
				difference between them is the leg information.
				</para>
				</listitem>

			</itemizedlist>
			<para>
				<emphasis>Important!!!</emphasis> In order to use <emphasis>RADIUS</emphasis>,
				one must include the AVPs which are located in
				$(opensips_install_dir)/etc/dictionary.opensips, both in opensips radius config
				script dictionary and radius server dictionary. Most important are the last three
				AVPs (IDs : 227, 228, 229) which you won't find in any SIP dictionary
				(at least at this moment) because they are only used in openSips.
			</para>
		</section>
	</section>

	<section id="ACC-cdr-id">
		<title>CDRs accounting</title>
		<section id="overview_cdr_accounting" xreflabel="Overview: CDR Accounting">
			<title>Overview</title>
			<para>
			ACC module can now also maintain session/dialog accounting. This
			allows you to log useful information like call duration, call
			start time and setup time.
			</para>
		</section>
		<section>
			<title>Configuration</title>
			<para>
			In order to have CDRs accounting, first you need to set the
			<emphasis>cdr</emphasis> flag when calling
			<xref linkend="func_do_accounting"/> script function for the
			initial INVITE of the dialog.
			</para>
		</section>
		<section>
			<title>How it works</title>
			<para>
			This type of accounting is based on the dialog module. When
			an initial INVITE is received, if the <emphasis>cdr</emphasis>
			flag is set, then the dialog creation time is saved. Once the call is
			answered and the ACK is received, other information like extra values
			or leg values are saved. When the corresponding BYE is received,
			the call duration is computed and all information is stored to
			the desired backend.
			</para>
		</section>
	</section>



	<section id="dependencies" xreflabel="Dependencies">
		<title>Dependencies</title>
		<section>
			<title>&osips; Modules</title>
			<para>
			The module depends on the following modules (in the other words
			the listed modules must be loaded before this module):
			<itemizedlist>
				<listitem>
				<para><emphasis>tm</emphasis> -- Transaction Manager</para>
				</listitem>
				<listitem>
				<para><emphasis>a database module</emphasis> -- If SQL
				support is used.</para>
				</listitem>
				<listitem>
				<para><emphasis>rr</emphasis> -- Record Route, if
				<quote>detect_direction</quote> module parameter is enabled.
				</para>
				</listitem>
				<listitem>
				<para><emphasis>an aaa module</emphasis></para>
			</listitem>
				<listitem>
				<para><emphasis>dialog</emphasis> -- Dialog, if
				<quote>cdr</quote> option is used
				</para>
				</listitem>
			</itemizedlist>
			</para>
		</section>
		<section>
			<title>External Libraries or Applications</title>
			<para>
			The following libraries or applications must be installed
			before running &osips; with this module loaded:
			</para>
			<itemizedlist>
				<listitem>
				<para>
				none.
				</para>
				</listitem>
			</itemizedlist>
		</section>
	</section>

	<section id="exported_parameters" xreflabel="Exported Parameters">
	<title>Exported Parameters</title>
	<!-- Generic ACC parameters -->
	<section id="param_early_media" xreflabel="early_media">
		<title><varname>early_media</varname> (integer)</title>
		<para>
		Should be early media (any provisional reply with body) accounted too ?
		</para>
		<para>
		Default value is 0 (no).
		</para>
		<example>
		<title>early_media example</title>
		<programlisting format="linespecific">
modparam("acc", "early_media", 1)
</programlisting>
		</example>
	</section>
	<section id="param_report_cancels" xreflabel="report_cancels">
		<title><varname>report_cancels</varname> (integer)</title>
		<para>
		By default, CANCEL reporting is disabled -- most accounting
		applications wants to see INVITE's cancellation status.
		Turn on if you explicitly want to account CANCEL transactions.
		</para>
		<para>
		Default value is 0 (no).
		</para>
		<example>
		<title>report_cancels example</title>
		<programlisting format="linespecific">
modparam("acc", "report_cancels", 1)
</programlisting>
		</example>
	</section>
	<section id="param_detect_direction" xreflabel="detect_direction">
		<title><varname>detect_direction</varname> (integer)</title>
		<para>
		Controls the direction detection for sequential requests. If
		enabled (non zero value), for sequential requests with upstream
		direction (from callee to caller), the FROM and TO will be swapped
		(the direction will be preserved as in the original request).
		</para>
		<para>
		It affects all values related to TO and FROM headers (body, URI,
		username, domain, TAG).
		</para>
		<para>
		Default value is 0 (disabled).
		</para>
		<example>
		<title>detect_direction example</title>
		<programlisting format="linespecific">
modparam("acc", "detect_direction", 1)
</programlisting>
		</example>
	</section>

	<section id="param_extra_fields" xreflabel="extra_fields">
		<title><varname>extra_fields</varname> (string)</title>
		<para>
		Defines the tag-log_value set to be used in extra fields accounting.
		See <xref linkend="ACC-extra-id"/> for a
		detailed description of the Extra accounting.
		</para>
		<para>
		If empty, extra accounting support will be disabled.
		</para>
		<para>
		Default value is 0 (disabled).
		</para>
		<example>
		<title>Setting <emphasis>extra_fields</emphasis> example:</title>
		<programlisting format="linespecific">
# for syslog-based accounting, use any text you want to be printed
# if setting $acc_extra(a) you will see "My_a_Field=&lt;value&gt; in logs
# if setting $acc_extra(b) you will see "b=&lt;value&gt; in logs
modparam("acc", "extra_fields", "log: a->My_a_Field; b")
# for mysql-based accounting, use the names of the columns
# $acc_extra(a) = &lt;value&gt;  results in setting col_a with &lt;value&gt; in db
modparam("acc", "extra_fields", "db: a->col_a; col_b")
# for AAA-based accounting, use the names of the AAA AVPs
modparam("acc", "extra_fields","aaa:a->AAA_SRC;b->AAA_DST")
# evi definition example
modparam("acc", "extra_fields","a->2345;b->2346")
</programlisting>
		</example>
	</section>

	<section id="param_leg_fields" xreflabel="leg_fields">
		<title><varname>leg_fields</varname> (string)</title>
		<para>
		Defines the tag-log_value set to be used in multi-leg accounting.
		See <xref linkend="multi-call-legs"/> for a
		detailed description of the Multi Call-Legs accounting.
		</para>
		<para>
		If empty, multi-leg accounting support will be disabled.
		</para>
		<para>
		Default value is 0 (disabled).
		</para>
		<example>
		<title>Setting <emphasis>leg_fields</emphasis> example:</title>
		<programlisting format="linespecific">
# for syslog-based accounting, use any text you want to be printed
# if setting $(acc_leg(a)[0]) you will see "My_a_Field=&lt;value&gt; in logs
# if setting $(acc_leg(b)[0]) you will see "b=&lt;value&gt; in logs
modparam("acc", "leg_fields", "log: a->My_a_Field; b")
# for mysql-based accounting, use the names of the columns
# $acc_leg(a) = &lt;value&gt;  results in setting col_a with &lt;value&gt; in db
modparam("acc", "leg_fields", "db: a->col_a; col_b")
# for AAA-based accounting, use the names of the AAA AVPs
modparam("acc", "leg_fields","aaa:a->AAA_LEG_SRC;b->AAA_LEG_DST")
# evi definition example
modparam("acc", "leg_fields","a->2345;b->2346")
</programlisting>
		</example>
	</section>


	<section id="param_log_level" xreflabel="log_level">
		<title><varname>log_level</varname> (integer)</title>
		<para>
		Log level at which accounting messages are issued to syslog.
		</para>
		<para>
		Default value is L_NOTICE.
		</para>
		<example>
		<title>log_level example</title>
		<programlisting format="linespecific">
modparam("acc", "log_level", 2)   # Set log_level to 2
</programlisting>
		</example>
	</section>
		<section id="param_log_facility" xreflabel="log_facility">
		<title><varname>log_facility</varname> (string)</title>
		<para>
		Log facility to which accounting messages are issued to syslog.
		This allows to easily seperate the accounting specific logging
		from the other log messages.
		</para>
		<para>
		Default value is LOG_DAEMON.
		</para>
		<example>
		<title>log_facility example</title>
		<programlisting format="linespecific">
modparam("acc", "log_facility", "LOG_DAEMON")
</programlisting>
		</example>
	</section>

	<!-- AAA specific ACC parameters -->

	<section id="param_aaa_url" xreflabel="aaa_url">
		<title><varname>aaa_url</varname> (string)</title>
		<para>
		This is the url representing the AAA protocol used and the location of the configuration file of this protocol.
		</para>
		<para>
		If the parameter is set to empty string, the AAA accounting support
		will be disabled.
		</para>
		<para>
			Default value is <quote>NULL</quote>.
		</para>
		<example>
		<title>Set <varname>aaa_url</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("acc", "aaa_url", "radius:/etc/radiusclient-ng/radiusclient.conf")
...
</programlisting>
		</example>
	</section>

	<section id="param_service_type" xreflabel="service_type">
		<title><varname>service_type</varname> (integer)</title>
		<para>
		AAA service type used for accounting.
		</para>
		<para>
		Default value is not-set.
		</para>
		<example>
		<title>service_type example</title>
		<programlisting format="linespecific">
# Default value of service type for SIP is 15
modparam("acc", "service_type", 15)
</programlisting>
		</example>
	</section>
	<!-- SQL specific ACC parameters -->
	<section id="param_db_table_acc" xreflabel="db_table_acc">
		<title><varname>db_table_acc</varname> (string)</title>
		<para>
		Table name of accounting successful calls -- database specific.
		</para>
		<para>
		Default value is <quote>acc</quote>
		</para>
		<example>
		<title>db_table_acc example</title>
		<programlisting format="linespecific">
modparam("acc", "db_table_acc", "myacc_table")
</programlisting>
		</example>
	</section>
	<section id="param_db_table_missed_calls" xreflabel="db_table_missed_calls">
		<title><varname>db_table_missed_calls</varname> (string)</title>
		<para>
		Table name for accounting missed calls -- database specific.
		</para>
		<para>
		Default value is <quote>missed_calls</quote>
		</para>
		<example>
		<title>db_table_missed_calls example</title>
		<programlisting format="linespecific">
modparam("acc", "db_table_missed_calls", "myMC_table")
</programlisting>
		</example>
	</section>
	<section id="param_db_url" xreflabel="db_url">
		<title><varname>db_url</varname> (string)</title>
		<para>
		SQL address -- database specific. If is set to NULL or empty string,
		the SQL support is disabled.
		</para>
		<para>
		Default value is <quote>NULL</quote> (SQL disabled).
		</para>
		<example>
		<title>db_url example</title>
		<programlisting format="linespecific">
modparam("acc", "db_url", "mysql://user:password@localhost/opensips")
</programlisting>
		</example>
	</section>
	<section id="param_acc_method_column" xreflabel="acc_method_column">
		<title><varname>acc_method_column</varname> (string)</title>
		<para>
		Column name in accounting table to store the request's method name as
		string.
		</para>
		<para>
		Default value is <quote>method</quote>.
		</para>
		<example>
		<title>acc_method_column example</title>
		<programlisting format="linespecific">
modparam("acc", "acc_method_column", "method")
</programlisting>
		</example>
	</section>
	<section id="param_acc_from_tag_column" xreflabel="acc_from_tag_column">
		<title><varname>acc_from_tag_column</varname> (string)</title>
		<para>
		Column name in accounting table to store the From header TAG parameter.
		</para>
		<para>
		Default value is <quote>from_tag</quote>.
		</para>
		<example>
		<title>acc_from_tag_column example</title>
		<programlisting format="linespecific">
modparam("acc", "acc_from_tag_column", "from_tag")
</programlisting>
		</example>
	</section>
	<section id="param_acc_to_tag_column" xreflabel="acc_to_tag_column">
		<title><varname>acc_to_tag_column</varname> (string)</title>
		<para>
		Column name in accounting table to store the To header TAG parameter.
		</para>
		<para>
		Default value is <quote>to_tag</quote>.
		</para>
		<example>
		<title>acc_to_tag_column example</title>
		<programlisting format="linespecific">
modparam("acc", "acc_to_tag_column", "to_tag")
</programlisting>
		</example>
	</section>
	<section id="param_acc_callid_column" xreflabel="acc_callid_column">
		<title><varname>acc_callid_column</varname> (string)</title>
		<para>
		Column name in accounting table to store the request's Callid value.
		</para>
		<para>
		Default value is <quote>callid</quote>.
		</para>
		<example>
		<title>acc_callid_column example</title>
		<programlisting format="linespecific">
modparam("acc", "acc_callid_column", "callid")
</programlisting>
		</example>
	</section>
	<section id="param_acc_sip_code_column" xreflabel="acc_sip_code_column">
		<title><varname>acc_sip_code_column</varname> (string)</title>
		<para>
		Column name in accounting table to store the final reply's numeric code
		value in string format.
		</para>
		<para>
		Default value is <quote>sip_code</quote>.
		</para>
		<example>
		<title>acc_sip_code_column example</title>
		<programlisting format="linespecific">
modparam("acc", "acc_sip_code_column", "sip_code")
</programlisting>
		</example>
	</section>
	<section id="param_acc_sip_reason_column" xreflabel="acc_sip_reason_column">
		<title><varname>acc_sip_reason_column</varname> (string)</title>
		<para>
		Column name in accounting table to store the final reply's reason
		phrase value.
		</para>
		<para>
		Default value is <quote>sip_reason</quote>.
		</para>
		<example>
		<title>acc_sip_reason_column example</title>
		<programlisting format="linespecific">
modparam("acc", "acc_sip_reason_column", "sip_reason")
</programlisting>
		</example>
	</section>
	<section id="param_acc_time_column" xreflabel="acc_time_column">
		<title><varname>acc_time_column</varname> (string)</title>
		<para>
		Column name in accounting table to store the time stamp of the
		transaction completion in date-time format.
		</para>
		<para>
		Default value is <quote>time</quote>.
		</para>
		<example>
		<title>acc_time_column example</title>
		<programlisting format="linespecific">
modparam("acc", "acc_time_column", "time")
</programlisting>
		</example>
	</section>

	</section>

	<section id="exported_pseudo_variables" xreflabel="Exported Pseudo-Variables">
	<title>Exported Pseudo-Variables</title>
	<section id="pv_acc_extra" xreflabel="$acc_extra">
		<title>$acc_extra(tag_name)</title>
		<para> This variable can addresed with the tag names defined
			using <xref linkend="param_extra_fields"/>. If
			<xref linkend="func_do_accounting"/> isn't called, this
			variable is visible during the whole processing of one message,
			enabling calling <emphasis>acc_XXX_request()</emphasis>.
			If <xref linkend="func_do_accounting"/> is called, the variable
			will be visible from the first call of this function until the
			actual accounting is being made.
		</para>
	</section>

	<section id="pv_acc_leg" xreflabel="$acc_leg">
		<title>$(acc_leg(tag_name)[leg_index])</title>
		<para> This variable can be addressed with the tag names defined
			using <xref linkend="param_leg_fields"/> and  a valid leg index
			(&lt;= <xref linkend="pv_acc_current_leg"/>). This variable cannot
			be used unless <xref linkend="func_do_accounting"/> is used. The
			variable also accepts negative indexes, which start from -1
			(the lastly added leg).
		</para>
		<para>
<programlisting>
# the "caller" value of the current leg
$acc_leg(caller)

# the "caller" value of the lastly added leg
$(acc_leg(caller)[-1]) # equivalent to $acc_leg(caller)
                       # equivalent to $(acc_leg(caller)[$acc_current_leg])

# the "caller" value of the next-to-last leg
$(acc_leg(caller)[-2])

</programlisting>
		</para>
	</section>

	<section id="pv_acc_current_leg" xreflabel="$acc_current_leg">
		<title>$acc_current_leg (read-only)</title>
		<para> Holds the index of the current leg, starting from 0.  Calling
			<xref linkend="func_acc_new_leg"/> will increment this index.
		</para>
	</section>

	</section>

	<section id="exported_functions" xreflabel="exported_functions">
	<title>Exported Functions</title>
	<section id="func_do_accounting" xreflabel="do_accounting()">
		<title>
			<function moreinfo="none">do_accounting(type, [flags], [table])</function>
		</title>
		<para>
			<function moreinfo="none">do_accounting()</function> replaces all the
			*_flag and, *_missed_flag, cdr_flag, failed transaction_flag and the
			db_table_avp modparams. Just call do_accounting(), select where and how you want
			the accounting to take place, and the function will do all the work for you.
		</para>

		<para>
		When called multiple times, the function behaves <emphasis>additively</emphasis>.
		</para>
		<para>
			Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>type (string)</emphasis> - the type of accounting you want to do.
			All types have to be separated by '|'. The following parameters can
			be used: </para>
			<itemizedlist>
				<listitem>
					<para><emphasis>log</emphasis> - syslog accounting;</para>
				</listitem>
				<listitem>
					<para><emphasis>db</emphasis> - database accounting;</para>
				</listitem>
				<listitem>
					<para><emphasis>aaa</emphasis> - aaa specific accounting;</para>
				</listitem>
				<listitem>
					<para><emphasis>evi</emphasis> - Event Interface accounting;</para>
				</listitem>
			</itemizedlist>
		</listitem>
		<listitem>
			<para><emphasis>flags (string, optional)</emphasis> - flags for the accounting type you have
			selected. All the types have to be separated by '|'. The following
			parameters can be used: </para>
			<itemizedlist>
				<listitem>
					<para><emphasis>cdr</emphasis> - enables dialog-level accounting.
						OpenSIPS will internally detect dialog termination (generation/receipt
						of a BYE request), and store the CDR as soon as the BYE request
						is replied to. By enabling the "cdr" flag, the following additional
						fields will be populated: duration, ms_duration, setuptime, created.
						 (requires dialog module support)</para>
				</listitem>
				<listitem>
					<para><emphasis>missed</emphasis> - log missed calls; take care
						that this flag will be deactivated after the first missed call;
						you will have to reactivate it in the
						<emphasis>failure_route</emphasis> if you want to account
						each destination that did not respond to the call;</para>
				</listitem>
				<listitem>
					<para><emphasis>failed</emphasis> -  flag which indicates if the
						transaction should also be accounted in case
						of failure (status>=300);</para>
				</listitem>
			</itemizedlist>
		</listitem>
		<listitem>
			<para><emphasis>table (string, optional)</emphasis> - table where to do the accounting;
			it replaces old table_avp parameter;</para>
		</listitem>
		</itemizedlist>

		<para>
			This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
			BRANCH_ROUTE and LOCAL_ROUTE.
		</para>

		<example>
				<title>do_accounting usage</title>
				<programlisting format="linespecific">
		...
		if (!has_totag()) {
			if (is_method("INVITE")) {
			/* enable cdr and missed calls accounting in the database
			 * and to syslog; db accounting shall be done in "my_acc" table */
				do_accounting("db|log", "cdr|missed", "my_acc");
			}
		}
		...
		if (is_method("BYE")) {
			/* do normal accounting via aaa */
			do_accounting("aaa");
		}
		...
		</programlisting>
		</example>

	</section>

	<section id="func_drop_accounting" xreflabel="drop_accounting()">
		<title>
			<function moreinfo="none">drop_accounting([type], [flags])</function>
		</title>
		<para>
			<function moreinfo="none">drop_accounting()</function> resets flags
			and types of accounting set with do_accounting(). If called with no
			arguments all accounting will be stopped. If called with only one argument
			all accounting for that type will be stopped. If called with two arguments
			normal accounting will still be enabled.</para>

		<para>
		When called multiple times, the function behaves <emphasis>additively</emphasis>.
		</para>
		<para>
		Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>type (string, optional)</emphasis> - the type of accounting you want to stop.
			All the types have to be separated by '|'. The following parameters can
			be used: </para>
			<itemizedlist>
				<listitem>
					<para><emphasis>log</emphasis> - stop syslog accounting;</para>
				</listitem>
				<listitem>
					<para><emphasis>db</emphasis> - stop database accounting;</para>
				</listitem>
				<listitem>
					<para><emphasis>aaa</emphasis> - stop aaa specific accounting;</para>
				</listitem>
				<listitem>
					<para><emphasis>evi</emphasis> - stop Event Interface accounting;</para>
				</listitem>
			</itemizedlist>
		</listitem>
		<listitem>
			<para><emphasis>flags (string, optional)</emphasis> - flags to be reset for the accouting type you have
			selected. All the types have to be separated by '|'. The following
			parameters can be used: </para>
			<itemizedlist>
				<listitem>
					<para><emphasis>cdr</emphasis> - stop CDR accounting;</para>
				</listitem>
				<listitem>
					<para><emphasis>missed</emphasis> - stop logging missed calls;</para>
				</listitem>
				<listitem>
					<para><emphasis>failed</emphasis> -  stop failed transaction accounting;</para>
				</listitem>
			</itemizedlist>
		</listitem>
		</itemizedlist>

		<para>
			This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
			BRANCH_ROUTE and LOCAL_ROUTE.
		</para>

		<example>
				<title>drop_accounting usage</title>
				<programlisting format="linespecific">
		...
		acc_log_request("403 Destination not allowed");
		if (!has_totag()) {
			if (is_method("INVITE")) {
			/* enable cdr and missed calls accounting in the database
			 * and to syslog; db accounting shall be done in "my_acc" table */
				do_accounting("db|log", "cdr|missed", "my_acc");
			}
		}
		...
		/* later in your script */
		if (...) { /* you don't want accounting anymore */
			/* stop all syslog accounting */
			drop_accounting("log");
			/* or stop missed calls and cdr accounting for syslog;
			 * normal accounting will still be enabled */
			drop_accounting("log", "missed|cdr");
			/* or stop all types of accounting  */
			drop_accounting();
		}
		...
		</programlisting>
		</example>

	</section>



	<section id="func_acc_log_request" xreflabel="acc_log_request()">
		<title>
			<function moreinfo="none">acc_log_request(comment)</function>
		</title>
		<para>
		<function moreinfo="none">acc_request</function> reports on a request,
		for example, it can be used to report on missed calls to off-line users
		who are replied 404 - Not Found. To avoid multiple reports on UDP
		request retransmission, you would need to embed the
		action in stateful processing.
		</para>
		<para>
		Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>comment (string)</emphasis> - Comment describing how the
			request completed - this string has to contain a reply code
			followed by a reply reason phrase (ex: "480 Nobody Home"). Variables
			are accepted in this string.</para>
		</listitem>
		</itemizedlist>
		<para>
			This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
			BRANCH_ROUTE and LOCAL_ROUTE.
		</para>
		<example>
		<title>acc_log_request usage</title>
		<programlisting format="linespecific">
...
acc_log_request("403 Destination not allowed");
...
</programlisting>
		</example>
	</section>
	<section id="func_acc_db_request" xreflabel="acc_db_request()">
		<title>
			<function moreinfo="none">acc_db_request(comment, table)</function>
		</title>
		<para>
		Like <function moreinfo="none">acc_log_request</function>,
		<function moreinfo="none">acc_db_request</function> reports on a
		request. The report is sent to database at <quote>db_url</quote>, in
		the table referred to in the second action parameter.
		</para>
		<para>
		Meaning of the parameters is as follows:
		</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>comment (string)</emphasis> - Comment describing how the
			request completed - this string has to contain a reply code
			followed by a reply reason phrase (ex: "480 Nobody Home"). Variables
			are accepted in this string.</para>
		</listitem>
		<listitem>
			<para><emphasis>table (string)</emphasis> - Database table to be used.</para>
		</listitem>
		</itemizedlist>
		<para>
			This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
			BRANCH_ROUTE and LOCAL_ROUTE.
		</para>
		<example>
		<title>acc_db_request usage</title>
		<programlisting format="linespecific">
...
acc_db_request("Some comment", "Some table");
acc_db_request("$T_reply_code $(&lt;reply&gt;rr)", "acc");
...
</programlisting>
		</example>
	</section>
	<section id="func_acc_aaa_request" xreflabel="acc_aaa_request()">
		<title>
			<function moreinfo="none">acc_aaa_request(comment)</function>
		</title>
		<para>
		Like <function moreinfo="none">acc_log_request</function>,
		<function moreinfo="none">acc_aaa_request</function> reports on
		a request. It reports to aaa server as configured in
		<quote>aaa_url</quote>.
		</para>
		<para>
		Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>comment (string)</emphasis> - Comment describing how the
			request completed - this string has to contain a reply code
			followed by a reply reason phrase (ex: "404 Nobody home"). Variables
			are accepted in this string.</para>
		</listitem>
		</itemizedlist>
		<para>
			This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
			BRANCH_ROUTE and LOCAL_ROUTE.
		</para>
		<example>
		<title>acc_aaa_request usage</title>
		<programlisting format="linespecific">
...
acc_aaa_request("403 Destination not allowed");
...
</programlisting>
		</example>
	</section>
	<section id="func_acc_evi_request" xreflabel="acc_evi_request()">
		<title>
			<function moreinfo="none">acc_evi_request(comment)</function>
		</title>
		<para>
		Like <function moreinfo="none">acc_log_request</function>,
		<function moreinfo="none">acc_evi_request</function> reports on a
		request. The report is packed as an event sent through the &osips; Event
		Interface as <emphasis>E_ACC_EVENT</emphasis> if the reply code is a
		positive one (lower than 300), or <emphasis>E_ACC_MISSED_EVENT</emphasis>
		for negative or no codes. More information on this in
		<xref linkend="exported_events"/>.
		</para>
		<para>
		Meaning of the parameters is as follows:
		</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>comment (string)</emphasis> - Comment describing how the
			request completed - this string has to contain a reply code
			followed by a reply reason phrase (ex: "404 Nobody home")</para>
		</listitem>
		</itemizedlist>
		<para>
			This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
			BRANCH_ROUTE and LOCAL_ROUTE.
		</para>
		<example>
		<title>acc_evi_request usage</title>
		<programlisting format="linespecific">
...
acc_evi_request("403 Destination not allowed");
...
</programlisting>
		</example>
	</section>

	<section id="func_acc_new_leg" xreflabel="acc_new_leg()">
		<title>
			<function moreinfo="none">acc_new_leg()</function>
		</title>
		<para>
			Creates a new leg and increments <xref linkend="pv_acc_current_leg"/>
			only if multi-leg accounting is used.  All values of the new leg
			will be initialized to null.
		</para>
		<para>
			This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
			BRANCH_ROUTE and LOCAL_ROUTE.
		</para>
		<example>
		<title>acc_new_leg usage</title>
		<programlisting format="linespecific">
...
	acc_new_leg();
...
</programlisting>
		</example>
	</section>

	<section id="func_acc_load_ctx_from_dlg" xreflabel="acc_load_ctx_from_dlg()">
		<title>
			<function moreinfo="none">acc_load_ctx_from_dlg()</function>
		</title>
		<para>
			The function loads and exposes the accounting context of the
			currently in-use dialog. By dialog context, it means, from script
			level, you will read/write the accounting variables from the
			other dialog. The current accounting context is
			stashed until an unload operation is done.
		</para>
		<para>
			Note that this functions makes sense only when used together with
			the <emphasis>load_dialog_ctx()</emphasis> function from the
			dialog module. After loading the context of another dialog, by
			using the <emphasis>acc_load_ctx_from_dlg()</emphasis> function,
			you can also access the accounting context of the loaded dialog.
		</para>
		<para>
		NOTE: you cannot perform a new load until doing an unload - no nested
		loadings are allowed.
		</para>
		<para>
			This function can be used from any type of route.
		</para>
		<example>
		<title>acc_load_ctx_from_dlg usage</title>
<programlisting format="linespecific">
...
if ( load_dialog_ctx("$var(callid)") ) {
	# we now have the dialog context of the new dialog
	acc_load_ctx_from_dlg();
	# we have now also the accouting context of that dialog
	xlog("The accounting caller of call '$var(callid)' "
		"is '$acc_extra(caller)'\n");
	acc_unload_ctx_from_dlg();
	unload_dialog_ctx();
}

...
</programlisting>
		</example>
	</section>

	<section id="func_acc_unload_ctx_from_dlg" xreflabel="acc_unload_ctx_from_dlg()">
		<title>
		<function moreinfo="none">acc_unload_ctx_from_dlg()</function>
		</title>
		<para>
		The function off-loads a previosuly loaded accounting context, exposing
		whatever accounting context was present before doing the load.
		</para>
		<para>
		NOTE: you MUST perform from script an explicit unload for each load
		you did!
		</para>
		<para>
		This function can be used from any type of route.
		</para>
		<para>
		For usage example, see the <xref linkend="func_acc_load_ctx_from_dlg"/>.
		</para>
	</section>

	</section>


	<section id="exported_events" xreflabel="Exported Events">
	<title>Exported Events</title>
	<section id="event_E_ACC_CDR" xreflabel="E_ACC_CDR">
		<title>
		<function moreinfo="none">E_ACC_CDR</function>
		</title>
		<para>
			The event raised when a CDR is generated. Note that this event will
			only be triggered if the auto CDR accounting is used.
		</para>
		<para>Parameters:</para>
		<itemizedlist>
			<listitem><para>
				<emphasis>method</emphasis> - Request method name
			</para></listitem>
			<listitem><para>
				<emphasis>from_tag</emphasis> - From header tag parameter
			</para></listitem>
			<listitem><para>
				<emphasis>to_tag</emphasis> - To header tag parameter
			</para></listitem>
			<listitem><para>
				<emphasis>callid</emphasis> - Message Call-id
			</para></listitem>
			<listitem><para>
				<emphasis>sip_code</emphasis> - The status code from the final reply
			</para></listitem>
			<listitem><para>
				<emphasis>sip_reason</emphasis> - The status reason from the final reply
			</para></listitem>
			<listitem><para>
				<emphasis>time</emphasis> - The timestamp when the call was established
			</para></listitem>
			<listitem><para>
				<emphasis>evi_extra*</emphasis> - Extra parameters added by
				the <emphasis>evi_extra</emphasis> parameter.
			</para></listitem>
			<listitem><para>
				<emphasis>evi_extra_bye*</emphasis> - Extra parameters added by
				the <emphasis>evi_extra_bye</emphasis> parameter
			</para></listitem>
			<listitem><para>
				<emphasis>multi_leg_info*</emphasis> - Extra parameters added by
				the <emphasis>multi_leg_info</emphasis> parameter
			</para></listitem>
			<listitem><para>
				<emphasis>multi_leg_bye_info*</emphasis> - Extra parameters added by
				the <emphasis>multi_leg_bye_info</emphasis> parameter
			</para></listitem>
			<listitem><para>
				<emphasis>duration</emphasis> - The call duration in seconds
			</para></listitem>
			<listitem><para>
				<emphasis>ms_duration</emphasis> - The call duration in milliseconds
			</para></listitem>
			<listitem><para>
				<emphasis>setuptime</emphasis> - The call setup time in seconds
			</para></listitem>
			<listitem><para>
				<emphasis>created</emphasis> - The timestamp when the call was
				created (the initial Invite was received)
			</para></listitem>

		</itemizedlist>
	</section>
	<section id="event_E_ACC_EVENT" xreflabel="E_ACC_EVENT">
		<title>
		<function moreinfo="none">E_ACC_EVENT</function>
		</title>
		<para>
			This event is triggered when old-style accounting is used. It is
			generated when the requests (INVITE and BYE) transaction have
			positive final replies, or by the <function>acc_evi_request()</function>
			function that has a positive reply code in comment.
		</para>
		<para>Parameters:</para>
		<itemizedlist>
			<listitem><para>
				<emphasis>method</emphasis> - Request method name
			</para></listitem>
			<listitem><para>
				<emphasis>from_tag</emphasis> - From header tag parameter
			</para></listitem>
			<listitem><para>
				<emphasis>to_tag</emphasis> - To header tag parameter
			</para></listitem>
			<listitem><para>
				<emphasis>callid</emphasis> - Message Call-id
			</para></listitem>
			<listitem><para>
				<emphasis>sip_code</emphasis> - The status code from the final reply
			</para></listitem>
			<listitem><para>
				<emphasis>sip_reason</emphasis> - The status reason from the final reply
			</para></listitem>
			<listitem><para>
				<emphasis>time</emphasis> - The timestamp when the transaction was created
			</para></listitem>
			<listitem><para>
				<emphasis>evi_extra*</emphasis> - Extra parameters added by
				the <emphasis>evi_extra</emphasis> parameter
			</para></listitem>
			<listitem><para>
				<emphasis>multi_leg_info*</emphasis> - Extra parameters added by
				the <emphasis>multi_leg_info</emphasis> parameter
			</para></listitem>
		</itemizedlist>
	</section>
	<section id="event_E_ACC_MISSED_EVENT" xreflabel="E_ACC_MISSED_EVENT">
		<title>
		<function moreinfo="none">E_ACC_MISSED_EVENT</function>
		</title>
		<para>
			This event is triggered when old-style accounting is used. It is
			generated when the requests (INVITE and BYE) transaction have
			negative final replies, or by the <function>acc_evi_request()</function>
			function that has a negative reply code in comment.
		</para>
		<para>Parameters:</para>
		<itemizedlist>
			<listitem><para>
				<emphasis>method</emphasis> - Request method name
			</para></listitem>
			<listitem><para>
				<emphasis>from_tag</emphasis> - From header tag parameter
			</para></listitem>
			<listitem><para>
				<emphasis>to_tag</emphasis> - To header tag parameter
			</para></listitem>
			<listitem><para>
				<emphasis>callid</emphasis> - Message Call-id
			</para></listitem>
			<listitem><para>
				<emphasis>sip_code</emphasis> - The status code from the final reply
			</para></listitem>
			<listitem><para>
				<emphasis>sip_reason</emphasis> - The status reason from the final reply
			</para></listitem>
			<listitem><para>
				<emphasis>time</emphasis> - The timestamp when the transaction was created
			</para></listitem>
			<listitem><para>
				<emphasis>evi_extra*</emphasis> - Extra parameters added by
				the <emphasis>evi_extra</emphasis> parameter
			</para></listitem>
			<listitem><para>
				<emphasis>multi_leg_info*</emphasis> - Extra parameters added by
				the <emphasis>multi_leg_info</emphasis> parameter
			</para></listitem>
			<listitem><para>
				<emphasis>created</emphasis> - Timestamp when the call was created
			</para></listitem>
			<listitem><para>
				<emphasis>setuptime</emphasis> - The call setup time in seconds
			</para></listitem>


		</itemizedlist>
	</section>

	</section>

</chapter>
