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


CentOS v7
Homer v5
Kamailio v5
CaptAgent v6


Disable Selinux

Check status.


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
yum install ntp
systemctl enable ntpd
systemctl start ntpd

Find timezone


Set timezone example

timedatectl set-timezone America/Vancouver


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


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


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 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


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

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.



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 #

Create startup systemd file

nano /etc/systemd/system/kamailio.service

Description=Kamailio - the Open Source SIP Server
After=mariadb.service httpd.service

ExecStartPre=/usr/bin/mkdir -m=2770 -p /var/run/kamailio
ExecStartPre=/usr/bin/chown kamailio:kamailio /var/run/kamailio
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


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 /var/www/html >
    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.


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


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.


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
cd /usr/src
git clone https://github.com/sipcapture/captagent.git
cd captagent
make && make install


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">
        <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>
    <profile name="socketspcap_rtcp" description="RTCP Socket" enable="true" serial="2014010402">
        <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>


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">
        <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"/>


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!!!!");
          #Activate it for RTCP checks
              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!!!");
        #    }
        # }

Configure init or systemd and default


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

chmod 755 /etc/init.d/captagent
chkconfig --add captagent
chkconfig captagent on
service captagent start


Homer Screenshot