Sniffer configuration: Difference between revisions

From VoIPmonitor.org
No edit summary
(Add clarification about audio playback vs pre-generated files, explain saveaudio is independent and CPU intensive)
 
(81 intermediate revisions by 2 users not shown)
Line 1: Line 1:
'''This document provides a comprehensive reference for all parameters in the `voipmonitor.conf` configuration file. It is designed to help administrators understand and tune the VoIPmonitor sensor for their specific environment.'''
[[Category:Configuration]]
{{DISPLAYTITLE:Sniffer Configuration Reference (voipmonitor.conf)}}


The main configuration file is located at `/etc/voipmonitor.conf`. Additional configuration snippets can be placed in files within the `/etc/voipmonitor/conf.d/` directory (these should not contain the `[general]` section header).
'''Comprehensive reference for `/etc/voipmonitor.conf` parameters.''' Additional configuration snippets can be placed in `/etc/voipmonitor/conf.d/` (without `[general]` header).


== General & Core Settings ==
'''Related documentation:'''
* [[Sniffer_installation|Installation Guide]] - Installing the sniffer
* [[Sniffer_distributed_architecture|Distributed Architecture]] - Client/server deployment
* [[Sniffer_troubleshooting|Troubleshooting]] - Common issues and solutions
* [[Scaling|Scaling Guide]] - Performance tuning for high traffic
* [[Data_Cleaning|Data Cleaning]] - Retention and cleanup configuration


=== Time and Sensor Identification ===
= General & Core Settings =
;<code>id_sensor = 1</code>
:(Default: unset) A unique numeric identifier (1-65535) for this sensor. This is '''essential''' in multi-sensor deployments to distinguish which sensor captured a call. The value is stored in the `cdr.id_sensor` column.


;<code>utc = yes</code>
== Sensor Identification & Time ==
:(Default: no) When set to `yes`, all timestamps for CDRs and PCAP files are stored in UTC. This is '''highly recommended''' for deployments with sensors in different timezones to ensure consistency.


;<code>timezone = /usr/share/zoneinfo/UTC</code>
{| class="wikitable"
:(Default: system timezone) Overrides the system's default timezone by specifying a path to a valid zoneinfo file. Use this only if you need the sensor to operate in a timezone different from the server it's running on.
! Parameter !! Default !! Description
|-
| <code>id_sensor</code> || unset || Unique numeric identifier (1-65535). '''Essential''' for multi-sensor deployments.
|-
| <code>utc</code> || no || Store timestamps in UTC. '''Recommended''' for multi-timezone deployments.
|-
| <code>timezone</code> || system || Override system timezone with zoneinfo path (e.g., <code>/usr/share/zoneinfo/UTC</code>).
|}


=== Process Management ===
== Process Management ==
;<code>watchdog = yes</code>
:(Default: no) If enabled, a watchdog process is created that automatically restarts the voipmonitor sensor if it crashes or is terminated unexpectedly.


;<code>watchdog_run_command = systemctl restart voipmonitor</code>
{| class="wikitable"
:(Default: unset) If specified, the watchdog will execute this command to restart the service instead of just re-running the binary. This is useful for proper service management with `systemd`.
! Parameter !! Default !! Description
|-
| <code>watchdog</code> || no || Auto-restart sensor on crash.
|-
| <code>watchdog_run_command</code> || unset || Custom restart command (e.g., <code>systemctl restart voipmonitor</code>).
|}


== Database Configuration ==
== Deprecated Options (v2025.09.1+) ==


=== Connection Settings ===
{{Warning|1=The following options are '''unsupported and ignored''' in sniffer version 2025.09.1+. Remove them from your configuration.}}
;<code>mysqlhost = localhost</code>
:IP address or hostname of the MySQL/MariaDB server.
;<code>mysqlsocket = /var/run/mysqld/mysqld.sock</code>
:Path to the MySQL socket file for local connections (often faster than TCP).
;<code>mysqlport = 3306</code>
:TCP port of the database server.
;<code>mysqlusername = root</code>
:Username for the database connection.
;<code>mysqlpassword =</code>
:Password for the database connection.
;<code>mysqldb = voipmonitor</code>
:The name of the database to use. It will be created automatically if it doesn't exist.
;<code>mysql_connect_timeout = 60</code>
:(Default: 60) Timeout in seconds for establishing a connection to the database.
;<code>mysql_client_compress = no</code>
:(Default: no) Enables compression for the MySQL connection. Only use this if the database is on a remote, slow network link.
;<code>mysql_reconnect = yes</code>
:(Default: no) Enables automatic reconnection to the database if the connection is lost.


=== Database SSL/TLS ===
{| class="wikitable"
;<code>mysqlsslkey = /etc/ssl/client-key.pem</code>
! Deprecated Option !! Modern Replacement
:Path to the client's SSL private key file.
|-
;<code>mysqlsslcert = /etc/ssl/client-cert.pem</code>
| <code>vxlan</code>, <code>vxlan_port</code>, <code>vxlan_skipcrc</code> || <code>udp_port_vxlan = 4789</code>
:Path to the client's SSL certificate file.
|-
;<code>mysqlsslcacert = /etc/ssl/ca-cert.pem</code>
| <code>packet_buffer_total_size</code> || <code>max_buffer_mem</code> (auto-managed)
:Path to the Certificate Authority (CA) certificate file.
|-
| <code>udp_reassembly</code>, <code>udp_reassembly_max_size</code> || <code>udpfrag = yes</code>
|-
| <code>sipdefrag</code>, <code>sipdefrag_maxpacket</code>, <code>defragment_*</code> || Auto-managed; use <code>max_sip_packets_in_call</code>
|-
| <code>max_sip_size</code>, <code>interface_snaplen</code> || <code>snaplen = 3200</code>
|-
| <code>sanity_checks</code>, <code>check_sip_header</code>, <code>ignore_sip_parsing_errors</code> || Built-in (cannot be disabled)
|}
 
{{Tip|After removing deprecated options, check logs for warnings: <code>journalctl -u voipmonitor -f</code>}}
 
= Database Configuration =
 
== Connection Settings ==
 
{| class="wikitable"
! Parameter !! Default !! Description
|-
| <code>mysqlhost</code> || localhost || MySQL/MariaDB server address
|-
| <code>mysqlsocket</code> || unset || Socket path for local connections (faster than TCP)
|-
| <code>mysqlport</code> || 3306 || TCP port
|-
| <code>mysqlusername</code> || root || Database username
|-
| <code>mysqlpassword</code> || empty || Database password
|-
| <code>mysqldb</code> || voipmonitor || Database name (auto-created if missing)
|-
| <code>mysql_reconnect</code> || no || Auto-reconnect on connection loss
|}
 
=== SSL/TLS for Database ===
<syntaxhighlight lang="ini">
mysqlsslkey = /etc/ssl/client-key.pem
mysqlsslcert = /etc/ssl/client-cert.pem
mysqlsslcacert = /etc/ssl/ca-cert.pem
</syntaxhighlight>
 
== Performance & Schema ==
 
