FAQ

This page provides answers to frequently asked questions and solutions to common issues encountered during the configuration and operation of VoIPmonitor.

Quick Navigation

General Topics	Configuration	Troubleshooting	Files & Compliance
Scaling Licensing Platform Support	SIP Ports IPv6 DTMF	CDR Issues Admin Tasks GUI Debug	Audio/PCAP PCI Compliance Capture Rules

General & Scalability

How does VoIPmonitor scale for high traffic?: For a detailed guide on performance tuning, hardware recommendations, and optimizing the three main system bottlenecks (CPU, Disk I/O, Database), please refer to our comprehensive Scaling and Performance Tuning guide.

How do I manage disk space and database size?: VoIPmonitor uses separate mechanisms for cleaning PCAP files from the filesystem and CDRs from the database. For a complete walkthrough, see the Data Cleaning and Retention guide.

CDR (Call Detail Record) View

What does the small red icon in the CDR view mean?: The red icon () indicates which party in the call sent the BYE message first, effectively ending the call.

How can I use regular expressions to filter calls?: The filter bar in the CDR view supports regular expressions. This is useful for finding malformed or unusual data. For example, to find all calls where the caller number contains non-numeric characters, you can use a negative match:; !R(^[+]?[0-9]+$)

Why is there a delay between when a call ends and when it appears in the CDR view?

This delay is typically caused by the database's inability to keep up with the rate of incoming calls, creating a queue of SQL queries on the sensor. For solutions, please read:

How can I enable millisecond precision for timestamps in the CDR view?: By default, timestamps are stored with second precision. To enable millisecond precision, please follow the steps in this guide: How_to_enable_milliseconds_precision.

How do I search for multi-word strings in custom header fields?: When searching for a multi-word string (e.g., "Normal Call Clearing") in a custom header field, the system interprets spaces as logical OR operators by default. To search for the exact multi-word string, use an underscore (_) as a wildcard character to represent the space.

Example: To search for "Normal Call Clearing", use:

%normal_call_clearing%

The underscore acts as a wildcard that matches a single character (in this case, the space), while the percent (%) matches any number of characters before and after the phrase.

Can I generate a report of concurrent calls broken down by individual source IP address?: No, this functionality is not currently available via the GUI, the Web API, or a simple SQL query. The system can show total concurrent calls over time (in Charts > "number of calls") and can provide call summaries grouped by IP address (in Reports > Call Summary), but there is no built-in function to display concurrent calls per individual source IP over time without creating separate chart series or filters for each IP.

Workarounds:

Use the Call Summary report to see aggregate call statistics per IP (total calls, duration, etc.)
Create separate series in Charts for each IP using the Filters tab (requires individual IP filters)
Create IP Groups to group multiple IPs and create charts per group

Platform & Environment Support

What hardware architectures does the sensor support?: The sensor is tested and supported on x86 (32/64-bit) and ARMv7/v8 architectures. If you encounter an error like __sync_fetch_and_sub_8 on an older ARM device, you may need to upgrade your GCC compiler to version 4.8 or newer.

Can I run VoIPmonitor on AWS?

Yes, AWS is supported. For the license check to function correctly on some Amazon Machine Images (AMIs), you may need to adjust permissions on the root device file:

chmod 644 /dev/root

Is Docker or other container environments supported?: Yes, the GUI and sensor can run in a containerized environment. However, you must ensure that the content of /proc/self/cgroup does not change with every container restart. If it does, the hardware ID will change, and you will be prompted to update your license key after each reboot.

Are hosted/cloud databases (like Amazon RDS, Azure Database) supported?: Yes, VoIPmonitor requires a MySQL-compatible database (MySQL, MariaDB, Percona) and can connect to it regardless of its location. However, the database user requires SUPER privilege for creating functions and triggers.

What if my cloud database (like Azure) does not grant SUPER privilege?

If SUPER privilege is not available, you must manually set the following server variable in your cloud database configuration console:

log_bin_trust_function_creators = ON

Additionally, ensure your database instance has sufficient performance (e.g., at least 1100 IOPS for 5000 concurrent calls on Azure).

Why is packet mirroring not working on VMWare ESXi 6.5+?: This is often caused by the vSwitch port group being set to VLAN 4095, which activates Virtual Guest Tagging (VGT). In this mode, the guest OS is expected to handle VLAN tags, which can disrupt sniffing.; Solution: Edit the port group settings in vSphere and change the VLAN ID to a specific number (e.g., 0 or your monitoring VLAN ID) instead of 4095.

Configuration & Features

Why don't I see SIP packets on ports other than 5060?: By default, the sensor only listens for SIP traffic on UDP/TCP port 5060. To monitor additional SIP ports, you must explicitly define them in voipmonitor.conf. See the sipport configuration guide.

How do I enable IPv6 traffic processing?: By default, IPv6 is disabled. To enable it on a new installation, set ipv6=yes in voipmonitor.conf. If you have existing IPv4 data, enabling IPv6 requires a database migration. For detailed instructions, please see the IPv6 Enabling Guide.

