acc_db 7 acc_db Transaction Accounting into a Database The acc_db SER module stores information about processed SIP transactions in a database. Unlike most other modules, acc_db is normally not used by calling one of its functions. Instead, it is invoked by setting a certain flag and then starting a transaction by calling a function from the tm module, usually t_relay. There are two flags. Their names are determined by the module parameters log_flag and log_missed_flag respectively. The former is intended to be used for all transactions that are involved in a successfully established call. If the flag is set, information on the transaction (an "accounting entry") is written to the database table given by the parameter acc_table. The second flag is to be used for transactions of a failed call attempt. Information on transactions for which this flag is set are then written to the table given by the mc_table (for "missed calls table") parameter. Neither flag is set by default. In order to activate the writing of accounting entries, you have to explicitely choose flags by setting the module parameters. Normally, you can use the same flag for both parameters since acc_db's internal logic takes care of distinguishing between the two tables. It only writes an accounting entry to the acc_table if the transaction ended with a final response sent upstream with a 2xx status, ie., was successful. Likewise, the module only writes to the mc_table if the final response sent upstream had a status of 300 or up. If you want to write all accounting entries into one table, you either give the same table name two both acc_table and mc_table or set the module parameter failed_transactions to yes. The latter causes the restriction on acc_table to be lifted and entries to be written regardless of the status code of the final response. Note that the acc_db module only writes accounting entries for individual transactions. A call usually consists at least of an INVITE and a BYE transaction for the start and end of a call. Searching the accounting records for the call and translating them into call detail records is not performed by the module. Allowed in request and failure processing. The acc_db_log() forces acc_db to write information taken from the currently processed request into the database table determined by the parameter acc_table. If the argument status is given, it contains the status code that should be stored in the field sip_status. If it is missing, the field will be set to 0. Allowed in request and failure processing. The acc_db_missed() forces acc_db to write information taken from the currently processed request into the database table determined by the parameter mc_table. If the argument status is given, it contains the status code that should be stored in the field sip_status. If it is missing, the field will be set to 0. string acc The acc_table parameter sets the name of the database table into which information for successfully established calls should be written. Transaction belonging to such a call are indicated by the flag named through the parameter log_flag being set. string "" The attrs parameter contains a comma separated list of those attributes whose values should be written to the database. See the description of the field attrs for information on how these values are stored in the database. string "attrs" The attrs_column parameter contains the name of the database column for the attrs field. string "sip_callid" The callid_column parameter contains the name of the database column for the sip_callid field. string "sip_cseq" The cseq_column parameter contains the name of the database column for the sip_cseq field. string mysql://ser:heslo@localhost/ser The db_url parameter contains the URL used to connect to the database. The scheme identifies the database module in use. Check the reference for the database you intend to use for more information. string "digest_realm" The digrealm_column parameter contains the name of the database column for the digest_realm field. string "digest_username" The diguser_column parameter contains the name of the database column for the digest_user field. boolean no The early_media parameter determines, whether the arrival of a reponse 183 (Session Progress) should trigger the writing of information, too. If the parameter is set to yes, a 183 response will be treated as a successful response and information stored in the acc_table if the log_flag is set. boolean no The failed_transactions parameter determines, whether transaction with a final response indicating a failure (ie., status codes of 300 and up) should be accounted too if the log_flag is set. The value of the failed_transactions parameter has no influence on accounting if the log_missed_flag is set, in which case the transaction will be accounted for only if the final response indicates a failure. string "flags" The flags_column parameter contains the name of the database column for the flags field. string "sip_from" The from_column parameter contains the name of the database column for the sip_from field. string from_did The fromdid_column parameter contains the name of the database column for the from_did field. string "from_tag" The fromtag_column parameter contains the name of the database column for the from_tag field. string "from_uid" The fromuid_column parameter contains the name of the database column for the from_uid field. string "from_uri" The fromuri_column parameter contains the name of the database column for the from_uri field. string "in_ruri" The iuri_column parameter contains the name of the database column for the in_ruri field. flag name none The log_flag parameter sets the name of the flag that decides whether information about a succeeeded transaction (ie., one with a final response from the 2xx group) is to be stored in the acc_table. By setting the early_media and failed_transactions to yes setting the log_flag also triggers writing for 183 provisional responses and failed transactions respectively. string "acdfgimnoprstuxDFIMPRSTUX" The log_fmt parameter determines, which information is written to the database. Its value is a string. The various fields described in the section Database Schema below are assigned a letter. If the letter for the field is included in the string, the field will be written. The mapping between letters and fields is as follows: a attr c sip_callid d to_tag f sip_from g flags i in_ruri m sip_method n sip_cseq o out_ruri p src_ip r from_tag t sip_to u digest_username x request_timestamp D to_did F from_uri I from_uid M from_did P src_port R digest_realm S sip_status T to_uri U to_uid X response_timestamp By default, all of the fields are active. flag name none The log_missed_flag parameter determines the flag which control whether information on a failed transaction (ie., one with a final response with status code 300 or up) is to be written to the mc_table table. string missed_calls The mc_table parameter sets the name of the database table where information on transaction for failed call attempts should be stored. string "sip_method" The method_column parameter contains the name of the database column for the sip_method field. string "out_ruri" The ouri_column parameter contains the name of the database column for the out_ruri field. boolean no The report_ack parameter determines, whether a separate accounting entry should be written for the ACK following a 200 OK response. Usually, having the entry for the first transaction is enough and no additional entry is necessary. There is, however, a chance that the ACK does not reach its destination and the call does in fact not start. If you need to know about those cases, you can enable the report_ack parameter and check that there is an ACK for every INVITE. boolean no The report_cancels parameter determines, whether accounting entries should be made for CANCEL transactions. You can recognize a canceled transaction by its status 487 in the sip_status field. Because of this, there is usually no need for the extra entries the CANCEL transaction itself may create. string "request_timestamp" The reqtimestamp_column parameter contains the name of the database column for the request_timestamp field. string "response_timestamp" The restimestamp_column parameter contains the name of the database column for the response_timestamp field. string "server_id" The server_id_column parameter contains the name of the database column for the server_id_column field. string "src_ip" The src_ip_column parameter contains the name of the database column for the src_ip field. string src_port The src_port_column parameter contains the name of the database column for the src_port field. string "sip_status" The status_column parameter contains the name of the database column for the sip_status field. string "sip_to" The to_column parameter contains the name of the database column for the sip_to field. string "to_did" The todid_column parameter contains the name of the database column for the to_did field. string "to_tag" The totag_column parameter contains the name of the database column for the to_tag field. string "to_uid" The touid_column parameter contains the name of the database column for the to_uid field. string "to_uri" The touri_column parameter contains the name of the database column for the to_uri field. INT AUTO_INCREMENT NOT NULL The id field is not directly written to by the acc_db. Instead, as an auto-increment database field, it is set by the database itself and gives every entry its own unique numeric identifier. INT NOT NULL DEFAULT '0' The server_id field will contain the server ID of the SER instance that processed the transaction. This is useful in a cluster of several SER machines. By giving each machine its own server_id you can later determine, which server the accounting entry originated from. VARCHAR(64) The from_uid field will contain the user ID determined for the callee and stored in the $fu.uid attribute or NULL if the attribute was not set. VARCHAR(64) The to_uid field will contain the user ID determined for the caller and stored in the $tu.uid attribute or NULL if the attribute was not set. VARCHAR(64) The to_did field will contain the domain ID determined for the caller's domain and stored in the $td.did attribute or NULL if the attribute was not set. VARCHAR(64) The from_did field will contain the domain ID determined for the callee's domain and stored in the $fd.did attribute or NULL if the attribute was not set. VARCHAR(255) The sip_from field will contain the content of the From header field of the request. VARCHAR(255) The sip_to field will contain the content of the To header field of the request. INT The sip_status field will contain the status code of the final response or, if early_media is set, 183 response transmitted upstream for the transaction. VARCHAR(16) The sip_method field will contain the method of the request. VARCHAR(255) The in_ruri field will contain the Request-URI the request arrived with. VARCHAR(255) The out_ruri field will contain the Request-URI of the winning branch, ie., of that relayed request which caused the final response that was sent upstram. VARCHAR(255) The from_uri field will contain the URI of the From header field of the request. VARCHAR(255) The to_uri field will contain the URI of the To header field of the request. VARCHAR(255) The sip_callid field will contain the content of the Call-ID header field of the request. INT The sip_cseq field will contain the sequence number contained in the CSeq header field of the request. The method in that header field (which should be identical to the method of the request) can be found in the sip_method field. VARCHAR(64) The digest_username field will contain the username used in authenticating the request. If no authentication was done or the authentication failed, the field will be NULL. VARCHAR(255) The digest_realm field will contain the realm used in authenticating the request. If no authentication was done or it failed, the field will be NULL. VARCHAR(128) The from_tag field will contain the value of the tag parameter of the From header field of the request. VARCHAR(128) The to_tag field will contain the value of the tag parameter of the response sent upstream or NULL if the response was missing this parameter. INT UNSIGNED The src_ip field will contain the source IP address of the received request. SMALLINT UNSIGNED The src_port field will contain the source port of the received request. DATETIME NOT NULL The request_timestamp field will contain the date and time when the request was received, ie., when the transaction started. DATETIME NOT NULL The response_timestamp field will contain the date and time when the response was sent upstream, ie. when the transaction ended. INT UNSIGNED NOT NULL DEFAULT '0' The flags field will contain the combined numerical value of the flags that where set for the transaction when the entry was written. The value is determined by treating the flags as a bit field with the flag's number as the number of the corresponding bit. VARCHAR(255) The attrs field will contain the attribute and their values that have been selected for storing with the accounting entry. The field will contain a comma separated list of entries. Each entry will start with the name of the attribute, followed by a colon, followed by its value enclosed in double quotation marks. Which attributes will be in the list is controlled by the attrs module parameter. ser ser.cfg acc_radius acc_syslog tm