Sniffer configuration: Difference between revisions

From VoIPmonitor.org
Jump to navigation Jump to search
No edit summary
 
(14 intermediate revisions by 3 users not shown)
Line 1: Line 1:
Configuration file has only one section named [general] where all configuration directives belongs. List of directives will now follow with their description and recommendation values. Name in [ ] brackets is equivalent for command line which takes precendence over configuration file.  
'''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.'''
in case of running more voipmonitor instances on the same or another servers configured to save to one database and the same cdr table it is possible to differentiate CDR by id_sensor column. If you set id_sensor >= 0 the number will be saved in cdr.id_sensor column.


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


This specifies on which interface will voipmonitor listen. It can listen on one interface or on all interfaces. To listen on all interfaces use interface = any
== General & Core Settings ==
The number is between 1 - 65535 (16bit number)


id_sensor = 1
=== Time and Sensor Identification ===
;<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.


= interface =
;<code>utc = yes</code>
:(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.


listening interface. Can be 'any' which will listen on all interfaces - NOTE that "any" will not put intefaces into promiscuous mode and you have to do it with "ifconfig eth0 promisc". You can also sniff on multiple interfaces by providing list of them delimited by ',' example: interface = eth0,eth1
;<code>timezone = /usr/share/zoneinfo/UTC</code>
command line option is -i
:(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.
#interface = eth0,eth1
#interface = any
interface = eth0


= threading_mod =  
=== Process Management ===
* default threading_mod = 1 uses one thread for reading from interface doing deduplication at once* threading_mod = 2 (which is automatically set if you have multiple interfaces (interface = eth0,eth1,...)) reads from each interface in separate thread which is better option on multi core systems than interface = any * threading_mod = 3 will do deduplication (if enabled) in separate thread which is needed for high traffic* threading_mod = 4 will do deduplication in more than one threads - use this option if you enable deduplication and your traffic is over 100Mbit
;<code>watchdog = yes</code>
threading_mod = 1
:(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`.


= mirror =
== Database Configuration ==


since version 8 sniffer implements new mirroring option. Sender is packing data to compressed stream over the TCP to remote sniffer. if you are going to use this sniffer only as a mirroring sniffer all you need is to set interface, packetbuffer_* set compression on and set packetbuffer_file_* so in case the connection to remote sniffer will die or will be temporarily slow the sender will not loose single packet. The mirroring is trying to reconnect in case of failure. Packets are mirrored including the the original timestamp and headers.  this mirroring hopefully replaces pcapscandir feature which will be probably removed in favor of this approach.  
=== 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.


The sender needs to set only interface, ringbuffer, packetbuffer_*, filter and this two folling mirror_destination_*
=== Database SSL/TLS ===
mirror_destination_ip          =  
;<code>mysqlsslkey = /etc/ssl/client-key.pem</code>
mirror_destination_port        =
: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.


On receiver set mirror_bind_ip and mirror_bind_port. Do not forget to set firewall so no other except the sender will be able to connect to the receiver
=== Performance & Schema ===
;<code>query_cache = yes</code>
:(Default: yes) This is a '''critical''' feature. When enabled, all SQL queries are first saved to a disk-based queue before being sent to the database. This prevents data loss if the database is temporarily unavailable and prevents the sensor from running out of memory.
;<code>quick_save_cdr = no</code>
:(Default: no) Speeds up the visibility of calls in the GUI at the cost of higher system load. Options are `no` (10s delay, recommended), `yes` (3s delay), or `quick` (1s delay). Only change this if near-real-time CDR visibility is absolutely required.
;<code>cdr_partition = yes</code>
:(Default: yes) Enables partitioning for large tables (like `cdr`) by day. This is '''essential for performance and data management''' on any production system.
;<code>cdr_partition_by_hours = no</code>
:(Default: no) For extreme high-traffic environments (>= 15,000 CPS), this creates partitions per hour instead of per day to further improve performance.
;<code>disable_dbupgradecheck = yes</code>
:(Default: no) If set to `yes`, the sniffer will not check for and apply database schema updates on startup.
;<code>mysqlloadconfig = yes</code>
:(Default: yes) Allows loading additional configuration parameters dynamically from the `sensor_conf` database table.
;<code>mysqlcompress_type = ...</code>
:(Default: auto-detected) You do not normally need to set this. The sniffer automatically chooses the best table compression method (LZ4 page compression) based on your MySQL/MariaDB version. Only change this for legacy systems.
;<code>mysql_enable_set_id = yes</code>
:(Default: no) In very high-traffic client/server deployments, this allows the central server to generate CDR IDs, which can improve batch insert performance.
;<code>cdr_force_primary_index_in_all_tables = no</code>
:(Default: no) Creates primary indexes on all tables. This is only required for specific database clustering technologies like MySQL/Galera Cluster and should not be enabled otherwise.
;<code>disable_cdr_fields_rtp = no</code>
:(Default: no) Disables all RTP-related statistics columns in the CDR table to save space.


mirror_bind_ip              =  
=== SQL Queue Tuning ===
mirror_bind_port            =
;<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.''


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


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


scan pcap files folder and read file by file. This is in conjunction with running tcpdump which creates pcap file each 5 seconds (-G 5) storing pcap files named by UNIX_TIMESTAMP to /dev/shm/voipmonitor folder (do not forget create it) using 1GB ring buffer to avoid losing packets (-B500000 - you can lower it but not higher) filtering udp packets (udp parameter whcih you can change to your needs). voipmonitor then reads created files (and delete it after processing. This approach can be used for testing throughput or for very high voip traffic (>500Mbit). If the sniffer is able to process pcap files in realtime - there will be in /dev/shm/voipmonitor folder only one or two pcap files. If the sniffer is not able to process in realtime (blocking by I/O or by CPU) number of pcap files will grow faster then the sniffer is able process.  
== Network Interface & Sniffing ==
This section configures how the sensor captures packets.


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


WARNING: libpcap < 1.1 contains memory leak when pcap filter is set - do not set filter in this config or upgrade libpcap to the latest (debian 6 libpcap contains the leak) static compiled voipmonitor from voipmonitor.org contains the latest libpcap
=== High-Traffic & Advanced Packet Capture ===
;<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 in very high packet-rate scenarios.
;<code>dpdk_nb_rxq = 2</code>
:(Default: 2) For users of the [[DPDK|DPDK framework]], this sets the number of receive queues to use, enabling multi-core packet processing at the hardware/driver level.
;<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>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.


tcpdump example command:
=== Tunneling Protocol Support ===
nice -n -20 tcpdump -B500000 -i eth2 udp -G 5 -w /dev/shm/voipmonitor 2>/dev/null 1>/dev/null &
VoIPmonitor can decode various tunneling protocols. To enable listening, uncomment and configure the relevant port.
;<code>udp_port_tzsp = 37008</code> (Mikrotik TZSP)
;<code>udp_port_l2tp = 1701</code> (L2TP)
;<code>udp_port_vxlan = 4789</code> (VXLAN, common in AWS)
;<code>udp_port_hperm = 7932</code> (HP ERM)
;<code>audiocodes = yes</code> (Enables AudioCodes proprietary tunnel)
;<code>ipfix = yes</code> (Enables IPFIX, used by Oracle SBCs)
;<code>hep = yes</code> (Enables Homer Encapsulation Protocol)
;<code>kamailio_port = 5888</code> (Enables mirroring from Kamailio's `siptrace` module)
;<code>ribbonsbc_port = 9514</code> (Enables mirroring from Ribbon SBCs)


= ringbuffer =
== Performance & Threading ==
ringbuffer is circular memory queue directly in kernel memory space. libpcap is reading from this queue and delivers packets to voipmonitor. If the network rate is > 100 Mbit we recommend to set ringbuffer to at least 500. Maximum value is 2000 MB.  ringbuffer = 50 [ --ring-buffer ]


= packetbuffer =
=== Core Threading Model ===
packet buffer is new voipmonitor buffering architecture (since version 8). If enabled new threads are created which raads packets from kernel ringbuffer and queues them into dynamically allocated memory. Packets are dequeued and passed to next threads which reads the content. This will ensure that kernel ringbuffer will not overrun due to CPU or disk I/O spikes.
;<code>threading_expanded = yes</code>
packet buffer will dynamically grow until packetbuffer_total_maxheap is reached. Compression can be enabled (packetbuffer_compress) which compress the buffer with fast snappy algorythm with 50% compression ratio thus doubling the time when the buffer gets filled (600Mbit traffic consumes ~30% one one core Xeon E5-2620).
:(Default: yes) Enables the modern, multi-threaded processing engine. The sniffer automatically spawns and manages threads based on traffic load and CPU capacity. It is recommended to leave this enabled. Set to `high_traffic` for environments exceeding 5 Gbit/s.
;<code>preprocess_rtp_threads = 2</code>
:(Default: 2) The initial number of threads for RTP preprocessing. The system will auto-scale from here.
;<code>destroy_calls_in_storing_cdr = yes</code>
:(Default: no) Offloads the process of freeing call memory to a separate thread. Useful in very high-traffic scenarios (> 50,000 concurrent calls).


It is also possible to use disk buffer if the packet buffer memory is filled by enabling packetbuffer_file_totalmaxsize which is usefull when sniffer is only mirroring data over TCP to another sniffer - if the connection brakes or slowed down and packet buffer gets filled it will start using file buffer until the connection reestablishes so no single packet is lost. Enabling file buffer in non mirroring mode to the same disk as spooldir will get not much benefit because if the process is blocked mainly due to disk I/O it has no benefit to add more I/O by caching unprocessed packets to the same I/O layer.
=== Thread Scheduling & Priority ===
;<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. This helps ensure that packet capture is prioritized over other system tasks.


packetbuffer_enable            = yes
=== NUMA & Memory ===
packetbuffer_total_maxheap      = 2000 #in MB 
;<code>numa_balancing_set = autodisable</code>
packetbuffer_compress          = no #enable compression if you have >2 CPU cores 
:(Default: autodisable) Manages the Linux kernel's NUMA balancing feature. The default setting will automatically disable NUMA balancing if it detects high overhead.
packetbuffer_file_totalmaxsize  = 0 #MB. Default is disabled.
;<code>hugepages_max = 80000</code>
packetbuffer_file_path          = /var/spool/voipmonitor/packetbuffer
:(Default: 0, disabled) Enables the use of huge pages for memory allocation, which can improve performance on some systems by reducing TLB misses.


= rtpthreads =
== Distributed Operation: Client/Server & Mirroring ==


number of threads to process RTP packets. If not specified it will be number of available CPUs - 1. If equal to zero RTP threading is turned off. Each thread allocates default 20MB for buffers (increase to 100 on very high loads). This buffer can be controlled with rtpthread-buffer. For < 150 concurrent calls you can turn it off.  
=== Modern Client/Server Model (Recommended) ===
;<code>server_bind = 0.0.0.0</code>
:The IP address the central sensor will listen on for connections from remote clients.
;<code>server_destination = 10.0.0.1</code>
:The IP address of the central server a remote sensor should connect to.
;<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>server_type_compress = zstd</code>
:(Default: zstd) Compression algorithm for the client/server channel.


rtpthreads = 3
=== Legacy Mirroring Model ===
;<code>mirror_bind_ip = 0.0.0.0</code>
:The IP the receiver sensor listens on for the unencrypted, legacy mirroring protocol.
;<code>mirror_destination_ip = 10.0.0.1</code>
:The IP of the receiver sensor that the sender should stream packets to.


= sdp_reverse_ipport =
== Storage & File Management (Spooldir) ==


since 8.4RC17
=== Location and Permissions ===
if voip SIP device (with source IP 1.1.1.1) sends in SDP that it wants RTP for example to 10.0.0.1 and port 10000 the call also sniff RTP from 1.1.1.1:10000 or to 1.1.1.1:10000 which does more problems than it solves. Now this behaviour is changed and if you need this option back you can enable it
;<code>spooldir = /var/spool/voipmonitor</code>
:The primary directory for storing all captured data (PCAP, GRAPH, AUDIO files).
;<code>spooldir_file_permission = 0666</code>
;<code>spooldir_dir_permission = 0777</code>
:Allows setting specific filesystem permissions for newly created files and directories.
;<code>spooldir_by_sensor = no</code>
:(Default: no) If enabled, creates subdirectories within the spooldir for each `id_sensor`.


=== PCAP/TAR Storage Strategy ===
;<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>savesip = yes</code>
:Enables saving of SIP packets.
;<code>savertp = yes</code>
:Enables saving of RTP packets. Set to `header` to save only RTP headers, not the audio payload.
;<code>savertcp = yes</code>
:Enables saving of RTCP (RTP Control Protocol) packets.
;<code>savegraph = yes</code>
:Enables saving of call graph data.


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


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


sdp_reverse_ipport = yes
== Call Processing & Protocol Logic ==


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


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


in case the SIP(media) server is behind public IP (1.1.1.1) NATed to private IP (10.0.0.3) to sniff all traffic correctly you can specify alias for this case. You can specify more netaliases duplicating rows. In most cases this is not necessary because voipmonitor is able to track both RTP streams based on the other side IP. But if the stream is incoming from another IP then SIP source signalization and also from another IP than the SIP device which is also behind NAT its impossible to track the correct IP. Please note that this is for case where the SIP server is behind NAT and also the client is behind NAT. If your SIP server has public IP do not bother with this.  
=== RTP & SRTP (Encrypted Media) ===
;<code>jitterbuffer_f1 = yes</code>, `jitterbuffer_f2 = yes`, `jitterbuffer_adapt = yes</code>
:(Default: all yes) Enables the three jitter buffer simulators used to calculate parametric MOS scores. These are CPU-intensive; you can disable one or more on resource-constrained systems.
;<code>srtp_rtp = no</code>
:(Default: no) To save decrypted SRTP (audio) streams into the PCAP file, you must set this to `yes`. This requires a valid decryption key.
;<code>ssl_dtls_boost = no</code>
:(Default: no) A meta-parameter that enables a set of aggressive options for improving DTLS handshake and SRTP decryption success rates.


natalias = 1.1.1.1 10.0.0.3  
=== NAT Handling ===
natalias = 1.1.1.2 10.0.0.4
;<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.


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


define bind address for manager interface. Default is 127.0.0.1 it is not recommended to change this unless really needed due to security. If you need it on some other IP make sure you set firewall and change the standard port for better security
=== Call Recording Control ===
;<code>pauserecordingdtmf = *9</code>
:(Default: unset) If set, RTP recording will be paused when this DTMF sequence is detected in a call.
;<code>pauserecordingheader = MyCustomPauseHeader</code>
:(Default: unset) Pauses/unpauses recording based on the presence of a specific SIP header and its value (e.g., `pause` or `unpause`).
;<code>norecord-header = yes</code>
:(Default: no) If any SIP packet in a call contains the `X-VoipMonitor-norecord` header, the entire call record (PCAP and CDR) will be discarded.


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


= managerport =  
== Expert & Debugging Options ==
'''Warning:''' These options should only be changed if you are an expert or instructed to do so by the support team.


This specifies TCP port which will voipmonitor listen for incoming connections which controls voipmonitor or for getting information about calls. *reload configuration echo reload | nc localhost 5029 *get number of calls echo totalcalls | nc localhost 5029 *get list of calls in json format echo listcalls | nc localhost 5029 
;<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>deduplicate = yes</code>
:(Default: no) Enables packet deduplication based on an MD5 checksum. Useful if you are receiving the same traffic stream from multiple sources.
;<code>coredump_filter = 0x7F</code>
:Controls what memory segments are included in a coredump file if the application crashes.
;<code>abort_if_heap_full = no</code>
:A set of options that control whether the sniffer should intentionally crash under certain high-load error conditions to generate a coredump for debugging.


managerport = 5029 [ --manager-port <port number> ]
== AI Summary for RAG ==
 
'''Summary:''' This document is a comprehensive reference guide for the `voipmonitor.conf` sniffer configuration file. It is logically structured into sections covering General Settings (sensor ID, timezone), Database Connection and Performance (MySQL settings, partitioning, queue tuning, cleaning), Network Interface and Sniffing (interface selection, BPF filters, tunneling protocols like TZSP/VXLAN, and kernel-bypass methods like DPDK), Performance and Threading (NUMA, scheduling), Distributed Architectures (the modern client/server model vs. legacy mirroring), and Storage Management (spooldir, TAR file usage, pcap saving, and automated cleaning rules). It also details protocol-specific configurations for SIP, RTP, SRTP, Skinny, MGCP, and others, including call timeout logic, DTMF detection, and call identity headers. A final section covers expert and debugging options like database backup mode and deduplication.
= managerclient =  
'''Keywords:''' voipmonitor.conf, configuration, sniffer config, sensor, database, mysql, mariadb, cdr_partition, cleandatabase, interface, sniffing, promisc, bpf, filter, tunneling, DPDK, performance, threading, t0CPU, client/server, distributed, remote sensor, spooldir, storage, pcap, tar, maxpoolsize, saveaudio, SIP, RTP, SRTP, DTLS, skinny, MGCP, SS7, diameter, NAT, natalias, call recording, watchdog, `sched_pol_auto`
 
'''Key Questions:'''
connects to server and listen for commands.
* What are the most important settings in voipmonitor.conf for a new installation?
 
* How do I configure the database connection for the sniffer?
managerclient = serverip or hostname
* How do I set up a distributed client/server architecture?
managerclientport = 1234
* 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?
= destination_number_mode =
* How do I configure the sniffer to listen on multiple SIP ports?
 
* What are the `maxpoolsize` and `cleandatabase` options and how do they work?
take number from INVITE URI or To: SIP header. If destination_number_mode = 1 It will always save number from To: header. if destination_number_mode = 0 it will take number from INVITE URI.
* How do I enable SRTP decryption?
 
* How do I configure VoIPmonitor to handle tunneled traffic from a Mikrotik router or AWS?
default:
* How do I selectively pause or stop call recording?
 
destination_number_mode = 1
 
= sipport =
 
define SIP ports wihch will voipmonitor listen. For each port make new line with sipport = port (multiple lines)
 
sipport = 5060
sipport = 5061
sipport = 5062
 
= rtptimeout =
 
rtptimeout is important value which specifies how much seconds from the last SIP packet or RTP packet is call closed and writen to database. It means that if you need to monitor ONLY SIP you have to set this to at leat 2 hours = 7200 assuming your calls is not longer than 2 hours. Take in mind that seting this to very large value will cause to keep call in memory in case the call lost BYE and can consume all memory and slows down the sniffer - so do not set it to  very high numbers. Default is 300 seconds.
 
rtptimeout = 300
 
= jitterbuffer =
 
By default voipmonitor uses three types of jitterbuffer simulators to compute MOS score.  First variant is saved into cdr.[ab]_f1 and represents MOS score for devices which has only fixed 50ms jitterbuffer.  Second variant is same as first but for fixed 200ms and is saved to cdr.[ab]_f2 Third varinat is adaptive jitterbuffer simulator up to 500ms Jitterbuffer simulator is the most CPU intensive task which is voipmonitor doing. If you are hitting CPU 100% turn off some of the jitterbuffer simulator. Recommended for higher loads is to use only fixed 200ms (f1)
 
jitterbuffer_f1 = yes
jitterbuffer_f2 = yes
jitterbuffer_adapt = yes
 
= callslimit =
 
callslimit will limit maximum numbers of calls processed by voipmonitor at the same time. If calls are over limit it will be ignored (INVITE)  
 
callslimit = 0
 
= cdrproxy =
in case SIP session travels accross several proxies (and Call-ID header DOES not change) and you would like to track all sip proxies and make them searchable in GUI / database.  If disabled cdr will store to destination sip column destination IP from the first INVITE. If enabled there will be destination IP from the latest invite and all proxy ip will be stored in cdr_proxy table.
 
default = yes
 
cdrproxy = yes
 
= cdr_ua_enable=
this option allows to skip storing cdr.a_ua and cdr.b_ua - this is workaround for those who has extreme cdr rate and number of user agents in database is over 1000 and CPU is not powerfull enough to store cdr in real time. In future this option will be removed once we optimize this rutine.
default = yes
 
cdr_ua_enable = yes
 
= rtp-firstleg =
 
this is important option if voipmonitor is sniffing on SIP proxy like kamailio or openser and sees both RTP leg of CALL. In that case use this option. It will analyze RTP only for the first LEG and not each 4 RTP streams which will confuse voipmonitor. Drawback of this switch is that voipmonitor will analyze SDP only for SIP packets which have the same IP and port of the first INVITE source IP and port. It means it will not work in case where phone sends INVITE from a.b.c.d:1024 and SIP proxy replies to a.b.c.d:5060.
 
rtp-firstleg = no [ --rtp-firstleg ]
 
= allow-zerossrc =
 
* since 8.0.2
* default = no
 
SSRC in RTP headers must not equal zero according to RFC so voipmonitor is ignoring such RTP by default. If you still need to parse such packets enable it
 
allow-zerossrc = yes
 
= deduplicate =
 
duplicate check do md5 sum for each packet and if md5 is same as previous packet it will discard it. WARNING: md5 is expensive function (slows voipmonitor 3 times) so use it only if you have enough CPU or for pcap conversion only. Default is no.
 
deduplicate = yes
 
= deduplicate_ipheader =
 
*since 8.1
prior verison 8.0.1 deduplicate was comparing only data without ip header and udp header so duplicate packets was matched also in case the IP addresses differes. This was good for some cases but it leads to completely ignore RTP streams in other cases. Now default option is to check duplicates based on not only data but ip headers too. To change this set deduplicate_ipheader = no. default = yes.
deduplicate_ipheader = yes
 
= sipoverlap =
 
enable/disable updating called number from To: header from each caller INVITE. Default is enabled so it supports overlap dialing (RFC 3578)if you want to disable this behaviour and see always number only from the first INVITE set sipoverlap = no
 
sipoverlap = yes
 
 
= sip-register =
 
 
Enable parsing of SIP REGISTER message. SQL register table stores active SIP registrations. Once it expires it is removed from the table to new sql register_state table. The register state table is used to store changes in registrations. SQL table register_failed is used to store all failed sip register. To not overload this table there is counter column which adds +1 for each failed register from the same source.
 
sip-register = no [ -R ]
 
= sip-register-active-nologbin =
if mysql binlog is enabled, skip binlog inserts into active table (which is MEMORY type) if you still want to replicate this too (huge I/O impact) set it to = no sip-register-active-nologbin = yes
 
= skipdefault =
 
if yes, all SIP calls will be ignored unless capture rules set skip flag based on IP or Tel. numbers (mysql.filter_*) 
skipdefault = yes
 
= nocdr =
 
if yes, voipmonitor will not save CDR to MySQL
 
nocdr = no [ -c ]
 
= maxpcapsize =
 
limit pcap file size (in MB). default disabled. since 8.4
maxpcapsize = 500
 
= savesip =
 
Store SIP packets to pcap file.
 
savesip = [ --sip-register ]
 
= savertp =
save RTP packets to pcap file. savertp = yes automatically saves RTCP packets you can also save only RTP header without AUDIO: savertp = header if save RTP is aneblad it will also save UDPTL packets (used for T.38)  you can also set savertp = no and control what calls will record RTP in mysql table filter_ip or filter_tel which is controled in GUI -> Capture rules. Sending reload command will reload configuration from filter_* table. You can also set savertp = yes but denies recording RTP based on rules in filter_* table.
 
savertp = yes | header [ -R ]
 
= pcapsplit =
 
voipmonitor by default splits SIP and RTP packets to individual files (in case spooldiroldschema = no) which are located in SIP and RTP directories. This feature allows instance cleaning RTP streams differently then SIP packets to join two pcap files SIP+RTP use mergecap command line utility which is included in wireshark package default = yes | spooldiroldschema must be set to no
pcapsplit = yes
= savertcp =
 
Store RTCP packets to pcap file.
 
savertcp = yes [ --save-rtcp ]
= saveudptl =
 
save UDPTL packets (T.38). If savertp = yes the udptl packets are saved automatically. If savertp = no and you want to save only udptl packets enable saveudptl = yes and savertp = no
 
saveudptl = yes
 
= savegraph =
This is usefull only if you have commercial WEB GUI which uses graph files for ploting graph
 
savegraph = plain [ -G or --save-graph=[gzip|plain] ]
= saveaudio =
save RTP payload to audio file. Choose 'wav' for WAV PCM or 'ogg' for OGG 25kbps format. please note that this has great impact on I/O and can overload your storage leading to lose packets. Better way is to store only sip+rtp and convert wav files on demand.
saveaudio = wav
 
= convert_dlt_sll2en10 =
 
*since 8.0.2
 
in case you need to have ethernet encapsulation and you are sniffing on interface = any set this to = yes. this is needed only in case you need to merge pcap files with different encapsulations. default is no.
 
convert_dlt_sll2en10 = no
 
= keycheck =
default path to WEB GUI used to construct path to key check for codecs
default paths: #keycheck = /var/www/voipmonitor/php/keycheck.php #keycheck = /var/www/html/voipmonitor/php/keycheck.php
 
= saverfc2833 =
 
in case you are not saving RTP at all but you still want to save DTMF carried over RTP packets (RFC2833) you can enable this option. This feature slows down a bit processing RTP packets in main read thread in casse voipmonitor runs in threads. default = 0
 
saverfc2833 = 0
 
= dtmf2db =
Enable storing DTMF (SIP INFO or RFC2833) to cdr_dtmf database. It will store DTMF time and key then it will be shown in SIP history in the GUI
dtmf2db = 0
= norecord-header =
if any of SIP message during the call contains header X-VoipMonitor-norecord call will be not converted to wav and pcap file will be deleted.
norecord-header = yes
= norecord-dtmf =if any of SIP message during the call contains DTMF INFO sequence "*0" call will be not converted to wav and pcap file will be deleted. default: disabled
norecord-dtmf = yes
= pauserecordingdtmf =
enable pausing RTP/WAV recording if DTMF sequence detected. default: disabled
pauserecordingdtmf = *9
= dumpallpackets =
dump all packets to /tmp/voipmonitor-[UNIX_TIMESTAMP].pcap
dumpallpackets = yes
 
= mos_g729 =
 
enable MOS score for G.729 codec. If enabled, all cdr with 0 packet loss and stable delays will have maximum MOS of 3.92 and for loss and unstable delay MOS will be calculated according to ITU-T objective PESQ method for G.729 codec. if you want to use MOS as good search value which corellates loss and delay into single value leave it disabled (which is by default). If set to no, all calls will be calculated like it is G.711. Recommended value = no
 
mos_g729 = no
 
= custom_headers =
 
Since 7.0RC7.
 
enable storing custom sip headers to database column cdr_next.custom_header_headername. You can specify more headers delimited by ";".
WARNING - when you enable this feature voipmonitor will autoupgrade cdr_next table which can take hours depending on how large the table is. In GUI there is new section [[Settings#CDR_Custom_header]].
 
custom_headers = X-asterisk-Info ; X-myheader
 
analogical for SIP message is custom_headers_message
custom_headers_message = X-asterisk-Info ; X-myheader
 
= match_header =
 
enable saving content of custom header (typicaly in-reply-to) to cdr_next.match_header this header is used in related CDR GUI for matching legs to onen call
 
match_header = in-reply-to
= pcapcommand =
 
pcapcommand will run command after pcap file is closed (after call ends). %pcap% is substitution for real pcap file name. execution is guaranteed to run in serialized way (not in parallel)WARNING - pcapcommand is implemented by forking program which is very expensive and is causing TLB shootouts on multicore system which can generate 500 000 interrupts / sec causing system to drop packets. Watch the performance carefuly (with "vmstat 1" column "in"). Gziping pcap files will be implemented as native function directly in C++ to obey TLB shootdowns.
 
pcapcommand = gzip %pcap%
 
= filtercommand =
 
 
*since 8.3
 
 
 
filtercommand will run command after each call which matches script == 1 in filter_ip or filter_telnum (capture rules in GUI)
WARNING - filtercommand is implemented by forking program which is very expensive and is causing TLB shootouts on multicore system which can generate 500 000 interrupts per seconds causing system to drop packets. Watch the performance carefuly (with "vmstat 1" column "in").  
 
all non alphanum characters except '/' '#' ' ' '+' ':' '-' '.' and '@' in callid, dirname, caller, called and calldate are substituted to '_'
 
default is disabled
 
filtercommand = myscript '%basename%' '%dirname%' '%caller%' '%called%' '%calldate%'
 
= filter =
 
libpcap tcpdump style filter. Voipmonitor listens in default only for UDP packets. Unfortunatly filtering UDP packets will filter all VLAN tagged packets which means that you cannot filter only UDP if you want to listen to VLAN tagged packets.
 
'''WARNING''' - if you need to sniff IPinIP (like mirrored packets from voipmonitor) filter = udp will filter all those packets. In this case just disable filter.
 
 
filter = udp or (vlan and udp) [ -f ]
 
= convertchar =
 
list characters that should be converted to underscore (_) in filenames if you want to include space, put it between other characters, like ': :' (will convert ':' and ' ' to '_') defaults to nore
# example - avoid ':' when Call-Id contains port number convertchar = :
 
= spooldir =
 
This is directory where all pcap/graph/wav files are stored.
 
spooldir = /var/spool/voipmonitor [ -d ]
= spooldiroldschema =
new spooldir schema stores all files to year-mon-day/hour/minute/[ALL|SIP|RTP|AUDIO] directories if you need to have the old schema year-mon-day/* enable spooldiroldschema = yes. default = no
spooldiroldschema = no
 
= cachedir =
store pcap and graph file to <cache/dir> and move it after call ends to spool directory. Moving all files are guaranteed to be serialized which solves slow random write I/O on magnetic or other media. Typical cache directory is /dev/shm/voipmonitor which is in RAM and grows automatically or /mnt/ssd/voipmonitor which is mounted to SSD disk or some very fast SAS/SATA disk where spool can be network storage or raid5 etc. wav files are not implemented yet
 
cachedir = /dev/shm/voipmonitor
 
= cleandatabase_cdr =
 
 
Removes cdr* partitions older then set number of days. If set to 0 it is disabled (default)
 
 
cleandatabase_cdr = 0
 
 
 
= cleandatabase_register_state =
 
 
Removes register_state partitions older then set number of days. If set to 0 it is disabled (default)
 
 
= cleandatabase_register_failed =
 
 
Removes cleandatabase_register_failed partitions older then set number of days. If set to 0 it is disabled (default)
 
 
= cleandatabase =
 
Sets cleandatabase_cdr and cleandatabase_register_state and cleandatabase_register_failed to the same values. Configuration first look at cleandatabase parameter  then it looks for other cleandatabase_* parameters.
 
default is disabled
 
cleandatabase = 0
 
= cleanspool_interval =
 
 
clean spool directory every two hours from oldest file until spooldir size = cleanspool_size (in MB)  WARNING - if you have milions files set cleanspool_interval to 24 hour (clean once per day)  cleaning is very slow and can overload I/O (in seconds). Default is disabled.
 
cleanspool_interval = 7200
 
= cleanspool_size =
 
 
set target size of the spool directory for cleaning script (in MB). Default is disabled.
 
 
 
cleanspool_size = 50000
#usefull command to clean all RTP files older 7 days # find /var/spool/voipmonitor -maxdepth 1 -type d -mtime +7 -name '20*' | (while read d; do rm -rf $d/*/*/RTP; done)
= promisc =
 
This option is only relevant if you are mirroring traffic to your network card/cards. This will not work if interface = any - in this case, use ifconfig to put your desired interfaces to promis mode. Default value is yes and you want to turn it of on command line ues -n which will turn it off.
 
promisc = yes [ -n ]
 
= database =
 
== sqldriver ==
 
sqldriver = mysql  #sqldriver = odbc #odbcdriver = mssql #odbsdsn = voipmonitor #odbcuser = root #odbcpass =
voipmonitor can connect to mysql server or odbc driver. connecting voipmonitor to msssql please refer to README.mssql
 
== cdr_partition ==
 
use partitioning cdr* tables by day. If you have schema without partitioning, you MUST start with new database. default is = yes
 
cdr_partition = yes
 
== disable_partition_operations (since 8.4RC9) ==
 
disable partition creation which runs every 12 hours. If you have multiple sensors storing to one database it is redundant to create partitions by all sensors. default = no
disable_partition_operations = yes
 
== mysqlhost ==
 
mysql server, default is 127.0.0.1 (localhost). Command line option is -h
 
mysqlhost = 127.0.0.1
 
== mysqldb ==
 
mysql database, default is voipmonitor. Command line option is -b
 
mysqldb = voipmonitor
 
== mysqlusername ==
mysql username, default is root
 
mysqlusername = root
 
 
== mysqlpassword ==
 
mysql password, default is no password
 
mysqlpassword =
 
= upgrade_try_http_if_https_fail =
 
if https failes when upgrading the sniffer try also http
 
upgrade_try_http_if_https_fail = yes

Latest revision as of 10:45, 30 June 2025

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)

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.
deduplicate = yes
(Default: no) Enables packet deduplication based on an MD5 checksum. Useful if you are receiving the same traffic stream from multiple sources.
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 is logically structured into sections covering General Settings (sensor ID, timezone), Database Connection and Performance (MySQL settings, partitioning, queue tuning, cleaning), Network Interface and Sniffing (interface selection, BPF filters, tunneling protocols like TZSP/VXLAN, and kernel-bypass methods like DPDK), Performance and Threading (NUMA, scheduling), Distributed Architectures (the modern client/server model vs. legacy mirroring), and Storage Management (spooldir, TAR file usage, pcap saving, and automated cleaning rules). It also details protocol-specific configurations for SIP, RTP, SRTP, Skinny, MGCP, and others, including call timeout logic, DTMF detection, and call identity headers. A final section covers expert and debugging options like database backup mode and deduplication. Keywords: voipmonitor.conf, configuration, sniffer config, sensor, database, mysql, mariadb, cdr_partition, cleandatabase, interface, sniffing, promisc, bpf, filter, tunneling, DPDK, performance, threading, t0CPU, client/server, distributed, remote sensor, spooldir, storage, pcap, tar, maxpoolsize, saveaudio, SIP, RTP, SRTP, DTLS, skinny, MGCP, SS7, diameter, NAT, natalias, call recording, watchdog, `sched_pol_auto` Key Questions:

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