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_installationAnswer
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.gzEnable 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
