Sniffer configuration

From VoIPmonitor.org
Revision as of 15:10, 2 January 2026 by Admin (talk | contribs) (Add comprehensive packet deduplication documentation - deduplicate, auto_enable_use_blocks, deduplicate_ipheader=ip_only)

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

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.

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

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.

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.
Note: Many other `cleandatabase_*` options exist for specific tables like `register_failed`, `sip_msg`, `ss7`, etc.
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).

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`.
filter = udp or (vlan and udp)
(Default: unset) Applies a BPF filter (like in `tcpdump`) to the captured traffic. Warning: Using filters can be complex and may accidentally exclude important traffic like VLAN-tagged or tunneled packets. Use with caution.
interface_ip_filter = 192.168.0.0/24
(Default: unset) A more efficient way to filter traffic by IP address or subnet compared to the main `filter` option. Multiple lines can be used.

High-Traffic & Advanced Packet Capture

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 in very high packet-rate scenarios.
dpdk_nb_rxq = 2
(Default: 2) For users of the DPDK framework, this sets the number of receive queues to use, enabling multi-core packet processing at the hardware/driver level.
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`.
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.

Tunneling Protocol Support

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

udp_port_tzsp = 37008 (Mikrotik TZSP)
udp_port_l2tp = 1701 (L2TP)
udp_port_vxlan = 4789 (VXLAN, common in AWS)
udp_port_hperm = 7932 (HP ERM)
audiocodes = yes (Enables AudioCodes proprietary tunnel)
ipfix = yes (Enables IPFIX, used by Oracle SBCs)
hep = yes (Enables Homer Encapsulation Protocol)
kamailio_port = 5888 (Enables mirroring from Kamailio's `siptrace` module)
ribbonsbc_port = 9514 (Enables mirroring from Ribbon SBCs)

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.
auto_enable_use_blocks = yes
(Default: no) Required for deduplication when sniffing from multiple sources or interfaces. 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.

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. It is recommended to leave this enabled. Set to `high_traffic` for environments exceeding 5 Gbit/s.
preprocess_rtp_threads = 2
(Default: 2) The initial number of threads for RTP preprocessing. The system will auto-scale from here.
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).

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. This helps ensure that packet capture is prioritized over other system tasks.

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.

Distributed Operation: Client/Server & Mirroring

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_destination = 10.0.0.1
The IP address of the central server a remote sensor should connect to.
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).
server_type_compress = zstd
(Default: zstd) Compression algorithm for the client/server channel.

Legacy Mirroring Model

mirror_bind_ip = 0.0.0.0
The IP the receiver sensor listens on for the unencrypted, legacy mirroring protocol.
mirror_destination_ip = 10.0.0.1
The IP of the receiver sensor that the sender should stream packets to.

Storage & File Management (Spooldir)

Location and Permissions

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

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.
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.
savertcp = yes
Enables saving of RTCP (RTP Control Protocol) packets.
savegraph = yes
Enables saving of call graph data.

Spool Cleaning

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

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. Note: This is generally not necessary and adds significant CPU/I/O load.
mp3_quality = 5, `ogg_quality = 0.4`
Quality settings for the respective audio formats.

Call Processing & Protocol Logic

Call Identification & Merging

remoteparty_caller = calling, `passertedidentity = no`, etc.
A group of options that control which SIP headers (`Remote-Party-ID`, `P-Asserted-Identity`, etc.) are used to determine the definitive caller/callee information.
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.

Call Timeouts & Termination

absolute_timeout = 14400
(Default: 4 hours) Forcefully ends any call that lasts longer than this value to prevent runaway processes.
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.
ignore_rtp_after_response = 408;480;486;487;481;600;503
A list of SIP final response codes after which the sniffer should stop looking for RTP for that call.

RTP & SRTP (Encrypted Media)

jitterbuffer_f1 = yes, `jitterbuffer_f2 = yes`, `jitterbuffer_adapt = yes
(Default: all yes) Enables the three jitter buffer simulators used to calculate parametric MOS scores. These are CPU-intensive; you can disable one or more on resource-constrained systems.
srtp_rtp = no
(Default: no) To save decrypted SRTP (audio) streams into the PCAP file, you must set this to `yes`. This requires a valid decryption key.
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.

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.

SIP, REGISTER, and Other Messages

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

Call Recording Control

pauserecordingdtmf = *9
(Default: unset) If set, RTP recording will be paused when this DTMF sequence is detected in a call.
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.

Other Protocols

skinny = yes
(Default: no) Enables parsing for Cisco Skinny Call Control Protocol (SCCP).
mgcp = yes
(Default: no) Enables parsing for MGCP.
ss7 = yes
(Default: no) Enables parsing for SS7-over-IP (SIGTRAN).
diameter = no
(Default: no) Enables parsing for the Diameter protocol.

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

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), Database Connection and Performance (MySQL settings, partitioning, queue tuning, cleaning), Network Interface and Sniffing (interface selection, BPF filters, tunneling protocols, kernel-bypass with DPDK, and packet deduplication with options like `deduplicate`, `auto_enable_use_blocks`, and `deduplicate_ipheader`), Performance and Threading (NUMA, scheduling), Distributed Architectures (client/server model and legacy mirroring), and Storage Management (spooldir, TAR files, pcap saving, and cleaning rules). It also details protocol-specific configurations for SIP, RTP, SRTP, Skinny, MGCP, and others.

Keywords: voipmonitor.conf, configuration, sniffer config, sensor, database, mysql, mariadb, cdr_partition, cleandatabase, interface, sniffing, promisc, bpf, filter, tunneling, DPDK, performance, threading, t0CPU, client/server, distributed, remote sensor, spooldir, storage, pcap, tar, maxpoolsize, saveaudio, SIP, RTP, SRTP, DTLS, skinny, MGCP, SS7, diameter, NAT, natalias, call recording, watchdog, sched_pol_auto, deduplicate, auto_enable_use_blocks, deduplicate_ipheader, ip_only, packet deduplication, duplicate packets

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 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 using `innodb_buffer_pool_size` and other parameters?
  • 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?
  • How do I configure VoIPmonitor to handle tunneled traffic from a Mikrotik router or AWS?
  • How do I selectively pause or stop call recording?
  • How do I enable packet deduplication for multiple sensors or interfaces?
  • What is `auto_enable_use_blocks` and why is it required for deduplication?
  • What is the difference between `deduplicate_ipheader = yes`, `ip_only`, and `no`?
  • How do I configure deduplication when packets arrive from different network paths with different TTL values?
Retrieved from "https://www.voipmonitor.org/doc/index.php?title=Sniffer_configuration&oldid=6238"