Daniel-Constantin Mierla
97568d7132
modules: rebuild of readme files
|
9 ani în urmă | |
|---|---|---|
| .. | ||
| doc | 11 ani în urmă | |
| examples | 11 ani în urmă | |
| sql | 11 ani în urmă | |
| Makefile | 13 ani în urmă | |
| README | 9 ani în urmă | |
| hash_mode.c | 13 ani în urmă | |
| hash_mode.h | 11 ani în urmă | |
| hep.c | 10 ani în urmă | |
| hep.h | 11 ani în urmă | |
| sipcapture.c | 10 ani în urmă | |
| sipcapture.h | 11 ani în urmă | |
README
SipCapture Module
Alexandr Dubovikov
Edited by
Alexandr Dubovikov
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)
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. 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
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)
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. 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.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. 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)
...
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.
Alexandr Dubovikov
Edited by
Alexandr Dubovikov
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)
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. 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
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)
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. 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.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. 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)
...
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.