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