{| class="wikitable"
! Parameter !! Default !! Description
|-
| <code>query_cache</code> || yes || '''Critical:''' Queue SQL to disk (qoq* files) to prevent data loss during DB outages.
|-
| <code>quick_save_cdr</code> || no || CDR visibility delay: <code>no</code>=10s, <code>yes</code>=3s, <code>quick</code>=1s. Higher values increase load.
|-
| <code>cdr_partition</code> || yes || '''Essential:''' Daily table partitioning for performance.
|-
| <code>cdr_partition_by_hours</code> || no || Hourly partitions for extreme traffic (≥15k CPS).
|-
| <code>disable_partition_operations</code> || no || Disable auto partition management (for centralized DB).
|-
| <code>mysql_enable_set_id</code> || no || Central server generates CDR IDs (high-traffic client/server).
|}
 
== Configuration Priority: File vs GUI ==


=== Performance & Schema ===
;<code>query_cache = yes</code>
:(Default: yes) This is a '''critical''' feature. When enabled, all SQL queries are first saved to a disk-based queue before being sent to the database. This prevents data loss if the database is temporarily unavailable and prevents the sensor from running out of memory.
;<code>quick_save_cdr = no</code>
:(Default: no) Speeds up the visibility of calls in the GUI at the cost of higher system load. Options are `no` (10s delay, recommended), `yes` (3s delay), or `quick` (1s delay). Only change this if near-real-time CDR visibility is absolutely required.
;<code>cdr_partition = yes</code>
:(Default: yes) Enables partitioning for large tables (like `cdr`) by day. This is '''essential for performance and data management''' on any production system.
;<code>cdr_partition_by_hours = no</code>
:(Default: no) For extreme high-traffic environments (>= 15,000 CPS), this creates partitions per hour instead of per day to further improve performance.
;<code>disable_dbupgradecheck = yes</code>
:(Default: no) If set to `yes`, the sniffer will not check for and apply database schema updates on startup.
;<code>mysqlloadconfig = yes</code>
;<code>mysqlloadconfig = yes</code>
:(Default: yes) Allows loading additional configuration parameters dynamically from the `sensor_conf` database table.
:(Default: yes) Load settings from database (<code>sensor_config</code> table). '''GUI settings take priority over file settings.'''
;<code>mysqlcompress_type = ...</code>
 
:(Default: auto-detected) You do not normally need to set this. The sniffer automatically chooses the best table compression method (LZ4 page compression) based on your MySQL/MariaDB version. Only change this for legacy systems.
{{Warning|1=Setting <code>mysqlloadconfig = no</code> prevents loading the <code>manager_key</code> from the database, causing "failed read rsa key" startup errors in distributed deployments.}}
;<code>mysql_enable_set_id = yes</code>
 
:(Default: no) In very high-traffic client/server deployments, this allows the central server to generate CDR IDs, which can improve batch insert performance.
'''Diagnosing conflicts:'''
;<code>cdr_force_primary_index_in_all_tables = no</code>
<syntaxhighlight lang="bash">
:(Default: no) Creates primary indexes on all tables. This is only required for specific database clustering technologies like MySQL/Galera Cluster and should not be enabled otherwise.
systemctl restart voipmonitor
;<code>disable_cdr_fields_rtp = no</code>
grep 'Configuration valu' /var/log/syslog | grep ' / '
:(Default: no) Disables all RTP-related statistics columns in the CDR table to save space.
</syntaxhighlight>
 
'''Resolution options:'''
* '''Option 1:''' Update settings via GUI (recommended)
* '''Option 2:''' Set <code>mysqlloadconfig = no</code> for file-only management
* '''Option 3:''' Delete specific entries from <code>sensor_config</code> table
 
== SQL Queue Tuning ==
 
{| class="wikitable"
! Parameter !! Default !! Description
|-
| <code>mysqlstore_concat_limit</code> || 400 || SQL statements per batch
|-
| <code>mysqlstore_max_threads_cdr</code> || 2 || Max parallel CDR write threads
|}
 
== Database Cleaning ==
 
See [[Data_Cleaning]] for detailed documentation.
 
{| class="wikitable"
! Parameter !! Default !! Description
|-
| <code>cleandatabase</code> || 0 || Master retention period in days (0=disabled)
|-
| <code>cleandatabase_cdr</code> || 0 || CDR/message table retention
|-
| <code>cleandatabase_rtp_stat</code> || 2 || RTP statistics retention
|-
| <code>partition_operations_enable_fromto</code> || 1-5 || Partition drop time window (e.g., 1-5 AM)
|}
 
== CDR Summary (Aggregation) ==
 
Pre-aggregates call data for faster dashboard queries.
 
<syntaxhighlight lang="ini">
cdr_summary = yes
cdr_summary_interval = 5  # minutes
</syntaxhighlight>
 
= Network Interface & Sniffing =
 
== Interface Selection ==
 
