Latest revision as of 13:02, 20 January 2026

This guide covers VoIPmonitor deployment options: where to install the sensor, how to forward traffic, and distributed architectures for multi-site monitoring.

Sensor Deployment Options

On-Host Capture

Install the sensor directly on the same Linux server as your PBX/SBC.

Pros	Cons
No extra hardware, network changes, or port mirroring required	Adds CPU, memory, and disk I/O load to production voice server
Simplest setup	Not suitable if resources are critical

ℹ️ Note: VoIPmonitor sensor runs exclusively on Linux. For Windows-based PBXs (e.g., 3CX Windows edition), you must use a dedicated Linux sensor with traffic mirroring.

Dedicated Sensor

A separate Linux server runs only VoIPmonitor. Recommended for production environments as it isolates monitoring from voice platform resources.

When Required:

Windows-based PBXs
Limited CPU/RAM/disk I/O on PBX server
Zero monitoring impact needed
Centralized capture from multiple sites

Traffic Forwarding Methods

When using a dedicated sensor, you must forward traffic to it using one of these methods.

Hardware Port Mirroring (SPAN/RSPAN)

Physical or virtual switches copy traffic from source port(s) to a monitoring port.

Physical Switch

Configure your switch to mirror traffic from PBX/SBC ports to the sensor's port. Consult your switch documentation for specific commands.

# /etc/voipmonitor.conf
interface = eth0
sipport = 5060
savertp = yes

💡 Tip:

VMware/ESXi Virtual Switch

For virtualized environments, VMware provides port mirroring at the virtual switch level.

Standard vSwitch:

In vSphere Client, navigate to ESXi host
Select virtual switch → Properties/Edit Settings → Enable Port Mirroring
Set source (SBC VM) and destination (VoIPmonitor VM) ports

Distributed vSwitch:

In vSphere Web Client → Networking → Select distributed switch
Configure tab → Port Mirroring → Create mirroring session
Specify source/destination ports and enable

ℹ️ Note: Distributed switch mirroring can span multiple ESXi hosts within a cluster.

Multiple VoIP Platforms

Monitor multiple platforms (e.g., Mitel + FreeSWITCH) with a single sensor by mirroring multiple source ports to one destination port.

GUI differentiation:

Filter by IP address ranges
Filter by number prefixes
Use separate sensors with unique id_sensor values

⚠️ Warning: Critical: When sniffing from multiple mirrored sources, packets may arrive as duplicates. Add auto_enable_use_blocks = yes to voipmonitor.conf to enable automatic deduplication. See Sniffer_configuration for details.

Software-based Tunneling

When hardware mirroring is unavailable, use software tunneling to encapsulate and forward packets.

Protocol	Configuration Parameter	Notes
IP-in-IP, GRE, ERSPAN	Built-in (auto-detected)	No additional config needed
TZSP (MikroTik)	`udp_port_tzsp = 37008`
L2TP	`udp_port_l2tp = 1701`
VXLAN	`udp_port_vxlan = 4789`	Common in cloud environments
AudioCodes	`udp_port_audiocodes = 925`	See AudioCodes Tunneling
IPFIX (Oracle SBCs)	`ipfix*` options	Enable ipfix options in config

HEP (Homer Encapsulation Protocol)

Lightweight protocol for mirroring VoIP packets. Supported by Kamailio, OpenSIPS, FreeSWITCH, and many SBCs.

# /etc/voipmonitor.conf
hep = yes
hep_bind_port = 9060
hep_bind_udp = yes
# Optional: hep_kamailio_protocol_id_fix = yes

SIP and RTP Correlation from Multiple HEP Sources:

VoIPmonitor correlates calls using standard SIP Call-ID, To/From tags, and RTP streams are matched based on IP:port from SDP.

ℹ️ Note: Multiple HEP sources to same sniffer: When SIP HEP (e.g., from Kamailio) and RTP HEP (e.g., from rtpproxy) are sent to the same sniffer instance, they ARE correlated into unified CDRs. The sniffer processes both as regular SIP/RTP packets.

Example: Kamailio sends SIP via HEP → VoIPmonitor + rtpproxy sends RTP via HEP → same VoIPmonitor = Complete CDRs with SIP+RTP

💡 Tip: Client/Server mode also supported: A sniffer client can receive HEP packets and forward them to a central sniffer server using packetbuffer_sender=yes. The central server then correlates SIP and RTP from all sources. This works for HEP, IPFIX, and RibbonSBC protocols.

HEP Header Fields:

HEP Field	Present In	Current Usage
`correlation_id`	INVITE only	Parsed but not used
`capture_node_id`	All SIP packets	Parsed but not used

ℹ️ Note: Feature Request VS-1703: Option to set CDR id_sensor from HEP correlation_id or capture_node_id headers. This would allow sensor attribution based on the originating HEP source when SIP arrives via HEP but RTP comes from different sensors. Track status

HEP Timestamp: VoIPmonitor uses the HEP timestamp field. If the source has an unsynchronized clock, call timestamps will be incorrect. There is no option to ignore HEP timestamps.

