Introduction

This documents describes how to install and configure a Homer Capture Node, Capture Agents and WebHomer (UI)

Capture Node

The capture server is based on sipcapture module (OpenSIPS/SER/Kamailio) and collects all SIP messages in HEP/IPIP encapsulation protocols from your FreeSWITCHes, SERs, Acme Packet SBC or another capture agents or capturing SIP traffic directly via mirroring or monitoring port. The following capture server example is based on Kamailio. Therefore, you need to download Kamailio 3.2 or the last GIT version:

http://www.kamailio.org/pub/kamailio/latest/src/kamailio-3.2.0_src.tar.gz

git clone --depth 1 git://git.sip-router.org/sip-router kamailio

1. check if you have libmysql and mysql headers, needed to compile db_mysql and after it do:
• make FLAVOUR=kamailio cfg
• make modules-cfg include_modules="db_mysql sipcapture"
• make modules
• make install
2. copy the example kamailio.cfg from kamailio/modules/sipcapture/examples/ to yours default kamailio's config directory. i.e /usr/local/etc/kamailio/, open it and change:

     # here should be your ip and port on which the capture server listen on 
     listen=udp:192.168.0.1:9060 

     # credentials to access mysql db, where all messages collected 
     modparam("sipcapture", "db_url", "mysql://homer_user:homer_password@localhost/homer_db")  

    # if you have more then one node set capture_node name          
    # this name will be used in mysql, field node
    modparam("sipcapture", "capture_node", "homer03")

    #activate HEP capturing
    modparam("sipcapture", "hep_capture_on", 1)

3. if you plan to capture IP proto 4 packets (IPIP encapsulation) from your Acme Packet SBC, set:

   /* activate IPIP capturing */
   modparam("sipcapture", "raw_ipip_capture_on", 1)
   /* children for raw socket.*/
   modparam("sipcapture", "raw_sock_children", 4)

4. if you plan to capture a mirroring/monitoring port (raw SIP), set:

   /* activate monitoring/mirroring port capturing */
    modparam("sipcapture", "raw_moni_capture_on", 1)
   /* children for raw socket.*/
   modparam("sipcapture", "raw_sock_children", 4)
   /* Listening IP and port or portrange 5060-5090 */
   modparam("sipcapture", "raw_socket_listen", "192.168.0.1:5060")
   /* OR Name of interface to bind on raw socket */
   modparam("sipcapture", "raw_interface", "eth0")
   /* Promiscious mode RAW socket. Mirroring port. Linux only */
   modparam("sipcapture", "promiscious_on", 1)

5. Your kamailio's routing scripts should looks like:

# Main SIP request routing logic
# - processing of any incoming SIP request starts with this route
route {
        #For example, you can capture only needed methods...
        if (method =~ "^(INVITE|UPDATE|NOTIFY|SUBSCRIBE|OPTIONS|REGISTER)") {
                sip_capture();
        }
        exit;
}

onreply_route {
        #And replies of request methods
        #if(status =~ "^(1[0-9][0-9]|[3[0-9][0-9]|4[0-9]|[56][0-9][0-9])") {
        if($rm =~ "^(INVITE|UPDATE|NOTIFY|SUBSCRIBE|OPTIONS|REGISTER)") {
                sip_capture();
        }
        drop;
}

or collect all REQUESTS and METHODS:

route {
       sip_capture();
       drop;
}
onreply_route {
       sip_capture();
       drop;
}

6. Make sure your config has these lines:

       loadmodule "db_mysql.so"
       loadmodule "sipcapture.so"

and if you want to setup filtering like in the block #5 , you need to load "pv.so" module:

     loadmodule "pv.so"

7. create mysql DB with http://code.google.com/p/homer/source/browse/sql/create_sipcapture.sql from sql directory in Homer's git, or use "create_unixtimestamp.sql" from kamailio: modules/sipcapture/sql
8. Setup the mysql user, that you have defined in your kamailio.cfg as db_url
9. Now you can start kamailio as capture node. At first check if your modules are installed. In case if you don't have mysql.h or libmysql, you will see an exception during db_mysql compilation. Check if kamailio config is ok and all modules are compiled:

  /usr/local/sbin/kamailio -c 