{| class="wikitable"
! Parameter !! Default !! Description
|-
| <code>interface</code> || eth0 || Interface(s) to capture. Comma-separated for multiple. <code>any</code> = all (no promisc).
|-
| <code>promisc</code> || yes || Promiscuous mode (doesn't work with <code>any</code>).
|-
| <code>interfaces_optimize</code> || yes || Auto-tune NIC settings via ethtool.
|-
| <code>snaplen</code> || 3200 || Packet capture length. Increase for large SIP packets.
|}
 
== BPF Filtering ==
 
;<code>filter</code>
:BPF filter (tcpdump syntax). '''Warning:''' Can accidentally exclude important traffic.
<syntaxhighlight lang="ini">
# Example: Exclude specific subnets
filter = not net 192.168.0.0/16 and not net 10.0.0.0/8
</syntaxhighlight>
 
;<code>interface_ip_filter</code>
:CPU-efficient IP allow-list (no negation). Multiple lines supported.
<syntaxhighlight lang="ini">
interface_ip_filter = 192.168.0.0/24
interface_ip_filter = 10.0.0.0/8
</syntaxhighlight>
 
== 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:'''
<syntaxhighlight lang="ini">
# 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
</syntaxhighlight>
 
'''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.
 
<syntaxhighlight lang="ini">
deduplicate = yes
auto_enable_use_blocks = yes  # Required for deduplication
deduplicate_ipheader = ip_only  # Recommended for different network paths
</syntaxhighlight>
 
{| class="wikitable"
! Parameter !! Default !! Description
|-
| <code>deduplicate</code> || no || Enable checksum-based deduplication (CPU intensive)
|-
| <code>auto_enable_use_blocks</code> || no || '''Required''' for deduplication and correct RTP association across interfaces/VLANs
|-
| <code>deduplicate_ipheader</code> || yes || <code>ip_only</code> recommended when packets have different TTL
|}
 
== Tunneling Protocol Support ==
 
{| class="wikitable"
! Parameter !! Default !! Description
|-
| <code>udp_port_tzsp</code> || 37008 || Mikrotik TZSP
|-
| <code>udp_port_l2tp</code> || 1701 || L2TP tunneling
|-
| <code>udp_port_vxlan</code> || 4789 || VXLAN (AWS/cloud)
|-
| <code>audiocodes</code> || no || AudioCodes proprietary tunnel. See [[Audiocodes_tunneling]].
|-
| <code>ipfix</code> || no || Oracle/ACME SBC IPFIX
|-
| <code>hep</code> || no || Homer Encapsulation Protocol
|}
 
== Scan PCAP Directory Mode ==
 
Process PCAP files instead of live capture. Useful for Windows hosts without SPAN ports.
 
<syntaxhighlight lang="ini">
scanpcapdir = /var/spool/voipmonitor/scanpcap
scanpcapmethod = newfile
</syntaxhighlight>
 
'''Workflow:'''
# Capture on source: <code>tcpdump -i eth0 udp -G 300 -w /path/dump.pcap</code>
# Transfer to VoIPmonitor server
# Sensor processes files automatically
 
= SIP Configuration =
 
== Port Settings ==
 
{| class="wikitable"
! Parameter !! Default !! Description
|-
| <code>sipport</code> || 5060 || SIP ports. Multiple: <code>5060,5061,5070-5080</code>
|-
| <code>cdr_sipport</code> || yes || Store SIP ports in database
|-
| <code>cdr_country_code</code> || yes || Country code lookup for caller/called. Set <code>no</code> to disable country flags.
|}
 
== TCP Reassembly & UDP Fragmentation ==
 
{| class="wikitable"
! Parameter !! Default !! Description
|-
| <code>sip_tcp_reassembly_ext</code> || yes || TCP reassembly for SIP over TCP
|-
| <code>udpfrag</code> || yes || '''Critical:''' IP fragment reassembly for large SIP messages
|-
| <code>max_sip_packets_in_call</code> || 2000 || Maximum SIP packets per call
|}
 
= TLS/SSL & SRTP Decryption =
 
== SIP TLS Decryption ==
 
<syntaxhighlight lang="ini">
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
</syntaxhighlight>
 
'''Keylogger support (for PFS/TLS 1.3):'''
<syntaxhighlight lang="ini">
ssl_sessionkey_udp = yes
ssl_sessionkey_udp_port = 1234
</syntaxhighlight>
 
See [[Tls]] for complete TLS decryption documentation.
 
== SRTP Configuration ==
 
{| class="wikitable"
! Parameter !! Default !! Description
|-
| <code>srtp_rtp</code> || no || Decrypt and store RTP data in PCAPs
|-
| <code>srtp_rtcp</code> || yes || Decrypt RTCP streams
|-
| <code>srtp_rtp_dtls</code> || yes || DTLS decryption (requires keylogger)
|-
| <code>ssl_dtls_boost</code> || no || '''Meta-parameter''' enabling aggressive DTLS decryption options
|}
 
= Caller/Called Identity =
 
{| class="wikitable"
! Parameter !! Default !! Description
|-
| <code>remoteparty_caller</code> || unset || Update caller from Remote-Party-ID (<code>calling</code>/<code>called</code>)
|-
| <code>passertedidentity</code> || no || Use P-Asserted-Identity for caller
|-
| <code>destination_number_mode</code> || 1 || Source for called number: <code>1</code>=To header, <code>2</code>=INVITE URI
|-
| <code>sipoverlap</code> || yes || Update destination from subsequent INVITEs (overlap dialing)
|}
 
= Performance & Threading =
 
== Core Threading ==
 
{| class="wikitable"
! Parameter !! Default !! Description
|-
| <code>t2_boost</code> || unset || Set to <code>high_traffic</code> for ≥1500Mbit. Fixes CPU bottlenecks where single defrag thread runs at 100%.
|-
| <code>threading_expanded</code> || yes || Modern multi-threaded engine. Set <code>high_traffic</code> for >5 Gbit/s.
|-
| <code>preprocess_rtp_threads</code> || 2 || Initial RTP preprocessing threads (auto-scales)
|-
| <code>rtpthreads</code> || CPU count || RTP processing threads
|}
 
== Buffer Configuration ==
 
{| class="wikitable"
! Parameter !! Default !! Description
|-
| <code>ringbuffer</code> || 50 || Ringbuffer size MB. ≥500 recommended for >100 Mbit. Max 2000.
|-
| <code>max_buffer_mem</code> || 2000 || Max buffer memory MB. Increase to 10000+ for high concurrent calls.
|-
| <code>packetbuffer_compress</code> || no || Enable in distributed setups to reduce bandwidth.
|}
 
== Thread Priority ==
 
<syntaxhighlight lang="ini">
sched_pol_auto = prio -20  # Auto-elevate critical threads under load
sched_pol_auto_cpu_limit = 45  # CPU threshold for elevation
</syntaxhighlight>
 
= Distributed Operation =
 
See [[Sniffer_distributed_architecture]] for complete documentation.
 
<kroki lang="mermaid">
%%{init: {'flowchart': {'nodeSpacing': 15, 'rankSpacing': 40}}}%%
flowchart LR
    subgraph "Local Processing (packetbuffer_sender=no)"
        A1[Remote Sensor] -->|"Analyzes locally"| A2[CDR + Stats]
        A2 -->|"Sends CDRs"| A3[Central Server]
        A1 -->|"Stores PCAP"| A4[(Local Disk)]
    end
    subgraph "Packet Mirroring (packetbuffer_sender=yes)"
        B1[Remote Sensor] -->|"Forwards packets"| B2[Central Server]
        B2 -->|"Analyzes & stores"| B3[(Central Disk)]
    end
</kroki>
 
== Client/Server Configuration ==
 
'''Central Server:'''
<syntaxhighlight lang="ini">
server_bind = 0.0.0.0
server_bind_port = 60024
server_password = yourpassword
# CRITICAL: Exclude server port from sipport!
sipport = 1-60023,60025-65535
</syntaxhighlight>
 
'''Remote Sensor:'''
<syntaxhighlight lang="ini">
id_sensor = 2
server_destination = 10.0.0.1
server_destination_port = 60024
server_password = yourpassword
packetbuffer_sender = no  # or yes for packet mirroring
</syntaxhighlight>
 
{{Warning|1=When <code>packetbuffer_sender = yes</code>, '''all packets including RTP are transmitted''' regardless of <code>savertp</code> setting.}}
 
= Storage & File Management =
 
== Spool Directory ==
 
{| class="wikitable"
! Parameter !! Default !! Description
|-
| <code>spooldir</code> || /var/spool/voipmonitor || Primary storage directory
|-
| <code>spooldir_2</code> || unset || Secondary storage for capture rules with "Store to second spooldir"
|-
| <code>cachedir</code> || unset || Temp storage (use RAM/SSD for performance)
|}
 
{{Note|1=For GUI access to <code>spooldir_2</code>, configure "Sniffer second datapath" in GUI Settings > System Configuration > Basic.}}
 
== TAR Storage Strategy ==
 
<syntaxhighlight lang="ini">
tar = yes  # Group PCAPs into minute-based archives (reduces I/O)
tar_compress_sip = zstd
tar_compress_graph = zstd
</syntaxhighlight>
 
== Saving Options ==
 
{| class="wikitable"
! Parameter !! Default !! Description
|-
| <code>savesip</code> || yes || Save SIP packets
|-
| <code>savertp</code> || yes || <code>yes</code>=full, <code>header</code>=metadata only (no audio), <code>no</code>=disabled
|-
| <code>savertp_video</code> || no || Video RTP. '''Limitation:''' Only ONE video stream per call saved to PCAP.
|-
| <code>saveudptl</code> || no || T.38 fax packets
|-
| <code>savegraph</code> || yes || Call graph data
|}
 
'''Disable audio recording:'''
<syntaxhighlight lang="ini">
savertp = header  # NOT 'no' - keeps RTP analysis tool working
saveaudio = no
</syntaxhighlight>
 
== Spool Cleaning ==
 
{| class="wikitable"
! Parameter !! Default !! Description
|-
| <code>cleanspool</code> || yes || Enable automatic spool cleaning
|-
| <code>maxpoolsize</code> || 102400 || Size limit in MB
|-
| <code>maxpooldays</code> || unset || Age limit in days
|-
| <code>autocleanspoolminpercent</code> || 1 || Emergency cleaning trigger (% free)
|}
 
== Audio File Generation ==
 
{| class="wikitable"
! Parameter !! Default !! Description
|-
| <code>saveaudio</code> || no || Generate audio files: <code>wav</code>, <code>ogg</code>, <code>mp3</code>, or <code>yes</code>
|-
| <code>saveaudio_singlefolder</code> || unset || Dedicated directory for audio files
|-
| <code>saveaudio_stereo</code> || yes || Caller=left, called=right channel
|}
=== Understanding Audio Playback vs Pre-Generated Files ===
 
VoIPmonitor provides '''two independent methods''' for audio playback:
 
{| class="wikitable"
! Method !! How it works !! Requirements !! Use Case
|-
| '''On-demand extraction''' (default) || GUI extracts audio from stored RTP packets in PCAP files || <code>savesip = yes</code>, <code>savertp = yes</code> || Standard operation - recommended
|-
| '''Pre-generated files''' || Sniffer creates .wav/.ogg/.mp3 files immediately during call processing || <code>saveaudio = wav</code> (or ogg/mp3) || Special requirements only
|}
 
{{Note|1=The <code>saveaudio</code> option is '''NOT required''' for audio playback in the GUI. The GUI can extract audio on-demand from stored PCAP files whenever <code>savertp = yes</code>.}}
 
'''Important considerations for <code>saveaudio</code>:'''
* '''CPU/IO intensive''' - Pre-generating audio files for every call significantly increases system load
* '''Independent option''' - Works regardless of <code>savertp</code>/<code>savesip</code> settings
* '''Storage overhead''' - Creates additional audio files beyond the PCAP storage
* '''Use sparingly''' - Only enable when you have specific requirements (e.g., external systems that need direct audio file access)
 
'''To disable audio recording while keeping quality metrics:'''
<syntaxhighlight lang="ini">
savertp = header  # Saves RTP headers only - keeps MOS/jitter/packet loss metrics
# saveaudio is 'no' by default - audio cannot be played/extracted
</syntaxhighlight>
 
'''To keep full audio capability (default):'''
<syntaxhighlight lang="ini">
savertp = yes      # Full RTP packets stored
# saveaudio is 'no' by default - GUI extracts audio on-demand from PCAP
</syntaxhighlight>
= Call Processing =
 
== Timeouts ==
 
{| class="wikitable"
! Parameter !! Default !! Description
|-
| <code>absolute_timeout</code> || 14400 || Force-end calls longer than this (seconds). Sets <code>cdr.bye = 102</code>.
|-
| <code>rtptimeout</code> || 300 || Close call if no RTP/RTCP for this duration
|-
| <code>sipwithoutrtptimeout</code> || 3600 || Close SIP call without RTP
|-
| <code>onewaytimeout</code> || 15 || End call if no reply from other side
|}
 
== Call Merging ==
 
{| class="wikitable"
! Parameter !! Default !! Description
|-
| <code>matchheader</code> || unset || SIP header to link call legs in GUI
|-
| <code>callidmerge_header</code> || unset || Header containing parent Call-ID for CDR merging
|-
| <code>call_id_alternative</code> || unset || Alternative identifiers (e.g., <code>Session-ID,Join</code> for CUCM)
|}
 
See [[Merging_or_correlating_multiple_call_legs]] for detailed documentation.
 
== Recording Control ==
 
{| class="wikitable"
! Parameter !! Default !! Description
|-
| <code>pauserecordingdtmf</code> || unset || DTMF sequence to pause recording (e.g., <code>*9</code>)
|-
| <code>pauserecordingdtmf_timeout</code> || 4 || Timeout between DTMF digits (seconds)
|-
| <code>norecord-dtmf</code> || no || Delete recording if <code>*0</code> is detected
|-
| <code>norecord-header</code> || no || Discard call if <code>X-VoipMonitor-norecord</code> header present
|}
 
== Custom Headers ==
 
<syntaxhighlight lang="ini">
custom_headers = Referred-By, Diversion, X-Custom-Header
custom_headers_last_value = yes
custom_headers_max_size = 1024
</syntaxhighlight>
 
After adding headers, configure display in GUI: '''Settings > CDR Custom Headers'''.
 
== SIP History ==
 
;<code>save_sip_history</code>
:(Default: no) Store SIP signaling for GUI filtering.
* <code>requests</code> - All SIP methods (PUBLISH, INFO, UPDATE, PRACK, REFER) in "SIP requests" filter
* <code>responses</code> - Full response text for searching (not just codes)
* <code>all</code> - Both requests and responses
 
{{Warning|1=Enabling SIP history significantly increases database load and storage.}}
 
 
 
=== GUI Filters for SIP Response Searching ===
 
There are two distinct SIP response filters in the CDR view. Understanding their differences prevents confusion:
 
{| class="wikitable"
! Filter !! What it searches !! Accepts !! Requires Configuration
|-
| '''Last SIP Response Code''' || Final response code in <code>cdr.lastSIPresponse</code> || Numeric codes (<code>404</code>, <code>503</code>), wildcards (<code>4%</code>, <code>5%</code>), '''and text''' (<code>%OK</code>, <code>%Busy%</code>) || '''None''' - always available
|-
| '''SIP responses''' || Full text of ALL SIP responses during the call || Full text search, any string || <code>save_sip_history = responses</code> or <code>save_sip_responses = yes</code>
|}
 
'''Key differences:'''
 
* '''Last SIP Response Code''' searches only the '''final''' response. Examples:
** <code>200</code> - exact numeric match
** <code>4%</code> - all 4xx errors
** <code>%OK</code> - responses ending with "OK"
** <code>%Busy%</code> - responses containing "Busy"
 
* '''SIP responses''' searches '''all''' SIP responses (180 Ringing, 183, provisional, etc.). Use for:
** Intermediate responses (e.g., 491 Request Pending mid-dialog)
** Custom SBC error messages
** Any response text, not just the final one
 
'''Example:''' A call completes with 200 OK but had a 503 from one provider during serial forking. "Last SIP Response Code = 503" won't find it, but "SIP responses = %503%" will.
 
=== save_sip_history vs save_sip_responses ===
 
These two parameters achieve the '''same result''' - storing SIP response text for the "SIP responses" filter. '''Do not enable both simultaneously''':
 
{| class="wikitable"
! Parameter !! Notes
|-
| <code>save_sip_history = responses</code> || Part of the multi-value <code>save_sip_history</code> option. Can combine with <code>requests</code> or use <code>all</code>.
|-
| <code>save_sip_responses = yes</code> || Standalone parameter for same functionality. Simpler if you only need response text.
|}
== RTP Processing ==
 
{| class="wikitable"
! Parameter !! Default !! Description
|-
| <code>jitterbuffer_f1</code> || yes || 50ms fixed jitterbuffer simulation
|-
| <code>jitterbuffer_f2</code> || yes || 200ms fixed jitterbuffer simulation
|-
| <code>jitterbuffer_adapt</code> || yes || Adaptive jitterbuffer (up to 500ms)
|-
| <code>allow-zerossrc</code> || no || Accept RTP with zero SSRC (some legacy gateways)
|}
 
'''CPU optimization (saves ~30%):'''
<syntaxhighlight lang="ini">
mosf1 = no
mos_adapt = no
mosf2 = yes  # Keep only f2 for stable MOS metric
</syntaxhighlight>
 
== Audio Analysis ==
 
{| class="wikitable"
! Parameter !! Default !! Description
|-
| <code>dtmf2db</code> || no || Store DTMF to database
|-
| <code>inbanddtmf</code> || no || In-band DTMF detection (G711 only, CPU intensive)
|-
| <code>silencedetect</code> || no || Silence detection (G711 only, CPU intensive)
|-
| <code>clippingdetect</code> || no || Audio clipping detection
|}
 
See [[Silence_detection]] for detailed documentation.
 
== NAT Handling ==
 
<syntaxhighlight lang="ini">
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)
</syntaxhighlight>
 
