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