Sniffing modes: Difference between revisions

From VoIPmonitor.org
Tag: Reverted
(Add note about deduplicate_ipheader in packetbuffer_sender mode (New in 2026.1))
 
(23 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{DISPLAYTITLE:VoIPmonitor Deployment & Topology Guide}}
{{DISPLAYTITLE:VoIPmonitor Deployment & Topology Guide}}


'''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.'''
This guide covers VoIPmonitor deployment options: where to install the sensor, how to forward traffic, and distributed architectures for multi-site monitoring.


== Core Concept: Where to Capture Traffic ==
<kroki lang="mermaid">
The first decision in any deployment is where the VoIPmonitor sensor (sniffer) will run.
%%{init: {'flowchart': {'nodeSpacing': 15, 'rankSpacing': 30}}}%%
flowchart TB
    START[Where to deploy sensor?] --> Q1{PBX runs on Linux?}
    Q1 -->|Yes| Q2{Spare resources?}
    Q1 -->|No - Windows| DED[Dedicated Sensor]
    Q2 -->|Yes| ONHOST[On-Host Capture]
    Q2 -->|No| DED


=== 1. On-Host Capture (on the PBX/SBC) ===
    DED --> Q3{Traffic forwarding method?}
The sensor can be installed directly on the same Linux server that runs your PBX or SBC.
    Q3 --> SPAN[SPAN/RSPAN]
* '''Pros:''' Requires no extra hardware, network changes, or port mirroring. It is the simplest setup.
    Q3 --> TUNNEL[Software Tunnel]
* '''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.
    Q3 --> CLOUD[Cloud Mirroring]


=== 2. Dedicated Sensor ===
    TUNNEL --> T1[GRE/ERSPAN]
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.
    TUNNEL --> T2[TZSP/VXLAN]
    TUNNEL --> T3[HEP/AudioCodes]
</kroki>


== Methods for Forwarding Traffic to a Dedicated Sensor ==
= Sensor Deployment Options =


=== A. Hardware Port Mirroring (SPAN/RSPAN) ===
== On-Host Capture ==
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 <code>interface = any</code> in <code>voipmonitor.conf</code> and enable promiscuous mode manually on each NIC (e.g., <code>ip link set dev eth1 promisc on</code>).
Install the sensor directly on the same Linux server as your PBX/SBC.


=== B. Software-based Tunnelling ===
{| class="wikitable"
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.
! Pros !! Cons
* '''Built-in Support:''' IP-in-IP, GRE, ERSPAN
|-
* '''UDP-based Tunnels:''' Configure the corresponding port in <code>voipmonitor.conf</code>:
| No extra hardware, network changes, or port mirroring required || Adds CPU, memory, and disk I/O load to production voice server
** <code>udp_port_tzsp = 37008</code> (for MikroTik's TZSP)
|-
** <code>udp_port_l2tp = 1701</code>
| Simplest setup || Not suitable if resources are critical
** <code>udp_port_vxlan = 4789</code> (common in cloud environments)
|}
* '''Proprietary & Other Protocols:'''
** [[audiocodes tunneling|AudioCodes Tunneling]] (uses <code>udp_port_audiocodes</code> or <code>tcp_port_audiocodes</code>)
** HEP (v3+) (enable <code>hep*</code> options)
** IPFIX (for Oracle SBCs) (enable <code>ipfix*</code> options)


== Distributed Deployment Models ==
{{Note|1=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.}}
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 ===
== Dedicated Sensor ==
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 <code>TCP/5029</code>).
* '''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 ===
A separate Linux server runs only VoIPmonitor. '''Recommended for production environments''' as it isolates monitoring from voice platform resources.
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:
'''When Required:'''
# '''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 <code>TCP/5029</code>).
* Windows-based PBXs
# '''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.
* Limited CPU/RAM/disk I/O on PBX server
* Zero monitoring impact needed
* Centralized capture from multiple sites


==== Architecture Diagrams (PlantUML) ====
= Traffic Forwarding Methods =


