Sniffer configuration

From VoIPmonitor.org
Revision as of 02:11, 9 January 2026 by Admin (talk | contribs) (Add: Database schema upgrade safety mechanism (1000 CDR threshold))


Comprehensive reference for `/etc/voipmonitor.conf` parameters. Additional configuration snippets can be placed in `/etc/voipmonitor/conf.d/` (without `[general]` header).

Related documentation:

General & Core Settings

Sensor Identification & Time

Parameter Default Description
id_sensor unset Unique numeric identifier (1-65535). Essential for multi-sensor deployments.
utc no Store timestamps in UTC. Recommended for multi-timezone deployments.
timezone system Override system timezone with zoneinfo path (e.g., /usr/share/zoneinfo/UTC).

Process Management

Parameter Default Description
watchdog no Auto-restart sensor on crash.
watchdog_run_command unset Custom restart command (e.g., systemctl restart voipmonitor).

Deprecated Options (v2025.09.1+)

⚠️ Warning: The following options are unsupported and ignored in sniffer version 2025.09.1+. Remove them from your configuration.

Deprecated Option Modern Replacement
vxlan, vxlan_port, vxlan_skipcrc udp_port_vxlan = 4789
packet_buffer_total_size max_buffer_mem (auto-managed)
udp_reassembly, udp_reassembly_max_size udpfrag = yes
sipdefrag, sipdefrag_maxpacket, defragment_* Auto-managed; use max_sip_packets_in_call
max_sip_size, interface_snaplen snaplen = 3200
sanity_checks, check_sip_header, ignore_sip_parsing_errors Built-in (cannot be disabled)

💡 Tip: After removing deprecated options, check logs for warnings: journalctl -u voipmonitor -f

Database Configuration

Connection Settings

Parameter Default Description
mysqlhost localhost MySQL/MariaDB server address
mysqlsocket unset Socket path for local connections (faster than TCP)
mysqlport 3306 TCP port
mysqlusername root Database username
mysqlpassword empty Database password
mysqldb voipmonitor Database name (auto-created if missing)
mysql_reconnect no Auto-reconnect on connection loss

SSL/TLS for Database

mysqlsslkey = /etc/ssl/client-key.pem
mysqlsslcert = /etc/ssl/client-cert.pem
mysqlsslcacert = /etc/ssl/ca-cert.pem

Performance & Schema

Parameter Default Description
query_cache yes Critical: Queue SQL to disk (qoq* files) to prevent data loss during DB outages.
quick_save_cdr no CDR visibility delay: no=10s, yes=3s, quick=1s. Higher values increase load.
cdr_partition yes Essential: Daily table partitioning for performance.
cdr_partition_by_hours no Hourly partitions for extreme traffic (≥15k CPS).
disable_partition_operations no Disable auto partition management (for centralized DB).
mysql_enable_set_id no Central server generates CDR IDs (high-traffic client/server).
disable_dbupgradecheck no Disable automatic schema checks and upgrades.

Automatic Schema Upgrade Safety Mechanism

The VoIPmonitor sensor includes a built-in safety mechanism to protect production databases from automatic schema modifications:

Database Size Behavior
< 1000 CDRs Auto-executes schema changes (CREATE TABLE, ALTER TABLE)
≥ 1000 CDRs Logs required ALTER queries to syslog/journalctl for manual execution

💡 Tip: Check logs after connecting to an existing production database: journalctl -u voipmonitor

For production databases with ≥ 1000 CDRs: 1. Sensor logs ALTER commands to /var/log/syslog, /var/log/messages, or journalctl 2. Execute logged queries manually during low-traffic period to prevent table locking 3. Use disable_dbupgradecheck = yes to skip all schema checks (rarely needed)

Configuration Priority: File vs GUI

mysqlloadconfig = yes
(Default: yes) Load settings from database (sensor_config table). GUI settings take priority over file settings.

