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 MySQL Support Network Connectivity Secure DNS Issues Missing Database Tables MariaDB System Table Corruption After OS Upgrade Missing Database Columns	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.

Can I run multiple GUI instances for redundancy or external access?

Yes, you can run multiple GUI instances pointing to the same database and storage. This is useful for creating a second externally accessible GUI (e.g., in a DMZ) or for GUI redundancy while keeping your sensors and database safely within your internal network.

Setup requirements:

• Database access: All GUI instances must connect to the same MySQL/MariaDB database. Ensure the database allows remote connections from each GUI's IP address.
• PCAP storage access: Each GUI needs access to the PCAP files. This is typically achieved via NFS/SSHFS mounting from the primary storage server.
• License configuration: Copy your existing license file (key.php) to each GUI server. If the hardware IDs differ, contact VoIPmonitor support to add the additional HWIDs to your license token.

CRITICAL: Cron Job Conflict

Alerts and daily reports are generated by a cron job that runs every minute on the GUI server. If you enable this cron job on multiple GUI instances, you will receive duplicate alerts and reports.

To prevent conflicts:

1. Enable the cron job on only one GUI instance (typically your primary internal GUI for active monitoring).
2. Disable the cron job on all secondary/redundant GUI instances.
3. Verify that the cron job exists in /etc/crontab or system cron configuration on each server.
4. Comment out or remove the cron line on secondary servers:

# On secondary GUI servers - DISABLE the cron job
# * * * * * root php /var/www/html/php/run.php cron

The GUI without the cron job will still function for viewing data, searching calls, and manual report generation - it simply will not process automated alerts or daily scheduled reports.

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

Why do caller and called numbers appear swapped in the CDRs?

VoIPmonitor extracts caller and called numbers from the SIP INVITE packet using specific header sources. By default:

• Caller number: Taken from the From header
• Called number: Taken from the To header (default mode)

If the numbers appear swapped, verify the following:

1. Check Default Behavior First, verify this is not simply a misunderstanding of how VoIPmonitor extracts the numbers. The default extraction uses:

• Caller = From header
• Called = To header

You can verify this by opening a call detail in the GUI, navigating to the SIP History tab, and inspecting the From and To headers in the first INVITE packet.

2. Adjust destination_number_mode Configuration If your PBX or SIP devices use a different convention for distinguishing caller/called numbers, you can change the source for the called number in voipmonitor.conf:

[general]
# Default: 1 = To header
# Alternative: 2 = INVITE URI
destination_number_mode = 1

Set destination_number_mode = 2 to use the INVITE Request-URI as the source for the called number instead of the To header. This may resolve swapped number issues in certain PBX configurations.

3. Check for Override Headers Some SIP headers can forcibly update the caller/called numbers. If these are misconfigured, they can cause swapped numbers:

• remoteparty_caller / remoteparty_called - Update numbers from Remote-Party-ID header
• passertedidentity = yes - Use P-Asserted-Identity header for caller
• ppreferredidentity = yes - Use P-Preferred-Identity header for caller

If these options are enabled, try disabling them or verify that the SIP headers contain the correct values:

[general]
# Comment out or remove to disable
# remoteparty_caller = calling
# remoteparty_called = called
# passertedidentity = no
# ppreferredidentity = no

4. Apply Configuration Changes After editing voipmonitor.conf, restart the sensor service:

systemctl restart voipmonitor

5. Test and Verify Generate a new test call and check the CDR to see if the numbers are now correctly assigned to caller and called fields.

For more detailed configuration options, see the Caller/Called Identity Configuration section of the Sniffer Configuration guide.

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 MySQL reporting a deprecation warning for mysql_native_password? Can I use caching_sha2_password?

MySQL 8.0 and MySQL 8.4+ (default in Ubuntu 24.04, Debian 12/13, Rocky 9, etc.) default to caching_sha2_password authentication and display deprecation warnings when the older mysql_native_password method is used.

