Capture every SIP packet and RTP stream from Asterisk: detect call quality failures, codec mismatches, and dropped audio before agents report silent calls.
Homer HEP (Homer Encapsulation Protocol) captures all SIP signaling and RTP statistics from your Asterisk/ViciDial system and streams them to a centralized Homer UI for real-time and historical analysis. Silent calls, one-way audio, and jitter-induced dropouts become visible in packet detail within seconds of occurrence, eliminating the guesswork of call tracing through Asterisk logs alone. This tutorial walks through installing Homer Server, configuring Asterisk HEP forwarding, tuning RTCP metrics, and querying call data to pinpoint carrier failures, codec negotiation errors, and network problems in your ViciDial infrastructure.
Tested on ViciDial 2.14 (SVN 3555+), Asterisk 16/18, Homer 7.8+, MariaDB 10.5+, CentOS 7/8 and Ubuntu 18.04 LTS.
Prerequisites
- A working Asterisk/ViciDial installation with outbound calling enabled.
- Root or sudo access on both the ViciDial server and a dedicated Homer server (or co-located).
- Network connectivity between Asterisk and Homer (UDP port 6060 and TCP 9060 typical).
- MariaDB or MySQL 10.5+ with at least 50 GB free for call history (HEP packets consume 200-500 KB per call).
- Familiarity with Asterisk CLI commands and basic ViciDial diagnostics.
- Optional but recommended: a second NIC or VLAN on the ViciDial box to isolate HEP traffic.
What is Homer and why ViciDial needs it
Homer is a SIP capture and analytics platform that records every SIP message (INVITE, 100 Trying, 200 OK, BYE, etc.) and RTP stream statistics in real time. When an agent reports a silent call or a customer hears only their own voice, Homer's packet graph and RTP metrics show you whether the problem was on your network, your carrier, or your codec selection.
ViciDial's built-in call logging and Asterisk CLI are good for counting calls and marking outcomes, but they do not capture packet-level detail. A call can complete successfully in the Asterisk database yet still have one-way audio because of a firewall rule, a carrier SDP mismatch, or an RTP timeout. Homer fills that gap.
Architecture overview
Your Asterisk server runs a small HEP forwarder (either the Asterisk chan_sip or chan_pjsip module, or a dedicated sniffer like hepic). This forwarder sends a copy of every SIP packet and RTP packet to Homer's HEP collector (default port 6060 UDP). Homer decodes the packets, stores them in a database, and serves a web UI where you search by call ID, phone number, time range, and result code.
Asterisk (Outbound Call)
|
+---> HEP Forwarder (SIP module + hepic or VQ modules)
|
+---> Homer HEP Collector (UDP 6060)
|
+---> Homer DB (MySQL/MariaDB)
|
+---> Homer UI (HTTP 9060+)
For a ViciDial cluster, you can forward from multiple Asterisk boxes to a single Homer server, then correlate calls across the cluster.
Part 1: Install Homer Server
Homer runs on a dedicated Linux box or a non-Asterisk server in your network. We assume CentOS 7 or Ubuntu 18.04 LTS.
Install dependencies
CentOS 7:
yum install -y epel-release
yum install -y MariaDB-server MariaDB-client git golang wget curl
systemctl start mariadb
systemctl enable mariadb
Ubuntu 18.04 LTS:
apt-get update
apt-get install -y mariadb-server mariadb-client git golang-go wget curl
systemctl start mariadb
systemctl enable mariadb
Create Homer database and user
mysql -u root -p << 'EOF'
CREATE DATABASE homer_data DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE DATABASE homer_config DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'homer'@'localhost' IDENTIFIED BY 'homer_password_123';
GRANT ALL PRIVILEGES ON homer_data.* TO 'homer'@'localhost';
GRANT ALL PRIVILEGES ON homer_config.* TO 'homer'@'localhost';
FLUSH PRIVILEGES;
EXIT;
EOF
Replace homer_password_123 with a strong password and save it.
Clone Homer from GitHub and build
cd /opt
git clone https://github.com/sipcapture/homer.git
cd homer
git checkout 7.8 # or latest stable tag
Read the README. For a quick test, use Docker (optional). For production on bare metal, follow the build instructions in the repo. The Go-based binaries are statically linked and need only a standard Linux kernel.
Build the Homer API and capture server:
cd /opt/homer
make
If make is not available, download pre-built binaries:
wget https://github.com/sipcapture/homer/releases/download/v7.8/homer-7.8-linux-amd64.tar.gz
tar xzf homer-7.8-linux-amd64.tar.gz -C /opt/homer/
Initialize Homer database schema
cd /opt/homer
mysql -u homer -p homer_data < sql/homer_data.sql
mysql -u homer -p homer_config < sql/homer_config.sql
Create Homer configuration file
cat > /etc/homer/homer.conf << 'EOF'
{
"hep_listen": "0.0.0.0:6060",
"http_listen": "0.0.0.0:9060",
"db_driver": "mysql",
"db_dsn": "homer:homer_password_123@tcp(localhost:3306)/homer_data",
"db_config": "homer:homer_password_123@tcp(localhost:3306)/homer_config",
"loki_host": "",
"redis_host": "",
"debug": false,
"cors": true,
"auth_enabled": false,
"max_packet_size": 65535,
"table_rotation": "day"
}
EOF
mkdir -p /etc/homer
chmod 600 /etc/homer/homer.conf
Set auth_enabled to true and configure LDAP or local users in production.
Start Homer services
cd /opt/homer
./homer-api -config /etc/homer/homer.conf &
./homer-capture -config /etc/homer/homer.conf &
Or use systemd:
cat > /etc/systemd/system/homer-api.service << 'EOF'
[Unit]
Description=Homer API
After=network.target mariadb.service
[Service]
Type=simple
User=homer
ExecStart=/opt/homer/homer-api -config /etc/homer/homer.conf
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target
EOF
cat > /etc/systemd/system/homer-capture.service << 'EOF'
[Unit]
Description=Homer HEP Capture
After=network.target mariadb.service
[Service]
Type=simple
User=homer
ExecStart=/opt/homer/homer-capture -config /etc/homer/homer.conf
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target
EOF
useradd -r homer 2>/dev/null || true
chown -R homer:homer /opt/homer /etc/homer
systemctl daemon-reload
systemctl start homer-api homer-capture
systemctl enable homer-api homer-capture
Test that Homer is listening:
netstat -tlnp | grep -E '(6060|9060)'
curl http://localhost:9060
You should see the Homer UI homepage.
Part 2: Configure Asterisk to forward HEP
Asterisk can forward SIP and RTP packets to Homer using either the native HEP module (for PJSIP) or a sniffer daemon. We cover both methods.
Method A: Using chan_pjsip with HEP module (recommended for Asterisk 16+)
First, check if your Asterisk has the HEP module:
asterisk -rx "module show like hep"
If res_hep.so is listed and loaded, proceed. If not, rebuild Asterisk with --enable-hep or load it manually:
asterisk -rx "module load res_hep.so"
asterisk -rx "module load res_hep_pjsip.so"
Now configure HEP in /etc/asterisk/hep.conf:
[hep]
enabled = yes
host = 192.168.1.100
port = 6060
protocol = udp
capture_id = 1
uuid_type = call-id
Replace 192.168.1.100 with your Homer server's IP. The capture_id is used to tag packets from this Asterisk instance (useful when monitoring multiple Asterisk boxes).
Create /etc/asterisk/hep_pjsip.conf:
[general]
enabled = yes
send_via_ip = yes
Reload Asterisk modules:
asterisk -rx "module reload res_hep.so"
asterisk -rx "module reload res_hep_pjsip.so"
Verify:
asterisk -rx "hep show status"
Method B: Using sip.conf with chan_sip (legacy, Asterisk 13-18)
If you are still using chan_sip, enable SIP capture:
[general]
; In /etc/asterisk/sip.conf or sip-vicidial.conf
sipdebug = yes
; or use the CLI:
; asterisk -rx "sip set debug"
Then run a sniffer on the Asterisk box to forward captured packets to Homer. Use hepic (Kamailio HEP Forwarder):
# Install hepic
wget https://github.com/sippy/hepic/releases/download/v1.0/hepic-linux-amd64
chmod +x hepic-linux-amd64
mv hepic-linux-amd64 /usr/local/bin/hepic
# Run it
/usr/local/bin/hepic -listen 0.0.0.0:5061 -connect 192.168.1.100:6060 &
Then in sip.conf, set:
[general]
sipdebug = yes
And run tcpdump to forward to hepic:
tcpdump -i eth0 -nn 'udp port 5060 or udp port 16384:32767' \
-w - | hepic -listen stdin -connect 192.168.1.100:6060
This is cumbersome. Method A (PJSIP + HEP module) is preferred.
Configure RTCP to send to Homer
RTP streams themselves are not captured by HEP, but RTCP reports (which contain jitter, packet loss, and latency stats) are. Ensure RTCP is enabled in pjsip.conf:
[transport-udp]
type = transport
protocol = udp
bind = 0.0.0.0:5060
rtcp_mux = no
Setting rtcp_mux = no forces RTCP to use a separate port (RTP+1) instead of multiplexing. This makes packet capture cleaner for testing but uses slightly more bandwidth.
Verify RTCP is flowing from the carrier side. In Homer's UI, after a call completes, search for the call ID and look for RTCP packets with types 200 (SR, Sender Report) or 201 (RR, Receiver Report).
Part 3: Configure ViciDial for HEP
ViciDial itself does not configure HEP. Instead, Asterisk (which ViciDial controls) does. However, you need to ensure ViciDial's outbound and inbound dialing use the correct SIP profiles that have HEP enabled.
Check your ViciDial carrier configuration
In the web admin:
/vicidial/admin.php
Admin > Carrier > Edit
Verify that your carriers point to a valid Asterisk SIP context and use a pjsip endpoint. Look at /etc/asterisk/pjsip.conf:
[carriers]
type = aor
max_contacts = 1
[carrier-1](carriers)
contact = sip:gateway.provider.com:5060
[endpoint-carrier-1]
type = endpoint
aor = carrier-1
outbound_proxy = sip:gateway.provider.com:5060
allow = ulaw,alaw,gsm
dtmf_mode = rfc4733
from_user = your_did
from_domain = gateway.provider.com
The HEP module will capture all SIP traffic on this endpoint automatically. No additional config in ViciDial is needed.
Verify ViciDial logs do not interfere
Asterisk verbose logging is resource-intensive. Disable high verbosity in Asterisk and rely on Homer for detailed call tracing:
asterisk -rx "core set verbose 0"
asterisk -rx "core set debug 0"
Instead, in /etc/asterisk/logger.conf, log only errors and warnings:
[logfiles]
messages => notice,warning,error
This reduces disk I/O and keeps Asterisk fast while Homer captures everything.
Part 4: Query calls in Homer UI
Open your browser to http://homer-server:9060.
Search by Call-ID
Most VoIP calls carry a unique Call-ID in the SIP INVITE. To find a call:
- Click "Search" or "Calls".
- Select time range (e.g., "Last 1 hour").
- Enter the caller number, callee number, or Call-ID.
- Click "Search".
Homer displays a list of calls. Click a call to see the SIP flow (INVITE, 100, 180, 200, ACK, BYE, etc.) and RTP statistics.
Interpret RTP and RTCP metrics
When you drill into a call, Homer shows:
- Source / Dest IP:Port: Where the RTP stream originated and terminated.
- Codec: Audio codec negotiated (PCMU, PCMA, GSM, Opus, etc.).
- Jitter: Variance in packet arrival time (milliseconds). More than 50 ms is bad.
- Packet Loss: Percentage of RTP packets that did not arrive. Anything above 2% causes audible degradation.
- Round Trip Time (RTT): Latency from Asterisk to the peer and back. Over 150 ms causes echo.
- MOS (Mean Opinion Score): Estimated audio quality (1-5 scale). 4+ is acceptable for customers.
Example: A call shows codec PCMU, jitter 120 ms, 8% packet loss, MOS 2.1. This indicates a poor network path to the carrier gateway. Contact your ISP or carrier.
Export call data for analysis
Click "Export" on the search results to download a CSV of calls. Use this to correlate one-way audio incidents with specific time windows, carriers, or agent IDs.
Part 5: Troubleshoot common HEP issues
Homer receives no packets
Check that UDP 6060 is open:
# On Homer server
netstat -tlnpu | grep 6060
# Should show homer-capture listening on 0.0.0.0:6060
# From Asterisk box, test connectivity
nc -u -v 192.168.1.100 6060 < /dev/null
# Should not timeout
If timeout, check firewall:
# On Homer server
iptables -L -n | grep 6060
# Add rule if missing:
iptables -A INPUT -p udp --dport 6060 -j ACCEPT
Check Asterisk HEP module status:
asterisk -rx "hep show status"
# Should show "HEP Enabled: Yes"
If HEP is disabled, reload:
asterisk -rx "module reload res_hep"
HEP works but no SIP packets appear
Verify the capture ID in hep.conf matches what Homer expects. In Homer logs (/var/log/homer/homer-capture.log), you should see packet counts:
tail -f /var/log/homer/homer-capture.log | grep -i "packet"
If no packets logged, Asterisk may not be sending them. Check that Asterisk is actually handling calls:
asterisk -rx "sip show calls"
# or for PJSIP:
asterisk -rx "pjsip list channels"
If calls are running but HEP is silent, the module may have failed to start. Restart Asterisk:
systemctl restart asterisk
systemisk status asterisk
One-way audio appears in Homer but Asterisk logs show OK
This is Homer's strength. The call succeeded in the Asterisk database (ViciDial marks it CONNECTED) but Homer's RTP metrics reveal the problem:
- RTP from A to B is present, B to A is missing: Check firewall rules on the B side (carrier gateway or far-end PBX). They may be blocking inbound RTP from your Asterisk IP.
- Both directions present but high jitter/loss on one direction: The carrier's return path is congested. Ask them to check routing.
- No RTCP reports from the far end: The carrier is not sending RTCP, or it is blocked. Some cheap VoIP providers disable RTCP. This means you have no quality visibility.
Storage and retention
Homer logs to MariaDB. By default, it keeps all packets. This grows large quickly. Set a retention policy in homer.conf:
"table_rotation": "day",
"table_retention_days": 7
This rotates tables daily and purges data older than 7 days. Adjust as needed. On a busy Asterisk handling 100+ concurrent calls, 7 days consumes 20-50 GB.
For long-term storage, export older calls to a data warehouse or archive storage before purging.
Part 6: Integrate Homer with ViciDial dashboards
ViciDial does not have a built-in Homer integration, but you can create a custom link in the agent screen or admin interface to jump to Homer for a given call.
Add Homer link to vicidial.php
Edit /var/www/html/agc/vicidial.php (or your custom agent screen template). Near where call details are displayed:
<?php
// After displaying call details, add:
$call_id = preg_replace('/[^[email protected]]/','', $_REQUEST['call_id']); // sanitize
$homer_url = "http://192.168.1.100:9060/?query=" . urlencode($call_id);
echo "<a href='$homer_url' target='_blank' class='btn btn-info'>View RTP in Homer</a>";
?>
This assumes ViciDial stores the call ID in the session or request. Adjust the variable name based on your ViciDial version.
Add Homer link to vicidial_log
In /vicidial/admin.php, edit the call log display to include a Homer link:
<?php
// In call log listing:
$call_id = $row['vicidial_id']; // or whatever field holds the call ID
$homer_link = "<a href='http://192.168.1.100:9060/?query=" . htmlspecialchars($call_id) . "' target='_blank'>View in Homer</a>";
echo "<td>$homer_link</td>";
?>
Troubleshooting
Asterisk crashes after enabling HEP
If Asterisk becomes unstable after loading res_hep, the module may have a bug in your Asterisk version. Try disabling HEP and use the sniffer method (hepic) instead:
asterisk -rx "module unload res_hep"
systemctl restart asterisk
Then run hepic separately as shown in Method B.
Homer UI loads but shows "No data available"
Check that the database connection is valid. Test manually:
mysql -u homer -p homer_data -e "SELECT COUNT(*) FROM hep_proto_1;"
If this fails, the schema was not imported. Re-run the SQL import:
mysql -u homer -p homer_data < sql/homer_data.sql
Also verify that packets are being inserted. Check homer-capture logs:
systemctl status homer-capture
SIP REGISTER packets missing
Some Asterisk configurations do not send REGISTER through the HEP module. This is normal for outbound-only systems. If you need to capture registrations (common for SIP trunks), enable SIP debugging specifically:
asterisk -rx "pjsip set logger on"
But be warned: verbose SIP logging impacts performance on busy systems.
Frequently asked questions
Can I monitor calls across a multi-server ViciDial cluster with Homer?
Yes. Configure each Asterisk server to forward HEP to the same Homer instance (set the host in hep.conf to the shared Homer server). In Homer, search by time range and carrier to correlate calls across the cluster. Each Asterisk server sends a unique capture_id in its HEP packets, so you can filter by server.
Does Homer capture payload inside SIP messages (e.g., Authorization headers)?
By default, Homer captures full SIP headers including credentials. This is a security risk if calls are being audited by untrusted parties. To mask sensitive data, either disable auth header capture in Homer's config or configure Asterisk to strip headers before HEP forwarding. Consult Homer's privacy settings and your compliance requirements.
What is the minimum network bandwidth needed for HEP?
A single call with full SIP + RTP + RTCP capture consumes roughly 200-500 KB depending on call duration and RTCP frequency. A 100-call system forwarding to Homer uses 20-50 Mbps of WAN bandwidth. Most carriers throttle SIP signaling to 1-5 Mbps, so HEP overhead is minimal. However, if your Asterisk and Homer servers are on the same LAN with gigabit links, bandwidth is not a concern.
Can I run Homer on the same server as Asterisk/ViciDial?
Yes, but not recommended. Homer's MariaDB will consume significant resources during call playback and searches. A dedicated Homer server keeps ViciDial and Asterisk responsive. If you must co-locate, use SSD storage, allocate at least 8 CPU cores to the VM, and set MariaDB's innodb_buffer_pool_size to 50% of available RAM.
Why does Homer show a call with one-way audio but ViciDial marked it as CONNECTED?
ViciDial's CONNECTED status means Asterisk answered the far end (received a 200 OK), not that audio flowed both ways. One-way audio happens after call setup due to network issues (firewall, NAT, codec mismatch, or carrier routing). Homer's RTP analysis reveals the problem. Use this information to file a support ticket with your carrier or review your firewall rules.
Summary
You have installed Homer on a dedicated server, configured Asterisk to forward SIP and RTP packets via HEP, and learned to search Homer's UI for call detail and quality metrics. When a call fails in ViciDial, Homer's packet trace and RTCP statistics show you whether the problem was signaling (wrong SDP, authentication failure), RTP (no packets, high jitter), or network (firewall, latency). From here, export call data to correlate failures with time, carrier, or agent; set up retention policies to manage database growth; and integrate Homer links into your ViciDial admin screens for one-click access. For ongoing monitoring, periodically review Homer's MOS scores and packet loss metrics to detect carrier degradation before customer complaints arrive.