acc(k): added notes about dynamic table name for db acc to docs

modules_k/acc/README

@@ -29,11 +29,11 @@ Sven Knoblich
    1&1 Internet AG
    <[email protected]>
 
-   Copyright © 2002, 2003 FhG FOKUS
+   Copyright © 2002, 2003 FhG FOKUS
 
-   Copyright © 2004, 2006 Voice Sistem SRL
+   Copyright © 2004, 2006 Voice Sistem SRL
 
-   Copyright © 2011 1&1 Internet AG
+   Copyright © 2011 1&1 Internet AG
    Revision History
    Revision $Revision$ $Date$
      __________________________________________________________________
@@ -119,9 +119,12 @@ Sven Knoblich
               6.36. diameter_client_port (int)
               6.37. diameter_extra (string)
               6.38. cdr_enable (integer)
-              6.39. cdr_start_when_confirmed (integer)
-              6.40. cdr_log_facility (integer)
-              6.41. cdr_log_extra (string)
+              6.39. cdr_start_on_confirmed (integer)
+              6.40. cdr_facility (integer)
+              6.41. cdr_extra (string)
+              6.42. cdr_start_id (string)
+              6.43. cdr_end_id (string)
+              6.44. cdr_duration_id (string)
 
         7. Functions
 
@@ -172,13 +175,16 @@ Sven Knoblich
    1.36. diameter_client_host example
    1.37. diameter_extra example
    1.38. cdr_enable example
-   1.39. cdr_start_when_confirmed example
-   1.40. cdr_log_facility example
-   1.41. cdr_log_extra example
-   1.42. acc_log_request usage
-   1.43. acc_db_request usage
-   1.44. acc_rad_request usage
-   1.45. acc_diam_request usage
+   1.39. cdr_start_on_confirmed example
+   1.40. cdr_facility example
+   1.41. cdr_extra example
+   1.42. cdr_start_id example
+   1.43. cdr_end_id example
+   1.44. cdr_duration_id example
+   1.45. acc_log_request usage
+   1.46. acc_db_request usage
+   1.47. acc_rad_request usage
+   1.48. acc_diam_request usage
 
 Chapter 1. Admin Guide
 
@@ -261,9 +267,12 @@ Chapter 1. Admin Guide
         6.36. diameter_client_port (int)
         6.37. diameter_extra (string)
         6.38. cdr_enable (integer)
-        6.39. cdr_start_when_confirmed (integer)
-        6.40. cdr_log_facility (integer)
-        6.41. cdr_log_extra (string)
+        6.39. cdr_start_on_confirmed (integer)
+        6.40. cdr_facility (integer)
+        6.41. cdr_extra (string)
+        6.42. cdr_start_id (string)
+        6.43. cdr_end_id (string)
+        6.44. cdr_duration_id (string)
 
    7. Functions
 
@@ -281,7 +290,7 @@ Chapter 1. Admin Guide
 
    To account a transaction and to choose which set of backends to be
    used, the script writer just has to set some flags (see the module
-   parameters section for flag definitions Section 6, “Parameters�). If
+   parameters section for flag definitions Section 6, "Parameters"). If
    the accounting flag for a specific backend is set, the acc module will
    then report on completed transaction. A typical usage of the module
    takes no acc-specific script command -- the functionality binds
@@ -293,7 +302,7 @@ Chapter 1. Admin Guide
    The accounting module will log by default a fixed set of attributes for
    the transaction - if you customize your accounting by adding more
    information to be logged, please see the next chapter about extra
-   accounting - Section 2, “Extra accounting�.
+   accounting - Section 2, "Extra accounting".
 
    The fixed minimal accounting information is:
      * Request Method name
@@ -500,8 +509,8 @@ Note
 
 4.1. Overview
 
-   It is possible to generate and log Call Data Records (CDRs) directly
-   from Kamailio in addition to transaction-based logging. Apart from a
+   In addition to transaction-based logging, it is possible to generate
+   and log Call Data Records (CDRs) directly from Kamailio. Apart from a
    basic set of CDR fields which are always included (covering start time,
    end time, and duration), the approach allows flexible specification of
    additional fields that should be taken into account using the