Short Answer: You do not need to force mysql_native_password if your PHP version is 7.4.4 or newer. The VoIPmonitor GUI automatically supports caching_sha2_password when using a modern PHP version with the mysqlnd driver.

Recommended Solution (Best Practice)::# Upgrade your PHP version to 7.4.4 or newer (recommended: 8.0, 8.1, 8.2, or 8.3).

1. Reinstall the IonCube Loader for your new PHP version. See GUI Installation Guide - Step 3.
2. Reinstall the VoIPmonitor GUI. See GUI Installation Guide - Reinstalling.

After this upgrade, the GUI will automatically use the authentication method configured for your database user (no additional configuration needed). Remove any default_authentication_plugin=mysql_native_password lines from your MySQL configuration.

Alternative Solution (Legacy PHP)::If you must use an older PHP version (before 7.4.4), you can force mysql_native_password by adding the following to your MySQL configuration file:

# /etc/mysql/mysql.conf.d/mysqld.cnf (or /etc/my.cnf.d/mysql-server.cnf on RHEL-based systems)
default_authentication_plugin=mysql_native_password

After making changes, restart the MySQL service and recreate your database user using the old method:

ALTER USER 'voipmonitor'@'127.0.0.1' IDENTIFIED WITH mysql_native_password BY 'YourPassword';
FLUSH PRIVILEGES;

⚠️ Warning: This alternative approach suppresses the warning but uses a deprecated authentication method. Upgrading PHP to 7.4.4+ is strongly recommended for security reasons.

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

Why are RTP packets not associated with the correct call legs after moving SIP and RTP to different NICs or VLANs?

This typically occurs when SIP signaling and RTP media arrive on different network interfaces, NICs, or VLANs, and the packet correlation logic needs adjustment.

Root Cause: When SIP and RTP traffic paths change (e.g., SIP on eth0/VLAN 10 and RTP on eth1/VLAN 20), the sniffer may incorrectly match RTP packets to call legs if the internal packet buffering and defragmentation logic is not optimized for multi-interface scenarios.

Solution: Set auto_enable_use_blocks = yes in /etc/voipmonitor.conf and restart the sniffer service:

# Edit configuration
echo "auto_enable_use_blocks = yes" >> /etc/voipmonitor.conf

# Restart sniffer
systemctl restart voipmonitor

This option enables memory blocks for proper packet processing across multiple interfaces. It is required in two scenarios: (1) deduplication when receiving duplicate packets from multiple sources, and (2) correct RTP association when SIP and RTP arrive on different interfaces, NICs, or VLANs. See Sniffer Configuration for details.

Additional Checks:

• Verify interface in voipmonitor.conf includes all relevant NICs (e.g., interface = eth0,eth1)
• Check vlan_siprtpsame = no (allows different VLANs for SIP and RTP)
• If IP addresses changed due to NAT, configure natalias for proper mapping

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. Request a temporary, complimentary license increase from VoIPmonitor support - support can apply a temporary boost to your licensed channel count (e.g., for two weeks) to immediately unlock your GUI. After you update the license, the temporary increase will automatically revert to your original limit after the specified period.
4. 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).

How do I determine which license key belongs to which instance when I have multiple keys?

If you have multiple VoIPmonitor instances and multiple license keys, you can identify which key belongs to which already-licensed instance using the License ID shown in the GUI and the Services section of the voipmonitor.org customer portal.

1. Log in to the GUI of the already licensed VoIPmonitor instance.
2. Navigate to Settings > License and note the License ID displayed in the license information.
3. Log in to the voipmonitor.org customer portal and navigate to Services > My Services.
4. Identify the License IDs for your available license keys in the customer portal.
5. Find the license key that has the same License ID as the one you noted from the GUI - this key activates that specific instance.
6. Apply the license key with the different License ID** to the unlicensed instance you want to license.

