FAQ

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

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

A feature request has been created for consideration in a future version, but there is no ETA for its implementation.

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

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.

A feature request to support downloading only filtered packets has been noted for consideration in a future version.

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. These errors can cause packet capture problems.

Symptoms:

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

Solutions:

Check interface MTU size:

# Verify MTU is greater than 1448 (common default is 1500)
ip addr show eth0
# or
ifconfig eth0

Disable GSO on the affected interface:

ethtool -K ens3 gso off

Replace `ens3` with your actual interface name.

Try disabling other offload features if GSO alone doesn't work:

# Disable TSO (TCP Segmentation Offload)
ethtool -K ens3 tso off

# Disable UFO (UDP Fragmentation Offload)
ethtool -K ens3 ufo off

# Disable Generic Receive Offload (GRO)
ethtool -K ens3 gro off

# Disable LRO (Large Receive Offload)
ethtool -K ens3 lro off

Make changes persistent across reboots:

Add the commands to a network interface configuration script or a systemd service. Example systemd service approach:

# Create service file: /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 ufo 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

Alternative: Add to network interface configuration:

On systems using NetworkManager or network scripts, you can add a post-up command to your interface configuration.

Check kernel logs for persistence:

# Monitor for GSO errors after fixes
dmesg -T | grep -i gso
tail -f /var/log/kern.log | grep -i gso

Update kernel and drivers:

If the issue persists after disabling offloads, consider updating the system's kernel and network interface drivers to the latest versions, as this may be a driver bug that has been fixed in newer releases.

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

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: This document serves as a comprehensive FAQ and troubleshooting guide for common VoIPmonitor issues. It covers a wide range of topics, including call data and CDR analysis (red icons, regex filters, CDR delay), platform support (AWS, Docker, VMWare ESXi, cloud databases like Azure), system configuration (monitoring multiple SIP ports, IPv6, DTMF), and licensing (channel calculation, handling spikes, temporary warnings that self-clear). It also provides solutions for managing audio files (bulk download, WAV to OGG conversion), and important troubleshooting information about non-G.711 codec audio file generation (noting that the `vmcodecs` binary from the GUI package is required for transcoding). Administrative tasks including resetting passwords, reinstalling the GUI or sniffer, and understanding the Audit Log are covered. A key section addresses PCI compliance, detailing how to selectively or globally disable audio and DTMF recording using capture rules and configuration settings. For GUI debugging and troubleshooting, see the separate GUI_troubleshooting page. The troubleshooting section now includes instructions for resolving kernel GSO/offload errors (e.g., "bad gso: type: 1, size: 1448") that appear when VoIPmonitor is running. The "Audio & PCAP Files" section includes information on why the GUI download button downloads the entire merged PCAP instead of filtered packets, with workarounds using Wireshark or command-line extraction tools. Keywords: faq, troubleshooting, cdr, red icon, regex, active calls, aws, docker, container, esxi, vlan 4095, azure, super privilege, sipport, ipv6, dtmf, license, concurrent channels, license spike, temporary warning, self-clearing warning, three consecutive days, audio files, bulk download, wav, ogg, ffmpeg, vmcodecs, codec transcoding, non-g711, opus, g729, g723, g726, gui installation, pci compliance, capture rules, savertp, dtmf2db, audit log, reinstall, lost password, multiple instances, gso, tso, ufo, ethtool, bad gso, kernel error, network offload, mtu, custom header, multi-word search, space OR operator, underscore wildcard, concurrent calls per ip, ip group, chart series, report generator, call summary, download button, gui download, entire pcap, filtered packets, wireshark, packet extraction, feature request Key Questions:

Why is there a delay between active calls and the CDR view?
How is VoIPmonitor licensing calculated for concurrent channels?
What happens if my call traffic exceeds my license limit?
Will the license warning disappear automatically?
When does the GUI become locked after exceeding license limits?
How can I run VoIPmonitor in Docker or on AWS?
Why is packet sniffing not working on my VMWare ESXi server?
How do I enable monitoring for SIP traffic on a non-standard port?
How can I convert all my recorded WAV files to OGG to save space?
Why does the GUI download button download the entire merged PCAP instead of only filtered packets?
Why are .wav audio files not generated for calls using non-G.711 codecs?
What is the vmcodecs binary and why is it needed for codec transcoding?
How do I selectively disable audio recording for certain calls to be PCI compliant?
How do I enable IPv6 support on a system with existing data?
How do I capture SIP REGISTER messages?
How do I search for multi-word strings in custom header fields using wildcards?
How do I fix "bad gso: type: 1, size: 1448" kernel errors when VoIPmonitor is running?
Can I generate a report of concurrent calls broken down by individual source IP address?