From ef40fe7d15161585ea552f75bbe588bd7bd66799 Mon Sep 17 00:00:00 2001 From: Kamailio Dev Date: Sun, 5 Nov 2017 08:46:38 +0100 Subject: [PATCH] modules: readme files regenerated - sipcapture ... [skip ci] --- src/modules/sipcapture/README | 559 ---------------------------------- 1 file changed, 559 deletions(-) diff --git a/src/modules/sipcapture/README b/src/modules/sipcapture/README index bc3360580ff..139597f9cb0 100644 --- a/src/modules/sipcapture/README +++ b/src/modules/sipcapture/README @@ -1,561 +1,2 @@ -SipCapture Module -Alexandr Dubovikov - - -Edited by - -Alexandr Dubovikov - - - - Copyright © 2011-15 SIPCAPTURE ORG - - Copyright © 2011 QSC AG - - Copyright © 2011 http://www.qsc.de - __________________________________________________________________ - - Table of Contents - - 1. Admin Guide - - 1. Overview - 2. Dependencies - - 2.1. Kamailio Modules - 2.2. External Libraries or Applications - - 3. Parameters - - 3.1. db_url (str) - 3.2. table_name (str) - 3.3. mt_mode (str) - 3.4. hash_source (str) - 3.5. db_insert_mode (integer) - 3.6. capture_on (integer) - 3.7. capture_mode (integer) - 3.8. hep_capture_on (integer) - 3.9. raw_ipip_capture_on (integer) - 3.10. raw_moni_capture_on (integer) - 3.11. raw_socket_listen (string) - 3.12. raw_interface (string) - 3.13. raw_sock_children (integer) - 3.14. promiscuous_on (integer) - 3.15. raw_moni_bpf_on (integer) - 3.16. capture_node (str) - 3.17. insert_retries (integer) - 3.18. insert_retry_timeout (integer) - 3.19. callid_aleg_header (str) - 3.20. topoh_unmask (int) - 3.21. nonsip_hook (int) - - 4. Functions - - 4.1. sip_capture([table]) - 4.2. report_capture([table],[data]) - - 5. RPC Commands - - 5.1. sipcapture.status param - - 6. Database setup - 7. Limitations - - List of Examples - - 1.1. Set db_url parameter - 1.2. Set sip_capture parameter - 1.3. Set mt_mode parameter - 1.4. Set mt_mode parameter - 1.5. db_insert_mode example - 1.6. Set capture_on parameter - 1.7. capture_mode example - 1.8. Set hep_capture_on parameter - 1.9. Set raw_ipip_capture_on parameter - 1.10. Set raw_moni_capture_on parameter - 1.11. Set raw_socket_listen parameter - 1.12. Set raw_interface parameter - 1.13. Set raw_sock_children parameter - 1.14. Set promiscous_on parameter - 1.15. Set raw_moni_bpf_on parameter - 1.16. Set capture_node parameter - 1.17. Set insert_retries parameter - 1.18. Set insert_retry_timeout parameter - 1.19. Set callid_aleg_header parameter - 1.20. Set topoh_unmask parameter - 1.21. Set nonsip_hook parameter - 1.22. sip_capture() usage - 1.23. report_capture() usage - -Chapter 1. Admin Guide - - Table of Contents - - 1. Overview - 2. Dependencies - - 2.1. Kamailio Modules - 2.2. External Libraries or Applications - - 3. Parameters - - 3.1. db_url (str) - 3.2. table_name (str) - 3.3. mt_mode (str) - 3.4. hash_source (str) - 3.5. db_insert_mode (integer) - 3.6. capture_on (integer) - 3.7. capture_mode (integer) - 3.8. hep_capture_on (integer) - 3.9. raw_ipip_capture_on (integer) - 3.10. raw_moni_capture_on (integer) - 3.11. raw_socket_listen (string) - 3.12. raw_interface (string) - 3.13. raw_sock_children (integer) - 3.14. promiscuous_on (integer) - 3.15. raw_moni_bpf_on (integer) - 3.16. capture_node (str) - 3.17. insert_retries (integer) - 3.18. insert_retry_timeout (integer) - 3.19. callid_aleg_header (str) - 3.20. topoh_unmask (int) - 3.21. nonsip_hook (int) - - 4. Functions - - 4.1. sip_capture([table]) - 4.2. report_capture([table],[data]) - - 5. RPC Commands - - 5.1. sipcapture.status param - - 6. Database setup - 7. Limitations - -1. Overview - - The sipcapture module stores incoming/outgoing SIP messages in - database. - - Kamailio can capture SIP messages in three modes - * IPIP encapsulation. (ETHHDR+IPHDR+IPHDR+UDPHDR). - * Monitoring/mirroring port. - * Homer encapsulation protocol mode (HEP v1, v2, v3). - - The capturing can be turned on/off using mi or rpc commands. Example: - - kamctl fifo sip_capture on - - kamctl fifo sip_capture off - -2. Dependencies - - 2.1. Kamailio Modules - 2.2. External Libraries or Applications - -2.1. Kamailio Modules - - The following modules must be loaded before this module: - * database module - mysql, postrgress, dbtext, unixodbc... - -2.2. External Libraries or Applications - - The following libraries or applications must be installed before - running Kamailio with this module loaded: - * None. - -3. Parameters - - 3.1. db_url (str) - 3.2. table_name (str) - 3.3. mt_mode (str) - 3.4. hash_source (str) - 3.5. db_insert_mode (integer) - 3.6. capture_on (integer) - 3.7. capture_mode (integer) - 3.8. hep_capture_on (integer) - 3.9. raw_ipip_capture_on (integer) - 3.10. raw_moni_capture_on (integer) - 3.11. raw_socket_listen (string) - 3.12. raw_interface (string) - 3.13. raw_sock_children (integer) - 3.14. promiscuous_on (integer) - 3.15. raw_moni_bpf_on (integer) - 3.16. capture_node (str) - 3.17. insert_retries (integer) - 3.18. insert_retry_timeout (integer) - 3.19. callid_aleg_header (str) - 3.20. topoh_unmask (int) - 3.21. nonsip_hook (int) - -3.1. db_url (str) - - Database URL. - - Default value is "". - - Example 1.1. Set db_url parameter -... -modparam("sipcapture", "db_url", "mysql://user:passwd@host/dbname") -... - -3.2. table_name (str) - - Name of the table's name used to store the SIP messages. Can contain - multiple tables, separated by "|". - - Default value is "sip_capture". Only for Homer 3. For Homer 5, please - use an argument for the sip_capture function. - - Example 1.2. Set sip_capture parameter -... -modparam("sipcapture", "table_name", "homer_capture") -... -modparam("sipcapture", "table_name", "homer_capture1|homer_capture2"); -... - -3.3. mt_mode (str) - - Name of the mode used for storing data in multiple tables. Modes can be - "rand" (random), "round_robin" (use a round_robin algorithm) or "hash" - (use hashing to determine the table to store). These modes are only - triggered if there is more than one table specified in table_name - parameter, separated by "|". - - Default value is "rand". - - Example 1.3. Set mt_mode parameter -... -modparam("sipcapture", "mt_mode", "hash") -... - -3.4. hash_source (str) - - The field of the SIP message used for hashing, when mt_mode is set to - "hash". The value can be "call_id", "to_user" or "from_user". - - Default value is "call_id". - - Example 1.4. Set mt_mode parameter -... -modparam("sipcapture", "hash_source", "to_user") -... - -3.5. db_insert_mode (integer) - - If set to 1, use INSERT DELAYED to store sip message into capture table - when the DB driver has support for it. If no INSERT DELAYED support is - offered by DB driver, then standard INSERT is used. - - If set to 2, use ASYNC INSERT to store sip message into capture table - when the DB driver has support for it. If no ASYNC INSERT support is - offered by DB driver, then standard INSERT is used. - - Default value is 0 (no INSERT DELAYED). - - Example 1.5. db_insert_mode example -modparam("sipcapture", "db_insert_mode", 1) - -3.6. capture_on (integer) - - Parameter to enable/disable capture globally (on(1)/off(0)) - - Default value is "0". - - Example 1.6. Set capture_on parameter -... -modparam("sipcapture", "capture_on", 1) -... - -3.7. capture_mode (integer) - - This parameter can be used for defining a capture mode which can be - used in the sip_capture calls as a parameter. A capture mode has a name - and some parameters. It must be defined in the format: - name=>param1=val1;param2=val2;... The parameters are db_url, - table_name, mt_mode and hash_source (optional). Multiple capture modes - can be defined by using this parameter multiple times. After this, the - capture modes can be used like: sip_capture ("", "CAPTURE_MODE"); - - Example 1.7. capture_mode example -modparam("sipcapture", "capture_mode", "mode1=>db_url=mysql://user:passwd@host/d -bname1;table_name=homer_capture1|homer_capture2;mt_mode=hash;hash_source=call_id -;") -modparam("sipcapture", "capture_mode", "mode2=>db_url=mysql://user:passwd@host/d -bname2;table_name=homer_capture3|homer_capture4;mt_mode=rand;") - -3.8. hep_capture_on (integer) - - Parameter to enable/disable capture of HEP (on(1)/off(0)) - - Default value is "0". - - Example 1.8. Set hep_capture_on parameter -... -modparam("sipcapture", "hep_capture_on", 1) -... - -3.9. raw_ipip_capture_on (integer) - - Parameter to enable/disable IPIP capturing (on(1)/off(0)) - - Default value is "0". - - Example 1.9. Set raw_ipip_capture_on parameter -... -modparam("sipcapture", "raw_ipip_capture_on", 1) -... - -3.10. raw_moni_capture_on (integer) - - Parameter to enable/disable monitoring/mirroring port capturing - (on(1)/off(0)) Only one mode on raw socket can be enabled! Monitoring - port capturing currently supported only on Linux. - - Default value is "0". - - Example 1.10. Set raw_moni_capture_on parameter -... -modparam("sipcapture", "raw_moni_capture_on", 1) -... - -3.11. raw_socket_listen (string) - - Parameter indicate an listen IP address of RAW socket for IPIP - capturing. You can also define a port/portrange for IPIP/Mirroring - mode, to capture SIP messages in specific ports: - - "10.0.0.1:5060" - the source/destination port of the SIP message must - be equal 5060 - - "10.0.0.1:5060-5090" - the source/destination port of the SIP message - must be equal or be between 5060 and 5090. - - The port/portrange must be defined if you are planning to use mirroring - capture! In this case, the part with IP address will be ignored, but to - make parser happy, use i.e. 10.0.0.0 - - Default value is "". - - Example 1.11. Set raw_socket_listen parameter -... -modparam("sipcapture", "raw_socket_listen", "10.0.0.1:5060-5090") -... -modparam("sipcapture", "raw_socket_listen", "10.0.0.1:5060") -... - -3.12. raw_interface (string) - - Name of the interface to bind on the raw socket. - - Default value is "". - - Example 1.12. Set raw_interface parameter -... -modparam("sipcapture", "raw_interface", "eth0") -... - -3.13. raw_sock_children (integer) - - Parameter define how many children that must be created to listen the - raw socket. - - Default value is "1". - - Example 1.13. Set raw_sock_children parameter -... -modparam("sipcapture", "raw_sock_children", 6) -... - -3.14. promiscuous_on (integer) - - Parameter to enable/disable promiscuous mode on the raw socket. Linux - only. - - Default value is "0". - - Example 1.14. Set promiscous_on parameter -... -modparam("sipcapture", "promiscuous_on", 1) -... - -3.15. raw_moni_bpf_on (integer) - - Activate Linux Socket Filter (LSF based on BPF) on the mirroring - interface. The structure is defined in linux/filter.h. The default LSF - accept a port/portrange from the raw_socket_listen param. Currently LSF - supported only on Linux. - - Default value is "0". - - Example 1.15. Set raw_moni_bpf_on parameter -... -modparam("sipcapture", "raw_moni_bpf_on", 1) -... - -3.16. capture_node (str) - - Name of the capture node. - - Default value is "homer01". - - Example 1.16. Set capture_node parameter -... -modparam("sipcapture", "capture_node", "homer03") -... - -3.17. insert_retries (integer) - - The number of times Kamailio should retry to write to the Homer - database in case the first attempt failed. The retry is also limited - timewise by the insert_retry_timeout parameter. Values allowed range - from 0 to 500. - - Default value is 0 (no retries). - - Example 1.17. Set insert_retries parameter -... -modparam("sipcapture", "insert_retries", 5) -... - -3.18. insert_retry_timeout (integer) - - The time limit in seconds Kamailio retries to write to the Homer - database in case the first attempt failed. This parameter is only used - together with the insert_retries parameter. Values allowed range from 0 - to 300. - - Default value is 60 seconds. - - Example 1.18. Set insert_retry_timeout parameter -... -modparam("sipcapture", "insert_retry_timeout", 10) -... - -3.19. callid_aleg_header (str) - - Header name used to correlate A-leg with B-leg. It can take a list of - headers, separated by semicolon, e.g. "X-CID0;X-CID1". First match - wins. - - Default value is "X-CID". - - Example 1.19. Set callid_aleg_header parameter -... -modparam("sipcapture", "callid_aleg_header", "X-CallIDALeg") -... - -3.20. topoh_unmask (int) - - If set to 1, call-id will be unmasked using topoh module api (topoh - module must be loaded in this case). - - Default value is 0. - - Example 1.20. Set topoh_unmask parameter -... -modparam("sipcapture", "topoh_unmask", 1) -... - -3.21. nonsip_hook (int) - - If set to 1, event route sipcapture:siprequest is run when HEP message - is received. - - Default value is 0. - - Example 1.21. Set nonsip_hook parameter -... -modparam("sipcapture", "nonsip_hook", 1) -... - -4. Functions - - 4.1. sip_capture([table]) - 4.2. report_capture([table],[data]) - -4.1. sip_capture([table]) - - Store the current processed HEP/IPIP SIP message in database. It is - stored in the form prior applying changes made to it. - - Meaning of the parameters is as follows: - * table - The table where HEP SIP message will be stored. Homer 5 use - now tables with datestamp. To generate an automatic table's name - please use strftime parameters. I.e. $var(table) = - "sip_capture_call_%Y%m%d" and set the variable as an argument of - the sip_capture function. - - This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, - ONREPLY_ROUTE, BRANCH_ROUTE. - Default value is "NULL". - - Example 1.22. sip_capture() usage -... -sip_capture(); -... -sip_capture("sip_capture_call_20160124"); -... - -4.2. report_capture([table],[data]) - - Store the current processed HEP REPORT message in database. - - Meaning of the parameters is as follows: - * table - The table where REPORT message will be stored. - data - The custom report data. - - This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, - ONREPLY_ROUTE, BRANCH_ROUTE. - Default value is "NULL". - - Example 1.23. report_capture() usage -... -report_capture(); -... -report_capture("report_data"); -... -report_capture("report_data", "{\"MOS\":4.1,\"PACKET_LOST\":100"}); -... - -5. RPC Commands - - 5.1. sipcapture.status param - -5.1. sipcapture.status param - - Name: sipcapture.status - - Parameters: - * on or off: turns on/off SIP message capturing. Possible values are: - + on - + off - * “check” does not change sipcapture status, just reports the current - status. - - RPC Command Format: -... -kamcmd sipcapture.status on -kamcmd sipcapture.status off -kamcmd sipcapture.status check -... - -6. Database setup - - Before running Kamailio with the sipcapture module, you have to setup - the database tables where the module will store the data. For that, if - the table were not created by the installation script or you choose to - install everything by yourself you can use the homer_databases.sql, SQL - script in the sql folder of sipcapture module as template. You can also - find the complete database documentation on the project webpage, - https://www.kamailio.org/docs/db-tables/kamailio-db-devel.html. - -7. Limitations - - * 1. Only one capturing mode on RAW socket is supported: IPIP or - monitoring/mirroring port. Don't activate both at the same time. - Obsolete. Please use HEP mirroring now. - * 2. Mirroring port capturing works only on Linux.