Sniffer configuration

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.

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:

Installation Guide - How to install the sniffer
Distributed Architecture - Client/server deployment details
Troubleshooting - Common issues and solutions
Scaling Guide - Performance tuning for high traffic
Data Cleaning - Retention and cleanup configuration

General & Core Settings

Time and Sensor Identification

id_sensor = 1: (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.

utc = yes: (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.

timezone = /usr/share/zoneinfo/UTC: (Default: system timezone) Overrides the system's default timezone by specifying a path to a valid zoneinfo file. Use this only if you need the sensor to operate in a timezone different from the server it's running on.

Process Management

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

watchdog_run_command = systemctl restart voipmonitor: (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

mysqlhost = localhost: IP address or hostname of the MySQL/MariaDB server.
mysqlsocket = /var/run/mysqld/mysqld.sock: Path to the MySQL socket file for local connections (often faster than TCP).
mysqlport = 3306: TCP port of the database server.
mysqlusername = root: Username for the database connection.
mysqlpassword =: Password for the database connection.
mysqldb = voipmonitor: The name of the database to use. It will be created automatically if it doesn't exist.
mysql_connect_timeout = 60: (Default: 60) Timeout in seconds for establishing a connection to the database.
mysql_client_compress = no: (Default: no) Enables compression for the MySQL connection. Only use this if the database is on a remote, slow network link.
mysql_reconnect = yes: (Default: no) Enables automatic reconnection to the database if the connection is lost.

Database SSL/TLS

mysqlsslkey = /etc/ssl/client-key.pem: Path to the client's SSL private key file.
mysqlsslcert = /etc/ssl/client-cert.pem: Path to the client's SSL certificate file.
mysqlsslcacert = /etc/ssl/ca-cert.pem: Path to the Certificate Authority (CA) certificate file.
mysqlsslcapath = /etc/ssl/capath: Directory containing CA certificates.
mysqlsslciphers =: List of allowed SSL ciphers.

Performance & Schema

query_cache = yes: (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 no, 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.
quick_save_cdr = no: (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.
cdr_partition = yes: (Default: yes) Enables partitioning for large tables (like `cdr`) by day. This is essential for performance and data management on any production system.
cdr_partition_by_hours = no: (Default: no) For extreme high-traffic environments (>= 15,000 CPS), this creates partitions per hour instead of per day to further improve performance.
disable_partition_operations = yes: (Default: no) Disables automatic partition creation. Useful when multiple sensors write to a single database and only one should manage partitions.
disable_dbupgradecheck = yes: (Default: no) If set to `yes`, the sniffer will not check for and apply database schema updates on startup.
mysqlloadconfig = yes: (Default: yes) Allows loading additional configuration parameters dynamically from the `sensor_conf` database table.
mysqlcompress_type = ...: (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.
mysql_enable_set_id = yes: (Default: no) In very high-traffic client/server deployments, this allows the central server to generate CDR IDs, which can improve batch insert performance.
cdr_force_primary_index_in_all_tables = no: (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.
disable_cdr_fields_rtp = no: (Default: no) Disables all RTP-related statistics columns in the CDR table to save space.
sqlcallend = yes: (Default: yes) Enables storing `cdr.callend` (calldate + duration). Disable only if the column is missing.

SQL Queue Tuning

mysqlstore_concat_limit = 400: (Default: 400) Sets the global number of SQL statements to batch together before sending to the database.
mysqlstore_max_threads_cdr = 2: (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.
server_sql_queue_limit = 1000000: (Default: 1000000) Limits the SQL queue size on the server side in client/server deployments. Set to 0 to disable.
server_sql_concat_limit = 5000: (Default: 1000) Number of queries to batch before confirming receipt in client/server mode.

Database Cleaning

cleandatabase = 0: (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.
cleandatabase_cdr = 0: (Default: 0, disabled) Specific retention period for `cdr` and `message` tables.
cleandatabase_rtp_stat = 2: (Default: 2) Retention period in days for detailed RTP statistics.
cleandatabase_register_failed = 0: (Default: 0) Retention for `register_failed` table.
cleandatabase_register_state = 0: (Default: 0) Retention for `register_state` table.
cleandatabase_sip_msg = 0: (Default: 0) Retention for `sip_msg` table (OPTIONS/SUBSCRIBE/NOTIFY).
cleandatabase_ss7 = 0: (Default: 0) Retention for `ss7` table.
cleandatabase_cdr_rtp_energylevels = 0: (Default: 0) Retention for energy levels table.
partition_operations_enable_fromto = 1-5: (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.
cleandatabase_size = 500000: (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.

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

SQL Error Logging

sql_log_all_errors = no: (Default: no) Logs all SQL errors to syslog.
sql_errors_log_file = /path/to/log: (Default: unset) Redirects SQL error logging to a specific file.
sql_errors_skip = 1054,1136: (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

interface = eth0: 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.
promisc = yes: (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`.
interfaces_optimize = yes: (Default: yes) Allows voipmonitor to automatically tune NIC settings like ring buffers and coalescing using `ethtool`.
eth_max_channels = 0: (Default: 0) Sets number of NIC interrupt queues. 0 means no change.
filter = udp or (vlan and udp): (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

# Exclude internal networks from capturing
filter = not net 192.168.0.0/16 and not net 10.0.0.0/8

Example: Capture only UDP SIP traffic

filter = udp port 5060

When modifying the `filter` setting, you must restart the sniffer service for changes to take effect: `systemctl restart voipmonitor`.

interface_ip_filter = 192.168.0.0/24: (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

# Only process packets from/to these networks
interface_ip_filter = 192.168.0.0/24
interface_ip_filter = 10.0.0.0/8

snaplen = 3200: (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

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.

Symptoms:

Audio breakage (jitter, packet loss)
Call lag or delay
Issues resolve when the sniffer is stopped

Solution 1: Specify Specific Interfaces Instead of using `interface = any`, specify a comma-separated list of the exact network interfaces that handle VoIP traffic:

# Instead of:
# interface = any

# Use specific interfaces:
interface = ens192,ens224

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:

# Disable automatic tuning of NIC settings
interfaces_optimize = no

Note: This option requires the `ethtool` utility to be installed on the system.

Solution 3: Reduce Sniffer Load For immediate relief, configure the sniffer to reduce CPU consumption:

# Save only RTP headers (metadata only, no audio payload)
savertp = header

# Disable audio transcoding (very CPU intensive)
saveaudio = no

Long-term Recommendation: 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.

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.

High-Traffic Parallel Capture

For environments with very high packet rates (>2.2M pps), you can split traffic across multiple processing threads:

interface_libpcap_filter = eth0 : port 5060: (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:

# Split SIP and non-SIP traffic into separate processing threads
interface_libpcap_filter = eth0 : port 5060
interface_libpcap_filter = eth0 : not port 5060

Multiple Sensor Instances on One Server

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.

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.

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.

= Memory Allocation

max_buffer_mem = 1000: (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.

= Database Thread Throttling

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:

mysqlstore_max_threads_cdr = 1
(Default: 2) Set to 1 in multi-instance deployments to reduce thread overhead.
mysqlstore_max_threads_message = 1
(Default: 2) Limits parallel threads for storing MESSAGE records.
mysqlstore_max_threads_register = 1
(Default: 2) Limits parallel threads for storing REGISTER data.
mysqlstore_max_threads_http = 1
(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

# Instance 1 Configuration (/etc/voipmonitor/instance1.conf)
[general]
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

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.

= Troubleshooting High CPU After Upgrade

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
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: Client/Server mode for an alternative to multi-instance deployments on a single host.

Tunneling Protocol Support

VoIPmonitor can decode various tunneling protocols. To enable listening, uncomment and configure the relevant port.

udp_port_tzsp = 37008: (Default: 37008) Mikrotik TZSP protocol.
udp_port_l2tp = 1701: (Default: 1701) L2TP tunneling.
udp_port_vxlan = 4789: (Default: 4789) VXLAN, common in AWS and cloud environments.
udp_port_hperm = 7932: (Default: 7932) HP ERM protocol.
audiocodes = yes: (Default: no) Enables AudioCodes proprietary tunnel.
udp_port_audiocodes = 925: Port for AudioCodes mirroring.
audiocodes_rtp = yes: Enable AudioCodes RTP processing. Options: no, yes, only, only_for_audiocodes_sip.
ipfix = yes: (Default: no) Enables IPFIX, used by Oracle/ACME SBCs. See IPFIX Support section.
hep = yes: (Default: no) Enables Homer Encapsulation Protocol. See HEP Support section.
kamailio_port = 5888: (Default: unset) Enables mirroring from Kamailio's `siptrace` module.
ribbonsbc = yes: (Default: no) Enables Ribbon SBC mirroring. See Ribbon SBC Mirroring section.
icmp_process_data = no: (Default: no) Extract SIP data from ICMP type 3 messages.

Packet Deduplication

When traffic is received from multiple sources or mirrored from multiple points, the same packet may arrive more than once. The deduplication feature identifies and discards duplicate packets based on checksum comparison.

Typical configuration for deduplication:

# Enable packet deduplication. Uses checksum to identify
# and discard duplicate packets. This is CPU intensive.
deduplicate = yes

# 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.
# This is useful when the same packet arrives from different
# network paths with different TTL or other IP header fields.
deduplicate_ipheader = ip_only

deduplicate = yes: (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.

use_block = yes: (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.

auto_enable_use_blocks = yes: (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.

deduplicate_ipheader = ip_only

(Default: yes, meaning full IP header) Controls how the IP header is used in the deduplication checksum:

yes (default): Include the full IP header in the checksum
ip_only: 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.
no: Exclude the IP header entirely from the checksum

deduplicate_ipheader_ignore_ttl = yes: (Default: yes) Ignore the TTL (Time To Live) field in the IP header when comparing packets. This prevents false negatives when the same packet arrives via different network hops.

deduplicate_udpheader_ignore_checksum = yes: (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

scanpcapdir = /dev/shm/voipmonitor: (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`.
scanpcapmethod = newfile: (Default: newfile) Method for detecting new files. Options: newfile, rename.

SIP Send (Third-Party Forwarding)

sip_send = 192.168.0.2:1555: (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.
sip_send_udp = yes: (Default: no) Use UDP instead of TCP for sip_send.
sip_send_before_packetbuffer = yes: (Default: no) Send packets immediately without buffering.

SIP Port & TCP Configuration

SIP Port Settings

sipport = 5060: (Default: 5060) Specifies the SIP ports that VoIPmonitor will listen to. Multiple ports can be specified: `sipport = 5060,5061,5062,5070-5080`.
cdr_sipport = yes: (Default: yes) Store SIP source and destination ports in the database.
cdr_rtpport = yes: (Default: yes) Store RTP destination port in the database.
cdr_rtpsrcport = no: (Default: no) Store RTP source port in the database.

TCP Reassembly

sip_tcp_reassembly_ext = yes: (Default: yes) Enable TCP reassembly for SIP over TCP.
sip_tcp_reassembly_stream_max_attempts = 50: (Default: 50) Maximum TCP reassembly attempts.
sip_tcp_reassembly_ext_link_timeout = 10: (Default: 10) TCP reassembly link timeout in seconds.
sip_tcp_reassembly_ext_quick_mod = no: (Default: no) Experimental quick mode for high traffic. Options: no, yes, ext, comb_ext.

SIP Packet Limits

max_sip_packets_in_call = 2000: (Default: 2000) Maximum SIP packets per call.
max_invite_packets_in_call = 10000: (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.

ssl = yes: (Default: no) Enable TLS/SSL decryption for SIP.

ssl_ipport = 10.0.0.1 : 5061 /path/to/your.key: (Default: unset) Specify IP:port and private key for decryption. Multiple keys can be separated by commas.

ssl_ipport = 10.0.0.0/24 : 5061 /path/to/your.key,/path/to/other.key: Example with subnet and multiple keys.

ssl_ipport_reverse_enable = yes: (Default: no) Enable reverse detection logic for ssl_ipport.

ssl_store_sessions_expiration_hours = 12: (Default: 12) SSL sessions expire after this many hours.

ssl_sessionkey_udp = yes: (Default: no) Enable parsing of session keys sent via UDP (keylogger support).

ssl_sessionkey_udp_port = 1234: UDP port for receiving session keys.

ssl_store_sessions = persistent: (Default: persistent) How to store SSL keys: 'persistent' (InnoDB) or 'memory'.

ssl_tls_12_sessionkey_mode = dssl: (Default: dssl) Decryption library: 'dssl' or 'wireshark'.

ssl_ignore_error_invalid_mac = yes: (Default: yes) Ignore SSL/TLS packets with invalid MAC.

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.

srtp_rtp = no: (Default: no) Decrypt and store RTP data in PCAPs. By default, only RTCP is decrypted.

srtp_rtcp = yes: (Default: yes) Decrypt RTCP streams.

srtp_rtp_dtmf = no: (Default: no) Decrypt only RTP DTMF packets.

srtp_rtp_dtls = yes: (Default: yes) Enable DTLS decryption. Requires keylogger or session keys.

ssl_dtls_queue = yes: (Default: no) Enable DTLS packet queue to prevent packet loss during decryption.

ssl_dtls_queue_expiration = 10: (Default: 10) DTLS queue expiration time in seconds.

srtp_rtp_local_instances = no: (Default: no) Create separate decryption instance per RTP stream.

ssl_dtls_queue_keep = no: (Default: no) Keep DTLS packets in queue after first successful use.

ssl_sessionkey_keep = no: (Default: no) Keep keylogger keys until expiration instead of discarding after first use.

ssl_dtls_handshake_safe = no: (Default: no) DTLS handling approach: no (queue), only (unified), yes (both, queue priority), ext (both, unified priority).

ssl_dtls_boost = no

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

remoteparty_caller = calling: (Default: unset) Update caller number from Remote-Party-ID header. Use 'calling' or 'called' based on the party attribute.

remoteparty_called = called: (Default: unset) Update called number from Remote-Party-ID header.

passertedidentity = no: (Default: no) Use P-Asserted-Identity header for caller info.

ppreferredidentity = no: (Default: no) Use P-Preferred-Identity header for caller info.

remotepartypriority = no: (Default: no) Give Remote-Party-ID priority over P-Asserted-Identity and P-Preferred-Identity.

callernum_numberonly = yes: (Default: yes) Parse only the number part from identity headers.

destination_number_mode = 1: (Default: 1) Source for destination number: 1 = To header, 2 = INVITE URI.

sipoverlap = yes: (Default: yes) Update destination number from subsequent INVITEs (overlap dialing support per RFC 3578).

last_dest_number = no: (Default: no) Always take destination from latest INVITE regardless of source IP.

update_dstnum_onanswer = no: (Default: no) Update destination number when callee answers (useful for hunt groups).

Performance & Threading

Core Threading Model

threading_expanded = yes: (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.
preprocess_rtp_threads = 2: (Default: 2) The initial number of threads for RTP preprocessing. The system will auto-scale from here.
preprocess_rtp_threads_max = 5: (Default: unlimited) Maximum RTP preprocessing threads.
pre_process_packets_next_thread = 4: For high network throughput (>= 5Gbit), set to 4.
pre_process_packets_next_thread_max = 4: Hard limit is 4 even if value is higher.
destroy_calls_in_storing_cdr = yes: (Default: no) Offloads the process of freeing call memory to a separate thread. Useful in very high-traffic scenarios (> 50,000 concurrent calls).
rtpthreads_start = 20: (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.
rtpthreads = 0: (Default: CPU count) Number of threads for RTP packet processing. 0 disables threading.

Thread Scheduling & Priority

sched_pol_auto = prio -20: (Default: `prio -20`) Automatically elevates the priority (lowers the `nice` value) of critical threads if the system comes under load.
sched_pol_auto_heap_limit = 1: (Default: 1) Heap growth percentage threshold for priority elevation.
sched_pol_auto_cpu_limit = 45: (Default: 45) CPU usage threshold for priority elevation.

Manual thread priority settings (alternative to auto):

sched_pol_interface = prio -20
sched_pol_pb = prio -20
sched_pol_sip = prio -20
sched_pol_rtp_prep = prio -20
sched_pol_rtp_read = prio -20

NUMA & Memory

numa_balancing_set = autodisable: (Default: autodisable) Manages the Linux kernel's NUMA balancing feature. The default setting will automatically disable NUMA balancing if it detects high overhead.
hugepages_max = 80000: (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

ringbuffer = 50: (Default: 50) Ringbuffer size in MB. Recommended >= 500 for >100 Mbit traffic. Max 2000.
packetbuffer_enable = yes: (Default: yes) Enable packet buffer cache.
packetbuffer_compress = no: (Default: no) Enable packet buffer compression.
max_buffer_mem = 2000: (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. Ensure sufficient RAM is available.
memory_purge_interval = 30: (Default: 30) Memory purge interval in seconds.
memory_purge_if_release_gt = 500: (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 packetbuffer_sender parameter:

Key differences:

Local Processing (packetbuffer_sender=no): Low network usage, PCAP files stored on remote sensor, higher CPU usage on sensor
Packet Mirroring (packetbuffer_sender=yes): Higher network usage, all data centralized, minimal CPU usage on sensor

Modern Client/Server Model (Recommended)

server_bind = 0.0.0.0: The IP address the central sensor will listen on for connections from remote clients.
server_bind_port = 60024: (Default: 60024) Port for client connections.
server_destination = 10.0.0.1: 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`.
server_destination_port = 60024: (Default: 60024) Port of the central server.
server_password =: A shared password to authenticate clients and servers.
packetbuffer_sender = no: (Default: no) The operational mode. `no` for local processing (low network usage), `yes` for packet mirroring (low remote CPU usage).
packetbuffer_file_path = /path/to/directory: 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)

Important: packetbuffer_sender Controls Packet Transmission
Critical Behavior:	When `packetbuffer_sender = yes`, all packets are transmitted (forwarded to central server or sent via packet buffer), which includes RTP packets regardless of your `savertp` setting. This option always transmits full packet streams for processing.
If RTP is recorded despite `savertp = no`:	Check for `packetbuffer_sender = yes` in your configuration. This setting will cause RTP packets to be saved because the raw packet stream is being transmitted. Set `packetbuffer_sender = no` or comment out the line to disable packet transmission.

server_type_compress = zstd: (Default: zstd) Compression algorithm for the client/server channel. Options: zstd, gzip, lzo, none.
receiver_check_id_sensor = yes: (Default: yes) Differentiate packets by originating sensor. Set to 'no' for multipath routing scenarios.

Time Synchronization

mirror_connect_maximum_time_diff_s = 2: (Default: 2) Maximum time difference for mirror connections.
client_server_connect_maximum_time_diff_s = 2: (Default: 2) Maximum time difference for client/server connections.
receive_packetbuffer_maximum_time_diff_s = 30: (Default: 30) Maximum time difference for packet buffer reception.

Legacy Mirroring Model

mirror_bind_ip = 0.0.0.0: The IP the receiver sensor listens on for the unencrypted, legacy mirroring protocol.
mirror_bind_port =: Port for legacy mirroring.
mirror_bind_sensor_id_by_sender = yes: (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.
mirror_destination_ip = 10.0.0.1: The IP of the receiver sensor that the sender should stream packets to.
mirror_destination_port =: Port for mirror destination.
mirror_require_confirmation = yes: (Default: yes) Require packet confirmation. Disable for higher throughput.
mirror_use_checksum = yes: (Default: yes) Enable block-level checksums.
pcap_queue_dequeu_window_length = 2000: (Default: 2000) Window length in ms for sorting packets from multiple mirrors.

Storage & File Management (Spooldir)

Location and Permissions

spooldir = /var/spool/voipmonitor: The primary directory for storing all captured data (PCAP, GRAPH, AUDIO files).
spooldir_rtp =: Separate directory for RTP files.
spooldir_graph =: Separate directory for graph files.
spooldir_audio =: Separate directory for audio files.
spooldir_2 = /var/spool/voipmonitor2: Secondary storage directory with separate autoclean setup.
spooldir_file_permission = 0666
spooldir_dir_permission = 0777: Allows setting specific filesystem permissions for newly created files and directories.
spooldir_owner = root
spooldir_group = root: Owner and group for created files.
spooldir_by_sensor = no: (Default: no) If enabled, creates subdirectories within the spooldir for each `id_sensor`.
spooldir_by_sensorname = yes: Organize by sensor name instead of ID.
name_sensor = sensor1: Sensor name for directory organization.
cachedir = /dev/shm/voipmonitor: Cache directory for temporary storage. Use RAM or SSD for better performance.

PCAP/TAR Storage Strategy

tar = yes: (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.
tar_maxthreads = 8: (Default: 8) Maximum threads for tar compression.
tar_compress_sip = zstd: (Default: zstd) SIP TAR compression. Options: none, gzip, zstd, lzma.
tar_sip_level_zstd = 1: (Default: 1) Compression level for SIP TAR.
tar_compress_rtp = no: (Default: no) RTP TAR compression. Individual RTP pcaps are compressed with lzo by default.
tar_compress_graph = zstd: (Default: zstd) Graph TAR compression.
tar_graph_level_zstd = 1: (Default: 1) Compression level for graph TAR.
tar_move = yes: (Default: no) Move tar files to another directory after closing. Options: no, yes (move and delete), copy.
tar_move_destination_path = /mnt/nfs/storage: Destination for tar move.
tar_move_max_threads = 2: (Default: 2) Threads for moving tar files.

Saving Options

savesip = yes: Enables saving of SIP packets.
savertp = yes: Enables saving of RTP packets. Set to `header` to save only RTP headers, not the audio payload.
savertp_video = no: (Default: no) Save video RTP packets. Options: no, yes, header, cdr_only.
savertcp = yes: Enables saving of RTCP (RTP Control Protocol) packets.
savegraph = yes: Enables saving of call graph data.
null_rtppayload = no: (Default: no) Zero out all RTP payload data.
maxpcapsize = 500: (Default: unset) Maximum pcap file size in MB.

PCAP Compression

pcap_dump_zip = yes: (Default: yes) Enable file compression for pcap files.
pcap_dump_zip_sip = zstd: SIP compression. Options: no, zstd, gzip, lzo, lz4.
pcap_dump_zip_rtp = lzo: (Default: lzo) RTP compression.
pcap_dump_zip_graph = no: Graph compression.
pcap_dump_ziplevel = 3: (Default: 3) Compression level.
pcap_dump_writethreads = 1: (Default: 1) Initial compression threads. Auto-scales.
pcap_dump_writethreads_max = 32: (Default: 32) Maximum compression threads.
pcap_dump_asyncwrite = yes: (Default: yes) Enable asynchronous writing.
pcap_dump_bufflength = 8184: (Default: 8184) Buffer size in bytes.

Spool Cleaning

cleanspool = yes: (Default: yes) Enables the automatic cleaning process for the spool directory.
cleanspool_enable_fromto = 1-5: (Default: 0-24) Restrict cleaning to specific hours.
maxpoolsize = 102400: (Default: 100 GB) The primary retention setting. Deletes the oldest data hourly until the specified size limit is reached (in MB).
maxpooldays = 30: (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.
autocleanspoolminpercent = 1: (Default: 1%) Emergency cleaning trigger percentage.
autocleanmingb = 5: (Default: 5 GB) Emergency cleaning trigger in GB.
maxpool_clean_obsolete = yes: (Default: no) Clean files not in the index.

Audio File Generation

saveaudio = wav: (Default: no) If enabled, voipmonitor will generate an audio file (`.wav`, `.ogg`, or `.mp3`) for each call in addition to the PCAP file. Options: wav, ogg, mp3, or yes. Using yes will default to WAV format. Note: This is generally not necessary and adds significant CPU/I/O load.
save_audiograph = yes: (Default: no) Enables generation of audio graph files (waveform and spectrogram images) stored in the spooldir/AUDIOGRAPH directory. These graphs visualize audio quality (MOS, jitter, packet loss) without requiring audio playback. If savertp = yes, audio graph files can be generated directly from the PCAP file without needing to enable this option. For auto-cleaning configuration, see maxpoolaudiographsize and maxpoolaudiographdays.
saveaudio_singlefolder = /var/spool/voipmonitor/audio: (Default: unset) Store all generated audio files in a single flat directory instead of the default spooldir structure. This option saves audio files in the specified directory with subdirectories based on date (e.g., /var/spool/voipmonitor/audio/2025/01/05/). Prerequisite: saveaudio must be enabled (set to wav, ogg, mp3, or yes).
saveaudio_afterconnect = no: (Default: no) Store audio only for connected calls.
saveaudio_from_first_invite = yes: (Default: yes) Generate silence from first INVITE to match SIP signalization length.
saveaudio_stereo = yes: (Default: yes) Caller in left channel, called in right channel.
mp3_quality = 5: (Default: 5) MP3 quality (0-9, 9 is worst).
ogg_quality = 0.4: (Default: 0.4) OGG quality setting.
audioqueue_threads_max = 10: (Default: 10) Maximum audio processing threads.
curl_hook_wav = http://127.0.0.1:8080/your-script-path: Webhook URL called for each audio file.

Call Processing & Protocol Logic

Call Identification & Merging

remoteparty_caller = calling, `passertedidentity = no`, etc.: A group of options that control which SIP headers are used to determine the caller/callee information. See Caller/Called Identity Configuration.
sipoverlap = yes: (Default: yes) Allows the destination number to be updated from subsequent INVITEs within the same dialog, necessary for overlap dialing.
matchheader = in-reply-to: Uses the specified SIP header to link different call legs into a single related call in the GUI.
callidmerge_header = Parent-Call-ID: A more advanced method to merge call legs based on a shared identifier in a custom header.
callidmerge_secret = yourSecretString: XOR secret for encrypted Call-ID merging header.
call_id_alternative = Session-ID,Join: Alternative unique identifiers for call merging (e.g., Cisco CUCM).
cdrproxy = yes: (Default: yes) Track all proxy IPs in `cdr_proxy` table.

Call Timeouts & Termination

absolute_timeout = 14400: (Default: 4 hours) Forcefully ends any call that lasts longer than this value to prevent runaway processes. Sets `cdr.bye = 102`.
rtptimeout = 300: (Default: 5 minutes) Closes a call if no RTP or RTCP packets have been received for this duration.
sipwithoutrtptimeout = 3600: (Default: 1 hour) Closes a SIP call that has no associated RTP stream after this duration.
bye_timeout = 1200: (Default: 1200) Timeout in seconds after BYE message.
bye_confirmed_timeout = 600: (Default: 600) Timeout after confirmed BYE.
onewaytimeout = 15: (Default: 15) Ends call if no reply from other side. Sets `cdr.bye = 101`.
ignore_rtp_after_response = 408;480;486;487;481;600;503: (Default: as shown) A list of SIP final response codes after which the sniffer should stop looking for RTP for that call.
ignore_rtp_after_bye = no: (Default: no) Stop RTP processing after BYE.
ignore_rtp_after_bye_confirmed = yes: (Default: yes) Stop RTP processing after confirmed BYE.
ignore_rtp_after_cancel_confirmed = yes: (Default: yes) Stop RTP processing after confirmed CANCEL.
redirect_response_300_timeout = 300: (Default: 300) Timeout for SIP 300 redirect.
get_reason_from_bye_cancel = yes: (Default: yes) Fetch Q.850 Reason header from BYE/CANCEL.
ignore_duration_after_bye_confirmed = yes: (Default: yes) Set duration based on confirmed BYE.
detect_alone_bye = no: (Default: no) Flag CDR if BYE is alone in dialog. Warning: Can cause high DB load.

RTP Processing

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

mosmin_f2 = yes: (Default: yes) Calculate mos_min_mult10 only from f2 jitter simulator.

RTP Tracking & SDP

sdp_multiplication = 3

(Default: 3) How many calls can share same IP:port. 0 = only newest call.

disable_process_sdp = no

(Default: no) Disable SDP processing. Only for very high CPS (>1000).

rtp_check_both_sides_by_sdp = no

(Default: no) Eliminate RTP duplication by checking source IP:port. Options:

no: Disabled (default)
yes: Verify both sides per SDP
keep_rtp_packets: Same as 'yes' but store unverified packets for debugging
strict: Allow unverified packets until first verified packet arrives
very_strict: No unverified packets allowed at any time

ignore_rtp_after_auth_failed = yes: (Default: yes) Close RTP ports on authentication failure.
disable_rtp_seq_probation = no: (Default: no) Disable RFC 3550 sequence validation.
allow-zerossrc = no: (Default: no) Allow RTP packets with zero SSRC.
check_diff_ssrc_on_same_ip_port = yes: (Default: yes) Check for different SSRC on same IP:port.
save_sdp_ipport = yes: (Default: yes) Store SDP IP/port in `cdr_sdp` table.
rtpfromsdp_onlysip = no: (Default: no) Only use RTP streams with same IP as SIP header.
rtpip_find_endpoints = yes: (Default: yes) Determine actual RTP endpoints (not proxies).

SRTP (Encrypted Media)

See SRTP Configuration section above.

NAT Handling

natalias = 1.1.1.1 10.0.0.3: 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.
sdp_reverse_ipport = no: (Default: no) Enable reverse IP:port sniffing for NAT scenarios. Use with caution.
sdp_ignore_ip = 192.168.0.1: Ignore RTP streams from specific IPs.
sdp_ignore_ip_port = 192.168.0.1:100: Ignore RTP streams from specific IP:port.

SIP REGISTER, OPTIONS, SUBSCRIBE, NOTIFY

sip-register = no: (Default: no) Enables the processing and storage of SIP `REGISTER` messages. Options: yes, nodb, no.
save-sip-register = no: (Default: no) Save REGISTER messages to disk.
sip-register-timeout = 5: (Default: 5) Timeout in seconds for REGISTER reply.
sip-register-active-nologbin = yes: (Default: yes) Skip binary logging for REGISTER active table.
sip-register-max-registers = 4: (Default: 4) Max request packets before terminating register session.
sip-register-max-messages = 20: (Default: 20) Max total packets before terminating register session.
sip-register-state-timeout = 600: (Default: 600) Interval between saving same states.
sip-register-state-compare-digest_ua = no: (Default: no) When enabled with yes, 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 sip-register-state-compare-ua = yes 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.
sip-options = no: (Default: no) Enables the processing of SIP `OPTIONS` messages.
save-sip-options = no: (Default: no) Save OPTIONS to disk.
sip-subscribe = no: (Default: no) Enable SUBSCRIBE processing.
sip-notify = no: (Default: no) Enable NOTIFY processing.
sip-message = yes: (Default: yes) Enables processing for SIP `MESSAGE` requests.

SIP History for Requests

save_sip_history = no: (Default: no) Enables storage of ALL SIP requests (not just call-related SIP signaling) in the database. When set to requests, all SIP request methods observed on the network are logged to the sip_request table, including methods not typically associated with calls like PUBLISH, INFO, UPDATE, PRACK, REFER, and others. This enables searching and filtering these requests in the GUI using the "SIP requests" filter. Options: no, requests.

Warning: Enabling this option significantly increases database write load and storage size, especially in high-traffic environments. Only enable it if you need to store and search non-call SIP requests.

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 save_sip_history = requests
After processing new calls, the GUI "SIP requests" filter will show all observed request types
Restart the voipmonitor service to apply changes

CDR Processing

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

Custom Headers

custom_headers = Referred-By, Diversion, X-Custom-Header: (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. Common use cases include capturing headers like Referred-By, Diversion, or custom correlation identifiers for call tracing.

custom_headers_last_value = yes: (Default: yes) Use last occurrence of custom header. If set to no, the first occurrence in the SIP message is stored instead.
custom_headers_max_size = 1024: (Default: 1024) Maximum custom header size in bytes. Headers longer than this value will be truncated.
allow_missing_header = no: (Default: no) Write empty value if header is missing in the first SIP packet of the call.

Call Recording Control

pauserecordingdtmf = *9: (Default: unset) If set, RTP recording will be paused when this DTMF sequence is detected in a call.
pauserecordingdtmf_timeout = 4: (Default: 4) Timeout between DTMF digits in seconds.
pauserecordingheader = MyCustomPauseHeader: (Default: unset) Pauses/unpauses recording based on the presence of a specific SIP header and its value (e.g., `pause` or `unpause`).
norecord-header = yes: (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.
norecord-dtmf = yes: (Default: no) Delete recording if DTMF sequence "*0" is detected.
182queuedpauserecording = no: (Default: no) Pause on "182 Queued avaya-cm-data".

Audio Analysis

dtmf2db = no: (Default: no) Store DTMF to database (SIP INFO and RTP RFC).
inbanddtmf = no: (Default: no) Enable in-band DTMF detection. G711 only. CPU intensive.
silencedetect = no: (Default: no) Enable silence detection. G711 only. CPU intensive.
silencethreshold = 512: (Default: 512) Silence detection threshold.
clippingdetect = no: (Default: no) Enable clipping detection. G711 only.
fasdetect = no: (Default: no) FAS (False Answer Supervision) detection based on ring detection after 200 OK.
save-energylevels = no: (Default: no) Store average 16-bit energy levels for each RTP packet in `cdr_rtp_energylevels` table.
energylevelheader = X-energlvl: Only save energy levels for calls with this header.
sipalg_detect = no: (Default: no) Detect SIP-ALG usage on routers/firewalls.

MOS Scoring

mos_g729 = no: (Default: no) Enable G.729 specific MOS scoring. Max MOS 3.92 for perfect G.729 calls.
ignorertcpjitter = 0: (Default: 0) Ignore RTCP jitter values higher than this.
ignore_mos_degradation_for_contiguous_packet_loss_greater_than = 1024: (Default: 1024) Don't count consecutive packet loss above this threshold.
ignore_mos_degradation_in_rtp_pause_without_seq_gap = 1000: (Default: 1000) Don't lower MOS for RTP gaps without sequence gaps.
plcdisable = no: (Default: no) Disable Packet Loss Concealment.

PESQ MOS

mos_lqo = no: (Default: no) Enable ITU-T P.862 PESQ scoring. Requires licensed pesq binary.
mos_lqo_bin = pesq: Path to PESQ binary.
mos_lqo_ref = /path/to/reference.wav: Reference audio file for PESQ.

Other Protocols

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

IPFIX Support

IPFIX (IP Flow Information Export) allows receiving RTP QoS data from Oracle/ACME SBCs and other exporters.

ipfix = yes: (Default: no) Enable IPFIX collector.

ipfix_bind_ip = 0.0.0.0: (Default: 0.0.0.0) Address to bind IPFIX UDP collector.

ipfix_bind_port = 12345: UDP port to listen for IPFIX.

ipfix_qos_fill_rtp_streams = yes: (Default: no) Save all observed RTP streams into `cdr_rtp`.

ipfix_qos_fill_codec = yes: (Default: no) Persist exporter-provided codec value.

ipfix_qos_fill_jitter = yes: (Default: no) Persist RTP/RTCP jitter values.

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 enables VoIPmonitor to act as a recording server for SIP proxies like OpenSIPS.

siprec_bind = 0.0.0.0: IP address to bind SIPREC server. Required to enable SIPREC.

siprec_bind_port = 5099: Port to listen for SIPREC connections. Required to enable SIPREC.

siprec_rtp_min = 10000: (Default: 10000) Lower bound of RTP port range.

siprec_rtp_max = 20000: (Default: 20000) Upper bound of RTP port range.

siprec_rtp_stream_timeout_s = 300: (Default: 300) RTP stream timeout in seconds.

siprec_rtp_streams_max_threads = 2: (Default: 2) Maximum RTP reception threads.

siprec_rtp_streams_max_per_thread = 100: (Default: 100) Maximum streams per thread.

HEP Support

HEP (Homer Encapsulation Protocol) allows receiving SIP traffic mirrored from Kamailio, OpenSIPS, Asterisk, and other SIP proxies.

receiver_mode = yes: (Default: no) Required to enable the HEP receiver. This directive must be set to yes in the [general] section before the HEP collector will bind to the configured port and accept HEP packets. Without receiver_mode = yes, the sensor will not listen on hep_bind_port even if hep = yes is set. After enabling, verify the port is listening with netstat -an | grep hep_bind_port.

hep = yes: (Default: no) Enable HEP collector.

hep_bind_ip = 0.0.0.0: (Default: 0.0.0.0) Address to bind HEP UDP collector.

hep_bind_port = 9060: UDP port to listen for HEP packets.

hep_kamailio_protocol_id_fix = yes: (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.

audio_transcribe = yes: (Default: no) Enable audio transcription.

whisper_rest_api_url = http://localhost:9000/asr?output=json&encode=true: URL for Whisper REST API. If set, overrides native and python methods.

whisper_rest_api_mode = stereo: (Default: stereo) REST API mode: 'stereo' (one stereo WAV) or 'split' (two mono WAVs).

whisper_native = no: (Default: no) Use native whisper.cpp library.

whisper_model = /path/to/ggml-base.en.bin: Path to Whisper model file.

whisper_language = auto: (Default: auto) Language for transcription. 'auto' for automatic detection.

whisper_timeout = 60: (Default: 0) Timeout for python script execution.

whisper_deterministic_mode = no: (Default: no) Enable deterministic mode.

whisper_python = /usr/bin/python3: (Default: python3) Path to Python interpreter.

whisper_threads = 4: (Default: 0, auto) Number of Whisper processing threads.

whisper_native_lib = /usr/local/lib/libwhisper.so: Path to native Whisper library.

audio_transcribe_threads = 2: (Default: 2) Number of transcription processing threads.

audio_transcribe_queue_length_max = 1000: (Default: 1000) Maximum transcription queue length.

audio_transcribe_parallel_channel_processing = yes: (Default: yes) Process audio channels in parallel.

Kamailio Mirroring

Configuration for receiving SIP traffic mirrored from Kamailio's siptrace module.

receiver_mode = yes: (Default: no) Enables the receiver mode for receiving mirrored traffic. When using Kamailio mirroring or the HEP collector, this directive must be set to yes in the [general] 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 netstat -an | grep 5888 or ss -ulpn | grep voipmonitor.

Kamailio configuration:

loadmodule "siptrace.so"
modparam("siptrace", "trace_on", 1)
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)

kamailio_port = 5888: Port to receive Kamailio mirrored traffic.

kamailio_dstip = 10.0.0.1: VoIPmonitor host IP address.

kamailio_srcip = 10.0.0.2: Kamailio server IP address (optional).

kamailio = no: (Default: no) Enable Kamailio-style substitution on sniffed traffic.

hep_kamailio_protocol_id_fix = yes: (Default: yes) Workaround for Kamailio protocol ID issues.

Ribbon SBC Mirroring

Support for Ribbon SBC monitoring profiles.

Passive Sniffing (Mode 1)

ribbonsbc = yes: (Default: no) Enable Ribbon-style IP:port substitution on sniffed traffic.

ribbonsbc_port = 9514: Expected mirror port in packets (legacy filter).

ribbonsbc_dstip = 10.0.0.1: VoIPmonitor host IP (legacy filter).

ribbonsbc_srcip = 10.0.0.2: Ribbon SBC IP (legacy filter).

Active Listener (Mode 2)

ribbonsbc_bind_ip = 0.0.0.0: Listen address for active mode.

ribbonsbc_bind_port = 9514: Listen port for active mode.

ribbonsbc_bind_udp = no: (Default: no) Enable UDP support. TCP recommended.

ribbonsbc_size_header = yes: (Default: yes) Expect 2-byte size header before each frame.

ribbonsbc_strict_check = no: (Default: no) Only process frames complete per size header.

ribbonsbc_counter_log = no: (Default: no) Log counts of incoming Ribbon frames.

Traffic Dumper

Save captured traffic to PCAP files with optional filtering.

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

traffic_dumper_by_interface = no: (Default: no) Create separate files per interface (yes) or per DLT type (no).

traffic_dumper_force_flush = no: (Default: no) Force flush after each packet. Impacts performance.

traffic_dumper_filter_ip = 192.168.1.100, 10.0.0.0/8: Filter by IP addresses or networks.

traffic_dumper_filter_port = 5060, 5061, 10000-20000: 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.

database_backup_from_date = 2023-01-01: A family of options that puts the sniffer into a special database backup/migration mode, copying data from another database.
coredump_filter = 0x7F: (Default: 0x7F) Controls what memory segments are included in a coredump file if the application crashes.
abort_if_heap_full = no: A set of options that control whether the sniffer should intentionally crash under certain high-load error conditions to generate a coredump for debugging.
interrupts_counters = yes: (Default: yes) Enable interrupt statistics. Disable on Virtuozzo containers.
callslimit = 0: (Default: 0, unlimited) Maximum concurrent calls to process.
skipdefault = yes: (Default: no) Ignore all SIP calls unless capture rules are set.
openfile_max = 65535: (Default: 65535) Maximum open files.
convertchar = :: Replace characters with underscores in filenames.
fbasenameheader = X-custom-filename: Name pcap files based on custom SIP header.
pcapcommand = echo %pcap% >> /tmp/list: Command to run after pcap is closed. Warning: Resource intensive.
filtercommand = myscript '%callid%' '%dirname%': Command for calls matching capture rules.
printinsertid = no: (Default: no) Print CDRID to stdout on every insert.

DPDK Configuration

dpdk_timer_reset_interval = 60: (Default: 60) Reset interval in seconds.
dpdk_nb_rxq = 2: (Default: 2) Number of receive queues. Increase for higher traffic.
dpdk_rxq_per_thread = no: (Default: no) Process RX queues with separate threads.
dpdk_ignore_ierrors = no: (Default: no) Ignore ierrors (packets with bad checksums).

AI Summary for RAG

Summary: This document is a comprehensive reference guide for the `voipmonitor.conf` sniffer configuration file. It covers General Settings (sensor ID, timezone, watchdog), Database Connection and Performance (MySQL settings, partitioning, queue tuning, cleaning, SSL/TLS), Network Interface and Sniffing (interface selection, BPF filters, tunneling protocols including TZSP, L2TP, VXLAN, AudioCodes, IPFIX, HEP, and packet deduplication 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, recording control), 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), 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

Key Questions:

What are the most important settings in voipmonitor.conf for a new installation?
How do I configure the database connection for the sniffer?
How do I fix voice breakage and call lag when the VoIPmonitor sniffer runs on the same server as the PBX?
What happens when I use interface = any versus specific interface names?
How does interfaces_optimize affect performance on shared servers?
What should I do if moving the VoIPmonitor sensor to a separate server is not possible?
How does specifying multiple interfaces create dedicated threads?
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 selectively pause or stop call recording?
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 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?