HomerSIPcaptureandVoIPMonitoringInstallGuide

Homer is a carrier-grade SIP capture and VoIP monitoring system. This procedure will show how to install Homer on a CentOS v7 server.

CaptAgent is a Homer Encapsulation Protocol (HEP) agent. It is used to collect relevant data on a local Linux VoIP server, encapsulate it for transportation, and send it to Homer. This procedure will show how to install it on CentOS v6, v7, and Debian v8

Software

CentOS v7

Homer v5

Kamailio v5

CaptAgent v6

PRE-INSTALL

Disable Selinux

Check status.

sestatus

If not disabled, do the following and reboot.

sed -i 's/\(^SELINUX=\).*/\SELINUX=disabled/' /etc/selinux/config

Disable firewall

It is sometimes helpful to disable the firewall during install.

systemctl disable firewalld
systemctl disable iptables
systemctl stop firewalld
systemctl stop iptables

Timezone

yum install ntp
systemctl enable ntpd
systemctl start ntpd

Find timezone

tzselect

Set timezone example

timedatectl set-timezone America/Vancouver

INSTALL

Prerequisites

yum -y install epel-release
yum -y update
yum -y install git nano gcc httpd mariadb mariadb-server mariadb-devel php php-mysql bison pcre-devel libpcap-devel flex GeoIP-devel

Homer

Download

cd /usr/src/
git clone https://github.com/sipcapture/homer-ui.git
git clone https://github.com/sipcapture/homer-api.git
git clone https://github.com/sipcapture/homer-config.git

Optionally change the default database password in the following files

/usr/src/homer-api/api/configuration_example.php
/usr/src/homer-api/sql/rotation_kamailio5.ini
/usr/src/homer-api/sql/mysql/homer_user.sql
/usr/src/homer-config/sipcapture/sipcapture.kamailio5

Copy files