HEP3 with Port 0: Not captured by default. Add port 0 to sipport:

sipport = 0,5060

HEP/IPFIX Timestamp Options

(New in 2026.1) By default, VoIPmonitor uses timestamps from HEP/IPFIX packet headers. If the source has an unsynchronized clock, enable system time instead:

# /etc/voipmonitor.conf
hep_use_system_time = yes    # Use system arrival time instead of HEP timestamp
ipfix_use_system_time = yes  # Use system arrival time instead of IPFIX timestamp

Use case: Debugging packet timing issues when combining HEP with PCAP replay or when HEP sources have clock drift.

Cloud Packet Mirroring

Cloud providers offer native mirroring services using VXLAN or GRE encapsulation.

Provider	Service Name
Google Cloud	Packet Mirroring
AWS	Traffic Mirroring
Azure	Virtual Network TAP

Configuration Steps:

Create a VoIPmonitor sensor VM in your cloud environment
Create mirroring policy: select source VMs/subnets, set destination to sensor VM
Critical: Capture traffic in BOTH directions (INGRESS and EGRESS)
Configure sensor:

udp_port_vxlan = 4789
interface = eth0
sipport = 5060

⚠️ Warning: Capturing only ingress or only egress results in incomplete CDRs and broken call data.

Best Practices:

Filter at source to forward only SIP/RTP ports
Monitor NIC bandwidth limits
Account for VXLAN overhead (~50 bytes) - may need jumbo frames
Ensure NTP sync across all VMs

Alternative: Consider Client/Server architecture with on-host sensors instead of cloud mirroring for better performance.

Pre-Deployment Verification

For complex setups (RSPAN, ERSPAN, proprietary SBCs), verify compatibility before production deployment:

Configure test mirroring with a subset of traffic
Capture test calls with tcpdump: sudo tcpdump -i eth0 -s0 port 5060 -w /tmp/test.pcap
Verify pcap contains SIP and RTP: tshark -r /tmp/test.pcap -Y "sip || rtp"
Submit pcap to VoIPmonitor support with hardware/configuration details

Distributed Architectures

For multi-site monitoring, sensors can be deployed in various configurations.

Classic Mode: Standalone Sensors

Each sensor operates independently:

Processes packets and stores PCAPs locally
Connects directly to central MySQL to write CDRs
GUI needs network access to each sensor's TCP/5029 for PCAP retrieval

Alternative: NFS/SSHFS Mounting

If TCP/5029 access is blocked, mount remote spool directories on the GUI server:

# NFS mount
sudo mount -t nfs 10.224.0.101:/var/spool/voipmonitor /mnt/voipmonitor/sensor1

# SSHFS mount
sshfs voipmonitor@10.224.0.101:/var/spool/voipmonitor /mnt/voipmonitor/sensor1

Configure GUI: Settings > System Configuration > Sniffer data path: /var/spool/voipmonitor:/mnt/voipmonitor/sensor1:/mnt/voipmonitor/sensor2

💡 Tip: For NFS, use hard,nofail,tcp mount options for reliability.

Modern Mode: Client/Server (v20+) — Recommended

Secure encrypted TCP channel between remote sensors and central server. GUI communicates only with central server.

Mode	Processing	PCAP Storage	WAN Traffic	Best For
Local Processing (`packetbuffer_sender=no`)	Remote	Remote	Low (CDRs only)	Limited WAN bandwidth
Packet Mirroring (`packetbuffer_sender=yes`)	Central	Central	High (full packets)	Low-resource remote sites

For detailed configuration, see Distributed Architecture: Client-Server Mode.

Quick Start - Remote Sensor (Local Processing):

id_sensor               = 2
server_destination      = 10.224.0.250
server_destination_port = 60024
server_password         = your_strong_password
packetbuffer_sender     = no
interface               = eth0
sipport                 = 5060
# No MySQL credentials needed - central server writes to DB

Quick Start - Central Server:

server_bind             = 0.0.0.0
server_bind_port        = 60024
server_password         = your_strong_password
mysqlhost               = 10.224.0.201
mysqldb                 = voipmonitor
mysqluser               = voipmonitor
mysqlpassword           = db_password
cdr_partition           = yes
interface               =   # Leave empty - don't sniff locally

ℹ️ Note: Deduplication in Packet Mirroring mode (New in 2026.1): When using packetbuffer_sender=yes with deduplicate_ipheader=ip_only on the server, the server now automatically sends this parameter to clients. For older versions, set deduplicate_ipheader=ip_only on both server AND client to ensure consistent hash calculation.

Firewall Requirements

Deployment	Port	Direction	Purpose
Client/Server	TCP/60024	Remote → Central	Encrypted CDR/packet channel
Client/Server	TCP/5029	Central → Remote	On-demand PCAP fetch (Local Processing mode)
GUI Access	TCP/5029	GUI → Central	Management/API
Cloud Mode	TCP/60023	Sensor → cloud.voipmonitor.org	Cloud service connection

Configuration Notes

Critical Parameters