This method allows you to systematically match each license key to its corresponding instance without trial-and-error.

Can I use my license on multiple servers (e.g., for a test/development environment)?

Yes, VoIPmonitor support can reconfigure your existing license token to be valid on multiple servers. This is useful for licensing a test or development environment without incurring additional costs.

To enable multi-server licensing:

1. Contact VoIPmonitor support via the customer portal or email
2. Specify that you need your license configured for multiple servers (mention it is for test/dev environment)
3. Provide the server ID (hardware ID) for each server where you will use the license
4. Support will reconfigure your license token to accept all specified servers

Once reconfigured, you can use the same license key on all authorized servers. This is typically provided at no additional cost for test/development environments, though support team approval is required.

Note: If you need a license for a completely new installation without an existing license, VoIPmonitor provides a 30-day trial license. You can obtain a trial license from the voipmonitor.org customer portal (logged in users) or by contacting support directly.

What should I do if my VoIPmonitor license has expired due to non-payment?

If your license has expired because of payment processing delays or other payment issues, you can prevent service interruption by requesting an emergency trial license.

Immediate Recovery Steps:

1. Contact VoIPmonitor support immediately to request a 30-day emergency trial license for your server.
2. Provide your server ID (hardware ID) when requesting the emergency trial license.
3. Once support generates the trial license token, apply it to your GUI by navigating to Settings > License and pasting the trial license key.
4. The trial license will restore full functionality for 30 days, giving you time to resolve the payment issue.

Important Considerations:

• This emergency trial license is a temporary measure to prevent service interruption while payment is being processed.
• After completing the payment for your permanent license renewal, you will need to replace the trial license key with your new permanent license key.
• Contact support again after payment completion to receive your permanent license key.

To verify your license status after applying the trial license, navigate to Tools > System Status > License in the GUI or run the license check command:

php /var/www/html/php/run.php checkLicense -v

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.

Why is audio playback garbled or distorted?

If audio recordings play but sound garbled, distorted, or unintelligible, the most common cause is DTLS-SRTP encryption on the RTP streams. Without proper decryption keys, VoIPmonitor cannot decode the encrypted media, resulting in audio that sounds like noise or static.

How to Identify DTLS-SRTP Encrypted Calls:

Check the SIP signaling (INVITE message) for the following indicators:

• SDP crypto attributes: Look for a=crypto lines in the SDP which indicate SRTP encryption
• DTLS fingerprint: Look for a=fingerprint or a=setup attributes which indicate DTLS-SRTP negotiation
• RTP encryption:** Encrypted packets will appear as random data when viewed in Wireshark

Solution: Configure DTLS-SRTP Decryption**

To enable audio playback for encrypted calls, VoIPmonitor must have access to the decryption keys. This is achieved using the SSL Key Logger method.

1. The SSL Key Logger is installed on the SBC or PBX that terminates the calls

2. It captures DTLS session keys from memory using the LD_PRELOAD mechanism

3. Keys are sent over the network to the VoIPmonitor sensor

4. VoIPmonitor uses these keys to decrypt the DTLS handshake and derive SRTP master keys

For detailed setup instructions, see the Tls documentation, specifically the Method 2: SSL Key Logger section. The guide covers:

• Compiling the sslkeylog.so library
• Configuring Asterisk, Kamailio, FreeSWITCH, or other SIP applications
• Setting up VoIPmonitor to receive session keys
• Correct ssl_ipport syntax for key logger mode
• TCP mode for secure key transport

Common Configuration Pitfalls:

• Wrong ssl_ipport syntax:** When using SSL Key Logger, ssl_ipport must NOT include a path to a key file (e.g., ssl_ipport = 192.168.1.50:5061 is correct, but ssl_ipport = 192.168.1.50:5061 /path/to/key.pem will fail)
• Keys sent to wrong destination:** In distributed architectures with packetbuffer_sender=yes, keys must go to the central server IP, not localhost or the remote client sensor
• PBX not configured: The PBX/SBC must have sslkeylog.so preloaded via LD_PRELOAD or equivalent mechanism

