Sniffer configuration: Difference between revisions

From VoIPmonitor.org
(Add cdr_country_code configuration option for country flag display in CDR view)
(Rewrite: konsolidace a vylepšení struktury)
Line 2: Line 2:
{{DISPLAYTITLE:Sniffer Configuration Reference (voipmonitor.conf)}}
{{DISPLAYTITLE:Sniffer Configuration Reference (voipmonitor.conf)}}


'''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.'''
'''Comprehensive reference for `/etc/voipmonitor.conf` parameters.''' Additional configuration snippets can be placed in `/etc/voipmonitor/conf.d/` (without `[general]` header).
 
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).


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


== General & Core Settings ==
= General & Core Settings =


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


;<code>utc = yes</code>
{| class="wikitable"
:(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.
! Parameter !! Default !! Description
|-
| <code>id_sensor</code> || unset || Unique numeric identifier (1-65535). '''Essential''' for multi-sensor deployments.
|-
| <code>utc</code> || no || Store timestamps in UTC. '''Recommended''' for multi-timezone deployments.
|-
| <code>timezone</code> || system || Override system timezone with zoneinfo path (e.g., <code>/usr/share/zoneinfo/UTC</code>).
|}


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


=== Deprecated and Removed Configuration Options ===
{| class="wikitable"
! Parameter !! Default !! Description
|-
| <code>watchdog</code> || no || Auto-restart sensor on crash.
|-
| <code>watchdog_run_command</code> || unset || Custom restart command (e.g., <code>systemctl restart voipmonitor</code>).
|}


When upgrading the VoIPmonitor sensor to version 2025.09.1 or newer, some legacy configuration options are no longer supported and must be removed from <code>/etc/voipmonitor.conf</code>. Keeping these unsupported options can cause confusion and prevent the sensor from applying correct default behaviors.
== Deprecated Options (v2025.09.1+) ==


{{Warning|1=The options listed below are '''unsupported and ignored''' in sniffer version 2025.09.1 and later. Remove them from your configuration file.}}
{{Warning|1=The following options are '''unsupported and ignored''' in sniffer version 2025.09.1+. Remove them from your configuration.}}


==== VXLAN Options (Removed) ====
{| 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)
|}


The following legacy VXLAN options were removed in favor of the modern <code>udp_port_vxlan</code> directive:
{{Tip|After removing deprecated options, check logs for warnings: <code>journalctl -u voipmonitor -f</code>}}


;<code>vxlan</code>
= Database Configuration =
:Deprecated. Use <code>udp_port_vxlan = 4789</code> instead.


;<code>vxlan_port</code>
== Connection Settings ==
:Deprecated. Use <code>udp_port_vxlan = 4789</code> instead.


;<code>vxlan_skipcrc</code>
{| class="wikitable"
:Deprecated. This option is no longer supported.
! 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
|}


==== Packet Buffer and UDP Reassembly Options (Removed) ====
=== SSL/TLS for Database ===
<syntaxhighlight lang="ini">
mysqlsslkey = /etc/ssl/client-key.pem
mysqlsslcert = /etc/ssl/client-cert.pem
mysqlsslcacert = /etc/ssl/ca-cert.pem
</syntaxhighlight>


;<code>packet_buffer_total_size</code>
== Performance & Schema ==
:Deprecated. The packet buffer memory is now managed automatically via <code>max_buffer_mem</code>.


;<code>udp_reassembly</code>
{| class="wikitable"
:Deprecated. UDP reassembly is now controlled by <code>udpfrag = yes</code>.
! Parameter !! Default !! Description
 
|-
;<code>udp_reassembly_max_size</code>
| <code>query_cache</code> || yes || '''Critical:''' Queue SQL to disk (qoq* files) to prevent data loss during DB outages.
:Deprecated. The system automatically handles fragment sizes.
|-
 
| <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.
==== SIP Defragmentation and Processing Options (Removed) ====
|-
 
| <code>cdr_partition</code> || yes || '''Essential:''' Daily table partitioning for performance.
;<code>sipdefrag</code>
|-
:Deprecated. SIP defragmentation is now automatic.
| <code>cdr_partition_by_hours</code> || no || Hourly partitions for extreme traffic (≥15k CPS).
 
|-
;<code>sipdefrag_maxpacket</code>
| <code>disable_partition_operations</code> || no || Disable auto partition management (for centralized DB).
:Deprecated. Defragmentation packet limits are handled internally.
|-
 
| <code>mysql_enable_set_id</code> || no || Central server generates CDR IDs (high-traffic client/server).
;<code>defragment_max_size</code>
|}
:Deprecated. Use <code>max_sip_packets_in_call</code> and <code>max_invite_packets_in_call</code> instead.


;<code>defragment_timeout</code>
== Configuration Priority: File vs GUI ==
:Deprecated. Packet processing timeouts are handled internally.


