homer seven setup

HOMER 7

Overview of Components

There are quite a few components which make up a complete Homer 7 stack. Below is the list for this guide.

Operating System Note

A quick note regarding the other components used in this guide. My operating system of choice is CentOS 7, and as such I have referenced and used RPM and YUM repos wherever possible to make updating components easier in the future. This should work fine for most RedHat distributions. If you prefer to use a different Linux distribution, please adjust accordingly and/or feel free to suggest the required edits so as to make this guide as complete as possible.

The HEPlify Capture Agent

As anyone knows, you can't gather information without someone and/or something listening for it. The HEPlify Capture Agent does just that, then sends the data to the HEPlify-Server to be ingested and sent out to the other components of the stack.

OS and Hardware Requirements

Hardware: I built this on a physical 1U Supermicro mini server with an Atom processor and a 16GB SSD and it is running just fine. You'll need 2 NICs, one for management, and one for the mirrored port from the switch.

OS Packages:

EPEL-Release
The Go programming Language.
PCAP Libraries

Install

Install your prerequisites.
yum install epel-release -y
yum install go -y
yum install -y libpcap-devel
Clone the github repo
git clone https://github.com/sipcapture/heplify
Run the make file in the cloned location with the make command.
Move the files to /opt/heplify path.
Note: Heplify capture requires root permissions to run.

Testing
You should now be able to start the heplify capture by running the heplify executable file. Output should be sent to the screen, and the heplify.log file should show the most recent information.

Service Installation

Copy the example service file to the proper spot in the file system.
cp /opt/heplify/example/heplify.service /etc/systemd/system/
Modify the executable path in the file to match what you want to be capturing. This is where you would modify it to specify which physical interface to listen on, as well as what server to send the captured packets to.

This is what the production hep capture service file looks like. Note that [interface_name] is the system name of the interface which will be listening and will be the monitor destination below.

  [Unit]
  Description=Captures packets from wire and sends them to Homer
  After=network.target
  
  [Service]
  WorkingDirectory=/opt/heplify
  ExecStart=/opt/heplify/heplify -i [interface_name] -hs [ip_of_heplify_server]:9060 -m SIPRTCP
  ExecStop=/bin/kill ${MAINPID}
  Restart=on-failure
  RestartSec=10s
  Type=simple
  
  [Install]
  WantedBy=multi-user.target

Enable the service.
systemctl daemon-reload
systemctl enable heplify
systemctl start heplify
Validate that the service is running by using systemctl status heplify
The log is written to /opt/heplify/heplify.log

Setting up the Mirror Port on the Switch

For this guide I used a Cisco switch to connect everything. In order for the HEPlify Capture Agent to receive the data from the VoIP services the traffic needs to be mirrored into the agent. Here are the commands for most Cisco switches.

Configure the source for the monitor session. This is the interface or interfaces from which you would like to capture the data. You can add multiples to this list if needed.

monitor session 1 source interface GigabitEthernet 0/0/x

Configure the destination for the monitor session. This should be the 2nd NIC port connected to the HEPlify Capture Agent hardware.

monitor session 1 destination interface GigabitEthernet 0/0/y

Here is Cisco's SPAN Guide for reference: SPAN Command Reference

PostgreSQL 10

PostgreSQL is where the HEPlify-Server stores all of the raw data that it ingests from the HEPlify Capture Agent. My suggestion is to size this appropriately to your environment. A smaller environment will probably not need as much resources as I've specified here, whereas a larger environment will probably require more. If you can back the database with fast disk that is helpful as well.

VM Specs
Minimum 4 CPUs
Minimum 16GB RAM
Minimum 1TB Storage Space

Package Requirements:

Epel-Release
yum install -y epel-release

Note: Make sure your PostgreSQL Data directory is configured to point to a very large data storage space. By default PostgreSQL will put all data into the same directory as the configuration files.

Install and Start PostgreSQL-10

Get the postgresql-10 repo installed.
rpm -Uvh https://yum.postgresql.org/10/redhat/rhel-7-x86_64/pgdg-centos10-10-2.noarch.rpm
Install postgresql-10 from the repo.
yum install postgresql10-server postgresql10 -y
Initialize the postgresql-10 configuration. This sets up the system databases and gets the PostgreSQL server ready to run.
/usr/pgsql-10/bin/postgresql-10-setup initdb
Verify the version installed.
/usr/pgsql-10/bin/postgres -V
Enable the services.
systemctl enable postgresql-10
systemctl start postgresql-10
Set the password on the postgres user account on the database server.
su -l postgres
psql
\password
\q (to quit)
exit (leave the postgres account and go back to root)
Modify the connection file to allow inbound connections to the postgresql services.
vi /var/lib/pgsql/10/data/pg_hba.conf
Add to the bottom of the file this line:
host all all [IP of HEPlify-Server]/32 password
host all all [IP of homer-app server]/32 password
Modify the postgresql.conf configuration file and set the following variables to have a good running server.

I found this PostgreSQL tuning guide: http://linuxfinances.info/info/quickstart.html
File Path: /var/lib/pgsql/10/data/postgresql.conf
listen_addresses = '*' under the -Connection Settings- header.
shared_buffers = 1024MB
effective_cache_size = 12GB
Note: This will likely be most of the servers physical memory, if postgres is installed by itself.
max_locks_per_transaction = 1000
data_directory = '[path to data directory]'

Restart the postgresql-10 service to commit the changes.
systemctl restart postgresql-10
Allow the firewall to accept the inbound connections on port 5432 for PostgreSQL clients.
firewall-cmd --add-port=5432/tcp --permanent
firewall-cmd --reload