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 Network Connectivity Secure DNS Issues	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:

• SQL queue is growing in a peaktime
• Minimizing Delay Between Call End and CDR Database Storage

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 calculates the maximum concurrent calls by averaging over 1-hour periods, and checks this once per day. In distributed environments with multiple sensors feeding a central GUI, a single logical call is counted only once regardless of how many sensors processed it (the system correlates call legs by matching the last 6 digits of the caller and called numbers within a time window).

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:

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

I get an "Invalid or corrupted hwid" error when trying to activate my license. What should I do?

There are two common causes for this error. Check which scenario applies to your situation:

Scenario 1: License key formatting issue (most common)

The license key is a multi-line text block that contains several fields such as Expires, easycallerid, id, and upgradeexpire. A very common mistake is copying only the first line of the key instead of the entire multi-line block.

• Ensure you select and copy the entire license key text (all lines) from your license email or customer portal.
• Paste the complete multi-line key into the activation field in the GUI.
• Do not truncate or remove any lines from the key.

Scenario 2: Hardware ID detection issue

If you have entered the complete license key correctly and still receive this error, the system may be unable to generate or read the hardware ID (HWID). This is most common in specific environments:

• AWS EC2: Run chmod 644 /dev/root to fix permissions on the root device.
• Docker/Containers: Ensure the container ID in /proc/self/cgroup does not change between restarts.
• Corrupted license file: Remove /var/www/html/key.php and re-fetch the license via the "get license key" button in the GUI.

If the above steps do not resolve the issue

If you have verified the license key format and fixed any HWID detection problems, but the error persists, this indicates the license key may have been generated for a different hardware ID. Follow these steps:

• Contact VoIPmonitor support to verify your license and report the error.
• Provide the full multi-line license key when contacting support.
• Support will verify the key and regenerate it to match the correct hardware ID if a mismatch is found.

How do I manually update my license when the automatic update fails?

If the VoIPmonitor server cannot reach the license server due to network restrictions, firewall, or proxy configuration issues, you can manually update the license through the web GUI.

1. Contact VoIPmonitor support to obtain the full, formatted license key.
2. Log in to the VoIPmonitor web GUI.
3. Navigate to Settings > License (or click the "get/update license" button if available).
4. Paste the entire multi-line license key into the provided text field.
5. Save the changes to apply the new license.

Important: Make sure you copy the complete license key including all lines (Expired, easycallerid, hwid, id, maxcalls, upgradeexpire, etc.). Truncating or omitting lines will cause activation errors. See the question above about "Invalid or corrupted hwid" for more details about license key formatting.

For persistent connectivity issues preventing automatic license updates, see FAQ#How_do_I_troubleshoot_internet_connectivity_issues for network and proxy configuration troubleshooting.

What happens to my license if I stop and restart an AWS instance?

If you stop and start an AWS EC2 instance, the hardware ID typically remains the same, so your license will continue to work. However, if you terminate the instance and launch a new one, the hardware ID will change and you will need a new license key. Automatic re-issuance is not available - you must contact support to obtain a new license.

Can I license VoIPmonitor based on a URL/domain instead of hardware ID?

Yes, as an alternative to hardware binding, you can request that your license be locked to a URL domain (for web-based deployments). Contact VoIPmonitor support to configure domain-based licensing if you have a scenario where hardware binding is impractical (e.g., frequently changing infrastructure or cloud deployments).

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:

1. 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.
2. 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.
3. Restart the sensor after installing the GUI to apply the changes.
4. 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.

How do I troubleshoot internet connectivity issues (cannot download updates, source code, or access external resources)?

If the sensor server cannot connect to external resources such as download servers, GitHub, or package repositories, follow this troubleshooting process:

Step 1: Verify basic network connectivity

# Test if the server can reach external hosts
ping -c 4 8.8.8.8

# Test DNS resolution
ping -c 4 google.com

If these commands fail, the issue is with network configuration or routing. Check:

• Network interface configuration: ip addr show
• Default gateway: ip route show
• DNS configuration: cat /etc/resolv.conf

Step 2: Check firewall rules for outbound connections

# Check if firewalld is being used
systemctl status firewalld

# List open ports if using firewalld
firewall-cmd --list-ports

# Check iptables rules if applicable
iptables -L -n | grep -E "ACCEPT|REJECT|DROP"

Ensure that outbound connections on HTTP (port 80) and HTTPS (port 443) are not blocked. The server needs to reach:

• download.voipmonitor.org (for software downloads)
• github.com (for source code)
• Package repository servers (dnf/yum/apt repositories)

Step 3: Test connectivity to specific hosts

# Test HTTPS connectivity to GitHub
curl -I https://github.com

# Test connectivity to VoIPmonitor download server
curl -I https://www.voipmonitor.org