How do I capture and view SIP REGISTER messages?: By default, REGISTER messages are not stored. To enable this, set sip-register=yes in voipmonitor.conf. For details on how active and failed registrations are stored and how to query them via the API, see the documentation on REGISTER monitoring.

How can I capture DTMF tones?

You can enable DTMF capture in voipmonitor.conf:

For RFC2833 and SIP INFO methods, set: dtmf2db = yes
For inband DTMF (G.711 codec only, requires more CPU), set: inbanddtmf = yes

How can I use the sensor's manager API securely?: Modern sniffer versions (32.0+) have API encryption enabled by default. Please refer to the Manager API Encryption guide for examples on how to use the API with or without encryption.

How does VoIPmonitor handle AudioCodes-tunneled traffic?: VoIPmonitor can process traffic encapsulated in AudioCodes' proprietary tunneling protocol. For setup details, see the AudioCodes Tunneling guide.

Can wildcards or regular expressions be used in domain-based capture rules?: No, domain-based capture rules only support exact string matching. Wildcards and regular expressions are not supported for domain matching in capture rules.

For different rule types, VoIPmonitor supports the following matching methods:

Rule Type	Matching Supported	Example
IP Addresses	CIDR subnet masks (wildcard networks)	`1.2.3.0/24` matches all IPs in that range
Telephone Numbers	Prefix matching (equivalent to wildcard)	`4420` matches `4420*`
SIP Domains	Exact match only	`example.com` ONLY matches `example.com`, not `sub.example.com`

If you need more complex domain matching logic (such as patterns or subdomains), you must use the filtercommand option with an external script, or use regular expressions in the CDR view filter bar for searching recorded calls.

Licensing

How do I determine the number of license channels I need?: The license is based on the maximum number of concurrent calls during your peak hours. It is not based on the number of phones or endpoints. You can find your peak usage by navigating in the GUI to Tools → System Status → Concurrent calls, which shows data for the past 14 days. The system intelligently groups multiple call legs (e.g., for a single bridged call) so they only count as one channel towards your license.

What happens if my call volume temporarily exceeds my license limit?: Important: The license alert is temporary and self-clearing.; If you exceed your concurrent call limit for a single day or occasionally, a warning message will appear in the GUI. This warning is temporary and will disappear automatically once your call volume returns to normal levels. No manual action is required to clear the warning.

When does the GUI become locked?: The GUI only becomes fully locked if the license limit is exceeded for three or more consecutive days.

What happens if I exceed my license for three consecutive days?

If high usage persists for three consecutive days within the 14-day grace period, the license will be temporarily blocked. To resolve this, you must either:

Delete the CDRs from the spike period via the GUI filter and delete tools (to reset the statistics).
Upgrade your license to a higher channel count via the voipmonitor.org customer portal.
Wait for the next 14-day window - the system allows spikes in different 14-day periods.

Audio & PCAP Files

How can I bulk download audio or PCAP files?: You can use the GUI API to script bulk downloads. Please see the guide: Bulk Download using API.

Why does the GUI download button download the entire merged PCAP instead of only the filtered packets?: This is the current functionality of the GUI download button in the CDR view. When you click to download a PCAP file, it will always include the entire merged packet capture for that call, regardless of any filters or views you have applied in the interface.

Workarounds:

If you need to extract only specific packets, download the full PCAP file and use a tool like Wireshark to apply filters and export the specific packets you need.
For advanced scripting or bulk extraction workflows, you can use the command-line tools described in the Manual PCAP Extraction from spooldir guide.

Why are .wav audio files not generated for calls using non-G.711 codecs (e.g., Opus, G.729)?: The VoIPmonitor sensor can generate audio files (WAV/OGG/MP3) natively for G.711 (a-law/μ-law) codecs. However, for non-G.711 codecs (such as Opus, G.729, G.723, G.726, etc.), the sensor requires an external helper binary named vmcodecs to perform the codec transcoding.

This vmcodecs binary is exclusively distributed within the GUI installation package and is required to create audio files from non-G.711 codec recordings.

To resolve this issue:

Install the GUI package (even if you don't plan to use the web interface). The GUI package includes the necessary vmcodecs binary in <gui-installation-path>/bin/vmcodecs.
Ensure vmcodecs is accessible to the sensor - it must be in a directory that is in the system's $PATH or the sensor's working directory.
Restart the sensor after installing the GUI to apply the changes.
For existing .raw files: Re-process the spooldir content after GUI installation to generate the missing audio files.

Note: Your license key must include support for the specific codec (e.g., Opus Codec Pack) for transcoding to work. Free licenses typically only support G.711.

How do I convert existing WAV audio files to OGG to save space?: If you have existing recordings saved as .wav and wish to convert them to the more efficient .ogg format to save disk space, you can run the following sequence of commands directly in your spool directory (e.g., /var/spool/voipmonitor):

# Navigate to your spool directory first
cd /var/spool/voipmonitor

# Step 1: Find all .wav files and convert each one to .ogg using ffmpeg.
# This command preserves the original filename, only changing the extension.
find ./ -name '*.wav' -exec bash -c 'ffmpeg -i "$0" -vn -acodec libvorbis "${0%.wav}.ogg"' {} \;

# Step 2: After confirming the conversion was successful, delete all the original .wav files.
find ./ -name '*.wav' -exec rm -f {} \;

# Step 3: Set the web server user (e.g., www-data) as the owner of all files.
# This is crucial for the GUI to be able to read and play the new .ogg files.
chown -R www-data:www-data ./

Administration & Troubleshooting

How do I fix "bad gso: type: 1, size: 1448" or kernel errors related to network offloading?; This error appears in the kernel logs when VoIPmonitor is running and indicates an issue with Generic Segmentation Offload (GSO), TCP Segmentation Offload (TSO), or other network interface offload features.

Symptoms:

Kernel messages like: ens3: bad gso: type: 1, size: 1448
Errors may mention UDP Fragmentation Offload (UFO)
Packet capture issues during VoIPmonitor operation

Solution: Disable the offload features on the affected interface:

# Check MTU (should be > 1448, typically 1500)
ip addr show eth0

# Disable offload features (replace ens3 with your interface name)
ethtool -K ens3 gso off tso off gro off lro off

# Verify the change persists (check kernel logs)
dmesg -T | grep -i gso

To make changes persistent across reboots, create a systemd service:

# /etc/systemd/system/disable-offload.service
[Unit]
Description=Disable network offloads for VoIPmonitor
After=network.target

[Service]
Type=oneshot
ExecStart=/usr/sbin/ethtool -K ens3 gso off tso off gro off lro off

[Install]
WantedBy=multi-user.target

# Enable and start the service
systemctl enable disable-offload.service
systemctl start disable-offload.service

If the issue persists after disabling offloads, consider updating the system's kernel and network interface drivers to the latest versions.

How do I reset a lost admin password for the GUI?: Please follow the instructions in the User Management guide.

How do I fix a corrupted GUI installation or reinstall it?: A reinstallation can fix issues with corrupted files or incorrect permissions. See the guide here: Re-install_the_GUI.

The GUI stopped working after a server OS or PHP version upgrade. How do I fix it?: This usually requires re-running the GUI installation script to align with the new PHP version. See: GUI_Installation#Re-installing_the_GUI.

How do I reinstall or upgrade the sniffer to the latest version?: Instructions for downloading and installing the latest static binary are here: Sniffer Installation.

Can I run multiple instances of the sniffer on a single host?: Yes, this is possible for advanced use cases. See the guide: Multiple_sniffer_instancies.

What user actions are recorded in the Audit Log?

The Audit Log tracks the following security-sensitive actions in the GUI:

Login / Logout
Playing or downloading WAV/PCAP files
Showing a FAX
Using the batch download feature
Applying a filter in the CDR view

How do I enable debug mode or troubleshoot GUI issues?: For GUI debugging techniques including enabling debug mode to see SQL queries, please see the GUI Troubleshooting guide.

PCI Compliance

VoIPmonitor is designed to be PCI compliance-ready. You have granular control over what data is stored to disk and to the database.

How do I turn off audio recording and DTMF capture globally?

To prevent RTP (audio) payload from being stored while still capturing headers for analysis, use savertp=header in voipmonitor.conf.
To disable RTP capture entirely, use savertp=no.
To prevent DTMF tones (from SIP INFO or RFC2833) from being saved to the database and PCAP files, use:

dtmf2db = no
dtmf2pcap = no

How do I selectively record or not record audio/DTMF?: VoIPmonitor's powerful Capture Rules allow you to define conditional logic. You can create rules based on IP address, telephone number, SIP domain, or any SIP header to selectively turn audio or DTMF recording ON or OFF for specific calls, enabling you to meet strict compliance requirements.

AI Summary for RAG

Summary: Comprehensive FAQ covering VoIPmonitor configuration and troubleshooting. Topics include: CDR analysis (delay causes, regex filters, custom header search with underscore wildcards), platform support (AWS, Docker, VMWare ESXi VLAN 4095 fix, Azure cloud databases), configuration (SIP ports, IPv6, DTMF, REGISTER messages, domain-based capture rule matching), licensing (concurrent channels, temporary warnings, 3-day lock), audio/PCAP files (bulk download, WAV-to-OGG conversion, vmcodecs requirement for non-G.711 codecs), and PCI compliance (selective recording via capture rules).

Keywords: faq, troubleshooting, cdr, sipport, ipv6, dtmf, license, concurrent calls, aws, docker, vmware, azure, wav, ogg, vmcodecs, pci compliance, capture rules, gso, ethtool, custom header, domain-based capture, exact match

Key Questions:

Why is there a delay between call end and CDR appearance?
How is VoIPmonitor licensing calculated?
What happens if I exceed my license limit?
Why are audio files not generated for non-G.711 codecs?
How do I fix "bad gso" kernel errors?
How do I search for multi-word strings in custom headers?
How do I disable audio recording for PCI compliance?
Can wildcards or regular expressions be used in domain-based capture rules?