How to monitor VoipNow with Homer

Applies to all VoipNow versions!

HOMER is an open source SIP Capture system which allows you to store and analyze SIP traffic. This article explains how to use Homer to monitor VoipNow.

Photo credits: https://github.com/sipcapture/homer/wiki/Quick-Install

Homer relies on the Capture Node and the Capture Agent.

The Capture Node is where Homer stores the SIP packets. The node comes with a web interface that allows you to filter the calls you need to analyze.

The Capture Agent feeds the capture node with SIP signaling, Logs, RTCP and more, using the HEP protocol (i.e. Homer Encapsulation Protocol). Asterisk and Kamailio natively support HEP through the "res_hep" (Asterisk) and "siptrace" (Kamailio) modules. For the time being, VoipNow's versions of Asterisk or Kamailio are not using these modules. So, for the Capture Agent, you can use port mirroring, Homer's CaptAgent, sngrep or others.

On GitHub, you can find several Homer installation options, but the simplest method is the automated installation. For the time being, the automated install is still listed as "work in progress". This article describes the manual installation successfully tested on CentOS 6 and 7 servers. Here and here you can read more on Homer.

Please note that this is not a copy&paste installation tutorial. Because of the many commands and the installation method which might change over time, it's recommended that you use this article as a guide and check the official website for differences in newer versions.

Step-by-step guide

Cloning repo and installing required rpm's

Clone the Homer repository.

$ git clone -b homer5 https://github.com/sipcapture/homer.git
$ cd homer
$ git submodule init
$ git submodule update

Install the needed rpm's.

yum install httpd mysql-server mysql php php-mysql

Set a root password for mysql:
```
mysqladmin -u root password weltest4PSA
```

Check that InnoDB is supported:

mysql -uroot -pweltest4PSA -e'show engines'

Setting up the HTTP server

Create an Apache virtual host following their example at $GIT/homer-api/examples/web/homer5.apache
Check the DocumentRoot line. If it shows up like this:
```
DocumentRoot /var/www/sipcapture/htdocs
```
Create the /var/www/sipcapture/htdocs and /var/www/sipcapture/htdocs/api directories.
In httpd.conf make sure mode rewrite is enabled if AllowOverride is set to "All".
Copy the homer-ui/* contents in /var/www/sipcapture/htdocs and HOMER-API/api/* contents in /var/www/sipcapture/htdocs/api/
Set recursive ownersip to apache on /var/www/sipcapture/:
```
chown -R apache: /var/www/sipcapture/
```

Setting up MySQL

Create databases, tables and users.

mysql -u root -pweltest4PSA < $GIT/homer-api/sql/homer_databases.sql
mysql -u root -pweltest4PSA < $GIT/homer-api/sql/homer_user.sql
mysql -u root -pweltest4PSA homer_data < $GIT/homer-api/sql/schema_data.sql
mysql -u root -pweltest4PSA homer_configuration < $GIT/homer-api/sql/schema_configuration.sql
mysql -u root -pweltest4PSA homer_statistic < $GIT/homer-api/sql/schema_statistic.sql

When importing "schema_statistic.sql", you might get this error:

"ERROR 1293 (HY000) at line 181: Incorrect table definition; there can be only one TIMESTAMP column with CURRENT_TIMESTAMP in DEFAULT or ON UPDATE clause"

To fix it, change:

`from_date` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,
`to_date` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,

to

`from_date` timestamp NOT NULL DEFAULT '0000-00-00 00:00:00',
`to_date` timestamp NOT NULL DEFAULT '0000-00-00 00:00:00',

Correct the error showing on all lines. In this case, the error appears on line 181.

Configuring HOMER-API

Check that these files are moved to the webserver location. If you followed all steps the files should already be there.
- $GIT/homer-api/api/preferences_example.php in $WEB/api/preferences.php
- $GIT/homer-api/api/configuration_example.php in $WEB/api/configuration.php
Check that the database credentials from $WEB/api/configuration.php are the same ones defined in $GIT/homer-api/sql/homer_user.sql

Configuring rotation scripts

Homer stores the captured SIP packets in tables which by default rotate daily.

Copy the scripts you have in $GIT/homer-api/scripts/ to another location - for example, /usr/local/bin/sipcapture/
Run chmod +x on the script directory.
Ensure that the homer_rotate script has the correct database credentials, as set in $GIT/homer-api/sql/homer_user.sql (defaults are homer_user and homer_password)
Set the rotate script in a cron:

30 3 * * * /usr/local/bin/sipcapture/homer_rotate > /dev/null 2>&1

By default, your database contains old tables. When you're ready to send SIP packets to the Capture Node, run the homer_rotate script manually so that it creates capture tables for the actual day. Otherwise, Kamailio won't be able to insert the logs in the database.

Installing Kamailio

Install Kamailio and kamailio-mysql rpms from their repository: http://download.opensuse.org/repositories/home:/kamailio:/
Make sure all required modules are loaded: db_mysql sipcapture pv textops rtimer xlog sqlops htable sl siputils

Overwrite the default config with the example provided by Homer:

cp $GIT/homer-api/examples/sipcapture/sipcapture.kamailio /etc/kamailio/kamailio.cfg

Start Kamailio.

Accessing the Homer web interface

Open Homer-UI at http://<capture_node_ip> and log in with username: admin and password: test123

Show all results

Space shortcuts

Page tree