acc: extend description in docs for log_missed_calls flag
[sip-router] / src / modules / acc / doc / acc_admin.xml
1 <?xml version="1.0" encoding='ISO-8859-1'?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
4
5 <!-- Include general documentation entities -->
6 <!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
7 %docentities;
8
9 ]>
10
11 <!-- Acc Module User's Guide -->
12
13 <chapter>
14
15         <title>&adminguide;</title>
16
17         <section>
18         <title>Overview</title>
19         <para>
20                 ACC module is used to account transactions information to different
21                 backends like syslog and <abbrev>SQL</abbrev>. With the separate module,
22                 <acronym>radius</acronym> support is enabled.
23         </para>
24         <para>
25                 There is some very early support of
26                 the <acronym>Diameter</acronym> protocol in the code which is no longer included
27                 by default and will be deleted in coming releases.
28                 This support is not up to date with the current Diameter protocols and
29                 is disabled. If you need Diameter support, please use the <acronym>ims_charging</acronym> module.
30         </para>
31         <para>
32                 To account a transaction and to choose which set of backends to be
33                 used, the script writer just has to set some flags (see the module
34                 parameters section for flag definitions <xref linkend="acc.i.params"/>).
35                 If the accounting flag for a specific backend is set, the acc module
36                 will then report on completed transaction. A typical usage of the
37                 module takes no acc-specific script command -- the functionality
38                 binds invisibly through transaction processing. Script writers just
39                 need to mark the transaction for accounting with proper setflag.
40                 Even so, the module allows the script writter to force accounting in
41                 special cases via some script functions.
42         </para>
43         <para>
44                 The accounting module will log by default a fixed set of attributes
45                 for the transaction - if you customize your accounting by adding more
46                 information to be logged, please see the next chapter about extra
47                 accounting - <xref linkend="acc.i.extra-accounting"/>.
48         </para>
49         <para>
50                 The fixed minimal accounting information is:
51                 <itemizedlist>
52                 <listitem>
53                         <para>Request Method name</para>
54                 </listitem>
55                 <listitem>
56                         <para>From header TAG parameter</para>
57                 </listitem>
58                 <listitem>
59                         <para>To header TAG parameter</para>
60                 </listitem>
61                 <listitem>
62                         <para>Call-Id</para>
63                 </listitem>
64                 <listitem>
65                         <para>3-digit Status code from final reply</para>
66                 </listitem>
67                 <listitem>
68                         <para>Reason phrase from final reply</para>
69                 </listitem>
70                 <listitem>
71                         <para>Time stamp when transaction was completed</para>
72                 </listitem>
73                 </itemizedlist>
74                 If a value is not present in request, the empty string is accounted
75                 instead.
76         </para>
77         <para>
78                 Note that:
79                 <itemizedlist>
80                 <listitem>
81                         <para>
82                         A single INVITE may produce multiple accounting reports -- that's
83                         due to SIP forking feature.
84                         </para>
85                 </listitem>
86                 <listitem>
87                         <para>
88                         All flags related to accounting need to be set in request processing
89                         route - only the "missed-call" flag may be toggled from other
90                         types of routes.
91                         </para>
92                 </listitem>
93                 <listitem>
94                         <para>
95                         If a UA fails in middle of conversation, a proxy will never
96                         find out about it. In general, a better practice is to account from an
97                         end-device (such as PSTN gateway), which best knows about call
98                         status (including media status and PSTN status in case of the
99                         gateway). However, CDR-base logging has the option to log existing
100                         information from expired dialogs (the dlg_vars in cdr_extra)
101                         Please see cdr_expired_dlg_enable parameter - <xref linkend="acc.p.cdr_expired_dlg_enable"/>.
102                         </para>
103                 </listitem>
104                 </itemizedlist>
105         </para>
106         <para>
107                 The SQL backend support is compiled in the module. For
108                 DIAMETER you need to enable it by recompiling the module with properly
109                 set defines: uncomment the DDIAM_ACC lines in
110                 modules/acc/Makefile.
111         </para>
112         <para>
113                 NOTE: diameter support was developed for DISC (DIameter Server Client
114                 project at http://developer.berlios.de/projects/disc/). This project
115                 seems to be no longer maintained and DIAMETER specifications were updated
116                 in the meantime. Thus, the DIAMETER part in the module is obsolete and
117                 needs rework to be usable with opendiameter or other DIAMETER servers.
118         </para>
119         <section>
120                 <title>General Example</title>
121                 <programlisting format="linespecific">
122 loadmodule "modules/acc/acc.so"
123 modparam("acc", "log_level", 1)
124 modparam("acc", "log_flag", 1)
125
126 if (uri=~"sip:+40") /* calls to Romania */ {
127     if (!proxy_authorize("sip_domain.net" /* realm */,
128     "subscriber" /* table name */))  {
129         proxy_challenge("sip_domain.net" /* realm */, "0" /* no qop */ );
130         exit;
131     }
132
133     if (method=="INVITE" &amp;&amp; !check_from()) {
134         log("from!=digest\n");
135         sl_send_reply("403","Forbidden");
136     }
137
138     setflag(1); /* set for accounting (the same value as in log_flag!)
139     t_relay();  /* enter stateful mode now */
140 };
141 </programlisting>
142         </section>
143         </section>
144
145         <section id="acc.i.extra-accounting">
146                 <title>Extra accounting</title>
147                 <section>
148                         <title>Overview</title>
149                         <para>
150                         Along the static default information, ACC modules
151                         allows dynamical selection of extra information to be logged.
152                         This allows you to log any pseudo-variable (AVPs, parts of
153                         the request, etc).
154                         </para>
155                 </section>
156                 <section id="acc-def-syn">
157                         <title>Definitions and syntax</title>
158                         <para>
159                         Selection of extra information is done via
160                         <emphasis>xxx_extra</emphasis> parameters by specifying the names
161                         of additional information you want to log. This information is
162                         defined via pseudo-variables and may include headers, AVPs values
163                         or other message or system values. The syntax of the parameter is:
164                         </para>
165                         <itemizedlist>
166                                 <listitem><para><emphasis>
167                                 xxx_extra = extra_definition (';'extra_definition)*
168                                 </emphasis></para></listitem>
169                                 <listitem><para><emphasis>
170                                 extra_definition = log_name '=' pseudo_variable
171                                 </emphasis></para></listitem>
172                         </itemizedlist>
173                         <para>
174                         The full list of supported pseudo-variables in &kamailio; is
175                         available at:
176                         <ulink url="http://www.kamailio.org/wiki/cookbooks/devel/pseudovariables">
177                         http://www.kamailio.org/wiki/cookbooks/devel/pseudovariables</ulink>
178                         </para>
179                         <para>
180                         Note: For all the ACK processed by tm, the registered callbacks
181                         (like acc module) will be called with the corresponding INVITE
182                         transaction contexts as long as this is still available. This means
183                         that the ACK callbacks will see the AVPs setup for the INVITE
184                         transaction and not the AVPs setup before t_relay().
185                         </para>
186                         <para>
187                         Via <emphasis>log_name</emphasis> you define how/where the
188                         <emphasis>data</emphasis> will be logged. Its meaning depends
189                         of the accounting support which is used:
190                         <itemizedlist>
191                                 <listitem><para><emphasis>LOG accounting</emphasis> - log_name
192                                 will be just printed along with the data in <emphasis>
193                                 log_name=data</emphasis> format;
194                                 </para></listitem>
195                                 <listitem><para><emphasis>DB accounting</emphasis> - log_name
196                                 will be the name of the DB column where the data will be
197                                 stored.<emphasis>IMPORTANT</emphasis>: add in db
198                                 <emphasis>acc</emphasis> table the columns corresponding to
199                                 each extra data;
200                                 </para></listitem>
201                                 <listitem><para><emphasis>RADIUS accounting</emphasis> -
202                                 log_name will be the AVP name used for packing the data into
203                                 RADIUS message. The log_name will be translated to AVP number
204                                 via the dictionary. <emphasis>IMPORTANT</emphasis>: add in
205                                 RADIUS dictionary the <emphasis>log_name</emphasis> attribute.
206                                 </para></listitem>
207                                 <listitem><para><emphasis>DIAMETER accounting</emphasis> -
208                                 log_name will be the AVP code used for packing the data
209                                 into DIAMETER message. The AVP code is given directly as
210                                 integer, since DIAMETER has no dictionary support yet.
211                                 <emphasis>IMPORTANT</emphasis>: <emphasis>log_name</emphasis>
212                                 must be a number.
213                                 </para></listitem>
214                         </itemizedlist>
215                         </para>
216                 </section>
217                 <section>
218                         <title>How it works</title>
219                         <para>
220                         Some pseudo variables may return more than one value (like
221                         headers or AVPs). In this case, the returned values are
222                         embedded in a single string in a comma-separated format.
223                         </para>
224                 </section>
225         </section>
226
227         <section id="acc.i.multi-call-legs">
228                 <title>Multi Call-Legs accounting</title>
229                 <section>
230                         <title>Overview</title>
231                         <para>
232                         A SIP call can have multiple legs due forwarding actions. For
233                         example user A calls user B which forwards the call to user C.
234                         There is only one SIP call but with 2 legs ( A to B and B to C).
235                         Accounting the legs of a call is required for proper billing of
236                         the calls (if C is a PSTN number and the call is billed, user B
237                         must pay for the call - as last party modifying the call
238                         destination-, and not A - as initiator of the call. Call
239                         forwarding on server is only one example which shows the
240                         necessity of the having an accounting engine with multiple legs
241                         support.
242                         </para>
243                 </section>
244                 <section>
245                         <title>Configuration</title>
246                         <para>
247                         First how it works: The idea is to have a set of AVPs and for each
248                         call leg to store a set of values in the AVPs. The meaning of
249                         the AVP content is strictly decided by the script writer - it can
250                         be the origin and source of the leg, its status or any other
251                         related information. If you have a set of 4 AVPS (AVP1, AVP2, AVP3,
252                         AVP4), then for the "A call B and B forwards to C" example,
253                         you need to set a different set of values for the AVPs
254                         for each leg ([A,B] and [B,C]) .
255                         The script writer must take care and properly insert all
256                         these AVP from the script (in proper order and with the correct type).
257                         </para>
258                         <para>
259                         When the accounting information for the call will be written/sent,
260                         all the call-leg pairs will be added (based on the found AVP sets).
261                         </para>
262                         <para>
263                         By default, the multiple call-leg support is disabled - it can be
264                         enabled just be setting the per-leg set of AVPs via the
265                         <varname>multi_leg_info</varname> module parameter.
266                         </para>
267                 </section>
268                 <section>
269                         <title>Logged data</title>
270                         <para>
271                         For each call, all the values of the AVP set (which defines a
272                         call-leg) will be logged. How the information will be actually
273                         logged, depends of the data backend:
274                         </para>
275                         <itemizedlist>
276                                 <listitem>
277                                 <para><emphasis>syslog</emphasis> -- all leg-sets will be added
278                                 to one record string as AVP1=xxx, AVP2=xxxx ,... sets.
279                                 </para>
280                                 </listitem>
281                                 <listitem>
282                                 <para><emphasis>database</emphasis> -- each pair will be
283                                 separately logged (due DB data structure constraints); several
284                                 records will be written, the difference between them being
285                                 only the fields corresponding to the call-leg info.
286                                 </para>
287                                 <note><para>You will need to add in your DB (all acc related
288                                 tables) the columns for call-leg info (a column for each AVP
289                                 of the set).
290                                 </para></note>
291                                 </listitem>
292                                 <listitem>
293                                 <para><emphasis>Radius</emphasis> -- all sets will be added
294                                 to the same Radius accounting message as RADIUS AVPs - for each
295                                 call-leg a set of RADIUS AVPs will be added (corresponding
296                                 to the per-leg AVP set). Note that Radius support is in a
297                                 separate module - acc_radius.
298                                 </para>
299                                 <note><para>You will need to add in your dictionary the
300                                 RADIUS AVPs used in call-leg AVP set definition.
301                                 </para></note>
302                                 </listitem>
303                         </itemizedlist>
304                 </section>
305         </section>
306         <section>
307                 <title>Call Data Record generation</title>
308         <section>
309             <title>Overview</title>
310                 <para>
311                 In addition to transaction-based logging, it is possible to generate and log Call Data
312                 Records (CDRs) directly from &kamailio;. Apart from a basic set of CDR fields which
313                 are always included (covering start time, end time, and duration), the approach allows
314                 flexible specification of additional fields that should be taken into account using
315                 the configuration script. This is very similar to how transaction-based logging may
316                 be customized with the exception that CDRs rely on dialogs instead of transactions
317                 to store relevant information during a call.
318                 </para>
319
320                 <para>
321                 In order to set up CDR generation, you must enable the CDR switch and load the dialog
322                 module. You probably also want to specify a set of pseudo-variables that define more
323                 relevant CDR fields. Pseudo-variables may be assigned arbitrarily during script
324                 execution, and the module will make sure that the variable content will be transformed
325                 into a CDR by the end of the dialog.
326                 </para>
327
328                 <para>
329                 To use CDR logging in a correct manner, you should only use the dialog-based
330                 pseudo-variables (dlg_var) from the dialog module. This allows you to save values
331                 right from the beginning through all requests and replies until termination of the
332                 call. While not recommended, it is still possible to use other pseudo-variables as
333                 well. Except for pseudo-variables valid in the call-final transaction, however,
334                 information given will not be stored in the CDR as they cannot be accessed by the
335                 end of the call when the CDR is logged.
336                 </para>
337
338                 <para>
339                                 Sometimes, dialogs expire because the UA has a problem and a final message is never
340                                 transmitted. You can toggle on/off the generation of CDR-based logging in such cases
341                                 with only the dlg_vars showing by using the cdr_expired_dlg_enable parameter
342                                 - <xref linkend="acc.p.cdr_expired_dlg_enable"/>. Default behavior is not logging.
343                 </para>
344         </section>
345                 <section id="acc.i.cdr-extra">
346                         <title>CDR Extra</title>
347                                         This section is similar to the <quote>LOG accounting</quote> part of
348                                         <xref linkend="acc.i.extra-accounting"/>.
349                         <section>
350                                 <title>Definitions and syntax</title>
351                                         <para>
352                                         Selection of extra information is done similar to the transaction extra
353                                         <xref linkend="acc-def-syn"/>.
354                                         </para>
355                                         <itemizedlist>
356                                                 <listitem><para><emphasis>
357                                                 cdr_extra = cdr_extra_definition (';'cdr_extra_definition)*
358                                                 </emphasis></para></listitem>
359                                                 <listitem><para><emphasis>
360                                                 cdr_extra_definition = cdr_log_name '=' pseudo_variable
361                                                 </emphasis></para></listitem>
362                                         </itemizedlist>
363                                         See also <xref linkend="acc.p.cdr_extra"/>.
364                                         <para>
365                                         The full list of supported pseudo-variables in Sip-Router is
366                                         available at:
367                                         <ulink url="http://sip-router.org/wiki/cookbooks/pseudo-variables/devel">
368                                         http://sip-router.org/wiki/cookbooks/pseudo-variables/devel</ulink>
369                                         </para>
370                         </section>
371                 </section>
372                 <section id="multi-cdr-call-legs">
373                         <title>CDR with Multi Call-Legs</title>
374                         <section>
375                                 <title>Overview</title>
376                                 <para>
377                                 As mentioned in <xref linkend="acc.i.multi-call-legs"/>, a leg represents a parallel
378                                 or forwarded call. In contrast to the normal accounting the cdr logging uses dialogs
379                                 instead of transaction to log data. This may reduce the amount of information
380                                 but it also make it possible to combine all important data in one cdr at
381                                 once. A second mechanism to process multiple data-sets into one cdr is not further
382                                 necessary.
383                                 </para>
384                         </section>
385                         <section>
386                                 <title>Configuration</title>
387                                 <para>
388                                 When you route messages multiple times through your proxy (e.g. to
389                                 handle <quote>call-forwardings</quote>) you have to use detect_spirals
390                                 from the dialog modules. Otherwise the proxy can't identify and reuse existing
391                                 dialogs.
392                                 </para>
393                                 <para>
394                                 To get the correct call-forwarding-chain you have to store each cf* with the
395                                 corresponding caller and callee in a dialog based pseudo-variable (dlg_var)
396                                 (e.g. chain=B;cfa;C|C;cfnr;D). Additionally it is necessary to store the
397                                 caller and callee for each leg. All this helps to identify the involved
398                                 phone partners and forwarding chain. When you route such calls multiple times
399                                 to the same Proxy, you could store the caller and callee within an transaction
400                                 based avp and write it into the dialog based dlg_var pv during a 200 INVITE.
401                                 </para>
402                                 <section>
403                                         <title>Example for a spiraled Proxy</title>
404                                         <programlisting format="linespecific">
405 ...
406 # A calls B (transaction 1)
407 $avp(caller)='A'
408 $avp(callee)='B';
409 $dlg_var(chain)='';
410
411 # B cfa C (transaction 2)
412 $avp(caller)='B'
413 $avp(callee)='C';
414 $dlg_var(chain)='B;cfu;C';
415
416 # C cfnr D (transaction 3)
417 $avp(caller)='C'
418 $avp(callee)='D';
419 $dlg_var(chain)=$dlg_var(chain) + "|" + "C;cfnr;D";
420
421 # C confirms call (200 reply of transaction 2)
422 $dlg_var(caller) = $avp(caller); #caller='B'
423 $dlg_var(callee) = $avp(callee); #callee='C'
424 ...
425                                         </programlisting>
426                                 </section>
427                         </section>
428                         <section>
429                                 <title>Logged data</title>
430                                 For each call, all dialog corresponding variables will be logged. After a call
431                                 is finished, the generated call data record information will be logged as string
432                                 (VAR1=xxx,VAR2=xxxx,...) to the syslog.
433                         </section>
434                 </section>
435         </section>
436         <section>
437                 <title>Dependencies</title>
438                 <section>
439                         <title>&kamailio; Modules</title>
440                         <para>
441                         The module depends on the following modules (in the other words
442                         the listed modules must be loaded before this module):
443                         <itemizedlist>
444                                 <listitem>
445                                 <para><emphasis>tm</emphasis> -- Transaction Manager</para>
446                                 </listitem>
447                                 <listitem>
448                                 <para><emphasis>a database module</emphasis> -- If SQL
449                                 support is used.</para>
450                                 </listitem>
451                                 <listitem>
452                                 <para><emphasis>rr</emphasis> -- Record Route, if
453                                 <quote>detect_direction</quote> module parameter is enabled.
454                                 </para>
455                                 </listitem>
456                                 <listitem>
457                                 <para><emphasis>dialog</emphasis> -- Dialog, if
458                                 <quote>cdr_enable</quote> module parameter is enabled.
459                                 </para>
460                                 </listitem>
461                         </itemizedlist>
462                         </para>
463                 </section>
464                 <section>
465                         <title>External Libraries or Applications</title>
466                         <para>
467                         The following libraries or applications must be installed
468                         before running &kamailio; with this module loaded:
469                         </para>
470                         <itemizedlist>
471                                 <listitem>
472                                 <para>None</para>
473                                 </listitem>
474                         </itemizedlist>
475                 </section>
476         </section>
477
478         <section id="acc.i.params">
479         <title>Parameters</title>
480         <!-- Generic ACC parameters -->
481         <section id="acc.p.early_media">
482                 <title><varname>early_media</varname> (integer)</title>
483                 <para>
484                 Should be early media (any provisional reply with body) accounted too ?
485                 </para>
486                 <para>
487                 Default value is 0 (no).
488                 </para>
489                 <example>
490                 <title>early_media example</title>
491                 <programlisting format="linespecific">
492 ...
493 modparam("acc", "early_media", 1)
494 ...
495 </programlisting>
496                 </example>
497         </section>
498         <section id="acc.p.failed_transaction_flag">
499                 <title><varname>failed_transaction_flag</varname> (integer)</title>
500                 <para>
501                 Per transaction flag which says if the transaction should be
502                 accounted also in case of failure (status>=300).
503                 </para>
504                 <para>
505                 Default value is not-set (no flag).
506                 </para>
507                 <example>
508                 <title>failed_transaction_flag example</title>
509                 <programlisting format="linespecific">
510 ...
511 modparam("acc", "failed_transaction_flag", 4)
512 ...
513 </programlisting>
514                 </example>
515         </section>
516         <section id="acc.p.failed_filter">
517                 <title><varname>failed_filter</varname> (string)</title>
518                 <para>
519                 A string of failure response codes from 300 to 999
520                 separated by commas. Failed transaction will not be accounted
521                 if its response code is in the list even when
522                 failed_transaction_flag is set.
523                 </para>
524                 <para>
525                 Default value is not-set (failure filtering is off).
526                 </para>
527                 <example>
528                 <title>failed_filter example</title>
529                 <programlisting format="linespecific">
530 ...
531 modparam("acc", "failed_filter", "404,407")
532 ...
533 </programlisting>
534                 </example>
535         </section>
536         <section id="acc.p.report_ack">
537                 <title><varname>report_ack</varname> (integer)</title>
538                 <para>
539                 Shall acc attempt to account e2e ACKs too ? Note that this is really
540                 only an attempt, as e2e ACKs may take a different path
541                 (unless RR enabled) and mismatch original INVITE (e2e ACKs are
542                 a separate transaction). The flag for accounting has to be set
543                 for each ACK as well.
544                 </para>
545                 <para>
546                 Default value is 0 (no).
547                 </para>
548                 <example>
549                 <title>report_ack example</title>
550                 <programlisting format="linespecific">
551 ...
552 modparam("acc", "report_ack", 1)
553 ...
554 </programlisting>
555                 </example>
556         </section>
557         <section id="acc.p.report_cancels">
558                 <title><varname>report_cancels</varname> (integer)</title>
559                 <para>
560                 By default, CANCEL reporting is disabled -- most accounting
561                 applications wants to see INVITE's cancellation status.
562                 Turn on if you explicitly want to account CANCEL transactions.
563                 </para>
564                 <para>
565                 Default value is 0 (no).
566                 </para>
567                 <example>
568                 <title>report_cancels example</title>
569                 <programlisting format="linespecific">
570 ...
571 modparam("acc", "report_cancels", 1)
572 ...
573 </programlisting>
574                 </example>
575         </section>
576         <section id="acc.p.detect_direction">
577                 <title><varname>detect_direction</varname> (integer)</title>
578                 <para>
579                 Controls the direction detection for sequential requests. If
580                 enabled (non zero value), for sequential requests with upstream
581                 direction (from callee to caller), the FROM and TO will be swapped
582                 (the direction will be preserved as in the original request).
583                 </para>
584                 <para>
585                 It affects all values related to TO and FROM headers (body, URI,
586                 username, domain, TAG).
587                 </para>
588                 <para>
589                 Default value is 0 (disabled).
590                 </para>
591                 <example>
592                 <title>detect_direction example</title>
593                 <programlisting format="linespecific">
594 ...
595 modparam("acc", "detect_direction", 1)
596 ...
597 </programlisting>
598                 </example>
599         </section>
600         <section id="acc.p.acc_prepare_flag">
601                 <title><varname>acc_prepare_flag</varname> (integer)</title>
602                 <para>
603                 Per transaction flag which says if the transaction may be accounted
604                 later, with flags set in TM module specific routes (e.g., like
605                 failure_route). If this flag is not set and acc or missed_call flag
606                 are not set either in request route block, there is no way to mark the
607                 request for transaction later unless you set acc_prepare_always. If either acc or missed_call flags are
608                 set in request route block, there is no need to set this flag.
609                 </para>
610                 <para>
611                 Default value is not-set (no flag).
612                 </para>
613                 <example>
614                 <title>acc_prepare_flag example</title>
615                 <programlisting format="linespecific">
616 ...
617 modparam("acc", "acc_prepare_flag", 5)
618 ...
619 </programlisting>
620                 </example>
621         </section>
622         <section id="acc.p.acc_prepare_always">
623                 <title><varname>acc_prepare_always</varname> (integer)</title>
624                 <para>
625                 Prepare all request even if acc_prepare_flag is not set to mark the request for transaction later.
626                 </para>
627                 <para>
628                 Default value is not-set (previous behaviour).
629                 </para>
630                 <example>
631                 <title>acc_prepare_flag example</title>
632                 <programlisting format="linespecific">
633 ...
634 modparam("acc", "acc_prepare_always", 1)
635 ...
636 </programlisting>
637                 </example>
638         </section>
639         <section id="acc.p.multi_leg_info">
640                 <title><varname>multi_leg_info</varname> (string)</title>
641                 <para>
642                 Defines the AVP set to be used in per-call-leg accounting.
643                 See <xref linkend="acc.i.multi-call-legs"/> for a
644                 detailed description of the Multi Call-Legs accounting.
645                 </para>
646                 <para>
647                 If empty, the multi-leg accounting support will be disabled.
648                 </para>
649                 <para>
650                 Default value is 0 (disabled).
651                 </para>
652                 <example>
653                 <title>multi_leg_info example</title>
654                 <programlisting format="linespecific">
655 ...
656 # for syslog-based accounting, use any text you want to be printed
657 modparam("acc", "multi_leg_info",
658     "text1=$avp(src);text2=$avp(dst)")
659 # for mysql-based accounting, use the names of the columns
660 modparam("acc", "multi_leg_info",
661     "leg_src=$avp(src);leg_dst=$avp(dst)")
662 # for DIAMETER-based accounting, use the DIAMETER AVP ID (as integer)
663 modparam("acc", "multi_leg_info",
664     "2345=$avp(src);2346=$avp(dst)")
665 ...
666 </programlisting>
667                 </example>
668         </section>
669         <!-- SYSLOG specific ACC parameters -->
670         <section id="acc.p.log_flag">
671                 <title><varname>log_flag</varname> (integer)</title>
672                 <para>
673                 Request flag which needs to be set to account a transaction via syslog.
674                 </para>
675                 <para>
676                 Default value is not-set (no flag).
677                 </para>
678                 <example>
679                 <title>log_flag example</title>
680                 <programlisting format="linespecific">
681 ...
682 modparam("acc", "log_flag", 2)
683 ...
684 </programlisting>
685                 </example>
686         </section>
687         <section id="acc.p.log_missed_flag">
688                 <title><varname>log_missed_flag</varname> (integer)</title>
689                 <para>
690                 Request flag which needs to be set to account missed calls via syslog.
691                 This can be used to e.g. account failures during the call setup phase
692                 from the callee side, for example if you do forking to several
693                 destinations.
694                 </para>
695                 <para>
696                 Keep in mind that this flag is reset after processing. Therefore it is
697                 necessary to set it again e.g. in a failure_route if you do serial
698                 forking and want to log all attempts.
699                 </para>
700                 <para>
701                 Default value is not-set (no flag).
702                 </para>
703                 <example>
704                 <title>log_missed_flag example</title>
705                 <programlisting format="linespecific">
706 ...
707 modparam("acc", "log_missed_flag", 3)
708 ...
709 </programlisting>
710                 </example>
711         </section>
712         <section id="acc.p.log_level">
713                 <title><varname>log_level</varname> (integer)</title>
714                 <para>
715                 Log level at which accounting messages are issued to syslog.
716                 </para>
717                 <para>
718                 Default value is 1 (L_NOTICE).
719                 </para>
720                 <example>
721                 <title>log_level example</title>
722                 <programlisting format="linespecific">
723 ...
724 modparam("acc", "log_level", 2)   # Set log_level to 2 (L_INFO)
725 ...
726 </programlisting>
727                 </example>
728         </section>
729         <section id="acc.p.log_facility">
730                 <title><varname>log_facility</varname> (string)</title>
731                 <para>
732                 Log facility to which accounting messages are issued to syslog.
733                 This allows to easily separate the accounting specific logging
734                 from the other log messages.
735                 </para>
736                 <para>
737                 Default value is LOG_DAEMON.
738                 </para>
739                 <example>
740                 <title>log_facility example</title>
741                 <programlisting format="linespecific">
742 ...
743 modparam("acc", "log_facility", "LOG_DAEMON")
744 ...
745 </programlisting>
746                 </example>
747         </section>
748         <section id="acc.p.log_extra">
749                 <title><varname>log_extra</varname> (string)</title>
750                 <para>
751                 Extra values to be logged.
752                 See section <xref linkend="acc.i.extra-accounting"/> for more details.
753                 </para>
754                 <para>
755                 Default value is NULL.
756                 </para>
757                 <example>
758                 <title>log_extra example</title>
759                 <programlisting format="linespecific">
760 ...
761 modparam("acc", "log_extra", "ua=$hdr(User-Agent);uuid=$avp(i:123)")
762 ...
763 </programlisting>
764                 </example>
765         </section>
766         <!-- SQL specific ACC parameters -->
767         <section id="acc.p.db_flag">
768                 <title><varname>db_flag</varname> (integer)</title>
769                 <para>
770                 Request flag which needs to be set to account a
771                 transaction -- database specific.
772                 </para>
773                 <para>
774                 Default value is not-set (no flag).
775                 </para>
776                 <example>
777                 <title>db_flag example</title>
778                 <programlisting format="linespecific">
779 ...
780 modparam("acc", "db_flag", 2)
781 ...
782 </programlisting>
783                 </example>
784         </section>
785         <section id="acc.p.db_missed_flag">
786                 <title><varname>db_missed_flag</varname> (integer)</title>
787                 <para>
788                 Request flag which needs to be set to account missed
789                 calls -- database specific.
790                 </para>
791                 <para>
792                 Default value is not-set (no flag).
793                 </para>
794                 <example>
795                 <title>db_missed_flag example</title>
796                 <programlisting format="linespecific">
797 ...
798 modparam("acc", "db_missed_flag", 3)
799 ...
800 </programlisting>
801                 </example>
802         </section>
803         <section  id="acc.p.db_table_acc">
804                 <title><varname>db_table_acc</varname> (string)</title>
805                 <para>
806                 Table name of accounting successful calls -- database specific. It
807                 can contain config variables that will be evaluated at runtime.
808                 </para>
809                 <para>
810                 Default value is <quote>acc</quote>
811                 </para>
812                 <example>
813                 <title>db_table_acc example</title>
814                 <programlisting format="linespecific">
815 ...
816 modparam("acc", "db_table_acc", "myacc_table")
817 modparam("acc", "db_table_acc", "acc_$time(year)_$time(mon)")
818 ...
819 </programlisting>
820                 </example>
821         </section>
822         <section id="acc.p.db_table_missed_calls">
823                 <title><varname>db_table_missed_calls</varname> (string)</title>
824                 <para>
825                 Table name for accounting missed calls -- database specific. It
826                 can contain config variables that will be evaluated at runtime.
827                 </para>
828                 <para>
829                 Default value is <quote>missed_calls</quote>
830                 </para>
831                 <example>
832                 <title>db_table_missed_calls example</title>
833                 <programlisting format="linespecific">
834 ...
835 modparam("acc", "db_table_missed_calls", "myMC_table")
836 ...
837 </programlisting>
838                 </example>
839         </section>
840         <section id="acc.p.db_url">
841                 <title><varname>db_url</varname> (string)</title>
842                 <para>
843                 SQL address -- database specific. If is set to NULL or empty string,
844                 the SQL support is disabled.
845                 </para>
846                 <para>
847                 Default value is <quote>NULL</quote> (SQL disabled).
848                 </para>
849                 <example>
850                 <title>db_url example</title>
851                 <programlisting format="linespecific">
852 ...
853 modparam("acc", "db_url", "mysql://user:password@localhost/kamailio")
854 ...
855 </programlisting>
856                 </example>
857         </section>
858         <section  id="acc.p.acc_method_column">
859                 <title><varname>acc_method_column</varname> (string)</title>
860                 <para>
861                 Column name in accounting table to store the request's method name as
862                 string.
863                 </para>
864                 <para>
865                 Default value is <quote>method</quote>.
866                 </para>
867                 <example>
868                 <title>acc_method_column example</title>
869                 <programlisting format="linespecific">
870 ...
871 modparam("acc", "acc_method_column", "method")
872 ...
873 </programlisting>
874                 </example>
875         </section>
876         <section id="acc.p.acc_from_tag_column">
877                 <title><varname>acc_from_tag_column</varname> (string)</title>
878                 <para>
879                 Column name in accounting table to store the From header TAG parameter.
880                 </para>
881                 <para>
882                 Default value is <quote>from_tag</quote>.
883                 </para>
884                 <example>
885                 <title>acc_from_tag_column example</title>
886                 <programlisting format="linespecific">
887 ...
888 modparam("acc", "acc_from_tag_column", "from_tag")
889 ...
890 </programlisting>
891                 </example>
892         </section>
893         <section id="acc.p.acc_to_tag_column">
894                 <title><varname>acc_to_tag_column</varname> (string)</title>
895                 <para>
896                 Column name in accounting table to store the To header TAG parameter.
897                 </para>
898                 <para>
899                 Default value is <quote>to_tag</quote>.
900                 </para>
901                 <example>
902                 <title>acc_to_tag_column example</title>
903                 <programlisting format="linespecific">
904 ...
905 modparam("acc", "acc_to_tag_column", "to_tag")
906 ...
907 </programlisting>
908                 </example>
909         </section>
910         <section id="acc.p.acc_callid_column">
911                 <title><varname>acc_callid_column</varname> (string)</title>
912                 <para>
913                 Column name in accounting table to store the request's Callid value.
914                 </para>
915                 <para>
916                 Default value is <quote>callid</quote>.
917                 </para>
918                 <example>
919                 <title>acc_callid_column example</title>
920                 <programlisting format="linespecific">
921 ...
922 modparam("acc", "acc_callid_column", "callid")
923 ...
924 </programlisting>
925                 </example>
926         </section>
927         <section id="acc.p.acc_sip_code_column">
928                 <title><varname>acc_sip_code_column</varname> (string)</title>
929                 <para>
930                 Column name in accounting table to store the final reply's numeric code
931                 value in string format.
932                 </para>
933                 <para>
934                 Default value is <quote>sip_code</quote>.
935                 </para>
936                 <example>
937                 <title>acc_sip_code_column example</title>
938                 <programlisting format="linespecific">
939 ...
940 modparam("acc", "acc_sip_code_column", "sip_code")
941 ...
942 </programlisting>
943                 </example>
944         </section>
945         <section id="acc.p.acc_sip_reason_column">
946                 <title><varname>acc_sip_reason_column</varname> (string)</title>
947                 <para>
948                 Column name in accounting table to store the final reply's reason
949                 phrase value.
950                 </para>
951                 <para>
952                 Default value is <quote>sip_reason</quote>.
953                 </para>
954                 <example>
955                 <title>acc_sip_reason_column example</title>
956                 <programlisting format="linespecific">
957 ...
958 modparam("acc", "acc_sip_reason_column", "sip_reason")
959 ...
960 </programlisting>
961                 </example>
962         </section>
963         <section id="acc.p.acc_time_column">
964                 <title><varname>acc_time_column</varname> (string)</title>
965                 <para>
966                 Column name in accounting table to store the time stamp of the
967                 transaction completion in date-time format.
968                 </para>
969                 <para>
970                 Default value is <quote>time</quote>.
971                 </para>
972                 <example>
973                 <title>acc_time_column example</title>
974                 <programlisting format="linespecific">
975 ...
976 modparam("acc", "acc_time_column", "time")
977 ...
978 </programlisting>
979                 </example>
980         </section>
981         <section id="acc.p.db_extra">
982                 <title><varname>db_extra</varname> (string)</title>
983                 <para>
984                 Extra values to be logged into database - DB specific.
985                 See section <xref linkend="acc.i.extra-accounting"/> for more details.
986                 </para>
987                 <para>
988                 Default value is NULL.
989                 </para>
990                 <example>
991                 <title>db_extra example</title>
992                 <programlisting format="linespecific">
993 ...
994 modparam("acc", "db_extra", "ct=$hdr(Content-type); email=$avp(s:email)")
995 ...
996 </programlisting>
997                 </example>
998         </section>
999         <section id="acc.p.db_insert_mode">
1000                 <title><varname>db_insert_mode</varname> (integer)</title>
1001                 <para>
1002                 If set to 1, use INSERT DELAYED to add records to accounting tables
1003                 when the DB driver has support for it. If no INSERT DELAYED support
1004                 is offered by DB driver, then standard INSERT is used. Beware that
1005                 MySQL InnoDB engine doesn't support INSERT DELAYED, thus be sure
1006                 the acc tables are defined with different type (e.g., MyISAM).
1007                 </para>
1008                 <para>
1009                 If set to 2, async insert is used if the db driver module has
1010                 support for it and if async_workers core parameter value is greater
1011                 than 0. If not, then standard INSERT is used.
1012                 </para>
1013                 <para>
1014                 Default value is 0 (no INSERT DELAYED nor async insert).
1015                 </para>
1016                 <example>
1017                 <title>db_insert_mode example</title>
1018                 <programlisting format="linespecific">
1019 ...
1020 modparam("acc", "db_insert_mode", 1)
1021 ...
1022 </programlisting>
1023                 </example>
1024         </section>
1025         <!-- DIAMETER specific ACC parameters -->
1026         <section id="acc.p.diameter_flag">
1027                 <title><varname>diameter_flag</varname> (integer)</title>
1028                 <para>
1029                 Request flag which needs to be set to account a
1030                 transaction -- DIAMETER specific.
1031                 </para>
1032                 <para>
1033                 Default value is not-set (no flag).
1034                 </para>
1035                 <example>
1036                 <title>diameter_flag example</title>
1037                 <programlisting format="linespecific">
1038 ...
1039 modparam("acc", "diameter_flag", 2)
1040 ...
1041 </programlisting>
1042                 </example>
1043         </section>
1044         <section id="acc.p.diameter_missed_flag">
1045                 <title><varname>diameter_missed_flag</varname> (integer)</title>
1046                 <para>
1047                 Request flag which needs to be set to account missed
1048                 calls -- DIAMETER specific.
1049                 </para>
1050                 <para>
1051                 Default value is not-set (no flag).
1052                 </para>
1053                 <example>
1054                 <title>diameter_missed_flag example</title>
1055                 <programlisting format="linespecific">
1056 ...
1057 modparam("acc", "diameter_missed_flag", 3)
1058 ...
1059 </programlisting>
1060                 </example>
1061         </section>
1062         <section id="acc.p.diameter_client_host">
1063                 <title><varname>diameter_client_host</varname> (string)</title>
1064                 <para>
1065                 Hostname of the machine where the DIAMETER Client is
1066                 running -- DIAMETER specific.
1067                 </para>
1068                 <para>
1069                 Default value is <quote>localhost</quote>.
1070                 </para>
1071                 <example>
1072                 <title>diameter_client_host example</title>
1073                 <programlisting format="linespecific">
1074 ...
1075 modparam("acc", "diameter_client_host", "3a_server.net")
1076 ...
1077 </programlisting>
1078                 </example>
1079         </section>
1080         <section id="acc.p.diameter_client_port">
1081                 <title><varname>diameter_client_port</varname> (int)</title>
1082                 <para>
1083                 Port number where the Diameter Client is
1084                 listening -- DIAMETER specific.
1085                 </para>
1086                 <para>
1087                 Default value is 3000.
1088                 </para>
1089                 <example>
1090                 <title>diameter_client_host example</title>
1091                 <programlisting format="linespecific">
1092 ...
1093 modparam("acc", "diameter_client_port", 3000)
1094 ...
1095 </programlisting>
1096                 </example>
1097         </section>
1098         <section id="acc.p.diameter_extra">
1099                 <title><varname>diameter_extra</varname> (string)</title>
1100                 <para>
1101                 Extra values to be logged via DIAMETER - DIAMETER specific.
1102                 See section <xref linkend="acc.i.extra-accounting"/> for more details.
1103                 </para>
1104                 <para>
1105                 Default value is NULL.
1106                 </para>
1107                 <example>
1108                 <title>diameter_extra example</title>
1109                 <programlisting format="linespecific">
1110 ...
1111 modparam("acc", "diameter_extra", "7846=$hdr(Content-type);7847=$avp(s:email)")
1112 ...
1113 </programlisting>
1114                 </example>
1115         </section>
1116         <section id="acc.p.cdr_enable">
1117                 <title><varname>cdr_enable</varname> (integer)</title>
1118                 <para>
1119                 Should CDR-based logging be enabled?
1120                 </para>
1121                 <para>
1122                 0 - off (default).
1123                 1 - on.
1124                 </para>
1125                 <example>
1126                 <title>cdr_enable example</title>
1127                 <programlisting format="linespecific">
1128 ...
1129 modparam("acc", "cdr_enable", 1)
1130 ...
1131 </programlisting>
1132                 </example>
1133         </section>
1134         <section id="acc.p.cdr_expired_dlg_enable">
1135                 <title><varname>cdr_expired_dlg_enable</varname> (integer)</title>
1136                 <para>
1137                 Should CDR-based logging be enabled in case of expired dialogs?
1138                 </para>
1139                 <para>
1140                 0 - off (default).
1141                 1 - on.
1142                 </para>
1143                 <example>
1144                 <title>cdr_expired_dlg_enable example</title>
1145                 <programlisting format="linespecific">
1146 ...
1147 modparam("acc", "cdr_expired_dlg_enable", 1)
1148 ...
1149 </programlisting>
1150                 </example>
1151         </section>
1152         <section id="acc.p.cdr_start_on_confirmed">
1153                 <title><varname>cdr_start_on_confirmed</varname> (integer)</title>
1154                 <para>
1155                 Should the start time be taken from the time when the dialog is created,
1156                 or when the dialog is confirmed?
1157                 </para>
1158                 <para>
1159                 0 - use time of dialog creation (default).
1160                 1 - use time of dialog confirmation.
1161                 </para>
1162                 <example>
1163                 <title>cdr_start_on_confirmed example</title>
1164                 <programlisting format="linespecific">
1165 ...
1166 modparam("acc", "cdr_start_on_confirmed", 1)
1167 ...
1168 </programlisting>
1169                 </example>
1170         </section>
1171         <section id="acc.p.cdr_facility">
1172                 <title><varname>cdr_facility</varname> (integer)</title>
1173                 <para>
1174                 Log facility to which CDR messages are issued to syslog.
1175                 This allows to easily seperate CDR-specific logging from
1176                 the other log messages.
1177                 </para>
1178                 <para>
1179                 Default value is LOG_DAEMON.
1180                 </para>
1181                 <example>
1182                 <title>cdr_facility example</title>
1183                 <programlisting format="linespecific">
1184 ...
1185 modparam("acc", "cdr_facility", "LOG_DAEMON")
1186 ...
1187 </programlisting>
1188                 </example>
1189         </section>
1190         <section id="acc.p.cdr_extra">
1191                 <title><varname>cdr_extra</varname> (string)</title>
1192                 <para>
1193                 Set of pseudo-variables defining custom CDR fields. See
1194         <xref linkend="acc.i.cdr-extra"/> for more details.
1195                 </para>
1196                 <para>
1197                 Default value is NULL.
1198                 </para>
1199                 <example>
1200                 <title>cdr_extra example</title>
1201                 <programlisting format="linespecific">
1202 ...
1203 modparam("acc", "cdr_extra", "c1=$dlg_var(caller);c2=$dlg_var(callee)"
1204 ...
1205 </programlisting>
1206                 </example>
1207         </section>
1208         <section id="acc.p.cdr_extra_nullable">
1209                 <title><varname>cdr_extra_nullable</varname> (integer)</title>
1210                 <para>
1211                 Should custom CDR fields be saved as NULL?
1212                 </para>
1213                 <para>
1214                 If set to 0, custom CDR fields not defined in config operation (or set to $null) will be saved as empty string.
1215                 If set to 1, custom CDR fields not defined in config operation (or set to $null) will be saved as NULL.
1216                 </para>
1217                 <para>
1218                 Default value is 0.
1219                 </para>
1220                 <example>
1221                 <title>cdr_extra_nullable example</title>
1222                 <programlisting format="linespecific">
1223 ...
1224 modparam("acc", "cdr_extra_nullable", 1)
1225 ...
1226 </programlisting>
1227                 </example>
1228         </section>
1229         <section id="acc.p.cdr_start_id">
1230                 <title><varname>cdr_start_id</varname> (string)</title>
1231                 <para>
1232                 Modifying the id which is used to store the start time.
1233                 </para>
1234                 <para>
1235                 Default value is 'start_time'
1236                 </para>
1237                 <example>
1238                 <title>cdr_start_id example</title>
1239                 <programlisting format="linespecific">
1240 ...
1241 modparam("acc", "cdr_start_id", "start")
1242 ...
1243 </programlisting>
1244                 </example>
1245         </section>
1246         <section id="acc.p.cdr_end_id">
1247                 <title><varname>cdr_end_id</varname> (string)</title>
1248                 <para>
1249                 Modifying the id which is used to store the end time.
1250                 </para>
1251                 <para>
1252                 Default value is 'end_time'
1253                 </para>
1254                 <example>
1255                 <title>cdr_end_id example</title>
1256                 <programlisting format="linespecific">
1257 ...
1258 modparam("acc", "cdr_end_id", "end")
1259 ...
1260 </programlisting>
1261                 </example>
1262         </section>
1263         <section id="acc.p.cdr_duration_id">
1264                 <title><varname>cdr_duration_id</varname> (string)</title>
1265                 <para>
1266                 Modify the id which is used to store the duration.
1267                 </para>
1268                 <para>
1269                 Default value is 'duration'
1270                 </para>
1271                 <example>
1272                 <title>cdr_duration_id example</title>
1273                 <programlisting format="linespecific">
1274 ...
1275 modparam("acc", "cdr_duration_id", "d")
1276 ...
1277 </programlisting>
1278                 </example>
1279         </section>
1280         <section id="acc.p.cdr_log_enable">
1281                 <title><varname>cdr_log_enable</varname> (int)</title>
1282                 <para>
1283                 Control if CDR-based accounting should be written to syslog.
1284                 </para>
1285                 <para>
1286                 0 - off.
1287                 1 - on (default).
1288                 </para>
1289                 <example>
1290                 <title>cdr_log_enable example</title>
1291                 <programlisting format="linespecific">
1292 ...
1293 modparam("acc", "cdr_log_enable", 0)
1294 ...
1295 </programlisting>
1296                 </example>
1297         </section>
1298         <section id="acc.p.cdrs_table">
1299                 <title><varname>cdrs_table</varname> (str)</title>
1300                 <para>
1301                 Name of db table to store dialog-based CDRs.
1302                 </para>
1303                 <para>
1304                 Default value is "" (no db storage for dialog-based CDRs).
1305                 </para>
1306                 <example>
1307                 <title>cdrs_table example</title>
1308                 <programlisting format="linespecific">
1309 ...
1310 modparam("acc", "cdrs_table", "acc_cdrs")
1311 ...
1312 </programlisting>
1313                 </example>
1314         </section>
1315         <section id="acc.p.time_mode">
1316                 <title><varname>time_mode</varname> (int)</title>
1317                 <para>
1318                 Store additional value related to the time of event.
1319                 </para>
1320                 <para>
1321                 Values can be:
1322                 </para>
1323                 <itemizedlist>
1324                 <listitem>
1325                         <para><emphasis>0</emphasis> -  (default), save only unix
1326                                 timestamp for syslog and datetime for database.</para>
1327                 </listitem>
1328                 <listitem>
1329                         <para><emphasis>1</emphasis> - save seconds in time_attr and
1330                                 microseconds in time_exten.</para>
1331                 </listitem>
1332                 <listitem>
1333                         <para><emphasis>2</emphasis> - save seconds.milliseconds
1334                                 in time_attr.</para>
1335                 </listitem>
1336                 <listitem>
1337                         <para><emphasis>3</emphasis> - save formatted time according
1338                                 to time_format parameter, using the output of localtime(). Used for cdr entries too.
1339                         </para>
1340                 </listitem>
1341                 <listitem>
1342                         <para><emphasis>4</emphasis> - save formatted time according
1343                                 to time_format parameter, using the output of gmtime(). Used for cdr entries too.
1344                         </para>
1345                 </listitem>
1346                 </itemizedlist>
1347
1348                 <example>
1349                 <title>time_mode example</title>
1350                 <programlisting format="linespecific">
1351 ...
1352 modparam("acc", "time_mode", 1)
1353 ...
1354 </programlisting>
1355                 </example>
1356         </section>
1357         <section id="acc.p.time_attr">
1358                 <title><varname>time_attr</varname> (str)</title>
1359                 <para>
1360                 Name of the syslog attribute or database column where to store additional
1361                 value related to the time of event.
1362                 </para>
1363                 <para>
1364                 For db accounting, the column has to be of different types, depending on
1365                 time_mode value. When time_mode is:
1366                 </para>
1367                 <itemizedlist>
1368                 <listitem>
1369                         <para><emphasis>1</emphasis> - time_attr column has to be int.</para>
1370                 </listitem>
1371                 <listitem>
1372                         <para><emphasis>2</emphasis> - time_attr column has to be double.</para>
1373                 </listitem>
1374                 <listitem>
1375                         <para><emphasis>3</emphasis> - time_attr column has to be varchar(128).</para>
1376                 </listitem>
1377                 <listitem>
1378                         <para><emphasis>4</emphasis> - time_attr column has to be varchar(128).</para>
1379                 </listitem>
1380                 </itemizedlist>
1381                 <para>
1382                 For time_mode=1, this attribute is not written in syslog, because time
1383                 value is already unix timestamp, but in db accounting time value is
1384                 datetime and requires a function to get the timestamp.
1385                 </para>
1386                 <example>
1387                 <title>time_attr example</title>
1388                 <programlisting format="linespecific">
1389 ...
1390 modparam("acc", "time_attr", "seconds")
1391 ...
1392 </programlisting>
1393                 </example>
1394         </section>
1395         <section id="acc.p.time_exten">
1396                 <title><varname>time_exten</varname> (str)</title>
1397                 <para>
1398                 Name of the syslog attribute or database column where to store extended
1399                 value related to the time of event.
1400                 </para>
1401                 <para>
1402                 It is used now only for time_mode=1 and database column has to be int:
1403                 </para>
1404                 <example>
1405                 <title>time_exten example</title>
1406                 <programlisting format="linespecific">
1407 ...
1408 modparam("acc", "time_exten", "microsecs")
1409 ...
1410 </programlisting>
1411                 </example>
1412         </section>
1413         <section id="acc.p.time_format">
1414                 <title><varname>time_format</varname> (str)</title>
1415                 <para>
1416                 Specify the format to print the time for time_mode 3 or 4.
1417                 </para>
1418                 <para>
1419                 Default value is %Y-%m-%d %H:%M:%S".
1420                 </para>
1421                 <example>
1422                 <title>time_format example</title>
1423                 <programlisting format="linespecific">
1424 ...
1425 modparam("acc", "time_format", "%Y/%m/%d %H:%M:%S")
1426 ...
1427 </programlisting>
1428                 </example>
1429         </section>
1430         <section id="acc.p.reason_from_hf">
1431                 <title><varname>reason_from_hf</varname> (int)</title>
1432                 <para>
1433                 Tells where to take sip_reason from.  If value is 0,
1434                 sip_reason is taken from status line.  Otherwise, sip_reason
1435                 is taken from Reason header field(s) if present.
1436                 Currently only the first Reason header is used.
1437                 </para>
1438                 <para>
1439                 Default value is 0.
1440                 </para>
1441                 <example>
1442                 <title>reason_from_hf</title>
1443                 <programlisting format="linespecific">
1444 ...
1445 modparam("acc", "reason_from_hf", 1)
1446 ...
1447 </programlisting>
1448                 </example>
1449         </section>
1450         <section id="acc.p.clone_msg">
1451                 <title><varname>clone_msg</varname> (int)</title>
1452                 <para>
1453                 If set to 1, request structure from transaction is cloned temporarily
1454                 in the callback to get acc attributes. It is required if you account
1455                 values from SIP headers to avoid concurrent access to the shared memory
1456                 transaction structure, specially when accounting 1xx events. If set to
1457                 0, it uses directly the shared memory structure, be sure you store all
1458                 needed attributes in AVPs/XAVPs inside request route.
1459                 </para>
1460                 <para>
1461                 Default value is 1.
1462                 </para>
1463                 <example>
1464                 <title>clone_msg</title>
1465                 <programlisting format="linespecific">
1466 ...
1467 modparam("acc", "clone_msg", 0)
1468 ...
1469 </programlisting>
1470                 </example>
1471         </section>
1472         <section id="acc.p.cdr_on_failed">
1473                 <title><varname>cdr_on_failed</varname> (int)</title>
1474                 <para>
1475                 If set to 1, the module stores the CDR for a failed dialog (calls not
1476                 answered). If set to 0, those records are not stored, only those for
1477                 answered calls.
1478                 </para>
1479                 <para>
1480                 Default value is 1.
1481                 </para>
1482                 <example>
1483                 <title>cdr_on_failed</title>
1484                 <programlisting format="linespecific">
1485 ...
1486 modparam("acc", "cdr_on_failed", 0)
1487 ...
1488 </programlisting>
1489                 </example>
1490         </section>
1491         </section>
1492
1493         <section>
1494         <title>Functions</title>
1495         <section id="acc.f.acc_log_request">
1496                 <title>
1497                         <function moreinfo="none">acc_log_request(comment)</function>
1498                 </title>
1499                 <para>
1500                 <function moreinfo="none">acc_request</function> reports on a request,
1501                 for example, it can be used to report on missed calls to off-line users
1502                 who are replied 404 - Not Found. To avoid multiple reports on UDP
1503                 request retransmission, you would need to embed the
1504                 action in stateful processing.
1505                 </para>
1506                 <para>
1507                 Meaning of the parameters is as follows:</para>
1508                 <itemizedlist>
1509                 <listitem>
1510                         <para><emphasis>comment</emphasis> - Comment to be appended.
1511                         The string can contain any number of pseudo-variables.
1512                         </para>
1513                 </listitem>
1514                 </itemizedlist>
1515                 <para>
1516                 This function can be used from ANY_ROUTE.
1517                 </para>
1518                 <example>
1519                 <title>acc_log_request usage</title>
1520                 <programlisting format="linespecific">
1521 ...
1522 acc_log_request("Some comment");
1523 $var(code) = 404;
1524 $avp(reason) = "Not found";
1525 acc_log_request("$var(code) Error: $avp(reason)");
1526 ...
1527 </programlisting>
1528                 </example>
1529         </section>
1530         <section id="acc.f.acc_db_request">
1531                 <title>
1532                         <function moreinfo="none">acc_db_request(comment, table)</function>
1533                 </title>
1534                 <para>
1535                 Like <function moreinfo="none">acc_log_request</function>,
1536                 <function moreinfo="none">acc_db_request</function> reports on a
1537                 request. The report is sent to database at <quote>db_url</quote>, in
1538                 the table referred to in the second action parameter.
1539                 </para>
1540                 <para>
1541                 Meaning of the parameters is as follows:
1542                 </para>
1543                 <itemizedlist>
1544                 <listitem>
1545                         <para><emphasis>comment</emphasis> - Comment to be appended.
1546                         The string can contain any number of pseudo-variables.
1547                         </para>
1548                 </listitem>
1549                 <listitem>
1550                         <para><emphasis>table</emphasis> - Database table to be used. It
1551                         can contain config variables that are evaluated at runtime.</para>
1552                 </listitem>
1553                 </itemizedlist>
1554                 <para>
1555                 This function can be used from ANY_ROUTE.
1556                 </para>
1557                 <example>
1558                 <title>acc_db_request usage</title>
1559                 <programlisting format="linespecific">
1560 ...
1561 acc_db_request("Some comment", "SomeTable");
1562 acc_db_request("Some comment", "acc_$time(year)_$time(mon)");
1563 acc_db_request("$var(code) Error: $avp(reason)", "SomeTable");
1564 ...
1565 </programlisting>
1566                 </example>
1567         </section>
1568         <section id="acc.f.acc_request">
1569                 <title>
1570                         <function moreinfo="none">acc_request(comment, table)</function>
1571                 </title>
1572                 <para>
1573                 Wrapper around <function moreinfo="none">acc_log_request</function>
1574                 and <function moreinfo="none">acc_db_request</function> functions,
1575                 writing the accounting record to LOG and DATABASE backends. If
1576                 <quote>db_url</quote> parameter is not set, the acc record is written
1577                 only to LOG backend.
1578                 </para>
1579                 <para>
1580                 Meaning of the parameters is as follows:
1581                 </para>
1582                 <itemizedlist>
1583                 <listitem>
1584                         <para><emphasis>comment</emphasis> - Comment to be used for
1585                         generating the SIP response code and text fields, if in the
1586                         format <quote>CODE TEXT</quote>. The CODE should be a valid
1587                         SIP response code (100..699). The TEXT can be one or many words.
1588                         If CODE is missing, then 0 is used.
1589                         The parameter can contain pseudo-variables.
1590                         </para>
1591                 </listitem>
1592                 <listitem>
1593                         <para><emphasis>table</emphasis> - Database table to be used. It
1594                         can contain config variables that are evaluated at runtime.</para>
1595                 </listitem>
1596                 </itemizedlist>
1597                 <para>
1598                 This function can be used from ANY_ROUTE.
1599                 </para>
1600                 <example>
1601                 <title>acc_db_request usage</title>
1602                 <programlisting format="linespecific">
1603 ...
1604 acc_request("100 Received", "acc");
1605 acc_request("100 Received", "acc_$time(year)_$time(mon)");
1606 acc_db_request("$var(code) $avp(reason)", "acc");
1607 ...
1608 </programlisting>
1609                 </example>
1610         </section>
1611         <section id="acc.f.acc_diam_request">
1612                 <title>
1613                         <function moreinfo="none">acc_diam_request(comment)</function>
1614                 </title>
1615                 <para>
1616                 Like <function moreinfo="none">acc_log_request</function>,
1617                 <function moreinfo="none">acc_diam_request</function> reports on
1618                 a request. It reports to the configured Diameter server.
1619                 </para>
1620                 <para>
1621                 Meaning of the parameters is as follows:</para>
1622                 <itemizedlist>
1623                 <listitem>
1624                         <para><emphasis>comment</emphasis> - Comment to be appended.
1625                         The string can contain any number of pseudo-variables.
1626                         </para>
1627                 </listitem>
1628                 </itemizedlist>
1629                 <para>
1630                 This function can be used from ANY_ROUTE.
1631                 </para>
1632                 <example>
1633                 <title>acc_diam_request usage</title>
1634                 <programlisting format="linespecific">
1635 ...
1636 acc_diam_request("Some comment");
1637 acc_diam_request("$var(code) Error: $avp(reason)");
1638 ...
1639 </programlisting>
1640                 </example>
1641         </section>
1642         </section>
1643 </chapter>
1644