if no errors, start kamailio in capture mode

  /usr/local/sbin/kamctl start

or use the init script

Table rotation

You need to setup crontab script or mySQL event to create a new partition for the next day/hour and drop the old partitons - choose according to your partitioning method day/hour. Please set crontab to run script daily (e.g. 04:00 AM) (partrotate_unixtimestamp.pl from homer/scripts directory)

Congratulations! If you performed all steps without issues, your system is now ready to start capturing SIP/HEP/IPIP traffic as configured!

TO DEBUG ANY ISSUE please see the: Homer FAQ and Mailing-List

For additional details, follow the README file of sipcapture module or the specific examples

Capture Agent

If you are user of FreeSWITCH, OpenSIPs or Kamailio use internal/build-in HEP capture agents. ACME SBC and HAUWEI SBC users can use internal IPIP/Proto4/RFC 2003 capture agents.

FreeSWITCH

open sofia.conf.xml and set capture-server param

<param name="capture-server" value="udp:192.168.0.1:9060"/>

the ip address and port must be same as the listen param in your kamailio.cfg

open internal.xml and change sip-capture param to "yes"

<param name="sip-capture" value="yes"/>

in case if you don't want to activate capturing process on start, use CLI commands:

freeswitch@fsnode04> sofia global capture on
 
+OK Global capture on
freeswitch@fsnode04> sofia global capture off
 
+OK Global capture off
freeswitch@fsnode04>

or activate capturing only for one profile:

freeswitch@fsnode04> sofia profile internal capture on
 
Enabled sip capturing on internal

freeswitch@fsnode04> sofia profile internal capture off
 
Disabled sip capturing on internal
 

Kamailio

At first compile siptrace module and cofigure this module in your kamailio.cfg:

loadmodule "siptrace.so"

# check IP and port of your capture node
modparam("siptrace", "duplicate_uri","sip:192.168.0.1:9060");
modparam("siptrace", "hep_on",1);
modparam("siptrace", "trace_to_database","0");
modparam("siptrace", "trace_flag",22);
modparam("siptrace", "trace_on", 1);

For additional details, follow the README file of siptrace module or the specific examples

ACME SBC

ACME "packet-trace" command can capture RFC 2003 (IP to IP encapsulated) SIP signaling on the Net-Net SBC and natively mirror it to Homer SIP Capture server. To configure, we need to create a capture receiver:

capture-receiver
        state               enabled
        ip-address          192.168.0.1
        network-interface   m00:0
        last-modified-by    engineer@192.168.30.1
        last-modified-date  2011-10-10 00:00:01

or

packet-trace-config < state | address | network-interface | select| no | show | done | exit>

The "packet-trace" command can now start packet tracing on the Net-Net SBC and duplicate all packets sent to and from theendpoint identified by the IP address on the specified Net-Net SBC network interface:

#packet-trace start Access:0 192.168.30.5 5060 5060

If you access and network side present different CALLID breaking call-flow correlation, use HDR and add X-CID: (callid from A-leg) into INVITE in your B-leg.

Homer Capture Agent (for all other unsupported system)

if your SIP system (PBX, proxy) doesn't have a built-in capture agent with HEP or IPIP encapsulation support, you can use Homer Capture Agent (captagent). This is an external application (daemon) that collect SIP messages thru PCAPlib and send them to your capture server. The captagent support IPv4 and IPv6.

Limitation: unfortunately, the agent works only with UDP/SIP. In case TCP/SIP, you can get retransmit packets.

captagent -p 9060 -s 192.168.0.1 -r 5060-5080

Usage:

usage: captagent <-mvhn> <-d dev> <-s host> <-p port>
             <-P pid file> <-r port|portrange> <-c config file>
   -h  is help/usage
   -v  is version information
   -m  is don't go into promiscuous mode
   -n  is don't go into background
   -d  is use specified device instead of the pcap default
   -D  is use specified pcap file instead of a device
   -s  is the capture server
   -p  is use specified port of capture server
   -f  is the file with specific pcap filter
   -r  is open specified capturing port or portrange instead of the default (5060)
   -P  is open specified pid file instead of the default (/var/run/captagent.pid)

Tips:

• -p the port number where your capture server listen on. By default it must be 9060.
• -r normaly it's 5060, but you can use ports range 5060-5090 too.
• -s this param can be or IP address or FQDN.
• -f the filter in the file must start from "or" or "and" . I.E. "and not dst host 10.0.0.1", "or udp port 5090". Check PCAP syntax for it
• -D to load data from a PCAP file instead of a device (NEW!)

Web Interface

The web interface (webHomer) is a separate application which allows admins and users to search, display and interact with all SIP messages captured by homer server and generate callflow diagrams and pcap files natively (Screenshots: http://code.google.com/p/homer/wiki/Webinterface)

Minimal LAMP Requirements:

1. webserver with PHP support (Apache, LightHTTPD)
2. PHP5.2+ (w/ PHP-GD, JSON)
3. MySQL 5.1.48+ (or other DB via PDO) for:
• local user authorization
• nodes & hosts information
• statistics & activity history

Clone webHomer from GIT:

git clone https://code.google.com/p/homer/

Copy the included /webhomer folder to your preferred location (ie:/var/www/webhomer) and assign the ownership of the folder tree according to your system requirements.

Next create a new MySQL database and fill it with homer_users.sql (from webhomer/sql) and create a mysql user with full access. The Application needs to access this database as well as the SIP capture database. For this purpose, two example configuration files are provided (configuration_example.php and preferences_example.php) that need to be filled in and renamed before use. Insert the minimum DB access details in "configuration.php":

/* Access db of homer users */
define(HOST, "localhost");
define(USER, "root");
define(PW, "password");
define(DB, "homer_users");

Also define username and password for HOMER SIP Capture DB. This user must be defined in all your nodes DB. Don't forget to insert all your database nodes into homer_nodes table. Configure the proper details in "configuration.php":

/* Homer connection 
*  this user must have the same password for all Homer nodes
*  please define all your nodes in homer_nodes table
*/

define(HOMER_HOST, "localhost"); /* DEFAULT. Don't forget insert this host to your DB nodes table */
define(HOMER_USER, "homer_users");
define(HOMER_PW, "homer_password");
define(HOMER_DB, "homer_db");
define(HOMER_TABLE, "sip_capture");

The application needs a temporary folder to store its generated files. Configure full write permissions to the /tmp folder inside webHomer, and configure the following parameters accordingly in "configuration.php":

PCAPDIR - this directory will be used to store temporary pcap files and call flow SVG/HTMLs. Must be absolute path and must reflect the location of the webhomer folder from GIT. THIS FOLDER MUST BE WRITEABLE!

WEBPCAPLOC - web location of PCAPDIR (must reflect webserver /)

/* Settings 
*
*/

/* here */
define(PCAPDIR,"/var/www/webhomer/tmp/");
define(WEBPCAPLOC,"/webhomer/tmp/");
define(APILOC,"/webhomer/api/");

A number of customizable, non critical parameters such as timezones and modules, and user interface preferences are set separately in "preferences.php" - rename the example file and set your preferences accordingly.

Statistics

To enable statistics, add the required tables to homer_db using " statistics.sql" from webhomer/sql and enable MODULES in configuration.php

define(MODULES,1);

Statistics Collection Script

You need to setup crontab script for statistic data collection. Please set crontab to run script (e.g. every 5 minutes) (edit DB AUTH details and use statistic.pl from homer/scripts directory)

For example put the following line into crontab file:

*/5 *    * * *   root    /usr/sbin/statistic.pl

If you still have a problem with Homer, check our FAQ and if your question has not been answered there, contact us, we will be glad to help you