= Protocol Support =
 
== SIP REGISTER/OPTIONS/SUBSCRIBE ==
 
{| class="wikitable"
! Parameter !! Default !! Description
|-
| <code>sip-register</code> || no || Process REGISTER messages (<code>yes</code>, <code>nodb</code>, <code>no</code>)
|-
| <code>sip-options</code> || no || Process OPTIONS messages
|-
| <code>sip-subscribe</code> || no || Process SUBSCRIBE messages
|-
| <code>sip-message</code> || yes || Process MESSAGE requests
|}
 
See [[Register]] for detailed REGISTER documentation.
 
== Other Protocols ==
 
{| class="wikitable"
! Parameter !! Default !! Description
|-
| <code>skinny</code> || no || Cisco Skinny/SCCP protocol
|-
| <code>mgcp</code> || no || MGCP protocol
|-
| <code>ss7</code> || no || SS7-over-IP (SIGTRAN)
|-
| <code>diameter</code> || no || Diameter protocol
|-
| <code>ipv6</code> || no || IPv6 support (requires IPv6 database columns)
|}
 
= Advanced Protocol Support =
 
== IPFIX Support ==
 
IPFIX (IP Flow Information Export) is used with Oracle/ACME SBCs to receive call data.
 
'''IMPORTANT - PCAP Availability:''' IPFIX data is internally converted to packet format for processing. This means PCAP files CAN be downloaded from the GUI for IPFIX-sourced calls (SIP signaling is reconstructed). However, RTP streams are NOT included in the PCAP - only QoS metrics from the IPFIX data are available, not actual audio packets.