⚠️ Warning: Setting mysqlloadconfig = no prevents loading the manager_key from the database, causing "failed read rsa key" startup errors in distributed deployments.

Diagnosing conflicts: 

systemctl restart voipmonitor
grep 'Configuration valu' /var/log/syslog | grep ' / '

Resolution options:

  • Option 1: Update settings via GUI (recommended)
  • Option 2: Set mysqlloadconfig = no for file-only management
  • Option 3: Delete specific entries from sensor_config table

SQL Queue Tuning

Parameter Default Description
mysqlstore_concat_limit 400 SQL statements per batch
mysqlstore_max_threads_cdr 2 Max parallel CDR write threads

Database Cleaning

See Data_Cleaning for detailed documentation.

Parameter Default Description
cleandatabase 0 Master retention period in days (0=disabled)
cleandatabase_cdr 0 CDR/message table retention
cleandatabase_rtp_stat 2 RTP statistics retention
partition_operations_enable_fromto 1-5 Partition drop time window (e.g., 1-5 AM)

CDR Summary (Aggregation)

Pre-aggregates call data for faster dashboard queries. 

cdr_summary = yes
cdr_summary_interval = 5  # minutes

Network Interface & Sniffing

Interface Selection

Parameter Default Description
interface eth0 Interface(s) to capture. Comma-separated for multiple. any = all (no promisc).
promisc yes Promiscuous mode (doesn't work with any).
interfaces_optimize yes Auto-tune NIC settings via ethtool.
snaplen 3200 Packet capture length. Increase for large SIP packets.

BPF Filtering

filter
BPF filter (tcpdump syntax). Warning: Can accidentally exclude important traffic.
# Example: Exclude specific subnets
filter = not net 192.168.0.0/16 and not net 10.0.0.0/8
interface_ip_filter
CPU-efficient IP allow-list (no negation). Multiple lines supported.
interface_ip_filter = 192.168.0.0/24
interface_ip_filter = 10.0.0.0/8

Shared Server Optimization

When the sniffer runs on the same server as the PBX, resource contention can cause voice breakage.

Symptoms: Audio jitter, packet loss, call lag that resolves when sniffer is stopped.

Solutions: 

# Solution 1: Specify interfaces (creates dedicated threads)
interface = ens192,ens224  # NOT 'any'

# Solution 2: Disable NIC optimization
interfaces_optimize = no

# Solution 3: Reduce sniffer load
savertp = header
saveaudio = no

Long-term: Move sensor to dedicated server with SPAN/Mirror. See Sniffer_distributed_architecture.

Packet Deduplication

Required when receiving same packets from multiple sources/interfaces. 

deduplicate = yes
auto_enable_use_blocks = yes  # Required for deduplication
deduplicate_ipheader = ip_only  # Recommended for different network paths
Parameter Default Description
deduplicate no Enable checksum-based deduplication (CPU intensive)
auto_enable_use_blocks no Required for deduplication and correct RTP association across interfaces/VLANs
deduplicate_ipheader yes ip_only recommended when packets have different TTL

Tunneling Protocol Support

Parameter Default Description
udp_port_tzsp 37008 Mikrotik TZSP
udp_port_l2tp 1701 L2TP tunneling
udp_port_vxlan 4789 VXLAN (AWS/cloud)
audiocodes no AudioCodes proprietary tunnel. See Audiocodes_tunneling.
ipfix no Oracle/ACME SBC IPFIX
hep no Homer Encapsulation Protocol

Scan PCAP Directory Mode

Process PCAP files instead of live capture. Useful for Windows hosts without SPAN ports. 

scanpcapdir = /var/spool/voipmonitor/scanpcap
scanpcapmethod = newfile

Workflow:

  1. Capture on source: tcpdump -i eth0 udp -G 300 -w /path/dump.pcap
  2. Transfer to VoIPmonitor server
  3. Sensor processes files automatically

SIP Configuration

Port Settings

Parameter Default Description
sipport 5060 SIP ports. Multiple: 5060,5061,5070-5080
cdr_sipport yes Store SIP ports in database
cdr_country_code yes Country code lookup for caller/called. Set no to disable country flags.

TCP Reassembly & UDP Fragmentation

Parameter Default Description
sip_tcp_reassembly_ext yes TCP reassembly for SIP over TCP
udpfrag yes Critical: IP fragment reassembly for large SIP messages
max_sip_packets_in_call 2000 Maximum SIP packets per call

TLS/SSL & SRTP Decryption

SIP TLS Decryption

ssl = yes
ssl_ipport = 10.0.0.1:5061 /path/to/your.key
# Subnet with multiple keys:
ssl_ipport = 10.0.0.0/24:5061 /path/key1.pem,/path/key2.pem

Keylogger support (for PFS/TLS 1.3): 

ssl_sessionkey_udp = yes
ssl_sessionkey_udp_port = 1234

See Tls for complete TLS decryption documentation.

SRTP Configuration

Parameter Default Description
srtp_rtp no Decrypt and store RTP data in PCAPs
srtp_rtcp yes Decrypt RTCP streams
srtp_rtp_dtls yes DTLS decryption (requires keylogger)
ssl_dtls_boost no Meta-parameter enabling aggressive DTLS decryption options

Caller/Called Identity

Parameter Default Description
remoteparty_caller unset Update caller from Remote-Party-ID (calling/called)
passertedidentity no Use P-Asserted-Identity for caller
destination_number_mode 1 Source for called number: 1=To header, 2=INVITE URI
sipoverlap yes Update destination from subsequent INVITEs (overlap dialing)

Performance & Threading

Core Threading

Parameter Default Description
t2_boost unset Set to high_traffic for ≥1500Mbit. Fixes CPU bottlenecks where single defrag thread runs at 100%.
threading_expanded yes Modern multi-threaded engine. Set high_traffic for >5 Gbit/s.
preprocess_rtp_threads 2 Initial RTP preprocessing threads (auto-scales)
rtpthreads CPU count RTP processing threads

Buffer Configuration

Parameter Default Description
ringbuffer 50 Ringbuffer size MB. ≥500 recommended for >100 Mbit. Max 2000.
max_buffer_mem 2000 Max buffer memory MB. Increase to 10000+ for high concurrent calls.
packetbuffer_compress no Enable in distributed setups to reduce bandwidth.

Thread Priority

sched_pol_auto = prio -20  # Auto-elevate critical threads under load
sched_pol_auto_cpu_limit = 45  # CPU threshold for elevation

Distributed Operation

See Sniffer_distributed_architecture for complete documentation.

Client/Server Configuration

Central Server: 

server_bind = 0.0.0.0
server_bind_port = 60024
server_password = yourpassword
# CRITICAL: Exclude server port from sipport!
sipport = 1-60023,60025-65535

Remote Sensor: 

id_sensor = 2
server_destination = 10.0.0.1
server_destination_port = 60024
server_password = yourpassword
packetbuffer_sender = no  # or yes for packet mirroring

⚠️ Warning: When packetbuffer_sender = yes, all packets including RTP are transmitted regardless of savertp setting.

Storage & File Management

Spool Directory

Parameter Default Description
spooldir /var/spool/voipmonitor Primary storage directory
spooldir_2 unset Secondary storage for capture rules with "Store to second spooldir"
cachedir unset Temp storage (use RAM/SSD for performance)

ℹ️ Note: For GUI access to spooldir_2, configure "Sniffer second datapath" in GUI Settings > System Configuration > Basic.

TAR Storage Strategy

tar = yes  # Group PCAPs into minute-based archives (reduces I/O)
tar_compress_sip = zstd
tar_compress_graph = zstd

Saving Options

Parameter Default Description
savesip yes Save SIP packets
savertp yes yes=full, header=metadata only (no audio), no=disabled
savertp_video no Video RTP. Limitation: Only ONE video stream per call saved to PCAP.
saveudptl no T.38 fax packets
savegraph yes Call graph data

Disable audio recording: 

savertp = header  # NOT 'no' - keeps RTP analysis tool working
saveaudio = no

Spool Cleaning

Parameter Default Description
cleanspool yes Enable automatic spool cleaning
maxpoolsize 102400 Size limit in MB
maxpooldays unset Age limit in days
autocleanspoolminpercent 1 Emergency cleaning trigger (% free)

Audio File Generation

Parameter Default Description
saveaudio no Generate audio files: wav, ogg, mp3, or yes
saveaudio_singlefolder unset Dedicated directory for audio files
saveaudio_stereo yes Caller=left, called=right channel

Call Processing

Timeouts

Parameter Default Description
absolute_timeout 14400 Force-end calls longer than this (seconds). Sets cdr.bye = 102.
rtptimeout 300 Close call if no RTP/RTCP for this duration
sipwithoutrtptimeout 3600 Close SIP call without RTP
onewaytimeout 15 End call if no reply from other side

Call Merging

Parameter Default Description
matchheader unset SIP header to link call legs in GUI
callidmerge_header unset Header containing parent Call-ID for CDR merging
call_id_alternative unset Alternative identifiers (e.g., Session-ID,Join for CUCM)

See Merging_or_correlating_multiple_call_legs for detailed documentation.

Recording Control

Parameter Default Description
pauserecordingdtmf unset DTMF sequence to pause recording (e.g., *9)
pauserecordingdtmf_timeout 4 Timeout between DTMF digits (seconds)
norecord-dtmf no Delete recording if *0 is detected
norecord-header no Discard call if X-VoipMonitor-norecord header present

Custom Headers

custom_headers = Referred-By, Diversion, X-Custom-Header
custom_headers_last_value = yes
custom_headers_max_size = 1024

After adding headers, configure display in GUI: Settings > CDR Custom Headers.

SIP History

save_sip_history
(Default: no) Store SIP signaling for GUI filtering.
  • requests - All SIP methods (PUBLISH, INFO, UPDATE, PRACK, REFER) in "SIP requests" filter
  • responses - Full response text for searching (not just codes)
  • all - Both requests and responses

⚠️ Warning: Enabling SIP history significantly increases database load and storage.

RTP Processing

Parameter Default Description
jitterbuffer_f1 yes 50ms fixed jitterbuffer simulation
jitterbuffer_f2 yes 200ms fixed jitterbuffer simulation
jitterbuffer_adapt yes Adaptive jitterbuffer (up to 500ms)
allow-zerossrc no Accept RTP with zero SSRC (some legacy gateways)

CPU optimization (saves ~30%): 

mosf1 = no
mos_adapt = no
mosf2 = yes  # Keep only f2 for stable MOS metric

Audio Analysis

Parameter Default Description
dtmf2db no Store DTMF to database
inbanddtmf no In-band DTMF detection (G711 only, CPU intensive)
silencedetect no Silence detection (G711 only, CPU intensive)
clippingdetect no Audio clipping detection

See Silence_detection for detailed documentation.

NAT Handling

natalias = 1.1.1.1 10.0.0.3  # Public to private IP mapping
sdp_reverse_ipport = no  # Reverse sniffing for NAT (use with caution)

Protocol Support

SIP REGISTER/OPTIONS/SUBSCRIBE

Parameter Default Description
sip-register no Process REGISTER messages (yes, nodb, no)
sip-options no Process OPTIONS messages
sip-subscribe no Process SUBSCRIBE messages
sip-message yes Process MESSAGE requests

See Register for detailed REGISTER documentation.

Other Protocols

Parameter Default Description
skinny no Cisco Skinny/SCCP protocol
mgcp no MGCP protocol
ss7 no SS7-over-IP (SIGTRAN)
diameter no Diameter protocol
ipv6 no IPv6 support (requires IPv6 database columns)

Advanced Protocol Support

IPFIX Support

ipfix = yes
ipfix_bind_port = 12345
ipfix_qos_fill_rtp_streams = yes
# Include TLS port for SIPS/SRTP:
sipport = 5060,5061

SIPREC Support

siprec_bind = 0.0.0.0
siprec_bind_port = 5099
siprec_rtp_min = 10000
siprec_rtp_max = 20000

HEP Support

receiver_mode = yes  # Required!
hep = yes
hep_bind_port = 9060
hep_kamailio_protocol_id_fix = yes  # For Kamailio sources

Kamailio Mirroring

receiver_mode = yes  # Required!
kamailio_port = 5888

Ribbon SBC Mirroring

ribbonsbc = yes
ribbonsbc_bind_ip = 0.0.0.0
ribbonsbc_bind_port = 9514

Whisper Transcription

audio_transcribe = yes
whisper_native = no
whisper_model = /path/to/ggml-base.bin
whisper_language = auto

See Whisper for detailed transcription documentation.

Expert & Debugging Options

⚠️ Warning: Only change these if instructed by support or you are an expert.

Parameter Default Description
callslimit 0 Max concurrent calls (0=unlimited)
skipdefault no Ignore all calls unless capture rules match
openfile_max 65535 Maximum open files
coredump_filter 0x7F Memory segments in coredump

Traffic Dumper

traffic_dumper_path = /var/spool/voipmonitor/traffic
traffic_dumper_filter_ip = 192.168.1.100, 10.0.0.0/8
traffic_dumper_filter_port = 5060, 5061, 10000-20000

AI Summary for RAG

Summary: Comprehensive reference for voipmonitor.conf covering: sensor identification, database configuration (MySQL settings, partitioning, mysqlloadconfig for GUI vs file priority), network interface settings (BPF filters, deduplication with auto_enable_use_blocks), tunneling protocols (VXLAN, TZSP, HEP, AudioCodes), TLS/SRTP decryption, distributed client/server architecture (packetbuffer_sender), storage management (TAR archives, spool cleaning), call processing (timeouts, merging, recording control), SIP history storage, audio analysis, and protocol support (IPFIX, SIPREC, HEP, Kamailio, Ribbon SBC, Whisper). Deprecated options in v2025.09.1+ include vxlan, packet_buffer_total_size, udp_reassembly, sipdefrag.

Keywords: voipmonitor.conf, sniffer configuration, id_sensor, mysqlloadconfig, manager_key, deduplicate, auto_enable_use_blocks, packetbuffer_sender, savertp, TLS decryption, SRTP, ssl_dtls_boost, distributed architecture, client-server, maxpoolsize, cleandatabase, custom_headers, save_sip_history, t2_boost, threading, scanpcapdir, deprecated options, IPFIX, SIPREC, HEP, Kamailio, Ribbon SBC, Whisper, pauserecordingdtmf

Key Questions:

  • What are the most important settings in voipmonitor.conf?
  • How do I configure the database connection?
  • Why does the sniffer fail with "failed read rsa key"?
  • How do I set up distributed client/server architecture?
  • What is the difference between packetbuffer_sender = yes and no?
  • How do I enable packet deduplication?
  • How do I decrypt TLS/SRTP traffic?
  • How do I disable audio recording while keeping RTP analysis?
  • How do I capture custom SIP headers?
  • How do I configure IPFIX/SIPREC/HEP receivers?
  • Which options were deprecated in v2025.09.1?
  • How do I fix CPU bottlenecks with t2_boost?
  • How do I process PCAP files with scanpcapdir?
  • What is the database schema upgrade safety mechanism?
Retrieved from "https://www.voipmonitor.org/doc/index.php?title=Sniffer_configuration&oldid=10264"