cp -R /usr/src/homer-ui/* /var/www/html
cp -R /usr/src/homer-api/api /var/www/html/api
mkdir /opt/homer
cp /usr/src/homer-api/scripts/mysql/* /opt/homer
mv -f /opt/homer/rotation_kamailio5.ini /opt/homer/rotation.ini
chmod +x /opt/homer/*

Rename preference and configuration files.

cd /var/www/html/api
mv preferences_example.php preferences.php
mv configuration_example.php configuration.php

Edit preferences

nano /var/www/html/api/preferences.php

Set define('RTCP_TABLE_PARTITION', 1);

Change the REMOTE_LOG_URL and EXTERNAL_AUTH_URL to Homer server IP.

Change ALARM_FROMEMAIL, ALARM_TOEMAIL, HOMER_TIMEZONE, as necessary.

Change mysql socket directory and name for compatibility with CentOS v7

sed -i "s/run\/mysqld\/mysqld.sock/lib\/mysql\/mysql.sock/g" /opt/homer/rotation.ini

MariaDB

Create MySQL databases and tables

systemctl enable mariadb
systemctl restart mariadb

cd /usr/src/homer-api/sql/mysql

mysql mysql mysql homer_data mysql homer_configuration mysql homer_statistic

Lock down the database server

mysql_secure_installation

Answer Y to everything.

Rotation script

Create the daily cron

crontab -e

30 3 * * * root /opt/homer/homer_mysql_rotate > /dev/null 2>&1

The daily cron must be run before Homer can begin capturing data.

/opt/homer/homer_mysql_rotate

Kamailio

Compile install is required to use the geoip module. This compile procedure installs into the same directories as the official Kamailio RPMs, therefore it is interchangeable with an RPM install.

cd /usr/src
git clone -b 5.0 --single-branch https://github.com/kamailio/kamailio.git
cd /usr/src/kamailio
make include_modules="db_mysql sipcapture pv textops rtimer xlog sqlops htable sl siputils geoip" cfg \
prefix=/usr/ cfg_prefix=/

make all && make install

Copy and modify kamailio.cfg.

cp /usr/src/homer-config/sipcapture/sipcapture.kamailio5 /etc/kamailio/kamailio.cfg
sed -i "s/GeoIP.dat/GeoIPCity.dat/g" /etc/kamailio/kamailio.cfg
sed -i "s/lib\/x86_64-linux-gnu/lib64/g" /etc/kamailio/kamailio.cfg

Install GeoIP data

mkdir /usr/share/GeoIP
cd /usr/share/GeoIP/
wget -N -q http://geolite.maxmind.com/download/geoip/database/GeoLiteCity.dat.gz
mv GeoLiteCity.dat.gz GeoIPCity.dat.gz
gunzip GeoIPCity.dat.gz

Enable GeoIP

nano /etc/kamailio/kamailio.cfg

## Uncomment the following line near the top. So instead of ##, make it #
#!define WITH_HOMER_GEO


Create startup systemd file

nano /etc/systemd/system/kamailio.service

[Unit]
Description=Kamailio - the Open Source SIP Server
After=network-online.target
After=mariadb.service httpd.service
[Service]
Type=forking
EnvirOnment='CFGFILE=/etc/kamailio/kamailio.cfg'
EnvirOnmentFile=/etc/default/kamailio
ExecStartPre=/usr/bin/mkdir -m=2770 -p /var/run/kamailio
ExecStartPre=/usr/bin/chown kamailio:kamailio /var/run/kamailio
PIDFile=/var/run/kamailio.pid
ExecStart=/usr/sbin/kamailio -P /var/run/kamailio.pid -f $CFGFILE -m $SHM_MEMORY -M $PKG_MEMORY -u $USER -g $GROUP
ExecStopPost=/usr/bin/rm -f /var/run/kamailio.pid
Restart=on-abort
[Install]
WantedBy=multi-user.target


Create kamailio user

useradd kamailio

Copy Kamailio environment file

cp /usr/src/kamailio/pkg/kamailio/centos/7/kamailio.sysconfig /etc/default/kamailio

Enable and start Kamailio

systemctl enable kamailio
systemctl start kamailio

Apache configuration

chown -R apache. /var/www/html

nano /etc/httpd/conf.d/homer.conf


ServerName homer
# Indexes + Directory Root.
DirectoryIndex index.php index.html index.htm
DocumentRoot /var/www/html

Options FollowSymLinks
AllowOverride None


Options Indexes FollowSymLinks MultiViews
AllowOverride All
Order allow,deny
allow from all




systemctl enable httpd
systemctl restart httpd

Browse to http://yourserverip

username: admin
password: test123

Make sure date/time range in upper right is correct when searching.

Firewall

Replace x.x.x.x with the VoIP server IP being monitored and repeat as necessary.

systemctl enable firewalld
systemctl start firewalld
firewall-cmd --permanent --zOne=public --add-service={http,https}
firewall-cmd --permanent --zOne=public --add-rich-rule='rule family="ipv4" source address="x.x.x.x" accept'
firewall-cmd --reload

CaptAgent

Universal Homer Encapsulation Protocol (HEP) agent.

Install on any VoIP server you want to monitor. Alternatively, Asterisk PJSIP, Freeswitch, Kamailio, OpenSIPS, and rtpengine have the ability to enable native HEP support. Native clients may not support all features. For example, Freeswitch v1.6 does not currently support RTCP for QoS stats.

Prerequisites

Debian 8 (jessie)

apt-get install build-essential git-core libexpat-dev libpcap-dev libjson0-dev libtool automake flex bison libuv-dev

CentOS v6 & v7

yum -y install epel-release
yum -y install git gcc json-c-devel expat-devel libpcap-devel flex-devel automake libtool bison flex libuv-devel

Install

cd /usr/src
git clone https://github.com/sipcapture/captagent.git
cd captagent
./build.sh
./configure
make && make install

Configure

socket_pcap.xml

The only change necessary is to enable=true the rtcp section. If not using eth0 network interface, try change "dev" value="any" for both sections.

nano /usr/local/captagent/etc/captagent/socket_pcap.xml


portrange 5060-5091






portrange 5060-50000 and len >=50







transport_hep.xml

nano /usr/local/captagent/etc/captagent/transport_hep.xml

Change x.x.x.x to the IP address of your Homer monitoring server and change port to 9060. Optionally change capture-id number to uniquely identify this captagent instance.

sip_capture_plan.cfg

Uncomment the if(sip_has_sdp()) section

nano /usr/local/captagent/etc/captagent/captureplans/sip_capture_plan.cfg

capture[pcap] {
# here we can check source/destination IP/port, message size
if(msg_check("size", "100")) {
#Do parsing
if(parse_sip()) {
#Can be defined many profiles in transport_hep.xml

if(!send_hep("hepsocket")) {
clog("ERROR", "Error sending HEP!!!!");
}

if(sip_has_sdp())
{
#Activate it for RTCP checks
if(!check_rtcp_ipport())
{
clog("ERROR", "ALREADY EXIST");
}
}
#Duplicate all INVITEs to JSON transport
# if(sip_is_method() && sip_check("method","INVITE")) {
# #Can be defined many profiles in transport_json.xml
# if(!send_json("jsonsocket")) {
# clog("ERROR", "Error sending JSON!!!");
# }
# }
}
}
drop;
}

Configure init or systemd and default

Debian8

cp /usr/src/captagent/init/deb/jessie/captagent.service /etc/systemd/system/
cp /usr/src/captagent/init/deb/debian/captagent.default /etc/default/captagent
systemctl daemon-reload
systemctl enable captagent
systemctl start captagent

CentOS 7

cp /usr/src/captagent/init/el/7/captagent.service /etc/systemd/system/
cp /usr/src/captagent/init/el/captagent.sysconfig /etc/sysconfig/captagent
systemctl daemon-reload
systemctl enable captagent
systemctl start captagent

CentOS 6

cp /usr/src/captagent/init/el/6/captagent.init /etc/init.d/captagent
cp /usr/src/captagent/init/el/captagent.sysconfig /etc/sysconfig/captagent
# Modify init.d change directory name from "bin" to "sbin"
nano /etc/init.d/captagent
APP_FILE=/usr/local/captagent/sbin/$prog
chmod 755 /etc/init.d/captagent
chkconfig --add captagent
chkconfig captagent on
service captagent start

Screenshots