@@ -525,19 +534,24 @@ Note
    information given will not be stored in the CDR as they cannot be
    accessed by the end of the call when the CDR is logged.
 
+   Note that CDR generation does not involve any kind of database storage
+   (yet). In order to persist the CDRs into a database you will have to
+   set up an exterior process (i.e., a script living outside of Kamailio)
+   and implement the storage task yourself.
+
 4.2. CDR Extra
 
-   This section is similar to the “LOG accounting� part of Section 2,
-   “Extra accounting�.
+   This section is similar to the "LOG accounting" part of Section 2,
+   "Extra accounting".
 
 4.2.1. Definitions and syntax
 
    Selection of extra information is done similar to the transaction extra
-   Section 2.2, “Definitions and syntax�.
-     * cdr_log_extra = cdr_extra_definition (';'cdr_extra_definition)*
+   Section 2.2, "Definitions and syntax".
+     * cdr_extra = cdr_extra_definition (';'cdr_extra_definition)*
      * cdr_extra_definition = cdr_log_name '=' pseudo_variable
 
-   See also Section 6.41, “cdr_log_extra (string)�.
+   See also Section 6.41, "cdr_extra (string)".
 
    The full list of supported pseudo-variables in Sip-Router is available
    at: http://sip-router.org/wiki/cookbooks/pseudo-variables/devel
@@ -546,7 +560,7 @@ Note
 
 4.3.1. Overview
 
-   As mentioned in Section 3, “Multi Call-Legs accounting�, a leg
+   As mentioned in Section 3, "Multi Call-Legs accounting", a leg
    represents a parallel or forwarded call. In contrast to the normal
    accounting the cdr logging uses dialogs instead of transaction to log
    data. This may reduce the amount of information but it also make it
@@ -557,7 +571,7 @@ Note
 4.3.2. Configuration
 
    When you route messages multiple times through your proxy (e.g. to
-   handle “call-forwardings�) you have to use detect_spirals from the
+   handle "call-forwardings") you have to use detect_spirals from the
    dialog modules. Otherwise the proxy can't identify and reuse existing
    dialogs.
 
@@ -608,9 +622,9 @@ $dlg_var(callee) = $avp(callee); #callee='C'
    listed modules must be loaded before this module):
      * tm -- Transaction Manager
      * a database module -- If SQL support is used.
-     * rr -- Record Route, if “detect_direction� module parameter is
+     * rr -- Record Route, if "detect_direction" module parameter is
        enabled.
-     * dialog -- Dialog, if “cdr_enable� module parameter is enabled.
+     * dialog -- Dialog, if "cdr_enable" module parameter is enabled.
 
 5.2. External Libraries or Applications
 
@@ -659,9 +673,12 @@ $dlg_var(callee) = $avp(callee); #callee='C'
    6.36. diameter_client_port (int)
    6.37. diameter_extra (string)
    6.38. cdr_enable (integer)
-   6.39. cdr_start_when_confirmed (integer)
-   6.40. cdr_log_facility (integer)
-   6.41. cdr_log_extra (string)
+   6.39. cdr_start_on_confirmed (integer)
+   6.40. cdr_facility (integer)
+   6.41. cdr_extra (string)
+   6.42. cdr_start_id (string)
+   6.43. cdr_end_id (string)
+   6.44. cdr_duration_id (string)
 
 6.1. early_media (integer)
 
@@ -748,7 +765,7 @@ modparam("acc", "acc_prepare_flag", 5)
 6.8. multi_leg_info (string)
 
    Defines the AVP set to be used in per-call-leg accounting. See
-   Section 3, “Multi Call-Legs accounting� for a detailed description of
+   Section 3, "Multi Call-Legs accounting" for a detailed description of
    the Multi Call-Legs accounting.
 
    If empty, the multi-leg accounting support will be disabled.
@@ -809,7 +826,7 @@ modparam("acc", "log_facility", "LOG_DAEMON")
 
 6.13. log_extra (string)
 