# Test package repository (for RHEL/CentOS/AlmaLinux)
dnf repolist

# Test package repository (for Debian/Ubuntu)
apt-get update

If curl commands time out or fail, check for:

• Proxy server requirements (corporate networks often require HTTP proxy)
• Firewall rules blocking outbound HTTPS
• Network routing issues

Step 4: Configure HTTP proxy (if required by your network)

If your network requires a proxy server, configure the curlproxy parameter in /etc/voipmonitor.conf to enable sensor updates and downloads:

[general]
# Replace with your actual proxy address and port
curlproxy = http://proxy-server-ip:port

Then restart the sensor:

systemctl restart voipmonitor

Alternative: Use environment-wide proxy settings

For package managers and system-wide proxy access, configure environment variables:

# Set system-wide proxy (add to /etc/profile or /etc/environment)
export http_proxy="http://proxy-server-ip:port"
export https_proxy="http://proxy-server-ip:port"

# For package managers, configure in their settings files
# RHEL/CentOS/AlmaLinux: /etc/dnf/dnf.conf
proxy=http://proxy-server-ip:port

# Debian/Ubuntu: /etc/apt/apt.conf
Acquire::http::Proxy "http://proxy-server-ip:port";

I receive NXDOMAIN errors for VoIPmonitor-related domains only when Secure DNS (DNS-over-HTTPS/TLS) is enabled in my browser. How do I troubleshoot this?

NXDOMAIN errors that occur only when Secure DNS is enabled typically indicate an issue with the specific secure DNS provider rather than the actual domain resolution. Secure DNS providers may have caching issues, incomplete records, or temporary outages that differ from standard DNS resolution.

Diagnostic steps:

1. Check which secure DNS provider is configured in your browser (Chrome: navigate to chrome://settings/security and look under "Use secure DNS")

2. Verify the issue occurs only with Secure DNS enabled by temporarily disabling it and confirming the domain resolves normally

3. Test standard DNS resolution from the command line to confirm the domain is valid:

dig www.voipmonitor.org

4. Test DNS-over-HTTPS resolution directly against a provider's API to isolate the issue:

# Test Google's DNS-over-HTTPS API
curl -s "https://dns.google/resolve?name=www.voipmonitor.org&type=A" | jq

If dig successfully resolves the domain but Chrome Secure DNS fails, the issue is with your configured secure DNS provider. Try switching to an alternative secure DNS provider (e.g., switch from Cloudflare to Google, or vice versa) in your browser settings.

If direct DoH queries (via curl) also fail, this indicates a temporary issue with that DNS provider's service. Switching providers typically resolves the problem.

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 calculated over 1-hour periods checked once daily, distributed call correlation, 3-day lock, AWS instance lifecycle - stop/start preserves HWID but terminate/launch requires new license, no automatic re-issuance, option for domain-based license binding instead of HWID, "invalid or corrupted hwid" error - multi-line license key formatting, HWID detection issues, AWS EC2 permissions, Docker container persistence, corrupted key.php, contact support for hwid mismatch resolution, manual license updates via GUI when automatic updates fail due to network/firewall issues), audio/PCAP files (bulk download, WAV-to-OGG conversion, vmcodecs requirement for non-G.711 codecs), PCI compliance (selective recording via capture rules), network connectivity troubleshooting (ping, DNS, firewall rules, curlproxy configuration for HTTP proxy, package manager proxy settings), and secure DNS troubleshooting (NXDOMAIN errors with DNS-over-HTTPS/TLS, browser configuration, alternative DNS providers).

Keywords: faq, troubleshooting, cdr, sipport, ipv6, dtmf, license, concurrent calls, 1-hour averaging, distributed environment, call correlation, aws, docker, vmware, azure, wav, ogg, vmcodecs, pci compliance, capture rules, gso, ethtool, custom header, domain-based capture, exact match, invalid hwid, corrupt hwid, license key, multi-line key, hwid mismatch, contact support, license regeneration, domain-based licensing, url binding, aws instance lifecycle, manual license update, gui license update, network connectivity, internet access, curlproxy, proxy, firewall, ping, dns, github, download server, secure dns, dns-over-https, dns-over-tls, nxdomain, chrome, dns provider, dig, curl, doh

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?
• How often is the concurrent call limit checked?
• How are calls counted in distributed environments with multiple sensors?
• How do I fix "Invalid or corrupted hwid" error when activating a license?
• What should I do if troubleshooting steps do not resolve the hwid error?
• What happens to my license if I stop and restart an AWS instance?
• Can I license VoIPmonitor based on a URL/domain instead of hardware ID?
• How do I manually update my license when the automatic update fails?
• 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?
• How do I troubleshoot internet connectivity issues?
• I receive NXDOMAIN errors only when Secure DNS is enabled in my browser. How do I fix this?