Sniffing modes

This guide provides a comprehensive overview of VoIPmonitor's deployment models. It covers the fundamental choice between on-host and dedicated sensors, methods for capturing traffic, and detailed configurations for scalable, multi-site architectures.

Core Concept: Where to Capture Traffic

The first decision in any deployment is where the VoIPmonitor sensor (sniffer) will run.

1. On-Host Capture (on the PBX/SBC)

The sensor can be installed directly on the same Linux server that runs your PBX or SBC.

• Pros: Requires no extra hardware, network changes, or port mirroring. It is the simplest setup.
• Cons: Adds CPU, memory, and disk I/O load to your production voice server. If these resources are critical, a dedicated sensor is the recommended approach.

2. Dedicated Sensor

A dedicated Linux server runs only the VoIPmonitor sensor. This is the recommended approach for production environments as it isolates monitoring resources from your voice platform. To use a dedicated sensor, you must forward a copy of the network traffic to it using one of the methods below.

Methods for Forwarding Traffic to a Dedicated Sensor

A. Hardware Port Mirroring (SPAN/RSPAN)

This is the most common and reliable method. You configure your physical network switch to copy all traffic from the switch ports connected to your PBX/SBC to the switch port connected to the VoIPmonitor sensor. This feature is commonly called Port Mirroring, SPAN, or RSPAN. Consult your switch's documentation for configuration details.

The VoIPmonitor sensor interface will be put into promiscuous mode automatically. To capture from multiple interfaces, set interface = any in voipmonitor.conf and enable promiscuous mode manually on each NIC (e.g., ip link set dev eth1 promisc on).

B. Software-based Tunnelling

When hardware mirroring is not an option, many network devices and PBXs can encapsulate VoIP packets and send them to the sensor's IP address using a tunnel. VoIPmonitor natively supports a wide range of protocols.

