FAQ: Difference between revisions

From VoIPmonitor.org
(Add FAQ for MariaDB system table corruption after OS upgrade (Debian 11 to 13))
(Add clarification about on-demand audio extraction vs saveaudio option)
 
(108 intermediate revisions by the same user not shown)
Line 2: Line 2:
[[Category:GUI manual]]
[[Category:GUI manual]]


'''This page provides answers to frequently asked questions and solutions to common issues encountered during the configuration and operation of VoIPmonitor.'''
'''Quick answers to frequently asked questions. For detailed troubleshooting, see [[Sniffer_troubleshooting|Sniffer Troubleshooting]] and [[GUI_troubleshooting|GUI Troubleshooting]].'''


== Quick Navigation ==
== Quick Navigation ==
{| class="wikitable" style="width:100%; margin-bottom:20px;"
{| class="wikitable" style="width:100%; margin-bottom:20px;"
|-
|-
! style="width:25%; background:#e6f2ff;" | General Topics
! style="width:25%; background:#e6f2ff;" | General
! style="width:25%; background:#e6ffe6;" | Configuration
! style="width:25%; background:#e6ffe6;" | Configuration
! style="width:25%; background:#fff2e6;" | Troubleshooting
! style="width:25%; background:#fff2e6;" | Licensing
! style="width:25%; background:#ffe6e6;" | Files & Compliance
! style="width:25%; background:#ffe6e6;" | Audio & Files
|-
|-
| style="vertical-align:top; padding:8px;" |
| style="vertical-align:top; padding:8px;" |
* [[#General & Scalability|Scaling]]
* [[#General_&_Architecture|Architecture]]
* [[#Licensing|Licensing]]
* [[#Platform_Support|Platform Support]]
* [[#Platform & Environment Support|Platform Support]]
* [[#CDR_View|CDR View]]
| style="vertical-align:top; padding:8px;" |
| style="vertical-align:top; padding:8px;" |
* [[#Configuration & Features|SIP Ports]]
* [[#Protocols_&_Ports|Protocols & Ports]]
* [[#Configuration & Features|IPv6]]
* [[#RTP_&_Quality_Metrics|RTP & Quality]]
* [[#Configuration & Features|DTMF]]
* [[Capture_rules|Capture Rules]]
| style="vertical-align:top; padding:8px;" |
| style="vertical-align:top; padding:8px;" |
* [[#CDR (Call Detail Record) View|CDR Issues]]
* [[#Licensing|Channels & Limits]]
* [[#Administration & Troubleshooting|Admin Tasks]]
* [[#Licensing|HWID Issues]]
* [[GUI_troubleshooting|GUI Debug]]
* [[#Licensing|License Transfer]]
* [[#General & Scalability|MySQL Support]]
* [[#Administration & Troubleshooting|Network Connectivity]]
* [[#Administration & Troubleshooting|Secure DNS Issues]]
* [[#Administration & Troubleshooting|Missing Database Tables]]
* [[#Administration & Troubleshooting|MariaDB System Table Corruption After OS Upgrade]]
* [[#Administration & Troubleshooting|Missing Database Columns]]
| style="vertical-align:top; padding:8px;" |
| style="vertical-align:top; padding:8px;" |
* [[#Audio & PCAP Files|Audio/PCAP]]
* [[#Audio_&_PCAP_Files|Recording Limits]]
* [[#PCI compliance|PCI Compliance]]
* [[#Audio_&_PCAP_Files|Codec Support]]
* [[Capture_rules|Capture Rules]]
* [[#Compliance|PCI/CALEA]]
|}
|}


== General & Scalability ==
== General & Architecture ==


;How does VoIPmonitor scale for high traffic?
;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|Scaling and Performance Tuning guide]].
:For hardware recommendations and optimization of CPU, Disk I/O, and Database bottlenecks, see [[Scaling|Scaling and Performance Tuning]].
 
;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|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:
;How do I manage disk space and database retention?
:* '''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.
:See [[Data_Cleaning|Data Cleaning and Retention]] for PCAP cleanup (cleanspool) and CDR retention settings.
:* '''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 (<code>key.php</code>) 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'''
;Can I run multiple GUI instances for redundancy?
: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'''.
:Yes. Requirements:
:* All GUIs connect to the same database
:* PCAP storage accessible via NFS/SSHFS
:* Same <code>key.php</code> license file on each GUI


:To prevent conflicts:
:{{Warning|1='''CRITICAL:''' Enable the cron job on '''only ONE''' GUI instance. Multiple active cron jobs cause duplicate alerts and reports.}}
:# Enable the cron job on '''only one GUI instance''' (typically your primary internal GUI for active monitoring).
:<syntaxhighlight lang="bash"># Disable on secondary GUIs:
:# Disable the cron job on all secondary/redundant GUI instances.
:# Verify that the cron job exists in <code>/etc/crontab</code> or system cron configuration on each server.
:# Comment out or remove the cron line on secondary servers:
::<syntaxhighlight lang="bash"># On secondary GUI servers - DISABLE the cron job
# * * * * * root php /var/www/html/php/run.php cron</syntaxhighlight>
# * * * * * root php /var/www/html/php/run.php cron</syntaxhighlight>


: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.
;Can one GUI display data from multiple sensors?
:Yes. Use the '''Client-Server architecture''' (v20+):
:* '''Local Processing''' (<code>packetbuffer_sender=no</code>): Sensors analyze locally, send CDRs only
:* '''Packet Mirroring''' (<code>packetbuffer_sender=yes</code>): Sensors forward raw packets to central server
:See [[Sniffer_distributed_architecture|Distributed Architecture]] for full configuration.


== CDR (Call Detail Record) View ==
== Platform Support ==


;What does the small red icon in the CDR view mean?
;What architectures are supported?
:The red icon ([[File:Cdrcolumnsredflag.png]]) indicates which party in the call sent the <code>BYE</code> message first, effectively ending the call.
:{| class="wikitable"
 
|-
;How can I use regular expressions to filter calls?
! Component !! Supported !! Notes
: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:
|-
:<code>!R(^[+]?[0-9]+$)</code>
| Sensor || x86 (32/64-bit), ARMv7/v8 || Compile from source for ARM64
 
|-
;Why is there a delay between when a call ends and when it appears in the CDR view?
| GUI || x86 only || '''Not supported''' on ARM64/aarch64
: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 (<code>_</code>) as a wildcard character to represent the space.
 
:'''Example:''' To search for "Normal Call Clearing", use:
:<code>%normal_call_clearing%</code>
 
:The underscore acts as a wildcard that matches a single character (in this case, the space), while the percent (<code>%</code>) 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 [[Reports|Call Summary]] report to see aggregate call statistics per IP (total calls, duration, etc.)
:* Create separate series in [[Charts|Charts]] for each IP using the Filters tab (requires individual IP filters)
:* Create [[Groups|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 <code>From</code> header
:* '''Called number:''' Taken from the <code>To</code> 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 <code>From</code> and <code>To</code> headers in the first <code>INVITE</code> 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 <code>voipmonitor.conf</code>:
 
<syntaxhighlight lang="ini">[general]
# Default: 1 = To header
# Alternative: 2 = INVITE URI
destination_number_mode = 1</syntaxhighlight>
 
Set <code>destination_number_mode = 2</code> 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:
 
:* <code>remoteparty_caller</code> / <code>remoteparty_called</code> - Update numbers from Remote-Party-ID header
:* <code>passertedidentity = yes</code> - Use P-Asserted-Identity header for caller
:* <code>ppreferredidentity = yes</code> - 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:
<syntaxhighlight lang="ini">[general]
# Comment out or remove to disable
# remoteparty_caller = calling
# remoteparty_called = called
# passertedidentity = no
# ppreferredidentity = no</syntaxhighlight>
 
'''4. Apply Configuration Changes'''
After editing <code>voipmonitor.conf</code>, restart the sensor service:
<syntaxhighlight lang="bash">systemctl restart voipmonitor</syntaxhighlight>
 
'''5. Test and Verify'''
Generate a new test call and check the CDR to see if the numbers are now correctly assigned to <code>caller</code> and <code>called</code> fields.
 
For more detailed configuration options, see the [[Sniffer_configuration#Caller/Called_Identity_Configuration|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 <code>__sync_fetch_and_sub_8</code> 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?
;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:
:Yes. For license detection: <code>chmod 644 /dev/root</code>
:<syntaxhighlight lang="bash">chmod 644 /dev/root</syntaxhighlight>
:* '''Stop/Start instance:''' HWID usually preserved
:* '''Terminate/Launch new:''' HWID changes, requires new license key


;Is Docker or other container environments supported?
;Is Docker supported?
:Yes, the GUI and sensor can run in a containerized environment. However, you must ensure that the content of <code>/proc/self/cgroup</code> 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.
:Yes, but ensure <code>/proc/self/cgroup</code> content doesn't change between restarts (affects HWID stability).


;Are hosted/cloud databases (like Amazon RDS, Azure Database) supported?
;Are cloud databases (RDS, Azure) 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 <code>SUPER</code> privilege for creating functions and triggers.
:Yes. Requires MySQL-compatible database with <code>SUPER</code> privilege. If unavailable, set:
 
;What if my cloud database (like Azure) does not grant SUPER privilege?
:If <code>SUPER</code> privilege is not available, you must manually set the following server variable in your cloud database configuration console:
:<syntaxhighlight lang="ini">log_bin_trust_function_creators = ON</syntaxhighlight>
:<syntaxhighlight lang="ini">log_bin_trust_function_creators = ON</syntaxhighlight>
: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?
;Why is mysql_native_password deprecated?
:MySQL 8.0 and MySQL 8.4+ (default in Ubuntu 24.04, Debian 12/13, Rocky 9, etc.) default to <code>caching_sha2_password</code> authentication and display deprecation warnings when the older <code>mysql_native_password</code> method is used.
:PHP 7.4.4+ supports <code>caching_sha2_password</code> natively. Upgrade PHP and reinstall IonCube Loader. See [[GUI_installation|GUI Installation]].


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


:'''Recommended Solution (Best Practice):''':# Upgrade your PHP version to 7.4.4 or newer (recommended: 8.0, 8.1, 8.2, or 8.3).
;What does the red icon mean?
:# Reinstall the IonCube Loader for your new PHP version. See [[GUI_Installation#Step_3:_Install_or_Update_the_IonCube_Loader|GUI Installation Guide - Step 3]].
:Indicates which party sent the <code>BYE</code> message (ended the call).
:# Reinstall the VoIPmonitor GUI. See [[GUI_Installation#Re-installing_or_Upgrading_the_GUI|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 <code>default_authentication_plugin=mysql_native_password</code> lines from your MySQL configuration.


:'''Alternative Solution (Legacy PHP):''':If you must use an older PHP version (before 7.4.4), you can force <code>mysql_native_password</code> by adding the following to your MySQL configuration file:<syntaxhighlight lang="ini"># /etc/mysql/mysql.conf.d/mysqld.cnf (or /etc/my.cnf.d/mysql-server.cnf on RHEL-based systems)
;How do I filter with regular expressions?
default_authentication_plugin=mysql_native_password</syntaxhighlight>After making changes, restart the MySQL service and recreate your database user using the old method:<syntaxhighlight lang="sql">ALTER USER 'voipmonitor'@'127.0.0.1' IDENTIFIED WITH mysql_native_password BY 'YourPassword';
:Prefix with <code>R()</code>. Example: <code>R(^500[0-9]{4}$)</code>
FLUSH PRIVILEGES;</syntaxhighlight>{{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 ==
;How do I exclude values from filters?
:Use <code>!</code> prefix:
:* <code>!123456</code> – exclude specific number
:* <code>!00420%</code> – exclude prefix
:* <code>222%, !223%</code> – include 222*, exclude 223*


;Why don't I see SIP packets on ports other than 5060?
;How do I search multi-word strings in custom headers?
: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 <code>voipmonitor.conf</code>. See the [[Sniffer_configuration#sipport|sipport configuration guide]].
:Use underscore for spaces: <code>%normal_call_clearing%</code>


;How do I enable IPv6 traffic processing?
;Why are caller/called numbers swapped?
:By default, IPv6 is disabled. To enable it on a new installation, set <code>ipv6=yes</code> in <code>voipmonitor.conf</code>. If you have existing IPv4 data, enabling IPv6 requires a database migration. For detailed instructions, please see the [[How_to_enable_ipv6_processing|IPv6 Enabling Guide]].
:VoIPmonitor extracts from SIP headers (<code>From</code>/<code>To</code>). Check <code>destination_number_mode</code> setting. See [[Call_Detail_Record_-_CDR|CDR Documentation]].


;How do I capture and view SIP REGISTER messages?
;Why is there a delay before CDRs appear?
:By default, <code>REGISTER</code> messages are not stored. To enable this, set <code>sip-register=yes</code> in <code>voipmonitor.conf</code>. For details on how active and failed registrations are stored and how to query them via the API, see the [[Register|documentation on REGISTER monitoring]].
:Database can't keep up. See [[Database_troubleshooting#SQL_Queue_and_CDR_Delays|SQL Queue Troubleshooting]].


;How can I capture DTMF tones?
== Protocols & Ports ==
:You can enable DTMF capture in <code>voipmonitor.conf</code>:
:* For '''RFC2833''' and '''SIP INFO''' methods, set: <code>dtmf2db = yes</code>
:* For '''inband DTMF''' (G.711 codec only, requires more CPU), set: <code>inbanddtmf = yes</code>


;Why are RTP packets not associated with the correct call legs after moving SIP and RTP to different NICs or VLANs?
;Which protocols are supported?
:This typically occurs when SIP signaling and RTP media arrive on different network interfaces, NICs, or VLANs, and the packet correlation logic needs adjustment.
:{| class="wikitable"
 
:'''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 <code>auto_enable_use_blocks = yes</code> in <code>/etc/voipmonitor.conf</code> and restart the sniffer service:
:<syntaxhighlight lang="bash"># Edit configuration
echo "auto_enable_use_blocks = yes" >> /etc/voipmonitor.conf
 
# Restart sniffer
systemctl restart voipmonitor
</syntaxhighlight>
 
: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#auto_enable_use_blocks|Sniffer Configuration]] for details.
 
:'''Additional Checks:'''
:* Verify <code>interface</code> in <code>voipmonitor.conf</code> includes all relevant NICs (e.g., <code>interface = eth0,eth1</code>)
:* Check <code>vlan_siprtpsame = no</code> (allows different VLANs for SIP and RTP)
:* If IP addresses changed due to NAT, configure <code>natalias</code> 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 [[Encryption_in_manager_api_customer|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|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:
 
{| class="wikitable"
|-
|-
! Rule Type !! Matching Supported !! Example
! Supported !! Not Supported
|-
|-
| '''IP Addresses''' || CIDR subnet masks (wildcard networks) || <code>1.2.3.0/24</code> matches all IPs in that range
| SIP, Skinny/SCCP, MGCP, SS7/ISUP, Diameter, RTCP || '''H.323''', '''MEGACO/H.248'''
|-
| '''Telephone Numbers''' || Prefix matching (equivalent to wildcard) || <code>4420</code> matches <code>4420*</code>
|-
| '''SIP Domains''' || Exact match only || <code>example.com</code> ONLY matches <code>example.com</code>, not <code>sub.example.com</code>
|}
|}


:If you need more complex domain matching logic (such as patterns or subdomains), you must use the <code>filtercommand</code> option with an external script, or use regular expressions in the CDR view filter bar for searching recorded calls.
;Why don't I see SIP on ports other than 5060?
:Configure additional ports in <code>voipmonitor.conf</code>:
:<syntaxhighlight lang="ini">sipport = 5060,5080,8088,8089</syntaxhighlight>
:See [[Sniffer_configuration#sipport|sipport configuration]].


;How do I enable IPv6?
:Set <code>ipv6=yes</code> in config. Existing databases require migration. See [[How_to_enable_ipv6_processing|IPv6 Guide]].


== Licensing ==
;How do I capture REGISTER messages?
:Set <code>sip-register=yes</code>. See [[Register|REGISTER Monitoring]].


;How do I determine the number of license channels I need?
;How do I capture DTMF?
: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.
:<syntaxhighlight lang="ini">dtmf2db = yes          # RFC2833 and SIP INFO
: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).
inbanddtmf = yes        # G.711 only, CPU intensive</syntaxhighlight>


;What happens if my call volume temporarily exceeds my license limit?
== RTP & Quality Metrics ==
:'''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?
;Why are quality metrics (MOS, jitter) missing for one call leg?
:The GUI only becomes fully locked if the license limit is exceeded for '''three or more consecutive days'''.
:Usually NAT mismatch – SDP announces different IP than actual RTP source.


;What happens if I exceed my license for three consecutive days?
:'''Solution:''' Configure <code>natalias</code> mapping:
: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:
:<syntaxhighlight lang="ini"># Map public IP to private IP
:# Delete the CDRs from the spike period via the GUI filter and delete tools (to reset the statistics).
natalias = 1.2.3.4 10.0.0.100</syntaxhighlight>
:# Upgrade your license to a higher channel count via the voipmonitor.org customer portal.
:# 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.
:# 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?
:See [[Sniffer_configuration#NAT|NAT Configuration]] for details.
:There are two common causes for this error. Check which scenario applies to your situation:


:'''Scenario 1: License key formatting issue (most common)'''
;Why is RTP not correctly associated after moving SIP/RTP to different NICs?
:The license key is a multi-line text block that contains several fields such as <code>Expires</code>, <code>easycallerid</code>, <code>id</code>, and <code>upgradeexpire</code>. A very common mistake is copying only the first line of the key instead of the entire multi-line block.
:Enable memory blocks for multi-interface scenarios:
:* Ensure you select and copy the '''entire''' license key text (all lines) from your license email or customer portal.
:<syntaxhighlight lang="ini">auto_enable_use_blocks = yes</syntaxhighlight>
:* 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'''
;Why do recordings mix audio from different calls?
: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:
:Enable SDP verification on both sides:
:* '''AWS EC2:''' Run <code>chmod 644 /dev/root</code> to fix permissions on the root device.
:<syntaxhighlight lang="ini">rtp_check_both_sides_by_sdp = yes</syntaxhighlight>
:* '''Docker/Containers:''' Ensure the container ID in <code>/proc/self/cgroup</code> does not change between restarts.
:*'''Corrupted license file:''' Remove <code>/var/www/html/key.php</code> and re-fetch the license via the "get license key" button in the GUI.


:'''If the above steps do not resolve the issue'''
== Licensing ==
: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?
;How are license channels calculated?
: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.
:Based on '''maximum concurrent calls''' (averaged hourly, checked daily). View in '''Tools → System Status → Concurrent calls'''.
:* Calls are deduplicated if last 6 digits of caller/called match within ±10 seconds
:* 487 Request Terminated responses are NOT counted


:# Contact VoIPmonitor support to obtain the full, formatted license key.
;What happens if I exceed my limit?
:# Log in to the VoIPmonitor web GUI.
:{| class="wikitable"
:# Navigate to '''Settings > License''' (or click the "get/update license" button if available).
|-
:# Paste the '''entire multi-line license key''' into the provided text field.
! Duration !! Effect
:# Save the changes to apply the new license.
|-
| 1-2 days || Warning only, self-clearing
|-
| 3+ consecutive days || GUI blocked
|}


'''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.
;How do I unblock a locked GUI?
:In '''Settings > License''', click '''get/update license key''' – this grants a temporary increase automatically.


For persistent connectivity issues preventing automatic license updates, see [[FAQ#How_do_I_troubleshoot_internet_connectivity_issues]] for network and proxy configuration troubleshooting.
;I get "Invalid or corrupted hwid" error. What do I do?
:'''Common causes:'''
:# '''Incomplete key:''' Copy the '''entire''' multi-line license key, not just the first line
:# '''Wrong field:''' Use "License token" for short tokens, "License key" for full multi-line keys
:# '''AWS:''' Run <code>chmod 644 /dev/root</code>
:# '''Docker:''' Ensure container ID doesn't change on restart
:# '''Trial on different machine:''' Contact support for a pre-generated key


;What happens to my license if I stop and restart an AWS instance?
;I get "license file key.php is for another hwid" after hardware change?
: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.
:In '''Settings > License''', click '''get/update license key''' then '''recheck''' to fetch new key for current HWID.


;Can I license VoIPmonitor based on a URL/domain instead of hardware ID?
;I get "Bad Key Content" error?
: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).
:You're using the wrong field. Short tokens go in "License token" field, then click "get/update license key".


;How do I determine which license key belongs to which instance when I have multiple keys?
;How do I transfer a license to a new server?
: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.
:# Get token from old GUI ('''Settings > License''') or customer portal
:# On new GUI: paste token, click '''get/update license key'''
:# '''IMPORTANT:''' Disable cron on old server to prevent conflicts


:# Log in to the GUI of the '''already licensed''' VoIPmonitor instance.
;Can I use one license on multiple servers (test/dev)?
:# Navigate to '''Settings > License''' and note the '''License ID''' displayed in the license information.
:Yes. Contact support to reconfigure your token for multiple HWIDs.
:# Log in to the voipmonitor.org customer portal and navigate to '''Services > My Services'''.
:# Identify the License IDs for your available license keys in the customer portal.
:# Find the license key that has the same License ID as the one you noted from the GUI - this key activates that specific instance.
:# 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.
;What are the available license tiers?
 
:10, 35, 50, 100, 150, 200, 350, 500, 750, 1000, 1250, 1500, 1750, 2000
;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:
:# Contact VoIPmonitor support via the customer portal or email
:# Specify that you need your license configured for multiple servers (mention it is for test/dev environment)
:# Provide the server ID (hardware ID) for each server where you will use the license
:# 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:'''
:# Contact VoIPmonitor support immediately to request a '''30-day emergency trial license''' for your server.
:# Provide your server ID (hardware ID) when requesting the emergency trial license.
:# Once support generates the trial license token, apply it to your GUI by navigating to '''Settings > License''' and pasting the trial license key.
:# 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:
:<syntaxhighlight lang="bash">php /var/www/html/php/run.php checkLicense -v</syntaxhighlight>


== Audio & PCAP Files ==
== Audio & PCAP Files ==


;How can I bulk download audio or PCAP files?
;Why does call recording stop after exactly 4 hours?
:You can use the GUI API to script bulk downloads. Please see the guide: [[download_of_pcap_files_audio_files_using_GUI's_api|Bulk Download using API]].
:Default <code>absolute_timeout = 14400</code> (4 hours). Increase or disable:
 
:<syntaxhighlight lang="ini">absolute_timeout = 43200  # 12 hours
;Why does the GUI download button download the entire merged PCAP instead of only the filtered packets?
# absolute_timeout = 0    # Unlimited (watch memory usage)</syntaxhighlight>
: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|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 <code>vmcodecs</code> to perform the codec transcoding.
 
:This <code>vmcodecs</code> 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 <code>vmcodecs</code> binary in <code><gui-installation-path>/bin/vmcodecs</code>.
:# '''Ensure <code>vmcodecs</code> is accessible''' to the sensor - it must be in a directory that is in the system's <code>$PATH</code> 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.
 
;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 <code>a=crypto</code> lines in the SDP which indicate SRTP encryption
:* '''DTLS fingerprint:''' Look for <code>a=fingerprint</code> or <code>a=setup</code> attributes which indicate DTLS-SRTP negotiation
:* '''RTP encryption:** Encrypted packets will appear as random data when viewed in Wireshark


:'''Solution: Configure DTLS-SRTP Decryption**
;Why are WAV files missing for non-G.711 codecs (Opus, G.729)?
:Requires <code>vmcodecs</code> binary from GUI package. Install GUI, then restart sensor.


To enable audio playback for encrypted calls, VoIPmonitor must have access to the decryption keys. This is achieved using the '''SSL Key Logger''' method.
;Why is audio playback garbled?
:DTLS-SRTP encryption. Configure SSL Key Logger for decryption. See [[Tls|TLS/SRTP Decryption]].


;1. The SSL Key Logger is installed on the SBC or PBX that terminates the calls
;Why can't I download PCAP files?
;2. It captures DTLS session keys from memory using the <code>LD_PRELOAD</code> mechanism
:Files deleted by retention limits. Check:
;3. Keys are sent over the network to the VoIPmonitor sensor
:<syntaxhighlight lang="bash">grep maxpoolsize /etc/voipmonitor.conf
;4. VoIPmonitor uses these keys to decrypt the DTLS handshake and derive SRTP master keys
grep maxpooldays /etc/voipmonitor.conf</syntaxhighlight>
:Increase limits and restart. See [[Data_Cleaning|Data Cleaning]].


:For detailed setup instructions, see the [[Tls]] documentation, specifically the '''Method 2: SSL Key Logger''' section. The guide covers:
;Why does downloaded PCAP have fewer packets than GUI shows?
:'''Pcap deduplication before download''' is enabled. Disable in '''Settings > System Configuration > Advanced'''.


:* Compiling the <code>sslkeylog.so</code> library
;How do I bulk download audio/PCAP files?
:* Configuring Asterisk, Kamailio, FreeSWITCH, or other SIP applications
:Use GUI API. See [[download_of_pcap_files_audio_files_using_GUI's_api|Bulk Download Guide]].
:* Setting up VoIPmonitor to receive session keys
:* Correct <code>ssl_ipport</code> syntax for key logger mode
:* TCP mode for secure key transport


:'''Common Configuration Pitfalls:'''
;Can VoIPmonitor detect voicemail calls?
:'''No automatic detection''' by analyzing RTP audio. Workarounds:
:* Filter by voicemail pilot number
:* Track SIP 302 redirects (<code>save_sip_history = all</code>)
:* Capture custom SIP headers your PBX adds


:* '''Wrong ssl_ipport syntax:** When using SSL Key Logger, <code>ssl_ipport</code> must NOT include a path to a key file (e.g., <code>ssl_ipport = 192.168.1.50:5061</code> is correct, but <code>ssl_ipport = 192.168.1.50:5061 /path/to/key.pem</code> will fail)
;How do I convert WAV to OGG?
:* '''Keys sent to wrong destination:** In distributed architectures with <code>packetbuffer_sender=yes</code>, keys must go to the central server IP, not localhost or the remote client sensor
:<syntaxhighlight lang="bash">cd /var/spool/voipmonitor
:* '''PBX not configured:''' The PBX/SBC must have <code>sslkeylog.so</code> preloaded via <code>LD_PRELOAD</code> 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 <code>vmcodecs</code> binary. The <code>vmcodecs</code> 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 <code>bind</code>.
 
;2. Add natalias configuration
:Add the <code>natalias</code> option to the import configuration to map public IPs to private IPs:
:<syntaxhighlight lang="ini">
natalias = 1.1.1.1 10.0.0.3
natalias = 2.2.2.2 10.0.0.4
</syntaxhighlight>
:Multiple <code>natalias</code> lines can be used if multiple NAT mappings are required. See [[Sniffer_configuration#NAT|NAT Configuration]] in the sniffer configuration reference.
 
;3. Check GUI/DB Settings priority
:Settings in <code>Settings -> Sensors</code> in the GUI have higher priority than <code>voipmonitor.conf</code>. If <code>id_sensor</code> 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 <code>.wav</code> and wish to convert them to the more efficient <code>.ogg</code> format to save disk space, you can run the following sequence of commands directly in your spool directory (e.g., <code>/var/spool/voipmonitor</code>):
 
<syntaxhighlight lang="bash">
# 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"' {} \;
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 {} \;
find ./ -name '*.wav' -exec rm -f {} \;
chown -R www-data:www-data ./</syntaxhighlight>


# Step 3: Set the web server user (e.g., www-data) as the owner of all files.
;How do I enable live call listening?
# This is crucial for the GUI to be able to read and play the new .ogg files.
:Edit <code>configuration.php</code>:
chown -R www-data:www-data ./
:<syntaxhighlight lang="php">define('DISABLE_LIVEPLAY', false);</syntaxhighlight>
</syntaxhighlight>
:See [[GUI_Configuration_PHP|GUI Configuration]] for details.
;Why is transfer throughput to external storage (S3, CloudBerry) limited?
:VoIPmonitor does not impose speed limits on external storage transfers. If you see artificial throughput caps (e.g., 40 Mbps):<br>
# '''Verify bandwidth''' from your host to the internet is sufficient<br>
# '''Check third-party tool configuration''' (e.g., CloudBerry, s3fs, rclone) - the bottleneck is typically in these tools, not VoIPmonitor<br>
# For '''controlled bandwidth limiting''', use <code>rsync</code> via cron job with <code>--bwlimit</code> or the <code>tar_move</code> option - both allow bandwidth management
== Administration ==


;The 'live play' audio feature is disabled in the GUI. How do I re-enable it?
;How do I reset admin password?
: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.
:See [[User_Management|User Management]].


:'''To re-enable live play:'''
;How do I fix GUI after PHP/OS upgrade?
:Re-run installation. See [[Re-install_the_GUI|Re-install GUI]].


:# '''Access the GUI host server''' via SSH or terminal.
;How do I enable debug mode?
:# '''Edit the configuration file''' located at:
:Add <code>?debug=31415</code> to URL. See [[GUI_troubleshooting#GUI_Debug_Mode|GUI Debug Mode]].
::<code>/var/www/html/voipmonitor/configuration.php</code>
::(The path may vary slightly depending on your installation, typically under <code>/var/www/html/</code> or <code>/var/www/</code>)
:# '''Find the DISABLE_LIVEPLAY constant''':
::<syntaxhighlight lang="php">define('DISABLE_LIVEPLAY', true);</syntaxhighlight>
:# '''Change the value from true to false''':
::<syntaxhighlight lang="php">define('DISABLE_LIVEPLAY', false);</syntaxhighlight>
:# '''Save the file''' and exit the editor.
:# '''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.
;How do I fix "Unknown column" errors after database upgrade?
:Access: <code>https://your-gui/admin.php?check_tables=1</code>
:{{Note|1=Do NOT use "Check MySQL Schema" button in Tools - that's for millisecond precision only.}}


: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 <code>true</code>.
;Can I run multiple sensor instances on one host?
:Yes. See [[Multiple_sniffer_instancies|Multiple Instances Guide]].
;Users from the same organization cannot view each other's support tickets. How can we share access?
:Support tickets are associated with individual email addresses. To enable team-wide ticket visibility, '''merge all user accounts under a single main email address'''. Contact VoIPmonitor support to consolidate multiple accounts into one organization account.
== Compliance ==


== Administration & Troubleshooting ==
=== PCI Compliance ===


;How do I fix "bad gso: type: 1, size: 1448" or kernel errors related to network offloading?
;How do I disable audio recording?
: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.
:<syntaxhighlight lang="ini">savertp = header    # Headers only, no audio
savertp = no        # No RTP at all
dtmf2db = no        # No DTMF to database
dtmf2pcap = no      # No DTMF to PCAP</syntaxhighlight>


:'''Symptoms:'''
;How do I selectively record calls?
:* Kernel messages like: <code>ens3: bad gso: type: 1, size: 1448</code>
:Use [[Capture_rules|Capture Rules]] to enable/disable recording based on IP, number, or SIP headers.
:* Errors may mention UDP Fragmentation Offload (UFO)
:* Packet capture issues during VoIPmonitor operation


:'''Solution:''' Disable the offload features on the affected interface:
;How do I disable live listening?
<syntaxhighlight lang="bash">
:* '''Settings > System Configuration > Advanced:''' Enable "Hide live play" and "Hide WAV play"
# Check MTU (should be > 1448, typically 1500)
:* Edit <code>configuration.php</code>: <code>define('DISABLE_LIVEPLAY', true);</code>
ip addr show eth0
:* Edit <code>config/system_configuration.php</code>: <code>define('DISABLE_LIVE_SNIFFER', true);</code>
{{Note|1='''Understanding audio in VoIPmonitor:''' By default, the GUI extracts audio '''on-demand''' from stored RTP packets in PCAP files (when <code>savertp = yes</code>). The <code>saveaudio</code> option creates '''pre-generated''' audio files and is NOT required for audio playback. Setting <code>savertp = header</code> disables audio playback because RTP payload is not stored. See [[Sniffer_configuration#Understanding_Audio_Playback_vs_Pre-Generated_Files|Audio Playback vs Pre-Generated Files]] for details.}}
=== CALEA Compliance ===


# Disable offload features (replace ens3 with your interface name)
;How do I export data to CALEA systems?
ethtool -K ens3 gso off tso off gro off lro off
:Use GUI API methods <code>getPCAP</code> and <code>getVoiceRecording</code>. See [[CALEA_compliance|CALEA Integration Guide]].


# Verify the change persists (check kernel logs)
== See Also ==
dmesg -T | grep -i gso
</syntaxhighlight>


:To make changes '''persistent across reboots''', create a systemd service:
* [[Sniffer_troubleshooting|Sniffer Troubleshooting]] - packet capture, missing CDRs
<syntaxhighlight lang="ini">
* [[GUI_troubleshooting|GUI Troubleshooting]] - HTTP 500, database issues
# /etc/systemd/system/disable-offload.service
* [[Sniffer_configuration|Sniffer Configuration Reference]]
[Unit]
* [[License|Licensing Details]]
Description=Disable network offloads for VoIPmonitor
* [[Data_Cleaning|Data Cleaning and Retention]]
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
</syntaxhighlight>


<syntaxhighlight lang="bash">
# Enable and start the service
systemctl enable disable-offload.service
systemctl start disable-offload.service
</syntaxhighlight>


: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|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?
== AI Summary for RAG ==
:Instructions for downloading and installing the latest static binary are here: [[Sniffer_installation|Sniffer Installation]].


;Can I run multiple instances of the sniffer on a single host?
'''Summary:''' VoIPmonitor FAQ organized by topic. General: scaling (link to Scaling page), multiple GUI instances (requires same DB, NFS storage, single cron job to prevent duplicate alerts), client-server architecture for multi-sensor. Platform: x86 required for GUI (ARM64 not supported), AWS/Docker/cloud DB supported. CDR: regex filters with R() prefix, exclusion with ! prefix, underscore for multi-word search. Protocols: SIP, Skinny/SCCP, MGCP, SS7, Diameter supported; H.323 and MEGACO NOT supported. RTP: natalias for NAT mismatch causing missing quality metrics, auto_enable_use_blocks for multi-interface, rtp_check_both_sides_by_sdp for mixed audio. Licensing: concurrent calls averaged hourly, 3+ consecutive days over limit locks GUI, get/update button for temporary increase, common HWID errors (incomplete key, wrong field, AWS chmod, Docker cgroup). Audio: absolute_timeout default 4 hours (14400s), vmcodecs needed for non-G.711, DTLS-SRTP causes garbled audio. Admin: admin.php?check_tables=1 for schema errors after DB upgrade. Compliance: savertp=header/no for PCI, capture rules for selective recording, DISABLE_LIVEPLAY for hiding playback.
: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|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'''
:<syntaxhighlight lang="bash"># Test if the server can reach external hosts
ping -c 4 8.8.8.8
 
# Test DNS resolution
ping -c 4 google.com
</syntaxhighlight>
 
:If these commands fail, the issue is with network configuration or routing. Check:
:* Network interface configuration: <code>ip addr show</code>
:* Default gateway: <code>ip route show</code>
:* DNS configuration: <code>cat /etc/resolv.conf</code>
 
:'''Step 2: Check firewall rules for outbound connections'''
:<syntaxhighlight lang="bash"># 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"
</syntaxhighlight>
 
:Ensure that outbound connections on HTTP (port 80) and HTTPS (port 443) are not blocked. The server needs to reach:
:* <code>download.voipmonitor.org</code> (for software downloads)
:* <code>github.com</code> (for source code)
:* Package repository servers (dnf/yum/apt repositories)
 
:'''Step 3: Test connectivity to specific hosts'''
:<syntaxhighlight lang="bash"># 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
</syntaxhighlight>
 
:If <code>curl</code> 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 <code>curlproxy</code> parameter in <code>/etc/voipmonitor.conf</code> to enable sensor updates and downloads:
:<syntaxhighlight lang="ini">
[general]
# Replace with your actual proxy address and port
curlproxy = http://proxy-server-ip:port
</syntaxhighlight>
 
:Then restart the sensor:
:<syntaxhighlight lang="bash">systemctl restart voipmonitor</syntaxhighlight>
 
:'''Alternative: Use environment-wide proxy settings'''
:For package managers and system-wide proxy access, configure environment variables:
:<syntaxhighlight lang="bash">
# 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";
</syntaxhighlight>
 
;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 <code>chrome://settings/security</code> 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:
:<syntaxhighlight lang="bash">dig www.voipmonitor.org</syntaxhighlight>
 
:4. Test DNS-over-HTTPS resolution directly against a provider's API to isolate the issue:
:<syntaxhighlight lang="bash"># Test Google's DNS-over-HTTPS API
curl -s "https://dns.google/resolve?name=www.voipmonitor.org&type=A" | jq</syntaxhighlight>
 
:If <code>dig</code> 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 <code>cdr_stat_values</code>, <code>cdr_problems_by_ip</code>, 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:'''
:* <code>Table 'cdr_problems_by_ip' doesn't exist</code>
:* <code>Table 'cdr_stat_values' doesn't exist</code>
:* Errors during database initialization or schema creation
 
:'''Step 1: Check Database Privileges'''
:The MySQL/MariaDB user configured in <code>voipmonitor.conf</code> (the <code>mysqlusername</code> parameter) must have privileges to create and alter database schema.
 
:# Log in to your MySQL/MariaDB console:
:<syntaxhighlight lang="bash">mysql -u root -p</syntaxhighlight>
 
:# Check the current privileges for the VoIPmonitor user:
:<syntaxhighlight lang="sql">SHOW GRANTS FOR 'voipmonitor'@'localhost';</syntaxhighlight>
 
:# If the user lacks <code>CREATE</code>, <code>ALTER</code>, or <code>DROP</code> privileges, grant them:
:<syntaxhighlight lang="sql">GRANT ALL PRIVILEGES ON voipmonitor.* TO 'voipmonitor'@'localhost';
FLUSH PRIVILEGES;
EXIT;</syntaxhighlight>
 
:'''Step 2: Check the disable_dbupgradecheck Configuration'''
:If the <code>disable_dbupgradecheck</code> option is enabled in <code>voipmonitor.conf</code>, the sensor will skip the automatic database schema upgrade and table creation process.
 
:# Open your configuration file:
:<syntaxhighlight lang="bash">nano /etc/voipmonitor.conf</syntaxhighlight>
 
:# Search for <code>disable_dbupgradecheck</code>. Ensure it is either commented out or set to <code>no</code>:
:<syntaxhighlight lang="ini"># disable_dbupgradecheck = yes  <-- Comment this out or set to 'no'
disable_dbupgradecheck = no</syntaxhighlight>
 
:# 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:
 
:<syntaxhighlight lang="bash">
# Restart the service
systemctl restart voipmonitor
 
# Monitor the initialization process
journalctl -u voipmonitor -f
</syntaxhighlight>
 
: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.
 
:# Connect to the database:
:<syntaxhighlight lang="bash">mysql -u voipmonitor -p voipmonitor</syntaxhighlight>
:(Replace <code>voipmonitor</code> with your actual database name and username if different.)
 
:# Drop the problematic tables if they exist:
:<syntaxhighlight lang="sql">DROP TABLE IF EXISTS cdr_problems_by_ip;
DROP TABLE IF EXISTS cdr_stat_values;</syntaxhighlight>
 
:# Manually recreate the tables using the correct <code>CREATE TABLE</code> SQL statements. You can obtain the schema definition from:
::* The <code>Tools -&gt; System Status -&gt; Check MySQL Schema</code> option in the Web GUI (if accessible)
::* A working VoIPmonitor installation of the same version
::* VoIPmonitor support
 
:# After recreating the tables, exit MySQL:
:<syntaxhighlight lang="sql">EXIT;</syntaxhighlight>
 
:# Restart the VoIPmonitor sensor:
:<syntaxhighlight lang="bash">systemctl restart voipmonitor</syntaxhighlight>
 
:'''Step 5: Verify the Fix'''
:Check that the sensor is running without table-related errors:
 
:<syntaxhighlight lang="bash">
# Check service status
systemctl status voipmonitor
 
# Monitor logs for any errors
journalctl -u voipmonitor -f
</syntaxhighlight>
 
:The errors regarding missing tables should cease, and the sensor should operate normally.
 
:'''Prevention:'''
:* Ensure the database user always has sufficient privileges (<code>ALL PRIVILEGES</code> on the VoIPmonitor database schema).
:* Keep <code>disable_dbupgradecheck</code> disabled (<code>no</code> 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 <code>mysql</code> database (e.g., <code>mysql.column_stats</code>) 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 <code>voipmonitor</code> database user may lack the required privileges for the new MariaDB version
 
:'''Common Error Messages:'''
:* <code>Table 'mysql.column_stats' doesn't exist</code>
:* <code>Incorrect table definition; there can be only one auto column and it must be defined as a key</code>
:* <code>CREATE FUNCTION command denied to user 'voipmonitor'@'...' for table '...'</code>
 
:'''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 <code>mysqldump</code>.}}
 
:# '''Stop the MariaDB service''':
:<syntaxhighlight lang="bash">systemctl stop mariadb</syntaxhighlight>
 
:# '''Backup the MariaDB data directory (if you need to preserve any data)''':
:<syntaxhighlight lang="bash">cp -a /var/lib/mysql /var/lib/mysql.backup</syntaxhighlight>
 
:# '''Delete the entire MariaDB data directory''':
:<syntaxhighlight lang="bash">rm -rf /var/lib/mysql/* /var/lib/mysql/.* 2>/dev/null || true</syntaxhighlight>
 
:# '''Start the MariaDB service to reinitialize system databases cleanly''':
:<syntaxhighlight lang="bash">systemctl start mariadb</syntaxhighlight>
:The service will create fresh system databases (<code>mysql</code>, <code>information_schema</code>, <code>performance_schema</code>, etc.).
 
:# '''Create the VoIPmonitor database user with correct privileges''':
:<syntaxhighlight lang="bash">mysql</syntaxhighlight>
Once in the MySQL console, run:
:<syntaxhighlight lang="sql">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;</syntaxhighlight>
{{Note|The <code>GRANT SUPER</code> privilege is required for VoIPmonitor to create stored procedures and triggers in newer MariaDB versions.}}
 
:# '''Create the VoIPmonitor database''':
:<syntaxhighlight lang="sql">CREATE DATABASE voipmonitor;
EXIT;</syntaxhighlight>
 
:# '''Restart VoIPmonitor services''':
:<syntaxhighlight lang="bash">systemctl restart voipmonitor</syntaxhighlight>
:On startup, the sensor will automatically create the required tables, functions, and triggers in the new database.
 
:'''Alternative: Configure MariaDB Without SUPER Privilege'''{{Warning|If you cannot grant <code>SUPER</code> privilege (e.g., cloud-hosted database), you must set <code>log_bin_trust_function_creators = ON</code> in the MariaDB configuration.}}
 
:# Edit the MariaDB server configuration:
:<syntaxhighlight lang="bash">nano /etc/mysql/mariadb.conf.d/50-server.cnf</syntaxhighlight>
 
:# Add the following line under the <code>[mysqld]</code> section:
:<syntaxhighlight lang="ini">[mysqld]
log_bin_trust_function_creators = ON</syntaxhighlight>
 
:# Restart MariaDB to apply the change:
:<syntaxhighlight lang="bash">systemctl restart mariadb</syntaxhighlight>
 
:'''Prevention:'''
:* After major OS upgrades, check MariaDB system table compatibility before reinstalling VoIPmonitor
:* Run <code>mariadb-upgrade</code> (or <code>mysql_upgrade</code> on older systems) to update system databases if not performing a full reinitialization
:* Ensure the <code>voipmonitor</code> 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:'''
:* <code>Unknown column 'Sensors.color_rowview' in 'field list'</code>
:* <code>Unknown column 'cdr.new_field_name' in 'field list'</code>
:* 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:
 
# Open the VoIPmonitor GUI in your web browser
# Add <code>?check_tables=1</code> to the end of the URL in the address bar
:* Example: <code>http://<your_gui_ip>/admin.php?check_tables=1</code>
:* Example with hostname: <code>https://voipmonitor.example.com/admin.php?check_tables=1</code>
# Press Enter to load the URL
# Wait for the table check and repair process to complete
# Navigate back to the section where the error occurred (e.g., CDR view) to verify the fix
 
The <code>?check_tables=1</code> 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 <code>?check_tables=1</code> solution does not resolve the issue:
 
# Ensure the database user has <code>ALTER</code> privilege on the VoIPmonitor database. See the [[#Missing_Database_Tables|Missing Database Tables]] section for instructions on checking and granting privileges.
# Check that <code>disable_dbupgradecheck</code> is not enabled in <code>voipmonitor.conf</code> (see [[#Missing_Database_Tables|Missing Database Tables]]).
# Restart the VoIPmonitor sensor after applying <code>?check_tables=1</code>: <syntaxhighlight lang="bash">systemctl restart voipmonitor</syntaxhighlight>
# Check the sensor logs for schema validation errors: <syntaxhighlight lang="bash">journalctl -u voipmonitor -f</syntaxhighlight>
 
:'''Prevention:'''
:* Run <code>?check_tables=1</code> after every major VoIPmonitor GUI or Sniffer update to ensure the database schema is synchronized.
:* Keep <code>disable_dbupgradecheck</code> 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 <code>savertp=header</code> in <code>voipmonitor.conf</code>.
:* To disable RTP capture entirely, use <code>savertp=no</code>.
:* To prevent DTMF tones (from SIP INFO or RFC2833) from being saved to the database and PCAP files, use:
:<syntaxhighlight lang="ini">
dtmf2db = no
dtmf2pcap = no
</syntaxhighlight>
 
;How do I selectively record or not record audio/DTMF?
:VoIPmonitor's powerful '''[[Capture_rules|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
'''Keywords:''' faq, license, hwid, concurrent calls, absolute_timeout, natalias, auto_enable_use_blocks, rtp_check_both_sides_by_sdp, vmcodecs, savertp, capture rules, multiple gui, cron duplicate alerts, admin.php check_tables, schema error, H.323 not supported, MEGACO not supported, ARM64 not supported, sipport, ipv6, dtmf, PCI compliance, CALEA


'''Key Questions:'''
'''Key Questions:'''
* Why is there a delay between call end and CDR appearance?
* How do I fix "Invalid or corrupted hwid" license error?
* How is VoIPmonitor licensing calculated?
* Why does call recording stop after 4 hours?
* What happens if I exceed my license limit?
* Why are quality metrics missing for one call leg?
* How often is the concurrent call limit checked?
* How do I run multiple GUI instances without duplicate alerts?
* How are calls counted in distributed environments with multiple sensors?
* What protocols does VoIPmonitor support (H.323? MEGACO?)?
* How do I fix "Invalid or corrupted hwid" error when activating a license?
* How do I fix "Unknown column" database errors after upgrade?
* What should I do if troubleshooting steps do not resolve the hwid error?
* Can VoIPmonitor automatically detect voicemail calls?
* What happens to my license if I stop and restart an AWS instance?
* How do I transfer my license to a new server?
* 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?
* 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?
* How do I disable audio recording for PCI compliance?
* Can wildcards or regular expressions be used in domain-based capture rules?
* Does VoIPmonitor GUI run on ARM64?
* 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?

Latest revision as of 11:21, 13 January 2026


Quick answers to frequently asked questions. For detailed troubleshooting, see Sniffer Troubleshooting and GUI Troubleshooting.

Quick Navigation

General Configuration Licensing Audio & Files

General & Architecture

How does VoIPmonitor scale for high traffic?
For hardware recommendations and optimization of CPU, Disk I/O, and Database bottlenecks, see Scaling and Performance Tuning.
How do I manage disk space and database retention?
See Data Cleaning and Retention for PCAP cleanup (cleanspool) and CDR retention settings.
Can I run multiple GUI instances for redundancy?
Yes. Requirements:
  • All GUIs connect to the same database
  • PCAP storage accessible via NFS/SSHFS
  • Same key.php license file on each GUI

⚠️ Warning: CRITICAL: Enable the cron job on only ONE GUI instance. Multiple active cron jobs cause duplicate alerts and reports. 

# Disable on secondary GUIs:
# * * * * * root php /var/www/html/php/run.php cron
Can one GUI display data from multiple sensors?
Yes. Use the Client-Server architecture (v20+):
  • Local Processing (packetbuffer_sender=no): Sensors analyze locally, send CDRs only
  • Packet Mirroring (packetbuffer_sender=yes): Sensors forward raw packets to central server
See Distributed Architecture for full configuration.

Platform Support

What architectures are supported?
Component Supported Notes
Sensor x86 (32/64-bit), ARMv7/v8 Compile from source for ARM64
GUI x86 only Not supported on ARM64/aarch64
Can I run VoIPmonitor on AWS?
Yes. For license detection: chmod 644 /dev/root
  • Stop/Start instance: HWID usually preserved
  • Terminate/Launch new: HWID changes, requires new license key
Is Docker supported?
Yes, but ensure /proc/self/cgroup content doesn't change between restarts (affects HWID stability).
Are cloud databases (RDS, Azure) supported?
Yes. Requires MySQL-compatible database with SUPER privilege. If unavailable, set:
log_bin_trust_function_creators = ON
Why is mysql_native_password deprecated?
PHP 7.4.4+ supports caching_sha2_password natively. Upgrade PHP and reinstall IonCube Loader. See GUI Installation.

CDR View

What does the red icon mean?
Indicates which party sent the BYE message (ended the call).
How do I filter with regular expressions?
Prefix with R(). Example: R(^500[0-9]{4}$)
How do I exclude values from filters?
Use ! prefix:
  • !123456 – exclude specific number
  • !00420% – exclude prefix
  • 222%, !223% – include 222*, exclude 223*
How do I search multi-word strings in custom headers?
Use underscore for spaces: %normal_call_clearing%
Why are caller/called numbers swapped?
VoIPmonitor extracts from SIP headers (From/To). Check destination_number_mode setting. See CDR Documentation.
Why is there a delay before CDRs appear?
Database can't keep up. See SQL Queue Troubleshooting.

Protocols & Ports

Which protocols are supported?
Supported Not Supported
SIP, Skinny/SCCP, MGCP, SS7/ISUP, Diameter, RTCP H.323, MEGACO/H.248
Why don't I see SIP on ports other than 5060?
Configure additional ports in voipmonitor.conf:
sipport = 5060,5080,8088,8089
See sipport configuration.
How do I enable IPv6?
Set ipv6=yes in config. Existing databases require migration. See IPv6 Guide.
How do I capture REGISTER messages?
Set sip-register=yes. See REGISTER Monitoring.
How do I capture DTMF?
dtmf2db = yes           # RFC2833 and SIP INFO
inbanddtmf = yes        # G.711 only, CPU intensive

RTP & Quality Metrics

Why are quality metrics (MOS, jitter) missing for one call leg?
Usually NAT mismatch – SDP announces different IP than actual RTP source.
Solution: Configure natalias mapping:
# Map public IP to private IP
natalias = 1.2.3.4 10.0.0.100
See NAT Configuration for details.
Why is RTP not correctly associated after moving SIP/RTP to different NICs?
Enable memory blocks for multi-interface scenarios:
auto_enable_use_blocks = yes
Why do recordings mix audio from different calls?
Enable SDP verification on both sides:
rtp_check_both_sides_by_sdp = yes

Licensing

How are license channels calculated?
Based on maximum concurrent calls (averaged hourly, checked daily). View in Tools → System Status → Concurrent calls.
  • Calls are deduplicated if last 6 digits of caller/called match within ±10 seconds
  • 487 Request Terminated responses are NOT counted
What happens if I exceed my limit?
Duration Effect
1-2 days Warning only, self-clearing
3+ consecutive days GUI blocked
How do I unblock a locked GUI?
In Settings > License, click get/update license key – this grants a temporary increase automatically.
I get "Invalid or corrupted hwid" error. What do I do?
Common causes:
  1. Incomplete key: Copy the entire multi-line license key, not just the first line
  2. Wrong field: Use "License token" for short tokens, "License key" for full multi-line keys
  3. AWS: Run chmod 644 /dev/root
  4. Docker: Ensure container ID doesn't change on restart
  5. Trial on different machine: Contact support for a pre-generated key
I get "license file key.php is for another hwid" after hardware change?
In Settings > License, click get/update license key then recheck to fetch new key for current HWID.
I get "Bad Key Content" error?
You're using the wrong field. Short tokens go in "License token" field, then click "get/update license key".
How do I transfer a license to a new server?
  1. Get token from old GUI (Settings > License) or customer portal
  2. On new GUI: paste token, click get/update license key
  3. IMPORTANT: Disable cron on old server to prevent conflicts
Can I use one license on multiple servers (test/dev)?
Yes. Contact support to reconfigure your token for multiple HWIDs.
What are the available license tiers?
10, 35, 50, 100, 150, 200, 350, 500, 750, 1000, 1250, 1500, 1750, 2000

Audio & PCAP Files

Why does call recording stop after exactly 4 hours?
Default absolute_timeout = 14400 (4 hours). Increase or disable:
absolute_timeout = 43200   # 12 hours
# absolute_timeout = 0     # Unlimited (watch memory usage)
Why are WAV files missing for non-G.711 codecs (Opus, G.729)?
Requires vmcodecs binary from GUI package. Install GUI, then restart sensor.
Why is audio playback garbled?
DTLS-SRTP encryption. Configure SSL Key Logger for decryption. See TLS/SRTP Decryption.
Why can't I download PCAP files?
Files deleted by retention limits. Check:
grep maxpoolsize /etc/voipmonitor.conf
grep maxpooldays /etc/voipmonitor.conf
Increase limits and restart. See Data Cleaning.
Why does downloaded PCAP have fewer packets than GUI shows?
Pcap deduplication before download is enabled. Disable in Settings > System Configuration > Advanced.
How do I bulk download audio/PCAP files?
Use GUI API. See Bulk Download Guide.
Can VoIPmonitor detect voicemail calls?
No automatic detection by analyzing RTP audio. Workarounds:
  • Filter by voicemail pilot number
  • Track SIP 302 redirects (save_sip_history = all)
  • Capture custom SIP headers your PBX adds
How do I convert WAV to OGG?
cd /var/spool/voipmonitor
find ./ -name '*.wav' -exec bash -c 'ffmpeg -i "$0" -vn -acodec libvorbis "${0%.wav}.ogg"' {} \;
find ./ -name '*.wav' -exec rm -f {} \;
chown -R www-data:www-data ./
How do I enable live call listening?
Edit configuration.php:
define('DISABLE_LIVEPLAY', false);
See GUI Configuration for details.
Why is transfer throughput to external storage (S3, CloudBerry) limited?
VoIPmonitor does not impose speed limits on external storage transfers. If you see artificial throughput caps (e.g., 40 Mbps):
  1. Verify bandwidth from your host to the internet is sufficient
  2. Check third-party tool configuration (e.g., CloudBerry, s3fs, rclone) - the bottleneck is typically in these tools, not VoIPmonitor
  3. For controlled bandwidth limiting, use rsync via cron job with --bwlimit or the tar_move option - both allow bandwidth management

Administration

How do I reset admin password?
See User Management.
How do I fix GUI after PHP/OS upgrade?
Re-run installation. See Re-install GUI.
How do I enable debug mode?
Add ?debug=31415 to URL. See GUI Debug Mode.
How do I fix "Unknown column" errors after database upgrade?
Access: https://your-gui/admin.php?check_tables=1

ℹ️ Note: Do NOT use "Check MySQL Schema" button in Tools - that's for millisecond precision only.

Can I run multiple sensor instances on one host?
Yes. See Multiple Instances Guide.
Users from the same organization cannot view each other's support tickets. How can we share access?
Support tickets are associated with individual email addresses. To enable team-wide ticket visibility, merge all user accounts under a single main email address. Contact VoIPmonitor support to consolidate multiple accounts into one organization account.

Compliance

PCI Compliance

How do I disable audio recording?
savertp = header    # Headers only, no audio
savertp = no        # No RTP at all
dtmf2db = no        # No DTMF to database
dtmf2pcap = no      # No DTMF to PCAP
How do I selectively record calls?
Use Capture Rules to enable/disable recording based on IP, number, or SIP headers.
How do I disable live listening?
  • Settings > System Configuration > Advanced: Enable "Hide live play" and "Hide WAV play"
  • Edit configuration.php: define('DISABLE_LIVEPLAY', true);
  • Edit config/system_configuration.php: define('DISABLE_LIVE_SNIFFER', true);

ℹ️ Note: Understanding audio in VoIPmonitor: By default, the GUI extracts audio on-demand from stored RTP packets in PCAP files (when savertp = yes). The saveaudio option creates pre-generated audio files and is NOT required for audio playback. Setting savertp = header disables audio playback because RTP payload is not stored. See Audio Playback vs Pre-Generated Files for details.

CALEA Compliance

How do I export data to CALEA systems?
Use GUI API methods getPCAP and getVoiceRecording. See CALEA Integration Guide.

See Also





AI Summary for RAG

Summary: VoIPmonitor FAQ organized by topic. General: scaling (link to Scaling page), multiple GUI instances (requires same DB, NFS storage, single cron job to prevent duplicate alerts), client-server architecture for multi-sensor. Platform: x86 required for GUI (ARM64 not supported), AWS/Docker/cloud DB supported. CDR: regex filters with R() prefix, exclusion with ! prefix, underscore for multi-word search. Protocols: SIP, Skinny/SCCP, MGCP, SS7, Diameter supported; H.323 and MEGACO NOT supported. RTP: natalias for NAT mismatch causing missing quality metrics, auto_enable_use_blocks for multi-interface, rtp_check_both_sides_by_sdp for mixed audio. Licensing: concurrent calls averaged hourly, 3+ consecutive days over limit locks GUI, get/update button for temporary increase, common HWID errors (incomplete key, wrong field, AWS chmod, Docker cgroup). Audio: absolute_timeout default 4 hours (14400s), vmcodecs needed for non-G.711, DTLS-SRTP causes garbled audio. Admin: admin.php?check_tables=1 for schema errors after DB upgrade. Compliance: savertp=header/no for PCI, capture rules for selective recording, DISABLE_LIVEPLAY for hiding playback.

Keywords: faq, license, hwid, concurrent calls, absolute_timeout, natalias, auto_enable_use_blocks, rtp_check_both_sides_by_sdp, vmcodecs, savertp, capture rules, multiple gui, cron duplicate alerts, admin.php check_tables, schema error, H.323 not supported, MEGACO not supported, ARM64 not supported, sipport, ipv6, dtmf, PCI compliance, CALEA

Key Questions:

  • How do I fix "Invalid or corrupted hwid" license error?
  • Why does call recording stop after 4 hours?
  • Why are quality metrics missing for one call leg?
  • How do I run multiple GUI instances without duplicate alerts?
  • What protocols does VoIPmonitor support (H.323? MEGACO?)?
  • How do I fix "Unknown column" database errors after upgrade?
  • Can VoIPmonitor automatically detect voicemail calls?
  • How do I transfer my license to a new server?
  • Why is audio playback garbled or distorted?
  • How do I disable audio recording for PCI compliance?
  • Does VoIPmonitor GUI run on ARM64?
Retrieved from "https://www.voipmonitor.org/doc/index.php?title=FAQ&oldid=10684"