===== Module acc_db =====
The module **acc_db** allows to store the result of transactions into a database. It thus provides the basis for an accounting system. The modules **[[acc_radius]]** and **[[acc_syslog]]** are alternatives that provide the same function for different storage systems.
* [[#Requirements]]
* [[#Usage]]
* [[#Functions]]
* [[#Module Parameters]]
==== Requirements ====
The module **acc_db** requires that the module **[[tm]]** is loaded as well as the appropriate module for the database referenced in the **[[acc_db#db_url|db_url]]** module
parameter.
==== Usage ====
The module **acc_db*** works differently than most other modules in that you do not have to explicitly call functions provided by the module. Instead, whenever a certain flag is set, information for the transaction is saved into the database when the transaction finishes.
There are two flags, set by the module parameters **[[acc_db#log_flag|log_flag]]** and **[[acc_db#log_missed_flag|log_missed_flag]]**. The only difference between is the database table the transaction will be stored in, defined by the parameters **[[acc_db#acc_table|acc_table]]** and **[[acc_db#mc_table|mc_table]]** respectively. While the name suggests that you should store successful calls in the former and missed calls in the latter, there is no necessity to do so. Note, however, that SERweb picks up on this distinction.
Alternatively, information from the request currently processed can be stored explicitly by calling the various functions of the module.
//XXX Either bring an example or reference the respective section in the User's Manual//
==== Functions ====
=== acc_db_log() ===
| Syntax: | ''acc_db_log ( [//status//] )'' |
| allowed in: | request routes, failure routes |
The function **acc_db_log()** writes information from the request currently being processed into the database table for successful calls. The optional //status// parameters specifies the value to be assumed for the status column. Since the transaction is not yet finished, this value is yet unknown. If the parameters is left out, 0 is written.
=== acc_db_missed() ===
| Syntax: | ''acc_db_missed ( [//status//]] )'' |
| allowed in: | request routes, failure routes |
The function **acc_db_missed()** writes information from the request currently being processed into the database table for missed calls. The optional //status// parameters specifies the value to be assumed for the status column. Since the transaction is not yet finished, this value is yet unknown. If the parameters is left out, 0 is written.
==== Module Parameters ====
=== early_media ===
| Type: | boolean |
| Default: | false |
The **early_media** parameter defines whether a separate entry should be written to the database whenever a response 183 (Session Progress) is received. Through this, the presence and start of early media can be determined.
=== failed_transactions ===
| Type: | boolean |
| Default: | false |
The **failed_transactions** parameter determines, whether failed transactions should be accounted for, too. If the parameter remains at its default false, only transactions with a resulting status code of 200 (OK) are being written to the database.
=== report_ack ===
| Type: | boolean |
| Default: | true |
The **report_ack** parameter determines, whether a separate entry should be written for the ACK message in response to a 200 (OK) in an INVITE transaction. This will only work if the original INVITE was marked for record routing by use of the **[[rr#record_route()|record_route()]]** function.
=== report_cancels ===
| Type: | boolean |
| Default: | false |
The **report_cancels** parameter determines, whether CANCEL transactions sent to stop processing of an INVITE request should be accounted for separately. Usually, this is not necessary, as you can determine a canceled INVITE from the status code 487 (Request Terminated).
=== log_flag ===
| Type: | flag number or name |
| Default: | 0 (meaning "off") |
The **log_flag** parameter determines the flag that needs to be set upon the termination of a transaction to store information about this transaction in the database table determined by the **[[acc_db#acc_table|acc_table]]** parameter. This can either be the number of a flag or its name. If the parameter is set to 0, accounting into the **acc_table** is turned off.
=== log_missed_flag ===
| Type: | flag number or name |
| Default: | 0 (meaning "off") |
The **log_missed_flag** parameter determines the flag that needs to be set upon the termination of a transaction to store information about this transaction in the database table determined by the **[[acc_db#mc_table|mc_table]]** parameter. This can either be the number of a flag or its name. If the parameter is set to 0, accounting into the **acc_table** is turned off.
=== log_fmt ===
| Type: | string |
| Default: | "acdfgimnoprtuxDFIMPRSTUX" (ie., all) |
The **log_fmt** parameter determines, which information about the transaction should be stored in the database. It consists of a string of characters, each of which represents a certain piece of information. If a character is present, the information will be stored in the certain column. For each character there is a module parameter to set the name of the column. The following table maps the character to the column and also gives the default name for the column. More details can be found with the respective parameters.
^ Character ^ Parameter ^ Default ^ Content ^
| a | **[[acc_db#attrs_column]]** | attrs | attributes of the transaction |
| c | **[[acc_db#callid_column]]** | sip_callid | Call-ID |
| d | **[[acc_db#totag_column]]** | to_tag | To tag |
| f | **[[acc_db#from_column]]** | sip_from | complete From header field |
| g | **[[acc_db#flags_column]]** | flags | flags set for the transaction |
| i | **[[acc_db#iuri_column]]** | in_ruri | original, unchanged Request-URI |
| m | **[[acc_db#method_column]]** | sip_method | method of the request |
| n | **[[acc_db#cseq_column]]** | sip_cseq | number of the CSeq header field |
| o | **[[acc_db#ouri_column]]** | out_ruri | Request-URI of the request sent on |
| p | **[[acc_db#src_ip_column]]** | src_ip | source IP address of the incoming request |
| r | **[[acc_db#fromtag_column]]** | from_tag | From tag |
| u | **[[acc_db#diguser_column]]** | digest_username | username from authentication |
| x | **[[acc_db#reqtimestamp_column]]** | request_timestamp | time stamp of the incoming request |
| D | **[[acc_db#todid_column]]** | to_did | Domain ID of the target domain |
| F | **[[acc_db#fromuri_column]]** | from_uri | URI of the From header field |
| I | **[[acc_db#fromuid_column]]** | from_uid | User ID of the "caller" |
| M | **[[acc_db#fromdid_column]]** | from_did | Domain ID for the "caller" |
| P | **[[acc_db#src_port_column]]** | src_port | source port of the incoming request |
| R | **[[acc_db#digrealm_column]]** | digest_realm | realm from authentication |
| S | **[[acc_db#status_column]]** | sip_status | status code of the "winning" response |
| T | **[[acc_db#touri_column]]** | to_uri | URI of the To header field |
| U | **[[acc_db#touid_column]]** | to_uid | User ID of the "callee" |
| X | **[[acc_db#restimestamp_column]]** | response_timestamp | time stamp of the outgoing response |
=== attrs ===
| Type: | string |
| Default: | %%""%% |
The **attrs** parameter contains a comma separated list of the names of the attributes that should be stored in the column determined by the **[[acc_db#attrs_column]]** parameter. The names must include the dollar sign.
=== db_url ===
| Type: | database URL |
| Default: | %%"mysql://ser:heslo@localhost/ser"%% |
The **db_url** parameter determines the database information should be written to.
//XXX Reference where these database URLs are explained.//
=== acc_table ===
| Type: | string |
| Default: | %%"acc"%% |
The **acc_table** parameter determines the name of the database table information on transactions marked with the flag set by the **[[acc_db#log_flag]]** parameter are to be stored in.
=== mc_table ===
| Type: | string |
| Default: | %%"missed_calls"%% |
The **mc_table** parameter determines the name of the database table information on transactions marked with the flag set by the **[[acc_db#log_missed_flag]]** parameter are to be stored in.
=== attrs_column ===
| Type: | string |
| Default: | %%"attrs"%% |
The **attrs_column** parameter sets the name of the database column for the attributes of the transaction.
Only attributes included in the **[[acc_db#attrs]]** parameter are stored. These attributes are stored as a string. Individual attributes are separated by a comma, name and value of the attribute itself are separated by a colon.
For example, if the **attrs** parameter was set to
modparam ("acc_db", "attrs", "foo,bar")
the content the column for one specific transaction might look like this:
foo:12,bar:Buzz
//XXX Or is there some quoting involved?//
=== callid_column ===
| Type: | string |
| Default: | %%"sip_callid"%% |
The **callid_column** parameter sets the name of the database column the content of the Call-ID header field of the request processed will be stored in.
=== totag_column ===
| Type: | string |
| Default: | %%"to_tag"%% |
The **totag_column** parameter sets the name of the database column the value of the Tag paramer of the To header field will be stored in.
=== from_column ===
| Type: | string |
| Default: | %%"sip_from"%% |
The **from_column** parameter sets the name of the database column the full content of the From header field will be stored in.
=== flags_column ===
| Type: | string |
| Default: | %%"flags"%% |
The **flags_column** parameter sets the name of the database column the value of the flags set for the transaction will be stored in.