• Built-in Support: IP-in-IP, GRE, ERSPAN
• UDP-based Tunnels: Configure the corresponding port in voipmonitor.conf:
  • udp_port_tzsp = 37008 (for MikroTik's TZSP)
  • udp_port_l2tp = 1701
  • udp_port_vxlan = 4789 (common in cloud environments)
• Proprietary & Other Protocols:
  • AudioCodes Tunneling (uses udp_port_audiocodes or tcp_port_audiocodes)
  • HEP (v3+) (enable hep* options)
  • IPFIX (for Oracle SBCs) (enable ipfix* options)

Distributed Deployment Models

For monitoring multiple remote offices or a large infrastructure, a distributed model is essential. This involves a central GUI/Database server collecting data from multiple remote sensors.

Classic Mode: Standalone Remote Sensors

In this traditional model, each remote sensor is a fully independent entity.

• How it works: The remote sensor processes packets and stores PCAPs locally. It connects directly to the central MySQL/MariaDB database to write CDRs. For PCAP retrieval the GUI typically needs network access to each sensor's management port (default TCP/5029).
• Pros: Simple conceptual model.
• Cons: Requires opening firewall ports to each sensor and managing database credentials on every remote machine.

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

This model uses a secure, encrypted TCP channel between remote sensors (clients) and a central sensor instance (server). The GUI communicates with the central server only, which significantly simplifies networking and security.

This architecture supports two primary modes:

1. Local Processing: Remote sensors process packets locally and send only lightweight CDR data over the encrypted channel. PCAPs remain on the remote sensor. On-demand PCAP fetch is proxied via the central server (to the sensor's TCP/5029).
2. Packet Mirroring: Remote sensors forward the entire raw packet stream to the central server, which performs all processing and storage. Ideal for low-resource remote sites.

Architecture Diagrams (PlantUML)

Step-by-Step Configuration Guide

Prerequisites

• VoIPmonitor v20+ on all sensors.
• Central database reachable from the central server instance.
• Unique id_sensor per sensor (< 65536).
• NTP running everywhere (see Time Synchronization below).

Scenario A — Local Processing (default, low WAN usage)

# /etc/voipmonitor.conf on the REMOTE sensor (LOCAL PROCESSING)

id_sensor               = 2          # unique per sensor (< 65536)
server_destination      = 10.224.0.250
server_destination_port = 60024
server_password         = your_strong_password

packetbuffer_sender     = no         # local analysis; sends only CDRs
interface               = eth0       # or: interface = any
sipport                 = 5060       # example; add your usual sniffer options

# No MySQL credentials here — remote sensor does NOT write to DB directly.

# /etc/voipmonitor.conf on the CENTRAL server (LOCAL PROCESSING network)

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        # partitions for CDR tables
mysqlloadconfig         = yes        # allows DB-driven config if used

interface               =            # leave empty to avoid local sniffing
# The central server will proxy on-demand PCAP fetches to sensors (TCP/5029).

Scenario B — Packet Mirroring (centralized processing/storage)

# /etc/voipmonitor.conf on the REMOTE sensor (PACKET MIRRORING)

id_sensor               = 3
server_destination      = 10.224.0.250
server_destination_port = 60024
server_password         = your_strong_password

packetbuffer_sender     = yes        # send RAW packet stream to central
interface               = eth0       # capture source; no DB settings needed

# /etc/voipmonitor.conf on the CENTRAL server (PACKET MIRRORING)

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
mysqlloadconfig         = yes

# As this server does all analysis, configure as if sniffing locally:
sipport                 = 5060
# ... add your usual sniffer/storage options (pcap directories, limits, etc.)

Firewall Checklist (Quick Reference)

• Modern Client/Server (v20+):
  • Central Server: Allow inbound TCP/60024 from remote sensors. Allow inbound TCP/5029 from GUI (management/API to central sensor).
  • Remote Sensors (Local Processing only): Allow inbound TCP/5029 from the central server (for on-demand PCAP fetch via proxy). Outbound TCP/60024 to the central server.
• Cloud Mode:
  • Remote Sensors: Allow outbound TCP/60023 to cloud.voipmonitor.org.

Configuration & Checklists

Parameter Notes (clarifications)

• id_sensor — Mandatory in any distributed deployment (Classic or Client/Server). Must be unique per sensor (< 65536). The value is written to the database and used by the GUI to identify where a call was captured.
• cdr_partition — In Client/Server, enable on the central server instance that writes to the database. It can be disabled on remote "client" sensors that only mirror packets.
• mysqlloadconfig — When enabled, the sensor can load additional parameters dynamically from the sensor_config table in the database. Typically enabled on the central server sensor that writes to DB; keep disabled on remote clients which do not access DB directly.
• interface — Use a specific NIC (e.g., eth0) or any to capture from multiple NICs. For any ensure promiscuous mode on each NIC.

Initial Service Start & Database Initialization

After installation, the first startup against a new/empty database is critical.

1. Start the service: systemctl start voipmonitor
2. Follow logs to ensure schema/partition creation completes:
   • journalctl -u voipmonitor -f
   • or tail -f /var/log/syslog | grep voipmonitor

You should see creation of functions and partitions shortly after start. If you see errors like Table 'cdr_next_1' doesn't exist, the sensor is failing to initialize the schema — usually due to insufficient DB privileges or connectivity. Fix DB access and restart the sensor so it can finish initialization.

Time Synchronization

Accurate and synchronized time is critical for correlating call legs from different sensors. All servers (GUI, DB, and all Sensors) must run an NTP client (e.g., chrony or ntpdate) to keep clocks in sync.

Comparison of Remote Deployment Modes

Deployment Model	Packet Processing Location	PCAP Storage Location	Network Traffic to Central Server	GUI Connectivity
Classic Standalone	Remote	Remote	Minimal (MySQL CDRs)	GUI ↔ each Sensor (management port)
Modern Client/Server (Local Processing)	Remote	Remote	Minimal (Encrypted CDRs)	GUI ↔ Central Server only (central proxies PCAP fetch)
Modern Client/Server (Packet Mirroring)	Central	Central	High (Encrypted full packets)	GUI ↔ Central Server only

FAQ & Common Pitfalls

• Do remote sensors need DB credentials in Client/Server? No. Only the central server instance writes to DB.
• Why is id_sensor required everywhere? The GUI uses it to tag and filter calls by capture source.
• Local Processing still fetches PCAPs from remote — who connects to whom? The GUI requests via the central server; the central server then connects to the remote sensor's TCP/5029 to retrieve the PCAP.

Distributed Architecture: Client-Server and Mirroring Modes

This guide explains how to deploy VoIPmonitor in distributed architectures using client-server mode, packet mirroring, and hybrid configurations.

Overview

VoIPmonitor sniffers can be deployed in multiple architectural patterns:

• Standalone mode: Single instance capturing and analyzing traffic
• Client-Server mode: Multiple clients sending CDRs to central server
• Mirroring mode: Forwarding raw packets to another instance
• Hybrid mode: Combining mirroring with client-server (workaround)

Architecture Diagrams (PlantUML)

Standard Architectures

Multiple Clients to Single Server (Recommended)

This is the standard and fully supported architecture for distributed deployments.

Configuration:

On each client (A, B, C):

server_destination = central.server.ip
server_destination_port = 60024
server_password = shared_secret

On central server:

server_bind = 0.0.0.0
server_bind_port = 60024
server_password = shared_secret

Important notes:

• All clients and the server must use the same server_password
• Clients do not store CDRs to MySQL (they only send to server)
• Server stores all CDRs to MySQL database
• PCAP files are stored on clients by default

Packet Mirroring

Mirror mode forwards raw network packets from one sniffer to another.

<syntaxhighlight> Sensor A ──(packets)──→ Sensor B </syntaxhighlight>

Configuration:

On source sensor A:

mirror_destination = sensor.b.ip
mirror_destination_port = 5090

On receiving sensor B:

mirror_bind = 0.0.0.0
mirror_bind_port = 5090

Use cases:

• Forwarding packets from appliances without VoIPmonitor
• Port mirroring / SPAN to VoIPmonitor instance
• Distributed packet capture with central analysis

Hybrid Chain Configuration (Workaround)

However, a workaround exists using mirroring combined with client mode:

<syntaxhighlight> A (mirror) ──(packets)──→ B (mirror_bind + server_destination) ──(CDRs/packets)──→ C (server) </syntaxhighlight>

Scenario 1: CDR Forwarding

In this configuration, the intermediate sniffer (B) analyzes packets and forwards only CDRs to the central server.

Sensor A (source):

mirror_destination = sensor.b.ip
mirror_destination_port = 5090

Sensor B (intermediate):

mirror_bind = 0.0.0.0
mirror_bind_port = 5090
server_destination = central.server.ip
server_destination_port = 60024
packetbuffer_sender = no

Central Server C:

server_bind = 0.0.0.0
server_bind_port = 60024

Result:

• B analyzes packets from A
• B stores PCAP files locally
• B sends only CDRs to C
• C stores CDRs in MySQL and knows PCAPs are on B

Scenario 2: Packet Forwarding

The intermediate sniffer forwards raw packets instead of CDRs.

Sensor B (intermediate):

mirror_bind = 0.0.0.0
mirror_bind_port = 5090
server_destination = central.server.ip
server_destination_port = 60024
packetbuffer_sender = yes

Result:

• B forwards raw packets from A+B to C
• C analyzes all packets and stores PCAP files
• C stores CDRs in MySQL

Compression for Mirroring

When using mirror mode, compression can reduce network bandwidth:

packetbuffer_compress = yes
packetbuffer_compress_ratio = 100
max_buffer_mem = 2000

Adjust packetbuffer_compress_ratio if CPU becomes a bottleneck.

GUI Visibility

Automatic visibility:

• Client-server mode: Only the central server appears in GUI
• Hybrid chain: Only the final server (C) and intermediate forwarder (B) appear

Manual sensor registration:

If you want sensor A to appear in GUI (for RRD charts, remote upgrades):

1. Go to GUI → Settings → Sensors
2. Add sensor A manually with its manager_ip:manager_port
3. Ensure manager_aes_key and manager_aes_iv match GUI database values

Performance Optimization

Client-Server Mode for Better Performance

Switching from standalone to client-server architecture can significantly improve MySQL insert performance:

1. Centralized writes: Single server instance handles all MySQL inserts (reduces lock contention)
2. Enable mysql_enable_set_id: Let application handle ID auto-increment instead of MySQL
3. Optimize MySQL configuration: Tune innodb_flush_log_at_trx_commit, innodb_io_capacity, etc.

Migration steps:

1. Configure server: Set server_bind, server_bind_port, server_password
2. Initially set mysql_enable_set_id = no on server
3. Migrate sniffers one by one: Set server_destination, remove mysqlhost
4. After all sniffers migrated: Enable mysql_enable_set_id = yes on server and restart

SRTP/DTLS Decryption in Mirror Mode

When using mirror mode, ensure SSL/TLS decryption is configured correctly:

On source sniffer (with mirror_destination):

sipport = 5060,5061

This ensures TCP packets (including TLS handshakes) are also mirrored.

On receiving sniffer (with mirror_bind):

Configure SSL decryption options here:

ssl_ipport = ...
ssl_sessionkey = ...

Important Limitations

Key limitations:

1. server_bind and server_destination cannot coexist in one instance
2. Hybrid chain architecture is unstable across sniffer versions
3. No per-client authentication (same password for all clients)
4. Recommended: Use standard multiple clients → single server architecture

Future Enhancement (VS-1605)

A future release may support native dual-mode operation with these new options:

# Server mode (receive connections)
server_bind = 0.0.0.0
server_bind_port = 60024
server_bind_password = receive_secret

# Client mode (send to upstream)
server_destination = upstream.ip
server_destination_port = 60025
server_destination_password = send_secret

# Enable both modes
server_dual_mode = yes

This would enable clean multi-tier architectures without workarounds.

AI Summary for RAG

Summary: This guide explains how to deploy VoIPmonitor in distributed architectures using standalone, client-server, packet mirroring, and hybrid chain topologies. It documents how multiple remote sensors can send data to a central server, how mirror mode forwards raw packets between sniffers, and how a workaround combines mirroring with client mode to build multi-tier chains. The article clarifies where CDRs and PCAPs are stored in each scenario, how sensors appear in the GUI, how to manually register sensors, and how to optimize MySQL and VoIPmonitor configuration when migrating to client-server mode for better performance. It also covers SRTP/DTLS decryption in mirror mode, current limitations (such as lack of dual-mode server/client in one process), and a proposed future enhancement (VS-1605) that would enable clean multi-hop deployments without workarounds. Keywords: distributed architecture, client-server mode, mirror mode, hybrid chain, remote sensor, CDR forwarding, packet mirroring, packetbuffer_sender, compression, MySQL performance, SRTP, DTLS, GUI sensors, manager_ip, scalability, multi-site monitoring Key Questions:

• How do I connect multiple VoIPmonitor sensors to a single central server using client-server mode?
• When should I use packet mirroring instead of sending only CDRs from remote sensors?
• How are CDRs and PCAP files stored and accessed in client-server versus hybrid chain configurations?
• What are the limitations of combining server_bind and server_destination in a single sniffer instance?
• How can I optimize MySQL and VoIPmonitor settings when migrating from standalone to client-server architecture?
• How do I ensure that all sensors are visible in the GUI and correctly registered for remote management?
• What are the current constraints and future plans (VS-1605) for native multi-tier VoIPmonitor deployments?