Parameter	Description	Notes
`id_sensor`	Unique sensor identifier (1-65535)	Mandatory in distributed deployments
`cdr_partition`	Enable daily CDR table partitions	Enable on server writing to DB
`mysqlloadconfig`	Load config from database	Enable on central server only
`interface`	Capture interface	Use specific NIC or `any`

Time Synchronization

⚠️ Warning: Accurate NTP sync is critical for correlating call legs across sensors. All servers (GUI, DB, sensors) must run NTP client (chrony or ntpd).

First Startup

On first start against empty database:

Start service: systemctl start voipmonitor
Monitor logs: journalctl -u voipmonitor -f
Wait for schema/partition creation to complete

If you see Table 'cdr_next_1' doesn't exist errors, check DB connectivity and privileges.

Deployment Comparison

Model	Processing	PCAP Storage	WAN Traffic	GUI Connectivity
Classic Standalone	Remote	Remote	Minimal (MySQL CDRs)	GUI ↔ each Sensor
Client/Server (Local Processing)	Remote	Remote	Minimal (encrypted CDRs)	GUI ↔ Central only
Client/Server (Packet Mirroring)	Central	Central	High (encrypted packets)	GUI ↔ Central only

Troubleshooting

NFS/SSHFS Connectivity

Missing data for specific time periods usually indicates storage server connectivity issues.

Symptom	Likely Cause	Solution
Data gap in time period	NFS/SSHFS server unreachable	Check logs for "not responding, timed out"
Stale file handle	Server rebooted or export changed	Remount NFS share
Connection resets	Network interruption	Check network stability
GUI shows "File not found"	Mount point dismounted	grep nfs

# Check for NFS errors
grep "nfs: server.*not responding" /var/log/syslog
grep "nfs.*timed out" /var/log/syslog

# Verify mount status
mount | grep nfs
stat /mnt/voipmonitor/sensor1

AI Summary for RAG

Summary: VoIPmonitor deployment guide covering sensor placement (on-host vs dedicated), traffic forwarding methods (SPAN/RSPAN, software tunneling, cloud mirroring), and distributed architectures. Key traffic forwarding options: hardware port mirroring (physical/VMware switches), software tunnels (GRE, ERSPAN, TZSP, VXLAN, HEP, AudioCodes, IPFIX), and cloud provider services (GCP Packet Mirroring, AWS Traffic Mirroring, Azure Virtual Network TAP). CRITICAL HEP LIMITATION: VoIPmonitor does NOT use HEP correlation ID (captureNodeID) - SIP and RTP from different HEP sources will NOT be correlated (feature request VS-1703, no workaround). HEP3 packets with port 0 require adding port 0 to sipport directive. Cloud mirroring requires BIDIRECTIONAL capture (ingress+egress) or CDRs will be incomplete. Distributed architectures: Classic standalone (each sensor writes to central DB, GUI connects to each sensor) vs Modern Client/Server (recommended, encrypted TCP/60024 channel, GUI connects only to central server). Client/Server modes: Local Processing (packetbuffer_sender=no, CDRs only, PCAPs remain remote) vs Packet Mirroring (packetbuffer_sender=yes, full packets sent to central). Alternative for blocked TCP/5029: mount remote spools via NFS/SSHFS, configure multiple paths in GUI Sniffer data path setting. NFS troubleshooting: check for "not responding, timed out" in logs, verify mount status, use hard,nofail,tcp mount options. Critical requirement: NTP sync across all servers.

Keywords: deployment, topology, on-host, dedicated sensor, SPAN, RSPAN, port mirroring, VMware, vSwitch, dvSwitch, tunneling, GRE, ERSPAN, TZSP, VXLAN, HEP, HEP correlation ID, captureNodeID, VS-1703, HEP port 0, sipport, AudioCodes, IPFIX, cloud mirroring, GCP, AWS, Azure, Packet Mirroring, Traffic Mirroring, ingress, egress, bidirectional, client server, packetbuffer_sender, local processing, packet mirroring, TCP 60024, TCP 5029, NFS, SSHFS, sniffer data path, NTP, time synchronization, id_sensor, cdr_partition

Key Questions:

Should I install VoIPmonitor on my PBX or use a dedicated sensor?
How do I configure port mirroring (SPAN) for VoIPmonitor?
How do I configure VMware/ESXi virtual switch mirroring?
What software tunneling protocols does VoIPmonitor support?
How do I configure HEP (Homer Encapsulation Protocol)?
Does VoIPmonitor use HEP correlation ID to correlate SIP and RTP?
Why are SIP and RTP from different HEP sources not correlated?
How do I capture HEP3 packets with port 0?
How do I configure cloud packet mirroring (GCP/AWS/Azure)?
Why do I get incomplete CDRs with cloud mirroring?
What is the difference between classic and client/server deployment?
What is the difference between local processing and packet mirroring mode?
How do I access PCAPs if TCP/5029 is blocked?
How do I configure NFS/SSHFS for remote spool access?
How do I troubleshoot missing data with NFS mounts?
What firewall ports are required for client/server mode?
Why is NTP important for distributed VoIPmonitor?

Sniffing modes: Difference between revisions