-   Extra values to be logged. See section Section 2, “Extra accounting�
+   Extra values to be logged. See section Section 2, "Extra accounting"
    for more details.
 
    Default value is NULL.
@@ -828,7 +845,7 @@ modparam("acc", "log_extra", "ua=$hdr(User-Agent);uuid=$avp(i:123)")
    If the parameter is set to empty string, the RADIUS accounting support
    will be disabled (even if compiled).
 
-   Default value is “NULL�.
+   Default value is "NULL".
 
    Example 1.14. radius_config example
 modparam("acc", "radius_config", "/etc/radiusclient/radiusclient.conf")
@@ -865,7 +882,7 @@ modparam("acc", "service_type", 16)
 6.18. radius_extra (string)
 
    Extra values to be logged via RADIUS - RADIUS specific. See section
-   Section 2, “Extra accounting� for more details.
+   Section 2, "Extra accounting" for more details.
 
    Default value is NULL.
 
@@ -894,18 +911,21 @@ modparam("acc", "db_missed_flag", 3)
 
 6.21. db_table_acc (string)
 
-   Table name of accounting successfull calls -- database specific.
+   Table name of accounting successfull calls -- database specific. It can
+   contain config variables that will be evaluated at runtime.
 
-   Default value is “acc�
+   Default value is "acc"
 
    Example 1.21. db_table_acc example
 modparam("acc", "db_table_acc", "myacc_table")
+modparam("acc", "db_table_acc", "acc_$time(year)_$time(mon)")
 
 6.22. db_table_missed_calls (string)
 
-   Table name for accounting missed calls -- database specific.
+   Table name for accounting missed calls -- database specific. It can
+   contain config variables that will be evaluated at runtime.
 
-   Default value is “missed_calls�
+   Default value is "missed_calls"
 
    Example 1.22. db_table_missed_calls example
 modparam("acc", "db_table_missed_calls", "myMC_table")
@@ -915,7 +935,7 @@ modparam("acc", "db_table_missed_calls", "myMC_table")
    SQL address -- database specific. If is set to NULL or emty string, the
    SQL support is disabled.
 
-   Default value is “NULL� (SQL disabled).
+   Default value is "NULL" (SQL disabled).
 
    Example 1.23. db_url example
 modparam("acc", "db_url", "mysql://user:password@localhost/openser")
@@ -925,7 +945,7 @@ modparam("acc", "db_url", "mysql://user:password@localhost/openser")
    Column name in accounting table to store the request's method name as
    string.
 
-   Default value is “method�.
+   Default value is "method".
 
    Example 1.24. acc_method_column example
 modparam("acc", "acc_method_column", "method")
@@ -934,7 +954,7 @@ modparam("acc", "acc_method_column", "method")
 
    Column name in accounting table to store the From header TAG parameter.
 
-   Default value is “from_tag�.
+   Default value is "from_tag".
 
    Example 1.25. acc_from_tag_column example
 modparam("acc", "acc_from_tag_column", "from_tag")
@@ -943,7 +963,7 @@ modparam("acc", "acc_from_tag_column", "from_tag")
 
    Column name in accounting table to store the To header TAG parameter.
 
-   Default value is “to_tag�.
+   Default value is "to_tag".
 
    Example 1.26. acc_to_tag_column example
 modparam("acc", "acc_to_tag_column", "to_tag")
@@ -952,7 +972,7 @@ modparam("acc", "acc_to_tag_column", "to_tag")
 
    Column name in accounting table to store the request's Callid value.
 
-   Default value is “callid�.
+   Default value is "callid".
 
    Example 1.27. acc_callid_column example
 modparam("acc", "acc_callid_column", "callid")
@@ -962,7 +982,7 @@ modparam("acc", "acc_callid_column", "callid")
    Column name in accounting table to store the final reply's numric code
    value in string format.
 
-   Default value is “sip_code�.
+   Default value is "sip_code".
 
    Example 1.28. acc_sip_code_column example
 modparam("acc", "acc_sip_code_column", "sip_code")
