FAQ: Difference between revisions

From VoIPmonitor.org
(Add troubleshooting for 'Error, conversion failed, audio file was not created from pcap')
(Add clarification about on-demand audio extraction vs saveaudio option)
 
(40 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{DISPLAYTITLE:FAQ & Common Issues}}
[[Category:GUI manual]]
[[Category:GUI manual]]


This page provides troubleshooting tips and debugging techniques for the VoIPmonitor web GUI.
'''Quick answers to frequently asked questions. For detailed troubleshooting, see [[Sniffer_troubleshooting|Sniffer Troubleshooting]] and [[GUI_troubleshooting|GUI Troubleshooting]].'''


== Known GUI Bugs and Workarounds ==
== Quick Navigation ==
 
{| class="wikitable" style="width:100%; margin-bottom:20px;"
=== Dashboard Edit Icon Grayed Out ===
|-
 
! style="width:25%; background:#e6f2ff;" | General
If admin users are unable to rename dashboards or edit metrics and the edit icons are consistently grayed out on the "Manage Dashboards" page, this is a known GUI issue.
! style="width:25%; background:#e6ffe6;" | Configuration
 
! style="width:25%; background:#fff2e6;" | Licensing
==== Symptoms ====
! style="width:25%; background:#ffe6e6;" | Audio & Files
 
|-
* Admin users cannot rename dashboards
| style="vertical-align:top; padding:8px;" |
* Edit icons on the "Manage Dashboards" page are grayed out (disabled)
* [[#General_&_Architecture|Architecture]]
* The issue affects all admin users, not just specific accounts
* [[#Platform_Support|Platform Support]]
* The `readonly` directive in `voipmonitor.conf` is NOT enabled
* [[#CDR_View|CDR View]]
 
| style="vertical-align:top; padding:8px;" |
==== Workaround ====
* [[#Protocols_&_Ports|Protocols & Ports]]
 
* [[#RTP_&_Quality_Metrics|RTP & Quality]]
The edit icon within the dashboard view may not work, but users can successfully rename dashboards directly from the main list of dashboards:
* [[Capture_rules|Capture Rules]]
 
| style="vertical-align:top; padding:8px;" |
# Navigate to the main dashboard list (not within a specific dashboard)
* [[#Licensing|Channels & Limits]]
# Find the dashboard you want to rename in the list
* [[#Licensing|HWID Issues]]
# Use the rename option available in the main dashboard list
* [[#Licensing|License Transfer]]
 
| style="vertical-align:top; padding:8px;" |
The issue of editing metrics from the "Manage Dashboards" page is under investigation and does not currently have a workaround.
* [[#Audio_&_PCAP_Files|Recording Limits]]
 
* [[#Audio_&_PCAP_Files|Codec Support]]
==== Note ====
* [[#Compliance|PCI/CALEA]]
 
|}
This is distinct from the global read-only mode issue (see the "readonly" directive in [[Configuration_file_options]] under GUI options). This known bug affects users even when read-only mode is NOT enabled.
 
== RTP Audio Playback Not Available in GUI ==
 
If RTP streams are not available for download or playback in the GUI and no WAV files are generated, even though SIP signaling and QoS metrics are visible, the issue is that the sensor is not configured to save the audio payload of RTP packets.
 
=== Symptoms ===
 
* SIP packets are being captured and visible (signaling works)
* QoS metrics like jitter, packet loss, and MOS are calculated and displayed
* No audio playback option (Play button) is available in the CDR view
* No WAV files are being generated in the spool directory
* PCAP files may be saved but without RTP payload data
 
=== Root Cause ===
 
By default, or in configurations optimized for low disk usage, VoIPmonitor may only save RTP packet headers (needed for QoS calculations) without capturing the RTP payload (the actual audio data). This allows QoS metrics to work but prevents audio playback and WAV file generation.
 
=== Solution ===
 
To enable audio playback in the GUI and WAV file generation, configure the sniffer to save full RTP packets.
 
==== Step 1: Enable RTP Packet Saving ===
 
Edit the `/etc/voipmonitor.conf` file and add or modify the `savertp` option:
 
<syntaxhighlight lang="ini">
# Save full RTP packets (required for audio playback)
savertp = yes
</syntaxhighlight>
 
Notes:
* `savertp = yes` saves both headers and payload (enables audio playback)
* `savertp = header` saves only headers (QoS metrics only, no audio)
* The default setting varies by configuration and may not save audio payload
 
==== Step 2: Restart VoIPmonitor Service ===
 
Apply the configuration change by restarting the VoIPmonitor service:
 
<syntaxhighlight lang="bash">
# Restart the VoIPmonitor service
systemctl restart voipmonitor


# Verify the service is running correctly
== General & Architecture ==
systemctl status voipmonitor
</syntaxhighlight>


==== Step 3: Verify the Fix ===
;How does VoIPmonitor scale for high traffic?
:For hardware recommendations and optimization of CPU, Disk I/O, and Database bottlenecks, see [[Scaling|Scaling and Performance Tuning]].


After restarting the service:
;How do I manage disk space and database retention?
:See [[Data_Cleaning|Data Cleaning and Retention]] for PCAP cleanup (cleanspool) and CDR retention settings.


1. Make a test call that generates RTP traffic
;Can I run multiple GUI instances for redundancy?
2. Navigate to the CDR listing in the web GUI
:Yes. Requirements:
3. Look for a Play (▶) icon in the player column for the test call
:* All GUIs connect to the same database
4. Check your spool directory (typically `/var/spool/voipmonitor/`) for RTP packets containing audio data
:* PCAP storage accessible via NFS/SSHFS
:* Same <code>key.php</code> license file on each GUI


=== Additional Notes ===
:{{Warning|1='''CRITICAL:''' Enable the cron job on '''only ONE''' GUI instance. Multiple active cron jobs cause duplicate alerts and reports.}}
:<syntaxhighlight lang="bash"># Disable on secondary GUIs:
# * * * * * root php /var/www/html/php/run.php cron</syntaxhighlight>


The [[Sniffer_configuration]] page documents additional audio-related options:
;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.


* `saveaudio = wav` - Generates standalone WAV files in addition to PCAP files (adds CPU/I/O load, generally not necessary for GUI playback)
== Platform Support ==
* `wav = ` - Individual codec-specific options (not typically needed)
* `saveaudio_stereo`, `saveaudio_from_first_invite` - Audio format controls


However, for basic GUI audio playback, setting `savertp = yes` is sufficient. The other options are for specialized use cases.
;What architectures are supported?
 
:{| class="wikitable"
=== Related Information ===
 
* [[Sniffer_configuration]] - Full reference for all voipmonitor.conf options
* [[Manual_PCAP_Extraction_from_spooldir]] - Manual PCAP and audio extraction procedures
* [[Download_of_pcap_files_/_audio_files_using_GUI's_api]] - Programmatic audio file access
 
== "Error, conversion failed, audio file was not created from pcap" Message ==
 
If you encounter the error message **"Error, conversion failed, audio file was not created from pcap"** when attempting to download a media trace (audio file) from the GUI, this indicates that while the PCAP file exists and is accessible, VoIPmonitor cannot generate audio (WAV) from it. This error typically has two distinct root causes that require different diagnostic approaches.
 
=== Symptoms ===
 
* Error message appears when clicking the "Audio" download button in the CDR view
* The media trace download fails with the conversion error
* The PCAP download works correctly, but audio conversion fails
* The error message is specific to the conversion process, not file access
 
=== Root Causes and Diagnostic Workflow ===
 
Follow this diagnostic workflow to identify which scenario applies to your case:
 
==== Step 1: Download and Examine the PCAP File ===
 
First, download the PCAP file associated with the CDR in question. Then use Wireshark or tshark to verify whether the PCAP contains actual RTP audio packets.
 
<syntaxhighlight lang="bash">
# Download the PCAP from the GUI CDR view
 
# Method 1: Use tshark from command line (quick test)
tshark -r downloaded.pcap -Y "rtp" | head -20
 
# If no output, try checking for RTCP only (control packets, no audio)
tshark -r downloaded.pcap -Y "rtcp" | head -20
 
# Method 2: Use tcpdump (alternative)
tcpdump -r downloaded.pcap -nn 'rtp[1] & 0x7f == 0' -c 5
</syntaxhighlight>
 
==== Scenario A: No RTP Packets Found (Most Common) ===
 
If your search returns **zero RTP packets**, this indicates that RTP audio payload was never captured or has been removed from storage. This is a data retention policy issue, not a conversion failure.
 
'''Root Cause Analysis:'''
 
Check the following possibilities:
 
1. **RTP was captured but removed by retention policies:**
  # Check your retention settings in /etc/voipmonitor.conf
  grep -E "maxpoolrtp|maxpool|maxpooldays" /etc/voipmonitor.conf
 
  Look for:
  * <code>maxpoolrtpsize</code> - Size limit for RTP files
  * <code>maxpoolrtpdays</code> - Age limit for RTP files
  * <code>maxpooldays</code> - Overall age limit
 
  The RTP directory for this call's date may have been cleaned up while SIP files remain.
 
2. **RTP was never captured (configuration issue):**
  # Check RTP capture settings
  grep -E "savertp|savertcp" /etc/voipmonitor.conf
 
  Possible causes:
  * <code>savertp = no</code> - RTP audio is disabled
  * <code>savertp = header</code> - Only RTP headers captured (no audio payload)
  * <code>savertcp = yes</code> - Saves RTCP control packets (not audio)
 
'''Solution:'''
 
Adjust your data retention policies to ensure RTP packets are kept as long as needed:
 
<syntaxhighlight lang="ini">
# Edit /etc/voipmonitor.conf
 
# Increase RTP retention (size-based)
maxpoolrtpsize = 204800    # 200 GB for RTP files (adjust based on disk)
 
# OR Increase RTP retention (time-based)
maxpoolrtpdays = 30      # Keep RTP files for 30 days
 
# Ensure overall limit allows sufficient space
maxpoolsize = 512000      # Overall spool limit (must accommodate RTP + SIP + other)
</syntaxhighlight>
 
Apply changes:
<syntaxhighlight lang="bash">
systemctl restart voipmonitor
</syntaxhighlight>
 
For detailed information on retention configuration, see [[Data_Cleaning]].
 
==== Scenario B: RTP Packets Present but Conversion Fails ===
 
If the PCAP file contains RTP packets with actual audio payload but audio conversion still fails, this indicates a more complex issue that requires investigation.
 
'''Symptoms:'''
* tshark shows RTP packets with payload
* Wireshark "RTP Stream Analysis" shows audio data
* Error persists despite RTP being present in the PCAP
 
'''Potential Causes:*
* Unsupported codec or codec configuration issue
* Corrupted or malformed RTP packets
* Complex codec negotiation not fully understood
* Specialized call setup or encryption causing conversion issues
 
'''Solution: Share the PCAP File with Support ===
 
For this scenario, the issue requires further investigation by VoIPmonitor support. Please:
 
1. Download the complete PCAP file from the GUI
2. Document the call details (CDR ID, calldate, codec used)
3. Share the PCAP file with VoIPmonitor support for analysis
4. Include any error messages or logs from the conversion attempt
 
This allows support to reproduce and diagnose the specific conversion failure.
 
=== Additional Diagnostic Tips ===
 
{| class="wikitable"
! Symptom ! Likely Cause ! Resolution
|-
| Only SIP packets in PCAP | RTP packets not captured | Check <code>savertp</code> setting, ensure audio recording is enabled
|-
|-
| Only RTCP packets in PCAP | Only control traffic captured | Check <code>savertcp=yes</code> with <code>savertp=no</code>, audio payload not saved
! Component !! Supported !! Notes
|-
|-
| PCAP empty or very small | Capture issues or corruption | Verify packet capture interface and check for dropped packets
| Sensor || x86 (32/64-bit), ARMv7/v8 || Compile from source for ARM64
|-
|-
| RTP present but no audio | Codec or payload issue | Share PCAP with support for analysis
| GUI || x86 only || '''Not supported''' on ARM64/aarch64
|}
|}


=== Quick Reference: Common Configuration Issues ===
;Can I run VoIPmonitor on AWS?
:Yes. For license detection: <code>chmod 644 /dev/root</code>
:* '''Stop/Start instance:''' HWID usually preserved
:* '''Terminate/Launch new:''' HWID changes, requires new license key


<syntaxhighlight lang="ini">
;Is Docker supported?
# Common problematic configurations:
:Yes, but ensure <code>/proc/self/cgroup</code> content doesn't change between restarts (affects HWID stability).


# Problem 1: RTP audio disabled
;Are cloud databases (RDS, Azure) supported?
savertp = no              # No RTP audio is captured
:Yes. Requires MySQL-compatible database with <code>SUPER</code> privilege. If unavailable, set:
# Fix: savertp = yes
:<syntaxhighlight lang="ini">log_bin_trust_function_creators = ON</syntaxhighlight>


# Problem 2: Only RTCP control packets
;Why is mysql_native_password deprecated?
savertcp = yes            # Saves RTCP (no audio)
:PHP 7.4.4+ supports <code>caching_sha2_password</code> natively. Upgrade PHP and reinstall IonCube Loader. See [[GUI_installation|GUI Installation]].
savertp = no              # RTP audio disabled
# Fix: savertp = yes, savertcp = no (if RTCP not needed)


# Problem 3: Headers only (QoS metrics but no audio)
== CDR View ==
savertp = header          # Only RTP headers, no payload
# Fix: savertp = yes


# Problem 4: RTP retention too short
;What does the red icon mean?
maxpoolrtpdays = 7        # RTP deleted after 7 days
:Indicates which party sent the <code>BYE</code> message (ended the call).
maxpooldays = 60          # SIP kept for 60 days
# Fix: Increase maxpoolrtpdays to match desired retention
</syntaxhighlight>


=== Related Information ===
;How do I filter with regular expressions?
:Prefix with <code>R()</code>. Example: <code>R(^500[0-9]{4}$)</code>


* [[Data_Cleaning]] - Comprehensive guide on data retention policies
;How do I exclude values from filters?
* [[Sniffer_configuration#Saving_Options]] - Sniffer configuration for RTP saving options
:Use <code>!</code> prefix:
* [[Manual_PCAP_Extraction_from_spooldir]] - Manual PCAP and audio conversion procedures
:* <code>!123456</code> – exclude specific number
:* <code>!00420%</code> – exclude prefix
:* <code>222%, !223%</code> – include 222*, exclude 223*


== GUI Debug Mode ==
;How do I search multi-word strings in custom headers?
:Use underscore for spaces: <code>%normal_call_clearing%</code>


The GUI debug mode allows you to see SQL queries and other debugging information directly in your browser's Developer Console.
;Why are caller/called numbers swapped?
: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]].


=== Enabling Debug Mode ===
;Why is there a delay before CDRs appear?
:Database can't keep up. See [[Database_troubleshooting#SQL_Queue_and_CDR_Delays|SQL Queue Troubleshooting]].


To enable debug mode in the VoIPmonitor web GUI, '''add the parameter <code>?debug=31415</code> to the end of any GUI URL'''. For example:
== Protocols & Ports ==


<code>http://your-server/voipmon/admin.php?debug=31415</code>
;Which protocols are supported?
 
:{| class="wikitable"
This enables the following features:
|-
* SQL queries executed by the GUI are logged to the browser's Developer Console
! Supported !! Not Supported
* Additional debugging information is displayed for dashboard panels and charts
|-
* Performance timing and query execution details become visible
| SIP, Skinny/SCCP, MGCP, SS7/ISUP, Diameter, RTCP || '''H.323''', '''MEGACO/H.248'''
 
|}
=== Finding SQL Queries for Dashboard Panels ===
 
To see the exact SQL query executed by a dashboard panel:
 
# Add <code>?debug=31415</code> to your GUI URL and navigate to the dashboard
# Open your browser's Developer Tools (press F12 or Ctrl+Shift+I)
# Switch to the '''Console''' tab
# Interact with the dashboard (e.g., refresh, change time range, or hover over panels)
# The SQL queries will be printed to the console log
 
The queries appear in the console in the order the panels are rendered. If you need to isolate a specific panel, hover over it or interact with its filters after loading the page - this often triggers a re-query which will appear as a new entry in the console.
 
=== Disabling Debug Mode ===
 
Simply remove the <code>?debug=31415</code> parameter from the URL, or navigate to any GUI page without it. Debug mode is not persistent and must be re-enabled each time by adding the URL parameter.
 
== GUI Upgrade Issues ==
 
The following are common issues that may occur during GUI upgrades and their solutions.
 
=== Upgrade Option Not Visible or Functional ===
 
If the VoIPmonitor GUI indicates an upgrade is available but the upgrade button or link is not visible or functional, try the following steps in order:
 
==== Step 1: Refresh Your Session ====
 
The GUI may be showing outdated information from your session. Log out of the GUI and log back in. Check the top right corner of the interface for the upgrade link again.
 
Often, the upgrade indication persists from an earlier version check, and refreshing the session updates the display to show the correct upgrade options.
 
==== Step 2: Force Upgrade via Command Line ====
 
If the upgrade button is still not visible or the web-based upgrade is stuck, you can force the upgrade via the command line on the GUI server:
 
<syntaxhighlight lang="bash">
# Log in to the GUI host as root
# Navigate to the GUI installation directory (default is /var/www/html)
cd /var/www/html
 
# Execute the forced upgrade command
php php/run.php upgrade -f
</syntaxhighlight>
 
The <code>-f</code> flag forces a complete upgrade, which updates any missing or stuck GUI components.
 
This method is useful when the web interface is not responding correctly or the upgrade process appears to be stuck for an extended period.
 
=== "Invalid compressed data in update file" Error ===
 
If the GUI update fails with the error "Invalid compressed data in update file", this is often caused by incorrect ownership of the web root directory. The web server user needs write permission to extract and install the update files.
 
==== Symptoms ====
 
* GUI update aborts with error: <code>"Invalid compressed data in update file"</code>
* Manual reinstallation via tar.gz extraction works fine
* The update process cannot write files to the web root directory
 
==== Root Cause ====
 
The web server process (Apache, httpd, nginx, etc.) runs under a specific user account (typically <code>apache</code>, <code>www-data</code>, or <code>nginx</code>). If the web root directory (typically <code>/var/www/html</code> or <code>/var/www/voipmonitor</code>) is owned by a different user, the update process will fail when attempting to extract and install the update files. The error message is misleading and appears to indicate a corrupted download, but the actual issue is a write permission problem.
 
==== Solution: Fix Web Root Directory Ownership ====
 
Verify and fix the ownership of the web root directory:
 
<syntaxhighlight lang="bash">
# Check current ownership of the web root
ls -ld /var/www/html
# or
ls -ld /var/www/voipmonitor
 
# Determine your web server user:
# Debian/Ubuntu: www-data
# CentOS/RHEL: apache
# Nginx: nginx
 
# Fix ownership - replace with your actual web server user and path
# For Debian/Ubuntu
sudo chown -R www-data:www-data /var/www/html
 
# For CentOS/RHEL/AlmaLinux
sudo chown -R apache:apache /var/www/html
 
# For Nginx
sudo chown -R nginx:nginx /var/www/html
</syntaxhighlight>
 
After fixing the ownership, retry the GUI update process.
 
==== Verifying the Fix ====
 
Ensure the web server user can write to the web root:
 
<syntaxhighlight lang="bash">
# For Debian/Ubuntu
sudo -u www-data touch /var/www/html/test_write
sudo rm /var/www/html/test_write
 
# For CentOS/RHEL
sudo -u apache touch /var/www/html/test_write
sudo rm /var/www/html/test_write
</syntaxhighlight>
 
If the test file can be created and deleted, ownership is correct.
 
=== Browser Cache Issues After GUI Upgrade ===
If specific features stop working immediately after a GUI upgrade (for example, IP lookup not translating addresses, missing icons, broken styling, or JavaScript errors), the issue is likely caused by outdated browser cache. The browser may be serving stale JavaScript, CSS, and other assets from the previous GUI version.
 
==== Symptoms ====
 
* Features that worked before the upgrade now fail or behave unexpectedly
* IP address lookup (GeoIP resolution) shows no translated addresses
* Icons, buttons, or interface elements appear broken or missing
* Visual styling appears incorrect or outdated
* The issue persists even after restarting the web server
* The problem only affects one browser, and clearing cache fixes it
 
==== Root Cause ====
 
Web browsers cache static assets (JavaScript files, CSS stylesheets, images) to improve performance. When you upgrade the VoIPmonitor GUI, these assets are replaced with new versions. However, if the browser continues to serve cached versions of these files from the previous release, the GUI will not function correctly until the cache is cleared.
 
==== Solution: Clear Browser Cache and Cookies ====
 
The fastest and most reliable fix is to clear the browser cache and cookies, or perform a hard refresh.
 
'''Option 1: Hard Refresh (Quickest)'''
 
Perform a hard refresh to force the browser to reload all assets:
* Windows/Linux: Press <code>Ctrl+F5</code> or <code>Ctrl+Shift+R</code>
* Mac: Press <code>Cmd+Shift+R</code>
 
'''Option 2: Clear Full Browser Cache and Cookies (Recommended After GUI Upgrades)'''
 
For a complete cache clear:
* Chrome/Edge: Press <code>Ctrl+Shift+Delete</code> (Windows) or <code>Cmd+Shift+Delete</code> (Mac), select "Cached images and files" and "Cookies and other site data", then click "Clear data"
* Firefox: Press <code>Ctrl+Shift+Delete</code> (Windows) or <code>Cmd+Shift+Delete</code> (Mac), select "Cache" and "Cookies", then click "Clear Now"
* Safari: Press <code>Cmd+Option+E</code> to clear cache, and Preferences > Privacy > Manage Website Data to clear cookies
 
'''Important:''' After a GUI upgrade, it is recommended to perform a hard refresh or clear the cache entirely to ensure the latest assets are loaded.
 
==== Verification ====
 
After clearing the cache:
# Reload the GUI page
# Verify that the previously broken feature now works correctly
# Check that visual styling appears correct
# Test functionality across different browsers if available
 
If the problem persists after clearing the cache, proceed to other troubleshooting steps in this guide.
 
=== Web Portal Inaccessible After Upgrade ===
If the web portal becomes inaccessible immediately after attempting an upgrade, the web server service may need to be restarted to load the new GUI files correctly. This is often the quickest fix after completing an upgrade.
 
==== Step 1: Check Web Server Status ====
First, verify that the web server service is running normally:
 
<syntaxhighlight lang="bash">
# For CentOS/RHEL/AlmaLinux with httpd
sudo systemctl status httpd
 
# For Debian/Ubuntu with Apache
sudo systemctl status apache2
 
# For nginx with PHP-FPM
sudo systemctl status php-fpm
</syntaxhighlight>
 
If the service is not running or showing errors, check the web server error logs for specific error indicators:
 
<syntaxhighlight lang="bash">
# Check Apache/httpd error log
sudo tail -50 /var/log/httpd/error_log
 
# For Debian/Ubuntu systems
sudo tail -50 /var/log/apache2/error.log
</syntaxhighlight>
 
Look for error patterns like:
* <code>SIGSEGV</code> (segmentation fault)
* PHP module loading errors
* Permission denied errors
* Configuration file syntax errors
 
==== Step 2: Restart the Web Server ====
If the service is running but not responding correctly, restart it to load the new GUI files:
 
<syntaxhighlight lang="bash">
# For CentOS/RHEL/AlmaLinux with httpd
sudo systemctl restart httpd
 
# For Debian/Ubuntu with Apache
sudo systemctl restart apache2
 
# For nginx with PHP-FPM
sudo systemctl restart php-fpm
</syntaxhighlight>
 
==== Step 3: Verify Local Access ====
After restarting, verify that the web server is responding locally:
 
<syntaxhighlight lang="bash">
# Test local access to web server
wget -O - http://127.0.0.1
</syntaxhighlight>
 
If this command succeeds and returns HTML content, the web server is working correctly. If it fails, there is a web server configuration issue.
 
==== Step 4: Check Firewall Rules ====
If local access works but the portal is still inaccessible from external clients, check firewall rules to ensure HTTP/HTTPS ports are not blocked:
 
<syntaxhighlight lang="bash">
# Check firewalld rules (RHEL/CentOS/AlmaLinux)
sudo firewall-cmd --list-all
 
# Check iptables rules
sudo iptables -L -n
 
# Open HTTP/HTTPS ports if blocked (firewalld)
sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --reload
</syntaxhighlight>
 
Ensure that ports 80 (HTTP) and 443 (HTTPS) are allowed through the firewall.
 
==== Verification ====
After completing all troubleshooting steps:
1. Try accessing the web portal from a web browser
2. Verify that the login page appears correctly
3. Test login to ensure full GUI functionality
 
If the portal is now accessible, the upgrade was successful. If the issue persists after all troubleshooting steps, consider performing a full GUI reinstallation or contacting VoIPmonitor support.
 
=== VM Binary (binary missing) Error ===
 
If you encounter an error message indicating "VM Binary (binary missing)" during or after a GUI upgrade, this indicates that the GUI application files were not completely updated. Perform a forced CLI upgrade to resolve this issue:
 
==== Step 1: Verify Internet Connectivity ====
 
Before running the upgrade, ensure the server has internet connectivity to download the latest GUI files.
 
<syntaxhighlight lang="bash">
# Test internet connectivity
ping -c 4 8.8.8.8
 
# Test DNS resolution
ping -c 4 voipmonitor.org
</syntaxhighlight>
 
If the server cannot reach the internet, resolve network connectivity issues before proceeding with the upgrade.
 
==== Step 2: Perform Forced CLI Upgrade ====
 
<syntaxhighlight lang="bash">
# Log in to the GUI host as root
# Navigate to the GUI installation directory (default is /var/www/html)
cd /var/www/html
 
# Execute the forced upgrade command
php php/run.php upgrade -f
</syntaxhighlight>
 
The <code>-f</code> flag forces a complete upgrade, which updates any missing or corrupt GUI binaries.
 
==== Step 3: Verify and Retry if Issue Persists ====
 
If the web interface remains inaccessible after running the forced upgrade command, verify that the application files are present and the version matches the latest release:
 
<syntaxhighlight lang="bash">
# Check if application files are present
find /var/www/html | grep 'app-'
 
# This should show something like:
# /var/www/html/app-2025.01.01/
# Verify the version is the latest available release
</syntaxhighlight>
 
If the version does not match the latest release or if no <code>app-</code> directories are found, re-run the forced upgrade command:
 
<syntaxhighlight lang="bash">
cd /var/www/html
php php/run.php upgrade -f
</syntaxhighlight>
 
=== Blank Screen with JavaScript ReferenceError After Update ===
 
If you can log in to the GUI after an update but are presented with a blank screen, and the browser's JavaScript console shows an error like:
 
<code>ReferenceError: _AuditActivity_download_wav is not defined</code>
 
This is typically caused by a conflicting PEAR file that was not removed during the upgrade. The fix is simple:
 
<syntaxhighlight lang="bash">
# Remove the conflicting old PEAR constants file
rm /usr/share/pear/constants.php
 
# Refresh your browser (Ctrl+Shift+R) to reload the GUI
</syntaxhighlight>
 
After removing this file and refreshing the browser, the GUI should load correctly. This issue occurs because the old <code>constants.php</code> file from the system's PEAR installation conflicts with VoIPmonitor's internal JavaScript definitions.
 
=== Blank Screen Due to SELinux ===
 
If you can log in to the GUI but are presented with a blank white screen, and there are no JavaScript errors in the browser console, the issue may be caused by SELinux blocking access to required resources. This is particularly common on RHEL/CentOS/AlmaLinux systems where SELinux is enabled by default.
 
==== Diagnosis: Check if SELinux is Running
 
First, verify that SELinux is enabled and in enforcing mode:
 
<syntaxhighlight lang="bash">
# Check current SELinux status
getenforce
 
# Common values: Enforcing (active), Permissive (logging only), Disabled
</syntaxhighlight>
 
If the output is <code>Enforcing</code>, proceed to the solution.
 
==== Solution: Disable SELinux
 
'''Permanently disable SELinux:'''
 
Edit the SELinux configuration file:
 
<syntaxhighlight lang="bash">
sudo nano /etc/selinux/config
</syntaxhighlight>
 
Change <code>SELINUX=enforcing</code> to:
 
<pre>SELINUX=disabled</pre>
 
Then reboot the server:
 
<syntaxhighlight lang="bash">
sudo reboot
</syntaxhighlight>
 
After the reboot, the GUI should load correctly.
 
'''Temporarily disable SELinux (for testing):'''
 
If you want to test whether SELinux is the cause without rebooting:
 
<syntaxhighlight lang="bash">
# Temporarily switch SELinux to permissive mode
sudo setenforce 0
</syntaxhighlight>
 
This change only lasts until the next reboot. If this resolves the blank screen issue, follow the permanent disable instructions above.
 
==== Related Information
 
SELinux is a security feature that enforces mandatory access control policies. While it provides strong security, it can interfere with web applications that require access to files outside standard locations or that use non-standard system calls. If you require SELinux for security compliance, you may need to create custom SELinux policies to allow VoIPmonitor instead of disabling it entirely.
 
=== "unable to remove old files" During GUI Upgrade ===
 
If the GUI upgrade process fails with an "unable to remove old files" error and the issue is not related to web directory ownership, the problem may be caused by incorrect ownership of the `tshark` binary used during the upgrade process.
 
==== Symptoms ====
 
* GUI upgrade fails with "unable to remove old files" error
* Error persists after fixing web directory ownership
* TShark binary cannot be overwritten or replaced during upgrade
* Upgrade process cannot access system binaries
 
==== Root Cause ====
 
The VoIPmonitor GUI upgrade process may attempt to update or use the `tshark` binary during the upgrade. If the `tshark` binary is owned by a user other than the web server user (e.g., owned by `root`), the web server process cannot modify or replace it, causing the upgrade to fail.
 
==== Solution: Fix tshark Binary Ownership ====
 
Identify the `tshark` binary location and change its ownership to the web server user:
 
<syntaxhighlight lang="bash">
# Find the location of tshark
which tshark
# Common locations: /usr/bin/tshark, /usr/sbin/tshark, /usr/local/bin/tshark
 
# Check current ownership
ls -l $(which tshark)
 
# Determine your web server user:
# Debian/Ubuntu: www-data
# CentOS/RHEL: apache
# Nginx: nginx
 
# Fix ownership - replace /usr/bin/tshark with actual path and www-data with your web server user
sudo chown www-data:www-data /usr/bin/tshark
 
# For CentOS/RHEL
sudo chown apache:apache /usr/bin/tshark
 
# For Nginx
sudo chown nginx:nginx /usr/bin/tshark
</syntaxhighlight>
 
==== Verification ====
 
Verify the ownership has been fixed:
 
<syntaxhighlight lang="bash">
# Check that the web server user owns tshark
ls -l /usr/bin/tshark
# Should show: -rwxr-xr-x 1 www-data www-data ... /usr/bin/tshark
# (or apache/apache, nginx/nginx depending on your system)
</syntaxhighlight>
 
After fixing the ownership, retry the GUI upgrade process through the web interface.
 
=== apilicensecheck.php Fatal Error: Call to undefined function findExecutableFile() ===
 
'''Do NOT reinstall the entire GUI to fix this error. Use the patched file instead.'''
 
When calling the Check License API endpoint (<code>php/apilicensecheck.php</code>), you may encounter the following PHP fatal error:
 
<code>Call to undefined function findExecutableFile()</code>
 
This is a known bug in specific GUI versions where the <code>findExecutableFile()</code> function is missing. A full GUI reinstallation is '''not required''' to fix this issue. The solution is to replace '''only''' the affected file with a patched version provided by VoIPmonitor support.
 
==== Solution: Replace apilicensecheck.php with Patched File ====
 
To resolve this issue, obtain the patched <code>apilicensecheck.php</code> file from VoIPmonitor support and perform the following steps:
 
<syntaxhighlight lang="bash">
# 1. Navigate to your GUI installation directory (default is /var/www/html)
cd /var/www/html
 
# 2. Back up the original file
sudo cp php/apilicensecheck.php php/apilicensecheck.php.backup
 
# 3. Replace with the patched file from support
# (Copy the patched file to this location, preserving permissions)
sudo cp /path/to/patched/apilicensecheck.php php/apilicensecheck.php
 
# 4. Ensure correct ownership and permissions
sudo chown www-data:www-data php/apilicensecheck.php
sudo chmod 644 php/apilicensecheck.php
 
# 5. Verify the fix by testing the API endpoint
curl "http://your-server/php/apilicensecheck.php?task=licenseCheck"
</syntaxhighlight>
 
You should receive a JSON response with the license status instead of a PHP error. Example successful responses:
 
<syntaxhighlight lang="json">
{"status":0,"message":"License OK."}
</syntaxhighlight>
 
or
 
<syntaxhighlight lang="json">
{"status":1,"message":"license file key.php expired. Current date: 2024-01-15 Expiration date: 2024-01-10"}
</syntaxhighlight>
 
''Note:'' The patched file must be obtained from VoIPmonitor support. This is not a self-service fix.
 
== MySQL/MariaDB Connection Limit Issues ==
 
If the VoIPmonitor GUI becomes inaccessible or generates database connection errors during normal operation, this may be caused by MySQL/MariaDB reaching its configured maximum connection limit. When the connection pool is exhausted, new GUI requests cannot establish database connections.
 
=== Symptoms ===
 
* GUI pages load slowly or fail to load entirely with database connection errors
* Error messages indicating "Too many connections" or MySQL/MariaDB connection failures
* Issue occurs under load or during periods of high activity
* Database service is running but GUI cannot connect
* The problem resolves temporarily after restarting MySQL/MariaDB, then recurs
 
=== Diagnosis
 
Check the current MySQL/MariaDB connection usage and limit:
 
<syntaxhighlight lang="bash">
# Check current connection limit
mysql -u root -p -e "SHOW VARIABLES LIKE 'max_connections';"
 
# Check number of active connections
mysql -u root -p -e "SHOW STATUS LIKE 'Threads_connected';"
 
# Check connection usage history
mysql -u root -p -e "SHOW STATUS LIKE 'Max_used_connections';"
</syntaxhighlight>
 
If <code>Threads_connected</code> is close to or equal to <code>max_connections</code>, the connection pool is full.
 
=== Root Cause
 
The <code>max_connections</code> parameter in MySQL/MariaDB configuration specifies the maximum number of simultaneous client connections the database server will accept. This limit is set to prevent the server from being overwhelmed by too many simultaneous connections.
 
In high-traffic VoIPmonitor deployments, especially with:
* Multiple sensors writing simultaneously
* Concurrent GUI users accessing dashboards and reports
* Background jobs and reporting queries
 
The default connection limit (typically 151 or similar) may be insufficient.
 
=== Solution: Increase MySQL/MariaDB Connection Limit ===
 
==== Step 1: Identify MySQL Configuration File Location
 
Find the active MySQL/MariaDB configuration file:
 
<syntaxhighlight lang="bash">
# Common locations:
# Debian/Ubuntu:  /etc/mysql/my.cnf or files in /etc/mysql/mysql.conf.d/
# CentOS/RHEL:  /etc/my.cnf
 
# Check which file is being used
mysql --help | grep "Default options" -A 1
</syntaxhighlight>
 
==== Step 2: Locate and Edit max_connections Parameter
 
Open the MySQL configuration file:
 
<syntaxhighlight lang="bash">
# Debian/Ubuntu
sudo nano /etc/mysql/mysql.conf.d/mysqld.cnf
# or check files in /etc/mysql/
 
# CentOS/RHEL
sudo nano /etc/my.cnf
</syntaxhighlight>
 
Locate the <code>[mysqld]</code> section and find or add the <code>max_connections</code> parameter:
 
<syntaxhighlight lang="ini">
[mysqld]
max_connections = 500
</syntaxhighlight>
 
Choose a value suitable for your expected load:
* Small deployments: 200-300
* Medium deployments: 500
* Large deployments with many sensors and users: 1000 or more
 
'''Note:''' Increasing <code>max_connections</code> requires that the server has sufficient RAM to handle the additional connections. MySQL allocates memory for each connection thread.
 
==== Step 3: Restart MySQL/MariaDB Service
 
Apply the changes by restarting the database service:
 
<syntaxhighlight lang="bash">
# Debian/Ubuntu (MySQL)
sudo systemctl restart mysql
 
# Debian/Ubuntu (MariaDB)
sudo systemctl restart mariadb
 
# CentOS/RHEL (MySQL/MariaDB)
sudo systemctl restart mysqld
# or
sudo systemctl restart mariadb
</syntaxhighlight>
 
==== Step 4: Verify the New Limit
 
Confirm that the new limit is active:
 
<syntaxhighlight lang="bash">
mysql -u root -p -e "SHOW VARIABLES LIKE 'max_connections';"
</syntaxhighlight>
 
The output should reflect your new setting (e.g., <code>500</code>).
 
=== Monitoring Connection Usage ===
 
To proactively monitor connection usage:
 
<syntaxhighlight lang="bash">
# Check current usage percentage
mysql -u root -p -e "
SELECT
  ROUND(Threads_connected / max_connections * 100, 2) AS usage_percent,
  Threads_connected AS active_connections,
  max_connections AS max_limit
FROM information_schema.global_status, (
  SELECT @@max_connections AS max_connections
) AS vars;
"
</syntaxhighlight>
 
If usage consistently exceeds 80% of max_connections, consider further increasing the limit or optimizing database queries.
 
=== Related Parameters
 
Consider adjusting these additional parameters along with <code>max_connections</code>:
 
''Table cache (''<code>table_open_cache</code>''):''<syntaxhighlight lang="ini">
table_open_cache = 4000
</syntaxhighlight>
 
Increases the number of tables MySQL can keep open simultaneously.
 
''Thread cache (''<code>thread_cache_size</code>''):''<syntaxhighlight lang="ini">
thread_cache_size = 100
</syntaxhighlight>
 
Caches connection threads to avoid creating new threads for each connection, reducing overhead.
 
=== Connection Pool Optimization in VoIPmonitor ===
 
If you consistently hit connection limits, also consider tuning the VoIPmonitor GUI database connection settings in the GUI configuration:
 
* Reduce concurrent database queries from the GUI
* Optimize dashboard queries to use fewer connections
* Implement database query result caching where possible
 
For advanced connection pooling, consider implementing a proxy layer such as ProxySQL.
 
== MySQL/MariaDB Database Corruption ==
 
If the Web GUI fails to start and logs show MySQL/MariaDB database errors (such as corrupted tables, missing files, or startup failures), this indicates database corruption. This can occur after manual file deletion, disk failures, or improper MySQL shutdown procedures.
 
=== Symptoms ===
 
* Web GUI displays database connection errors or shows a blank page
* MySQL/MariaDB service fails to start or immediately crashes
* Error messages in MySQL logs indicating corrupted tables or missing database files
* CDR queries return empty results or throw SQL errors
 
=== Diagnosis ===
 
First, check the MySQL/MariaDB service status:
 
<syntaxhighlight lang="bash">
# Check if MySQL/MariaDB is running
systemctl status mysql
# or
systemctl status mariadb
 
# View MySQL error logs for corruption indicators
tail -100 /var/log/mysql/error.log
# or
tail -100 /var/log/mariadb/mariadb.log
</syntaxhighlight>
 
Look for error messages such as:
* <code>Table is marked as crashed</code>
* <code>InnoDB: Database page corruption</code>
* <code>Incorrect key file</code>
* <code>Can't open file</code>
* <code>semaphore waits</code>
* <code>page corruption detected</code>
* <code>InnoDB: Assertion failure</code>
 
=== Solution: Table-Level Repair (mysqlcheck --repair) ===
 
If MySQL is running but specific tables in the voipmonitor database are corrupted, you can attempt to repair the tables without dropping the entire database. This method preserves CDR data when the corruption is limited to individual tables.
 
'''When to use table-level repair:'''
* MySQL service is running and accessible
* Only specific tables are corrupted (not the entire database)
* You want to preserve CDR data as much as possible
* Corruption is detected early and is not widespread
 
==== Step 1: Stop All VoIPmonitor Processes ====
 
Stop VoIPmonitor sensors to prevent write operations during repair:
 
<syntaxhighlight lang="bash">
# Stop all VoIPmonitor sensor services
systemctl stop voipmonitor
</syntaxhighlight>
 
==== Step 2: Repair Tables Using mysqlcheck ====
 
The <code>mysqlcheck</code> utility can repair corrupted MyISAM tables. For InnoDB tables, <code>mysqlcheck --repair</code> will attempt to analyze and fix corruption.
 
<syntaxhighlight lang="bash">
# Repair all tables in the voipmonitor database
mysqlcheck -u root -p --repair voipmonitor
 
# Repair a specific table
mysqlcheck -u root -p --repair voipmonitor cdr
 
# Check tables before repair (shows table status)
mysqlcheck -u root -p --auto-repair voipmonitor
</syntaxhighlight>
 
The <code>--auto-repair</code> option automatically repairs tables that show signs of corruption during the check. The <code>--repair</code> option forces repair on all tables even if they do not appear corrupted.
 
'''Important notes:'''
* <code>mysqlcheck --repair</code> works on MyISAM tables. For InnoDB tables, it may simply analyze and report problems without fixing them
* VoIPmonitor primarily uses InnoDB tables, so <code>REPAIR TABLE</code> SQL commands may be required directly
 
==== Step 3: Repair InnoDB Tables with REPAIR TABLE ====
 
For InnoDB tables (most VoIPmonitor tables), use the SQL <code>REPAIR TABLE</code> command:
 
<syntaxhighlight lang="bash">
mysql -u root -p voipmonitor
</syntaxhighlight>
 
Run the following SQL command to repair a specific table:
 
<syntaxhighlight lang="sql">
REPAIR TABLE cdr;
REPAIR TABLE cdr_next_partition;
REPAIR TABLE cdr_partition_202501;
</syntaxhighlight>
 
You can repair multiple tables in one statement:
 
<syntaxhighlight lang="sql">
REPAIR TABLE cdr, cdr_next_partition, cdr_partition_202501, sip, message;
</syntaxhighlight>
 
If <code>REPAIR TABLE</code> fails on InnoDB tables, this indicates more severe corruption that requires the <code>innodb_force_recovery</code> method (see below).
 
==== Step 4: Check Disk Space and Trim Large Tables ====
 
Large tables consuming excessive disk space can contribute to corruption and performance issues. Check and trim tables if necessary:
 
<syntaxhighlight lang="bash">
# Check table sizes
mysql -u root -p voipmonitor -e "SELECT table_name AS 'Table', ROUND(((data_length + index_length) / 1024 / 1024), 2) AS 'Size (MB)' FROM information_schema.TABLES WHERE table_schema = 'voipmonitor' ORDER BY (data_length + index_length) DESC LIMIT 10;"
</syntaxhighlight>
 
Identify very large tables and consider using the <code>DELETE</code> statement with a date filter to remove old data, or use VoIPmonitor's built-in <code>cleandatabase*</code> configuration options to trim data automatically.
 
For example, to delete old CDR records manually:
 
<syntaxhighlight lang="sql">
-- Delete CDRs older than 90 days (replace date as needed)
DELETE FROM cdr WHERE calldate < '2024-10-01';
 
-- Optimize table after deletion to reclaim space
OPTIMIZE TABLE cdr;
</syntaxhighlight>
 
'''Recommendation:** Instead of manual deletion, configure automatic data cleanup in <code>/etc/voipmonitor.conf</code>:
 
<syntaxhighlight lang="ini">
[general]
# Automatically delete old data
cleandatabase = 90
cleandatabasecdr = 90
cleandatabasemsg = 30
cleandatabaseregister = 7
</syntaxhighlight>
 
See the <code>Prevention: Automatic Database Cleanup</code> section below for more details.
 
==== Step 5: Restart Services ====
 
After the repair is complete, restart VoIPmonitor:
 
<syntaxhighlight lang="bash">
# Restart the sensor service
systemctl start voipmonitor
 
# Verify the service is running
systemctl status voipmonitor
 
# Check MySQL error logs for any new errors
tail -f /var/log/mysql/error.log
# or
tail -f /var/log/mariadb/mariadb.log
</syntaxhighlight>
 
If table repair was successful, the system should operate normally. If corruption persists or mysqlcheck reports errors that cannot be repaired, proceed to one of the full recovery methods (Drop and Recreate Database or innodb_force_recovery).
 
==== Step 6: Upgrade MySQL Server (Optional but Recommended) ====
 
After recovering from corruption, consider upgrading MySQL/MariaDB to the latest version in your current branch. This provides performance and stability improvements that can prevent future corruption.
 
For example, if you are running MySQL 5.7.33, upgrade to the latest 5.7.x version within the same series (not jumping to 8.0 unless you are prepared for a major upgrade).
 
<syntaxhighlight lang="bash">
# Check current version
mysql -V
 
# Debian/Ubuntu: Check available upgrades
apt list --upgradable | grep mysql-server
 
# Upgrade MySQL (distribution-specific commands vary)
# For Debian/Ubuntu:
sudo apt update
sudo apt upgrade mysql-server
 
# For CentOS/RHEL/AlmaLinux:
sudo yum update mysql-server
# or
sudo dnf upgrade mysql-server
</syntaxhighlight>
 
'''Important notes:'**
* Always backup your database before upgrading
* Test the upgrade on a development/staging system first if possible
* Major version upgrades (e.g., 5.7 to 8.0) require additional planning and testing
* Review the MySQL upgrade documentation for your version for any breaking changes
 
=== Which Recovery Method to Use ===
 
'''Use Table-Level Repair (First Attempt when MySQL is running):'''
* MySQL/MariaDB service is running and accessible
* Only specific tables are corrupted (not entire database)
* You want to preserve CDR data as much as possible
* Corruption appears mild and detected early
* System is experiencing poor performance but still accessible
 
This method uses <code>mysqlcheck --repair</code> or <code>REPAIR TABLE</code> to fix individual tables without dropping the database. See the <code>Solution: Table-Level Repair</code> section above.
 
'''Use Drop and Recreate Database (Simplest, when MySQL is running):'''
* MySQL/MariaDB service is running and accessible
* Only the voipmonitor database is corrupted
* You do not need to preserve CDR data (historical call records are acceptable to lose)
* You want to restore service quickly with minimal downtime
* GUI configuration loss is acceptable or will be reconfigured
 
'''Use innodb_force_recovery (Recommended for filesystem corruption/InnoDB assertion failures):'''
* MySQL fails to start after a filesystem issue (Read-only file system errors)
* InnoDB assertion failures during startup
* PCAP files may or may not be available in the spool directory
* You need to preserve GUI configuration (users, sensors, settings)
* You are willing to lose all CDR data if it cannot be restored from PCAP
 
'''Use PCAP restore (Alternative):'''
* PCAP files are definitely available and intact in the spool directory
* You want to restore historical CDR data along with GUI configuration
* The innodb_force_recovery method did not work
* You have time for a lengthy re-processing operation
 
=== Solution: Drop and Recreate Database (Simplest, When MySQL is Running) ===
 
If MySQL/MariaDB is running but only the voipmonitor database is corrupted, the fastest recovery method is to drop the corrupted database and let the sensor recreate it automatically.
 
'''Warning:''' This procedure will result in complete loss of all CDR data, call recordings, and GUI configuration. You will need to reconfigure sensors, users, and settings in the GUI.
 
==== Step 1: Stop All VoIPmonitor Sensor Processes ====
 
Stop all VoIPmonitor sensors to prevent further database corruption during the recovery process.
 
<syntaxhighlight lang="bash">
# Stop all VoIPmonitor sensor services
systemctl stop voipmonitor
 
# If running distributed (client/server mode), stop all sensor services:
# - On server sensors: systemctl stop voipmonitor-server
# - On client sensors: systemctl stop voipmonitor-client
# - Check all running sensors: ps aux | grep voipmonitor
</syntaxhighlight>
 
If you are using a client/server architecture, stop ALL sensors first, including both client and server sensors.
 
==== Step 2: Drop the Corrupted VoIPmonitor Database ====
 
Delete the corrupted voipmonitor database from MySQL/MariaDB.
 
<syntaxhighlight lang="bash">
# Connect to MySQL as root
mysql -u root -p
</syntaxhighlight>
 
Run the following SQL command:
 
<syntaxhighlight lang="sql">
DROP DATABASE IF EXISTS voipmonitor;
EXIT;
</syntaxhighlight>
 
Replace the database name <code>voipmonitor</code> if you are using a custom database name in your configuration.
 
==== Step 3: Restart a Single Sensor to Create Fresh Database ====
 
Start ONE sensor instance (preferably the server sensor in client/server mode) so it can automatically create a fresh, empty database with all required tables.
 
<syntaxhighlight lang="bash">
# Start the primary sensor (or server sensor in client/server mode)
systemctl start voipmonitor
 
# Verify the sensor is running
systemctl status voipmonitor
 
# Monitor the sensor log for database creation messages
journalctl -u voipmonitor -f
</syntaxhighlight>
 
The sensor will automatically create the voipmonitor database, all tables, functions, and routines. You should see log messages indicating the database structure is being created.
 
==== Step 4: Start All Remaining Sensors ====
 
Once the database is created, start any additional sensors (client sensors in distributed mode).
 
<syntaxhighlight lang="bash">
# Start any remaining sensors
systemctl start voipmonitor-client1
systemctl start voipmonitor-client2
# ... etc for all sensors
</syntaxhighlight>
 
==== Step 5: Verify System Functionality ====
 
Verify that the system is operating correctly.
 
* Access the VoIPmonitor web GUI and log in
* You may need to reconfigure the GUI (create users, sensors, capture rules, alerts)
* Check that the sniffer service is running and capturing:
  <syntaxhighlight lang="bash">systemctl status voipmonitor</syntaxhighlight>
* Confirm that new calls are being captured and processed
 
==== Step 6: Prevent Future Corruption with Automatic Database Cleanup ====
 
To prevent future database corruption due to excessive data accumulation, configure automatic database cleanup using the <code>cleandatabase*</code> options in your sensor configuration file (<code>/etc/voipmonitor.conf</code>).
 
Edit the configuration file:
 
<syntaxhighlight lang="bash">
sudo nano /etc/voipmonitor.conf
</syntaxhighlight>
 
Add or adjust the following parameters based on your requirements:
 
<syntaxhighlight lang="ini">
# Automatically delete CDR records older than X days
cleandatabase = 90;  # Delete CDRs older than 90 days
 
# Optionally control per-table cleanup
cleandatabasecdr = 90;      # Delete cdr table records older than 90 days
cleandatabasemsg = 30;        # Delete message table records older than 30 days
cleandatabaseregister = 7;    # Delete register table records older than 7 days
cleandatabasesip = 30;        # Delete sip table records older than 30 days
cleandatabasequeue = 180;    # Delete queue table records older than 180 days
 
# Optionally control cleanup timing
cleandatabasehour = 3;        # Run cleanup at 3:00 AM daily
cleandatabaseminute = 0;      # At 00 minutes past the hour
</syntaxhighlight>
 
For more information on data retention and cleanup options, see the [[Data_Cleaning]] page.
 
Restart the sensor after making configuration changes:
 
<syntaxhighlight lang="bash">
systemctl restart voipmonitor
</syntaxhighlight>
 
=== Solution: Using innodb_force_recovery (Recommended for Filesystem Corruption and InnoDB Assertion Failures) ===
 
If the database is corrupted after a filesystem issue and MySQL/MariaDB fails to start with InnoDB assertion errors, you can attempt to recover using the MySQL <code>innodb_force_recovery</code> parameter. This method starts MySQL in a read-only recovery mode, allowing you to back up and restore the GUI configuration.
 
'''Warning:''' This procedure will result in complete loss of CDR data. Only the GUI configuration can be preserved.
 
==== Step 1: Ensure Filesystem Issues Are Resolved ====
 
Before attempting MySQL recovery, the underlying filesystem issue that caused the corruption must be fixed. MySQL will likely fail again if the disk is still having problems.
 
===== Detailed Filesystem Check (fsck) Procedure =====
 
If a partition becomes read-only due to filesystem errors, follow these steps to repair it:
 
1. '''Identify the problematic partition:'''
<syntaxhighlight lang="bash">
# Check mount points to see which partition is affected
df -h
 
# Check for read-only mount or I/O errors in dmesg
dmesg | tail -100 | grep -i "read-only\|i/o error\|ext4-fs"
</syntaxhighlight>
 
2. '''Stop services writing to the partition:'''
Important: You must stop any services (voipmonitor, mariadb, etc.) that are writing to the affected partition before unmounting it.
<syntaxhighlight lang="bash">
# Example: Stop services that write to /home partition
systemctl stop voipmonitor mariadb
# Adjust these services based on which partition is affected
</syntaxhighlight>
 
3. '''Unmount the partition:'''
<syntaxhighlight lang="bash">
# Unmount the affected partition
umount /home
# Replace /home with your actual mount point from df -h
</syntaxhighlight>
 
4. '''Run filesystem check:'''
<syntaxhighlight lang="bash">
# Standard partition (e.g., /dev/sda1)
fsck -t ext4 -y /dev/sda1
 
# LVM partition (e.g., /dev/mapper/vg_northvoipmonitorr630-lv_home)
fsck -t ext4 -y /dev/mapper/vg_northvoipmonitorr630-lv_home
</syntaxhighlight>
 
The <code>-t ext4</code> flag specifies the filesystem type (ext3, ext4, xfs, etc.). Use <code>df -T</code> to check the filesystem type. The <code>-y</code> flag automatically answers 'yes' to all repair prompts.
 
5. '''Remount the partition:'''
<syntaxhighlight lang="bash">
mount /home
# Replace with your mount point
</syntaxhighlight>
 
6. '''Restart the services:'''
<syntaxhighlight lang="bash">
systemctl start mariadb voipmonitor
# Adjust these services based on what you stopped
</syntaxhighlight>
 
7. '''Verify the filesystem is healthy:'''
<syntaxhighlight lang="bash">
# Check mount status and free space
df -h
 
# Verify mounted read-write (not read-only)
mount | grep "on /home type"
 
# Check system logs for filesystem errors
dmesg | grep -i ext4 | tail -20
</syntaxhighlight>
 
'''Summary Checklist:'''
* Check <code>dmesg</code> or <code>/var/log/syslog</code> for I/O errors
* Ensure the partition is mounted Read-Write (not Read-Only)
* Stop services writing to the partition before unmounting
* Unmount and run <code>fsck</code> on the unmounted device
* Remount and restart services
* Verify filesystem health with <code>df -h</code>, <code>mount</code>, and <code>dmesg</code>
 
==== Step 2: Enable innodb_force_recovery Mode ====
 
Add the recovery parameter to MySQL's configuration to start it in read-only mode. This allows MySQL to start despite InnoDB corruption.
 
Edit the MySQL/MariaDB configuration file:
 
<syntaxhighlight lang="bash">
sudo nano /etc/my.cnf
# or
sudo nano /etc/mysql/my.cnf
</syntaxhighlight>
 
Add the following line to the <code>[mysqld]</code> section:
 
<syntaxhighlight lang="ini">
[mysqld]
innodb_force_recovery=6
</syntaxhighlight>
 
The <code>innodb_force_recovery=6</code> setting is the most aggressive recovery mode. It allows MySQL to start in read-only mode even with severe InnoDB corruption. See the [[#Understanding innodb_force_recovery Levels|innodb_force_recovery levels]] section below for details on each level.
 
==== Step 3: Back Up GUI Configuration ====
 
With MySQL in recovery mode, back up the GUI configuration before proceeding.
 
<syntaxhighlight lang="bash">
cd /var/www/html
php php/run.php backupGuiTables -t config -f /root/backup.zip
</syntaxhighlight>
 
This command exports all GUI settings (users, sensors, capture rules, alerts, etc.) to a backup file. For more information on GUI backup and restore, see the [[Backing_Up_GUI_Configuration]] page.
 
==== Step 4: Stop MySQL and Back Up Corrupted Data ====
 
Stop the MySQL service and create a backup of the corrupted MySQL data directory.
 
<syntaxhighlight lang="bash">
# Stop MySQL
systemctl stop mysql
# or
systemctl stop mariadb
 
# Move the corrupted data directory to a backup location
sudo mv /var/lib/mysql /var/lib/mysql-corrupted
</syntaxhighlight>
 
==== Step 5: Re-initialize MySQL Data Directory ====
 
Create a new, empty MySQL data directory.
 
<syntaxhighlight lang="bash">
# Reinitialize MySQL data directory
sudo mysql_install_db --user=mysql --datadir=/var/lib/mysql
# or on newer systems:
sudo mysqld --initialize --user=mysql
</syntaxhighlight>
 
'''Important: Finding the Temporary Root Password'''
 
After running <code>mysqld --initialize</code>, MySQL generates a temporary random password for the root user. You must retrieve this password from the MySQL error log before you can proceed.
 
<syntaxhighlight lang="bash">
# Find the temporary password in MySQL error logs
# Common log locations:
grep "temporary password" /var/log/mysql/error.log
# or for MariaDB:
grep "temporary password" /var/log/mariadb/mariadb.log
# or system journal:
journalctl -u mysql | grep "temporary password"
</syntaxhighlight>
 
The output will look like:
 
<pre>[Note] A temporary password is generated for root@localhost: <random password here></pre>
 
'''Copy this temporary password''' - you will need it to log in and set a new permanent password.


===== Setting a New Permanent Root Password =====
;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]].


With the temporary password, log in and set a new password:
;How do I enable IPv6?
:Set <code>ipv6=yes</code> in config. Existing databases require migration. See [[How_to_enable_ipv6_processing|IPv6 Guide]].


<syntaxhighlight lang="bash">
;How do I capture REGISTER messages?
# Log in to MySQL using the temporary password
:Set <code>sip-register=yes</code>. See [[Register|REGISTER Monitoring]].
mysql -u root -p
# When prompted, paste the temporary password from the log file
</syntaxhighlight>


In the MySQL console, set a new password:
;How do I capture DTMF?
:<syntaxhighlight lang="ini">dtmf2db = yes          # RFC2833 and SIP INFO
inbanddtmf = yes        # G.711 only, CPU intensive</syntaxhighlight>


<syntaxhighlight lang="sql">
== RTP & Quality Metrics ==
-- Set new root password
ALTER USER 'root'@'localhost' IDENTIFIED BY 'NewStrongPassword123!';


-- Use mysql_native_password authentication (required by VoIPmonitor)
;Why are quality metrics (MOS, jitter) missing for one call leg?
ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY 'NewStrongPassword123!';
:Usually NAT mismatch – SDP announces different IP than actual RTP source.


FLUSH PRIVILEGES;
:'''Solution:''' Configure <code>natalias</code> mapping:
EXIT;
:<syntaxhighlight lang="ini"># Map public IP to private IP
</syntaxhighlight>
natalias = 1.2.3.4 10.0.0.100</syntaxhighlight>


Replace <code>NewStrongPassword123!</code> with your own strong password.
:See [[Sniffer_configuration#NAT|NAT Configuration]] for details.


===== Creating MySQL Users for VoIPmonitor =====
;Why is RTP not correctly associated after moving SIP/RTP to different NICs?
:Enable memory blocks for multi-interface scenarios:
:<syntaxhighlight lang="ini">auto_enable_use_blocks = yes</syntaxhighlight>


After setting the root password, create the MySQL users required by VoIPmonitor. Use the <code>mysql_native_password</code> authentication plugin for compatibility with VoIPmonitor components.
;Why do recordings mix audio from different calls?
:Enable SDP verification on both sides:
:<syntaxhighlight lang="ini">rtp_check_both_sides_by_sdp = yes</syntaxhighlight>


<syntaxhighlight lang="bash">
== Licensing ==
# Log in to MySQL as root
mysql -u root -p
# Use the new password you just set
</syntaxhighlight>


Create users for the GUI and sniffer:
;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


<syntaxhighlight lang="sql>-- Create user for VoIPmonitor GUI
;What happens if I exceed my limit?
CREATE USER 'voipmonitor'@'localhost' IDENTIFIED WITH mysql_native_password BY 'YourGUIStrongPassword';
:{| class="wikitable"
 
-- Create user for VoIPmonitor sniffer (if different from GUI user)
-- Adjust hostname 'localhost' or 'sensor.host' as needed for your architecture
CREATE USER 'voipmonitor-sniffer'@'localhost' IDENTIFIED WITH mysql_native_password BY 'YourSnifferStrongPassword';
 
-- Grant all privileges on the voipmonitor database
GRANT ALL PRIVILEGES ON voipmonitor.* TO 'voipmonitor'@'localhost';
GRANT ALL PRIVILEGES ON voipmonitor.* TO 'voipmonitor-sniffer'@'localhost';
 
-- For remote sensors (client/server mode), grant access from remote hosts:
-- GRANT ALL PRIVILEGES ON voipmonitor.* TO 'voipmonitor'@'sensor1.example.com';
-- GRANT ALL PRIVILEGES ON voipmonitor.* TO 'voipmonitor'@'sensor2.example.com';
 
FLUSH PRIVILEGES;
EXIT;
</syntaxhighlight>
 
Update your VoIPmonitor configuration files (<code>/etc/voipmonitor.conf</code> for the sniffer and GUI configuration) with these MySQL credentials.
 
==== Step 6: Remove innodb_force_recovery and Start MySQL ====
 
Remove the recovery parameter from the configuration file and start MySQL normally.
 
First, edit the configuration file and remove or comment out the line:
 
<syntaxhighlight lang="ini">
[mysqld]
# innodb_force_recovery=6  <-- Comment out or remove this line
</syntaxhighlight>
 
Then start MySQL:
 
<syntaxhighlight lang="bash">
systemctl start mysql
# or
systemctl start mariadb
 
# Verify MySQL is running
systemctl status mysql
</syntaxhighlight>
 
MySQL should now be able to start with a fresh, empty database.
 
==== Step 7: Create VoIPmonitor Database ====
 
Create a new database for VoIPmonitor:
 
<syntaxhighlight lang="bash">
mysql -u root -p
</syntaxhighlight>
 
Run the following SQL commands:
 
<syntaxhighlight lang="sql">
CREATE DATABASE voipmonitor;
CREATE USER 'voipmonitor'@'localhost' IDENTIFIED BY 'your_password_here';
GRANT ALL PRIVILEGES ON voipmonitor.* TO 'voipmonitor'@'localhost';
FLUSH PRIVILEGES;
EXIT;
</syntaxhighlight>
 
==== Step 8: Restore GUI Configuration ====
 
Restore the GUI configuration from the backup file created in Step 3.
 
<syntaxhighlight lang="bash">
cd /var/www/html
php php/run.php restoreGuiTables -t config -f /root/backup.zip
</syntaxhighlight>
 
==== Step 9: Verify System Functionality ====
 
Verify that the GUI and sniffer are working correctly.
 
* Access the VoIPmonitor web GUI and log in
* Verify that sensors, users, and other settings are present
* Check that the sniffer service is running:
  <syntaxhighlight lang="bash">systemctl status voipmonitor</syntaxhighlight>
* Confirm that new calls are being captured and processed
 
'''Note:''' All historical CDR data has been lost. Only the GUI configuration was preserved. The system will begin accumulating new CDR data from this point forward.
 
==== Understanding innodb_force_recovery Levels ====
 
The <code>innodb_force_recovery</code> parameter accepts values from 1 to 6, each enabling progressively more aggressive recovery options:
 
{| class="wikitable"
|-
|-
! Value
! Duration !! Effect
! Meaning
|-
|-
| 1
| 1-2 days || Warning only, self-clearing
| (SRV_FORCE_IGNORE_CORRUPT) Runs the server even if it detects a corrupt page
|-
|-
| 2
| 3+ consecutive days || GUI blocked
| (SRV_FORCE_NO_BACKGROUND) Prevents the master thread from running; prevents crash recovery
|-
| 3
| (SRV_FORCE_NO_TRX_UNDO) Does not run transaction rollbacks after recovery
|-
| 4
| (SRV_FORCE_NO_IBUF_MERGE) Prevents insert buffer merge operations
|-
| 5
| (SRV_FORCE_NO_UNDO_LOG_SCAN) Does not look at undo logs when starting the database
|-
| 6
| (SRV_FORCE_NO_LOG_REDO) Does not apply the redo log from crash recovery (most aggressive)
|}
|}


For maximum recovery capability, use <code>innodb_force_recovery=6</code>. This mode enables all recovery strategies and allows MySQL to start even with severe InnoDB corruption.
;How do I unblock a locked GUI?
 
:In '''Settings > License''', click '''get/update license key''' – this grants a temporary increase automatically.
=== Solution: Restore from PCAP Files (Alternative) ===
 
If you have PCAP files available in the spool directory, you can restore CDR data from them instead of using <code>innodb_force_recovery</code>. This preserves your call recordings and metadata by reprocessing the packet captures.
 
'''When to use PCAP restore:'''
* PCAP files are available in the spool directory
* You want to restore historical CDR data, not just GUI configuration
* <code>innodb_force_recovery</code> method did not work
 
'''Warning:''' This procedure requires stopping the VoIPmonitor services and may take significant time depending on the amount of data to restore.
 
The following diagram illustrates the restoration workflow:
 
<kroki lang="plantuml">
@startuml
skinparam shadowing false
skinparam defaultFontName Arial
skinparam activityFontSize 12
skinparam arrowFontSize 11
 
title Database Restore from PCAP Files
 
start
 
:Stop VoIPmonitor services;
note right: voipmonitor, manager, gui
 
:Backup corrupted database;
note right: /var/lib/mysql-backup-corrupted
 
:Remove corrupted database;
note right: /var/lib/mysql/voipmonitor
 
:Start MySQL/MariaDB;
 
:Create fresh database;
note right: CREATE DATABASE voipmonitor
 
:Run sniffer in restore mode;
note right: --readpcapdir /var/spool/voipmonitor
 
while (All PCAP files processed?) is (no)
  :Process next PCAP file;
  :Generate CDR records;
endwhile (yes)
 
:Stop restore process;
 
:Start normal service;
note right: systemctl start voipmonitor
 
:Verify Web GUI access;
 
stop
 
@enduml
</kroki>
 
==== Step 1: Stop VoIPmonitor Services ====
 
Stop all VoIPmonitor services to prevent further database corruption:
 
<syntaxhighlight lang="bash">
# Stop the sniffer service
systemctl stop voipmonitor
 
# Stop sniffer manager (if running)
systemctl stop voipmonitor-manager
 
# Stop any other VoIPmonitor services
systemctl stop voipmonitor-gui
</syntaxhighlight>
 
==== Step 2: Backup the Corrupted Database ====
 
Although corrupted, create a backup of the existing database for troubleshooting purposes:
 
<syntaxhighlight lang="bash">
# Stop MySQL/MariaDB service
systemctl stop mysql
 
# Create a backup of the MySQL data directory
sudo cp -a /var/lib/mysql /var/lib/mysql-backup-corrupted
</syntaxhighlight>
 
==== Step 3: Remove the Corrupted Database ====
 
Move or remove the corrupted database files to prepare for a fresh database:
 
<syntaxhighlight lang="bash">
# Remove the corrupted VoIPmonitor database directory
sudo rm -rf /var/lib/mysql/voipmonitor
 
# Alternatively, move it instead of deleting:
sudo mv /var/lib/mysql/voipmonitor /var/lib/mysql/voipmonitor.corrupted
</syntaxhighlight>
 
==== Step 4: Start MySQL/MariaDB Service ====
 
Restart the MySQL/MariaDB service:
 
<syntaxhighlight lang="bash">
# Start MySQL/MariaDB
systemctl start mysql
 
# Verify the service is running
systemctl status mysql
</syntaxhighlight>
 
==== Step 5: Create a Fresh VoIPmonitor Database ====
 
Create a new empty database for VoIPmonitor:
 
<syntaxhighlight lang="bash">
# Log in to MySQL as root
mysql -u root -p
</syntaxhighlight>
 
Run the following SQL commands:
 
<syntaxhighlight lang="sql">
CREATE DATABASE voipmonitor;
CREATE USER 'voipmonitor'@'localhost' IDENTIFIED BY 'your_password_here';
GRANT ALL PRIVILEGES ON voipmonitor.* TO 'voipmonitor'@'localhost';
FLUSH PRIVILEGES;
EXIT;
</syntaxhighlight>
 
Replace <code>your_password_here</code> with a strong password.
 
==== Step 6: Restore CDRs from PCAP Files ====
 
Instruct the sniffer to reprocess all PCAP files from the spool directory and populate the new database:
 
<syntaxhighlight lang="bash">
# 1. Verify your spool directory path
# Check voipmonitor.conf for the spooldir setting (default: /var/spool/voipmonitor)
grep "^spooldir" /etc/voipmonitor.conf
 
# 2. Clear the sniffer's manager socket for the restore process
# This ensures clean communication with the sniffer
rm -f /tmp/vmsck
 
# 3. Start the sniffer in restore mode
# The sniffer will read all PCAP files from the spool directory
# and regenerate CDR records in the new database
voipmonitor --config-file /etc/voipmonitor.conf --readpcapdir /var/spool/voipmonitor
</syntaxhighlight>
 
'''Note:''' The <code>--readpcapdir</code> parameter instructs the sniffer to process all PCAP files in the specified directory. This may take considerable time depending on the amount of historical data.
 
==== Step 7: Monitor the Restore Process ====
 
Monitor the restore progress:
 
<syntaxhighlight lang="bash">
# Monitor sniffer output for progress
journalctl -u voipmonitor -f
 
# Alternatively, check the database for new CDR records
mysql -u root -p voipmonitor -e "SELECT COUNT(*) FROM cdr;"
</syntaxhighlight>
 
==== Step 8: Restart Normal Service ====
 
Once the restore is complete, restart the sniffer in normal operation mode:
 
<syntaxhighlight lang="bash">
# Stop the restore process (Ctrl+C if running manually)
# Then start the normal sniffer service
systemctl start voipmonitor
 
# Verify the sniffer is running and capturing
systemctl status voipmonitor
 
# Test Web GUI access
# Navigate to http://your-server/ in your browser
</syntaxhighlight>
 
=== Prevention: Database Backup Strategies ===
 
To avoid future data loss due to database corruption:
 
==== Automatic Filesystem Backup ====
 
Configure regular backups of the MySQL data directory:
 
<syntaxhighlight lang="bash">
# Example: Daily backup using cron
0 2 * * * /usr/bin/rsync -av --delete /var/lib/mysql/ /backup/mysql-$(date +\%Y\%m\%d)/
</syntaxhighlight>
 
==== MySQL Replication ====
 
Set up MySQL master-slave replication for redundancy:
* See the [[Mysql_master-slave_replication_hints]] guide for detailed instructions
* This provides a real-time backup database that can be promoted if corruption occurs
 
==== VoIPmonitor Database Replication ====
 
Use VoIPmonitor's built-in database backup mode ([[Redundant_database]]):
* This replicates CDR data to a secondary database server
* No traditional MySQL replication required
* Useful for GUI migrations and disaster recovery
 
== RRD Graph Errors After Hardware Upgrades ==
 
After a hardware upgrade or system migration, RRD (Round Robin Database) graphs in the VoIPmonitor GUI may display errors indicating that Data Sources (DS) are missing from RRD files. This occurs because RRD files are created with a specific hardware-dependent schema that may become incompatible after system changes.
 
=== Symptoms ===
 
* RRD graphs in the Web GUI show display errors instead of rendering data
* Error message: <code>ERROR: No DS called '...' in '/var/spool/voipmonitor/rrd/..."'</code>
* Example: <code>ERROR: No DS called 'SQLq-SM' in '/var/spool/voipmonitor/rrd/3db-SQL.rrd'</code>
* The error appears after hardware upgrades, CPU changes, or system migrations
* Multiple RRD files may be affected, affecting various graph types
 
=== RRD File Location ===
 
RRD files are stored in the RRD directory within the VoIPmonitor spool directory:
 
<code>/var/spool/voipmonitor/rrd/</code>
 
=== Root Cause ===
 
RRD (Round Robin Database) files contain time-series data with a schema defined at creation time. Some data sources in RRD files are hardware-specific (e.g., CPU metrics tied to specific CPU identifiers). When hardware changes, the schema information stored in the RRD files may no longer match the current system configuration, resulting in missing Data Source (DS) errors.
 
=== Solution: Delete Corrupted RRD Files ===
 
The VoIPmonitor service will automatically recreate RRD files with the correct schema if they are missing. This is a safe operation because:
 
* New RRD files will be created with the current hardware's correct schema
* Historical RRD data is typically short-term (graph display purposes only)
* CDR data and call recordings are stored separately and are not affected
 
==== Step 1: Stop the VoIPmonitor Service ====
 
Stop the voipmonitor service to prevent file access conflicts:
 
<syntaxhighlight lang="bash">
systemctl stop voipmonitor
</syntaxhighlight>
 
==== Step 2: Remove Corrupted RRD Files ====
 
Delete the affected RRD files from the RRD directory. You can remove individual problematic files or the entire RRD directory:
 
<syntaxhighlight lang="bash">
# Option 1: Remove specific corrupted RRD file (recommended)
rm /var/spool/voipmonitor/rrd/3db-SQL.rrd
 
# Option 2: Remove all RRD files if multiple errors exist
rm /var/spool/voipmonitor/rrd/*
</syntaxhighlight>
 
Replace <code>3db-SQL.rrd</code> with the actual filename from the error message.
 
==== Step 3: Start the VoIPmonitor Service ====
 
Start the voipmonitor service to recreate the RRD files:
 
<syntaxhighlight lang="bash">
systemctl start voipmonitor
</syntaxhighlight>
 
The service will automatically detect the missing RRD files and recreate them with the correct schema based on the current hardware configuration. New graph data will begin accumulating immediately.
 
==== Step 4: Verify RRD Graphs ====
 
Check the Web GUI to verify that RRD graphs are now displaying correctly:
 
* Navigate to the VoIPmonitor Web GUI
* Access dashboard or reporting pages with RRD graphs
* Verify that graphs render without errors
* Note: Historical data in the affected RRD files will be lost, but new data will start appearing
 
=== Rerunning with Different Hardware ===
 
If you need to preserve RRD data when moving to different hardware (for example, testing on a different machine), consider these options:
 
* '''Don't copy RRD files''' - Let the new system create fresh RRD files with appropriate schemas
* '''Use rrdtool dump/restore''' - For advanced users, you can modify RRD file contents using rrdtool export/import tools
* '''Accept data loss''' - RRD data is typically short-term monitoring data, not critical call records
 
=== Related Information ===
 
* RRD files are separate from CDR data (cdr table in MySQL) and PCAP recordings
* The VoIPmonitor <code>spooldir</code> location is configurable in /etc/voipmonitor.conf
* RRD files are automatically created by the sniffer service when needed
 
== Faxes Cannot Be Displayed in the GUI ==
 
If faxes cannot be displayed in the GUI and an error message appears, the issue is likely that the required package for fax conversion is not installed.
 
=== Symptoms ===
 
* Faxes are not displayed in the GUI or a generic error message appears when attempting to view fax contents
* Other GUI features work normally
* No error in browser console related to failed binary execution
 
=== Root Cause ===
 
The GUI requires the `tiff2pdf` utility to convert fax TIFF images for display in the web browser. This utility is part of the `libtiff-tools` package on Debian/Ubuntu systems or related packages on other distributions.
 
=== Solution: Install libtiff-tools Package ===
 
Install the required package using your system's package manager.
 
'''For Debian/Ubuntu:'''
 
<syntaxhighlight lang="bash">
# SSH into the GUI host
sudo apt-get update
sudo apt-get install libtiff-tools
</syntaxhighlight>
 
'''For CentOS/RHEL/AlmaLinux:'''
 
<syntaxhighlight lang="bash">
sudo yum install libtiff-tools
# or on newer systems:
sudo dnf install libtiff-tools
</syntaxhighlight>
 
=== Verifying the Fix ===
 
Verify that the `tiff2pdf` binary is accessible and executable by the web server user:
 
<syntaxhighlight lang="bash">
# Check if tiff2pdf is available system-wide
which tiff2pdf
 
# Verify the web server user can access tiff2pdf
# For Debian/Ubuntu (www-data)
runuser -u www-data -- which tiff2pdf
 
# For CentOS/RHEL (apache)
runuser -u apache -- which tiff2pdf
</syntaxhighlight>
 
If the command returns a path (e.g., `/usr/bin/tiff2pdf`), the binary is correctly installed and accessible.
 
After installing the package, reload the GUI and try to display faxes again. The ability to view faxes in the GUI should now be restored.
 
=== Related Information ===
 
* The `tiff2pdf` utility converts TIFF image files to PDF format for web browser display
* Faxes are captured by VoIPmonitor as TIFF images in T.38 fax sessions
* This conversion is required because not all browsers can display TIFF images natively
* Other GUI features (audio playback, graphs, etc.) may have different package requirements
 
== Incorrect Ownership / Permission Errors ==
 
If the GUI reports an "incorrect ownership" error even after verifying that the web server user (e.g., apache or www-data) has write permissions to the web root directory, the actual error may be hidden. The web server user needs **execute permissions** on all binary files in the `./bin` directory of the GUI installation.
 
=== Symptoms ===
 
* GUI displays "incorrect ownership" or permission errors
* Error persists even after fixing ownership/permissions on the web root directory
* Binary files in the bin directory cannot be executed by the web server
 
=== Root Cause ===
 
The GUI requires the web server user to have execute permissions on all binary files in the `bin` directory (e.g., `sox-x86_64`, `ffmpeg`, etc.). These binaries are used by the GUI for audio processing, call playback, and other features. If the binaries lack execute permissions, the GUI cannot run them.
 
=== Solution: Set Execute Permissions on Binaries ===
 
Check and fix permissions on all files in the `./bin` directory:
 
<syntaxhighlight lang="bash">
# Navigate to the GUI installation directory (default is /var/www/html)
cd /var/www/html
 
# Check the bin directory
ls -la bin/
 
# Set execute permissions on all files in the bin directory
chmod +x bin/*
 
# For specific binaries, you can set execute permissions individually
chmod +x bin/sox-x86_64
chmod +x bin/ffmpeg
</syntaxhighlight>
 
=== Verifying the Fix ===
 
Test that the binaries can be executed by the web server user:
 
<syntaxhighlight lang="bash">
# For Debian/Ubuntu (www-data)
su - www-data -s /bin/bash -c "/var/www/html/bin/sox-x86_64 --version"
# or
su - www-data -s /bin/bash -c "ls -x /var/www/html/bin/"
 
# For CentOS/RHEL (apache)
su - apache -s /bin/bash -c "/var/www/html/bin/sox-x86_64 --version"
# or
su - apache -s /bin/bash -c "ls -x /var/www/html/bin/"
</syntaxhighlight>
 
If the binaries can now be executed, the GUI should work correctly.
 
=== Troubleshooting Symlinks ===
 
Sometimes the `bin` directory contains symlinks to other locations. Check both the symlink and its target:
 
<syntaxhighlight lang="bash">
# Check if files are symlinks and their targets
ls -lah bin/
 
# If a symlink cannot be accessed, check permissions on the target
# For example, if bin/sox-x86_64 is a symlink:
ls -l bin/sox-x86_64
ls -l /path/to/real/location/sox-x86_64
 
# Fix permissions on the target if needed
chmod +x /path/to/real/location/sox-x86_64
</syntaxhighlight>
 
=== Reproducing the Error ===
 
To verify that missing execute permissions cause this error, you can temporarily remove execute permissions:
 
<syntaxhighlight lang="bash">
# Remove execute permissions (reproduces the error)
chmod -x bin/sox-x86_64
 
# Test the GUI - should show "incorrect ownership" error
 
# Restore execute permissions
chmod +x bin/sox-x86_64
</syntaxhighlight>
 
=== Common Binaries in bin/ Directory ===
 
Typical binaries that require execute permissions include:
 
* `sox-x86_64` - Audio conversion tool
* `ffmpeg` - Video/audio processing
* `soxr` - Audio resampling library
* Other utility binaries used by the GUI
 
== Permission Denied for NAS-Mounted Spool Directories ==
 
After a migration or system upgrade, the GUI may report "permission denied" errors when trying to access or play recordings stored on a NAS-mounted spool directory, even though new files are being written there successfully by the sensor.
 
=== Symptoms ===
 
* GUI displays "permission denied" when attempting to view or play recordings from a secondary spool directory
* Error occurs only for directories mounted from NAS or external storage
* The sensor can write new files to the spool directory without issues
* The issue affects multiple recordings in the NAS-mounted directory
 
=== Root Cause ===
 
The VoIPmonitor sensor service (typically running as `root` or `voipmonitor`) has write permissions to the NAS mount, but the web server GUI process (running as `www-data`, `apache`, or `nginx`) lacks read permissions. This commonly occurs after migrations where permission settings are not properly transferred to new NAS mount points.
 
Additionally, when fixing permissions, it is critical to set permissions on **ALL parent directories** in the path, not just the final spool directory. For example, if the spool directory is mounted at `/NAS/voipmonitor/spool`, both `/NAS` and `/NAS/voipmonitor` must also allow access by the web server user.
 
=== Solution: Fix Directory and Mount Permissions ===
 
==== Step 1: Identify the Web Server User ===
 
Determine which user account runs your web server process:
 
<syntaxhighlight lang="bash">
# Debian/Ubuntu
ps aux | grep -E 'apache2|nginx' | grep -v grep
 
# CentOS/RHEL
ps aux | grep -E 'httpd|nginx' | grep -v grep
</syntaxhighlight>
 
Common web server users:
* Debian/Ubuntu: `www-data`
* CentOS/RHEL: `apache`
* Nginx: `nginx`
 
==== Step 2: Fix Permissions Using ACLs (Recommended) ===
 
The recommended method is to use Access Control Lists (ACLs) via the `setfacl` command. This avoids changing ownership of files while granting specific read access to the web server user:
 
<syntaxhighlight lang="bash">
# Grant read/write/execute access to web server user
# Debian/Ubuntu
sudo setfacl -R -m u:www-data:rwx /path/to/nas/spool
 
# CentOS/RHEL
sudo setfacl -R -m u:apache:rwx /path/to/nas/spool
 
# Verify the ACL was applied
getfacl /path/to/nas/spool
</syntaxhighlight>
 
==== Step 3: Set Permissions on ALL Parent Directories ===
 
If the NAS is mounted at a path like `/NAS/voipmonitor/spool`, you must ensure the web server user can traverse all parent directories:
 
<syntaxhighlight lang="bash">
# Set ACLs on parent directories as well
sudo setfacl -m u:www-data:rx /NAS
sudo setfacl -m u:www-data:rx /NAS/voipmonitor
 
# Alternatively, use chmod for parent directories (simpler but less granular)
sudo chmod o+x /NAS
sudo chmod o+x /NAS/voipmonitor
</syntaxhighlight>
 
The web server user needs `rx` (read + execute) permissions on parent directories to traverse the path to reach the spool directory.
 
==== Step 4: Alternative: Change Directory Ownership ===
 
As an alternative to ACLs, you can change ownership of the entire spool directory to the web server user:
 
<syntaxhighlight lang="bash">
# Change ownership to web server user (Debian/Ubuntu)
sudo chown -R www-data:www-data /path/to/nas/spool
 
# Or CentOS/RHEL
sudo chown -R apache:apache /path/to/nas/spool
</syntaxhighlight>
 
'''Note:''' This method is preferred when the NAS mount is used exclusively by VoIPmonitor and you want the web server user to have full control. Use ACLs (setfacl) if you need to preserve existing ownership for backup systems or other services.
 
==== Step 5: Verify Read Access ===
 
Test that the web server user can read files in the spool directory:
 
<syntaxhighlight lang="bash">
# Switch to web server user and test read access
sudo -u www-data ls /path/to/nas/spool
# or for CentOS/RHEL
sudo -u apache ls /path/to/nas/spool
 
# Test reading an actual recording file
sudo -u www-data cat /path/to/nas/spool/YYYY-MM-DD/HH/MM/SIP/some_file.pcap.gz | head -c 100
</syntaxhighlight>
 
If the command succeeds and lists files without errors, permissions are correct.
 
==== Step 6: Verify NAS Mount Permissions ===
 
Check that the NAS mount itself has appropriate permissions in `/etc/fstab` or your mount command:
 
<syntaxhighlight lang="bash">
# View current mount options
mount | grep /path/to/nas/spool
 
# Check /etc/fstab for mount configuration
grep /path/to/nas/spool /etc/fstab
</syntaxhighlight>
 
For NFS mounts, ensure the NFS server exports the directory with appropriate permissions. For CIFS/SMB mounts, verify the mount credentials have read access.
 
=== Verifying the Fix ===
 
After fixing permissions:
1. Refresh the GUI and attempt to access recordings from the NAS-mounted spool directory
2. Verify that you can playback audio in the GUI
3. Check that new recordings are immediately accessible
 
If the issue persists, confirm that files can be read from the command line as the web server user (see Step 5 above) and verify the NAS mount is stable and accessible.
 
=== Related Information ===
 
* The `setfacl` command provides more granular permission control than `chown`
* ACLs are preserved across reboots if the filesystem supports them (ext4, xfs, etc.)
* Check the NAS mount point in `/etc/fstab` to ensure options like `nosuid` or `nodev` are not interfering
* For debugging, you can check the web server error logs: `/var/log/apache2/error.log` or `/var/log/httpd/error_log`
 
== IonCube Loader Issues ==
 
The VoIPmonitor GUI is protected with IonCube, which requires proper PHP configuration. Common issues include permission errors on temporary directories and security module interference.
 
=== Unable to create lock file / temp directory not writable ===
 
If you see errors like "Unable to create lock file" or "System temp directory check fails... not writable" from IonCube Loader, follow these troubleshooting steps:
 
==== Step 1: Update the system and restart ====
 
First, ensure your system packages are up to date:
 
<syntaxhighlight lang="bash">
# Debian/Ubuntu
sudo apt update && sudo apt upgrade -y
 
# RHEL/CentOS/AlmaLinux
sudo yum update -y
# or
sudo dnf update -y
 
# Then restart the server
sudo reboot
</syntaxhighlight>
 
==== Step 2: Check SELinux or AppArmor ====
 
Security modules like SELinux (default on RHEL/CentOS/Red Hat systems) or AppArmor (default on Ubuntu/Debian) can block IonCube from accessing temporary directories.
 
'''Check if SELinux is enabled:'''
 
<syntaxhighlight lang="bash">
# Check current status
getenforce
 
# Common values: Enforcing (active), Permissive (logging only), Disabled
 
# To temporarily disable SELinux for testing:
sudo setenforce 0
</syntaxhighlight>
 
If disabling SELinux resolves the issue, you can permanently configure it:
 
<syntaxhighlight lang="bash">
# Edit the SELinux configuration file
sudo nano /etc/selinux/config
 
# Change SELINUX= to either:
# SELINUX=permissive
# or
# SELINUX=disabled
 
# Then reboot the server
sudo reboot
</syntaxhighlight>
 
'''Check if AppArmor is enabled:'''
 
<syntaxhighlight lang="bash">
# Check AppArmor status
sudo aa-status
 
# If AppArmor is running, temporarily disable individual profiles:
sudo aa-disable /etc/apparmor.d/*php*
 
# Or disable it entirely for testing:
sudo systemctl stop apparmor
sudo systemctl disable apparmor
</syntaxhighlight>
 
==== Step 3: Check systemd PrivateTmp ====
 
Some systemd service configurations use <code>PrivateTmp=true</code>, which creates a private temporary directory for each service. This can cause issues if the private tmp directory has restrictive permissions.
 
Check if your web server is using PrivateTmp:
 
<syntaxhighlight lang="bash">
# For Apache
systemctl show httpd | grep PrivateTmp
# or
systemctl show apache2 | grep PrivateTmp
 
# For PHP-FPM
systemctl show php-fpm | grep PrivateTmp
</syntaxhighlight>
 
If PrivateTmp is enabled (value=1), disable it in the service file:
 
<syntaxhighlight lang="bash">
# Create override directory if it doesn't exist
sudo mkdir -p /etc/systemd/system/httpd.service.d
 
# Create override file
sudo nano /etc/systemd/system/httpd.service.d/privatetmp.conf
</syntaxhighlight>
 
Add the following content:
 
<syntaxhighlight lang="ini">
[Service]
PrivateTmp=false
</syntaxhighlight>
 
Then reload and restart:
 
<syntaxhighlight lang="bash">
# Reload systemd and restart the service
sudo systemctl daemon-reload
sudo systemctl restart httpd
# or
sudo systemctl restart apache2
</syntaxhighlight>
 
==== Step 4: Verify PHP Temporary Directory Configuration ====
 
Check which temporary directory PHP is using:
 
Create a PHP info file:
 
<syntaxhighlight lang="bash">
echo '<?php phpinfo(); ?>' > /var/www/html/info.php
</syntaxhighlight>
 
Visit <code>http://your-server-ip/info.php</code> in your browser and search for:
* <code>upload_tmp_dir</code>
* <code>sys_get_temp_dir</code>
* <code>session.save_path</code>
 
Ensure these directories are writable by the web server user:
 
<syntaxhighlight lang="bash">
# Check ownership
ls -ld /tmp
 
# Fix ownership if needed
sudo chown www-data:www-data /tmp  # Debian/Ubuntu
# or
sudo chown apache:apache /tmp      # CentOS/RHEL
 
# Fix permissions
sudo chmod 1777 /tmp
</syntaxhighlight>
 
'''Important:''' Clean up after troubleshooting:
 
<syntaxhighlight lang="bash">
rm /var/www/html/info.php
</syntaxhighlight>
 
==== Step 5: Check open_basedir restrictions ====
 
If the above steps don't resolve the issue, check if PHP's <code>open_basedir</code> is restricting access to the temp directory:
 
<syntaxhighlight lang="bash">
# Check open_basedir in php.ini
grep open_basedir /etc/php/*/apache2/php.ini
# or
grep open_basedir /etc/php.ini
</syntaxhighlight>
 
Ensure the temp directory is included in the list, e.g.:
 
<code>open_basedir = /var/www/html:/tmp:/var/tmp</code>
 
=== Failed check Ioncube.com PHP Loader for php cli ===
 
If the GUI installation check fails with the error "Failed check Ioncube.com PHP Loader for php cli : no ionCube extension enabled in PHP cli" even though IonCube appears to be correctly installed from the command line, the issue is often a difference between the PHP CLI environment tested by root and the PHP environment used by the web server.
 
==== Diagnosis: Exact Web Server Environment Test ====
 
To diagnose the issue, run the exact command the GUI uses as the web server user instead of root:
 
<syntaxhighlight lang="bash">
# Test IonCube extension as the web server user
sudo -u www-data PATH=$PATH:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin php -r 'echo extension_loaded("ionCube Loader")?"yes":"no";' 2>&1
 
# For CentOS/RHEL systems, replace www-data with apache
sudo -u apache PATH=$PATH:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin php -r 'echo extension_loaded("ionCube Loader")?"yes":"no";' 2>&1
</syntaxhighlight>
 
If this command returns "no" but the same command as root returns "yes", there is a configuration difference between users.
 
Note the <code>PATH=$PATH:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin</code> parameter is critical - it ensures the web server user can find the correct PHP binary.
 
==== Compare PHP Configuration Files ====
 
The CLI PHP may use a different configuration file than the web server PHP. Compare the configurations:
 
<syntaxhighlight lang="bash">
# Check which configuration file CLI PHP uses
php --ini
 
# Create phpinfo file to check web server configuration
echo '<?php phpinfo(); ?>' > /var/www/html/info.php
 
# Visit http://your-server-ip/info.php in your browser
# Look for "Loaded Configuration File" and "Additional .ini files parsed"
</syntaxhighlight>
 
==== Verify zend_extension Directive Placement ====
 
Ensure the <code>zend_extension</code> directive for IonCube Loader is in the correct PHP configuration file used by the web server, not just in the CLI configuration:
 
<syntaxhighlight lang="bash">
# Check for IonCube in web server config
grep -r "ioncube_loader" /etc/php/*/apache2/conf.d/
grep -r "ioncube_loader" /etc/php/*/fpm/conf.d/
# or for CentOS/RHEL
grep -r "ioncube_loader" /etc/php.d/
 
# Check CLI config
grep -r "ioncube_loader" /etc/php/*/cli/conf.d/
</syntaxhighlight>
 
If the web server config is missing the <code>zend_extension = ioncube_loader_lin_*.so</code> line, add it in the appropriate directory:
 
<syntaxhighlight lang="bash">
# Example for PHP 8.1 on Debian/Ubuntu (Apache)
echo 'zend_extension = ioncube_loader_lin_8.1.so' | sudo tee /etc/php/8.1/apache2/conf.d/00-ioncube.ini
 
# Example for PHP 8.1 on Debian/Ubuntu (FPM)
echo 'zend_extension = ioncube_loader_lin_8.1.so' | sudo tee /etc/php/8.1/fpm/conf.d/00-ioncube.ini
 
# Example for CentOS/RHEL
echo 'zend_extension = ioncube_loader_lin_8.1.so' | sudo tee /etc/php.d/00-ioncube.ini
</syntaxhighlight>
 
Restart the web server after making changes:
 
<syntaxhighlight lang="bash">
# Debian/Ubuntu with Apache
sudo systemctl restart apache2
 
# Debian/Ubuntu with PHP-FPM
sudo systemctl restart php8.1-fpm
 
# CentOS/RHEL with httpd
sudo systemctl restart httpd
 
# CentOS/RHEL with PHP-FPM
sudo systemctl restart php-fpm
</syntaxhighlight>
 
Clean up the test file:
 
<syntaxhighlight lang="bash">
rm /var/www/html/info.php
</syntaxhighlight>
 
== /dev/shm Filesystem Capacity Issues ==
 
After a period of operation, user sessions may start logging out and new logins become impossible. This occurs when the <code>/dev/shm</code> filesystem (tmpfs) reaches its capacity limit. The VoIPmonitor GUI stores PHP session files in <code>/dev/shm</code> by default for performance reasons.
 
=== Symptoms ===
 
* Users are frequently logged out from the GUI
* New logins fail or immediately redirect to login screen
* <code>/dev/shm</code> is reported as full (100% capacity)
* GUI behavior improves temporarily after clearing session files
 
=== Diagnosis ===
 
Check the current <code>/dev/shm</code> usage:
 
<syntaxhighlight lang="bash">
# Check /dev/shm usage and available space
df -h /dev/shm
 
# Check how much space is used by session files
du -sh /dev/shm/php_sessions/*
 
# Count session files
ls /dev/shm/php_sessions/ | wc -l
</syntaxhighlight>
 
=== Solution: Increase /dev/shm Size ===
 
==== Temporary Increase (Until Reboot) ====
 
To temporarily increase the size of <code>/dev/shm</code> without rebooting:
 
<syntaxhighlight lang="bash">
# Remount /dev/shm with increased size (example: 1GB)
mount -o remount,size=1G /dev/shm
 
# Verify the new size
df -h /dev/shm
</syntaxhighlight>
 
Adjust the size parameter (<code>size=1G</code>) based on your server's RAM and expected number of concurrent users.
 
==== Permanent Configuration (Persistent After Reboot) ====
 
To make the size increase permanent, edit the <code>/etc/fstab</code> file:
 
<syntaxhighlight lang="bash">
# Edit /etc/fstab as root
sudo nano /etc/fstab
</syntaxhighlight>
 
Find the line for <code>/dev/shm</code>. It typically looks like this:
<pre>tmpfs /dev/shm tmpfs defaults 0 0</pre>
 
Modify it to include the size parameter:
<pre>tmpfs /dev/shm tmpfs defaults,size=1G 0 0</pre>
 
Save the file and apply the changes without rebooting:
 
<syntaxhighlight lang="bash">
# Remount all filesystems from /etc/fstab
mount -a
 
# Verify the new size
df -h /dev/shm
</syntaxhighlight>
 
=== Prevention: Session Cleanup Configuration ===
 
Ensure that PHP is configured to clean up old session files from <code>/dev/shm</code>. Check the following PHP configuration settings:
 
<syntaxhighlight lang="bash">
# Check session configuration
php -i | grep -i session
 
# Look for these directives in php.ini:
# session.gc_maxlifetime - Session lifetime in seconds (default: 1440 = 24 minutes)
# session.gc_probability - Probability of garbage collection (default: 0)
# session.gc_divisor - Garbage collection divisor (default: 1000)
</syntaxhighlight>
 
For automatic cleanup, ensure <code>session.gc_probability</code> is set to a non-zero value. The probability is calculated as <code>gc_probability / gc_divisor</code>. For example:
 
* <code>session.gc_probability = 1</code> and <code>session.gc_divisor = 100</code> = 1% chance each session start
* <code>session.gc_probability = 1</code> and <code>session.gc_divisor = 10</code> = 10% chance each session start
 
=== Related Information ===
 
* <code>/dev/shm</code> is a tmpfs filesystem backed by RAM
* Increasing <code>/dev/shm</code> size consumes physical RAM - monitor total memory usage
* The GUI typically stores session files in <code>/dev/shm/php_sessions/</code> when configured for performance
* Alternative session handlers (memcached, redis) can be considered for very high-traffic deployments
 
== Alternative: MySQL General Log ==
 
If you need a persistent server-side log of all database queries (not just from the GUI), you can enable the MySQL general log:
 
<syntaxhighlight lang="sql">
-- Enable general log
SET GLOBAL general_log = 'ON';
 
-- Perform actions in the GUI...
 
-- Disable when done (important for performance)
SET GLOBAL general_log = 'OFF';
</syntaxhighlight>
 
The log file location is typically <code>/var/lib/mysql/hostname.log</code> or as defined in your MySQL configuration.
 
'''Warning:''' The general log can grow very quickly on a busy system. Always disable it after debugging.
 
== GUI Inaccessible Due to Invalid Timezone Setting ==
 
If the VoIPmonitor GUI becomes completely inaccessible and displays a PHP Fatal error after an invalid timezone is set via the GUI settings, you must manually correct the setting in the configuration file.
 
=== Symptoms ===
 
* GUI is completely inaccessible and displays a PHP Fatal error
* Error message typically indicates: <code>DateTimeZone::__construct(): Unknown or bad timezone</code>
* The error occurs after changing timezone settings via Settings > System Configuration > National
* Web server logs show PHP errors related to timezone initialization
* No GUI pages load, only error messages appear
 
=== Root Cause ===
 
The GUI stores the "Timezone" and "Sensors Timezone" settings in the configuration file <code>/var/www/html/config/configuration.php</code>. When an invalid timezone identifier is set (e.g., a typo or non-existent timezone region), PHP attempts to initialize this timezone during the bootstrapping process of the GUI initialization. This causes a fatal error that prevents the entire GUI from loading.
 
Since the GUI is inaccessible, the invalid setting cannot be reverted through the web interface. The configuration file must be edited directly from the command line.
 
=== Solution: Edit Configuration File ===
 
==== Step 1: Access the Server's Command Line ===
 
Log in to the server via SSH as root or a user with sudo privileges.
 
==== Step 2: Open the Configuration File ===
 
Open the configuration file for editing:
 
<syntaxhighlight lang="bash">
sudo nano /var/www/html/config/configuration.php
</syntaxhighlight>
 
==== Step 3: Find and Modify the Timezone Settings ===
 
Locate the lines defining <code>TIMEZONE</code> and <code>SENSORS_TIMEZONE</code>. They will look similar to:
 
<pre>
define('TIMEZONE', 'InvalidTimezone123');
define('SENSORS_TIMEZONE', 'InvalidTimezone123');
</pre>
 
Change the values to a valid timezone identifier. Use a valid timezone string from the PHP timezone database:
 
<pre>
define('TIMEZONE', 'Europe/Lisbon');
define('SENSORS_TIMEZONE', 'Europe/Lisbon');
</pre>
 
''Recommended default values:''
* <code>UTC</code> - Universal Coordinated Time (safe default)
* <code>Europe/London</code> - UK time
* <code>America/New_York</code> - US Eastern Time
* <code>Europe/Berlin</code> - Central European Time
 
See the [https://www.php.net/manual/en/timezones.php Official PHP Timezone List] for a complete list of valid timezone identifiers.
 
==== Step 4: Save and Exit ===
 
Save the file (Ctrl+O) and exit the editor (Ctrl+X).
 
==== Step 5: Clear PHP Cache (Optional) ===
 
If your system uses PHP-FPM with OPcache, you may need to clear the cache:


<syntaxhighlight lang="bash">
;I get "Invalid or corrupted hwid" error. What do I do?
# For PHP-FPM
:'''Common causes:'''
sudo systemctl restart php-fpm
:# '''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


# Or for Apache with mod_php
;I get "license file key.php is for another hwid" after hardware change?
sudo systemctl restart apache2
:In '''Settings > License''', click '''get/update license key''' then '''recheck''' to fetch new key for current HWID.
</syntaxhighlight>


==== Step 6: Verify GUI Access ===
;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".


Open your web browser and navigate to your VoIPmonitor GUI URL. The interface should now be accessible.
;How do I transfer a license to a new server?
:# 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


Once logged in, you can navigate to '''Settings > System Configuration > National''' to set the correct timezone for your region. Verify the new timezone setting works correctly.
;Can I use one license on multiple servers (test/dev)?
:Yes. Contact support to reconfigure your token for multiple HWIDs.


=== Prevention ===
;What are the available license tiers?
:10, 35, 50, 100, 150, 200, 350, 500, 750, 1000, 1250, 1500, 1750, 2000


Always use a valid timezone identifier when changing timezone settings in the GUI. The GUI timezone settings should be from the official PHP timezone database. Common pitfalls to avoid:
== Audio & PCAP Files ==


* Do not use custom or made-up timezone names
;Why does call recording stop after exactly 4 hours?
* Do not use 3-letter abbreviations (e.g., "EST", "CST") - these are ambiguous and not recommended
:Default <code>absolute_timeout = 14400</code> (4 hours). Increase or disable:
* Use the "Region/City" format (e.g., "America/New_York") for unambiguous timezone specification
:<syntaxhighlight lang="ini">absolute_timeout = 43200  # 12 hours
# absolute_timeout = 0    # Unlimited (watch memory usage)</syntaxhighlight>


=== Related Information ===
;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.


* Timezone settings are stored in <code>/var/www/html/config/configuration.php</code>
;Why is audio playback garbled?
* PHP requires valid timezone identifiers that match the IANA timezone database
:DTLS-SRTP encryption. Configure SSL Key Logger for decryption. See [[Tls|TLS/SRTP Decryption]].
* The GUI applies timezone settings during PHP initialization, so invalid values cause fatal errors
* Changing timezone settings in the GUI updates the configuration file automatically


== Concurrent Calls Stats Server-Side Error Caused by Duplicate Cron Jobs ==
;Why can't I download PCAP files?
:Files deleted by retention limits. Check:
:<syntaxhighlight lang="bash">grep maxpoolsize /etc/voipmonitor.conf
grep maxpooldays /etc/voipmonitor.conf</syntaxhighlight>
:Increase limits and restart. See [[Data_Cleaning|Data Cleaning]].


If accessing the 'Concurrent calls stats' section in the GUI results in a generic 'server-side error', this may be caused by duplicate cron job entries running the same VoIPmonitor maintenance scripts.
;Why does downloaded PCAP have fewer packets than GUI shows?
:'''Pcap deduplication before download''' is enabled. Disable in '''Settings > System Configuration > Advanced'''.


=== Symptoms ===
;How do I bulk download audio/PCAP files?
:Use GUI API. See [[download_of_pcap_files_audio_files_using_GUI's_api|Bulk Download Guide]].


* Accessing the 'Concurrent calls stats' section in the GUI results in a generic 'server-side error'
;Can VoIPmonitor detect voicemail calls?
* The error may be accompanied by database-related error messages
:'''No automatic detection''' by analyzing RTP audio. Workarounds:
* The issue occurs suddenly on pages that previously worked correctly
:* Filter by voicemail pilot number
* Other GUI sections may work normally
:* Track SIP 302 redirects (<code>save_sip_history = all</code>)
:* Capture custom SIP headers your PBX adds


=== Root Cause ===
;How do I convert WAV to OGG?
:<syntaxhighlight lang="bash">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 ./</syntaxhighlight>


Duplicate entries in the system crontab file can cause the same VoIPmonitor cron job (such as `php /var/www/html/php/run.php cron`) to run simultaneously. These concurrent executions can interfere with each other, leading to database lock conflicts, query timeouts, and server-side errors when accessing pages that depend on cron-maintained data such as concurrent calls statistics.
;How do I enable live call listening?
:Edit <code>configuration.php</code>:
:<syntaxhighlight lang="php">define('DISABLE_LIVEPLAY', false);</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 ==


=== Solution: Identify and Remove Duplicate Cron Entries ===
;How do I reset admin password?
:See [[User_Management|User Management]].


==== Step 1: Check the System Crontab ===
;How do I fix GUI after PHP/OS upgrade?
:Re-run installation. See [[Re-install_the_GUI|Re-install GUI]].


Examine the system crontab file for duplicate entries:
;How do I enable debug mode?
:Add <code>?debug=31415</code> to URL. See [[GUI_troubleshooting#GUI_Debug_Mode|GUI Debug Mode]].


<syntaxhighlight lang="bash">
;How do I fix "Unknown column" errors after database upgrade?
# View the system crontab
:Access: <code>https://your-gui/admin.php?check_tables=1</code>
sudo nano /etc/crontab
:{{Note|1=Do NOT use "Check MySQL Schema" button in Tools - that's for millisecond precision only.}}
</syntaxhighlight>


Look for lines similar to:
;Can I run multiple sensor instances on one host?
<pre>* * * * * root php /var/www/html/php/run.php cron</pre>
: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 ==


If you see two (or more) identical or similar VoIPmonitor cron job entries, this is the cause of the issue.
=== PCI Compliance ===


==== Step 2: Comment Out Duplicate Entries ===
;How do I disable audio recording?
:<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>


Comment out all but one of the duplicate cron job entries by adding a `#` at the beginning of the line:
;How do I selectively record calls?
:Use [[Capture_rules|Capture Rules]] to enable/disable recording based on IP, number, or SIP headers.


<syntaxhighlight lang="bash">
;How do I disable live listening?
# Example: Keep only one active entry
:* '''Settings > System Configuration > Advanced:''' Enable "Hide live play" and "Hide WAV play"
* * * * * root php /var/www/html/php/run.php cron
:* Edit <code>configuration.php</code>: <code>define('DISABLE_LIVEPLAY', true);</code>
:* 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 ===


# Comment out duplicates
;How do I export data to CALEA systems?
# * * * * * root php /var/www/html/php/run.php cron
:Use GUI API methods <code>getPCAP</code> and <code>getVoiceRecording</code>. See [[CALEA_compliance|CALEA Integration Guide]].
</syntaxhighlight>


==== Step 3: Apply the Changes ===
== See Also ==


Save the file and exit the editor. Reload the cron service to apply the changes:
* [[Sniffer_troubleshooting|Sniffer Troubleshooting]] - packet capture, missing CDRs
* [[GUI_troubleshooting|GUI Troubleshooting]] - HTTP 500, database issues
* [[Sniffer_configuration|Sniffer Configuration Reference]]
* [[License|Licensing Details]]
* [[Data_Cleaning|Data Cleaning and Retention]]


<syntaxhighlight lang="bash">
# Reload the cron service
sudo systemctl reload cron


# On some systems, use:
# sudo service cron reload
</syntaxhighlight>


==== Step 4: Verify the Fix ===


Navigate back to the 'Concurrent calls stats' section in the GUI and verify that the page now loads without error.


=== Prevention ===


To prevent duplicate cron job entries in the future:


* Always review the crontab file carefully before adding new entries
* Use version control or configuration management for cron file modifications
* Periodically audit the crontab file for duplicate or obsolete entries
* When manually editing cron jobs, ensure you are not creating conflicting schedules


== AI Summary for RAG ==
== AI Summary for RAG ==


'''Summary:''' This page covers GUI troubleshooting techniques including GUI inaccessibility due to invalid timezone setting (GUI becomes completely inaccessible with PHP Fatal error after setting an invalid timezone via Settings > System Configuration > National; root cause: invalid timezone identifier in configuration.php causes PHP initialization failure; solution: edit /var/www/html/config/configuration.php directly via command line, locate TIMEZONE and SENSORS_TIMEZONE defines, change to valid timezone like 'UTC' or 'Europe/Lisbon', save file, optionally restart PHP-FPM or Apache, then the GUI becomes accessible; recommended defaults: UTC, Europe/London, America/New_York, Europe/Berlin; prevention: always use valid PHP timezone identifiers from IANA database, avoid 3-letter abbreviations like EST/CST), RTP audio playback not available (RTP streams not available for download/playback, no WAV files generated, but SIP signaling and QoS metrics visible; root cause: sensor configured to save only RTP headers without audio payload; solution: set savertp=yes in /etc/voipmonitor.conf to save full RTP packets, then restart with systemctl restart voipmonitor; alternative: savertp=header for QoS metrics only without audio), debug mode activation, MySQL/MariaDB connection limit issues (GUI inaccessibility caused by max_connections being reached - symptoms include database connection errors, slow loading, or pages failing to load; diagnosis: check SHOW VARIABLES LIKE 'max_connections' and SHOW STATUS LIKE 'Threads_connected'; solution: increase max_connections value in [mysqld] section of MySQL configuration file to 500 or more based on expected load, then restart MySQL/MariaDB service), GUI upgrade issues including VM Binary (binary missing) errors (GUI upgrade fails with an error related to the VM binary/corrupt binaries; solution: execute forced CLI upgrade command "php php/run.php upgrade -f" from the GUI installation directory /var/www/html, the -f flag forces a complete update of missing or corrupt GUI binaries), tshark binary ownership problems (GUI upgrade fails with "unable to remove old files" error even after fixing web directory ownership; root cause: tshark binary owned by root instead of web server user (www-data/apache/nginx); solution: use "which tshark" to find location, check ownership with ls -l, then change ownership with "sudo chown www-data:www-data /usr/bin/tshark" or similar), web portal inaccessible after upgrade (web portal becomes inaccessible immediately after attempting an upgrade; solution: check web server status with systemctl status apache2/httpd/php-fpm and restart web server service to load new GUI files), database corruption restoration, and filesystem repair procedures. The database corruption section includes FOUR recovery methods with clear decision criteria: (1) Table-Level Repair (FIRST ATTEMPT when MySQL is running and corruption is limited to specific tables - use mysqlcheck --repair or REPAIR TABLE) by stopping voipmonitor, running mysqlcheck --repair voipmonitor, repairing specific InnoDB tables with "REPAIR TABLE cdr; REPAIR TABLE cdr_next_partition;", checking and trimming large tables with DELETE/OPTIMIZE or configuring cleandatabase options, restarting services, and optionally upgrading MySQL to latest version in branch (e.g., 5.7.33 to latest 5.7.x), (2) Drop and recreate database (SIMPLEST AND FASTEST - use when MySQL is running, corruption is widespread, data loss is acceptable, and quick service restoration is needed) by stopping sensors with systemctl stop voipmonitor, dropping the database with DROP DATABASE IF EXISTS voipmonitor, restarting one sensor to auto-recreate the database, then starting remaining sensors, (3) innodb_force_recovery parameter (ONLY for InnoDB assertion failures after filesystem corruption where MySQL fails to start - this is more complex and requires GUI backup/restore) to save GUI configuration when MySQL cannot start normally, and (4) restore from PCAP files (alternative when PCAP files are available and you want to restore historical CDR data). For the innodb_force_recovery method involving mysqld --initialize: CRITICAL steps include finding the temporary root password from MySQL error logs (grep "temporary password" in /var/log/mysql/error.log or journalctl -u mysql), connecting with mysql -u root -p using the temp password, then setting a new permanent password with ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY 'NewPassword', and creating VoIPmonitor MySQL users using mysql_native_password authentication (CREATE USER 'voipmonitor'@'localhost' IDENTIFIED WITH mysql_native_password BY 'password' followed by GRANT ALL PRIVILEGES ON voipmonitor.* TO 'voipmonitor'@'localhost'). For recovery, ALWAYS try table-level repair first (mysqlcheck) if MySQL is running, then drop/recreate if repair fails or data loss is acceptable, then innodb_force_recovery for severe InnoDB corruption. Corruption indicators in MySQL logs include "semaphore waits", "page corruption detected", "Table is marked as crashed", "InnoDB Assertion failure". Prevention: Configure cleandatabase* options (cleandatabase=90 etc.) in /etc/voipmonitor.conf to prevent future corruption from excessive data accumulation. The filesystem check section provides complete fsck procedure for repairing read-only partitions (stop services, unmount, run fsck -t ext4 -y, remount, restart services, verify). Known GUI bugs section includes dashboard edit icon grayed out issue (affects all admin users; workaround: rename dashboards from main dashboard list instead of from within dashboard view; editing metrics from Manage Dashboards page has no workaround; distinct from readonly mode issue). Other topics include permission denied for NAS-mounted spool directories (symptoms: GUI cannot access/play recordings from NAS mount while sensor can write files; diagnosis: web server user (www-data/apache) lacks read permissions that sensor (root/voipmonitor) has; solution: use setfacl -R -m u:www-data:rwx /path/to/nas/spool OR chown -R www-data:www-data /path/to/nas/spool; CRITICAL: must set permissions on ALL parent directories in path e.g., setfacl -m u:www-data:rx /NAS and /NAS/voipmonitor for path /NAS/voipmonitor/spool), browser cache issues after GUI upgrade (clear cache or hard refresh Ctrl+F5/Cmd+Shift+R), faxes not being displayed in the GUI (missing libtiff-tools package with tiff2pdf utility), incorrect ownership errors caused by missing execute permissions on GUI binaries in the ./bin directory, incorrect web root directory ownership causing "Invalid compressed data in update file" error, RRD graph errors after hardware upgrades (delete RRD files, service auto-recreates), upgrade issues (web portal inaccessible after upgrade requiring web server restart, blank screen with JavaScript errors, conflicting constants.php file, blank white screen due to SELinux), apilicensecheck.php fatal error (DO NOT reinstall entire GUI - replace only the patched file), IonCube Loader problems, /dev/shm filesystem capacity issues, and concurrent calls stats server-side error caused by duplicate cron jobs (symptoms: accessing Concurrent calls stats results in server-side error; root cause: duplicate cron job entries in /etc/crontab running php /var/www/html/php/run.php cron simultaneously causing database lock conflicts; solution: check /etc/crontab for duplicate entries, comment out duplicates by adding #, reload cron with systemctl reload cron or service cron reload).
'''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:''' GUI troubleshooting, invalid timezone, timezone error, PHP Fatal error, DateTimeZone error, Unknown or bad timezone, TIMEZONE configuration, SENSORS_TIMEZONE configuration, timezone settings invalid, timezone setting breaks GUI, fix invalid timezone, edit configuration.php, timezone identifier, IANA timezone database, PHP timezone list, valid timezone strings, UTC timezone, Europe/Lisbon timezone, timezone configuration file, timezone National settings, Settings > System Configuration > National, timezone from command line, revert timezone settings, prevent timezone errors, avoid timezone abbreviations, 3-letter timezone abbreviations, GUI inaccessible, RTP audio playback not available, audio playback not working, no audio in GUI, RTP streams not available, cannot play audio, disable audio playback, enable audio playback, savertp=yes, savertp no audio, QoS visible but no audio, cannot download RTP, no WAV files, RTP payload, audio payload, RTP headers only, debug mode, MySQL max_connections, MariaDB max_connections, connection limit, Too many connections, database connection errors, GUI inaccessible, GUI slow load, connection pool exhausted, max_connections parameter, Increase max_connections, MySQL configuration, MariaDB configuration, my.cnf, mysqld.cnf, Threads_connected, Max_used_connections, connection limit increase, MySQL connection limit, MariaDB connection limit, connect limit, connection pool, database connection pool, connection limit tuning, table_open_cache, thread_cache_size, connection monitoring, database connection monitoring, ProxySQL, connection pooling, GUI database connection, GUI cannot connect, GUI database error, GUI upgrade, GUI upgrade fails, VM Binary (binary missing), VM binary error, binary missing error, corrupt binaries, forced CLI upgrade, php php/run.php upgrade -f, forced upgrade command, upgrade -f flag, incomplete GUI upgrade, GUI binary files missing, VM binary upgrade error, unable to remove old files, tshark ownership, tshark binary, chown tshark, tshark permission unable, tshark upgrade error, GUI upgrade tshark unable to remove old files GUI upgrade tshark ownership, MySQL corruption, MariaDB corruption, database restore, PCAP restore, CDR restore, drop database, recreate database, drop and recreate, DROP DATABASE, sensor auto-create, database corruption recovery, cleandatabase, cleandatabasecdr, cleandatabasemsg, cleandatabaseregister, cleandatabasesip, cleandatabasequeue, automatic database cleanup, prevent corruption, innodb_force_recovery, InnoDB assertion failure, read-only filesystem, filesystem repair, filesystem check, fsck, partition repair, umount, remount, ext4, filesystem errors, I/O errors, disk check, partition readonly, read-only partition, GUI configuration backup, GUI configuration restore, table-level repair, mysqlcheck, mysqlcheck --repair, REPAIR TABLE, repair corrupted tables, table corruption, semaphore waits, page corruption, InnoDB page corruption, database error log, check MySQL error log, trim large tables, DELETE old data, OPTIMIZE TABLE, upgrade MySQL server, MySQL upgrade, latest MySQL version, MySQL 5.7.33, MySQL 5.7 upgrade, mysqld --initialize, mysql_initialize, MySQL temporary password, temporary password, mysqld initialize, MySQL data directory reinitialize, mysql_install_db, find temp password MySQL, grep temporary password, MySQL error log, set MySQL password, ALTER USER, change MySQL root password, mysql_native_password, native password authentication, CREATE USER IDENTIFIED WITH mysql_native_password, grant MySQL privileges, create voipmonitor MySQL user, MySQL user mysql_native_password, MySQL authentication plugin, restore password, MySQL reset, dashboard edit icon grayed out, dashboard rename, Manage Dashboards, dashboard editing, dashboard bug, edit metrics, edit icon disabled, gray icon, dashboard workaround, GUI bug, known GUI issues, Manage Dashboards page, dashboard list, rename dashboard, faxes not displaying, cannot display faxes, fax error, FAX, T.38, fax TIFF, TIFF images, PDF conversion, tiff2pdf, missing tiff2pdf, libtiff-tools, install libtiff-tools, fax package, fax conversion, fax preview, fax missing, permission denied, NAS spool, NAS mount, external storage, secondary spool directory, setfacl, ACL, Access Control Lists, chown, chmod, web server user, www-data, apache, nginx, parent directories, read permissions, traversal permissions, mount permissions, incorrect ownership, permission errors, bin directory, execute permissions, chmod +x, sox-x86_64, ffmpeg, symlinks, web root ownership, chown -R, Invalid compressed data in update file, directory ownership fix, update fails, RRD graphs, RRD error, Round Robin Database, hardware upgrade, No DS called, delete RRD files, systemctl stop voipmonitor, upgrade issues, web portal inaccessible, restart httpd, restart apache2, restart php-fpm, systemctl restart, IonCube, SELinux, AppArmor, PrivateTmp, temporary directory, permissions, open_basedir, blank screen, blank white screen, JavaScript errors, constants.php, PEAR, ReferenceError, setenforce, /dev/shm, dev shm, tmpfs, session logout, login failed, mount -o remount, fstab, session gc, session.gc_maxlifetime, session.gc_probability, php_sessions, apilicensecheck.php, findExecutableFile, patched file, license check API, Check License, undefined function, call to undefined function, PHP Fatal error, DO NOT reinstall, full reinstall not required, replace single file, backup original file, chown www-data:www-data, chmod 644, browser cache, clear cache, hard refresh, Ctrl+F5, Cmd+Shift+R, cookies, stale assets, GUI upgrade cache issues, cron jobs, duplicate cron, Concurrent calls stats, server-side error, cron entries, /etc/crontab, php run.php cron, run.php cron, cron duplicate, database lock conflicts, query timeouts, concurrent executions, cron service reload, systemctl reload cron, service cron reload, duplicate cron entries, cron job interference
'''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:'''
* GUI is completely inaccessible after setting invalid timezone - how do I fix it?
* How do I fix "Invalid or corrupted hwid" license error?
* GUI shows PHP Fatal error after changing timezone settings - what do I do?
* Why does call recording stop after 4 hours?
* How do I fix invalid timezone that makes GUI inaccessible?
* Why are quality metrics missing for one call leg?
* Why does GUI show DateTimeZone::__construct(): Unknown or bad timezone error?
* How do I run multiple GUI instances without duplicate alerts?
* How do I revert invalid timezone setting when GUI is inaccessible?
* What protocols does VoIPmonitor support (H.323? MEGACO?)?
* Where is the timezone configuration file for VoIPmonitor GUI?
* How do I fix "Unknown column" database errors after upgrade?
* How do I edit TIMEZONE and SENSORS_TIMEZONE in configuration.php?
* Can VoIPmonitor automatically detect voicemail calls?
* What are valid timezone identifiers for VoIPmonitor?
* How do I transfer my license to a new server?
* Where can I find the PHP timezone list?
* Why is audio playback garbled or distorted?
* How do I fix GUI timezone error from command line?
* How do I disable audio recording for PCI compliance?
* What timezone strings should I use for VoIPmonitor?
* Does VoIPmonitor GUI run on ARM64?
* Should I use 3-letter timezone abbreviations like EST or CST?
* How do I edit configuration.php to fix invalid timezone?
* RTP audio playback is not available in GUI - how do I fix it?
* RTP streams are not available for download or playback, even though SIP and QoS metrics are visible - what's wrong?
* Why can't I play audio in the GUI when QoS metrics are working?
* How do I enable audio playback in VoIPmonitor?
* What configuration option enables audio playback for RTP streams?
* How do I enable audio download and playback in the GUI?
* My GUI shows QoS metrics but no audio playback option - how to fix?
* How do I enable WAV file generation for playback?
* What's the difference between savertp=yes and savertp=header?
* How do I configure VoIPmonitor to save audio payload from RTP packets?
* How to enable audio playback when only SIP signaling and QoS metrics are visible?
* Cannot download RTP audio from GUI but SIP works - what do I do?
* No WAV files being generated but QoS visible - what's the solution?
* How do I fix audio playback not available in the CDR view?
* Concurrent calls stats section shows server-side error - how do I fix it?
* GUI shows server-side error when accessing Concurrent calls stats - what is the cause?
* How do I fix duplicate cron job entries causing database conflicts?
* Where do I find the system crontab file?
* How do I check /etc/crontab for duplicate VoIPmonitor cron entries?
* How do I comment out duplicate cron job entries?
* How do I reload the cron service after editing crontab?
* What is the command to reload cron (systemctl reload cron or service cron reload)?
* After migration, GUI reports permission denied for recordings in NAS spool directory - how do I fix it?
* GUI cannot access recordings from NAS-mounted spool directory but sensor can write files - what is the problem?
* How do I fix permission denied errors for GUI accessing NAS-mounted spool directories?
* Why does GUI show permission denied for recordings on NAS mount after migration?
* How do I use setfacl to fix permissions on NAS-mounted spool directories?
* Should I use setfacl or chown to fix NAS spool directory permissions?
* What is the difference between sensor user and web server user for spool directory access?
* How do I set permissions on parent directories for NAS-mounted spool paths?
* GUI cannot play recordings from NAS spool - what permissions are missing?
* How do I check if web server user can read files in NAS spool directory?
* What is the recommended method to fix NAS spool directory permissions: setfacl or chown?
* Sensor can write to NAS spool but GUI cannot read - what causes this?
* How do I verify NAS mount permissions after fixing spool directory access?
* My recordings on NAS mount are inaccessible after migration - how do I fix permissions?
* How do I use getfacl to check ACL permissions on spool directories?
* What is the correct permission setup for NAS-mounted spool directories?
* How do I grant read access to web server user for NAS spool directory?
* Should permissions be set on parent directories for NAS-mounted spool paths?
* What are the symptoms of permission denied errors for NAS-mounted spool directories?
* How do I fix GUI permission denied for NAS spool without changing ownership?
* What user accounts need read access to NAS-mounted spool directories?
* What is the difference between sensor (root/voipmonitor) and GUI (www-data/apache) user permissions?
* How do I use setfacl -R to fix permissions on NAS spool directory tree?
* When should I use ACLs vs chown for NAS spool directory permissions?
* How do I check if NAS mount has correct permissions in /etc/fstab?
* What is the impact of parent directory permissions on NAS-mounted spool access?
* How do I diagnose permission denied errors for GUI accessing NAS recordings?
* What are the troubleshooting steps for GUI unable to access NAS spool directories?
* How do I test if web server user can read files in NAS spool directory?
* What is the relationship between NFS/CIFS mount permissions and GUI access?
* After fixing NAS spool permissions, why might GUI still show permission denied?
* How do I refresh GUI after fixing NAS spool directory permissions?
* What is the root cause of GUI permission denied errors for NAS-mounted spool directories?
* How do I ensure ACLs are preserved across reboots on NAS directories?
* GUI is completely inaccessible after setting invalid timezone - how do I fix it?
* GUI shows PHP Fatal error after changing timezone settings - what do I do?
* How do I fix invalid timezone that makes GUI inaccessible?
* Why does GUI show DateTimeZone::__construct(): Unknown or bad timezone error?
* How do I revert invalid timezone setting when GUI is inaccessible?
* Where is the timezone configuration file for VoIPmonitor GUI?
* How do I edit TIMEZONE and SENSORS_TIMEZONE in configuration.php?
* What are valid timezone identifiers for VoIPmonitor?
* Where can I find the PHP timezone list?
* How do I fix GUI timezone error from command line?
* What timezone strings should I use for VoIPmonitor?
* Should I use 3-letter timezone abbreviations like EST or CST?
* How do I edit configuration.php to fix invalid timezone?
* How do I enable debug mode in the GUI to see SQL queries?
* GUI becomes inaccessible or shows database connection errors during normal operation - what is the cause?
* I'm getting "Too many connections" error in VoIPmonitor GUI - how do I fix it?
* How do I check if MySQL has reached its connection limit?
* How do I increase the MySQL max_connections parameter?
* Where do I configure max_connections in MySQL/MariaDB?
* How do I find my MySQL configuration file (my.cnf or mysqld.cnf)?
* How do I check current MySQL connection usage (Threads_connected vs max_connections)?
* What is the correct max_connections value for VoIPmonitor deployments?
* How do I restart MySQL/MariaDB after changing max_connections?
* How do I prevent GUI connection errors due to MySQL connection limits?
* How do I monitor MySQL connection usage percentage?
* What is table_open_cache and how does it relate to max_connections?
* What is thread_cache_size and how does it help with MySQL connections?
* GUI pages load slowly or fail - could it be max_connections?
* GUI upgrade fails with an error related to the VM binary - how do I fix it?
* What does "VM Binary (binary missing)" error mean during GUI upgrade?
* What is the forced CLI upgrade command for fixing VM binary errors?
* How do I run "php php/run.php upgrade -f" to fix corrupt GUI binaries?
* What does the -f flag do in the GUI upgrade command?
* GUI upgrade fails with "unable to remove old files" error - what do I do?
* GUI upgrade fails even after fixing web directory ownership - what could be the problem?
* How do I fix tshark binary ownership issues for GUI upgrade?
* What causes GUI upgrade to fail with tshark ownership errors?
* IP lookup stopped working after GUI upgrade - what do I do?
* Features stop working immediately after GUI upgrade - how do I fix it?
* How do I clear browser cache and cookies after a GUI upgrade?
* What is a hard refresh and how do I perform it (Ctrl+F5, Cmd+Shift+R)?
* Why should I clear browser cache after upgrading the GUI?
* GUI features broken after upgrade but web server restart doesn't help - what now?
* Icons or styling appear wrong after GUI upgrade - how do I fix it?
* The edit icon for dashboard renaming is grayed out - how do I fix this?
* Admin users cannot rename dashboards in Manage Dashboards page - what is the workaround?
* How do I rename a dashboard when the edit icon is grayed out?
* Dashboard edit icons are disabled for all admins - is this a bug?
* How can I rename dashboards if the edit icon within the dashboard view does not work?
* Is there a workaround for dashboard editing when the edit icons are grayed out?
* Dashboard metrics cannot be edited from Manage Dashboards page - what can I do?
* How do I bypass the grayed-out edit icon for dashboard renaming?
* Faxes cannot be displayed in the GUI - what do I do?
* What package do I need to install to view faxes in the GUI?
* How do I fix fax display errors in VoIPmonitor?
* Why are faxes not showing in my VoIPmonitor GUI?
* tiff2pdf command not found - how do I fix fax display?
* How do I verify tiff2pdf is accessible to the web server?
* What is the tiff2pdf utility used for in VoIPmonitor?
* How do I install libtiff-tools for fax display?
* GUI update fails with "Invalid compressed data in update file" - what do I do?
* The GUI reports an incorrect ownership error but web server user has permissions - what do I check?
* My MySQL database is corrupted, data loss is acceptable, and I need to restore service quickly - what do I do?
* What is the FASTEST way to restore service when MySQL database is corrupted?
* How do I quickly fix a corrupted voipmonitor database when MySQL is running?
* Should I use drop and recreate or innodb_force_recovery for database corruption?
* When should I use DROP DATABASE vs innodb_force_recovery?
* What is the simplest way to restore service when the voipmonitor database is corrupted?
* How do I use the sensor to auto-create a fresh database?
* What should I do if the MySQL/MariaDB database is corrupted but the service is running?
* How do I use mysqlcheck --repair to fix corrupted tables?
* What is the table-level repair method for database corruption?
* How do I use REPAIR TABLE to fix InnoDB corruption?
* How do I trim large tables to free disk space?
* How do I upgrade MySQL server after database corruption?
* What are the MySQL error log indicators for database corruption (semaphore waits, page corruption, InnoDB Assertion failure)?
* How do I fix a corrupted voipmonitor database when MySQL is running?
* How do I drop and recreate the voipmonitor database?
* How do I configure cleandatabase options to prevent future database corruption?
* What cleandatabase parameters should I set for automatic database cleanup?
* How do I prevent database corruption due to excessive data accumulation?
* How do I stop sensors and restart them to recreate the database?
* What is the DROP DATABASE command for corrupted voipmonitor database?
* How do I choose between drop/recreate and innodb_force_recovery for database corruption?
* How do I fix incorrect ownership errors related to the bin directory?
* What files need execute permissions in the GUI bin directory?
* How do I use chmod +x on GUI binaries like sox-x86_64?
* Why do GUI binaries need execute permissions?
* How do I verify that the web server user can execute binaries in the bin directory?
* What should I do if the MySQL/MariaDB database is corrupted after a filesystem issue?
* How do I choose between innodb_force_recovery and PCAP restore for database corruption?
* MySQL fails to start after filesystem crash with InnoDB assertion failures - which method should I use?
* How do I use innodb_force_recovery to recover MySQL from InnoDB corruption?
* What is the innodb_force_recovery parameter in MySQL?
* How do I back up and restore GUI configuration using backupGuiTables and restoreGuiTables?
* MySQL fails to start with InnoDB assertion failure - how do I fix it?
* How do I reinitialize MySQL data directory after corruption?
* How do I restore CDR data from PCAP files after database corruption?
* When should I use innodb_force_recovery versus PCAP restore for database corruption?
* RRD graphs show error "No DS called 'SQLq-SM'" after hardware upgrade - how do I fix it?
* How do I fix web portal inaccessible after GUI upgrade?
* Should I restart the web server after upgrading the GUI?
* What web server commands should I use after a GUI upgrade?
* How do I fix RRD graph errors appearing after system migration or CPU change?
* Can I delete RRD files and will voipmonitor recreate them automatically?
* Where are VoIPmonitor RRD files stored?
* How do I fix "Unable to create lock file" errors from IonCube Loader?
* How do I check if SELinux or AppArmor is blocking the GUI?
* What is systemd PrivateTmp and how does it affect the GUI?
* Why is my GUI showing a blank screen with JavaScript ReferenceError after an update?
* How do I fix ReferenceError: _AuditActivity_download_wav is not defined?
* My GUI shows a blank white screen after login without JavaScript errors - is this caused by SELinux?
* How do I disable SELinux to fix blank white screen in the GUI?
* What is the command to temporarily disable SELinux (setenforce 0)?
* How do I permanently disable SELinux in /etc/selinux/config?
* How do I check if SELinux is enabled with getenforce?
* My Check License API call fails with "Call to undefined function findExecutableFile()" - how do I fix it?
* Call to undefined function findExecutableFile in apilicensecheck.php - should I reinstall the entire GUI?
* How do I replace apilicensecheck.php with a patched file from support?
* What is the correct fix for apilicensecheck.php PHP Fatal error?
* How do I fix the apilicensecheck.php fatal error requiring a patched file?
* Users are being logged out and cannot login - /dev/shm is full - what do I do?
* How do I increase /dev/shm size?
* How do I permanently change /dev/shm size in /etc/fstab?
* How do I configure PHP to clean up old session files from /dev/shm?
* A Linux partition becomes read-only due to filesystem errors - how do I fix it?
* How do I run fsck to repair a read-only filesystem?
* What is the procedure for fixing a filesystem that is mounted read-only?
* How do I stop services before running fsck on a partition?
* How do I unmount a partition to run filesystem check?
* What fsck command do I use to repair a read-only partition?
* How do I check the filesystem type before running fsck?
* What should I do after running fsck on a corrupted filesystem?
* How do I verify the filesystem is healthy after running fsck?
* What is the correct order: fsck first or MySQL recovery first?
* How do I find the temporary root password after running mysqld --initialize?
* Where do I look for the MySQL temporary password in the logs?
* MySQL generated a temporary password with mysqld --initialize - how do I retrieve it?
* Can't find MySQL temporary password after running mysqld --initialize?
* How do I grep for temporary password in MySQL error logs?
* How do I use grep "temporary password" in MySQL error log?
* What is the command to find MySQL temporary password in /var/log/mysql/error.log?
* How do I change MySQL root password after running mysqld --initialize?
* How do I set a new permanent MySQL root password with the temporary password?
* How do I use ALTER USER to change MySQL root password?
* How do I set MySQL root password to use mysql_native_password authentication?
* How do I install VoIPmonitor MySQL users with mysql_native_password?
* How do I CREATE USER with mysql_native_password for VoIPmonitor?
* How do I grant privileges to VoIPmonitor MySQL users?
* What is the correct syntax for CREATE USER IDENTIFIED WITH mysql_native_password?
* How do I connect to MySQL with temporary password?
* MySQL temp password from mysqld --initialize - how to login?
* What auth plugin should I use for VoIPmonitor MySQL users?
* How do I reset MySQL root password if I forgot the temporary password?
* Can I use auth_socket instead of mysql_native_password for VoIPmonitor?
* What is the mysql_native_password authentication plugin?
* How do I create MySQL users for VoIPmonitor GUI and sniffer after corruption recovery?
* After mysqld --initialize, how do I create VoIPmonitor database users?

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"