Homer SIP capture and VoIP Monitoring Install Guide

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 < homer_databases.sql
mysql < homer_user.sql
mysql homer_data < schema_data.sql
mysql homer_configuration < schema_configuration.sql
mysql homer_statistic < schema_statistic.sql

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

<VirtualHost *:80>
  ServerName homer

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

  <Directory />
    Options FollowSymLinks
    AllowOverride None
  </Directory>
  <Directory /var/www/html >
    Options Indexes FollowSymLinks MultiViews
    AllowOverride All
    Order allow,deny
    allow from all
  </Directory>

</VirtualHost>

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

<?xml version="1.0"?>
<document type="captagent_module/xml">
    <module name="socket_pcap" description="HEP Socket" serial="2014010402">
    <profile name="socketspcap_sip" description="HEP Socket" enable="true" serial="2014010402">
        <settings>
        <param name="dev" value="any"/>
        <param name="promisc" value="true"/>
        <param name="reasm" value="false"/>
        <param name="tcpdefrag" value="false"/>
        <param name="capture-plan" value="sip_capture_plan.cfg"/>
        <param name="filter">
            <value>portrange 5060-5091</value>
        </param>
        </settings>
    </profile>
    <profile name="socketspcap_rtcp" description="RTCP Socket" enable="true" serial="2014010402">
        <settings>
        <param name="dev" value="any"/>
        <param name="promisc" value="true"/>
        <param name="reasm" value="false"/>
        <!-- size in MB -->
        <param name="ring-buffer" value="20"/>
        <!-- for rtp && rtcp < 250 -->
        <param name="snap-len" value="256"/>
        <param name="capture-filter" value="rtcp"/>
        <param name="capture-plan" value="rtcp_capture_plan.cfg"/>
        <param name="filter">
            <value>portrange 5060-50000 and len >=50 </value>
        </param>
        </settings>
    </profile>
    </module>
</document>

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.

<?xml version="1.0"?>
<document type="captagent_module/xml">
    <module name="transport_hep" description="HEP Protocol" serial="2014010402">
    <profile name="hepsocket" description="Transport HEP" enable="true" serial="2014010402">
        <settings>
        <param name="version" value="3"/>
        <param name="capture-host" value="x.x.x.x"/>
        <param name="capture-port" value="9060"/>
        <param name="capture-proto" value="udp"/>
        <param name="capture-id" value="100"/>
        <param name="capture-password" value="myhep"/>
        <param name="payload-compression" value="false"/>
        </settings>
    </profile>
    </module>
</document>

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

Sections: 

Other

 

copyright

https://www.powerpbx.org/content/homer-voip-monitoring-install-guide-v1