Sniffer configuration: Difference between revisions

From VoIPmonitor.org
(Clarify maxpool_clean_obsolete operates on filesystem cache not database)
(Add clarification about audio playback vs pre-generated files, explain saveaudio is independent and CPU intensive)
 
(70 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).


== Deprecated & Removed Options ==
'''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


The following configuration options were removed in sniffer version 2025.09.1. These options are no longer supported and should be removed from your configuration file. Keeping deprecated options does not cause errors (they are ignored), but cleaning them up reduces confusion.
= General & Core Settings =


=== VXLAN Options (Removed - 2025.09.1) ===
== Sensor Identification & Time ==
The old VXLAN configuration system was replaced. Remove these options and use the new format instead:


;syntaxhighlight lang="ini"
{| class="wikitable"
# DEPRECATED - Remove these options:
! Parameter !! Default !! Description
# vxlan = yes
|-
# vxlan_port = 4789
| <code>id_sensor</code> || unset || Unique numeric identifier (1-65535). '''Essential''' for multi-sensor deployments.
# vxlan_skipcrc = no
|-
# ;/syntaxhighlight
| <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>).
|}


;code>udp_port_vxlan = 4789</code>
== Process Management ==
:(Default: 4789) VXLAN, common in AWS and cloud environments. Use this single option instead of the deprecated vxlan/vxlan_port combination.


=== Packet Buffer & Memory Options (Removed - 2025.09.1) ===
{| class="wikitable"
;syntaxhighlight lang="ini"
! Parameter !! Default !! Description
# DEPRECATED Remove:
|-
# packet_buffer_total_size = 2000
| <code>watchdog</code> || no || Auto-restart sensor on crash.
# ;/syntaxhighlight
|-
| <code>watchdog_run_command</code> || unset || Custom restart command (e.g., <code>systemctl restart voipmonitor</code>).
|}


This setting is no longer needed. The packet buffer is now automatically managed. Use `max_buffer_mem` instead if you need to set a limit.
== Deprecated Options (v2025.09.1+) ==


=== UDP Reassembly Options (Removed - 2025.09.1) ===
{{Warning|1=The following options are '''unsupported and ignored''' in sniffer version 2025.09.1+. Remove them from your configuration.}}
;syntaxhighlight lang="ini"
# DEPRECATED - Remove these options:
# udp_reassembly = yes
# udp_reassembly_max_size = 500
# ;/syntaxhighlight


UDP packet reassembly is now handled automatically. These dedicated options are no longer needed.
{| class="wikitable"
! Deprecated Option !! Modern Replacement
|-
| <code>vxlan</code>, <code>vxlan_port</code>, <code>vxlan_skipcrc</code> || <code>udp_port_vxlan = 4789</code>
|-
| <code>packet_buffer_total_size</code> || <code>max_buffer_mem</code> (auto-managed)
|-
| <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)
|}


=== SIP Defragmentation Options (Removed - 2025.09.1) ===
{{Tip|After removing deprecated options, check logs for warnings: <code>journalctl -u voipmonitor -f</code>}}
;syntaxhighlight lang="ini"
# DEPRECATED - Remove these options:
# sipdefrag = yes
# sipdefrag_maxpacket = 100000
# defragment_max_size = 100000
# defragment_timeout = 10
# ;/syntaxhighlight


SIP packet defragmentation settings have been simplified and integrated into the core processing. The system now automatically handles fragmented SIP packets without these dedicated options.
= Database Configuration =


=== SIP Parsing Options (Removed - 2025.09.1) ===
== Connection Settings ==
;syntaxhighlight lang="ini"
# DEPRECATED - Remove these options:
# ignore_sip_parsing_errors = yes
# sip_auto_clean = yes
# max_sip_size = 200000
# sip_force_content_length = no
# ;/syntaxhighlight


SIP parsing is now more robust and auto-correcting. These fine-tuning options are no longer needed.
{| 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
|}


=== Sanity Check Options (Removed - 2025.09.1) ===
=== SSL/TLS for Database ===
;syntaxhighlight lang="ini"
<syntaxhighlight lang="ini">
# DEPRECATED - Remove these options:
mysqlsslkey = /etc/ssl/client-key.pem
# sanity_checks = yes
mysqlsslcert = /etc/ssl/client-cert.pem
# check_sip_header = yes
mysqlsslcacert = /etc/ssl/ca-cert.pem
# ;/syntaxhighlight
</syntaxhighlight>


General sanity checking is now built-in and cannot be disabled.
== Performance & Schema ==


=== Interface Capture Length (Removed - 2025.09.1) ===
{| class="wikitable"
;syntaxhighlight lang="ini"
! Parameter !! Default !! Description
# DEPRECATED - Remove:
|-
# interface_snaplen = 3200
| <code>query_cache</code> || yes || '''Critical:''' Queue SQL to disk (qoq* files) to prevent data loss during DB outages.
# ;/syntaxhighlight
|-
| <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).
|}


Use `snaplen` instead (see Network Interface & Sniffing section below).
== Configuration Priority: File vs GUI ==


=== Supported Alternatives ===
;<code>mysqlloadconfig = yes</code>
These options remain supported and should be used instead:
:(Default: yes) Load settings from database (<code>sensor_config</code> table). '''GUI settings take priority over file settings.'''
;code>udp_port_vxlan</code> - Port for VXLAN tunneling (replaces vxlan_port)
;code>auto_enable_use_blocks</code> - Enables memory blocks for deduplication/defrag
;code>deduplicate</code> - Packet deduplication based on checksum
;code>snaplen</code> - Packet capture length (replaces interface_snaplen)


== General & Core Settings ==
{{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.}}


=== Time and Sensor Identification ===
'''Diagnosing conflicts:'''
;<code>id_sensor = 1</code>
<syntaxhighlight lang="bash">
:(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.
systemctl restart voipmonitor
grep 'Configuration valu' /var/log/syslog | grep ' / '
</syntaxhighlight>


;<code>utc = yes</code>
'''Resolution options:'''
:(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.
* '''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