@@ -972,7 +992,7 @@ modparam("acc", "acc_sip_code_column", "sip_code")
    Column name in accounting table to store the final reply's reason
    phrase value.
 
-   Default value is “sip_reason�.
+   Default value is "sip_reason".
 
    Example 1.29. acc_sip_reason_column example
 modparam("acc", "acc_sip_reason_column", "sip_reason")
@@ -982,7 +1002,7 @@ modparam("acc", "acc_sip_reason_column", "sip_reason")
    Column name in accounting table to store the time stamp of the
    transaction completion in date-time format.
 
-   Default value is “time�.
+   Default value is "time".
 
    Example 1.30. acc_time_column example
 modparam("acc", "acc_time_column", "time")
@@ -990,7 +1010,7 @@ modparam("acc", "acc_time_column", "time")
 6.31. db_extra (string)
 
    Extra values to be logged into database - DB specific. See section
-   Section 2, “Extra accounting� for more details.
+   Section 2, "Extra accounting" for more details.
 
    Default value is NULL.
 
@@ -1033,7 +1053,7 @@ modparam("acc", "diameter_missed_flag", 3)
    Hostname of the machine where the DIAMETER Client is running --
    DIAMETER specific.
 
-   Default value is “localhost�.
+   Default value is "localhost".
 
    Example 1.35. diameter_client_host example
 modparam("acc", "diameter_client_host", "3a_server.net")
@@ -1051,7 +1071,7 @@ modparam("acc", "diameter_client_port", 3000)
 6.37. diameter_extra (string)
 
    Extra values to be logged via DIAMETER - DIAMETER specific. See section
-   Section 2, “Extra accounting� for more details.
+   Section 2, "Extra accounting" for more details.
 
    Default value is NULL.
 
@@ -1067,7 +1087,7 @@ modparam("acc", "diameter_extra", "7846=$hdr(Content-type);7847=$avp(s:email)")
    Example 1.38. cdr_enable example
 modparam("acc", "cdr_enable", 1)
 
-6.39. cdr_start_when_confirmed (integer)
+6.39. cdr_start_on_confirmed (integer)
 
    Should the start time be taken from the time when the dialog is
    created, or when the dialog is confirmed?
@@ -1075,28 +1095,55 @@ modparam("acc", "cdr_enable", 1)
    0 - use time of dialog creation (default). 1 - use time of dialog
    confirmation.
 
-   Example 1.39. cdr_start_when_confirmed example
-modparam("acc", "cdr_start_when_confirmed", 1)
+   Example 1.39. cdr_start_on_confirmed example
+modparam("acc", "cdr_start_on_confirmed", 1)
 
-6.40. cdr_log_facility (integer)
+6.40. cdr_facility (integer)
 
    Log facility to which CDR messages are issued to syslog. This allows to
    easily seperate CDR-specific logging from the other log messages.
 
    Default value is LOG_DAEMON.
 
-   Example 1.40. cdr_log_facility example
-modparam("acc", "cdr_log_facility", "LOG_DAEMON")
+   Example 1.40. cdr_facility example
+modparam("acc", "cdr_facility", "LOG_DAEMON")
 
-6.41. cdr_log_extra (string)
+6.41. cdr_extra (string)
 
    Set of pseudo-variables defining custom CDR fields. See Section 4.2,
-   “CDR Extra� for more details.
+   "CDR Extra" for more details.
 
    Default value is NULL.
 