=== SQL Queue Tuning ===
<syntaxhighlight lang="ini">
;<code>mysqlstore_concat_limit = 400</code>
ipfix = yes
:(Default: 400) Sets the global number of SQL statements to batch together before sending to the database.
ipfix_bind_port = 12345
;<code>mysqlstore_max_threads_cdr = 2</code>
ipfix_qos_fill_rtp_streams = yes
:(Default: 2) The maximum number of parallel threads (and database connections) for writing CDRs. The sniffer will automatically scale up to this number if the queue grows.
# Include TLS port for SIPS/SRTP:
;''Note: Separate `_concat_limit_*` and `_max_threads_*` options exist for `message`, `register`, `http`, etc.''
sipport = 5060,5061
</syntaxhighlight>


=== Database Cleaning ===
{| class="wikitable"
;<code>cleandatabase = 0</code>
! Parameter !! Default !! Description
:(Default: 0, disabled) The master setting for database cleaning. Defines the retention period in days for CDRs and several other tables. Requires partitioning to be enabled.
|-
;<code>cleandatabase_cdr = 0</code>
| <code>ipfix</code> || no || Enable IPFIX receiver (Oracle/ACME SBC)
:(Default: 0, disabled) Specific retention period for `cdr` and `message` tables.
|-
;<code>cleandatabase_rtp_stat = 2</code>
| <code>ipfix_bind_ip</code> || 0.0.0.0 || Bind IP address for IPFIX listener
:(Default: 2) Retention period in days for detailed RTP statistics.
|-
;''Note: Many other `cleandatabase_*` options exist for specific tables like `register_failed`, `sip_msg`, `ss7`, etc.''
| <code>ipfix_bind_port</code> || 4739 || UDP port for IPFIX data
;<code>partition_operations_enable_fromto = 1-5</code>
|-
:(Default: 1-5) Restricts partition-dropping operations to a specific time window (e.g., 1 AM to 5 AM) to avoid impacting performance during peak hours.
| <code>ipfix_qos_fill_rtp_streams</code> || no || Populate RTP stream statistics from IPFIX QoS data
;<code>cleandatabase_size = 500000</code>
|}
:(Default: unset) An alternative cleaning method that removes old data to stay below a total database size limit (in MB).


=== SQL Error Logging ===
== SIPREC Support ==
;<code>sql_log_all_errors = no</code>
:(Default: no) Logs all SQL errors to syslog.
;<code>sql_errors_log_file = /path/to/log</code>
:(Default: unset) Redirects SQL error logging to a specific file.
;<code>sql_errors_skip = 1054,1136</code>
:(Default: unset) A comma-separated list of SQL error codes to ignore and not log.


== Network Interface & Sniffing ==
<syntaxhighlight lang="ini">
This section configures how the sensor captures packets.
siprec_bind = 0.0.0.0
siprec_bind_port = 5099
siprec_rtp_min = 10000
siprec_rtp_max = 20000
</syntaxhighlight>


=== Interface Selection ===
== HEP Support ==
;<code>interface = eth0</code>
:Specifies the network interface(s) to listen on. Use a comma-separated list for multiple interfaces (e.g., `eth0,eth1`). Using `any` will listen on all interfaces but will not enable promiscuous mode.
;<code>promisc = yes</code>
:(Default: yes) Puts the specified interface(s) into promiscuous mode to capture all traffic, not just traffic addressed to the server. Does not work with `interface = any`.
;<code>interfaces_optimize = yes</code>
:(Default: yes) Allows voipmonitor to automatically tune NIC settings like ring buffers and coalescing using `ethtool`.
;<code>filter = udp or (vlan and udp)</code>
:(Default: unset) Applies a BPF filter (like in `tcpdump`) to the captured traffic. '''Warning:''' Using filters can be complex and may accidentally exclude important traffic like VLAN-tagged or tunneled packets. Use with caution.
;<code>interface_ip_filter = 192.168.0.0/24</code>
:(Default: unset) A more efficient way to filter traffic by IP address or subnet compared to the main `filter` option. Multiple lines can be used.