;<code>timezone = /usr/share/zoneinfo/UTC</code>
== SQL Queue Tuning ==
:(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.


=== Process Management ===
{| class="wikitable"
;<code>watchdog = yes</code>
! Parameter !! Default !! Description
:(Default: no) If enabled, a watchdog process is created that automatically restarts the voipmonitor sensor if it crashes or is terminated unexpectedly.
|-
| <code>mysqlstore_concat_limit</code> || 400 || SQL statements per batch
|-
| <code>mysqlstore_max_threads_cdr</code> || 2 || Max parallel CDR write threads
|}


;<code>watchdog_run_command = systemctl restart voipmonitor</code>
== Database Cleaning ==
:(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`.


== Database Configuration ==
See [[Data_Cleaning]] for detailed documentation.


=== Connection Settings ===
{| class="wikitable"
;<code>mysqlhost = localhost</code>
! Parameter !! Default !! Description
:IP address or hostname of the MySQL/MariaDB server.
|-
;<code>mysqlsocket = /var/run/mysqld/mysqld.sock</code>
| <code>cleandatabase</code> || 0 || Master retention period in days (0=disabled)
:Path to the MySQL socket file for local connections (often faster than TCP).
|-
;<code>mysqlport = 3306</code>
| <code>cleandatabase_cdr</code> || 0 || CDR/message table retention
:TCP port of the database server.
|-
;<code>mysqlusername = root</code>
| <code>cleandatabase_rtp_stat</code> || 2 || RTP statistics retention
:Username for the database connection.
|-
;<code>mysqlpassword =</code>
| <code>partition_operations_enable_fromto</code> || 1-5 || Partition drop time window (e.g., 1-5 AM)
: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 ===
== CDR Summary (Aggregation) ==
;<code>mysqlsslkey = /etc/ssl/client-key.pem</code>
:Path to the client's SSL private key file.
;<code>mysqlsslcert = /etc/ssl/client-cert.pem</code>
:Path to the client's SSL certificate file.
;<code>mysqlsslcacert = /etc/ssl/ca-cert.pem</code>
:Path to the Certificate Authority (CA) certificate file.
;<code>mysqlsslcapath = /etc/ssl/capath</code>
:Directory containing CA certificates.
;<code>mysqlsslciphers =</code>
:List of allowed SSL ciphers.


=== Performance & Schema ===
Pre-aggregates call data for faster dashboard queries.
;<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_partition_operations = yes</code>
:(Default: no) Disables automatic partition creation. Useful when multiple sensors write to a single database and only one should manage partitions.
;<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>
:(Default: yes) Allows loading additional configuration parameters dynamically from the `sensor_conf` database table.
;<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.
;<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.
;<code>cdr_force_primary_index_in_all_tables = no</code>
:(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.
;<code>disable_cdr_fields_rtp = no</code>
:(Default: no) Disables all RTP-related statistics columns in the CDR table to save space.
;<code>sqlcallend = yes</code>
:(Default: yes) Enables storing `cdr.callend` (calldate + duration). Disable only if the column is missing.


=== SQL Queue Tuning ===
<syntaxhighlight lang="ini">
;<code>mysqlstore_concat_limit = 400</code>
cdr_summary = yes
:(Default: 400) Sets the global number of SQL statements to batch together before sending to the database.
cdr_summary_interval = 5  # minutes
;<code>mysqlstore_max_threads_cdr = 2</code>
</syntaxhighlight>
:(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.
;''Note: Separate `_concat_limit_*` and `_max_threads_*` options exist for `message`, `register`, `http`, etc.''
;<code>server_sql_queue_limit = 1000000</code>
:(Default: 1000000) Limits the SQL queue size on the server side in client/server deployments. Set to 0 to disable.
;<code>server_sql_concat_limit = 5000</code>
:(Default: 1000) Number of queries to batch before confirming receipt in client/server mode.


=== Database Cleaning ===
= Network Interface & Sniffing =
;<code>cleandatabase = 0</code>
:(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>
:(Default: 0, disabled) Specific retention period for `cdr` and `message` tables.
;<code>cleandatabase_rtp_stat = 2</code>
:(Default: 2) Retention period in days for detailed RTP statistics.
;<code>cleandatabase_register_failed = 0</code>
:(Default: 0) Retention for `register_failed` table.
;<code>cleandatabase_register_state = 0</code>
:(Default: 0) Retention for `register_state` table.
;<code>cleandatabase_sip_msg = 0</code>
:(Default: 0) Retention for `sip_msg` table (OPTIONS/SUBSCRIBE/NOTIFY).
;<code>cleandatabase_ss7 = 0</code>
:(Default: 0) Retention for `ss7` table.
;<code>cleandatabase_cdr_rtp_energylevels = 0</code>
:(Default: 0) Retention for energy levels table.
;<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>cleandatabase_size = 500000</code>
:(Default: unset) An alternative cleaning method that removes old data to stay below a total database size limit (in MB).


=== CDR Summary (Aggregation) ===
== Interface Selection ==


The CDR Summary feature pre-aggregates call data into intervals for significantly faster dashboard and reporting queries. See [[CDR_Summary]] for complete documentation including GUI behavior.
{| 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.
|}


;<code>cdr_summary = yes</code>
== BPF Filtering ==
:(Default: no) Enables the CDR summary feature. When enabled, the sniffer creates a <code>cdr_summary</code> table and continuously aggregates CDR data by sipcallerip, sipcalledip, payload, and last_sip_response.
;<code>cdr_summary_interval = 5</code>
:(Default: 5) The aggregation interval in minutes. Data is grouped into buckets of this size.
;<code>cleandatabase_cdr_summary = 0</code>
:(Default: 0, uses cleandatabase setting) Optional separate retention period in days specifically for the <code>cdr_summary</code> table. If not set, the main <code>cleandatabase</code> setting is used.


=== SQL Error Logging ===
;<code>filter</code>
;<code>sql_log_all_errors = no</code>
:BPF filter (tcpdump syntax). '''Warning:''' Can accidentally exclude important traffic.
:(Default: no) Logs all SQL errors to syslog.
<syntaxhighlight lang="ini">
;<code>sql_errors_log_file = /path/to/log</code>
# Example: Exclude specific subnets
:(Default: unset) Redirects SQL error logging to a specific file.
filter = not net 192.168.0.0/16 and not net 10.0.0.0/8
;<code>sql_errors_skip = 1054,1136</code>
</syntaxhighlight>
:(Default: unset) A comma-separated list of SQL error codes to ignore and not log.
 
== Network Interface & Sniffing ==
This section configures how the sensor captures packets.


=== Interface Selection ===
;<code>interface_ip_filter</code>
;<code>interface = eth0</code>
:CPU-efficient IP allow-list (no negation). Multiple lines supported.
: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>eth_max_channels = 0</code>
:(Default: 0) Sets number of NIC interrupt queues. 0 means no change.
;<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.
;<code>snaplen = 3200</code>
:(Default: 3200, 6000 if SSL/HTTP enabled) Packet capture length override.
 
=== High-Traffic Parallel Capture ===
For environments with very high packet rates (>2.2M pps), you can split traffic across multiple processing threads:
 
;<code>interface_libpcap_filter = eth0 : port 5060</code>
:(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.
 
'''Example for splitting traffic:'''
<syntaxhighlight lang="ini">
<syntaxhighlight lang="ini">
# Split SIP and non-SIP traffic into separate processing threads
interface_ip_filter = 192.168.0.0/24
interface_libpcap_filter = eth0 : port 5060
interface_ip_filter = 10.0.0.0/8
interface_libpcap_filter = eth0 : not port 5060
</syntaxhighlight>
</syntaxhighlight>


=== Tunneling Protocol Support ===
== Shared Server Optimization ==
VoIPmonitor can decode various tunneling protocols. To enable listening, uncomment and configure the relevant port.
;<code>udp_port_tzsp = 37008</code>
:(Default: 37008) Mikrotik TZSP protocol.
;<code>udp_port_l2tp = 1701</code>
:(Default: 1701) L2TP tunneling.
;<code>udp_port_vxlan = 4789</code>
:(Default: 4789) VXLAN, common in AWS and cloud environments.
;<code>udp_port_hperm = 7932</code>
:(Default: 7932) HP ERM protocol.
;<code>audiocodes = yes</code>
:(Default: no) Enables AudioCodes proprietary tunnel.
;<code>udp_port_audiocodes = 925</code>
:Port for AudioCodes mirroring.
;<code>audiocodes_rtp = yes</code>
:Enable AudioCodes RTP processing. Options: no, yes, only, only_for_audiocodes_sip.
;<code>ipfix = yes</code>
:(Default: no) Enables IPFIX, used by Oracle/ACME SBCs. See [[#IPFIX Support|IPFIX Support]] section.
;<code>hep = yes</code>
;<code>hep_bind_port = 9060</code>
:(Default: 9060) Port to listen for HEP (Homer Encapsulation Protocol) packets.
;<code>hep_bind_ip = 0.0.0.0</code>
:(Default: unset) IP address to bind for HEP listener. If unset, binds to all interfaces.
:(Default: no) Enables Homer Encapsulation Protocol.
;<code>kamailio_port = 5888</code>
:(Default: unset) Enables mirroring from Kamailio's `siptrace` module.
;<code>ribbonsbc = yes</code>
:(Default: no) Enables Ribbon SBC mirroring. See [[#Ribbon SBC Mirroring|Ribbon SBC Mirroring]] section.
;<code>icmp_process_data = no</code>
:(Default: no) Extract SIP data from ICMP type 3 messages.


=== Packet Deduplication ===
When the sniffer runs on the same server as the PBX, resource contention can cause voice breakage.
When traffic is received from multiple sources or mirrored from multiple points, the same packet may arrive more than once. The deduplication feature identifies and discards duplicate packets based on checksum comparison.


'''Typical configuration for deduplication:'''
'''Symptoms:''' Audio jitter, packet loss, call lag that resolves when sniffer is stopped.
 
'''Solutions:'''
<syntaxhighlight lang="ini">
<syntaxhighlight lang="ini">
# Enable packet deduplication. Uses checksum to identify
# Solution 1: Specify interfaces (creates dedicated threads)
# and discard duplicate packets. This is CPU intensive.
interface = ens192,ens224  # NOT 'any'
deduplicate = yes


# Required for deduplication to work correctly when
# Solution 2: Disable NIC optimization
# packets are received from multiple sources or interfaces.
interfaces_optimize = no
auto_enable_use_blocks = yes


# Count only IP addresses from IP header in the checksum.
# Solution 3: Reduce sniffer load
# This is useful when the same packet arrives from different
savertp = header
# network paths with different TTL or other IP header fields.
saveaudio = no
deduplicate_ipheader = ip_only
</syntaxhighlight>
</syntaxhighlight>


;<code>deduplicate = yes</code>
'''Long-term:''' Move sensor to dedicated server with SPAN/Mirror. See [[Sniffer_distributed_architecture]].
:(Default: no) Enables packet deduplication based on a checksum (MD5 or the faster experimental "murmur" algorithm). Useful if you are receiving the same traffic stream from multiple sources or interfaces. '''Note:''' This is CPU intensive.


;<code>auto_enable_use_blocks = yes</code>
== Packet Deduplication ==
:(Default: no) '''Required for deduplication''' when sniffing from multiple sources or interfaces. Automatically enables use of memory blocks for deduplication and defragmentation processing.


;<code>deduplicate_ipheader = ip_only</code>
Required when receiving same packets from multiple sources/interfaces.
:(Default: yes, meaning full IP header) Controls how the IP header is used in the deduplication checksum:
:* <code>yes</code> (default): Include the full IP header in the checksum
:* <code>ip_only</code>: Count only the source and destination IP addresses from the IP header. '''Recommended''' when packets arrive from different network paths that may modify TTL or other IP header fields.
:* <code>no</code>: Exclude the IP header entirely from the checksum


;<code>deduplicate_ipheader_ignore_ttl = yes</code>
<syntaxhighlight lang="ini">
:(Default: yes) Ignore the TTL (Time To Live) field in the IP header when comparing packets. This prevents false negatives when the same packet arrives via different network hops.
deduplicate = yes
auto_enable_use_blocks = yes # Required for deduplication
deduplicate_ipheader = ip_only  # Recommended for different network paths
</syntaxhighlight>


;<code>deduplicate_udpheader_ignore_checksum = yes</code>
{| class="wikitable"
:(Default: yes) Exclude the UDP header checksum when comparing packets. Useful because some network equipment may recalculate the UDP checksum, causing identical payload packets to have different checksums.
! 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
|}


=== Scan PCAP Directory Mode ===
== Tunneling Protocol Support ==
;<code>scanpcapdir = /dev/shm/voipmonitor</code>
:(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>scanpcapmethod = newfile</code>
:(Default: newfile) Method for detecting new files. Options: newfile, rename.


=== SIP Send (Third-Party Forwarding) ===
{| class="wikitable"
;<code>sip_send = 192.168.0.2:1555</code>
! Parameter !! Default !! Description
:(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.
|-
;<code>sip_send_udp = yes</code>
| <code>udp_port_tzsp</code> || 37008 || Mikrotik TZSP
:(Default: no) Use UDP instead of TCP for sip_send.
|-
;<code>sip_send_before_packetbuffer = yes</code>
| <code>udp_port_l2tp</code> || 1701 || L2TP tunneling
:(Default: no) Send packets immediately without buffering.
|-
| <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
|}


== SIP Port & TCP Configuration ==
== Scan PCAP Directory Mode ==


=== SIP Port Settings ===
Process PCAP files instead of live capture. Useful for Windows hosts without SPAN ports.
;<code>sipport = 5060</code>
:(Default: 5060) Specifies the SIP ports that VoIPmonitor will listen to. Multiple ports can be specified: `sipport = 5060,5061,5062,5070-5080`.
;<code>cdr_sipport = yes</code>
:(Default: yes) Store SIP source and destination ports in the database.
;<code>cdr_rtpport = yes</code>
:(Default: yes) Store RTP destination port in the database.
;<code>cdr_rtpsrcport = no</code>
:(Default: no) Store RTP source port in the database.


=== TCP Reassembly ===
<syntaxhighlight lang="ini">
;<code>sip_tcp_reassembly_ext = yes</code>
scanpcapdir = /var/spool/voipmonitor/scanpcap
:(Default: yes) Enable TCP reassembly for SIP over TCP.
scanpcapmethod = newfile
;<code>sip_tcp_reassembly_stream_max_attempts = 50</code>
</syntaxhighlight>
:(Default: 50) Maximum TCP reassembly attempts.
;<code>sip_tcp_reassembly_ext_link_timeout = 10</code>
:(Default: 10) TCP reassembly link timeout in seconds.
;<code>sip_tcp_reassembly_ext_quick_mod = no</code>
:(Default: no) Experimental quick mode for high traffic. Options: no, yes, ext, comb_ext.


=== SIP Packet Limits ===
'''Workflow:'''
;<code>max_sip_packets_in_call = 2000</code>
# Capture on source: <code>tcpdump -i eth0 udp -G 300 -w /path/dump.pcap</code>
:(Default: 2000) Maximum SIP packets per call.
# Transfer to VoIPmonitor server
;<code>max_invite_packets_in_call = 10000</code>
# Sensor processes files automatically
:(Default: 10000) Maximum SIP INVITE packets per call.


== SIP TLS/SSL Decryption ==
= SIP Configuration =


To decrypt TLS-encrypted SIP traffic, you need to provide the private key. Note that Diffie-Hellman ciphers cannot be decrypted without session keys.
== Port Settings ==


;<code>ssl = yes</code>
{| class="wikitable"
:(Default: no) Enable TLS/SSL decryption for SIP.
! 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.
|}


;<code>ssl_ipport = 10.0.0.1 : 5061 /path/to/your.key</code>
== TCP Reassembly & UDP Fragmentation ==
:(Default: unset) Specify IP:port and private key for decryption. Multiple keys can be separated by commas.


;<code>ssl_ipport = 10.0.0.0/24 : 5061 /path/to/your.key,/path/to/other.key</code>
{| class="wikitable"
:Example with subnet and multiple keys.
! 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
|}


;<code>ssl_ipport_reverse_enable = yes</code>
= TLS/SSL & SRTP Decryption =
:(Default: no) Enable reverse detection logic for ssl_ipport.


;<code>ssl_store_sessions_expiration_hours = 12</code>
== SIP TLS Decryption ==
:(Default: 12) SSL sessions expire after this many hours.


;<code>ssl_sessionkey_udp = yes</code>
<syntaxhighlight lang="ini">
:(Default: no) Enable parsing of session keys sent via UDP (keylogger support).
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>


;<code>ssl_sessionkey_udp_port = 1234</code>
'''Keylogger support (for PFS/TLS 1.3):'''
:UDP port for receiving session keys.
<syntaxhighlight lang="ini">
 
ssl_sessionkey_udp = yes
;<code>ssl_store_sessions = persistent</code>
ssl_sessionkey_udp_port = 1234
:(Default: persistent) How to store SSL keys: 'persistent' (InnoDB) or 'memory'.
</syntaxhighlight>
 
;<code>ssl_tls_12_sessionkey_mode = dssl</code>
:(Default: dssl) Decryption library: 'dssl' or 'wireshark'.


;<code>ssl_ignore_error_invalid_mac = yes</code>
See [[Tls]] for complete TLS decryption documentation.
:(Default: yes) Ignore SSL/TLS packets with invalid MAC.


== SRTP Configuration ==
== SRTP Configuration ==


This section deals with Secure RTP (SRTP) decryption, including both RTP and RTCP streams. Supported encryption algorithms: AES_CM_128_HMAC_SHA1_32, AES_CM_128_HMAC_SHA1_80.
{| 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
|}


;<code>srtp_rtp = no</code>
= Caller/Called Identity =
:(Default: no) Decrypt and store RTP data in PCAPs. By default, only RTCP is decrypted.


;<code>srtp_rtcp = yes</code>
{| class="wikitable"
:(Default: yes) Decrypt RTCP streams.
! 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)
|}


;<code>srtp_rtp_dtmf = no</code>
= Performance & Threading =
:(Default: no) Decrypt only RTP DTMF packets.


;<code>srtp_rtp_dtls = yes</code>
== Core Threading ==
:(Default: yes) Enable DTLS decryption. Requires keylogger or session keys.


;<code>ssl_dtls_queue = yes</code>
{| class="wikitable"
:(Default: no) Enable DTLS packet queue to prevent packet loss during decryption.
! 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
|}


;<code>ssl_dtls_queue_expiration = 10</code>
== Buffer Configuration ==
:(Default: 10) DTLS queue expiration time in seconds.


;<code>srtp_rtp_local_instances = no</code>
{| class="wikitable"
:(Default: no) Create separate decryption instance per RTP stream.
! 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.
|}


;<code>ssl_dtls_queue_keep = no</code>
== Thread Priority ==
:(Default: no) Keep DTLS packets in queue after first successful use.


;<code>ssl_sessionkey_keep = no</code>
<syntaxhighlight lang="ini">
:(Default: no) Keep keylogger keys until expiration instead of discarding after first use.
sched_pol_auto = prio -20  # Auto-elevate critical threads under load
sched_pol_auto_cpu_limit = 45  # CPU threshold for elevation
</syntaxhighlight>


;<code>ssl_dtls_handshake_safe = no</code>
= Distributed Operation =
:(Default: no) DTLS handling approach: no (queue), only (unified), yes (both, queue priority), ext (both, unified priority).


;<code>ssl_dtls_boost = no</code>
See [[Sniffer_distributed_architecture]] for complete documentation.
:(Default: no) A '''meta-parameter''' that enables a set of aggressive options for improving DTLS handshake and SRTP decryption success rates. When enabled, it sets:
:* ssl_dtls_queue_expiration = 30
:* ssl_sessionkey_keep = yes
:* ssl_dtls_queue_keep = yes
:* ssl_dtls_handshake_safe = ext
:* ssl_dtls_rtp_local = yes


== Caller/Called Identity Configuration ==
<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>


These options control how caller and called party information is extracted from SIP headers.
== Client/Server Configuration ==


;<code>remoteparty_caller = calling</code>
'''Central Server:'''
:(Default: unset) Update caller number from Remote-Party-ID header. Use 'calling' or 'called' based on the party attribute.
<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>


;<code>remoteparty_called = called</code>
'''Remote Sensor:'''
:(Default: unset) Update called number from Remote-Party-ID header.
<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>


;<code>passertedidentity = no</code>
{{Warning|1=When <code>packetbuffer_sender = yes</code>, '''all packets including RTP are transmitted''' regardless of <code>savertp</code> setting.}}
:(Default: no) Use P-Asserted-Identity header for caller info.


;<code>ppreferredidentity = no</code>
= Storage & File Management =
:(Default: no) Use P-Preferred-Identity header for caller info.


;<code>remotepartypriority = no</code>
== Spool Directory ==
:(Default: no) Give Remote-Party-ID priority over P-Asserted-Identity and P-Preferred-Identity.


;<code>callernum_numberonly = yes</code>
{| class="wikitable"
:(Default: yes) Parse only the number part from identity headers.
! 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)
|}


;<code>destination_number_mode = 1</code>
{{Note|1=For GUI access to <code>spooldir_2</code>, configure "Sniffer second datapath" in GUI Settings > System Configuration > Basic.}}
:(Default: 1) Source for destination number: 1 = To header, 2 = INVITE URI.


;<code>sipoverlap = yes</code>
== TAR Storage Strategy ==
:(Default: yes) Update destination number from subsequent INVITEs (overlap dialing support per RFC 3578).


;<code>last_dest_number = no</code>
<syntaxhighlight lang="ini">
:(Default: no) Always take destination from latest INVITE regardless of source IP.
tar = yes  # Group PCAPs into minute-based archives (reduces I/O)
tar_compress_sip = zstd
tar_compress_graph = zstd
</syntaxhighlight>


;<code>update_dstnum_onanswer = no</code>
== Saving Options ==
:(Default: no) Update destination number when callee answers (useful for hunt groups).


== Performance & Threading ==
{| 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
|}


=== Core Threading Model ===
'''Disable audio recording:'''
;<code>threading_expanded = yes</code>
<syntaxhighlight lang="ini">
:(Default: yes) Enables the modern, multi-threaded processing engine. The sniffer automatically spawns and manages threads based on traffic load and CPU capacity. Set to `high_traffic` for environments exceeding 5 Gbit/s.
savertp = header  # NOT 'no' - keeps RTP analysis tool working
;<code>preprocess_rtp_threads = 2</code>
saveaudio = no
:(Default: 2) The initial number of threads for RTP preprocessing. The system will auto-scale from here.
</syntaxhighlight>
;<code>preprocess_rtp_threads_max = 5</code>
:(Default: unlimited) Maximum RTP preprocessing threads.
;<code>pre_process_packets_next_thread = 4</code>
:For high network throughput (>= 5Gbit), set to 4.
;<code>pre_process_packets_next_thread_max = 4</code>
:Hard limit is 4 even if value is higher.
;<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).
;<code>rtpthreads = 0</code>
:(Default: CPU count) Number of threads for RTP packet processing. 0 disables threading.


=== Thread Scheduling & Priority ===
== Spool Cleaning ==
;<code>sched_pol_auto = prio -20</code>
:(Default: `prio -20`) Automatically elevates the priority (lowers the `nice` value) of critical threads if the system comes under load.
;<code>sched_pol_auto_heap_limit = 1</code>
:(Default: 1) Heap growth percentage threshold for priority elevation.
;<code>sched_pol_auto_cpu_limit = 45</code>
:(Default: 45) CPU usage threshold for priority elevation.


Manual thread priority settings (alternative to auto):
{| class="wikitable"
;<code>sched_pol_interface = prio -20</code>
! Parameter !! Default !! Description
;<code>sched_pol_pb = prio -20</code>
|-
;<code>sched_pol_sip = prio -20</code>
| <code>cleanspool</code> || yes || Enable automatic spool cleaning
;<code>sched_pol_rtp_prep = prio -20</code>
|-
;<code>sched_pol_rtp_read = prio -20</code>
| <code>maxpoolsize</code> || 102400 || Size limit in MB
|-
| <code>maxpooldays</code> || unset || Age limit in days
|-
| <code>autocleanspoolminpercent</code> || 1 || Emergency cleaning trigger (% free)
|}


=== NUMA & Memory ===
== Audio File Generation ==
;<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.


=== Buffer Configuration ===
{| class="wikitable"
;<code>ringbuffer = 50</code>
! Parameter !! Default !! Description
:(Default: 50) Ringbuffer size in MB. Recommended >= 500 for >100 Mbit traffic. Max 2000.
|-
;<code>packetbuffer_enable = yes</code>
| <code>saveaudio</code> || no || Generate audio files: <code>wav</code>, <code>ogg</code>, <code>mp3</code>, or <code>yes</code>
:(Default: yes) Enable packet buffer cache.
|-
;<code>packetbuffer_compress = no</code>
| <code>saveaudio_singlefolder</code> || unset || Dedicated directory for audio files
:(Default: no) Enable packet buffer compression.
|-
;<code>max_buffer_mem = 2000</code>
| <code>saveaudio_stereo</code> || yes || Caller=left, called=right channel
:(Default: 2000) Maximum buffer memory in MB.
|}
;<code>memory_purge_interval = 30</code>
=== Understanding Audio Playback vs Pre-Generated Files ===
:(Default: 30) Memory purge interval in seconds.
;<code>memory_purge_if_release_gt = 500</code>
:(Default: 500) Memory purge threshold in MB.


== Distributed Operation: Client/Server & Mirroring ==
VoIPmonitor provides '''two independent methods''' for audio playback:


=== Modern Client/Server Model (Recommended) ===
{| class="wikitable"
;<code>server_bind = 0.0.0.0</code>
! Method !! How it works !! Requirements !! Use Case
:The IP address the central sensor will listen on for connections from remote clients.
|-
;<code>server_bind_port = 60024</code>
| '''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
:(Default: 60024) Port for client connections.
|-
;<code>server_destination = 10.0.0.1</code>
| '''Pre-generated files''' || Sniffer creates .wav/.ogg/.mp3 files immediately during call processing || <code>saveaudio = wav</code> (or ogg/mp3) || Special requirements only
:The IP address of the central server a remote sensor should connect to. Multiple IPs for failover: `192.168.0.1, 192.168.0.2`.
|}
;<code>server_destination_port = 60024</code>
:(Default: 60024) Port of the central server.
;<code>server_password =</code>
:A shared password to authenticate clients and servers.
;<code>manager_ip = 10.0.0.5</code>
:The local IP address to bind as the source when connecting to the central server. Use this when the sensor has multiple network interfaces and you want to enforce a specific source IP (e.g., static IP in an HA setup instead of a floating/virtual IP). This parameter is only applicable on client/sensor nodes.
;<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. Options: zstd, gzip, lzo, none.
;<code>receiver_check_id_sensor = yes</code>
:(Default: yes) Differentiate packets by originating sensor. Set to 'no' for multipath routing scenarios.


=== Time Synchronization ===
{{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>.}}
;<code>mirror_connect_maximum_time_diff_s = 2</code>
:(Default: 2) Maximum time difference for mirror connections.
;<code>client_server_connect_maximum_time_diff_s = 2</code>
:(Default: 2) Maximum time difference for client/server connections.
;<code>receive_packetbuffer_maximum_time_diff_s = 30</code>
:(Default: 30) Maximum time difference for packet buffer reception.


=== Legacy Mirroring Model ===
'''Important considerations for <code>saveaudio</code>:'''
;<code>mirror_bind_ip = 0.0.0.0</code>
* '''CPU/IO intensive''' - Pre-generating audio files for every call significantly increases system load
:The IP the receiver sensor listens on for the unencrypted, legacy mirroring protocol.
* '''Independent option''' - Works regardless of <code>savertp</code>/<code>savesip</code> settings
;<code>mirror_bind_port =</code>
* '''Storage overhead''' - Creates additional audio files beyond the PCAP storage
:Port for legacy mirroring.
* '''Use sparingly''' - Only enable when you have specific requirements (e.g., external systems that need direct audio file access)
;<code>mirror_destination_ip = 10.0.0.1</code>
:The IP of the receiver sensor that the sender should stream packets to.
;<code>mirror_destination_port =</code>
:Port for mirror destination.
;<code>mirror_require_confirmation = yes</code>
:(Default: yes) Require packet confirmation. Disable for higher throughput.
;<code>mirror_use_checksum = yes</code>
:(Default: yes) Enable block-level checksums.
;<code>pcap_queue_dequeu_window_length = 2000</code>
:(Default: 2000) Window length in ms for sorting packets from multiple mirrors.


== Storage & File Management (Spooldir) ==
'''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>


=== Location and Permissions ===
'''To keep full audio capability (default):'''
;<code>spooldir = /var/spool/voipmonitor</code>
<syntaxhighlight lang="ini">
:The primary directory for storing all captured data (PCAP, GRAPH, AUDIO files).
savertp = yes      # Full RTP packets stored
;<code>spooldir_rtp =</code>
# saveaudio is 'no' by default - GUI extracts audio on-demand from PCAP
:Separate directory for RTP files.
</syntaxhighlight>
;<code>spooldir_graph =</code>
= Call Processing =
:Separate directory for graph files.
;<code>spooldir_audio =</code>
:Separate directory for audio files.
;<code>spooldir_2 = /var/spool/voipmonitor2</code>
:Secondary storage directory with separate autoclean setup.
;<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_owner = root</code>
;<code>spooldir_group = root</code>
:Owner and group for created files.
;<code>spooldir_by_sensor = no</code>
:(Default: no) If enabled, creates subdirectories within the spooldir for each `id_sensor`.
;<code>spooldir_by_sensorname = yes</code>
:Organize by sensor name instead of ID.
;<code>name_sensor = sensor1</code>
:Sensor name for directory organization.
;<code>cachedir = /dev/shm/voipmonitor</code>
:Cache directory for temporary storage. Use RAM or SSD for better performance.


=== PCAP/TAR Storage Strategy ===
== Timeouts ==
;<code>tar = yes</code>
:(Default: yes) This is a key performance feature. When set to `no`, individual PCAP files are written directly without TAR archiving. Instead of writing thousands of small PCAP files, voipmonitor groups them into minute-based `.tar` archives, which drastically reduces disk I/O load.
;<code>tar_maxthreads = 8</code>
:(Default: 8) Maximum threads for tar compression.
;<code>tar_compress_sip = zstd</code>
:(Default: zstd) SIP TAR compression. Options: none, gzip, zstd, lzma.
;<code>tar_sip_level_zstd = 1</code>
:(Default: 1) Compression level for SIP TAR.
;<code>tar_compress_rtp = no</code>
:(Default: no) RTP TAR compression. Individual RTP pcaps are compressed with lzo by default.
;<code>tar_compress_graph = zstd</code>
:(Default: zstd) Graph TAR compression.
;<code>tar_graph_level_zstd = 1</code>
:(Default: 1) Compression level for graph TAR.
;<code>tar_move = yes</code>
:(Default: no) Move tar files to another directory after closing. Options: no, yes (move and delete), copy.
;<code>tar_move_destination_path = /mnt/nfs/storage</code>
:Destination for tar move.
;<code>tar_move_max_threads = 2</code>
:(Default: 2) Threads for moving tar files.


;=== Legacy Directory Structure ===
{| class="wikitable"
;<code>spooldiroldschema = yes</code>
! 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
|}


:(Default: no) When enabled, uses the old directory schema `YYYY-MM-DD` (flat structure) instead of the default nested `YYYY/MM/HH` structure for organizing PCAP files in the spooldir. This keeps all recordings from a single day in one directory. Note: enabling this automatically disables TAR archiving and automatic spool cleaning (cleanspool).
== Call Merging ==


;=== PCAP File Splitting ===
{| class="wikitable"
;<code>pcapsplit = yes</code>
! 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)
|}


:(Default: yes) When set to `no`, all calls are saved into a single PCAP file per minute instead of splitting each call into separate files. This is useful for creating continuous single-pcap recordings. Note: combining `pcapsplit=no` with `tar=no` and `spooldiroldschema=yes` will save all recordings into a single directory with minimal file splitting.
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 ==


=== Saving Options ===
<syntaxhighlight lang="ini">
;<code>savesip = yes</code>
custom_headers = Referred-By, Diversion, X-Custom-Header
:Enables saving of SIP packets.
custom_headers_last_value = yes
;<code>savertp = yes</code>
custom_headers_max_size = 1024
:Enables saving of RTP packets. Set to `header` to save only RTP headers, not the audio payload.
</syntaxhighlight>
;<code>savertp_video = no</code>
:(Default: no) Save video RTP packets. Options: no, yes, header, cdr_only.
;<code>savertcp = yes</code>
:Enables saving of RTCP (RTP Control Protocol) packets.
;<code>savegraph = yes</code>
:Enables saving of call graph data.
;<code>null_rtppayload = no</code>
:(Default: no) Zero out all RTP payload data.
;<code>maxpcapsize = 500</code>
:(Default: unset) Maximum pcap file size in MB.


=== PCAP Compression ===
After adding headers, configure display in GUI: '''Settings > CDR Custom Headers'''.
;<code>pcap_dump_zip = yes</code>
:(Default: yes) Enable file compression for pcap files.
;<code>pcap_dump_zip_sip = zstd</code>
:SIP compression. Options: no, zstd, gzip, lzo, lz4.
;<code>pcap_dump_zip_rtp = lzo</code>
:(Default: lzo) RTP compression.
;<code>pcap_dump_zip_graph = no</code>
:Graph compression.
;<code>pcap_dump_ziplevel = 3</code>
:(Default: 3) Compression level.
;<code>pcap_dump_writethreads = 1</code>
:(Default: 1) Initial compression threads. Auto-scales.
;<code>pcap_dump_writethreads_max = 32</code>
:(Default: 32) Maximum compression threads.
;<code>pcap_dump_asyncwrite = yes</code>
:(Default: yes) Enable asynchronous writing.
;<code>pcap_dump_bufflength = 8184</code>
:(Default: 8184) Buffer size in bytes.


=== Spool Cleaning ===
== SIP History ==
;<code>cleanspool = yes</code>
:(Default: yes) Enables the automatic cleaning process for the spool directory.
;<code>cleanspool_enable_fromto = 1-5</code>
:(Default: 0-24) Restrict cleaning to specific hours.
;<code>maxpoolsize = 102400</code>
:(Default: 100 GB) The primary retention setting. Deletes the oldest data hourly until the specified size limit is reached (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*`, `maxpoolgraph*`, `maxpoolaudio*` options exist for granular policies.''
;<code>autocleanspoolminpercent = 1</code>
:(Default: 1%) Emergency cleaning trigger percentage.
;<code>autocleanmingb = 5</code>
:(Default: 5 GB) Emergency cleaning trigger in GB.
;<code>maxpool_clean_obsolete = yes</code>
:(Default: no) Delete files NOT found in the <code>.cleanspool_cache</code> filesystem index. When <code>no</code>, cleanspool will only delete files that are indexed (scanned into the cache file). When <code>yes</code>, any files in the spool directory that are not in the cache index will also be deleted. Note: This operates on the filesystem cache index, NOT the database. The cleanspool process deletes all indexed files based on <code>maxpoolsize</code>/<code>maxpooldays</code> limits, regardless of whether those files are present in the database.


=== Audio File Generation ===
;<code>save_sip_history</code>
;<code>saveaudio = wav</code>
:(Default: no) Store SIP signaling for GUI filtering.
:(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>requests</code> - All SIP methods (PUBLISH, INFO, UPDATE, PRACK, REFER) in "SIP requests" filter
;<code>saveaudio_afterconnect = no</code>
* <code>responses</code> - Full response text for searching (not just codes)
:(Default: no) Store audio only for connected calls.
* <code>all</code> - Both requests and responses
;<code>saveaudio_from_first_invite = yes</code>
:(Default: yes) Generate silence from first INVITE to match SIP signalization length.
;<code>saveaudio_stereo = yes</code>
:(Default: yes) Caller in left channel, called in right channel.
;<code>mp3_quality = 5</code>
:(Default: 5) MP3 quality (0-9, 9 is worst).
;<code>ogg_quality = 0.4</code>
:(Default: 0.4) OGG quality setting.
;<code>audioqueue_threads_max = 10</code>
:(Default: 10) Maximum audio processing threads.
;<code>curl_hook_wav = http://127.0.0.1:8080/your-script-path</code>
:Webhook URL called for each audio file.


== Call Processing & Protocol Logic ==
{{Warning|1=Enabling SIP history significantly increases database load and storage.}}


=== Call Identification & Merging ===
;<code>remoteparty_caller = calling</code>, `passertedidentity = no`, etc.
:A group of options that control which SIP headers are used to determine the caller/callee information. See [[#Caller/Called Identity Configuration|Caller/Called Identity Configuration]].
;<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.
;<code>callidmerge_secret = yourSecretString</code>
:XOR secret for encrypted Call-ID merging header.
;<code>call_id_alternative = Session-ID,Join</code>
:Alternative unique identifiers for call merging (e.g., Cisco CUCM).
;<code>cdrproxy = yes</code>
:(Default: yes) Track all proxy IPs in `cdr_proxy` table.


=== 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. Sets `cdr.bye = 102`.
;<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>bye_timeout = 1200</code>
:(Default: 1200) Timeout in seconds after BYE message.
;<code>bye_confirmed_timeout = 600</code>
:(Default: 600) Timeout after confirmed BYE.
;<code>onewaytimeout = 15</code>
:(Default: 15) Ends call if no reply from other side. Sets `cdr.bye = 101`.
;<code>ignore_rtp_after_response = 408;480;486;487;481;600;503</code>
:(Default: as shown) A list of SIP final response codes after which the sniffer should stop looking for RTP for that call.
;<code>ignore_rtp_after_bye = no</code>
:(Default: no) Stop RTP processing after BYE.
;<code>ignore_rtp_after_bye_confirmed = yes</code>
:(Default: yes) Stop RTP processing after confirmed BYE.
;<code>ignore_rtp_after_cancel_confirmed = yes</code>
:(Default: yes) Stop RTP processing after confirmed CANCEL.
;<code>redirect_response_300_timeout = 300</code>
:(Default: 300) Timeout for SIP 300 redirect.
;<code>get_reason_from_bye_cancel = yes</code>
:(Default: yes) Fetch Q.850 Reason header from BYE/CANCEL.
;<code>ignore_duration_after_bye_confirmed = yes</code>
:(Default: yes) Set duration based on confirmed BYE.
;<code>detect_alone_bye = no</code>
:(Default: no) Flag CDR if BYE is alone in dialog. Warning: Can cause high DB load.


=== RTP Processing ===
=== GUI Filters for SIP Response Searching ===
;<code>jitterbuffer_f1 = yes</code>
:(Default: yes) Fixed 50ms jitterbuffer simulation, saved in cdr.[ab]_f1.
;<code>jitterbuffer_f1_jbsize = 50</code>
:(Default: 50) Jitter buffer size in ms.
;<code>jitterbuffer_f2 = yes</code>
:(Default: yes) Fixed 200ms jitterbuffer simulation, saved in cdr.[ab]_f2.
;<code>jitterbuffer_adapt = yes</code>
:(Default: yes) Adaptive jitterbuffer up to 500ms.
;''Note: These are CPU-intensive; disable some on resource-constrained systems. Set to 'no' for MOS=4.5 or 'null' for NULL value.''


;<code>mosmin_f2 = yes</code>
There are two distinct SIP response filters in the CDR view. Understanding their differences prevents confusion:
:(Default: yes) Calculate mos_min_mult10 only from f2 jitter simulator.


=== RTP Tracking & SDP ===
{| class="wikitable"
;<code>sdp_multiplication = 3</code>
! Filter !! What it searches !! Accepts !! Requires Configuration
:(Default: 3) How many calls can share same IP:port. 0 = only newest call.
|-
;<code>disable_process_sdp = no</code>
| '''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
:(Default: no) Disable SDP processing. Only for very high CPS (>1000).
|-
;<code>rtp_check_both_sides_by_sdp = no</code>
| '''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>
:(Default: no) Eliminate RTP duplication by checking source IP:port. Options:
|}
:* <code>no</code>: Disabled (default)
:* <code>yes</code>: Verify both sides per SDP
:* <code>keep_rtp_packets</code>: Same as 'yes' but store unverified packets for debugging
:* <code>strict</code>: Allow unverified packets until first verified packet arrives
:* <code>very_strict</code>: No unverified packets allowed at any time
;<code>ignore_rtp_after_auth_failed = yes</code>
:(Default: yes) Close RTP ports on authentication failure.
;<code>disable_rtp_seq_probation = no</code>
:(Default: no) Disable RFC 3550 sequence validation.
;<code>allow-zerossrc = no</code>
:(Default: no) Allow RTP packets with zero SSRC.
;<code>check_diff_ssrc_on_same_ip_port = yes</code>
:(Default: yes) Check for different SSRC on same IP:port.
;<code>save_sdp_ipport = yes</code>
:(Default: yes) Store SDP IP/port in `cdr_sdp` table.
;<code>rtpfromsdp_onlysip = no</code>
:(Default: no) Only use RTP streams with same IP as SIP header.
;<code>rtpip_find_endpoints = yes</code>
:(Default: yes) Determine actual RTP endpoints (not proxies).


=== SRTP (Encrypted Media) ===
'''Key differences:'''
See [[#SRTP Configuration|SRTP Configuration]] section above.


=== NAT Handling ===
* '''Last SIP Response Code''' searches only the '''final''' response. Examples:
;<code>natalias = 1.1.1.1 10.0.0.3</code>
** <code>200</code> - exact numeric match
: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.
** <code>4%</code> - all 4xx errors
;<code>sdp_reverse_ipport = no</code>
** <code>%OK</code> - responses ending with "OK"
:(Default: no) Enable reverse IP:port sniffing for NAT scenarios. Use with caution.
** <code>%Busy%</code> - responses containing "Busy"
;<code>sdp_ignore_ip = 192.168.0.1</code>
:Ignore RTP streams from specific IPs.
;<code>sdp_ignore_ip_port = 192.168.0.1:100</code>
:Ignore RTP streams from specific IP:port.


=== SIP REGISTER, OPTIONS, SUBSCRIBE, NOTIFY ===
* '''SIP responses''' searches '''all''' SIP responses (180 Ringing, 183, provisional, etc.). Use for:
;<code>save_sip_history = all</code>
** Intermediate responses (e.g., 491 Request Pending mid-dialog)
:(Default: none) Enables detailed SIP history logging for all SIP requests and responses, including subdialog methods like `REFER`, `BYE`, `CANCEL`, etc. Stored in the `cdr_siphistory` database table and shown in the SIP History tab of the CDR view. Options: all, none. When enabled, you can filter CDRs by specific SIP request methods (INVITE, REFER, OPTIONS, etc.) via the GUI filter's "SIP requests" dropdown. Requires restart of voipmonitor sniffer to take effect.
** Custom SBC error messages
;<code>sip-register = no</code>
** Any response text, not just the final one
:(Default: no) Enables the processing and storage of SIP `REGISTER` messages. Options: yes, nodb, no.
;<code>save-sip-register = no</code>
:(Default: no) Save REGISTER messages to disk.
;<code>sip-register-timeout = 5</code>
:(Default: 5) Timeout in seconds for REGISTER reply.
;<code>sip-register-active-nologbin = yes</code>
:(Default: yes) Skip binary logging for REGISTER active table.
;<code>sip-register-max-registers = 4</code>
:(Default: 4) Max request packets before terminating register session.
;<code>sip-register-max-messages = 20</code>
:(Default: 20) Max total packets before terminating register session.
;<code>sip-register-state-timeout = 600</code>
:(Default: 600) Interval between saving same states.
;<code>sip-options = no</code>
:(Default: no) Enables the processing of SIP `OPTIONS` messages.
;<code>save-sip-options = no</code>
:(Default: no) Save OPTIONS to disk.
;<code>sip-subscribe = no</code>
:(Default: no) Enable SUBSCRIBE processing.
;<code>sip-notify = no</code>
:(Default: no) Enable NOTIFY processing.
;<code>sip-message = yes</code>
:(Default: yes) Enables processing for SIP `MESSAGE` requests.


=== CDR Processing ===
'''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.
;<code>nocdr = no</code>
:(Default: no) Disable saving CDRs to MySQL.
;<code>cdronlyanswered = no</code>
:(Default: no) Only save answered calls.
;<code>cdronlyrtp = no</code>
:(Default: no) Only save calls with RTP.
;<code>cdr_check_exists_callid = no</code>
:(Default: no) Check for existing CDR with same Call-ID.
;<code>cdr_ignore_response = 302,303,4</code>
:Ignore CDRs based on SIP response codes.
;<code>cdr_sip_response_number_max_length = 3</code>
:Limit phone number length in SIP response text.
;<code>cdr_sip_response_normalisation = yes</code>
:(Default: yes) Normalize SIP response text.
;<code>cdr_reason_string_enable = yes</code>
:(Default: yes) Store reasons in cdr_reason table.
;<code>cdr_reason_normalisation = yes</code>
:(Default: yes) Normalize reason text.
;<code>cdr_ua_enable = yes</code>
:(Default: yes) Store user agent in cdr.a_ua and cdr.b_ua.
;<code>cdr_ua_normalisation = yes</code>
:(Default: yes) Normalize user agent strings.
;<code>cdr_stat = both</code>
:Enable aggregated CDR statistics. Options: both, src, dst.
;<code>cdr_stat_interval = 15</code>
:(Default: 15) Statistics interval in minutes.
;<code>vlan_siprtpsame = no</code>
:(Default: no) Filter RTP by VLAN tag from SIP packet.
;<code>dscp = yes</code>
:(Default: yes) Store DSCP values in cdr.dscp.


=== Custom Headers ===
=== save_sip_history vs save_sip_responses ===
;<code>custom_headers = X-Custom-Header</code>
:(Default: empty) List of custom SIP headers to store in cdr_next database. Separate multiple headers with commas (e.g., <code>custom_headers = X-Cisco-Org-ID, X-Custom-ID</code>). After changing this option and restarting voipmonitor, the headers appear in [[Settings|GUI Settings > CDR Custom Headers]] where you can configure them for display in CDR columns.


;<code>custom_headers_last_value = yes</code>
These two parameters achieve the '''same result''' - storing SIP response text for the "SIP responses" filter. '''Do not enable both simultaneously''':
:(Default: yes) Use last occurrence of custom header.
;<code>custom_headers_max_size = 1024</code>
:(Default: 1024) Maximum custom header size.
;<code>allow_missing_header = no</code>
:(Default: no) Write empty value if header missing in first packet.


=== Call Recording Control ===
{| class="wikitable"
;<code>pauserecordingdtmf = *9</code>
! Parameter !! Notes
:(Default: unset) If set, RTP recording will be paused when this DTMF sequence is detected in a call.
|-
;<code>pauserecordingdtmf_timeout = 4</code>
| <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>.
:(Default: 4) Timeout between DTMF digits in seconds.
|-
;<code>pauserecordingheader = MyCustomPauseHeader</code>
| <code>save_sip_responses = yes</code> || Standalone parameter for same functionality. Simpler if you only need response text.
:(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>
== RTP Processing ==
:(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.
;<code>norecord-dtmf = yes</code>
:(Default: no) Delete recording if DTMF sequence "*0" is detected.
;<code>182queuedpauserecording = no</code>
:(Default: no) Pause on "182 Queued avaya-cm-data".


=== Audio Analysis ===
{| class="wikitable"
;<code>dtmf2db = no</code>
! Parameter !! Default !! Description
:(Default: no) Store DTMF to database (SIP INFO and RTP RFC).
|-
;<code>inbanddtmf = no</code>
| <code>jitterbuffer_f1</code> || yes || 50ms fixed jitterbuffer simulation
:(Default: no) Enable in-band DTMF detection. G711 only. CPU intensive.
|-
;<code>silencedetect = no</code>
| <code>jitterbuffer_f2</code> || yes || 200ms fixed jitterbuffer simulation
:(Default: no) Enable silence detection. G711 only. CPU intensive.
|-
;<code>silencethreshold = 512</code>
| <code>jitterbuffer_adapt</code> || yes || Adaptive jitterbuffer (up to 500ms)
:(Default: 512) Silence detection threshold.
|-
;<code>clippingdetect = no</code>
| <code>allow-zerossrc</code> || no || Accept RTP with zero SSRC (some legacy gateways)
:(Default: no) Enable clipping detection. G711 only.
|}
;<code>fasdetect = no</code>
:(Default: no) FAS (False Answer Supervision) detection based on ring detection after 200 OK.
;<code>save-energylevels = no</code>
:(Default: no) Store average 16-bit energy levels for each RTP packet in `cdr_rtp_energylevels` table.
;<code>energylevelheader = X-energlvl</code>
:Only save energy levels for calls with this header.
;<code>sipalg_detect = no</code>
:(Default: no) Detect SIP-ALG usage on routers/firewalls.


=== MOS Scoring ===
'''CPU optimization (saves ~30%):'''
;<code>mos_g729 = no</code>
<syntaxhighlight lang="ini">
:(Default: no) Enable G.729 specific MOS scoring. Max MOS 3.92 for perfect G.729 calls.
mosf1 = no
;<code>ignorertcpjitter = 0</code>
mos_adapt = no
:(Default: 0) Ignore RTCP jitter values higher than this.
mosf2 = yes  # Keep only f2 for stable MOS metric
;<code>ignore_mos_degradation_for_contiguous_packet_loss_greater_than = 1024</code>
</syntaxhighlight>
:(Default: 1024) Don't count consecutive packet loss above this threshold.
;<code>ignore_mos_degradation_in_rtp_pause_without_seq_gap = 1000</code>
:(Default: 1000) Don't lower MOS for RTP gaps without sequence gaps.
;<code>plcdisable = no</code>
:(Default: no) Disable Packet Loss Concealment.
 
=== PESQ MOS ===
;<code>mos_lqo = no</code>
:(Default: no) Enable ITU-T P.862 PESQ scoring. Requires licensed pesq binary.
;<code>mos_lqo_bin = pesq</code>
:Path to PESQ binary.
;<code>mos_lqo_ref = /path/to/reference.wav</code>
:Reference audio file for PESQ.


=== Other Protocols ===
== Audio Analysis ==
;<code>skinny = yes</code>
:(Default: no) Enables parsing for Cisco Skinny Call Control Protocol (SCCP).
;<code>skinny_port = 2000</code>
:(Default: 2000) Skinny port(s).
;<code>skinny_ignore_rtpip = 10.1.1.1</code>
:Ignore RTP from Cisco Call Manager IP.
;<code>mgcp = yes</code>
:(Default: no) Enables parsing for MGCP.
;<code>tcp_port_mgcp_gateway = 2427</code>
;<code>udp_port_mgcp_gateway = 2427</code>
;<code>tcp_port_mgcp_callagent = 2727</code>
;<code>udp_port_mgcp_callagent = 2727</code>
;<code>ss7 = yes</code>
:(Default: no) Enables parsing for SS7-over-IP (SIGTRAN).
;<code>ss7_rudp_port = 7000</code>
:SS7 RUDP port.
;<code>ss7_use_sam_subsequent_number = yes</code>
:Use SAM subsequent number.
;<code>diameter = no</code>
:(Default: no) Enables parsing for the Diameter protocol.
;<code>diameter_tcp_ports = 3868</code>
;<code>diameter_udp_ports = 3868</code>
;<code>diameter_time_overlap = 10</code>
:(Default: 10) Allow Diameter packets up to 10 seconds before SIP sessions.
;<code>diameter_ignore_domain = no</code>
:(Default: no) Skip domain match between SIP and Diameter.
;<code>diameter_ignore_prefix = no</code>
:(Default: no) Allow 'sip:' to match 'tel:' prefix.
;<code>ipv6 = yes</code>
:(Default: no) Enable IPv6 support. Database must be created with IPv6 columns.


== IPFIX Support ==
{| 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
|}


IPFIX (IP Flow Information Export) allows receiving RTP QoS data from Oracle/ACME SBCs and other exporters.
See [[Silence_detection]] for detailed documentation.


;<code>ipfix = yes</code>
== NAT Handling ==
:(Default: no) Enable IPFIX collector.


;<code>ipfix_bind_ip = 0.0.0.0</code>
<syntaxhighlight lang="ini">
:(Default: 0.0.0.0) Address to bind IPFIX UDP collector.
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>


;<code>ipfix_bind_port = 12345</code>
= Protocol Support =
:UDP port to listen for IPFIX.


;<code>ipfix_qos_fill_rtp_streams = yes</code>
== SIP REGISTER/OPTIONS/SUBSCRIBE ==
:(Default: no) Save all observed RTP streams into `cdr_rtp`.


;<code>ipfix_qos_fill_codec = yes</code>
{| class="wikitable"
:(Default: no) Persist exporter-provided codec value.
! 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
|}


;<code>ipfix_qos_fill_jitter = yes</code>
See [[Register]] for detailed REGISTER documentation.
:(Default: no) Persist RTP/RTCP jitter values.


'''Data written to CDR:'''
== Other Protocols ==
* a_saddr / b_saddr: RTP source IPs
* a_received / b_received: Total RTP packets
* a_lost / b_lost: Lost RTP packets
* a_mos_f2_mult10 / b_mos_f2_mult10: MOS values (multiplied by 10)


== SIPREC Support ==
{| 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)
|}


SIPREC enables VoIPmonitor to act as a recording server for SIP proxies like OpenSIPS.
= Advanced Protocol Support =


;<code>siprec_bind = 0.0.0.0</code>
== IPFIX Support ==
:IP address to bind SIPREC server. Required to enable SIPREC.


;<code>siprec_bind_port = 5099</code>
IPFIX (IP Flow Information Export) is used with Oracle/ACME SBCs to receive call data.
:Port to listen for SIPREC connections. Required to enable SIPREC.


;<code>siprec_rtp_min = 10000</code>
'''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.
:(Default: 10000) Lower bound of RTP port range.


;<code>siprec_rtp_max = 20000</code>
<syntaxhighlight lang="ini">
:(Default: 20000) Upper bound of RTP port range.
ipfix = yes
ipfix_bind_port = 12345
ipfix_qos_fill_rtp_streams = yes
# Include TLS port for SIPS/SRTP:
sipport = 5060,5061
</syntaxhighlight>


;<code>siprec_rtp_stream_timeout_s = 300</code>
{| class="wikitable"
:(Default: 300) RTP stream timeout in seconds.
! Parameter !! Default !! Description
|-
| <code>ipfix</code> || no || Enable IPFIX receiver (Oracle/ACME SBC)
|-
| <code>ipfix_bind_ip</code> || 0.0.0.0 || Bind IP address for IPFIX listener
|-
| <code>ipfix_bind_port</code> || 4739 || UDP port for IPFIX data
|-
| <code>ipfix_qos_fill_rtp_streams</code> || no || Populate RTP stream statistics from IPFIX QoS data
|}


;<code>siprec_rtp_streams_max_threads = 2</code>
== SIPREC Support ==
:(Default: 2) Maximum RTP reception threads.


;<code>siprec_rtp_streams_max_per_thread = 100</code>
<syntaxhighlight lang="ini">
:(Default: 100) Maximum streams per thread.
siprec_bind = 0.0.0.0
siprec_bind_port = 5099
siprec_rtp_min = 10000
siprec_rtp_max = 20000
</syntaxhighlight>


== Whisper Transcription ==
== HEP Support ==


VoIPmonitor supports audio transcription using OpenAI's Whisper model.
<syntaxhighlight lang="ini">
 
receiver_mode = yes  # Required!
;<code>audio_transcribe = yes</code>
hep = yes
:(Default: no) Enable audio transcription.
hep_bind_port = 9060
 
hep_kamailio_protocol_id_fix = yes  # For Kamailio sources
;<code>whisper_rest_api_url = http://localhost:9000/asr?output=json&encode=true</code>
</syntaxhighlight>
:URL for Whisper REST API. If set, overrides native and python methods.
 
;<code>whisper_rest_api_mode = stereo</code>
:(Default: stereo) REST API mode: 'stereo' (one stereo WAV) or 'split' (two mono WAVs).
 
;<code>whisper_native = no</code>
:(Default: no) Use native whisper.cpp library.
 
;<code>whisper_model = /path/to/ggml-base.en.bin</code>
:Path to Whisper model file.
 
;<code>whisper_language = auto</code>
:(Default: auto) Language for transcription. 'auto' for automatic detection.
 
;<code>whisper_timeout = 60</code>
:(Default: 0) Timeout for python script execution.
 
;<code>whisper_deterministic_mode = no</code>
:(Default: no) Enable deterministic mode.
 
;<code>whisper_python = /usr/bin/python3</code>
:(Default: python3) Path to Python interpreter.
 
;<code>whisper_threads = 4</code>
:(Default: 0, auto) Number of Whisper processing threads.
 
;<code>whisper_native_lib = /usr/local/lib/libwhisper.so</code>
:Path to native Whisper library.
 
;<code>audio_transcribe_threads = 2</code>
:(Default: 2) Number of transcription processing threads.
 
;<code>audio_transcribe_queue_length_max = 1000</code>
:(Default: 1000) Maximum transcription queue length.
 
;<code>audio_transcribe_parallel_channel_processing = yes</code>
:(Default: yes) Process audio channels in parallel.


== Kamailio Mirroring ==
== Kamailio Mirroring ==


Configuration for receiving SIP traffic mirrored from Kamailio's siptrace module.
'''Kamailio configuration:'''
<syntaxhighlight lang="ini">
<syntaxhighlight lang="ini">
loadmodule "siptrace.so"
receiver_mode = yes  # Required!
modparam("siptrace", "trace_on", 1)
kamailio_port = 5888
modparam("siptrace", "duplicate_uri", "sip:10.0.0.1:5888")
modparam("siptrace", "trace_to_database", 0)
modparam("siptrace", "trace_mode", 4)
modparam("siptrace", "xheaders_write", 1)
</syntaxhighlight>
</syntaxhighlight>
;<code>kamailio_port = 5888</code>
:Port to receive Kamailio mirrored traffic.
;<code>kamailio_dstip = 10.0.0.1</code>
:VoIPmonitor host IP address.
;<code>kamailio_srcip = 10.0.0.2</code>
:Kamailio server IP address (optional).
;<code>kamailio = no</code>
:(Default: no) Enable Kamailio-style substitution on sniffed traffic.
;<code>hep_kamailio_protocol_id_fix = yes</code>
:(Default: yes) Workaround for Kamailio protocol ID issues.


== Ribbon SBC Mirroring ==
== Ribbon SBC Mirroring ==


Support for Ribbon SBC monitoring profiles.
<syntaxhighlight lang="ini">
ribbonsbc = yes
ribbonsbc_bind_ip = 0.0.0.0
ribbonsbc_bind_port = 9514
</syntaxhighlight>


=== Passive Sniffing (Mode 1) ===
== Whisper Transcription ==
;<code>ribbonsbc = yes</code>
:(Default: no) Enable Ribbon-style IP:port substitution on sniffed traffic.


;<code>ribbonsbc_port = 9514</code>
<syntaxhighlight lang="ini">
:Expected mirror port in packets (legacy filter).
audio_transcribe = yes
whisper_native = no
whisper_model = /path/to/ggml-base.bin
whisper_language = auto
</syntaxhighlight>


;<code>ribbonsbc_dstip = 10.0.0.1</code>
See [[Whisper]] for detailed transcription documentation.
:VoIPmonitor host IP (legacy filter).
{{Note|1='''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 <code>ribbonsbc</code> protocol
Do not confuse these - they require different VoIPmonitor configuration.}}
= Expert & Debugging Options =


;<code>ribbonsbc_srcip = 10.0.0.2</code>
{{Warning|1=Only change these if instructed by support or you are an expert.}}
:Ribbon SBC IP (legacy filter).


=== Active Listener (Mode 2) ===
{| class="wikitable"
;<code>ribbonsbc_bind_ip = 0.0.0.0</code>
! Parameter !! Default !! Description
:Listen address for active mode.
|-
| <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
|}


;<code>ribbonsbc_bind_port = 9514</code>
== Traffic Dumper ==
:Listen port for active mode.


;<code>ribbonsbc_bind_udp = no</code>
<syntaxhighlight lang="ini">
:(Default: no) Enable UDP support. TCP recommended.
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
</syntaxhighlight>


;<code>ribbonsbc_size_header = yes</code>
== DEPRECATED DO NOT USE ==
:(Default: yes) Expect 2-byte size header before each frame.
 
;<code>ribbonsbc_strict_check = no</code>
:(Default: no) Only process frames complete per size header.
 
;<code>ribbonsbc_counter_log = no</code>
:(Default: no) Log counts of incoming Ribbon frames.
 
== Traffic Dumper ==


Save captured traffic to PCAP files with optional filtering.
<!-- This is a placeholder for correct deprecated options section -->


;<code>traffic_dumper_path = /var/spool/voipmonitor/traffic</code>
:Path where pcap files will be saved. Setting this enables the traffic dumper.


;<code>traffic_dumper_by_interface = no</code>
:(Default: no) Create separate files per interface (yes) or per DLT type (no).


;<code>traffic_dumper_force_flush = no</code>
:(Default: no) Force flush after each packet. Impacts performance.


;<code>traffic_dumper_filter_ip = 192.168.1.100, 10.0.0.0/8</code>
:Filter by IP addresses or networks.


;<code>traffic_dumper_filter_port = 5060, 5061, 10000-20000</code>
:Filter by ports or port ranges.


== Expert & Debugging Options ==
'''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>
:A family of options that puts the sniffer into a special database backup/migration mode, copying data from another database.
;<code>coredump_filter = 0x7F</code>
:(Default: 0x7F) 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.
;<code>interrupts_counters = yes</code>
:(Default: yes) Enable interrupt statistics. Disable on Virtuozzo containers.
;<code>callslimit = 0</code>
:(Default: 0, unlimited) Maximum concurrent calls to process.
;<code>skipdefault = yes</code>
:(Default: no) Ignore all SIP calls unless capture rules are set.
;<code>openfile_max = 65535</code>
:(Default: 65535) Maximum open files.
;<code>convertchar = :</code>
:Replace characters with underscores in filenames.
;<code>fbasenameheader = X-custom-filename</code>
:Name pcap files based on custom SIP header.
;<code>pcapcommand = echo %pcap% >> /tmp/list</code>
:Command to run after pcap is closed. Warning: Resource intensive.
;<code>filtercommand = myscript '%callid%' '%dirname%'</code>
:Command for calls matching capture rules.
;<code>printinsertid = no</code>
:(Default: no) Print CDRID to stdout on every insert.


=== DPDK Configuration ===
= AI Summary for RAG =
;<code>dpdk_timer_reset_interval = 60</code>
:(Default: 60) Reset interval in seconds.
;<code>dpdk_nb_rxq = 2</code>
:(Default: 2) Number of receive queues. Increase for higher traffic.
;<code>dpdk_rxq_per_thread = no</code>
:(Default: no) Process RX queues with separate threads.
;<code>dpdk_ignore_ierrors = no</code>
:(Default: no) Ignore ierrors (packets with bad checksums).


== AI Summary for RAG ==
'''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>.
'''Summary:''' This document is a comprehensive reference guide for the `voipmonitor.conf` sniffer configuration file. It covers General Settings (sensor ID, timezone, watchdog), Database Connection and Performance (MySQL settings, partitioning, queue tuning, cleaning, SSL/TLS), Network Interface and Sniffing (interface selection, BPF filters, tunneling protocols including TZSP, L2TP, VXLAN, AudioCodes, IPFIX, HEP, and '''packet deduplication''' with options like `deduplicate`, `auto_enable_use_blocks`, and `deduplicate_ipheader`), SIP TLS/SSL Decryption (ssl, ssl_ipport, keylogger support), SRTP Configuration (srtp_rtp, ssl_dtls_boost), Caller/Called Identity (remoteparty, passertedidentity, destination_number_mode), Performance and Threading (NUMA, scheduling, buffer configuration), Distributed Architectures (client/server model and legacy mirroring), Storage Management (spooldir, TAR files, pcap saving, compression, and cleaning rules), Call Processing (timeouts, RTP tracking, NAT handling, custom headers, recording control), Audio Analysis (DTMF, silence detection, energy levels, MOS scoring), Protocol Support (SIP, Skinny, MGCP, SS7, Diameter), IPFIX Support, SIPREC Support, Whisper Transcription, Kamailio Mirroring, Ribbon SBC Mirroring, and Traffic Dumper.


'''Keywords:''' voipmonitor.conf, configuration, sniffer config, sensor, database, mysql, mariadb, cdr_partition, cleandatabase, interface, sniffing, promisc, bpf, filter, tunneling, DPDK, performance, threading, client/server, distributed, remote sensor, spooldir, storage, pcap, tar, maxpoolsize, saveaudio, SIP, RTP, SRTP, DTLS, ssl_dtls_boost, skinny, MGCP, SS7, diameter, NAT, natalias, call recording, watchdog, sched_pol_auto, deduplicate, auto_enable_use_blocks, deduplicate_ipheader, ip_only, packet deduplication, duplicate packets, ssl, ssl_ipport, TLS decryption, IPFIX, HEP, SIPREC, whisper, transcription, Kamailio, Ribbon SBC, traffic dumper, energy levels, DTMF detection, silence detection, MOS scoring, call merging, callidmerge_header, rtp_check_both_sides_by_sdp, cdr_summary, cdr_summary_interval, cleandatabase_cdr_summary, aggregation, dashboard performance, deprecated, removed, obsolete, upgrade, 2025.09.1, vxlan, vxlan_port, vxlan_skipcrc, packet_buffer_total_size, udp_reassembly, sipdefrag, defragment, ignore_sip_parsing_errors, sip_auto_clean, max_sip_size, sip_force_content_length, sanity_checks, check_sip_header, interface_snaplen
'''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:'''
'''Key Questions:'''
* What configuration options were removed in VoIPmonitor version 2025.09.1?
* What are the most important settings in voipmonitor.conf?
* Which VXLAN configuration options are deprecated and what should I use instead?
* How do I configure the database connection?
* What should I replace vxlan, vxlan_port, and vxlan_skipcrc with in my configuration?
* Why does the sniffer fail with "failed read rsa key"?
* What replaces packet_buffer_total_size in newer versions?
* How do I set up distributed client/server architecture?
* Are udp_reassembly, sipdefrag, and defragment options still supported?
* What is the difference between packetbuffer_sender = yes and no?
* What should I do with ignore_sip_parsing_errors, sip_auto_clean, and max_sip_size options?
* How do I enable packet deduplication?
* Are sanity_checks and check_sip_header options supported in version 2025.09.1?
* How do I decrypt TLS/SRTP traffic?
* What replaces interface_snaplen for packet capture length?
* How do I disable audio recording while keeping RTP analysis?
* What are the most important settings in voipmonitor.conf for a new installation?
* How do I capture custom SIP headers?
* How do I configure the database connection for the sniffer?
* How do I configure IPFIX/SIPREC/HEP receivers?
* How do I set up a distributed client/server architecture?
* Which options were deprecated in v2025.09.1?
* What is the difference between `packetbuffer_sender = yes` and `no`?
* How do I fix CPU bottlenecks with t2_boost?
* How do I tune the database for high performance?
* How do I process PCAP files with scanpcapdir?
* How do I configure the sniffer to listen on multiple SIP ports?
* What are the `maxpoolsize` and `cleandatabase` options and how do they work?
* How do I enable SRTP decryption and what is ssl_dtls_boost?
* How do I configure VoIPmonitor to handle tunneled traffic from a Mikrotik router or AWS?
* How do I selectively pause or stop call recording?
* How do I enable packet deduplication for multiple sensors or interfaces?
* What is `auto_enable_use_blocks` and why is it required for deduplication?
* What is the difference between `deduplicate_ipheader = yes`, `ip_only`, and `no`?
* How do I configure deduplication when packets arrive from different network paths with different TTL values?
* How do I decrypt TLS-encrypted SIP traffic?
* How do I configure IPFIX to receive RTP QoS from Oracle SBC?
* How do I configure HEP (Homer Encapsulation Protocol) to receive traffic from SBCs?
* How do I set up SIPREC recording?
* How do I enable Whisper audio transcription?
* How do I configure Kamailio siptrace mirroring?
* How do I set up Ribbon SBC monitoring profile mirroring?
* How do I use the traffic dumper to capture specific traffic?
* How do I enable CDR summary for faster dashboard queries?
* What is cdr_summary_interval and how does it affect aggregation?
* What is rtp_check_both_sides_by_sdp and when should I use it?
* How do I configure energy level detection for audio analysis?
* How do I enable DTMF, silence, or clipping detection?

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"