-   Example 1.41. cdr_log_extra example
-modparam("acc", "cdr_log_extra", "c1=$dlg_var(caller);c2=$dlg_var(callee)"
+   Example 1.41. cdr_extra example
+modparam("acc", "cdr_extra", "c1=$dlg_var(caller);c2=$dlg_var(callee)"
+
+6.42. cdr_start_id (string)
+
+   Modifying the start id which is used to store the start time.
+
+   Default value is 'st'
+
+   Example 1.42. cdr_start_id example
+modparam("acc", "cdr_start_id", "start")
+
+6.43. cdr_end_id (string)
+
+   Modifying the end id which is used to store the end time.
+
+   Default value is 'et'
+
+   Example 1.43. cdr_end_id example
+modparam("acc", "cdr_end_id", "end")
+
+6.44. cdr_duration_id (string)
+
+   Modifying the duration id which is used to store the duration.
+
+   Default value is 'd'
+
+   Example 1.44. cdr_duration_id example
+modparam("acc", "cdr_duration_id", "start")
 
 7. Functions
 
@@ -1105,7 +1152,7 @@ modparam("acc", "cdr_log_extra", "c1=$dlg_var(caller);c2=$dlg_var(callee)"
    7.3. acc_rad_request(comment)
    7.4. acc_diam_request(comment)
 
-7.1.  acc_log_request(comment)
+7.1. acc_log_request(comment)
 
    acc_request reports on a request, for example, it can be used to report
    on missed calls to off-line users who are replied 404 - Not Found. To
@@ -1117,44 +1164,46 @@ modparam("acc", "cdr_log_extra", "c1=$dlg_var(caller);c2=$dlg_var(callee)"
 
    This function can be used from ANY_ROUTE.
 
-   Example 1.42. acc_log_request usage
+   Example 1.45. acc_log_request usage
 ...
 acc_log_request("Some comment");
 ...
 
-7.2.  acc_db_request(comment, table)
+7.2. acc_db_request(comment, table)
 
    Like acc_log_request, acc_db_request reports on a request. The report
-   is sent to database at “db_url�, in the table referred to in the second
+   is sent to database at "db_url", in the table referred to in the second
    action parameter.
 
    Meaning of the parameters is as follows:
      * comment - Comment to be appended.
-     * table - Database table to be used.
+     * table - Database table to be used. It can contain config variables
+       that are evaluated at runtime.
 
    This function can be used from ANY_ROUTE.
 
-   Example 1.43. acc_db_request usage
+   Example 1.46. acc_db_request usage
 ...
-acc_log_request("Some comment", "Some table");
+acc_log_request("Some comment", "SomeTable");
+acc_log_request("Some comment", "acc_$time(year)_$time(mon)");
 ...
 
-7.3.  acc_rad_request(comment)
+7.3. acc_rad_request(comment)
 
    Like acc_log_request, acc_rad_request reports on a request. It reports
-   to radius server as configured in “radius_config�.
+   to radius server as configured in "radius_config".
 
    Meaning of the parameters is as follows:
      * comment - Comment to be appended.
 
    This function can be used from ANY_ROUTE.
 
-   Example 1.44. acc_rad_request usage
+   Example 1.47. acc_rad_request usage
 ...
 acc_rad_request("Some comment");
 ...
 
-7.4.  acc_diam_request(comment)
+7.4. acc_diam_request(comment)
 
    Like acc_log_request, acc_diam_request reports on a request. It reports
    to the configured Diameter server.
@@ -1164,7 +1213,7 @@ acc_rad_request("Some comment");
 
    This function can be used from ANY_ROUTE.
 
-   Example 1.45. acc_diam_request usage
+   Example 1.48. acc_diam_request usage
 ...
 acc_diam_request("Some comment");
 ...
@@ -1180,55 +1229,55 @@ Chapter 2. Frequently Asked Questions
 
    2.1.
 
-       What happend with old log_fmt parameter
+   What happend with old log_fmt parameter
 
-       The parameter became obsolete with the restructure of the data logged
-       by ACC module (refer to the Overview chapter). For similar behaviour
-       you can use the extra accouting (see the coresponding chapter).
+   The parameter became obsolete with the restructure of the data logged
+   by ACC module (refer to the Overview chapter). For similar behaviour
+   you can use the extra accouting (see the coresponding chapter).
 
    2.2.
 
-       What happend with old multi_leg_enabled parameter
+   What happend with old multi_leg_enabled parameter
 
-       The parameter becaome obsolete by the addition of the new
-       multi_leg_info parameter. The multi-leg accouting is automatically
-       enabled when multi_leg_info is defined.
+   The parameter becaome obsolete by the addition of the new
+   multi_leg_info parameter. The multi-leg accouting is automatically
+   enabled when multi_leg_info is defined.
 
    2.3.
 
-       What happend with old src_leg_avp_id and dst_leg_avp_id parameters
+   What happend with old src_leg_avp_id and dst_leg_avp_id parameters
 
-       The parameter was replaced by the more generic new parameter
-       multi_leg_info. This allows logging (per-leg) of more information than
-       just dst and src.
+   The parameter was replaced by the more generic new parameter
+   multi_leg_info. This allows logging (per-leg) of more information than
+   just dst and src.
 
    2.4.
 
-       Where can I find more about Kamailio?
+   Where can I find more about Kamailio?
 
-       Take a look at http://www.kamailio.org/.
+   Take a look at http://www.kamailio.org/.
 
    2.5.
 
-       Where can I post a question about this module?
+   Where can I post a question about this module?
 
-       First at all check if your question was already answered on one of our
-       mailing lists:
-         * User Mailing List -
-           http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-users
-         * Developer Mailing List -
-           http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-dev
+   First at all check if your question was already answered on one of our
+   mailing lists:
+     * User Mailing List -
+       http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-users
+     * Developer Mailing List -
+       http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-dev
 
-       E-mails regarding any stable Kamailio release should be sent to
-       <[email protected]> and e-mails regarding development
-       versions should be sent to <[email protected]>.
+   E-mails regarding any stable Kamailio release should be sent to
+   <[email protected]> and e-mails regarding development
+   versions should be sent to <[email protected]>.
 
-       If you want to keep the mail private, send it to
-       <[email protected]>.
+   If you want to keep the mail private, send it to
+   <[email protected]>.
 
    2.6.
 
-       How can I report a bug?
+   How can I report a bug?
 
-       Please follow the guidelines provided at:
-       http://sip-router.org/tracker.
+   Please follow the guidelines provided at:
+   http://sip-router.org/tracker.

modules_k/acc/doc/acc_admin.xml

@@ -853,7 +853,8 @@ modparam("acc", "db_missed_flag", 3)
 	<section>
 		<title><varname>db_table_acc</varname> (string)</title>
 		<para>
-		Table name of accounting successfull calls -- database specific.
+		Table name of accounting successfull calls -- database specific. It
+		can contain config variables that will be evaluated at runtime.
 		</para>
 		<para>
 		Default value is <quote>acc</quote>
@@ -862,13 +863,15 @@ modparam("acc", "db_missed_flag", 3)
 		<title>db_table_acc example</title>
 		<programlisting format="linespecific">
 modparam("acc", "db_table_acc", "myacc_table")
+modparam("acc", "db_table_acc", "acc_$time(year)_$time(mon)")
 </programlisting>
 		</example>
 	</section>
 	<section>
 		<title><varname>db_table_missed_calls</varname> (string)</title>
 		<para>
-		Table name for accounting missed calls -- database specific.
+		Table name for accounting missed calls -- database specific. It
+		can contain config variables that will be evaluated at runtime.
 		</para>
 		<para>
 		Default value is <quote>missed_calls</quote>
@@ -1283,7 +1286,8 @@ acc_log_request("Some comment");
 			<para><emphasis>comment</emphasis> - Comment to be appended.</para>
 		</listitem>
 		<listitem>
-			<para><emphasis>table</emphasis> - Database table to be used.</para>
+			<para><emphasis>table</emphasis> - Database table to be used. It
+			can contain config variables that are evaluated at runtime.</para>
 		</listitem>
 		</itemizedlist>
 		<para>
@@ -1293,7 +1297,8 @@ acc_log_request("Some comment");
 		<title>acc_db_request usage</title>
 		<programlisting format="linespecific">
 ...
-acc_log_request("Some comment", "Some table");
+acc_log_request("Some comment", "SomeTable");
+acc_log_request("Some comment", "acc_$time(year)_$time(mon)");
 ...
 </programlisting>
 		</example>