=== High-Traffic & Advanced Packet Capture ===
<syntaxhighlight lang="ini">
;<code>interface_libpcap_filter = eth0 : port 5060</code>
receiver_mode = yes  # Required!
:(Default: unset) Allows splitting traffic from a single physical interface into multiple parallel processing threads within voipmonitor, each with its own BPF filter. This is an advanced technique to overcome per-core CPU limits in very high packet-rate scenarios.
hep = yes
;<code>dpdk_nb_rxq = 2</code>
hep_bind_port = 9060
:(Default: 2) For users of the [[DPDK|DPDK framework]], this sets the number of receive queues to use, enabling multi-core packet processing at the hardware/driver level.
hep_kamailio_protocol_id_fix = yes  # For Kamailio sources
;<code>scanpcapdir = /dev/shm/voipmonitor</code>
</syntaxhighlight>
:(Default: unset) A special mode where the sensor does not capture live traffic but instead processes PCAP files from a directory as they are created by another tool, like `tcpdump`.
;<code>sip_send = 192.168.0.2:1555</code>
:(Default: unset) Forwards a copy of all captured SIP packets to a specified third-party destination over TCP or UDP. This is not for mirroring between sensors.


=== Tunneling Protocol Support ===
== Kamailio Mirroring ==
VoIPmonitor can decode various tunneling protocols. To enable listening, uncomment and configure the relevant port.
;<code>udp_port_tzsp = 37008</code> (Mikrotik TZSP)
;<code>udp_port_l2tp = 1701</code> (L2TP)
;<code>udp_port_vxlan = 4789</code> (VXLAN, common in AWS)
;<code>udp_port_hperm = 7932</code> (HP ERM)
;<code>audiocodes = yes</code> (Enables AudioCodes proprietary tunnel)
;<code>ipfix = yes</code> (Enables IPFIX, used by Oracle SBCs)
;<code>hep = yes</code> (Enables Homer Encapsulation Protocol)
;<code>kamailio_port = 5888</code> (Enables mirroring from Kamailio's `siptrace` module)
;<code>ribbonsbc_port = 9514</code> (Enables mirroring from Ribbon SBCs)


== Performance & Threading ==
<syntaxhighlight lang="ini">
receiver_mode = yes  # Required!
kamailio_port = 5888
</syntaxhighlight>


=== Core Threading Model ===
== Ribbon SBC Mirroring ==
;<code>threading_expanded = yes</code>
:(Default: yes) Enables the modern, multi-threaded processing engine. The sniffer automatically spawns and manages threads based on traffic load and CPU capacity. It is recommended to leave this enabled. Set to `high_traffic` for environments exceeding 5 Gbit/s.
;<code>preprocess_rtp_threads = 2</code>
:(Default: 2) The initial number of threads for RTP preprocessing. The system will auto-scale from here.
;<code>destroy_calls_in_storing_cdr = yes</code>
:(Default: no) Offloads the process of freeing call memory to a separate thread. Useful in very high-traffic scenarios (> 50,000 concurrent calls).


=== Thread Scheduling & Priority ===
<syntaxhighlight lang="ini">
;<code>sched_pol_auto = prio -20</code>
ribbonsbc = yes
:(Default: `prio -20`) Automatically elevates the priority (lowers the `nice` value) of critical threads if the system comes under load. This helps ensure that packet capture is prioritized over other system tasks.
ribbonsbc_bind_ip = 0.0.0.0
ribbonsbc_bind_port = 9514
</syntaxhighlight>


=== NUMA & Memory ===
== Whisper Transcription ==
;<code>numa_balancing_set = autodisable</code>
:(Default: autodisable) Manages the Linux kernel's NUMA balancing feature. The default setting will automatically disable NUMA balancing if it detects high overhead.
;<code>hugepages_max = 80000</code>
:(Default: 0, disabled) Enables the use of huge pages for memory allocation, which can improve performance on some systems by reducing TLB misses.


== Distributed Operation: Client/Server & Mirroring ==
<syntaxhighlight lang="ini">
audio_transcribe = yes
whisper_native = no
whisper_model = /path/to/ggml-base.bin
whisper_language = auto
</syntaxhighlight>


=== Modern Client/Server Model (Recommended) ===
See [[Whisper]] for detailed transcription documentation.
;<code>server_bind = 0.0.0.0</code>
{{Note|1='''Oracle/ACME SBC''' and '''Ribbon SBC''' are products from '''different vendors''' with different integration methods:
:The IP address the central sensor will listen on for connections from remote clients.
* '''Oracle SBC''' (formerly Acme Packet, acquired by Oracle in 2013) → uses '''IPFIX''' protocol
;<code>server_destination = 10.0.0.1</code>
* '''Ribbon SBC''' (formed from GENBAND + Sonus Networks merger in 2017) → uses '''Monitoring Profile''' with proprietary <code>ribbonsbc</code> protocol
:The IP address of the central server a remote sensor should connect to.
Do not confuse these - they require different VoIPmonitor configuration.}}
;<code>server_password =</code>
= Expert & Debugging Options =
:A shared password to authenticate clients and servers.
;<code>packetbuffer_sender = no</code>
:(Default: no) The operational mode. `no` for local processing (low network usage), `yes` for packet mirroring (low remote CPU usage).
;<code>server_type_compress = zstd</code>
:(Default: zstd) Compression algorithm for the client/server channel.


=== Legacy Mirroring Model ===
{{Warning|1=Only change these if instructed by support or you are an expert.}}
;<code>mirror_bind_ip = 0.0.0.0</code>
:The IP the receiver sensor listens on for the unencrypted, legacy mirroring protocol.
;<code>mirror_destination_ip = 10.0.0.1</code>
:The IP of the receiver sensor that the sender should stream packets to.


== Storage & File Management (Spooldir) ==
{| class="wikitable"
! Parameter !! Default !! Description
|-
| <code>callslimit</code> || 0 || Max concurrent calls (0=unlimited)
|-
| <code>skipdefault</code> || no || Ignore all calls unless capture rules match
|-
| <code>openfile_max</code> || 65535 || Maximum open files
|-
| <code>coredump_filter</code> || 0x7F || Memory segments in coredump
|}


=== Location and Permissions ===
== Traffic Dumper ==
;<code>spooldir = /var/spool/voipmonitor</code>
:The primary directory for storing all captured data (PCAP, GRAPH, AUDIO files).
;<code>spooldir_file_permission = 0666</code>
;<code>spooldir_dir_permission = 0777</code>
:Allows setting specific filesystem permissions for newly created files and directories.
;<code>spooldir_by_sensor = no</code>
:(Default: no) If enabled, creates subdirectories within the spooldir for each `id_sensor`.


=== PCAP/TAR Storage Strategy ===
<syntaxhighlight lang="ini">
;<code>tar = yes</code>
traffic_dumper_path = /var/spool/voipmonitor/traffic
:(Default: yes) This is a key performance feature. Instead of writing thousands of small PCAP files, voipmonitor groups them into minute-based `.tar` archives, which drastically reduces disk I/O load.
traffic_dumper_filter_ip = 192.168.1.100, 10.0.0.0/8
;<code>savesip = yes</code>
traffic_dumper_filter_port = 5060, 5061, 10000-20000
:Enables saving of SIP packets.
</syntaxhighlight>
;<code>savertp = yes</code>
:Enables saving of RTP packets. Set to `header` to save only RTP headers, not the audio payload.
;<code>savertcp = yes</code>
:Enables saving of RTCP (RTP Control Protocol) packets.
;<code>savegraph = yes</code>
:Enables saving of call graph data.


=== Spool Cleaning ===
== DEPRECATED DO NOT USE ==
;<code>cleanspool = yes</code>
:(Default: yes) Enables the automatic cleaning process for the spool directory.
;<code>maxpoolsize = 102400</code>
:(Default: 100 GB) The primary retention setting. Deletes the oldest data to stay under this total size limit (in MB).
;<code>maxpooldays = 30</code>
:(Default: unset) An alternative policy that deletes all data older than the specified number of days.
;''Note: Separate `maxpoolsip*`, `maxpoolrtp*`, etc., options exist for granular policies.''
;<code>autocleanspoolminpercent = 1</code> and `autocleanmingb = 5`
:(Defaults: 1% and 5 GB) Emergency cleaning triggers to prevent the disk from filling up completely.


=== Audio File Generation ===
<!-- This is a placeholder for correct deprecated options section -->
;<code>saveaudio = wav</code>
:(Default: no) If enabled, voipmonitor will generate an audio file (`.wav`, `.ogg`, or `.mp3`) for each call in addition to the PCAP file. '''Note:''' This is generally not necessary and adds significant CPU/I/O load.
;<code>mp3_quality = 5</code>, `ogg_quality = 0.4`
:Quality settings for the respective audio formats.


== Call Processing & Protocol Logic ==


=== Call Identification & Merging ===
;<code>remoteparty_caller = calling</code>, `passertedidentity = no`, etc.
:A group of options that control which SIP headers (`Remote-Party-ID`, `P-Asserted-Identity`, etc.) are used to determine the definitive caller/callee information.
;<code>sipoverlap = yes</code>
:(Default: yes) Allows the destination number to be updated from subsequent INVITEs within the same dialog, necessary for overlap dialing.
;<code>matchheader = in-reply-to</code>
:Uses the specified SIP header to link different call legs into a single related call in the GUI.
;<code>callidmerge_header = Parent-Call-ID</code>
:A more advanced method to merge call legs based on a shared identifier in a custom header.


=== Call Timeouts & Termination ===
;<code>absolute_timeout = 14400</code>
:(Default: 4 hours) Forcefully ends any call that lasts longer than this value to prevent runaway processes.
;<code>rtptimeout = 300</code>
:(Default: 5 minutes) Closes a call if no RTP or RTCP packets have been received for this duration.
;<code>sipwithoutrtptimeout = 3600</code>
:(Default: 1 hour) Closes a SIP call that has no associated RTP stream after this duration.
;<code>ignore_rtp_after_response = 408;480;486;487;481;600;503</code>
:A list of SIP final response codes after which the sniffer should stop looking for RTP for that call.


=== RTP & SRTP (Encrypted Media) ===
;<code>jitterbuffer_f1 = yes</code>, `jitterbuffer_f2 = yes`, `jitterbuffer_adapt = yes</code>
:(Default: all yes) Enables the three jitter buffer simulators used to calculate parametric MOS scores. These are CPU-intensive; you can disable one or more on resource-constrained systems.
;<code>srtp_rtp = no</code>
:(Default: no) To save decrypted SRTP (audio) streams into the PCAP file, you must set this to `yes`. This requires a valid decryption key.
;<code>ssl_dtls_boost = no</code>
:(Default: no) A meta-parameter that enables a set of aggressive options for improving DTLS handshake and SRTP decryption success rates.


=== NAT Handling ===
;<code>natalias = 1.1.1.1 10.0.0.3</code>
:Creates a mapping between a public IP and a private IP, helping the sniffer correctly associate call legs behind a NAT device. Multiple lines can be used.


=== SIP, REGISTER, and Other Messages ===
;<code>sip-register = no</code>
:(Default: no) Enables the processing and storage of SIP `REGISTER` messages.
;<code>sip-options = no</code>
:(Default: no) Enables the processing and storage of SIP `OPTIONS` messages.
;<code>sip-subscribe = no</code>
;<code>sip-notify = no</code>
:Enable processing for `SUBSCRIBE` and `NOTIFY` messages.
;<code>sip-message = yes</code>
:(Default: yes) Enables processing for SIP `MESSAGE` requests.


=== Call Recording Control ===
;<code>pauserecordingdtmf = *9</code>
:(Default: unset) If set, RTP recording will be paused when this DTMF sequence is detected in a call.
;<code>pauserecordingheader = MyCustomPauseHeader</code>
:(Default: unset) Pauses/unpauses recording based on the presence of a specific SIP header and its value (e.g., `pause` or `unpause`).
;<code>norecord-header = yes</code>
:(Default: no) If any SIP packet in a call contains the `X-VoipMonitor-norecord` header, the entire call record (PCAP and CDR) will be discarded.


=== Other Protocols ===
= AI Summary for RAG =
;<code>skinny = yes</code>
:(Default: no) Enables parsing for Cisco Skinny Call Control Protocol (SCCP).
;<code>mgcp = yes</code>
:(Default: no) Enables parsing for MGCP.
;<code>ss7 = yes</code>
:(Default: no) Enables parsing for SS7-over-IP (SIGTRAN).
;<code>diameter = no</code>
:(Default: no) Enables parsing for the Diameter protocol.


== Expert & Debugging Options ==
'''Summary:''' Comprehensive reference for <code>voipmonitor.conf</code> covering: sensor identification, database configuration (MySQL settings, partitioning, <code>mysqlloadconfig</code> for GUI vs file priority), network interface settings (BPF filters, deduplication with <code>auto_enable_use_blocks</code>), tunneling protocols (VXLAN, TZSP, HEP, AudioCodes), TLS/SRTP decryption, distributed client/server architecture (<code>packetbuffer_sender</code>), 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 <code>vxlan</code>, <code>packet_buffer_total_size</code>, <code>udp_reassembly</code>, <code>sipdefrag</code>.
'''Warning:''' These options should only be changed if you are an expert or instructed to do so by the support team.


;<code>database_backup_from_date = 2023-01-01</code>
'''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
:A family of options that puts the sniffer into a special database backup/migration mode, copying data from another database.
;<code>deduplicate = yes</code>
:(Default: no) Enables packet deduplication based on an MD5 checksum. Useful if you are receiving the same traffic stream from multiple sources.
;<code>coredump_filter = 0x7F</code>
:Controls what memory segments are included in a coredump file if the application crashes.
;<code>abort_if_heap_full = no</code>
:A set of options that control whether the sniffer should intentionally crash under certain high-load error conditions to generate a coredump for debugging.


== AI Summary for RAG ==
'''Summary:''' This document is a comprehensive reference guide for the `voipmonitor.conf` sniffer configuration file. It is logically structured into sections covering General Settings (sensor ID, timezone), Database Connection and Performance (MySQL settings, partitioning, queue tuning, cleaning), Network Interface and Sniffing (interface selection, BPF filters, tunneling protocols like TZSP/VXLAN, and kernel-bypass methods like DPDK), Performance and Threading (NUMA, scheduling), Distributed Architectures (the modern client/server model vs. legacy mirroring), and Storage Management (spooldir, TAR file usage, pcap saving, and automated cleaning rules). It also details protocol-specific configurations for SIP, RTP, SRTP, Skinny, MGCP, and others, including call timeout logic, DTMF detection, and call identity headers. A final section covers expert and debugging options like database backup mode and deduplication.
'''Keywords:''' voipmonitor.conf, configuration, sniffer config, sensor, database, mysql, mariadb, cdr_partition, cleandatabase, interface, sniffing, promisc, bpf, filter, tunneling, DPDK, performance, threading, t0CPU, client/server, distributed, remote sensor, spooldir, storage, pcap, tar, maxpoolsize, saveaudio, SIP, RTP, SRTP, DTLS, skinny, MGCP, SS7, diameter, NAT, natalias, call recording, watchdog, `sched_pol_auto`
'''Key Questions:'''
'''Key Questions:'''
* What are the most important settings in voipmonitor.conf for a new installation?
* What are the most important settings in voipmonitor.conf?
* How do I configure the database connection for the sniffer?
* How do I configure the database connection?
* How do I set up a distributed client/server architecture?
* Why does the sniffer fail with "failed read rsa key"?
* What is the difference between `packetbuffer_sender = yes` and `no`?
* How do I set up distributed client/server architecture?
* How do I tune the database for high performance using `innodb_buffer_pool_size` and other parameters?
* What is the difference between packetbuffer_sender = yes and no?
* How do I configure the sniffer to listen on multiple SIP ports?
* How do I enable packet deduplication?
* What are the `maxpoolsize` and `cleandatabase` options and how do they work?
* How do I decrypt TLS/SRTP traffic?
* How do I enable SRTP decryption?
* How do I disable audio recording while keeping RTP analysis?
* How do I configure VoIPmonitor to handle tunneled traffic from a Mikrotik router or AWS?
* How do I capture custom SIP headers?
* How do I selectively pause or stop call recording?
* 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?

Latest revision as of 11:21, 13 January 2026


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).

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

Understanding Audio Playback vs Pre-Generated Files

VoIPmonitor provides two independent methods for audio playback:

Method How it works Requirements Use Case
On-demand extraction (default) GUI extracts audio from stored RTP packets in PCAP files savesip = yes, savertp = yes Standard operation - recommended
Pre-generated files Sniffer creates .wav/.ogg/.mp3 files immediately during call processing saveaudio = wav (or ogg/mp3) Special requirements only

ℹ️ Note: The saveaudio option is NOT required for audio playback in the GUI. The GUI can extract audio on-demand from stored PCAP files whenever savertp = yes.

Important considerations for saveaudio:

  • CPU/IO intensive - Pre-generating audio files for every call significantly increases system load
  • Independent option - Works regardless of savertp/savesip settings
  • Storage overhead - Creates additional audio files beyond the PCAP storage
  • Use sparingly - Only enable when you have specific requirements (e.g., external systems that need direct audio file access)

To disable audio recording while keeping quality metrics: 

savertp = header   # Saves RTP headers only - keeps MOS/jitter/packet loss metrics
# saveaudio is 'no' by default - audio cannot be played/extracted

To keep full audio capability (default): 

savertp = yes      # Full RTP packets stored
# saveaudio is 'no' by default - GUI extracts audio on-demand from PCAP

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.


GUI Filters for SIP Response Searching

There are two distinct SIP response filters in the CDR view. Understanding their differences prevents confusion:

Filter What it searches Accepts Requires Configuration
Last SIP Response Code Final response code in cdr.lastSIPresponse Numeric codes (404, 503), wildcards (4%, 5%), and text (%OK, %Busy%) None - always available
SIP responses Full text of ALL SIP responses during the call Full text search, any string save_sip_history = responses or save_sip_responses = yes

Key differences:

  • Last SIP Response Code searches only the final response. Examples:
    • 200 - exact numeric match
    • 4% - all 4xx errors
    • %OK - responses ending with "OK"
    • %Busy% - responses containing "Busy"
  • SIP responses searches all SIP responses (180 Ringing, 183, provisional, etc.). Use for:
    • Intermediate responses (e.g., 491 Request Pending mid-dialog)
    • Custom SBC error messages
    • Any response text, not just the final one

Example: A call completes with 200 OK but had a 503 from one provider during serial forking. "Last SIP Response Code = 503" won't find it, but "SIP responses = %503%" will.

save_sip_history vs save_sip_responses

These two parameters achieve the same result - storing SIP response text for the "SIP responses" filter. Do not enable both simultaneously:

Parameter Notes
save_sip_history = responses Part of the multi-value save_sip_history option. Can combine with requests or use all.
save_sip_responses = yes Standalone parameter for same functionality. Simpler if you only need response text.

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 (IP Flow Information Export) is used with Oracle/ACME SBCs to receive call data.

IMPORTANT - PCAP Availability: IPFIX data is internally converted to packet format for processing. This means PCAP files CAN be downloaded from the GUI for IPFIX-sourced calls (SIP signaling is reconstructed). However, RTP streams are NOT included in the PCAP - only QoS metrics from the IPFIX data are available, not actual audio packets. 

ipfix = yes
ipfix_bind_port = 12345
ipfix_qos_fill_rtp_streams = yes
# Include TLS port for SIPS/SRTP:
sipport = 5060,5061
Parameter Default Description
ipfix no Enable IPFIX receiver (Oracle/ACME SBC)
ipfix_bind_ip 0.0.0.0 Bind IP address for IPFIX listener
ipfix_bind_port 4739 UDP port for IPFIX data
ipfix_qos_fill_rtp_streams no Populate RTP stream statistics from IPFIX QoS data

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.

ℹ️ Note: Oracle/ACME SBC and Ribbon SBC are products from different vendors with different integration methods:

  • Oracle SBC (formerly Acme Packet, acquired by Oracle in 2013) → uses IPFIX protocol
  • Ribbon SBC (formed from GENBAND + Sonus Networks merger in 2017) → uses Monitoring Profile with proprietary ribbonsbc protocol

Do not confuse these - they require different VoIPmonitor configuration.

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

DEPRECATED DO NOT USE

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