<kroki lang="plantuml">
When using a dedicated sensor, you must forward traffic to it using one of these methods.
  @startuml
  skinparam shadowing false
  skinparam defaultFontName Arial
  skinparam rectangle {
    BorderColor #4A90E2
    BackgroundColor #FFFFFF
    stereotypeFontColor #333333
  }
  skinparam packageBorderColor #B0BEC5
  skinparam packageBackgroundColor #F7F9FC


  title Client/Server Architecture — Local Processing Mode
== Hardware Port Mirroring (SPAN/RSPAN) ==


  package "Remote Site" {
Physical or virtual switches copy traffic from source port(s) to a monitoring port.
    [Remote Probe/Sensor] as Remote
    database "Local Storage (PCAP)" as RemotePCAP
  }


  package "Central Site" {
=== Physical Switch ===
    [Central VoIPmonitor Server] as Central
    database "Central MySQL/MariaDB" as CentralDB
    [Web GUI] as GUI
  }


  Remote -[#2F6CB0]-> Central : Encrypted TCP/60024\nCDRs only
Configure your switch to mirror traffic from PBX/SBC ports to the sensor's port. Consult your switch documentation for specific commands.
  Remote --> RemotePCAP : Stores PCAP locally
  Central --> CentralDB : Writes CDRs
  GUI -[#2F6CB0]-> Central : Queries data & requests PCAPs
  Central -[#2F6CB0]-> RemotePCAP : Fetches PCAPs on demand (TCP/5029)
  @enduml
  </kroki>


<kroki lang="plantuml">
<syntaxhighlight lang="ini">
  @startuml
# /etc/voipmonitor.conf
  skinparam shadowing false
interface = eth0
  skinparam defaultFontName Arial
sipport = 5060
  skinparam rectangle {
savertp = yes
    BorderColor #4A90E2
</syntaxhighlight>
    BackgroundColor #FFFFFF
    stereotypeFontColor #333333
  }
  skinparam packageBorderColor #B0BEC5
  skinparam packageBackgroundColor #F7F9FC
 
  title Client/Server Architecture — Packet Mirroring Mode


  package "Remote Site" {
{{Tip|To capture from multiple interfaces, set <code>interface = any</code> and enable promiscuous mode on each NIC: <code>ip link set dev eth1 promisc on</code>}}
    [Remote Probe/Sensor\n(Low Resource)] as Remote
  }


  package "Central Site" {
=== VMware/ESXi Virtual Switch ===
    [Central VoIPmonitor Server] as Central
    database "Central MySQL/MariaDB" as CentralDB
    database "Central Storage (PCAP)" as CentralPCAP
    [Web GUI] as GUI
  }


  Remote -[#2F6CB0]-> Central : Encrypted TCP/60024\nRaw packet stream
For virtualized environments, VMware provides port mirroring at the virtual switch level.
  Central --> CentralDB : Writes CDRs
  Central --> CentralPCAP : Processes & stores PCAPs
  GUI -[#2F6CB0]-> Central : Queries data & downloads PCAPs
  @enduml
  </kroki>


==== Step-by-Step Configuration Guide ====
'''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


; Prerequisites
'''Distributed vSwitch:'''
* VoIPmonitor v20+ on all sensors.
# In vSphere Web Client → Networking → Select distributed switch
* Central database reachable from the central server instance.
# Configure tab → Port Mirroring → Create mirroring session
* Unique <code>id_sensor</code> per sensor (< 65536).
# Specify source/destination ports and enable
* NTP running everywhere (see '''Time Synchronization''' below).


; Scenario A — Local Processing (default, low WAN usage)
{{Note|1=Distributed switch mirroring can span multiple ESXi hosts within a cluster.}}
<pre>
# /etc/voipmonitor.conf on the REMOTE sensor (LOCAL PROCESSING)


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


packetbuffer_sender    = no        # local analysis; sends only CDRs
Monitor multiple platforms (e.g., Mitel + FreeSWITCH) with a single sensor by mirroring multiple source ports to one destination port.
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.
'''GUI differentiation:'''
</pre>
* Filter by IP address ranges
* Filter by number prefixes
* Use separate sensors with unique <code>id_sensor</code> values


<pre>
{{Warning|1='''Critical:''' When sniffing from multiple mirrored sources, packets may arrive as duplicates. Add <code>auto_enable_use_blocks = yes</code> to voipmonitor.conf to enable automatic deduplication. See [[Sniffer_configuration#auto_enable_use_blocks|Sniffer_configuration]] for details.}}
# /etc/voipmonitor.conf on the CENTRAL server (LOCAL PROCESSING network)


server_bind            = 0.0.0.0
== Software-based Tunneling ==
server_bind_port        = 60024
server_password        = your_strong_password


mysqlhost              = 10.224.0.201
When hardware mirroring is unavailable, use software tunneling to encapsulate and forward packets.
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).
</pre>
; Scenario B — Packet Mirroring (centralized processing/storage)
<pre>
# /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
</pre>
<pre>
# /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.)
</pre>
==== Firewall Checklist (Quick Reference) ====
* '''Modern Client/Server (v20+):'''
** '''Central Server:''' Allow inbound <code>TCP/60024</code> from remote sensors. Allow inbound <code>TCP/5029</code> from GUI (management/API to central sensor).
** '''Remote Sensors (Local Processing only):''' Allow inbound <code>TCP/5029</code> from the central server (for on-demand PCAP fetch via proxy). Outbound <code>TCP/60024</code> to the central server.
* '''Cloud Mode:'''
** '''Remote Sensors:''' Allow outbound <code>TCP/60023</code> to <code>cloud.voipmonitor.org</code>.
== Configuration & Checklists ==
=== Parameter Notes (clarifications) ===
* '''<code>id_sensor</code>''' — 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.
* '''<code>cdr_partition</code>''' — 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.
* '''<code>mysqlloadconfig</code>''' — When enabled, the sensor can load additional parameters dynamically from the <code>sensor_config</code> 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.
* '''<code>interface</code>''' — Use a specific NIC (e.g., <code>eth0</code>) or <code>any</code> to capture from multiple NICs. For <code>any</code> ensure promiscuous mode on each NIC.
=== Initial Service Start & Database Initialization ===
After installation, the '''first startup''' against a new/empty database is critical.
# Start the service: <code>systemctl start voipmonitor</code>
# Follow logs to ensure schema/partition creation completes:
#* <code>journalctl -u voipmonitor -f</code>
#* or <code>tail -f /var/log/syslog | grep voipmonitor</code>
You should see creation of functions and partitions shortly after start. If you see errors like <code>Table 'cdr_next_1' doesn't exist</code>, 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., <code>chrony</code> or <code>ntpdate</code>) to keep clocks in sync.
== Comparison of Remote Deployment Modes ==
{| class="wikitable"
{| class="wikitable"
! Deployment Model
! Protocol !! Configuration Parameter !! Notes
! Packet Processing Location
|-
! PCAP Storage Location
| IP-in-IP, GRE, ERSPAN || Built-in (auto-detected) || No additional config needed
! Network Traffic to Central Server
|-
! GUI Connectivity
| TZSP (MikroTik) || <code>udp_port_tzsp = 37008</code> ||
|-
| L2TP || <code>udp_port_l2tp = 1701</code> ||
|-
|-
| Classic Standalone
| VXLAN || <code>udp_port_vxlan = 4789</code> || Common in cloud environments
| Remote
| Remote
| Minimal (MySQL CDRs)
| GUI ↔ each Sensor (management port)
|-
|-
| '''Modern Client/Server (Local Processing)'''
| AudioCodes || <code>udp_port_audiocodes = 925</code> || See [[Audiocodes_tunneling|AudioCodes Tunneling]]
| Remote
| Remote
| Minimal (Encrypted CDRs)
| '''GUI ↔ Central Server only''' (central proxies PCAP fetch)
|-
|-
| '''Modern Client/Server (Packet Mirroring)'''
| IPFIX (Oracle SBCs) || <code>ipfix*</code> options || Enable ipfix options in config
| '''Central'''
| '''Central'''
| High (Encrypted full packets)
| '''GUI ↔ Central Server only'''
|}
|}


== FAQ & Common Pitfalls ==
=== HEP (Homer Encapsulation Protocol) ===
* '''Do remote sensors need DB credentials in Client/Server?''' No. Only the central server instance writes to DB.
* '''Why is <code>id_sensor</code> 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 <code>TCP/5029</code> to retrieve the PCAP.


=Distributed Architecture: Client-Server and Mirroring Modes=
Lightweight protocol for mirroring VoIP packets. Supported by Kamailio, OpenSIPS, FreeSWITCH, and many SBCs.


This guide explains how to deploy VoIPmonitor in distributed architectures using client-server mode, packet mirroring, and hybrid configurations.
<syntaxhighlight lang="ini">
# /etc/voipmonitor.conf
hep = yes
hep_bind_port = 9060
hep_bind_udp = yes
# Optional: hep_kamailio_protocol_id_fix = yes
</syntaxhighlight>


==Overview==
'''SIP and RTP Correlation from Multiple HEP Sources:'''


VoIPmonitor sniffers can be deployed in multiple architectural patterns:
VoIPmonitor correlates calls using standard SIP Call-ID, To/From tags, and RTP streams are matched based on IP:port from SDP.


* '''Standalone mode''': Single instance capturing and analyzing traffic
{{Note|1='''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.
* '''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) ====
'''Example:''' Kamailio sends SIP via HEP → VoIPmonitor + rtpproxy sends RTP via HEP → same VoIPmonitor = Complete CDRs with SIP+RTP}}


<kroki lang="plantuml">
{{Tip|1='''Client/Server mode also supported:''' A sniffer client can receive HEP packets and forward them to a central sniffer server using <code>packetbuffer_sender=yes</code>. The central server then correlates SIP and RTP from all sources. This works for HEP, IPFIX, and RibbonSBC protocols.}}
  @startuml
  skinparam shadowing false
  skinparam defaultFontName Arial
  skinparam rectangle {
    BorderColor #4A90E2
    BackgroundColor #FFFFFF
    stereotypeFontColor #333333
  }


  title Multiple Clients → Single Server (Client-Server Mode)
'''HEP Header Fields:'''


  rectangle "Sensor A\n(client)" as A
{| class="wikitable"
  rectangle "Sensor B\n(client)" as B
! HEP Field !! Present In !! Current Usage
  rectangle "Sensor C\n(client)" as C
|-
  rectangle "Central Server\n(server_bind)" as S
| <code>correlation_id</code> || INVITE only || Parsed but not used
|-
| <code>capture_node_id</code> || All SIP packets || Parsed but not used
|}


  A --> S : CDRs
{{Note|1='''Feature Request VS-1703:''' Option to set CDR <code>id_sensor</code> from HEP <code>correlation_id</code> or <code>capture_node_id</code> headers. This would allow sensor attribution based on the originating HEP source when SIP arrives via HEP but RTP comes from different sensors. [https://jira.voipmonitor.org/browse/VS-1703 Track status]}}
  B --> S : CDRs
  C --> S : CDRs


  note right of S
'''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.
    Stores all CDRs to MySQL
    PCAPs remain on sensors by default
  end note


  @enduml
'''HEP3 with Port 0:''' Not captured by default. Add port 0 to sipport:
</kroki>


<kroki lang="plantuml">
<syntaxhighlight lang="ini">
  @startuml
sipport = 0,5060
  skinparam shadowing false
</syntaxhighlight>
  skinparam defaultFontName Arial
==== HEP/IPFIX Timestamp Options ====


  title Packet Mirroring (Sensor A → Sensor B)
'''(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:


  rectangle "Sensor A\n(source capture)" as A
<syntaxhighlight lang="ini">
  rectangle "Sensor B\n(receiver / analysis)" as B
# /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
</syntaxhighlight>


  A -[#black]-> B : mirrored packets\n(SIP, RTP, TCP, TLS)
'''Use case:''' Debugging packet timing issues when combining HEP with PCAP replay or when HEP sources have clock drift.
== Cloud Packet Mirroring ==


  note right of B
Cloud providers offer native mirroring services using VXLAN or GRE encapsulation.
    Analyzes mirrored traffic
    Can store CDRs and PCAPs
  end note


  @enduml
{| class="wikitable"
</kroki>
! Provider !! Service Name
|-
| Google Cloud || Packet Mirroring
|-
| AWS || Traffic Mirroring
|-
| Azure || Virtual Network TAP
|}


<kroki lang="plantuml">
'''Configuration Steps:'''
  @startuml
  skinparam shadowing false
  skinparam defaultFontName Arial


  title Hybrid Chain (Mirror + Client)
# 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:


  rectangle "Sensor A\nmirror_destination" as A
<syntaxhighlight lang="ini">
  rectangle "Sensor B\nmirror_bind +\nserver_destination" as B
udp_port_vxlan = 4789
  rectangle "Central Server C\nserver_bind" as C
interface = eth0
 
sipport = 5060
  A -[#black]-> B : mirrored packets
</syntaxhighlight>
  B -[#black]-> C : CDRs and/or packets


  note right of B
{{Warning|1=Capturing only ingress or only egress results in incomplete CDRs and broken call data.}}
    Workaround only
    Not officially supported
  end note


  @enduml
'''Best Practices:'''
</kroki>
* 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


==Standard Architectures==
'''Alternative:''' Consider [[Sniffer_distributed_architecture|Client/Server architecture]] with on-host sensors instead of cloud mirroring for better performance.


===Multiple Clients to Single Server (Recommended)===
== Pre-Deployment Verification ==


This is the standard and fully supported architecture for distributed deployments.
For complex setups (RSPAN, ERSPAN, proprietary SBCs), verify compatibility before production deployment:


<kroki lang="plantuml">
# Configure test mirroring with a subset of traffic
  @startuml
# Capture test calls with tcpdump: <code>sudo tcpdump -i eth0 -s0 port 5060 -w /tmp/test.pcap</code>
  title Multiple Clients → Single Server
# Verify pcap contains SIP and RTP: <code>tshark -r /tmp/test.pcap -Y "sip || rtp"</code>
  rectangle "Sensor A\n(client)" as A
# Submit pcap to VoIPmonitor support with hardware/configuration details
  rectangle "Sensor B\n(client)" as B
  rectangle "Sensor C\n(client)" as C
  rectangle "Central Server\n(server_bind)" as S


  A --> S : CDRs
= Distributed Architectures =
  B --> S : CDRs
  C --> S : CDRs
  @enduml
</kroki>


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


On each client (A, B, C):
== Classic Mode: Standalone Sensors ==
<pre>
server_destination = central.server.ip
server_destination_port = 60024
server_password = shared_secret
</pre>


On central server:
Each sensor operates independently:
<pre>
* Processes packets and stores PCAPs locally
server_bind = 0.0.0.0
* Connects directly to central MySQL to write CDRs
server_bind_port = 60024
* GUI needs network access to each sensor's <code>TCP/5029</code> for PCAP retrieval
server_password = shared_secret
</pre>


'''Important notes:'''
'''Alternative: NFS/SSHFS Mounting'''
* All clients and the server must use the same <code>server_password</code>
* 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===
If TCP/5029 access is blocked, mount remote spool directories on the GUI server:


Mirror mode forwards raw network packets from one sniffer to another.
<syntaxhighlight lang="bash">
# NFS mount
sudo mount -t nfs 10.224.0.101:/var/spool/voipmonitor /mnt/voipmonitor/sensor1


<syntaxhighlight>
# SSHFS mount
Sensor A ──(packets)──→ Sensor B
sshfs voipmonitor@10.224.0.101:/var/spool/voipmonitor /mnt/voipmonitor/sensor1
</syntaxhighlight>
</syntaxhighlight>


<kroki lang="plantuml">
Configure GUI: '''Settings > System Configuration > Sniffer data path:'''
  @startuml
<code>/var/spool/voipmonitor:/mnt/voipmonitor/sensor1:/mnt/voipmonitor/sensor2</code>
  title Packet Mirroring (A → B)
  rectangle "Sensor A\n(source)" as A
  rectangle "Sensor B\n(receiver)" as B


  A --> B : mirrored packets
{{Tip|For NFS, use <code>hard,nofail,tcp</code> mount options for reliability.}}
  @enduml
</kroki>


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


On source sensor A:
Secure encrypted TCP channel between remote sensors and central server. GUI communicates only with central server.
<pre>
mirror_destination = sensor.b.ip
mirror_destination_port = 5090
</pre>


On receiving sensor B:
<kroki lang="mermaid">
<pre>
%%{init: {'flowchart': {'nodeSpacing': 10, 'rankSpacing': 25}}}%%
mirror_bind = 0.0.0.0
flowchart LR
mirror_bind_port = 5090
    subgraph "Local Processing"
</pre>
        R1[Remote Sensor] -->|CDRs only| C1[Central Server]
        R1 -.->|PCAP on demand| C1
    end


'''Use cases:'''
    subgraph "Packet Mirroring"
* Forwarding packets from appliances without VoIPmonitor
        R2[Remote Sensor] -->|Raw packets| C2[Central Server]
* Port mirroring / SPAN to VoIPmonitor instance
    end
* Distributed packet capture with central analysis
</kroki>


==Hybrid Chain Configuration (Workaround)==
{| class="wikitable"
! Mode !! Processing !! PCAP Storage !! WAN Traffic !! Best For
|-
| '''Local Processing''' (<code>packetbuffer_sender=no</code>) || Remote || Remote || Low (CDRs only) || Limited WAN bandwidth
|-
| '''Packet Mirroring''' (<code>packetbuffer_sender=yes</code>) || Central || Central || High (full packets) || Low-resource remote sites
|}


{{Warning|A single sniffer instance '''cannot''' operate in both client and server modes simultaneously using <code>server_bind</code> + <code>server_destination</code>. These options are mutually exclusive.}}
For detailed configuration, see [[Sniffer_distributed_architecture|Distributed Architecture: Client-Server Mode]].


However, a '''workaround exists''' using mirroring combined with client mode:
'''Quick Start - Remote Sensor (Local Processing):'''


<syntaxhighlight>
<syntaxhighlight lang="ini">
A (mirror) ──(packets)──→ B (mirror_bind + server_destination) ──(CDRs/packets)──→ C (server)
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
</syntaxhighlight>
</syntaxhighlight>


<kroki lang="plantuml">
'''Quick Start - Central Server:'''
  @startuml
  title Hybrid Chain A → B → C
  rectangle "Sensor A\n(mirror_destination)" as A
  rectangle "Sensor B\n(mirror_bind +\nserver_destination)" as B
  rectangle "Server C\n(server_bind)" as C


  A --> B : packets
<syntaxhighlight lang="ini">
   B --> C : CDRs / packets
server_bind            = 0.0.0.0
  @enduml
server_bind_port        = 60024
</kroki>
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
</syntaxhighlight>
{{Note|1='''Deduplication in Packet Mirroring mode (New in 2026.1):''' When using <code>packetbuffer_sender=yes</code> with <code>deduplicate_ipheader=ip_only</code> on the server, the server now automatically sends this parameter to clients. For older versions, set <code>deduplicate_ipheader=ip_only</code> on '''both''' server AND client to ensure consistent hash calculation.}}
== Firewall Requirements ==


===Scenario 1: CDR Forwarding===
{| class="wikitable"
! 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
|}


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


'''Sensor A (source):'''
== Critical Parameters ==
<pre>
mirror_destination = sensor.b.ip
mirror_destination_port = 5090
</pre>


'''Sensor B (intermediate):'''
{| class="wikitable"
<pre>
! Parameter !! Description !! Notes
mirror_bind = 0.0.0.0
|-
mirror_bind_port = 5090
| <code>id_sensor</code> || Unique sensor identifier (1-65535) || '''Mandatory''' in distributed deployments
server_destination = central.server.ip
|-
server_destination_port = 60024
| <code>cdr_partition</code> || Enable daily CDR table partitions || Enable on server writing to DB
packetbuffer_sender = no
|-
</pre>
| <code>mysqlloadconfig</code> || Load config from database || Enable on central server only
|-
| <code>interface</code> || Capture interface || Use specific NIC or <code>any</code>
|}


'''Central Server C:'''
== Time Synchronization ==
<pre>
server_bind = 0.0.0.0
server_bind_port = 60024
</pre>


'''Result:'''
{{Warning|1=Accurate NTP sync is '''critical''' for correlating call legs across sensors. All servers (GUI, DB, sensors) must run NTP client (chrony or ntpd).}}
* 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===
== First Startup ==


The intermediate sniffer forwards raw packets instead of CDRs.
On first start against empty database:
# Start service: <code>systemctl start voipmonitor</code>
# Monitor logs: <code>journalctl -u voipmonitor -f</code>
# Wait for schema/partition creation to complete


'''Sensor B (intermediate):'''
If you see <code>Table 'cdr_next_1' doesn't exist</code> errors, check DB connectivity and privileges.
<pre>
mirror_bind = 0.0.0.0
mirror_bind_port = 5090
server_destination = central.server.ip
server_destination_port = 60024
packetbuffer_sender = yes
</pre>


'''Result:'''
= Deployment Comparison =
* 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===
{| class="wikitable"
! 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'''
|}


When using mirror mode, compression can reduce network bandwidth:
= Troubleshooting =


<pre>
== NFS/SSHFS Connectivity ==
packetbuffer_compress = yes
packetbuffer_compress_ratio = 100
max_buffer_mem = 2000
</pre>


Adjust <code>packetbuffer_compress_ratio</code> if CPU becomes a bottleneck.
Missing data for specific time periods usually indicates storage server connectivity issues.


==GUI Visibility==
{| class="wikitable"
! 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 || Verify mount with <code>mount | grep nfs</code>
|}


'''Automatic visibility:'''
<syntaxhighlight lang="bash">
* Client-server mode: Only the central server appears in GUI
# Check for NFS errors
* Hybrid chain: Only the final server (C) and intermediate forwarder (B) appear
grep "nfs: server.*not responding" /var/log/syslog
grep "nfs.*timed out" /var/log/syslog


'''Manual sensor registration:'''
# Verify mount status
 
mount | grep nfs
If you want sensor A to appear in GUI (for RRD charts, remote upgrades):
stat /mnt/voipmonitor/sensor1
 
</syntaxhighlight>
# Go to GUI → Settings → Sensors
# Add sensor A manually with its <code>manager_ip:manager_port</code>
# Ensure <code>manager_aes_key</code> and <code>manager_aes_iv</code> 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:
 
# '''Centralized writes''': Single server instance handles all MySQL inserts (reduces lock contention)
# '''Enable <code>mysql_enable_set_id</code>''': Let application handle ID auto-increment instead of MySQL
# '''Optimize MySQL configuration''': Tune <code>innodb_flush_log_at_trx_commit</code>, <code>innodb_io_capacity</code>, etc.
 
'''Migration steps:'''
# Configure server: Set <code>server_bind</code>, <code>server_bind_port</code>, <code>server_password</code>
# Initially set <code>mysql_enable_set_id = no</code> on server
# Migrate sniffers one by one: Set <code>server_destination</code>, remove <code>mysqlhost</code>
# After all sniffers migrated: Enable <code>mysql_enable_set_id = yes</code> 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):'''
= See Also =
<pre>
sipport = 5060,5061
</pre>


This ensures TCP packets (including TLS handshakes) are also mirrored.
* [[Sniffer_distributed_architecture|Distributed Architecture: Client-Server Mode]] - Detailed client/server configuration
* [[Sniffer_troubleshooting|Sniffer Troubleshooting]] - Diagnostic procedures
* [[Audiocodes_tunneling|AudioCodes Tunneling]] - AudioCodes SBC integration
* [[Tls|TLS/SRTP Decryption]] - Encrypted traffic monitoring
* [[Cloud|Cloud Service Configuration]] - Cloud deployment specifics
* [[Scaling|Scaling and Performance Tuning]] - Performance optimization


'''On receiving sniffer (with mirror_bind):'''


Configure SSL decryption options here:
<pre>
ssl_ipport = ...
ssl_sessionkey = ...
</pre>


==Important Limitations==


{{Warning|The hybrid chain workaround is '''not officially supported''' and may not work in future sniffer releases.}}
= AI Summary for RAG =


'''Key limitations:'''
'''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.
# <code>server_bind</code> and <code>server_destination</code> cannot coexist in one instance
# Hybrid chain architecture is unstable across sniffer versions
# No per-client authentication (same password for all clients)
# Recommended: Use standard multiple clients → single server architecture


==Future Enhancement (VS-1605)==
'''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


A future release may support native dual-mode operation with these new options:
<pre>
# 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
</pre>
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:'''
'''Key Questions:'''
* How do I connect multiple VoIPmonitor sensors to a single central server using client-server mode?
* Should I install VoIPmonitor on my PBX or use a dedicated sensor?
* When should I use packet mirroring instead of sending only CDRs from remote sensors?
* How do I configure port mirroring (SPAN) for VoIPmonitor?
* How are CDRs and PCAP files stored and accessed in client-server versus hybrid chain configurations?
* How do I configure VMware/ESXi virtual switch mirroring?
* What are the limitations of combining <code>server_bind</code> and <code>server_destination</code> in a single sniffer instance?
* What software tunneling protocols does VoIPmonitor support?
* How can I optimize MySQL and VoIPmonitor settings when migrating from standalone to client-server architecture?
* How do I configure HEP (Homer Encapsulation Protocol)?
* How do I ensure that all sensors are visible in the GUI and correctly registered for remote management?
* Does VoIPmonitor use HEP correlation ID to correlate SIP and RTP?
* What are the current constraints and future plans (VS-1605) for native multi-tier VoIPmonitor deployments?
* Why are SIP and RTP from different HEP sources not correlated?
 
* How do I capture HEP3 packets with port 0?
==See Also==
* How do I configure cloud packet mirroring (GCP/AWS/Azure)?
 
* Why do I get incomplete CDRs with cloud mirroring?
* [[Configuration Parameters]]
* What is the difference between classic and client/server deployment?
* [[Installation Guide]]
* What is the difference between local processing and packet mirroring mode?
* [[Performance Tuning]]
* How do I access PCAPs if TCP/5029 is blocked?
 
* How do I configure NFS/SSHFS for remote spool access?
[[Category:Configuration]]
* How do I troubleshoot missing data with NFS mounts?
[[Category:Installation]]
* What firewall ports are required for client/server mode?
[[Category:Architecture]]
* Why is NTP important for distributed VoIPmonitor?

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:

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

Distributed vSwitch:

  1. In vSphere Web Client → Networking → Select distributed switch
  2. Configure tab → Port Mirroring → Create mirroring session
  3. 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:

  1. Create a VoIPmonitor sensor VM in your cloud environment
  2. Create mirroring policy: select source VMs/subnets, set destination to sensor VM
  3. Critical: Capture traffic in BOTH directions (INGRESS and EGRESS)
  4. 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:

  1. Configure test mirroring with a subset of traffic
  2. Capture test calls with tcpdump: sudo tcpdump -i eth0 -s0 port 5060 -w /tmp/test.pcap
  3. Verify pcap contains SIP and RTP: tshark -r /tmp/test.pcap -Y "sip || rtp"
  4. 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:

  1. Start service: systemctl start voipmonitor
  2. Monitor logs: journalctl -u voipmonitor -f
  3. 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

See Also



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?
Retrieved from "https://www.voipmonitor.org/doc/index.php?title=Sniffing_modes&oldid=10843"