Distinguishing From Other Audio Issues:

If audio is completely silent or WAV files are not generated for non-G.711 codecs (Opus, G.729, etc.), see the previous FAQ entry about the vmcodecs binary. The vmcodecs issue is about missing transcoding capability, while garbled audio typically indicates encryption.

Why are call durations truncated and RTP streams delayed after importing PCAP files into a new VoIPmonitor instance?

This issue typically occurs when the import environment configuration does not match the original probe configuration, particularly for NAT-related settings.

Root Cause: When processing PCAP files, the sniffer needs the same NAT configuration as the original capture probe to correctly correlate call legs. Missing NAT configuration can cause:

• Truncated calls: Call ends prematurely because the cleanup logic triggers incorrectly
• RTP delays/graph errors: Jitter buffer simulation becomes unsynchronized

Solution:

1. Mirror the original probe configuration

Ensure the import configuration file mirrors the original probe settings, except for options like bind.

2. Add natalias configuration

Add the natalias option to the import configuration to map public IPs to private IPs:

natalias = 1.1.1.1 10.0.0.3
natalias = 2.2.2.2 10.0.0.4

Multiple natalias lines can be used if multiple NAT mappings are required. See NAT Configuration in the sniffer configuration reference.

3. Check GUI/DB Settings priority

Settings in Settings -> Sensors in the GUI have higher priority than voipmonitor.conf. If id_sensor is set in the config file, ensure that:

• The sensor entry in Settings > Sensors has matching configuration
• NAT-related settings are also configured in the GUI if database is managing sensor settings
• The GUI does not override your config file settings

Verification: After applying these configuration changes, re-import or re-process the PCAP files and verify that:

• Call durations match the expected length
• RTP streams are synchronized in the graph view
• No RTP delays or gaps appear in the audio playback

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

The 'live play' audio feature is disabled in the GUI. How do I re-enable it?

If the live play functionality for listening to active calls is disabled or the play buttons are not visible in the Active Calls view, this is controlled by a PHP configuration constant in the GUI configuration file.

To re-enable live play:

1. Access the GUI host server via SSH or terminal.
2. Edit the configuration file located at:

/var/www/html/voipmonitor/configuration.php

(The path may vary slightly depending on your installation, typically under /var/www/html/ or /var/www/)

1. Find the DISABLE_LIVEPLAY constant:

define('DISABLE_LIVEPLAY', true);

1. Change the value from true to false:

define('DISABLE_LIVEPLAY', false);

1. Save the file and exit the editor.
2. Log out of the GUI and log back in to see the play buttons for compatible active calls (typically G.711 a-law and μ-law codecs).

Note: Live playback requires the sensor to be actively capturing calls with G.711 codec. Other codecs may not be supported for live listening.

If you encounter performance issues after enabling live play (high CPU usage during busy call periods), you can revert the change by setting the value back to true.

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.

Missing Database Tables

VoIPmonitor logs errors that required database tables do not exist and fails to create them on restart. How do I fix this?

If the VoIPmonitor sensor logs errors indicating that required database tables (such as cdr_stat_values, cdr_problems_by_ip, or others) do not exist and the service fails to create them automatically on startup, follow these steps to resolve the issue.

Common Error Messages:

• Table 'cdr_problems_by_ip' doesn't exist
• Table 'cdr_stat_values' doesn't exist
• Errors during database initialization or schema creation

Step 1: Check Database Privileges

The MySQL/MariaDB user configured in voipmonitor.conf (the mysqlusername parameter) must have privileges to create and alter database schema.

1. Log in to your MySQL/MariaDB console:

mysql -u root -p

1. Check the current privileges for the VoIPmonitor user:

SHOW GRANTS FOR 'voipmonitor'@'localhost';