;<code>ignore_sip_parsing_errors</code>
:Deprecated. The sensor has improved error handling and this option is no longer needed.
;<code>sip_auto_clean</code>
:Deprecated. Automatic cleanup is now built-in.
;<code>max_sip_size</code>
:Deprecated. Use <code>snaplen</code> instead to control packet capture length.
;<code>sip_force_content_length</code>
:Deprecated. Content length handling is now automatic.
==== Validation and Interface Options (Removed) ====
;<code>sanity_checks</code>
:Deprecated. Enhanced validation is now built-in and cannot be disabled.
;<code>check_sip_header</code>
:Deprecated. SIP header validation is automatic.
;<code>interface_snaplen</code>
:Deprecated. Use <code>snaplen</code> instead (applies to all interfaces).
==== Modern Replacements ====
These options replace the deprecated ones above and should be used instead:
;<code>udp_port_vxlan = 4789</code>
:(Default: 4789) Port for VXLAN traffic in AWS and cloud environments. Use this instead of the legacy VXLAN options.
;<code>snaplen = 3200</code>
:(Default: 3200, 6000 if SSL/HTTP enabled) Packet capture length override. Replaces <code>max_sip_size</code> and <code>interface_snaplen</code>.
;<code>udpfrag = yes</code>
:(Default: yes) Enable IP fragment reassembly for UDP packets. Replaces <code>udp_reassembly</code>.
;<code>auto_enable_use_blocks = yes</code>
:(Default: no) Enables automatic memory block allocation for deduplication when sniffing from multiple sources or interfaces.
;<code>deduplicate = yes</code>
:(Default: no) Enables packet deduplication to identify and discard duplicate packets.
{{Tip|After removing deprecated options, restart the sensor and check the logs for any "unknown option" warnings: <code>journalctl -u voipmonitor -f</code>}}
=== Process Management ===
;<code>watchdog = yes</code>
:(Default: no) If enabled, a watchdog process is created that automatically restarts the voipmonitor sensor if it crashes or is terminated unexpectedly.
;<code>watchdog_run_command = systemctl restart voipmonitor</code>
:(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 ==
=== Connection Settings ===
;<code>mysqlhost = localhost</code>
:IP address or hostname of the MySQL/MariaDB server.
;<code>mysqlsocket = /var/run/mysqld/mysqld.sock</code>
:Path to the MySQL socket file for local connections (often faster than TCP).
;<code>mysqlport = 3306</code>
:TCP port of the database server.
;<code>mysqlusername = root</code>
:Username for the database connection.
;<code>mysqlpassword =</code>
:Password for the database connection.
;<code>mysqldb = voipmonitor</code>
:The name of the database to use. It will be created automatically if it doesn't exist.
;<code>mysql_connect_timeout = 60</code>
:(Default: 60) Timeout in seconds for establishing a connection to the database.
;<code>mysql_client_compress = no</code>
:(Default: no) Enables compression for the MySQL connection. Only use this if the database is on a remote, slow network link.
;<code>mysql_reconnect = yes</code>
:(Default: no) Enables automatic reconnection to the database if the connection is lost.
=== Database SSL/TLS ===
;<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 ===
;<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 (qoq* files in the spool directory) 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. When database connection is restored, the sensor writes the buffered CDRs from the queue files to the database. This process introduces a small delay but ensures no data loss during database downtime. If set to <code>no</code>, CDRs are held in sensor memory only during database outages, which can lead to OOM (Out Of Memory) situations and data loss if the database is offline for an extended period.
;<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>
;<code>mysqlloadconfig = yes</code>
:(Default: yes) When enabled, VoIPmonitor loads additional configuration parameters dynamically from the `sensor_config` database table (configured via the GUI). The GUI settings take '''priority''' over settings in `/etc/voipmonitor.conf`.
:(Default: yes) Load settings from database (<code>sensor_config</code> table). '''GUI settings take priority over file settings.'''
 
'''Important Behavior:''' If you modify the same parameter in both locations, the value from the database (GUI) is used and the file value is ignored. This is the default and recommended behavior for deployments using the web interface for configuration management. This setting also controls loading of the <code>manager_key</code> from the <code>system</code> table. If set to <code>no</code>, VoIPmonitor will NOT load the manager_key from the database, which will cause the sensor to fail to start with the error "failed read rsa key." For distributed manager/sensor deployments, ensure this option is enabled (or omitted for the default <code>yes</code> behavior) on both the manager and sensor to permit proper key exchange.
 
=== Troubleshooting Configuration File vs Database Conflicts ===
 
When <code>mysqlloadconfig = yes</code> (default), the sensor prioritizes configuration from the database over the configuration file. This can cause confusion if you edit settings in the file but do not also update them in the GUI, as your file changes will be silently ignored.
 
'''Symptoms of a Configuration Conflict:'''
* A parameter you changed in the configuration file has no effect
* Different values are shown in the GUI versus what you configured
* Settings revert after restarting the service
 
'''Diagnosing Conflicts via Syslog:'''


The sensor logs conflicting parameters to the system log at startup. To identify which settings are conflicting:
{{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.}}


# Restart the sensor service to trigger configuration logging:
'''Diagnosing conflicts:'''
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
systemctl restart voipmonitor
systemctl restart voipmonitor
grep 'Configuration valu' /var/log/syslog | grep ' / '
</syntaxhighlight>
</syntaxhighlight>


# Check the system log for messages containing "Configuration values":
'''Resolution options:'''
<syntaxhighlight lang="bash">
* '''Option 1:''' Update settings via GUI (recommended)
grep 'Configuration valu' /var/log/syslog
* '''Option 2:''' Set <code>mysqlloadconfig = no</code> for file-only management
</syntaxhighlight>
* '''Option 3:''' Delete specific entries from <code>sensor_config</code> table
 
== SQL Queue Tuning ==


# Filter to show only the parameter names and values:
{| class="wikitable"
<syntaxhighlight lang="bash">
! Parameter !! Default !! Description
cat /var/log/syslog | grep 'Configuration valu' -A 100 | grep ' / '
|-
</syntaxhighlight>
| <code>mysqlstore_concat_limit</code> || 400 || SQL statements per batch
|-
| <code>mysqlstore_max_threads_cdr</code> || 2 || Max parallel CDR write threads
|}


The log output shows parameters where the file and database values differ, for example:
== Database Cleaning ==
<syntaxhighlight lang="text">
Configuration values from configuration file and GUI (database) are different:
mysqlloadconfig = yes (active) - cleaning
/sensor_config/cleanspool vs /voipmonitor.conf/cleanspool = no
/sensor_config/maxpoolsize vs /voipmonitor.conf/maxpoolsize = 51200
</syntaxhighlight>


In this example, the <code>cleanspool</code> and <code>maxpoolsize</code> settings are loaded from the database (GUI) rather than the configuration file.
See [[Data_Cleaning]] for detailed documentation.


'''Resolving Conflicts:'''
{| class="wikitable"
! Parameter !! Default !! Description
|-
| <code>cleandatabase</code> || 0 || Master retention period in days (0=disabled)
|-
| <code>cleandatabase_cdr</code> || 0 || CDR/message table retention
|-
| <code>cleandatabase_rtp_stat</code> || 2 || RTP statistics retention
|-
| <code>partition_operations_enable_fromto</code> || 1-5 || Partition drop time window (e.g., 1-5 AM)
|}


Choose one of these approaches based on your environment:
== CDR Summary (Aggregation) ==


;<code>Option 1: Update via GUI (Recommended)</code>
Pre-aggregates call data for faster dashboard queries.
If you want to continue using the GUI for configuration management, ensure all parameter changes are made through the web interface:
# Log in to the VoIPmonitor GUI
# Navigate to <strong>Settings > Sensors</strong>
# Click the wrench icon for the affected sensor
# Update the desired parameter to match your intended configuration
# Save the changes
The sensor will apply the new values immediately or upon the next reload.


;<code>Option 2: Disable MySQL Config Loading for File-Based Management</code>
If you manage configuration exclusively via <code>/etc/voipmonitor.conf</code> or automation tools (Ansible, Puppet, etc.), disable database-driven configuration:
# Edit the configuration file:
<syntaxhighlight lang="bash">
nano /etc/voipmonitor.conf
</syntaxhighlight>
# Add or modify this setting in the <code>[general]</code> section:
<syntaxhighlight lang="ini">
<syntaxhighlight lang="ini">
mysqlloadconfig = no
cdr_summary = yes
cdr_summary_interval = 5  # minutes
</syntaxhighlight>
</syntaxhighlight>
# Restart the service:
<syntaxhighlight lang="bash">
systemctl restart voipmonitor
</syntaxhighlight>
'''Warning:''' With this setting disabled, changes made via the GUI sensor settings page will be ignored.


;<code>Option 3: Remove Conflicting Database Entries</code>
= Network Interface & Sniffing =
If you need to keep <code>mysqlloadconfig = yes</code> but want a specific parameter to use the file value instead of the database value:
# Connect to the voipmonitor database:
<syntaxhighlight lang="bash">
mysql -u root -p voipmonitor
</syntaxhighlight>
# Check the current database value for the specific parameter:
<syntaxhighlight lang="sql">
SELECT * FROM sensor_config WHERE name = 'parameter_name';
</syntaxhighlight>
# Delete the conflicting entry to force the sensor to fall back to the file value:
<syntaxhighlight lang="sql">
DELETE FROM sensor_config WHERE name = 'parameter_name';
</syntaxhighlight>
# Verify deletion:
<syntaxhighlight lang="sql">
SELECT * FROM sensor_config WHERE name = 'parameter_name';
</syntaxhighlight>
# Restart the sensor:
<syntaxhighlight lang="bash">
systemctl restart voipmonitor
</syntaxhighlight>


'''Best Practices:'''
== Interface Selection ==


* Decide on a single configuration source based on your management approach (GUI vs config file/automation)
{| class="wikitable"
* For GUI-based management, always use the web interface to modify settings
! Parameter !! Default !! Description
* For config file/automation management, set <code>mysqlloadconfig = no</code> to prevent conflicts
|-
* Periodically review syslog for conflict warnings to catch discrepancies early
| <code>interface</code> || eth0 || Interface(s) to capture. Comma-separated for multiple. <code>any</code> = all (no promisc).
* After resolving conflicts, verify the active value with the syslog diagnostic command above
|-
;<code>mysqlcompress_type = ...</code>
| <code>promisc</code> || yes || Promiscuous mode (doesn't work with <code>any</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>
| <code>interfaces_optimize</code> || yes || Auto-tune NIC settings via ethtool.
:(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>
| <code>snaplen</code> || 3200 || Packet capture length. Increase for large SIP packets.
:(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.
|}
 
'''Important: This setting only affects table creation.''' When enabled, VoIPmonitor creates new tables with primary keys, but it does not modify existing tables or databases. If you have an existing database that was created without this setting enabled, you cannot simply enable it and expect existing tables to be retroactively fixed.
 
If you are deploying VoIPmonitor on a database cluster (such as Percona XtraDB Cluster in `ENFORCING` or `MASTER` mode) that requires all tables to have primary keys, follow this procedure:


# Ensure <code>cdr_force_primary_index_in_all_tables = yes</code> is set in <code>/etc/voipmonitor.conf</code> on the sensor or aggregator node responsible for database creation.
== BPF Filtering ==
# Back up any important data from the existing <code>voipmonitor</code> database.
# Drop the existing <code>voipmonitor</code> database.
# Restart the VoIPmonitor service. It will automatically create a new database with the correct schema, including primary keys on all required tables.


{{Warning|Dropping and recreating the database will delete all existing CDRs, messages, and other data. Ensure you have a backup before proceeding.}}
;<code>filter</code>
;<code>disable_cdr_fields_rtp = no</code>
:BPF filter (tcpdump syntax). '''Warning:''' Can accidentally exclude important traffic.
:(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 ===
;<code>mysqlstore_concat_limit = 400</code>
:(Default: 400) Sets the global number of SQL statements to batch together before sending to the database.
;<code>mysqlstore_max_threads_cdr = 2</code>
:(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 ===
;<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) ===
 
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.
 
;<code>cdr_summary = yes</code>
:(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>sql_log_all_errors = no</code>
:(Default: no) Logs all SQL errors to syslog.
;<code>sql_errors_log_file = /path/to/log</code>
:(Default: unset) Redirects SQL error logging to a specific file.
;<code>sql_errors_skip = 1054,1136</code>
:(Default: unset) A comma-separated list of SQL error codes to ignore and not log.
 
== Network Interface & Sniffing ==
This section configures how the sensor captures packets.
 
=== Interface Selection ===
;<code>interface = eth0</code>
:Specifies the network interface(s) to listen on. Use a comma-separated list for multiple interfaces (e.g., `eth0,eth1`). Using `any` will listen on all interfaces but will not enable promiscuous mode.
;<code>promisc = yes</code>
:(Default: yes) Puts the specified interface(s) into promiscuous mode to capture all traffic, not just traffic addressed to the server. Does not work with `interface = any`.
;<code>interfaces_optimize = yes</code>
:(Default: yes) Allows voipmonitor to automatically tune NIC settings like ring buffers and coalescing using `ethtool`.
;<code>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. The `filter` option is processed by libpcap using Berkeley Packet Filter (BPF) syntax and supports tcpdump-style expressions including negation ('not'), logical operators ('and', 'or'), parentheses, and complex criteria matching IP addresses, ports, protocols, VLAN tags, and other packet fields. However, it can be CPU-intensive and complex to configure correctly. '''Warning:''' Using filters can accidentally exclude important traffic like VLAN-tagged or tunneled packets. Use with caution.
 
:'''Example: Exclude specific subnets from being captured'''
<syntaxhighlight lang="ini">
<syntaxhighlight lang="ini">
# Exclude internal networks from capturing
# Example: Exclude specific subnets
filter = not net 192.168.0.0/16 and not net 10.0.0.0/8
filter = not net 192.168.0.0/16 and not net 10.0.0.0/8
</syntaxhighlight>
</syntaxhighlight>


:'''Example: Capture only UDP SIP traffic'''
;<code>interface_ip_filter</code>
:CPU-efficient IP allow-list (no negation). Multiple lines supported.
<syntaxhighlight lang="ini">
<syntaxhighlight lang="ini">
filter = udp port 5060
</syntaxhighlight>
:When modifying the `filter` setting, you must restart the sniffer service for changes to take effect: `systemctl restart voipmonitor`.
;<code>interface_ip_filter = 192.168.0.0/24</code>
:(Default: unset) A CPU-efficient method to filter traffic by IP address or subnet. This option matches packets whose source or destination IP falls within the specified networks. Multiple lines can be used to define multiple allowed networks. Unlike the main `filter` option, `interface_ip_filter` is an '''allow-list''' (whitelist) that implicitly discards traffic not matching any of the specified networks. It does not support negation or complex BPF syntax.
:'''Example: Allow only internal traffic'''
<syntaxhighlight lang="ini">
# Only process packets from/to these networks
interface_ip_filter = 192.168.0.0/24
interface_ip_filter = 192.168.0.0/24
interface_ip_filter = 10.0.0.0/8
interface_ip_filter = 10.0.0.0/8
</syntaxhighlight>
</syntaxhighlight>
;<code>snaplen = 3200</code>
:(Default: 3200, 6000 if SSL/HTTP enabled) Packet capture length override. This parameter controls how many bytes of each packet are captured. If a SIP packet exceeds this limit, it is truncated and the sniffer may fail to parse the call correctly, resulting in missing CDRs.


=== Optimizing for Shared Server Deployments ===
== Shared Server Optimization ==


When the VoIPmonitor sniffer runs on the same server as the PBX and RTP engine, resource contention can cause voice breakage and call lag. The sniffer competes for CPU cycles and network interrupts with the real-time media processing.
When the sniffer runs on the same server as the PBX, resource contention can cause voice breakage.


'''Symptoms:'''
'''Symptoms:''' Audio jitter, packet loss, call lag that resolves when sniffer is stopped.
* Audio breakage (jitter, packet loss)
* Call lag or delay
* Issues resolve when the sniffer is stopped


'''Solution 1: Specify Specific Interfaces'''
'''Solutions:'''
Instead of using `interface = any`, specify a comma-separated list of the exact network interfaces that handle VoIP traffic:
<syntaxhighlight lang="ini">
<syntaxhighlight lang="ini">
# Instead of:
# Solution 1: Specify interfaces (creates dedicated threads)
# interface = any
interface = ens192,ens224  # NOT 'any'


# Use specific interfaces:
# Solution 2: Disable NIC optimization
interface = ens192,ens224
</syntaxhighlight>
This creates a dedicated capture thread for each interface, improving performance on shared servers. Ensure the interfaces you specify are the ones carrying VoIP traffic.
 
'''Solution 2: Disable Automatic Interface Optimization'''
If performance issues persist after specifying specific interfaces, disable automatic NIC optimization:
<syntaxhighlight lang="ini">
# Disable automatic tuning of NIC settings
interfaces_optimize = no
interfaces_optimize = no
</syntaxhighlight>
Note: This option requires the `ethtool` utility to be installed on the system.


'''Solution 3: Reduce Sniffer Load'''
# Solution 3: Reduce sniffer load
For immediate relief, configure the sniffer to reduce CPU consumption:
<syntaxhighlight lang="ini">
# Save only RTP headers (metadata only, no audio payload)
# This prevents audio reconstruction but keeps the RTP analysis tool functional
savertp = header
savertp = header
# Disable audio transcoding (very CPU intensive)
saveaudio = no
saveaudio = no
</syntaxhighlight>
</syntaxhighlight>


'''Long-term Recommendation:'''
'''Long-term:''' Move sensor to dedicated server with SPAN/Mirror. See [[Sniffer_distributed_architecture]].
Move the VoIPmonitor sensor to a dedicated server connected via SPAN/Mirror port to eliminate resource contention entirely. See [[Sniffer_distributed_architecture]] for distributed deployment details.


Increase this value if you experience missing CDRs for calls with large SIP packets (e.g., INVITE requests with extensive SDP, many codec options, custom headers). Typical values are 65535 (maximum Ethernet frame size) or 20000.
== Packet Deduplication ==


To diagnose if packet truncation is the issue, use `tcpdump` with the `-s0` flag to capture full packets and verify packet sizes on your network.
Required when receiving same packets from multiple sources/interfaces.


=== 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
deduplicate = yes
interface_libpcap_filter = eth0 : port 5060
auto_enable_use_blocks = yes  # Required for deduplication
interface_libpcap_filter = eth0 : not port 5060
deduplicate_ipheader = ip_only  # Recommended for different network paths
</syntaxhighlight>
</syntaxhighlight>


=== Multiple Sensor Instances on One Server ===
{| class="wikitable"
When running multiple VoIPmonitor sensor instances on the same physical server to monitor different traffic sources, special configuration is required to prevent resource contention and excessive CPU usage.
! 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
|}


Each instance will compete for CPU cores, memory, and database connections. Improper configuration can lead to high CPU load, memory exhaustion, and system instability after VoIPmonitor upgrades that introduce improved multi-threading capabilities.
== Tunneling Protocol Support ==


;''Important:'' Newer VoIPmonitor versions have enhanced threading defaults. Existing multi-instance setups may experience unexpectedly high CPU load after an upgrade if the instances are not properly configured for resource sharing.
{| class="wikitable"
 
! Parameter !! Default !! Description
==== Memory Allocation ====
|-
;<code>max_buffer_mem = 1000</code>
| <code>udp_port_tzsp</code> || 37008 || Mikrotik TZSP
:(Default: 2000) Set this parameter in each instance's configuration file to limit the total buffer memory per instance. This prevents all instances from consuming all available RAM and causing swap usage. Set this value proportionally based on the number of instances and available RAM. For example, with 16GB RAM and 4 instances, set `max_buffer_mem = 4000` per instance.
|-
| <code>udp_port_l2tp</code> || 1701 || L2TP tunneling
|-
| <code>udp_port_vxlan</code> || 4789 || VXLAN (AWS/cloud)
|-
| <code>audiocodes</code> || no || AudioCodes proprietary tunnel. See [[Audiocodes_tunneling]].
|-
| <code>ipfix</code> || no || Oracle/ACME SBC IPFIX
|-
| <code>hep</code> || no || Homer Encapsulation Protocol
|}


==== Database Thread Throttling ====
== Scan PCAP Directory Mode ==
When running multiple instances on one server, each instance spawning multiple database threads can overwhelm the MySQL connections pool and cause excessive CPU usage. Limit database threads per instance:


;<code>mysqlstore_max_threads_cdr = 1</code>
Process PCAP files instead of live capture. Useful for Windows hosts without SPAN ports.
;(Default: 2) Set to 1 in multi-instance deployments to reduce thread overhead.
;<code>mysqlstore_max_threads_message = 1</code>
;(Default: 2) Limits parallel threads for storing MESSAGE records.
;<code>mysqlstore_max_threads_register = 1</code>
;(Default: 2) Limits parallel threads for storing REGISTER data.
;<code>mysqlstore_max_threads_http = 1</code>
;(Default: 2) Limits parallel threads for HTTP-related data.


;''Note:'' Reducing these values may slow down database writes during traffic bursts, but is necessary to prevent CPU overload when multiple instances compete for database resources.
==== Multi-Instance Configuration Example ====
<syntaxhighlight lang="ini">
<syntaxhighlight lang="ini">
# Instance 1 Configuration (/etc/voipmonitor/instance1.conf)
scanpcapdir = /var/spool/voipmonitor/scanpcap
[general]
scanpcapmethod = newfile
id_sensor = 1
pidfile = /var/run/voipmonitor/instance1.pid
interface = eth0
max_buffer_mem = 1000
mysqlstore_max_threads_cdr = 1
mysqlstore_max_threads_message = 1
mysqlstore_max_threads_register = 1
mysqlstore_max_threads_http = 1
 
# Instance 2 Configuration (/etc/voipmonitor/instance2.conf)
[general]
id_sensor = 2
pidfile = /var/run/voipmonitor/instance2.pid
interface = eth1
max_buffer_mem = 1000
mysqlstore_max_threads_cdr = 1
mysqlstore_max_threads_message = 1
mysqlstore_max_threads_register = 1
mysqlstore_max_threads_http = 1
</syntaxhighlight>
</syntaxhighlight>


;''Note on threading_expanded'': The modern `threading_expanded` parameter (enabled by default) automatically manages threads. In some multi-instance scenarios where you have limited CPU cores, you may need to disable this and use the legacy `threading_mod = 1` for single-threaded processing per instance. However, this is deprecated and should only be used as a last resort.
'''Workflow:'''
# Capture on source: <code>tcpdump -i eth0 udp -G 300 -w /path/dump.pcap</code>
# Transfer to VoIPmonitor server
# Sensor processes files automatically


==== Troubleshooting High CPU After Upgrade ====
= SIP Configuration =
If a multi-instance deployment experiences high CPU load after a VoIPmonitor upgrade:


# Review system baseline load before the upgrade to determine if the server was already near capacity
== Port Settings ==
# Apply the memory and thread throttling settings above to each instance
# Monitor `top` or `htop` to verify CPU usage is distributed properly
# If CPU load remains high after these changes, the root cause may be insufficient hardware capacity. Consider upgrading the server to provide more CPU cores or distributing instances across multiple physical servers.


;''See also:'' [[Sniffer_distributed_architecture|Client/Server mode]] for an alternative to multi-instance deployments on a single host.
{| class="wikitable"
! Parameter !! Default !! Description
|-
| <code>sipport</code> || 5060 || SIP ports. Multiple: <code>5060,5061,5070-5080</code>
|-
| <code>cdr_sipport</code> || yes || Store SIP ports in database
|-
| <code>cdr_country_code</code> || yes || Country code lookup for caller/called. Set <code>no</code> to disable country flags.
|}


=== Tunneling Protocol Support ===
== TCP Reassembly & UDP Fragmentation ==
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>
:(Default: no) Enables Homer Encapsulation Protocol. See [[#HEP Support|HEP Support]] section.
;<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 ===
{| class="wikitable"
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.
! Parameter !! Default !! Description
 
|-
'''Typical configuration for deduplication:'''
| <code>sip_tcp_reassembly_ext</code> || yes || TCP reassembly for SIP over TCP
<syntaxhighlight lang="ini">
|-
# Enable packet deduplication. Uses checksum to identify
| <code>udpfrag</code> || yes || '''Critical:''' IP fragment reassembly for large SIP messages
# and discard duplicate packets. This is CPU intensive.
|-
deduplicate = yes
| <code>max_sip_packets_in_call</code> || 2000 || Maximum SIP packets per call
 
|}
# Required for deduplication to work correctly when
# packets are received from multiple sources or interfaces.
auto_enable_use_blocks = yes


# Count only IP addresses from IP header in the checksum.
= TLS/SSL & SRTP Decryption =
# This is useful when the same packet arrives from different
# network paths with different TTL or other IP header fields.
deduplicate_ipheader = ip_only
</syntaxhighlight>


;<code>deduplicate = yes</code>
== SIP TLS Decryption ==
:(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>use_block = yes</code>
<syntaxhighlight lang="ini">
:(Default: no) Manually enables use of memory blocks for packet processing. This option is recommended in scenarios where the sniffer experiences high traffic loads or processing bottlenecks, particularly when symptoms include: (1) '''SIP registrations incorrectly shown as failed in the GUI''' even though packet captures on the sensor show the traffic is present, or (2) '''Missing call legs in CDRs''' despite complete packet captures. Memory blocks help the sniffer manage packet processing more efficiently, preventing drops during analysis bursts. This option is automatically enabled by `auto_enable_use_blocks = yes`, but can be set manually if needed.
ssl = yes
 
ssl_ipport = 10.0.0.1:5061 /path/to/your.key
;<code>auto_enable_use_blocks = yes</code>
# Subnet with multiple keys:
:(Default: no) Required in two scenarios: (1) '''For deduplication''' when sniffing from multiple sources or interfaces to identify and discard duplicate packets, and (2) '''For correct RTP association''' when SIP signaling and RTP media arrive on different interfaces, NICs, or VLANs, preventing RTP packets from being associated with the wrong call leg. Automatically enables use of memory blocks for deduplication and defragmentation processing.
ssl_ipport = 10.0.0.0/24:5061 /path/key1.pem,/path/key2.pem
 
;<code>deduplicate_ipheader = ip_only</code>
:(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>
:(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.
 
;<code>deduplicate_udpheader_ignore_checksum = yes</code>
:(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.
 
=== Scan PCAP Directory Mode ===
;<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.
;<code>scanpcapdir_thread = 1</code>
:(Default: 1) Number of threads for processing PCAP files in directory mode. Increasing this value can improve performance when processing multiple files, but may cause resource contention. Set to 0 or comment out to avoid threading overhead and performance issues in single-threaded scenarios. If you experience slow CDR processing when reading PCAP files from a directory, try disabling or reducing this setting.
 
This mode is useful in scenarios where live packet capture (SPAN/TAP) is not possible, such as:
 
* Monitoring traffic from a host where VoIPmonitor cannot run (e.g., Windows machines)
* Capturing traffic from isolated network segments without remote sensors
* Processing captured files from multiple sources in batch
 
=== Use Case: Monitoring from Windows Without SPAN Port ===
 
When you need to monitor VoIP traffic from a Windows host but port mirroring is not available, you can use the `scanpcapdir` mode as an alternative:
 
'''Step 1: Capture PCAP files on the Windows host'''
<syntaxhighlight lang="bash">
# On Windows (using WSL, Cygwin, or a Linux machine that can see the traffic)
# Capture UDP traffic to a rolling pcap file (rotates every 5 minutes)
tcpdump -i eth0 udp -G 300 -w /path/to/capture/dump.pcap
 
# Or use the -C option to rotate by file size (e.g., 100MB)
tcpdump -i eth0 udp -C 100 -w /path/to/capture/dump.pcap
</syntaxhighlight>
 
'''Step 2: Transfer PCAP files to the VoIPmonitor server'''
 
Use any file transfer method (SCP, SFTP, NFS, SMB share, rsync, etc.) to move the PCAP files to a directory accessible by the VoIPmonitor sensor.
 
<syntaxhighlight lang="bash">
# Example rsync command (run from Windows via WSL or SSH)
rsync -avz /path/to/capture/dump.pcap user@voipmonitor-server:/var/spool/voipmonitor/scanpcap/
 
# Or mount the Windows directory and have tcpdump write directly to it
# (ensure the mount is stable and handles file locking correctly)
</syntaxhighlight>
</syntaxhighlight>


'''Step 3: Configure VoIPmonitor to scan the directory'''
'''Keylogger support (for PFS/TLS 1.3):'''
 
Edit <code>/etc/voipmonitor.conf</code>:
 
<syntaxhighlight lang="ini">
<syntaxhighlight lang="ini">
[general]
ssl_sessionkey_udp = yes
# Disable live capture (interface is not used in scanpcapdir mode)
ssl_sessionkey_udp_port = 1234
# interface = eth0  <-- Leave this commented out
 
# Point to the directory containing the pcap files
scanpcapdir = /var/spool/voipmonitor/scanpcap
 
# Method: 'newfile' detects new files by modification time
# 'rename' requires files to be written to a temp location and then renamed
scanpcapmethod = newfile
</syntaxhighlight>
</syntaxhighlight>


'''Step 4: Restart VoIPmonitor'''
See [[Tls]] for complete TLS decryption documentation.
 
<syntaxhighlight lang="bash">
systemctl restart voipmonitor
</syntaxhighlight>
 
VoIPmonitor will now automatically scan the specified directory and process any new PCAP files, extracting call data, CDRs, and saving recordings if enabled.
 
'''Important Notes:'''
 
* When using `scanpcapdir`, the <code>interface</code> setting is not used
* Ensure the sensor has read permissions for the pcap files and directory
* The sensor processes each file exactly once and does not re-process already handled files
* Large pcap files (gigabytes in size) may take significant time to process
* Consider using <code>savertp = header</code> if you only need call metadata and not full audio
* File rotation (using `-G` or `-C` in tcpdump) prevents single large files from blocking processing
 
=== SIP Send (Third-Party Forwarding) ===
;<code>sip_send = 192.168.0.2:1555</code>
:(Default: unset) Forwards a copy of all captured SIP packets to a specified third-party destination over TCP or UDP. This is not for mirroring between sensors.
;<code>sip_send_udp = yes</code>
:(Default: no) Use UDP instead of TCP for sip_send.
;<code>sip_send_before_packetbuffer = yes</code>
:(Default: no) Send packets immediately without buffering.
 
== SIP Port & TCP Configuration ==
 
=== SIP Port Settings ===
;<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.
 
=== CDR Country Configuration ===
;<code>cdr_country_code = yes</code>
:(Default: yes) Enables country code lookup and storage in CDR for caller and called number columns. When enabled, VoIPmonitor attempts to determine the country code from telephone numbers and stores the information in the `cdr.caller_country` and `cdr.called_country` columns. This allows the GUI to display country flags and filter CDRs by country. Set to `no` to disable country code detection and storage, which may be useful if you do not use country-based filtering or want to reduce processing overhead.
 
{{Warning|1=Setting <code>cdr_country_code = no</code> disables country flags in the CDR view and prevents filtering by country, even if GeoIP and country prefix settings are configured. If country flags are not appearing in the GUI, check this setting and ensure it is set to <code>yes</code> (or commented out for default behavior).}}
 
=== TCP Reassembly ===
;<code>sip_tcp_reassembly_ext = yes</code>
:(Default: yes) Enable TCP reassembly for SIP over TCP.
;<code>sip_tcp_reassembly_stream_max_attempts = 50</code>
:(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.
 
=== UDP Fragmentation ===
;<code>udpfrag = yes</code>
:(Default: yes) Enable IP fragment reassembly for UDP packets. Large SIP messages (especially INVITE with SDP) may be fragmented at the IP layer when they exceed the MTU. When enabled, VoIPmonitor reassembles IP fragments before parsing SIP. '''Critical for missing SIP packets that contain large headers or SDP.''' Disable only for debugging purposes or when you are certain no fragmented traffic exists in your environment.
 
=== SIP Packet Limits ===
;<code>max_sip_packets_in_call = 2000</code>
:(Default: 2000) Maximum SIP packets per call.
;<code>max_invite_packets_in_call = 10000</code>
:(Default: 10000) Maximum SIP INVITE packets per call.
 
== SIP TLS/SSL Decryption ==
 
To decrypt TLS-encrypted SIP traffic, you need to provide the private key. Note that Diffie-Hellman ciphers cannot be decrypted without session keys.
 
;<code>ssl = yes</code>
:(Default: no) Enable TLS/SSL decryption for SIP.
 
;<code>ssl_ipport = 10.0.0.1 : 5061 /path/to/your.key</code>
:(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>
:Example with subnet and multiple keys.
 
;<code>ssl_ipport_reverse_enable = yes</code>
:(Default: no) Enable reverse detection logic for ssl_ipport.
 
;<code>ssl_store_sessions_expiration_hours = 12</code>
:(Default: 12) SSL sessions expire after this many hours.
 
;<code>ssl_sessionkey_udp = yes</code>
:(Default: no) Enable parsing of session keys sent via UDP (keylogger support).
 
;<code>ssl_sessionkey_udp_port = 1234</code>
:UDP port for receiving session keys.
 
;<code>ssl_store_sessions = persistent</code>
:(Default: persistent) How to store SSL keys: 'persistent' (InnoDB) or 'memory'.
 
'''Choosing Between Storage Options'''
 
The <code>ssl_store_sessions</code> parameter controls where VoIPmonitor stores encryption keys for SSL/TLS sessions:
 
* '''persistent''' (Recommended): Stores keys in the <code>ssl_sessions</code> InnoDB table on disk. This provides virtually unlimited storage space and eliminates "table full" errors.
 
* '''memory''' (Legacy): Stores keys in the <code>ssl_sessions_mem</code> MEMORY table in RAM. This provides faster performance but has a hard size limit defined by MySQL's <code>max_heap_table_size</code> and the table's <code>MAX_ROWS</code> definition. When this table becomes full, VoIPmonitor cannot write new session keys, leading to decryption failures and data insertion errors.
 
'''Recovering from a Full ssl_sessions_mem Table'''
 
If you encounter errors because the <code>ssl_sessions_mem</code> table is full:
 
1. On the main database server, identify which sensor(s) are still writing to the memory table:
<syntaxhighlight lang="sql">SELECT id_sensor, COUNT(*) FROM ssl_sessions_mem GROUP BY id_sensor;</syntaxhighlight>
 
2. Log into each identified sensor.
 
3. Edit <code>/etc/voipmonitor.conf</code> and ensure the setting is:
<syntaxhighlight lang="ini">ssl_store_sessions = persistent</syntaxhighlight>
 
4. Restart the VoIPmonitor sniffer service on each sensor to apply the change. This will direct new SSL session keys to the persistent <code>ssl_sessions</code> InnoDB table:
<syntaxhighlight lang="bash">systemctl restart voipmonitor</syntaxhighlight>
 
5. (Optional) Clear the existing data from the memory table on the database server:
<syntaxhighlight lang="sql">TRUNCATE TABLE ssl_sessions_mem;</syntaxhighlight>
 
'''Note:''' After switching to persistent storage, ensure your regular database maintenance scripts or partitioning strategies account for the growth of the <code>ssl_sessions</code> table on disk to prevent the disk itself from filling up over time.
 
;<code>ssl_tls_12_sessionkey_mode = dssl</code>
:(Default: dssl) Decryption library: 'dssl' or 'wireshark'.
 
;<code>ssl_ignore_error_invalid_mac = yes</code>
:(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
;<code>ssl_dtls_handshake_safe = no</code>
</syntaxhighlight>
:(Default: no) DTLS handling approach: no (queue), only (unified), yes (both, queue priority), ext (both, unified priority).
 
;<code>ssl_dtls_boost = no</code>
:(Default: no) A '''meta-parameter''' that enables a set of aggressive options for improving DTLS handshake and SRTP decryption success rates. 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 ==
 
These options control how caller and called party information is extracted from SIP headers.
 
;<code>remoteparty_caller = calling</code>
:(Default: unset) Update caller number from Remote-Party-ID header. Use 'calling' or 'called' based on the party attribute.
 
;<code>remoteparty_called = called</code>
:(Default: unset) Update called number from Remote-Party-ID header.
 
;<code>passertedidentity = no</code>
:(Default: no) Use P-Asserted-Identity header for caller info.
 
;<code>ppreferredidentity = no</code>
:(Default: no) Use P-Preferred-Identity header for caller info.
 
;<code>remotepartypriority = no</code>
:(Default: no) Give Remote-Party-ID priority over P-Asserted-Identity and P-Preferred-Identity.
 
;<code>callernum_numberonly = yes</code>
:(Default: yes) Parse only the number part from identity headers.
 
;<code>destination_number_mode = 1</code>
:(Default: 1) Source for destination number: 1 = To header, 2 = INVITE URI.
 
;<code>sipoverlap = yes</code>
:(Default: yes) Update destination number from subsequent INVITEs (overlap dialing support per RFC 3578).
 
;<code>last_dest_number = no</code>
:(Default: no) Always take destination from latest INVITE regardless of source IP.
 
;<code>update_dstnum_onanswer = no</code>
:(Default: no) Update destination number when callee answers (useful for hunt groups).
 
== Performance & Threading ==


=== Core Threading Model ===
= Distributed Operation =
;<code>t2_boost = high_traffic</code>
:(Default: unset) Optimizes the threading model for high-traffic environments (>=1500Mbit). This setting automatically adjusts thread allocation, which resolves CPU bottlenecks where a single defrag or reassembly thread runs at 100% while other threads are idle. Use this when you observe one thread at 100% CPU alongside "packetbuffer: MEMORY IS FULL" errors. Available values: `high_traffic` for very high bandwidth deployments, or `no` to disable.
;<code>threading_expanded = yes</code>
:(Default: yes) Enables the modern, multi-threaded processing engine. The sniffer automatically spawns and manages threads based on traffic load and CPU capacity. Set to `high_traffic` for environments exceeding 5 Gbit/s or very high concurrent call loads (8,000-10,000+ calls) where PACKETBUFFER saturation occurs.
;<code>preprocess_rtp_threads = 2</code>
:(Default: 2) The initial number of threads for RTP preprocessing. The system will auto-scale from here.
;<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_start = 20</code>
:(Default: rtpthreads value or half of CPU count) Starting number of RTP processing threads. For high concurrent call loads (8,000-10,000+ calls), set to approximately half of the total CPU count or a specific value like 20. This parameter directly influences RTP thread initialization and helps prevent PACKETBUFFER saturation under heavy load.
;<code>rtpthreads = 0</code>
:(Default: CPU count) Number of threads for RTP packet processing. 0 disables threading.


=== Thread Scheduling & Priority ===
See [[Sniffer_distributed_architecture]] for complete documentation.
;<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):
;<code>sched_pol_interface = prio -20</code>
;<code>sched_pol_pb = prio -20</code>
;<code>sched_pol_sip = prio -20</code>
;<code>sched_pol_rtp_prep = prio -20</code>
;<code>sched_pol_rtp_read = prio -20</code>
=== NUMA & Memory ===
;<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 ===
;<code>ringbuffer = 50</code>
:(Default: 50) Ringbuffer size in MB. Recommended >= 500 for >100 Mbit traffic. Max 2000.
;<code>packetbuffer_enable = yes</code>
:(Default: yes) Enable packet buffer cache.
;<code>packetbuffer_compress = no</code>
:(Default: no) Enable packet buffer compression. In distributed client/server setups with multiple sensors, set to <code>yes</code> on client instances to reduce the data transfer rate to the central server and prevent packet buffer memory overflow errors.
;<code>packetbuffer_compress_ratio = 100</code>
:(Default: 100) Compression ratio for packet buffer compression (1-100). Higher values provide better compression at the cost of increased CPU usage. Use <code>100</code> for maximum compression to minimize network bandwidth in distributed setups.
;<code>max_buffer_mem = 2000</code>
:(Default: 2000) Maximum buffer memory in MB. Increase to 10000 or higher for high concurrent call loads (8,000-10,000+ calls) to prevent "PACKETBUFFER: memory is FULL" errors. In distributed setups with compression enabled, a reasonable value of <code>10000</code> helps prevent excessive queuing of old packets when network transfer rates cannot keep up with data generation. Ensure sufficient RAM is available.
;<code>memory_purge_interval = 30</code>
:(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 supports distributed deployments where remote sensors send data to a central server. There are two operational modes controlled by the <code>packetbuffer_sender</code> parameter:
<div style="overflow-x: auto;">
<kroki lang="mermaid">
<kroki lang="mermaid">
%%{init: {'flowchart': {'nodeSpacing': 15, 'rankSpacing': 40}}}%%
%%{init: {'flowchart': {'nodeSpacing': 15, 'rankSpacing': 40}}}%%
Line 901: Line 382:
         A1 -->|"Stores PCAP"| A4[(Local Disk)]
         A1 -->|"Stores PCAP"| A4[(Local Disk)]
     end
     end
     subgraph "Packet Mirroring (packetbuffer_sender=yes)"
     subgraph "Packet Mirroring (packetbuffer_sender=yes)"
         B1[Remote Sensor] -->|"Forwards packets"| B2[Central Server]
         B1[Remote Sensor] -->|"Forwards packets"| B2[Central Server]
Line 907: Line 387:
     end
     end
</kroki>
</kroki>
</div>


'''Key differences:'''
== Client/Server Configuration ==
* '''Local Processing''' (<code>packetbuffer_sender=no</code>): Low network usage, PCAP files stored on remote sensor, higher CPU usage on sensor
* '''Packet Mirroring''' (<code>packetbuffer_sender=yes</code>): Higher network usage, all data centralized, minimal CPU usage on sensor


=== Modern Client/Server Model (Recommended) ===
'''Central Server:'''
;<code>server_bind = 0.0.0.0</code>
<syntaxhighlight lang="ini">
:The IP address the central sensor will listen on for connections from remote clients.
server_bind = 0.0.0.0
;<code>server_bind_port = 60024</code>
server_bind_port = 60024
:(Default: 60024) Port for client connections.
server_password = yourpassword
;<code>server_destination = 10.0.0.1</code>
# CRITICAL: Exclude server port from sipport!
: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`.
sipport = 1-60023,60025-65535
;<code>server_destination_port = 60024</code>
</syntaxhighlight>
:(Default: 60024) Port of the central server.
;<code>server_password =</code>
:A shared password to authenticate clients and servers.
;<code>packetbuffer_sender = no</code>
:(Default: no) The operational mode. `no` for local processing (low network usage), `yes` for packet mirroring (low remote CPU usage).
;<code>packetbuffer_file_path = /path/to/directory</code>
:Path to a local directory where CDR packets will be cached to disk when the connection to the central server is lost or temporarily unavailable. This provides a fallback queue for packet transmission during network outages. When the connection is restored, cached packets are transmitted. Note that the server may discard packets that are too old upon reconnection. (Default: not set - packets are buffered in memory only and lost if connection fails)


{| class="wikitable" style="background:#fff3cd; border:1px solid #ffc107;"
'''Remote Sensor:'''
! colspan="2" style="background:#ffc107;" | Important: packetbuffer_sender Controls Packet Transmission
|-
| style="vertical-align: top;" | '''Critical Behavior:'''
| When <code>packetbuffer_sender = yes</code>, '''all packets are transmitted''' (forwarded to central server or sent via packet buffer), which includes RTP packets regardless of your <code>savertp</code> setting. This option always transmits full packet streams for processing.
|-
| style="vertical-align: top;" | '''If RTP is recorded despite <code>savertp = no</code>:'''
| Check for <code>packetbuffer_sender = yes</code> in your configuration. This setting will cause RTP packets to be saved because the raw packet stream is being transmitted. Set <code>packetbuffer_sender = no</code> or comment out the line to disable packet transmission.
|}
;<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.
 
'''Important: Exclude server_bind_port from sipport'''
On central servers in client/server mode, ensure the <code>server_bind_port</code> (default 60024) is <strong>excluded</strong> from the <code>sipport</code> directive. Including this port causes the sensor-to-server communication traffic to be captured as SIP packets, leading to high and continuously increasing memory utilization.
 
Example for default <code>server_bind_port = 60024</code>:
<syntaxhighlight lang="ini">
<syntaxhighlight lang="ini">
# WRONG - includes sensor communication port:
id_sensor = 2
sipport = 1-65535
server_destination = 10.0.0.1
 
server_destination_port = 60024
# CORRECT - excludes sensor communication port:
server_password = yourpassword
sipport = 1-60023
packetbuffer_sender = no  # or yes for packet mirroring
sipport = 60025-65535
</syntaxhighlight>
</syntaxhighlight>


See [[Sniffer_distributed_architecture|Distributed Architecture]] for more details.
{{Warning|1=When <code>packetbuffer_sender = yes</code>, '''all packets including RTP are transmitted''' regardless of <code>savertp</code> setting.}}


=== Time Synchronization ===
= Storage & File Management =
;<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 in seconds for packet buffer reception on the central server. Packets older than this threshold are discarded. Adjust this value in distributed setups to control how aggressively the server filters stale packets when client buffers are overloaded.


=== Legacy Mirroring Model ===
== Spool Directory ==
;<code>mirror_bind_ip = 0.0.0.0</code>
:The IP the receiver sensor listens on for the unencrypted, legacy mirroring protocol.
;<code>mirror_bind_port =</code>
:Port for legacy mirroring.
;<code>mirror_bind_sensor_id_by_sender = yes</code>
:(Default: no) Bind the sensor ID to the sending probe's IP address in mirroring mode. When enabled, packets received from different probes are automatically associated with the corresponding sensor ID configured on each probe. This is useful for distinguishing which probe sent the packets in distributed mirror mode deployments where multiple probes forward traffic to a single receiver.
;<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) ==
{| class="wikitable"
! Parameter !! Default !! Description
|-
| <code>spooldir</code> || /var/spool/voipmonitor || Primary storage directory
|-
| <code>spooldir_2</code> || unset || Secondary storage for capture rules with "Store to second spooldir"
|-
| <code>cachedir</code> || unset || Temp storage (use RAM/SSD for performance)
|}


=== Location and Permissions ===
{{Note|1=For GUI access to <code>spooldir_2</code>, configure "Sniffer second datapath" in GUI Settings > System Configuration > Basic.}}
;<code>spooldir = /var/spool/voipmonitor</code>
:The primary directory for storing all captured data (PCAP, GRAPH, AUDIO files).
;<code>spooldir_rtp =</code>
:Separate directory for RTP files.
;<code>spooldir_graph =</code>
:Separate directory for graph files.
;<code>spooldir_audio =</code>
:Separate directory for audio files. When set, audio files are saved directly to this directory without the default spooldir date/time nesting structure. '''Warning:''' This configuration spawns a separate audio conversion process for every call, which can overload the system with high call volumes. This method is not recommended for deployments with more than 100 concurrent calls. For high-traffic deployments, consider using <code>saveaudio_singlefolder</code> or a scripting workaround to move files from the default spooldir structure.
;<code>spooldir_2 = /var/spool/voipmonitor2</code>
:Secondary storage directory with separate autoclean setup. This directory is used exclusively for PCAPs from calls that match capture rules where the "Store pcaps to second spooldir" option is enabled. '''Note:''' This is NOT an automatic overflow directory when the primary <code>spooldir</code> becomes full. When the primary directory reaches its limit (defined by <code>maxpoolsize</code> or <code>maxpooldays</code>), the <code>cleanspool</code> process triggers and deletes the oldest files from the primary directory to free up space. Standard traffic continues to write to the primary <code>spooldir</code> based on your capture rules. Use this feature to store specific subsets of calls (e.g., VIP customers, legal holds) that require different retention policies (e.g., <code>maxpoolsize_2</code>, <code>maxpooldays_2</code>) than the standard traffic. '''Important:''' To allow the GUI to access files stored in <code>spooldir_2</code>, you must also configure the "Sniffer second datapath" setting in the GUI under '''Settings > System Configuration > Basic''' and set it to the same path as <code>spooldir_2</code> in the sensor configuration. Without this GUI setting, the web interface will show "Data not yet written to disk" errors when trying to access recordings stored in the secondary spool directory, even though the files exist on the disk.
;<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 ===
== TAR Storage Strategy ==
;<code>tar = yes</code>
:(Default: yes) This is a key performance feature. Instead of writing thousands of small PCAP files, voipmonitor groups them into minute-based `.tar` archives, which drastically reduces disk I/O load.
;<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.


=== Saving Options ===
<syntaxhighlight lang="ini">
;<code>savesip = yes</code>
tar = yes # Group PCAPs into minute-based archives (reduces I/O)
:Enables saving of SIP packets.
tar_compress_sip = zstd
;<code>savertp = yes</code>
tar_compress_graph = zstd
:Controls saving of RTP packets. Options are <code>yes</code> (save full RTP packets), <code>header</code> (save only RTP headers, not the audio payload), or <code>no</code> (do not save RTP packets). <code>savertp = header</code> prevents audio reconstruction but keeps the RTP analysis tool functional in the GUI. <code>savertp = no</code> also disables the RTP analysis tool, but QoS/MOS metrics are still calculated from RTCP packets regardless of the savertp setting.
</syntaxhighlight>
;<code>savertp_video = no</code>
:(Default: no) Save video RTP packets. Options: no, yes, header, cdr_only. '''Important: VoIPmonitor can capture and save only one video RTP stream per call (CDR). If a SIP session negotiates multiple video streams simultaneously, only ONE stream will be saved to the PCAP file. The other video streams will not be captured in the PCAP. This is a system limitation - you cannot capture multiple video streams from a single session to a PCAP file concurrently. As a workaround, you can use <code>savertp_video = cdr_only</code> to capture metadata without storing full video payloads, use custom SIP headers to store SDP attributes in the database for filtering and reporting, or configure call merging to split sessions into separate CDRs if possible. This limitation applies to PCAP file storage. The <code>cdr_rtp</code> table will still show all detected video streams, but only the first one will be present in the PCAP file.'''
;<code>savertcp = yes</code>
:Enables saving of RTCP (RTP Control Protocol) packets.
;<code>saveudptl = no</code>
:(Default: no) Save T.38 fax packets (transported via UDPTL protocol). When enabled, T.38 fax packets are saved to the PCAP file regardless of the <code>savertp</code> setting. This allows viewing T.38 packets in the SIP History ladder diagram and enables TIFF fax image generation from captured calls. Use this option when you want to keep audio RTP streams header-only for space savings (<code>savertp = header</code> or <code>savertp = no</code>) while still capturing fax data for analysis and debugging. Note: If <code>savertp = yes</code> is set, T.38 packets are automatically saved as part of RTP streams and this option is redundant.
;<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.


=== Disabling Audio Recording ===
== Saving Options ==


To prevent VoIPmonitor from recording calls or saving RTP streams (ensuring no audio can be reconstituted), use the following configuration:
{| 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
|}


;<code>savertp = header</code>
'''Disable audio recording:'''
:'''CRITICAL: Use <code>header</code>, not <code>no</code>.''' Setting <code>savertp = header</code> saves RTP headers for QoS statistics and RTP analysis tools but discards the audio payload, preventing audio reconstruction. Using <code>savertp = no</code> will also disable the RTP analysis tool in the GUI.
 
;<code>saveaudio = no</code>
:Disables automatic audio file extraction (<code>.wav</code>, <code>.ogg</code>, <code>.mp3</code>).
 
'''Complete configuration for no audio recording:'''
<syntaxhighlight lang="ini">
<syntaxhighlight lang="ini">
# Disable audio recording - save headers only for statistics
savertp = header # NOT 'no' - keeps RTP analysis tool working
savertp = header
saveaudio = no
saveaudio = no
</syntaxhighlight>
</syntaxhighlight>


{{Note|1=If you need to capture T.38 fax packets for display in the SIP History ladder diagram (or for TIFF fax image generation) while keeping audio RTP streams header-only for space savings, add <code>saveudptl = yes</code> to your configuration. This allows fax monitoring without saving full audio RTP payloads.}}
== Spool Cleaning ==


{{Warning|1=When using <code>packetbuffer_sender = yes</code> (probe mode), these settings must be applied on the '''receiving central server''', not the probe itself. The probe forwards all packets including RTP to the central server for processing.}}
{| class="wikitable"
! Parameter !! Default !! Description
|-
| <code>cleanspool</code> || yes || Enable automatic spool cleaning
|-
| <code>maxpoolsize</code> || 102400 || Size limit in MB
|-
| <code>maxpooldays</code> || unset || Age limit in days
|-
| <code>autocleanspoolminpercent</code> || 1 || Emergency cleaning trigger (% free)
|}


{{Warning|1=If <code>savertcp = yes</code> is enabled, RTCP packets will be stored separately. This may cause the GUI to display audio replay buttons that will fail to play audio, since only RTCP information is available and not the actual RTP payload. Set <code>savertcp = no</code> to prevent this confusion.}}
== Audio File Generation ==


'''Verifying audio recording is disabled:'''
{| class="wikitable"
<syntaxhighlight lang="bash">
! Parameter !! Default !! Description
# Check spool directory sizes - should show minimal growth for RTP/RTPALL
|-
du -h -d1 /var/spool/voipmonitor/ | sort -k2,2
| <code>saveaudio</code> || no || Generate audio files: <code>wav</code>, <code>ogg</code>, <code>mp3</code>, or <code>yes</code>
</syntaxhighlight>
|-
| <code>saveaudio_singlefolder</code> || unset || Dedicated directory for audio files
|-
| <code>saveaudio_stereo</code> || yes || Caller=left, called=right channel
|}


After running calls, the <code>RTP</code> and <code>RTPALL</code> directories should remain small (only headers) and no <code>.wav</code>, <code>.ogg</code>, or <code>.mp3</code> audio files should be generated.
= Call Processing =


=== PCAP Compression ===
== Timeouts ==
;<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 ===
{| class="wikitable"
;<code>cleanspool = yes</code>
! Parameter !! Default !! Description
:(Default: yes) Enables the automatic cleaning process for the spool directory.
|-
;<code>cleanspool_enable_fromto = 1-5</code>
| <code>absolute_timeout</code> || 14400 || Force-end calls longer than this (seconds). Sets <code>cdr.bye = 102</code>.
:(Default: 0-24) Restrict cleaning to specific hours.
|-
;<code>maxpoolsize = 102400</code>
| <code>rtptimeout</code> || 300 || Close call if no RTP/RTCP for this duration
:(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>
| <code>sipwithoutrtptimeout</code> || 3600 || Close SIP call without RTP
:(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>onewaytimeout</code> || 15 || End call if no reply from other side
;<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) Clean files not in the index.


=== Audio File Generation ===
== Call Merging ==
;<code>saveaudio = wav</code>
:(Default: no) If enabled, voipmonitor will generate an audio file (`.wav`, `.ogg`, or `.mp3`) for each call in addition to the PCAP file. Options: <code>wav</code>, <code>ogg</code>, <code>mp3</code>, or <code>yes</code>. Using <code>yes</code> will default to WAV format. '''Note:''' This is generally not necessary and adds significant CPU/I/O load.
;<code>save_audiograph = yes</code>
:(Default: no) Enables generation of audio graph files (waveform and spectrogram images) stored in the <code>spooldir/AUDIOGRAPH</code> directory. These graphs visualize audio quality (MOS, jitter, packet loss) without requiring audio playback. If <code>savertp = yes</code>, audio graph files can be generated directly from the PCAP file without needing to enable this option. For auto-cleaning configuration, see <code>maxpoolaudiographsize</code> and <code>maxpoolaudiographdays</code>.
;<code>audiograph_fftw_fork_mode = no</code>
:(Default: yes) Controls the FFTW (Fastest Fourier Transform) library's threading mode for audiograph generation. Setting to <code>no</code> disables the fork-based thread pool, preventing memory leaks in the sensor process. Use this setting if you experience intermittent audiograph generation failures or sensor crashes. This option resolves issues where audiographs become unavailable in the GUI due to process instability.
;<code>audiograph_ms_per_pixel = 0</code>
:(Default: variable) Controls the horizontal resolution of the audiograph waveform by specifying milliseconds of audio per pixel. Lower values produce higher resolution waveforms (more pixels per second of audio), while higher values reduce detail. Setting to <code>0</code> enables maximum resolution for the highest quality saved audiograph images, matching the quality generated on-demand by the audio player. Adjust this value if you notice significant quality differences between saved audiograph images and the audio player visualization. Tradeoff: higher resolution requires more disk space and processing time.
;<code>audiograph_spectrogram_height = 64</code>
:(Default: variable) Controls the height (in pixels) of the spectrogram portion of the audiograph. Increasing this value produces taller and more detailed spectrograms, while decreasing it saves disk space and reduces generation time. Set to <code>64</code> or higher for high-quality saved audiograph images. The spectrogram height affects only the saved image files; on-demand audio player generation may use different defaults. Adjust together with <code>audiograph_ms_per_pixel</code> to match the quality generated by the audio player.
;<code>saveaudio_singlefolder = /var/spool/voipmonitor/audio</code>
:(Default: unset) Store all generated audio files in a dedicated directory separate from the main PCAP spooldir structure. Audio files are organized under the specified path with date-based subdirectories (e.g., <code>/var/spool/voipmonitor/audio/2025/01/05/</code>), which makes it easier to isolate audio storage for separate backup, mounting, or management purposes. This is the recommended approach for separating audio storage while maintaining organized directory structure. '''Prerequisite:''' <code>saveaudio</code> must be enabled (set to <code>wav</code>, <code>ogg</code>, <code>mp3</code>, or <code>yes</code>).
;<code>saveaudio_afterconnect = no</code>
:(Default: no) Store audio only for connected calls.
;<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.


=== Real-Time Call Notifications (SendCallInfo) ===
{| class="wikitable"
! Parameter !! Default !! Description
|-
| <code>matchheader</code> || unset || SIP header to link call legs in GUI
|-
| <code>callidmerge_header</code> || unset || Header containing parent Call-ID for CDR merging
|-
| <code>call_id_alternative</code> || unset || Alternative identifiers (e.g., <code>Session-ID,Join</code> for CUCM)
|}


{{Tip|This feature enables integration with external systems such as CRMs, helpdesk tickets, or custom dashboards by sending call information in real-time.}}
See [[Merging_or_correlating_multiple_call_legs]] for detailed documentation.


The `SendCallInfo` feature sends real-time call notifications to a remote URL '''before''' the call ends and before the CDR is stored in the database. This allows external systems to receive call information as it happens, based on SIP packets.
== Recording Control ==


;<code>SendCallInfo = yes</code>
{| class="wikitable"
:(Default: no) Enable real-time call notifications to an external URL. When enabled, VoIPmonitor sends HTTP requests to the configured destination URL as calls are detected.
! 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
|}


;<code>SendCallInfoUrl = http://your-api-server.com/endpoint</code>
== Custom Headers ==
:Destination URL where call information will be sent. The URL must be reachable from the VoIPmonitor server.


;<code>SendCallInfoMethod = post</code>
<syntaxhighlight lang="ini">
:(Default: post) HTTP method to use for sending call information. Supported methods are `post`, `get`, and `json`.
custom_headers = Referred-By, Diversion, X-Custom-Header
custom_headers_last_value = yes
custom_headers_max_size = 1024
</syntaxhighlight>


;<code>SendCallInfoContentType = application/json</code>
After adding headers, configure display in GUI: '''Settings > CDR Custom Headers'''.
:(Default: application/json) Content-Type header for the HTTP request. Configure this based on your external API requirements.


{{Warning|The HTTP request is sent based on SIP packet information during the call, not after the call completes. Final call duration and termination data will not be included in the notification.}}
== SIP History ==


=== Email SMTP Configuration ===
;<code>save_sip_history</code>
:(Default: no) Store SIP signaling for GUI filtering.
* <code>requests</code> - All SIP methods (PUBLISH, INFO, UPDATE, PRACK, REFER) in "SIP requests" filter
* <code>responses</code> - Full response text for searching (not just codes)
* <code>all</code> - Both requests and responses


;<code>email_smtp_server = localhost</code>
{{Warning|1=Enabling SIP history significantly increases database load and storage.}}
:(Default: unset) SMTP server address for sending notification emails from the sniffer. When configured, the sniffer uses this server for any email-based alerts or notifications. If not needed, leave this option unset or comment it out to avoid connection attempts overhead. If you experience slow performance or delays in CDR processing, especially when processing PCAP files from a directory, consider commenting out this setting as it may cause thread blocking during SMTP connection attempts.


== Call Processing & Protocol Logic ==
== RTP Processing ==


=== Call Identification & Merging ===
{| class="wikitable"
;<code>remoteparty_caller = calling</code>, `passertedidentity = no`, etc.
! Parameter !! Default !! Description
: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>
| <code>jitterbuffer_f1</code> || yes || 50ms fixed jitterbuffer simulation
:(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>
| <code>jitterbuffer_f2</code> || yes || 200ms fixed jitterbuffer simulation
: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>
| <code>jitterbuffer_adapt</code> || yes || Adaptive jitterbuffer (up to 500ms)
:A more advanced method to merge call legs based on a shared identifier in a custom header.
|-
;<code>callidmerge_secret = yourSecretString</code>
| <code>allow-zerossrc</code> || no || Accept RTP with zero SSRC (some legacy gateways)
: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 ===
'''CPU optimization (saves ~30%):'''
;<code>absolute_timeout = 14400</code>
<syntaxhighlight lang="ini">
:(Default: 4 hours) Forcefully ends any call that lasts longer than this value to prevent runaway processes. Sets `cdr.bye = 102`.
mosf1 = no
;<code>rtptimeout = 300</code>
mos_adapt = no
:(Default: 5 minutes) Closes a call if no RTP or RTCP packets have been received for this duration.
mosf2 = yes # Keep only f2 for stable MOS metric
;<code>sipwithoutrtptimeout = 3600</code>
</syntaxhighlight>
:(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.


=== Source Code Configuration (Advanced) ===
== Audio Analysis ==


The following timeout values are configured at compile time by modifying the sniffer source code and recompiling. These are not available as configuration file options. To change them:
{| 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
|}


# Download the sniffer source code from GitHub:
See [[Silence_detection]] for detailed documentation.
<syntaxhighlight lang="bash">
cd /usr/src
git clone -b master https://github.com/voipmonitor/sniffer.git
cd sniffer
</syntaxhighlight>


# Locate and modify the constant definition:
== NAT Handling ==
;<code>destroy_call_at_bye</code>
:Timeout in seconds after BYE packet before stopping call interception. Edit the constant definition in <code>call_table.cpp</code> and set the desired value (e.g., <code>1200</code> for 20 minutes).


# Recompile the sniffer:
<syntaxhighlight lang="ini">
<syntaxhighlight lang="bash">
natalias = 1.1.1.1 10.0.0.3  # Public to private IP mapping
./configure
sdp_reverse_ipport = no  # Reverse sniffing for NAT (use with caution)
make
make install
systemctl restart voipmonitor
</syntaxhighlight>
</syntaxhighlight>


This forces the sniffer to stop intercepting a call after the specified timeout following a BYE packet, even if RTP streams are still active.
= Protocol Support =


=== RTP Processing ===
== SIP REGISTER/OPTIONS/SUBSCRIBE ==
;<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.


:'''Behavior:''' By default (<code>yes</code>), MOS is calculated and counted. CPU-intensive; disable some on resource-constrained systems. Setting to <code>no</code> skips MOS calculation and pushes static value 4.5 to GUI. Setting to <code>null</code> skips calculation and pushes '-' (NULL) to GUI. Disabling calculation saves CPU time on heavily loaded hosts.
{| class="wikitable"
! Parameter !! Default !! Description
|-
| <code>sip-register</code> || no || Process REGISTER messages (<code>yes</code>, <code>nodb</code>, <code>no</code>)
|-
| <code>sip-options</code> || no || Process OPTIONS messages
|-
| <code>sip-subscribe</code> || no || Process SUBSCRIBE messages
|-
| <code>sip-message</code> || yes || Process MESSAGE requests
|}


;<code>mosmin_f2 = yes</code>
See [[Register]] for detailed REGISTER documentation.
:(Default: yes) Calculate mos_min_mult10 only from f2 jitter simulator.


;''Note for CPU optimization:'' If you experience high CPU load on RTP processing threads during peak call volume, you can significantly reduce CPU consumption (approximately 30%) by disabling MOS calculations for f1 and adaptive jitterbuffer while keeping f2 MOS calculation active. Configure as follows:
== Other Protocols ==
;<code>mosf1 = no</code>
:(Default: yes) Calculate MOS for jitterbuffer_f1. Disabling saves CPU on RTP threads.
;<code>mosf2 = yes</code>
:(Default: yes) Calculate MOS for jitterbuffer_f2 (static 200ms jitter). This provides a stable MOS metric even when f1/adapt are disabled.
;<code>mos_adapt = no</code>
:(Default: yes) Calculate MOS for adaptive jitterbuffer. Disabling provides additional CPU savings.


=== RTP Tracking & SDP ===
{| class="wikitable"
;<code>sdp_multiplication = 3</code>
! Parameter !! Default !! Description
:(Default: 3) How many calls can share same IP:port. 0 = only newest call.
|-
;<code>disable_process_sdp = no</code>
| <code>skinny</code> || no || Cisco Skinny/SCCP protocol
:(Default: no) Disable SDP processing. Only for very high CPS (>1000).
|-
;<code>rtp_check_both_sides_by_sdp = no</code>
| <code>mgcp</code> || no || MGCP protocol
:(Default: no) Eliminate RTP duplication by checking source IP:port. Options:
|-
:* <code>no</code>: Disabled (default)
| <code>ss7</code> || no || SS7-over-IP (SIGTRAN)
:* <code>yes</code>: Verify both sides per SDP
|-
:* <code>keep_rtp_packets</code>: Same as 'yes' but store unverified packets for debugging
| <code>diameter</code> || no || Diameter protocol
:* <code>strict</code>: Allow unverified packets until first verified packet arrives
|-
:* <code>very_strict</code>: No unverified packets allowed at any time
| <code>ipv6</code> || no || IPv6 support (requires IPv6 database columns)
;<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. Some VoIP gateways or PBX systems may send RTP packets with an SSRC (Synchronization Source) value of zero during specific scenarios such as silence periods, hold states, or certain codec configurations. By default VoIPmonitor drops these packets because a zero SSRC does not typically indicate a valid RTP stream. If you observe calls with missing audio during silence or apparent "dropped" RTP packets, enable this option. This setting is particularly useful when monitoring specific legacy or non-standard VoIP equipment that uses zero SSRC values.
;<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) ===
See [[#SRTP Configuration|SRTP Configuration]] section above.
 
=== NAT Handling ===
;<code>natalias = 1.1.1.1 10.0.0.3</code>
:Creates a mapping between a public IP and a private IP, helping the sniffer correctly associate call legs behind a NAT device. Multiple lines can be used.
;<code>sdp_reverse_ipport = no</code>
:(Default: no) Enable reverse IP:port sniffing for NAT scenarios. Use with caution.
;<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 ===
= Advanced Protocol Support =
;<code>sip-register = no</code>
:(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-register-state-compare-digest_ua = no</code>
:(Default: no) When enabled with <code>yes</code>, the sniffer will create a new record in the register state table whenever the SIP User-Agent (UA) string changes, even if other registration details remain the same. The alias <code>sip-register-state-compare-ua = yes</code> can also be used. This allows detection of UA changes by querying the database, but does not trigger a native GUI alert. Use with the anti-fraud system or custom database queries for detection.
;<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.
 
=== SIP History for Requests ===
;<code>save_sip_history = no</code>
:(Default: no) Enables storage of SIP signaling in the database. Multiple options are available depending on your needs:
:* <code>no</code> (default) - No SIP history stored
:* <code>requests</code> - Stores ALL SIP request methods (PUBLISH, INFO, UPDATE, PRACK, REFER, etc.) in the <code>sip_request</code> table, enabling GUI filtering with the "SIP requests" dropdown
:* <code>responses</code> - Stores SIP response text for full-text searching, enabling the "SIP responses" filter in CDR view
:* <code>all</code> - Stores both requests and responses (combined)
:* <code>requests,responses</code> - Explicitly stores both requests and responses
 
:'''Warning:''' Enabling SIP history significantly increases database write load and storage size, especially in high-traffic environments. Only enable options you need for your troubleshooting or reporting requirements.
 
:'''Example usage for PUBLISH packets:'''
:* By default, SIP PUBLISH packets are captured but not stored in the database or indexed for GUI filtering
:* To make PUBLISH and other non-call requests searchable, set <code>save_sip_history = requests</code>
:* After processing new calls, the GUI "SIP requests" filter will show all observed request types
:* Restart the voipmonitor service to apply changes
 
:'''Example usage for SIP response text searching:'''
:* The standard "Last SIP Response" filter only searches numeric response codes (e.g., 503, 404)
:* To search full SIP response text (e.g., "Service Unavailable", custom SBC messages), set <code>save_sip_history = responses</code>
:* After processing new calls, the GUI "SIP responses" filter field in the CDR view becomes active
:* You can then search for specific text patterns in SIP response headers
:* Restart the voipmonitor service to apply changes
 
;<code>save_sip_responses = yes</code>
:(Default: no) Alternative option to <code>save_sip_history = responses</code>. Enables storage of SIP response text for searching in the CDR GUI. Use this if you only need response text storage without request history. Enable either this option or <code>save_sip_history = responses</code>, but not both.
 
=== CDR Processing ===
;<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 and update it instead of creating a duplicate row. Use this when multiple probes or sniffer processes capture the same call packets and write CDRs to a shared database. The MySQL user must have UPDATE privileges on the cdr table. Side effect: the final CDR will only be associated with the id_sensor of the sniffer that last processed the call.
;<code>cdr_ignore_response = 302,303,4</code>
:Ignore CDRs based on SIP response codes. Use '0' or '000' to filter unreplied INVITE requests (calls with no response). This setting must be applied on the sniffer that analyzes and stores the packets. It will not work on a mirroring sniffer or probe where <code>packetbuffer_sender=yes</code> is set.
;<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 ===
;<code>custom_headers = Referred-By, Diversion, X-Custom-Header</code>
:(Default: unset) Specifies custom SIP headers to capture and store in the database. Multiple headers are separated by commas. After adding headers to this directive and restarting the sniffer, corresponding database columns are automatically created in the `cdr_next_X` tables. You can then configure the display and filtering behavior in the GUI under [[Settings#CDR_Custom_Headers|Settings > CDR Custom Headers]]. Common use cases include capturing headers like <code>Referred-By</code>, <code>Diversion</code>, or custom correlation identifiers for call tracing.
 
; <code>custom_headers_last_value = yes</code>
:(Default: yes) Use last occurrence of custom header. If set to <code>no</code>, the first occurrence in the SIP message is stored instead.
; <code>custom_headers_max_size = 1024</code>
:(Default: 1024) Maximum custom header size in bytes. Headers longer than this value will be truncated.
; <code>allow_missing_header = no</code>
:(Default: no) Write empty value if header is missing in the first SIP packet of the call.
 
=== Call Recording Control ===
;<code>pauserecordingdtmf = *9</code>
:(Default: unset) If set, RTP recording will be paused when this DTMF sequence is detected in a call.
;<code>pauserecordingdtmf_timeout = 4</code>
:(Default: 4) Timeout between DTMF digits in seconds.
;<code>pauserecordingheader = MyCustomPauseHeader</code>
:(Default: unset) Pauses/unpauses recording based on the presence of a specific SIP header and its value (e.g., `pause` or `unpause`).
;<code>norecord-header = yes</code>
:(Default: no) If any SIP packet in a call contains the `X-VoipMonitor-norecord` header, the entire call record (PCAP and CDR) will be discarded.
;<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 ===
;<code>dtmf2db = no</code>
:(Default: no) Store DTMF to database (SIP INFO and RTP RFC).
;<code>inbanddtmf = no</code>
:(Default: no) Enable in-band DTMF detection. G711 only. CPU intensive.
;<code>silencedetect = no</code>
:(Default: no) Enable silence detection. G711 only. CPU intensive.
;<code>silencethreshold = 512</code>
:(Default: 512) Silence detection threshold.
;<code>clippingdetect = no</code>
:(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 ===
;<code>mosf1 = no</code>
:(Default: yes) Calculate MOS for jitterbuffer_f1 (50ms fixed jitterbuffer). Disabling saves CPU on RTP threads.
;<code>mosf2 = yes</code>
:(Default: yes) Calculate MOS for jitterbuffer_f2 (200ms fixed jitterbuffer). This provides a stable MOS metric.
;<code>mos_adapt = no</code>
:(Default: yes) Calculate MOS for adaptive jitterbuffer (up to 500ms). Disabling provides CPU savings.
 
;''CPU Optimization Note:'' If you experience high CPU load on RTP processing threads during peak call volume, you can reduce CPU consumption by approximately 30% by disabling MOS calculations for f1 and adaptive jitterbuffer while keeping f2 MOS calculation active:
;<code>mosf1 = no</code>
;<code>mos_adapt = no</code>
;This configures VoIPmonitor to compute MOS only for the static 200ms jitter (f2), providing a quality metric with minimal CPU overhead.
 
;<code>mos_g729 = no</code>
:(Default: no) Enable G.729 specific MOS scoring. Max MOS 3.92 for perfect G.729 calls.
;<code>ignorertcpjitter = 0</code>
:(Default: 0) Ignore RTCP jitter values higher than this.
;<code>ignore_mos_degradation_for_contiguous_packet_loss_greater_than = 1024</code>
:(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 ===
;<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 ==
== IPFIX Support ==
IPFIX (IP Flow Information Export) allows receiving RTP QoS data from Oracle/ACME SBCs and other exporters.
;<code>ipfix = yes</code>
:(Default: no) Enable IPFIX collector.
;<code>ipfix_bind_ip = 0.0.0.0</code>
:(Default: 0.0.0.0) Address to bind IPFIX UDP collector.
;<code>ipfix_bind_port = 12345</code>
:UDP port to listen for IPFIX.
;<code>ipfix_qos_fill_rtp_streams = yes</code>
:(Default: no) Save all observed RTP streams into `cdr_rtp`.
;<code>ipfix_qos_fill_codec = yes</code>
:(Default: no) Persist exporter-provided codec value.
;<code>ipfix_qos_fill_jitter = yes</code>
:(Default: no) Persist RTP/RTCP jitter values.
'''Important: Monitoring SIPS/SRTP Calls'''
When using IPFIX to monitor call quality for encrypted SIP (SIPS) and RTP (SRTP) traffic, ensure the TLS port is included in the <code>sipport</code> configuration. For example:


<syntaxhighlight lang="ini">
<syntaxhighlight lang="ini">
# Include both UDP and TLS SIP ports
ipfix = yes
ipfix_bind_port = 12345
ipfix_qos_fill_rtp_streams = yes
# Include TLS port for SIPS/SRTP:
sipport = 5060,5061
sipport = 5060,5061
</syntaxhighlight>
</syntaxhighlight>
This allows VoIPmonitor to properly associate IPFIX QoS data with SIPS endpoints.
'''Data written to CDR:'''
* 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 ==
== SIPREC Support ==


SIPREC enables VoIPmonitor to act as a recording server for SIP proxies like OpenSIPS.
<syntaxhighlight lang="ini">
 
siprec_bind = 0.0.0.0
;<code>siprec_bind = 0.0.0.0</code>
siprec_bind_port = 5099
:IP address to bind SIPREC server. Required to enable SIPREC.
siprec_rtp_min = 10000
 
siprec_rtp_max = 20000
;<code>siprec_bind_port = 5099</code>
</syntaxhighlight>
:Port to listen for SIPREC connections. Required to enable SIPREC.
 
;<code>siprec_rtp_min = 10000</code>
:(Default: 10000) Lower bound of RTP port range.
 
;<code>siprec_rtp_max = 20000</code>
:(Default: 20000) Upper bound of RTP port range.
 
;<code>siprec_rtp_stream_timeout_s = 300</code>
:(Default: 300) RTP stream timeout in seconds.
 
;<code>siprec_rtp_streams_max_threads = 2</code>
:(Default: 2) Maximum RTP reception threads.
 
;<code>siprec_rtp_streams_max_per_thread = 100</code>
:(Default: 100) Maximum streams per thread.


== HEP Support ==
== HEP Support ==


HEP (Homer Encapsulation Protocol) allows receiving SIP traffic mirrored from Kamailio, OpenSIPS, Asterisk, and other SIP proxies.
<syntaxhighlight lang="ini">
 
receiver_mode = yes # Required!
;<code>receiver_mode = yes</code>
hep = yes
:(Default: no) Required to enable the HEP receiver. This directive must be set to <code>yes</code> in the <code>[general]</code> section before the HEP collector will bind to the configured port and accept HEP packets. Without <code>receiver_mode = yes</code>, the sensor will not listen on <code>hep_bind_port</code> even if <code>hep = yes</code> is set. After enabling, verify the port is listening with <code>netstat -an | grep hep_bind_port</code>.
hep_bind_port = 9060
 
hep_kamailio_protocol_id_fix = yes # For Kamailio sources
;<code>hep = yes</code>
</syntaxhighlight>
:(Default: no) Enable HEP collector.
 
;<code>hep_bind_ip = 0.0.0.0</code>
:(Default: 0.0.0.0) Address to bind HEP UDP collector.
 
;<code>hep_bind_port = 9060</code>
:UDP port to listen for HEP packets.
 
;<code>hep_bind_udp = yes</code>
:(Default: yes) Enable UDP binding for the HEP collector. This directive allows the HEP receiver to bind to a UDP port. Set to <code>no</code> only if you need to disable UDP binding for specific network configurations. In most deployments, this should be left at the default <code>yes</code>.
 
;<code>hep_kamailio_protocol_id_fix = yes</code>
:(Default: yes) Workaround for Kamailio protocol ID issues. Enable this when receiving HEP from Kamailio.
 
== Whisper Transcription ==
 
VoIPmonitor supports audio transcription using OpenAI's Whisper model.
 
;<code>audio_transcribe = yes</code>
:(Default: no) Enable audio transcription.
 
;<code>whisper_rest_api_url = http://localhost:9000/asr?output=json&encode=true</code>
: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.
;<code>receiver_mode = yes</code>
:(Default: no) Enables the receiver mode for receiving mirrored traffic. When using Kamailio mirroring or the HEP collector, this directive must be set to <code>yes</code> in the <code>[general]</code> section. Without this setting, the sensor will not bind to the configured receiver port and will not receive traffic, regardless of other configuration settings. Always verify the service is listening on the expected port after enabling this option using <code>netstat -an | grep 5888</code> or <code>ss -ulpn | grep voipmonitor</code>.
'''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).


;<code>ribbonsbc_srcip = 10.0.0.2</code>
= Expert & Debugging Options =
:Ribbon SBC IP (legacy filter).


=== Active Listener (Mode 2) ===
{{Warning|1=Only change these if instructed by support or you are an expert.}}
;<code>ribbonsbc_bind_ip = 0.0.0.0</code>
:Listen address for active mode.


;<code>ribbonsbc_bind_port = 9514</code>
{| class="wikitable"
:Listen port for active mode.
! Parameter !! Default !! Description
 
|-
;<code>ribbonsbc_bind_udp = no</code>
| <code>callslimit</code> || 0 || Max concurrent calls (0=unlimited)
:(Default: no) Enable UDP support. TCP recommended.
|-
 
| <code>skipdefault</code> || no || Ignore all calls unless capture rules match
;<code>ribbonsbc_size_header = yes</code>
|-
:(Default: yes) Expect 2-byte size header before each frame.
| <code>openfile_max</code> || 65535 || Maximum open files
 
|-
;<code>ribbonsbc_strict_check = no</code>
| <code>coredump_filter</code> || 0x7F || Memory segments in coredump
:(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 ==
== Traffic Dumper ==


Save captured traffic to PCAP files with optional filtering.
<syntaxhighlight lang="ini">
 
traffic_dumper_path = /var/spool/voipmonitor/traffic
;<code>traffic_dumper_path = /var/spool/voipmonitor/traffic</code>
traffic_dumper_filter_ip = 192.168.1.100, 10.0.0.0/8
:Path where pcap files will be saved. Setting this enables the traffic dumper.
traffic_dumper_filter_port = 5060, 5061, 10000-20000
 
</syntaxhighlight>
;<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), '''Deprecated and Removed Configuration Options''' (for sniffer version 2025.09.1 and later, removed options include: `vxlan`, `vxlan_port`, `vxlan_skipcrc`, `packet_buffer_total_size`, `udp_reassembly`, `udp_reassembly_max_size`, `sipdefrag`, `sipdefrag_maxpacket`, `defragment_max_size`, `defragment_timeout`, `ignore_sip_parsing_errors`, `sip_auto_clean`, `max_sip_size`, `sip_force_content_length`, `sanity_checks`, `check_sip_header`, `interface_snaplen`; modern replacements include `udp_port_vxlan`, `snaplen`, `udpfrag`, `auto_enable_use_blocks`, `deduplicate`), Database Connection and Performance (MySQL settings, partitioning, queue tuning, cleaning, SSL/TLS, and <code>mysqlloadconfig=yes</code> for loading configuration from database including the critical manager_key from the system table; setting <code>mysqlloadconfig=no</code> prevents loading the manager_key and causes "failed read rsa key" startup errors), Network Interface and Sniffing (interface selection, BPF filters, tunneling protocols including TZSP, L2TP, VXLAN, AudioCodes, IPFIX, HEP, and '''packet deduplication''' and '''RTP association''' with options like `deduplicate`, `auto_enable_use_blocks`, and `deduplicate_ipheader`), Shared Server Optimization (voice breakage and call lag when sniffer shares PBX server, solutions: specify specific interfaces instead of `any`, disable `interfaces_optimize=no`, reduce load with `savertp=header` and `saveaudio=no`), 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 including `mirror_bind_sensor_id_by_sender` for distinguishing sending probes), Storage Management (spooldir, TAR files, pcap saving, compression, and cleaning rules), Call Processing (timeouts, RTP tracking, NAT handling, custom headers, '''call recording control for privacy and opt-out scenarios including <code>pauserecordingdtmf</code> to pause recordings via DTMF sequences during calls, <code>norecord-dtmf</code> to delete recordings, <code>norecord-header</code> for SIP header-based recording suppression, and <code>pauserecordingheader</code> for pause/unpause via SIP headers''' ), '''Audio and Video Packet Saving''' (<code>savertp</code> for audio RTP payload, <code>savertp_video</code> for video RTP streams such as VP8, VP9, and H.264, <code>savertcp</code> for RTCP, <code>saveaudio</code> for audio file extraction, <code>savegraph</code> for call graphs), SIP Method Processing (REGISTER, OPTIONS, SUBSCRIBE, NOTIFY, MESSAGE, and `save_sip_history` for storing ALL SIP requests including PUBLISH, INFO, UPDATE, PRACK, REFER to enable GUI filtering), Audio Analysis (DTMF, silence detection, energy levels, MOS scoring), '''Scan PCAP Directory Mode''' (<code>scanpcapdir</code> for processing pcap files from a directory instead of live capture; useful for monitoring from Windows hosts without SPAN ports using tcpdump to capture and transfer pcaps to VoIPmonitor server), 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, rtp association, wrong call leg, different nic, different vlan, multiple interface, ssl, ssl_ipport, TLS decryption, IPFIX, 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, custom_headers, custom SIP headers, Referred-By, Diversion, CDR custom headers, capture SIP headers, SIP header filtering, shared server, PBX, resource contention, voice breakage, call lag, interfaces_optimize, dedicated threads, specific interfaces, ethtool, RTP engine, save_sip_history, SIP requests filter, PUBLISH, INFO, UPDATE, PRACK, REFER, non-call SIP methods, GUI SIP requests, mysqlloadconfig, manager_key, failed read rsa key, sensor_conf table, system table, pauserecordingdtmf, norecord-dtmf, norecord-header, pauserecordingheader, privacy, opt-out, call recording control, pause recording, stop recording, DTMF control, SIP header control, video, video RTP, video codec, VP8, VP9, H.264, H264, WebRTC video, savertp_video, video capture, recording video, video packet saving, SSRC, Synchronization Source, zero SSRC, allow-zerossrc, missing audio, silence packets, dropped RTP packets, t2_boost, high traffic threading, defrag thread, reassembly thread, MEMORY IS FULL, threading model, CPU bottleneck, 100% CPU, defrag bottleneck, packetbuffer, high throughput, scanpcapdir, scanpcapmethod, directory mode, offline processing, tcpdump, windows host, without span port, no port mirroring, pcap files, remote capture, deprecated options, deprecated configuration, removed options, legacy options, 2025.09.1, upgrade, vxlan, packet_buffer_total_size, udp_reassembly, sipdefrag, defragment, ignore_sip_parsing_errors, sip_auto_clean, max_sip_size, sanity_checks, check_sip_header, interface_snaplen, udp_port_vxlan, cdr_country_code, caller_country, called_country, country flags, CDR country filtering, country lookup, country code detection
'''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 does mysqlloadconfig=no do in voipmonitor.conf?
* What are the most important settings in voipmonitor.conf?
* Why does the sniffer fail to start with "failed read rsa key" error?
* How do I configure the database connection?
* How does mysqlloadconfig affect loading of the manager_key from the database?
* Why does the sniffer fail with "failed read rsa key"?
* What are the most important settings in voipmonitor.conf for a new installation?
* How do I set up distributed client/server architecture?
* How do I configure the database connection for the sniffer?
* What is the difference between packetbuffer_sender = yes and no?
* How do I fix voice breakage and call lag when the VoIPmonitor sniffer runs on the same server as the PBX?
* How do I enable packet deduplication?
* What happens when I use interface = any versus specific interface names?
* How do I decrypt TLS/SRTP traffic?
* How can I reduce CPU load on RTP processing threads during peak call volume?
* How do I disable audio recording while keeping RTP analysis?
* How do I disable MOS calculations for f1 and adaptive jitterbuffer?
* How do I capture custom SIP headers?
* What configuration saves approximately 30% CPU on RTP threads?
* How do I configure IPFIX/SIPREC/HEP receivers?
* How does interfaces_optimize affect performance on shared servers?
* Which options were deprecated in v2025.09.1?
* What should I do if moving the VoIPmonitor sensor to a separate server is not possible?
* How do I fix CPU bottlenecks with t2_boost?
* How does specifying multiple interfaces create dedicated threads?
* How do I process PCAP files with scanpcapdir?
* How do I set up a distributed client/server architecture?
* What is the difference between `packetbuffer_sender = yes` and `no`?
* How do I tune the database for high performance?
* 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 pause call recording during a call using DTMF sequences for opt-out scenarios?
* How do I configure pauserecordingdtmf to allow callers to pause recording by pressing a DTMF sequence?
* What is pauserecordingdtmf_timeout and how does it affect DTMF sequence recognition?
* How do I delete a recording entirely if a DTMF sequence is detected using norecord-dtmf?
* How do I suppress recording based on SIP headers using norecord-header?
* What is the difference between pauserecordingdtmf and norecord-dtmf?
* How do I enable packet deduplication for multiple sensors or interfaces?
* How do I save audio files to a single folder using saveaudio_singlefolder?
* Why are RTP packets not associated with the correct call legs when SIP and RTP are on different NICs or VLANs?
* 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 capture and filter SIP PUBLISH, INFO, UPDATE, or other non-call SIP methods in the GUI?
* What is `save_sip_history = requests` and when should I use it?
* How do I make SIP PUBLISH packets searchable in the GUI "SIP requests" filter?
* How do I configure IPFIX to receive RTP QoS from Oracle SBC?
* 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 configure VoIPmonitor to capture and save video RTP packets from WebRTC calls using VP8, VP9, or H.264 codecs?
* What is savertp_video and how does it differ from savertp?
* How do I enable video RTP packet saving in VoIPmonitor?
* Why are video RTP streams not being saved or captured in my PCAP files?
* What is cdr_country_code and how does it affect country flags in CDR view?
* Why are country flags not showing in the CDR view even though GeoIP is enabled?
* How do I configure VoIPmonitor to display country flags for caller and called numbers?
* What happens if I set cdr_country_code = no in voipmonitor.conf?
* How do I capture custom SIP headers like Referred-By or Diversion in the CDR?
* What is the custom_headers directive and how do I use it?
* How do I configure custom SIP headers for filtering and reporting in the CDR?
* How do I enable DTMF, silence, or clipping detection?
* What is SSRC in RTP and why does VoIPmonitor drop packets with zero SSRC by default?
* How do I fix missing audio or dropped RTP packets during silence periods?
* How do I capture RTP packets with zero SSRC from VoIP gateways or PBX systems?
* What does allow-zerossrc do and when should I enable it in voipmonitor.conf?
* Why are my calls showing missing audio during silence periods and how do I fix it?
* What is t2_boost and when should I use it?
* How do I fix CPU bottlenecks where a single defrag thread runs at 100%?
* What does the error "packetbuffer: MEMORY IS FULL" mean and how do I resolve it?
* How can t2_boost help with high traffic threading bottlenecks?
* How do I monitor VoIP traffic from a Windows host when port mirroring is not available?
* What is scanpcapdir and how do I use it for offline pcap processing?
* How do I configure VoIPmonitor to process pcap files from a directory instead of live capture?
* How can I use tcpdump and scanpcapdir to monitor traffic from Windows without SPAN port?
* Which configuration options were removed in sniffer version 2025.09.1?
* What deprecated options should I remove from voipmonitor.conf when upgrading?
* What are the modern replacements for vxlan, packet_buffer_total_size, and udp_reassembly?
* What options should I remove when upgrading to sensor version 2025.09.1?
* Are vxlan, vxlan_port, and vxlan_skipcrc still supported in the latest sniffer?
* What should I use instead of the deprecated sipdefrag and defragment_max_size options?
* How do I replace deprecated max_sip_size and interface_snaplen options?
* What deprecated SIP processing options are no longer needed in version 2025.09.1?

Revision as of 16:50, 8 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

Call Processing

Timeouts

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

Call Merging

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

See Merging_or_correlating_multiple_call_legs for detailed documentation.

Recording Control

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

Custom Headers

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

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

SIP History

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

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

RTP Processing

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

CPU optimization (saves ~30%): 

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

Audio Analysis

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

See Silence_detection for detailed documentation.

NAT Handling

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

Protocol Support

SIP REGISTER/OPTIONS/SUBSCRIBE

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

See Register for detailed REGISTER documentation.

Other Protocols

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

Advanced Protocol Support

IPFIX Support

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

SIPREC Support

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

HEP Support

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

Kamailio Mirroring

receiver_mode = yes  # Required!
kamailio_port = 5888

Ribbon SBC Mirroring

ribbonsbc = yes
ribbonsbc_bind_ip = 0.0.0.0
ribbonsbc_bind_port = 9514

Whisper Transcription

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

See Whisper for detailed transcription documentation.

Expert & Debugging Options

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

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

Traffic Dumper

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

AI Summary for RAG

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

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

Key Questions:

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