mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
412 lines
10 KiB
412 lines
10 KiB
SipCapture Module
|
|
|
|
Alexandr Dubovikov
|
|
|
|
<alexandr.dubovikov@gmail.com>
|
|
|
|
Edited by
|
|
|
|
Alexandr Dubovikov
|
|
|
|
<alexandr.dubovikov@gmail.com>
|
|
|
|
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. hep_capture_on (integer)
|
|
3.8. raw_ipip_capture_on (integer)
|
|
3.9. raw_moni_capture_on (integer)
|
|
3.10. raw_socket_listen (string)
|
|
3.11. raw_interface (string)
|
|
3.12. raw_sock_children (integer)
|
|
3.13. promiscuous_on (integer)
|
|
3.14. raw_moni_bpf_on (integer)
|
|
3.15. capture_node (str)
|
|
|
|
4. MI Commands
|
|
|
|
4.1. sip_capture
|
|
|
|
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. Set hep_capture_on parameter
|
|
1.8. Set raw_ipip_capture_on parameter
|
|
1.9. Set raw_moni_capture_on parameter
|
|
1.10. Set raw_socket_listen parameter
|
|
1.11. Set raw_socket_listen parameter
|
|
1.12. Set raw_sock_children parameter
|
|
1.13. Set promiscous_on parameter
|
|
1.14. Set raw_moni_bpf_on parameter
|
|
1.15. Set capture_node parameter
|
|
|
|
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. hep_capture_on (integer)
|
|
3.8. raw_ipip_capture_on (integer)
|
|
3.9. raw_moni_capture_on (integer)
|
|
3.10. raw_socket_listen (string)
|
|
3.11. raw_interface (string)
|
|
3.12. raw_sock_children (integer)
|
|
3.13. promiscuous_on (integer)
|
|
3.14. raw_moni_bpf_on (integer)
|
|
3.15. capture_node (str)
|
|
|
|
4. MI Commands
|
|
|
|
4.1. sip_capture
|
|
|
|
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. hep_capture_on (integer)
|
|
3.8. raw_ipip_capture_on (integer)
|
|
3.9. raw_moni_capture_on (integer)
|
|
3.10. raw_socket_listen (string)
|
|
3.11. raw_interface (string)
|
|
3.12. raw_sock_children (integer)
|
|
3.13. promiscuous_on (integer)
|
|
3.14. raw_moni_bpf_on (integer)
|
|
3.15. capture_node (str)
|
|
|
|
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".
|
|
|
|
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.
|
|
|
|
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 globaly (on(1)/off(0))
|
|
|
|
Default value is "0".
|
|
|
|
Example 1.6. Set capture_on parameter
|
|
...
|
|
modparam("sipcapture", "capture_on", 1)
|
|
...
|
|
|
|
3.7. hep_capture_on (integer)
|
|
|
|
Parameter to enable/disable capture of HEP (on(1)/off(0))
|
|
|
|
Default value is "0".
|
|
|
|
Example 1.7. Set hep_capture_on parameter
|
|
...
|
|
modparam("sipcapture", "hep_capture_on", 1)
|
|
...
|
|
|
|
3.8. raw_ipip_capture_on (integer)
|
|
|
|
Parameter to enable/disable IPIP capturing (on(1)/off(0))
|
|
|
|
Default value is "0".
|
|
|
|
Example 1.8. Set raw_ipip_capture_on parameter
|
|
...
|
|
modparam("sipcapture", "raw_ipip_capture_on", 1)
|
|
...
|
|
|
|
3.9. 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.9. Set raw_moni_capture_on parameter
|
|
...
|
|
modparam("sipcapture", "raw_moni_capture_on", 1)
|
|
...
|
|
|
|
3.10. 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.10. 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.11. raw_interface (string)
|
|
|
|
Name of the interface to bind on the raw socket.
|
|
|
|
Default value is "".
|
|
|
|
Example 1.11. Set raw_socket_listen parameter
|
|
...
|
|
modparam("sipcapture", "raw_interface", "eth0")
|
|
...
|
|
|
|
3.12. raw_sock_children (integer)
|
|
|
|
Parameter define how many children that must be created to listen the
|
|
raw socket.
|
|
|
|
Default value is "1".
|
|
|
|
Example 1.12. Set raw_sock_children parameter
|
|
...
|
|
modparam("sipcapture", "raw_sock_children", 6)
|
|
...
|
|
|
|
3.13. promiscuous_on (integer)
|
|
|
|
Parameter to enable/disable promiscuous mode on the raw socket. Linux
|
|
only.
|
|
|
|
Default value is "0".
|
|
|
|
Example 1.13. Set promiscous_on parameter
|
|
...
|
|
modparam("sipcapture", "promiscuous_on", 1)
|
|
...
|
|
|
|
3.14. 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.14. Set raw_moni_bpf_on parameter
|
|
...
|
|
modparam("sipcapture", "raw_moni_bpf_on", 1)
|
|
...
|
|
|
|
3.15. capture_node (str)
|
|
|
|
Name of the capture node.
|
|
|
|
Default value is "homer01".
|
|
|
|
Example 1.15. Set capture_node parameter
|
|
...
|
|
modparam("sipcapture", "capture_node", "homer03")
|
|
...
|
|
|
|
4. MI Commands
|
|
|
|
4.1. sip_capture
|
|
|
|
4.1. sip_capture
|
|
|
|
Name: sip_capture
|
|
|
|
Parameters:
|
|
* capture_mode : turns on/off SIP message capturing. Possible values
|
|
are:
|
|
+ on
|
|
+ off
|
|
The parameter is optional - if missing, the command will return the
|
|
status of the SIP message capturing (as string "on" or "off" )
|
|
without changing anything.
|
|
|
|
MI FIFO Command Format:
|
|
:sip_capture:_reply_fifo_file_
|
|
capture_mode
|
|
_empty_line_
|
|
|
|
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.
|
|
|
|
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 sipcapture_create.sql,
|
|
SQL script in the sql folder of sipcapture module as template. You can
|
|
also find the complete database documentation on the project webpage,
|
|
http://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.
|
|
* 2. By default MySQL doesn't support INSERT DELAYED for partitioning
|
|
table. You can patch MySQL (http://bugs.mysql.com/bug.php?id=50393)
|
|
* 3. Mirroring port capturing works only on Linux.
|