1. If the user lacks CREATE, ALTER, or DROP privileges, grant them:

GRANT ALL PRIVILEGES ON voipmonitor.* TO 'voipmonitor'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Step 2: Check the disable_dbupgradecheck Configuration

If the disable_dbupgradecheck option is enabled in voipmonitor.conf, the sensor will skip the automatic database schema upgrade and table creation process.

1. Open your configuration file:

nano /etc/voipmonitor.conf

1. Search for disable_dbupgradecheck. Ensure it is either commented out or set to no:

# disable_dbupgradecheck = yes  <-- Comment this out or set to 'no'
disable_dbupgradecheck = no

1. Save the file and exit the editor.

Step 3: Restart the Service and Monitor Logs

After correcting privileges and configuration, restart the sensor and watch the logs:

# Restart the service
systemctl restart voipmonitor

# Monitor the initialization process
journalctl -u voipmonitor -f

You should see messages indicating the creation of functions, partitions, and tables. If errors persist, proceed to Step 4.

Step 4: Manual Table Recreation (If Auto-Creation Fails)

In some cases, tables may be in a corrupted state or the automatic creation process may repeatedly fail. In these situations, manually dropping and recreating the tables is required.

1. Connect to the database:

mysql -u voipmonitor -p voipmonitor

(Replace voipmonitor with your actual database name and username if different.)

1. Drop the problematic tables if they exist:

DROP TABLE IF EXISTS cdr_problems_by_ip;
DROP TABLE IF EXISTS cdr_stat_values;

1. Manually recreate the tables using the correct CREATE TABLE SQL statements. You can obtain the schema definition from:

• The Tools -> System Status -> Check MySQL Schema option in the Web GUI (if accessible)
• A working VoIPmonitor installation of the same version
• VoIPmonitor support

1. After recreating the tables, exit MySQL:

EXIT;

1. Restart the VoIPmonitor sensor:

systemctl restart voipmonitor

Step 5: Verify the Fix

Check that the sensor is running without table-related errors:

# Check service status
systemctl status voipmonitor

# Monitor logs for any errors
journalctl -u voipmonitor -f

The errors regarding missing tables should cease, and the sensor should operate normally.

Prevention:

• Ensure the database user always has sufficient privileges (ALL PRIVILEGES on the VoIPmonitor database schema).
• Keep disable_dbupgradecheck disabled (no or commented) to allow automatic schema updates.
• Monitor database upgrade logs after VoIPmonitor version updates to catch schema issues early.

MariaDB System Table Corruption After OS Upgrade

After upgrading the OS (e.g., Debian 11 to 13) and reinstalling VoIPmonitor, MariaDB reports errors about incorrect table definitions in the system mysql database (e.g., mysql.column_stats) and VoIPmonitor fails to create routines due to insufficient user privileges. How do I fix this?

This issue occurs because:

• A major OS upgrade typically installs a newer version of MariaDB (e.g., MariaDB 10.11+ on Debian 13)
• The existing MariaDB system databases may not be fully compatible or may be corrupted
• The voipmonitor database user may lack the required privileges for the new MariaDB version

Common Error Messages:

• Table 'mysql.column_stats' doesn't exist
• Incorrect table definition; there can be only one auto column and it must be defined as a key
• CREATE FUNCTION command denied to user 'voipmonitor'@'...' for table '...'

Solution: Reinitialize MariaDB System Databases

⚠️ Warning: This procedure will delete all MariaDB databases and their data. The VoIPmonitor database will need to be recreated. If you need to preserve existing data, export it first using mysqldump.

1. Stop the MariaDB service:

systemctl stop mariadb

1. Backup the MariaDB data directory (if you need to preserve any data):

cp -a /var/lib/mysql /var/lib/mysql.backup

1. Delete the entire MariaDB data directory:

rm -rf /var/lib/mysql/* /var/lib/mysql/.* 2>/dev/null || true

1. Start the MariaDB service to reinitialize system databases cleanly:

systemctl start mariadb

The service will create fresh system databases (mysql, information_schema, performance_schema, etc.).

1. Create the VoIPmonitor database user with correct privileges:

mysql

Once in the MySQL console, run:

CREATE USER 'voipmonitor'@'127.0.0.1' IDENTIFIED BY 'YourPassword';
GRANT ALL ON voipmonitor.* TO 'voipmonitor'@'127.0.0.1';
GRANT SUPER ON *.* TO 'voipmonitor'@'127.0.0.1';
FLUSH PRIVILEGES;

ℹ️ Note: The GRANT SUPER privilege is required for VoIPmonitor to create stored procedures and triggers in newer MariaDB versions.

1. Create the VoIPmonitor database:

CREATE DATABASE voipmonitor;
EXIT;

1. Restart VoIPmonitor services:

systemctl restart voipmonitor

On startup, the sensor will automatically create the required tables, functions, and triggers in the new database.

Alternative: Configure MariaDB Without SUPER Privilege

⚠️ Warning:

1. Edit the MariaDB server configuration:

nano /etc/mysql/mariadb.conf.d/50-server.cnf

1. Add the following line under the [mysqld] section:

[mysqld]
log_bin_trust_function_creators = ON

1. Restart MariaDB to apply the change:

systemctl restart mariadb

Prevention:

• After major OS upgrades, check MariaDB system table compatibility before reinstalling VoIPmonitor
• Run mariadb-upgrade (or mysql_upgrade on older systems) to update system databases if not performing a full reinitialization
• Ensure the voipmonitor database user has appropriate privileges for your MariaDB version

Missing or Outdated Database Columns

A 'Server side error' pop-up appears in the GUI with the message 'Unknown column [table].[column] in 'field list. How do I fix this?

This error occurs when the database schema is out of sync with the installed GUI or Sniffer version. The application expects a column that does not exist in the current database. This typically happens after an update where the automatic schema upgrade was skipped or failed.

Common Error Messages:

• Unknown column 'Sensors.color_rowview' in 'field list'
• Unknown column 'cdr.new_field_name' in 'field list'
• Any error referencing a missing column in a table that exists

Solution: Check and Repair Tables via GUI

The fastest way to fix missing or outdated database columns is to use the built-in table repair feature in the VoIPmonitor GUI:

1. Open the VoIPmonitor GUI in your web browser
2. Add ?check_tables=1 to the end of the URL in the address bar

• Example: http://<your_gui_ip>/admin.php?check_tables=1
• Example with hostname: https://voipmonitor.example.com/admin.php?check_tables=1

1. Press Enter to load the URL
2. Wait for the table check and repair process to complete
3. Navigate back to the section where the error occurred (e.g., CDR view) to verify the fix

The ?check_tables=1 parameter triggers an automatic database schema check and repair process. This will add any missing columns, update table structures, and ensure your database matches the expected schema for your software version.

If the Error Persists:

If the ?check_tables=1 solution does not resolve the issue:

1. Ensure the database user has ALTER privilege on the VoIPmonitor database. See the Missing Database Tables section for instructions on checking and granting privileges.
2. Check that disable_dbupgradecheck is not enabled in voipmonitor.conf (see Missing Database Tables).
3. Restart the VoIPmonitor sensor after applying ?check_tables=1:

   systemctl restart voipmonitor
   

4. Check the sensor logs for schema validation errors:

   journalctl -u voipmonitor -f
   

Prevention:

• Run ?check_tables=1 after every major VoIPmonitor GUI or Sniffer update to ensure the database schema is synchronized.
• Keep disable_dbupgradecheck disabled to allow automatic schema updates.
• Monitor database upgrade logs after software updates.

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, multi-server licensing - support can reconfigure existing license token to be valid on multiple servers for test/dev environment at no cost, 30-day trial licenses for new installations, emergency trial license for expired licenses due to non-payment - contact support immediately, provide server ID, apply trial key in GUI Settings > License, replace with permanent license after payment completion, verify with checkLicense -v command, determining which license key belongs to which instance using License ID from GUI Settings > License and voipmonitor.org Services > My Services, "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, garbled/distorted audio due to DTLS-SRTP encryption - requires SSL Key Logger on SBC/PBX to capture decryption keys, identify via SDP a=crypto, a=fingerprint, or a=setup attributes, see Tls documentation for full setup instructions, common pitfalls like wrong ssl_ipport syntax when using key logger), PCAP import issues (truncated calls and RTP delays due to missing natalias/GUI override), PCI compliance (selective recording via capture rules), network connectivity troubleshooting (ping, DNS, firewall rules, curlproxy configuration for HTTP proxy, package manager proxy settings), secure DNS troubleshooting (NXDOMAIN errors with DNS-over-HTTPS/TLS, browser configuration, alternative DNS providers), database troubleshooting (missing tables like cdr_stat_values and cdr_problems_by_ip, manual table recreation with DROP TABLE and CREATE TABLE, database privileges, disable_dbupgradecheck configuration, MariaDB system table corruption after OS upgrades - requires deleting /var/lib/mysql directory to reinitialize, creating voipmonitor user with SUPER privilege or configuring log_bin_trust_function_creators = ON, missing database columns fixed by ?check_tables=1 URL parameter), and multiple GUI instances for redundancy or external access - enable cron job on only one GUI to prevent duplicate alerts and reports.

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, license id, multiple instances, multiple license keys, multi-server, test environment, development environment, dev license, trial license, 30-day license, emergency trial license, license expired, expired license, non-payment, payment issue, temporary license, service interruption, missing database tables, table doesn't exist, drop table, create table, database privileges, disable_dbupgradecheck, mysql privileges, database schema, corrupted tables, unknown column, missing column, server side error, check_tables, check_tables=1, field list error, database schema upgrade, mariadb system table corruption, os upgrade, debian upgrade, column_stats, incorrect table definition, mariadb-upgrade, delete var/lib/mysql, reinitialize mariadb, super privilege, log_bin_trust_function_creators, create function, create trigger, multiple gui, redundant gui, backup gui, second gui, external gui, dmz gui, gui redundancy, cron job, duplicate alerts, cronjob, alerts conflict, reports conflict, nfs, sshfs, pcap import, mysql_native_password, caching_sha2_password, mysql authentication, php 7.4.4, truncated calls, rtp delays, natalias, gui settings config priority, rtp association, wrong call leg, different nic, different vlan, auto_enable_use_blocks, interface multiple, vlan_siprtpsame

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?
• Can I use my license on multiple servers (test or development environment)?
• How do I get a trial license for VoIPmonitor?
• What should I do if my VoIPmonitor license has expired due to non-payment?
• Why are audio files not generated for non-G.711 codecs?
• Why is audio playback garbled or distorted?
• How do I fix "bad gso" kernel errors?
• How do I search for multi-word strings in custom headers?
• How do I determine which license key belongs to which instance when I have multiple keys?
• 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?
• VoIPmonitor logs errors that required database tables do not exist and fails to create them on restart. How do I fix this?
• After upgrading the OS and reinstalling VoIPmonitor, MariaDB reports errors about incorrect table definitions in the system mysql database and fails to create routines due to insufficient user privileges. How do I fix this?
• The 'live play' audio feature is disabled in the GUI. How do I re-enable it?
• A 'Server side error' pop-up appears in the GUI with the message 'Unknown column [table].[column] in 'field list. How do I fix this?
• Why is MySQL reporting a deprecation warning for mysql_native_password? Can I use caching_sha2_password?
• Can I run multiple GUI instances for redundancy or external access?
• Why are call durations truncated and RTP streams delayed after importing PCAP files into a new VoIPmonitor instance?