GUI troubleshooting: Difference between revisions

From VoIPmonitor.org
(Add SELinux blank screen troubleshooting)
(Add spool directory ownership fix for GUI loading issues)
 
(33 intermediate revisions by the same user not shown)
Line 1: Line 1:
[[Category:GUI manual]]
= GUI Troubleshooting =


This page provides troubleshooting tips and debugging techniques for the VoIPmonitor web GUI.
This guide covers common VoIPmonitor GUI issues organized by symptom category.


== GUI Debug Mode ==
== Quick Navigation ==


The GUI debug mode allows you to see SQL queries and other debugging information directly in your browser's Developer Console.
{| class="wikitable"
! Category !! Common Issues
|-
| [[#Access Issues|Access Issues]] || HTTP 500, blank screen, single user cannot access
|-
| [[#No Data Issues|No Data Issues]] || No CDR for today, empty dashboard, missing calls
|-
| [[#Database Issues|Database Issues]] || Timeouts, corruption, connections, schema errors
|-
| [[#GUI Upgrade Issues|GUI Upgrade Issues]] || Cannot login, blank screen, VM Binary error
|-
| [[#Permission Issues|Permission Issues]] || Ownership errors, NAS access, binary execution
|-
| [[#IonCube and PHP Issues|IonCube/PHP Issues]] || Loader errors, temp directory, PHP version
|-
| [[#Other Issues|Other Issues]] || Timezone, fax, attachments, RRD graphs
|}


=== Enabling Debug Mode ===
== Access Issues ==


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:
=== HTTP 500 Error ===


<code>http://your-server/voipmon/admin.php?debug=31415</code>
'''Client-side steps (try first):'''
# Different browser or incognito mode
# Clear browser cache (Ctrl+Shift+Delete)
# Disable browser extensions
# Try from a different network


This enables the following features:
'''Server-side diagnosis:'''
* SQL queries executed by the GUI are logged to the browser's Developer Console
* Additional debugging information is displayed for dashboard panels and charts
* Performance timing and query execution details become visible


=== Finding SQL Queries for Dashboard Panels ===
<syntaxhighlight lang="bash">
# Check Apache error log
tail -100 /var/log/apache2/error.log    # Debian/Ubuntu
tail -100 /var/log/httpd/error_log      # RHEL/CentOS


To see the exact SQL query executed by a dashboard panel:
# Check PHP-FPM log
tail -100 /var/log/php-fpm/www-error.log


# Add <code>?debug=31415</code> to your GUI URL and navigate to the dashboard
# Check SELinux
# Open your browser's Developer Tools (press F12 or Ctrl+Shift+I)
getenforce
# Switch to the '''Console''' tab
# If "Enforcing", try temporarily: setenforce 0
# Interact with the dashboard (e.g., refresh, change time range, or hover over panels)
</syntaxhighlight>
# 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.
{{Tip|For detailed SQL query debugging, add <code>?debug=31415</code> to any GUI URL and check browser console (F12).}}


== GUI Upgrade Issues ==


The following are common issues that may occur during GUI upgrades and their solutions.


=== "Invalid compressed data in update file" Error ===
=== Firefox/Waterfox: Blank Page or Hang on Login ===


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.
'''Firefox/Waterfox: Blank Page or Hang on Login'''


==== Symptoms ====
If the Web GUI shows a blank page or hangs during login, but works correctly in Chrome/Edge, the cause is typically a browser extension conflict.


* GUI update aborts with error: <code>"Invalid compressed data in update file"</code>
'''Diagnosis:'''
* Manual reinstallation via tar.gz extraction works fine
* Issue occurs in Firefox/Waterfox but not Chrome/Edge
* The update process cannot write files to the web root directory
* Works when Developer Tools (F12) is open
* Persists in private mode and through SSH tunnels


==== Root Cause ====
'''Solution:'''
# In Firefox, navigate to '''about:addons'''
# Select Extensions tab and '''disable all extensions'''
# Close and reopen Firefox completely
# Attempt to log in to the GUI
# If successful, one extension is the cause. Re-enable extensions one by one (or in pairs) restarting Firefox and testing after each change to identify the specific culprit
=== Single User Cannot Access ===


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.
If one user cannot access GUI while others can:


==== Solution: Fix Web Root Directory Ownership ====
# '''Check IP whitelist''': User Management > edit user > "Access from IPs" field
# '''Check network path''': Compare user's route vs working users
# '''Capture traffic''': <syntaxhighlight lang="bash" inline>tcpdump -i eth0 host USER_IP -w /tmp/debug.pcap</syntaxhighlight>


Verify and fix the ownership of the web root directory:
=== Blank Screen After Upgrade ===


<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Check current ownership of the web root
# Check for conflicting PEAR file
ls -ld /var/www/html
ls -la /usr/share/pear/constants.php
# or
# If exists, remove it:
ls -ld /var/www/voipmonitor
rm /usr/share/pear/constants.php


# Determine your web server user:
# Check SELinux
# Debian/Ubuntu: www-data
getenforce
# CentOS/RHEL: apache
# If Enforcing, temporarily disable: setenforce 0
# Nginx: nginx


# Fix ownership - replace with your actual web server user and path
# Clear browser cache
# For Debian/Ubuntu
# Press Ctrl+F5 in browser
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>
</syntaxhighlight>


After fixing the ownership, retry the GUI update process.
== No Data Issues ==


==== Verifying the Fix ====
=== No CDR or Dashboard Data for Current Day ===


Ensure the web server user can write to the web root:
'''Step 1: Check sensor status'''


<syntaxhighlight lang="bash">
Navigate to '''Settings > Sensors''' in GUI:
# For Debian/Ubuntu
* '''Status UP''' - Sensor connected, proceed to Step 2
sudo -u www-data touch /var/www/html/test_write
* '''Status Down''' - Sensor disconnected, see [[#Sensor Down|Sensor Down]] below
sudo rm /var/www/html/test_write


# For CentOS/RHEL
'''Step 2: Generate debug log (if sensor UP)'''
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.
Navigate to '''Tools > Generate Debug Log''' and share the link with VoIPmonitor support.


=== Web Portal Inaccessible After Upgrade ===
'''Step 3: Check common causes'''
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.


==== Solution: Restart the Web Server ====
{| class="wikitable"
<syntaxhighlight lang="bash">
! Cause !! Diagnosis !! Solution
# For CentOS/RHEL/AlmaLinux with httpd
|-
sudo systemctl restart httpd
| Missing partition || <code>SHOW CREATE TABLE cdr;</code> - check partition for today's date || <code>ALTER TABLE cdr ADD PARTITION (PARTITION pYYYYMMDD VALUES LESS THAN (UNIX_TIMESTAMP('YYYY-MM-DD')));</code>
|-
| Timezone mismatch || GUI shows different time than DB || Settings > System Configuration > National > Timezone
|-
| CDR disabled || Check voipmonitor.conf || Ensure <code>cdr = yes</code>
|-
| Spool directory || Check <code>spooldir</code> path || Verify path exists and has correct permissions
|}


# For Debian/Ubuntu with Apache
{{Note|If GUI shows yesterday's data but not today's, the most common cause is a missing database partition.}}
sudo systemctl restart apache2


# For nginx with PHP-FPM
==== Sensor Down ====
sudo systemctl restart php-fpm
</syntaxhighlight>
 
After restarting the web server, try accessing the web portal again. If the portal is now accessible, the upgrade was successful and no further action is needed. If the issue persists, proceed with the troubleshooting steps below or consider performing a full GUI reinstallation.
 
=== 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:


<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Log in to the GUI host as root
# Check sensor service
# Navigate to the GUI installation directory (default is /var/www/html)
systemctl status voipmonitor
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.
 
=== 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>
# View recent logs
journalctl -u voipmonitor -n 500


This is typically caused by a conflicting PEAR file that was not removed during the upgrade. The fix is simple:
# Check database connectivity
mysql -h DB_HOST -u voipmonitor -p -e "SELECT 1"


<syntaxhighlight lang="bash">
# Restart if needed
# Remove the conflicting old PEAR constants file
systemctl restart voipmonitor
rm /usr/share/pear/constants.php
 
# Refresh your browser (Ctrl+Shift+R) to reload the GUI
</syntaxhighlight>
</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.
=== No Audio Playback ===


=== Blank Screen Due to SELinux ===
If QoS data is visible but no audio:
 
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">
<syntaxhighlight lang="bash">
# Check current SELinux status
# Check voipmonitor.conf
getenforce
grep -E "^savertp|^savegraph" /etc/voipmonitor.conf


# Common values: Enforcing (active), Permissive (logging only), Disabled
# Should show:
# savertp = yes
# savegraph = yes (optional)
</syntaxhighlight>
</syntaxhighlight>


If the output is <code>Enforcing</code>, proceed to the solution.
See [[Sniffer_configuration#RTP_and_Audio_Recording|RTP and Audio Recording]] for detailed configuration.


==== Solution: Disable SELinux
== Database Issues ==


'''Permanently disable SELinux:'''
=== GUI Queries Timeout (40-50 seconds) ===


Edit the SELinux configuration file:
'''MySQL/MariaDB tuning:'''


<syntaxhighlight lang="bash">
<syntaxhighlight lang="ini">
sudo nano /etc/selinux/config
# /etc/mysql/mysql.conf.d/mysqld.cnf or /etc/my.cnf.d/server.cnf
</syntaxhighlight>
 
Change <code>SELINUX=enforcing</code> to:


<pre>SELINUX=disabled</pre>
[mysqld]
# Set to 50-70% of available RAM
innodb_buffer_pool_size = 4G


Then reboot the server:
# Reduce disk I/O (slight durability tradeoff)
innodb_flush_log_at_trx_commit = 2


<syntaxhighlight lang="bash">
# Increase connection timeout
sudo reboot
wait_timeout = 28800
interactive_timeout = 28800
</syntaxhighlight>
</syntaxhighlight>


After the reboot, the GUI should load correctly.
'''Apache mod_fcgid timeout:'''
 
'''Temporarily disable SELinux (for testing):'''


If you want to test whether SELinux is the cause without rebooting:
If you see "server side error - check your http server error log. - connection to the web server was lost / interrupted":


<syntaxhighlight lang="bash">
<syntaxhighlight lang="apache">
# Temporarily switch SELinux to permissive mode
# In httpd.conf or apache2.conf
sudo setenforce 0
<IfModule mod_fcgid.c>
    FcgidIdleTimeout 900
    FcgidProcessLifeTime 7200
    FcgidConnectTimeout 300
    FcgidIOTimeout 900
</IfModule>
</syntaxhighlight>
</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.
=== apilicensecheck.php Fatal Error ===
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 certain GUI versions. The solution is to replace the file with a patched version.
==== 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">
<syntaxhighlight lang="bash">
# 1. Navigate to your GUI installation directory (default is /var/www/html)
systemctl restart apache2  # or httpd
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>
</syntaxhighlight>


You should receive a JSON response with the license status instead of a PHP error. Example successful responses:
=== Too Many Connections ===


<syntaxhighlight lang="json">
<syntaxhighlight lang="sql">
{"status":0,"message":"License OK."}
-- Check current connections
</syntaxhighlight>
SHOW STATUS LIKE 'Threads_connected';
SHOW VARIABLES LIKE 'max_connections';


or
-- Increase limit (temporary)
SET GLOBAL max_connections = 500;


<syntaxhighlight lang="json">
-- Permanent: add to my.cnf
{"status":1,"message":"license file key.php expired. Current date: 2024-01-15 Expiration date: 2024-01-10"}
-- max_connections = 500
</syntaxhighlight>
</syntaxhighlight>


''Note:'' The patched file must be obtained from VoIPmonitor support. This is not a self-service fix.
=== MySQL Swap Memory Warning ===


== MySQL/MariaDB Database Corruption ==
If you see swap memory warning on GUI login:


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.
* '''Less than 50 MB swap''' - Safe to ignore, minor performance impact
 
* '''Hundreds of MB or GB''' - Investigate memory usage, consider increasing RAM or reducing innodb_buffer_pool_size
=== 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">
<syntaxhighlight lang="bash">
# Check if MySQL/MariaDB is running
# Check MySQL memory usage
systemctl status mysql
ps aux | grep mysqld
# or
free -h
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>
</syntaxhighlight>


Look for error messages such as:
=== Unknown Column in Field List ===
* <code>Table is marked as crashed</code>
* <code>InnoDB: Database page corruption</code>
* <code>Incorrect key file</code>
* <code>Can't open file</code>
 
=== Solution: Restore from PCAP Files (Recommended) ===
 
If the database is corrupted, a complete restore is necessary. The recommended approach is to '''restore CDR data from the pcap files stored in the spool directory''' into a new, clean database. This preserves your call recordings and metadata while fixing the corruption issue.
 
'''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:
If GUI shows "Unknown column [table].[column] in 'field list'":


<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Stop the sniffer service
# Method 1: URL parameter (fastest)
systemctl stop voipmonitor
# Add ?check_tables=1 to GUI URL:
# http://your-gui-ip/admin.php?check_tables=1


# Stop sniffer manager (if running)
# Method 2: Command line
systemctl stop voipmonitor-manager
cd /var/www/html
php php/run.php dbcheck


# Stop any other VoIPmonitor services
# Method 3: Restart sensor (if disable_dbupgradecheck=no)
systemctl stop voipmonitor-gui
systemctl restart voipmonitor
</syntaxhighlight>
</syntaxhighlight>


==== Step 2: Backup the Corrupted Database ====
=== Database Corruption ===


Although corrupted, create a backup of the existing database for troubleshooting purposes:
'''Recovery methods (try in order):'''


'''Method 1: Table repair'''
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Stop MySQL/MariaDB service
mysqlcheck -u root -p --auto-repair voipmonitor
systemctl stop mysql
 
# Create a backup of the MySQL data directory
sudo cp -a /var/lib/mysql /var/lib/mysql-backup-corrupted
</syntaxhighlight>
</syntaxhighlight>


==== Step 3: Remove the Corrupted Database ====
'''Method 2: Drop and recreate specific table'''
<syntaxhighlight lang="sql">
-- Backup structure first
SHOW CREATE TABLE problematic_table;


Move or remove the corrupted database files to prepare for a fresh database:
-- Drop and let sensor recreate
DROP TABLE problematic_table;
-- Restart sensor: systemctl restart voipmonitor
</syntaxhighlight>


<syntaxhighlight lang="bash">
'''Method 3: InnoDB force recovery'''
# Remove the corrupted VoIPmonitor database directory
<syntaxhighlight lang="ini">
sudo rm -rf /var/lib/mysql/voipmonitor
# Add to my.cnf [mysqld] section:
 
innodb_force_recovery = 1
# Alternatively, move it instead of deleting:
# Restart MySQL, export data, remove option, reimport
sudo mv /var/lib/mysql/voipmonitor /var/lib/mysql/voipmonitor.corrupted
</syntaxhighlight>
</syntaxhighlight>


==== Step 4: Start MySQL/MariaDB Service ====
{{Warning|After using innodb_force_recovery, remove the option before resuming normal operations. The database is read-only while this option is set.}}


Restart the MySQL/MariaDB service:
'''Method 4: PCAP restore'''


If PCAPs are preserved, drop database and let sensor reindex:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Start MySQL/MariaDB
# Edit voipmonitor.conf
systemctl start mysql
reindex_all = yes  # (temporary)


# Verify the service is running
systemctl restart voipmonitor
systemctl status mysql
# Wait for reindexing to complete, then remove reindex_all
</syntaxhighlight>
</syntaxhighlight>


==== Step 5: Create a Fresh VoIPmonitor Database ====
See [[Database_troubleshooting]] for detailed recovery procedures.


Create a new empty database for VoIPmonitor:
=== MySQL 8.0 Issues ===
 
<syntaxhighlight lang="bash">
# Log in to MySQL as root
mysql -u root -p
</syntaxhighlight>
 
Run the following SQL commands:


'''SYSTEM_USER privilege error:'''
<syntaxhighlight lang="sql">
<syntaxhighlight lang="sql">
CREATE DATABASE voipmonitor;
GRANT SYSTEM_USER ON *.* TO 'voipmonitor'@'localhost';
CREATE USER 'voipmonitor'@'localhost' IDENTIFIED BY 'your_password_here';
GRANT ALL PRIVILEGES ON *.* TO 'voipmonitor'@'localhost' WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON voipmonitor.* TO 'voipmonitor'@'localhost';
FLUSH PRIVILEGES;
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">
-- Also set:
# 1. Verify your spool directory path
SET GLOBAL log_bin_trust_function_creators = 1;
# 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>
</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.
'''MySQL 8.0.42 crashes:'''
 
==== Step 7: Monitor the Restore Process ====


Monitor the restore progress:
{{Warning|MySQL 8.0.42 has known bugs causing VoIPmonitor crashes. Upgrade to 8.0.43 or later.}}


<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Monitor sniffer output for progress
mysql --version
journalctl -u voipmonitor -f
# If 8.0.42:
 
sudo apt install --only-upgrade mysql-server-8.0  # Debian/Ubuntu
# Alternatively, check the database for new CDR records
sudo dnf update mysql-server                      # RHEL
mysql -u root -p voipmonitor -e "SELECT COUNT(*) FROM cdr;"
</syntaxhighlight>
</syntaxhighlight>


==== Step 8: Restart Normal Service ====
=== Managed Database: Primary Key Error ===


Once the restore is complete, restart the sniffer in normal operation mode:
For DigitalOcean, AWS RDS, Google Cloud SQL:


<syntaxhighlight lang="bash">
<syntaxhighlight lang="sql">
# Stop the restore process (Ctrl+C if running manually)
-- Disable in managed DB console or parameter group:
# Then start the normal sniffer service
sql_require_primary_key = OFF
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>
</syntaxhighlight>


=== Prevention: Database Backup Strategies ===
== GUI Upgrade Issues ==


To avoid future data loss due to database corruption:
=== Cannot Login After Upgrade ===


==== Automatic Filesystem Backup ====
'''Reset password via database:'''
 
<syntaxhighlight lang="sql">
Configure regular backups of the MySQL data directory:
UPDATE users SET password = MD5('newpassword') WHERE username = 'admin';
 
<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>
</syntaxhighlight>


==== MySQL Replication ====
'''Redis session issue (login loop):'''
 
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">
<syntaxhighlight lang="bash">
systemctl stop voipmonitor
redis-cli FLUSHALL
systemctl restart php-fpm
</syntaxhighlight>
</syntaxhighlight>


==== Step 2: Remove Corrupted RRD Files ====
=== VM Binary Error ===
 
Delete the affected RRD files from the RRD directory. You can remove individual problematic files or the entire RRD directory:


<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Option 1: Remove specific corrupted RRD file (recommended)
cd /var/www/html
rm /var/spool/voipmonitor/rrd/3db-SQL.rrd
php php/run.php upgrade -f
 
# Option 2: Remove all RRD files if multiple errors exist
rm /var/spool/voipmonitor/rrd/*
</syntaxhighlight>
</syntaxhighlight>


Replace <code>3db-SQL.rrd</code> with the actual filename from the error message.
=== Invalid Compressed Data ===
 
==== Step 3: Start the VoIPmonitor Service ====
 
Start the voipmonitor service to recreate the RRD files:


Usually caused by incorrect web root ownership:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
systemctl start voipmonitor
chown -R www-data:www-data /var/www/html  # Debian/Ubuntu
chown -R apache:apache /var/www/html      # RHEL/CentOS
</syntaxhighlight>
</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.
=== Unable to Remove Old Files ===
 
==== 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
 
== 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">
<syntaxhighlight lang="bash">
# Navigate to the GUI installation directory (default is /var/www/html)
# Fix tshark ownership
cd /var/www/html
chown www-data:www-data /var/www/html/bin/tshark*


# Check the bin directory
# Retry upgrade from GUI
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>
</syntaxhighlight>


=== Verifying the Fix ===
=== Upgrade Not Visible ===
 
Test that the binaries can be executed by the web server user:


Check internet connectivity from GUI server:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# For Debian/Ubuntu (www-data)
curl -I https://www.voipmonitor.org
su - www-data -s /bin/bash -c "/var/www/html/bin/sox-x86_64 --version"
ping www.voipmonitor.org
# 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>
</syntaxhighlight>


If the binaries can now be executed, the GUI should work correctly.
== Permission Issues ==
 
=== Troubleshooting Symlinks ===


Sometimes the `bin` directory contains symlinks to other locations. Check both the symlink and its target:
=== Incorrect Ownership Error ===


Often caused by missing execute permissions on binaries:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Check if files are symlinks and their targets
# Fix bin directory
ls -lah bin/
chmod +x /var/www/html/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
# Verify
chmod +x /path/to/real/location/sox-x86_64
ls -la /var/www/html/bin/
</syntaxhighlight>
</syntaxhighlight>


=== Reproducing the Error ===
=== NAS Spool Permission Denied ===
 
To verify that missing execute permissions cause this error, you can temporarily remove execute permissions:


<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Remove execute permissions (reproduces the error)
# Use ACLs (recommended)
chmod -x bin/sox-x86_64
setfacl -R -m u:www-data:rwx /path/to/nas/spool


# Test the GUI - should show "incorrect ownership" error
# CRITICAL: Set on ALL parent directories too
setfacl -m u:www-data:rx /NAS
setfacl -m u:www-data:rx /NAS/voipmonitor


# Restore execute permissions
# Verify
chmod +x bin/sox-x86_64
sudo -u www-data ls /path/to/nas/spool
</syntaxhighlight>
</syntaxhighlight>


=== Common Binaries in bin/ Directory ===
=== SELinux Blocking mscgen (SIP Call Flow Diagrams) ===
 
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
 
== 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:
If SIP call flow diagram shows "convert msc to svg (mscgen): unknown error":


<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Debian/Ubuntu
# Check SELinux denials
sudo apt update && sudo apt upgrade -y
ausearch -m avc -ts recent | grep mscgen


# RHEL/CentOS/AlmaLinux
# Create policy module
sudo yum update -y
grep mscgen /var/log/audit/audit.log | audit2allow -M mscgen_local
# or
semodule -i mscgen_local.pp
sudo dnf update -y
 
# Then restart the server
sudo reboot
</syntaxhighlight>
</syntaxhighlight>


==== Step 2: Check SELinux or AppArmor ====
== IonCube and PHP Issues ==


Security modules like SELinux (default on RHEL/CentOS/Red Hat systems) or AppArmor (default on Ubuntu/Debian) can block IonCube from accessing temporary directories.
=== Temp Directory Not Writable ===


'''Check if SELinux is enabled:'''
<syntaxhighlight lang="bash">
# Check and fix /tmp permissions
ls -ld /tmp
chmod 1777 /tmp


<syntaxhighlight lang="bash">
# Check SELinux
# Check current status
getenforce
getenforce
# If Enforcing, try: setenforce 0


# Common values: Enforcing (active), Permissive (logging only), Disabled
# Check systemd PrivateTmp
 
systemctl show httpd | grep PrivateTmp
# To temporarily disable SELinux for testing:
# If true, create override:
sudo setenforce 0
# /etc/systemd/system/httpd.service.d/privatetmp.conf
</syntaxhighlight>
# [Service]
 
# PrivateTmp=false
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>
</syntaxhighlight>


'''Check if AppArmor is enabled:'''
=== PHP CLI vs Web Server Mismatch ===


<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Check AppArmor status
# Test as web server user
sudo aa-status
sudo -u www-data php -r 'echo extension_loaded("ionCube Loader")?"yes":"no";'
 
# If AppArmor is running, temporarily disable individual profiles:
sudo aa-disable /etc/apparmor.d/*php*


# Or disable it entirely for testing:
# Compare configs
sudo systemctl stop apparmor
php --ini                    # CLI config
sudo systemctl disable apparmor
# Create phpinfo: echo '<?php phpinfo();' > /var/www/html/info.php
# Check "Loaded Configuration File" in browser
# Remove after: rm /var/www/html/info.php
</syntaxhighlight>
</syntaxhighlight>


==== Step 3: Check systemd PrivateTmp ====
=== License Activation: Server Side Error - Forbidden ===
 
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
This indicates ionCube PHP version incompatibility:
systemctl show php-fpm | grep PrivateTmp
</syntaxhighlight>


If PrivateTmp is enabled (value=1), disable it in the service file:
{| class="wikitable"
! GUI Version !! PHP Version
|-
| v26.37+ || PHP 8.3 supported
|-
| Older || PHP 8.2 or earlier required
|}


<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Create override directory if it doesn't exist
# Check Apache error log
sudo mkdir -p /etc/systemd/system/httpd.service.d
tail -50 /var/log/apache2/error.log | grep -i ioncube


# Create override file
# Solution: Either upgrade GUI to v26.37+ or downgrade PHP to 8.2
sudo nano /etc/systemd/system/httpd.service.d/privatetmp.conf
</syntaxhighlight>
</syntaxhighlight>


Add the following content:
== Other Issues ==
 
<syntaxhighlight lang="ini">
[Service]
PrivateTmp=false
</syntaxhighlight>


Then reload and restart:
=== Invalid Timezone (GUI Inaccessible) ===


<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Reload systemd and restart the service
# Edit directly
sudo systemctl daemon-reload
nano /var/www/html/config/configuration.php
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:
# Find and fix:
define('TIMEZONE', 'UTC');  # Use valid timezone
define('SENSORS_TIMEZONE', 'UTC');


<syntaxhighlight lang="bash">
systemctl restart php-fpm
echo '<?php phpinfo(); ?>' > /var/www/html/info.php
</syntaxhighlight>
</syntaxhighlight>


Visit <code>http://your-server-ip/info.php</code> in your browser and search for:
Valid timezones: <code>UTC</code>, <code>Europe/London</code>, <code>America/New_York</code>, <code>Europe/Berlin</code>, etc.
* <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:
=== Faxes Not Displayed ===


<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Check ownership
# Install libtiff-tools
ls -ld /tmp
apt-get install libtiff-tools    # Debian/Ubuntu
 
yum install libtiff-tools        # RHEL/CentOS
# Fix ownership if needed
sudo chown www-data:www-data /tmp  # Debian/Ubuntu
# or
sudo chown apache:apache /tmp      # CentOS/RHEL


# Fix permissions
# Verify
sudo chmod 1777 /tmp
which tiff2pdf
</syntaxhighlight>
</syntaxhighlight>


'''Important:''' Clean up after troubleshooting:
=== File Attachment Blocked ===


Files like .xlsx, .docx are blocked for security. Compress to .zip or .gz:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
rm /var/www/html/info.php
zip archive.zip your_file.xlsx
</syntaxhighlight>
</syntaxhighlight>


==== Step 5: Check open_basedir restrictions ====
=== RRD Graph Errors After Hardware Change ===


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">
# Delete corrupted RRD files
rm -rf /var/spool/voipmonitor/rrd/*


<syntaxhighlight lang="bash">
# Sensor will recreate them
# Check open_basedir in php.ini
systemctl restart voipmonitor
grep open_basedir /etc/php/*/apache2/php.ini
# or
grep open_basedir /etc/php.ini
</syntaxhighlight>
</syntaxhighlight>


Ensure the temp directory is included in the list, e.g.:
=== /dev/shm Full (Session Logout Issues) ===
 
<code>open_basedir = /var/www/html:/tmp:/var/tmp</code>
 
== /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">
<syntaxhighlight lang="bash">
# Check /dev/shm usage and available space
# Check usage
df -h /dev/shm
df -h /dev/shm


# Check how much space is used by session files
# Temporary increase
du -sh /dev/shm/php_sessions/*
mount -o remount,size=1G /dev/shm


# Count session files
# Permanent: edit /etc/fstab
ls /dev/shm/php_sessions/ | wc -l
# tmpfs /dev/shm tmpfs defaults,size=1G 0 0
</syntaxhighlight>
</syntaxhighlight>


=== Solution: Increase /dev/shm Size ===
=== Concurrent Calls Stats Error ===
 
==== Temporary Increase (Until Reboot) ====
 
To temporarily increase the size of <code>/dev/shm</code> without rebooting:


Usually caused by duplicate cron entries:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Remount /dev/shm with increased size (example: 1GB)
# Check for duplicates
mount -o remount,size=1G /dev/shm
grep "voipmonitor\|run.php" /etc/crontab


# Verify the new size
# Comment out duplicates, keep only one
df -h /dev/shm
</syntaxhighlight>
</syntaxhighlight>


Adjust the size parameter (<code>size=1G</code>) based on your server's RAM and expected number of concurrent users.
=== TShark CVE Security Updates ===


==== Permanent Configuration (Persistent After Reboot) ====
The bundled tshark may have known CVEs. To update:


To make the size increase permanent, edit the <code>/etc/fstab</code> file:
<syntaxhighlight lang="bash">
cd /var/www/html/bin


<syntaxhighlight lang="bash">
# Download updated binary from Wireshark
# Edit /etc/fstab as root
wget https://www.wireshark.org/download/automated/linux64/tshark
sudo nano /etc/fstab
chmod +x tshark
chown www-data:www-data tshark
</syntaxhighlight>
</syntaxhighlight>


Find the line for <code>/dev/shm</code>. It typically looks like this:
=== Dashboard Edit Icon Grayed Out ===
<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
User lacks edit permission. Grant via '''User Management''' > edit user > enable "Edit Dashboard" permission.
df -h /dev/shm
</syntaxhighlight>


=== Prevention: Session Cleanup Configuration ===
== GUI Not Loading (Spool Directory Ownership) ==


Ensure that PHP is configured to clean up old session files from <code>/dev/shm</code>. Check the following PHP configuration settings:
If the GUI is not loading or shows generic error messages, the cause may be incorrect ownership of the spool directory by the web server user.


<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Check session configuration
# Fix spool directory ownership
php -i | grep -i session
chown -R www-data:www-data /var/spool/voipmonitor    # Debian/Ubuntu
 
# OR
# Look for these directives in php.ini:
chown -R apache:apache /var/spool/voipmonitor        # RHEL/CentOS
# 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>
</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:
{{Note|The spool directory path is defined by the <code>spooldir</code> parameter in <code>/etc/voipmonitor.conf</code>. Use the correct path for your configuration.}}
 
* <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.


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


'''Summary:''' This page covers GUI troubleshooting techniques including debug mode activation, MySQL/MariaDB database corruption restoration from PCAP files, 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 (No DS errors in RRD files), 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 requiring patched file), IonCube Loader problems with temp directory permissions, SELinux, AppArmor, and systemd PrivateTmp, and /dev/shm filesystem capacity issues causing session logout problems.
'''Summary:''' VoIPmonitor GUI troubleshooting guide covering: (1) HTTP 500 errors - try client-side steps first (different browser, incognito, clear cache), then check Apache/PHP error logs and SELinux; (2) No CDR for current day - check sensor status in Settings > Sensors, generate debug log if UP, check partitions/timezone/cdr config if Down; (3) GUI debug mode - add ?debug=31415 to URL; (4) Database timeouts - tune innodb_buffer_pool_size (50-70% RAM), increase mod_fcgid timeouts; (5) Database corruption - use mysqlcheck, drop/recreate tables, or innodb_force_recovery; (6) GUI upgrade issues - reset password via database, fix ownership, run php php/run.php upgrade -f; (7) Permission errors - chmod +x bin/*, use setfacl for NAS; (8) IonCube errors - check SELinux, PHP version compatibility (GUI v26.37+ for PHP 8.3); (9) Schema errors - use ?check_tables=1 URL parameter.


'''Keywords:''' GUI troubleshooting, debug mode, MySQL corruption, MariaDB corruption, database restore, PCAP restore, CDR restore, 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, web server user, apache, www-data, nginx, 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
'''Keywords:''' HTTP 500, no CDR, sensor status, debug mode, ?debug=31415, innodb_buffer_pool_size, MySQL tuning, database corruption, mysqlcheck, innodb_force_recovery, GUI upgrade, password reset, IonCube, SELinux, PHP 8.3, ?check_tables=1, NAS permissions, setfacl, mod_fcgid timeout, FcgidIOTimeout, mscgen, SIP call flow, tshark CVE, MySQL 8.0.42, SYSTEM_USER privilege, /dev/shm, timezone error, libtiff-tools, file attachment blocked


'''Key Questions:'''
'''Key Questions:'''
* How do I enable debug mode in the GUI to see SQL queries?
* HTTP 500 error on GUI - what to try first?
* GUI update fails with "Invalid compressed data in update file" - what do I do?
* No CDR or dashboard data for current day - how to diagnose?
* The GUI reports an incorrect ownership error but web server user has permissions - what do I check?
* How to enable GUI debug mode?
* How do I fix incorrect ownership errors related to the bin directory?
* GUI queries timeout - how to tune MySQL?
* What files need execute permissions in the GUI bin directory?
* Database corrupted - which recovery method to use?
* How do I use chmod +x on GUI binaries like sox-x86_64?
* Cannot login after GUI upgrade - how to reset password?
* Why do GUI binaries need execute permissions?
* Permission errors with NAS spool - how to fix?
* How do I verify that the web server user can execute binaries in the bin directory?
* IonCube temp directory errors - what causes them?
* What should I do if the MySQL/MariaDB database is corrupted?
* GUI shows "Unknown column in field list" - how to fix?
* How do I restore CDR data from PCAP files after database corruption?
* SIP call flow diagram shows error - how to fix SELinux blocking?
* RRD graphs show error "No DS called 'SQLq-SM'" after hardware upgrade - how do I fix it?
* MySQL 8.0.42 causing crashes - what to do?
* How do I fix web portal inaccessible after GUI upgrade?
* License activation fails with Forbidden error - what causes it?
* 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?
* 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?

Latest revision as of 01:37, 10 January 2026

GUI Troubleshooting

This guide covers common VoIPmonitor GUI issues organized by symptom category.

Quick Navigation

Category Common Issues
Access Issues HTTP 500, blank screen, single user cannot access
No Data Issues No CDR for today, empty dashboard, missing calls
Database Issues Timeouts, corruption, connections, schema errors
GUI Upgrade Issues Cannot login, blank screen, VM Binary error
Permission Issues Ownership errors, NAS access, binary execution
IonCube/PHP Issues Loader errors, temp directory, PHP version
Other Issues Timezone, fax, attachments, RRD graphs

Access Issues

HTTP 500 Error

Client-side steps (try first):

  1. Different browser or incognito mode
  2. Clear browser cache (Ctrl+Shift+Delete)
  3. Disable browser extensions
  4. Try from a different network

Server-side diagnosis: 

# Check Apache error log
tail -100 /var/log/apache2/error.log    # Debian/Ubuntu
tail -100 /var/log/httpd/error_log      # RHEL/CentOS

# Check PHP-FPM log
tail -100 /var/log/php-fpm/www-error.log

# Check SELinux
getenforce
# If "Enforcing", try temporarily: setenforce 0

💡 Tip:


Firefox/Waterfox: Blank Page or Hang on Login

Firefox/Waterfox: Blank Page or Hang on Login

If the Web GUI shows a blank page or hangs during login, but works correctly in Chrome/Edge, the cause is typically a browser extension conflict.

Diagnosis:

  • Issue occurs in Firefox/Waterfox but not Chrome/Edge
  • Works when Developer Tools (F12) is open
  • Persists in private mode and through SSH tunnels

Solution:

  1. In Firefox, navigate to about:addons
  2. Select Extensions tab and disable all extensions
  3. Close and reopen Firefox completely
  4. Attempt to log in to the GUI
  5. If successful, one extension is the cause. Re-enable extensions one by one (or in pairs) restarting Firefox and testing after each change to identify the specific culprit

Single User Cannot Access

If one user cannot access GUI while others can:

  1. Check IP whitelist: User Management > edit user > "Access from IPs" field
  2. Check network path: Compare user's route vs working users
  3. Capture traffic: tcpdump -i eth0 host USER_IP -w /tmp/debug.pcap

Blank Screen After Upgrade

# Check for conflicting PEAR file
ls -la /usr/share/pear/constants.php
# If exists, remove it:
rm /usr/share/pear/constants.php

# Check SELinux
getenforce
# If Enforcing, temporarily disable: setenforce 0

# Clear browser cache
# Press Ctrl+F5 in browser

No Data Issues

No CDR or Dashboard Data for Current Day

Step 1: Check sensor status

Navigate to Settings > Sensors in GUI:

  • Status UP - Sensor connected, proceed to Step 2
  • Status Down - Sensor disconnected, see Sensor Down below

Step 2: Generate debug log (if sensor UP)

Navigate to Tools > Generate Debug Log and share the link with VoIPmonitor support.

Step 3: Check common causes

Cause Diagnosis Solution
Missing partition SHOW CREATE TABLE cdr; - check partition for today's date ALTER TABLE cdr ADD PARTITION (PARTITION pYYYYMMDD VALUES LESS THAN (UNIX_TIMESTAMP('YYYY-MM-DD')));
Timezone mismatch GUI shows different time than DB Settings > System Configuration > National > Timezone
CDR disabled Check voipmonitor.conf Ensure cdr = yes
Spool directory Check spooldir path Verify path exists and has correct permissions

ℹ️ Note: If GUI shows yesterday's data but not today's, the most common cause is a missing database partition.

Sensor Down

# Check sensor service
systemctl status voipmonitor

# View recent logs
journalctl -u voipmonitor -n 500

# Check database connectivity
mysql -h DB_HOST -u voipmonitor -p -e "SELECT 1"

# Restart if needed
systemctl restart voipmonitor

No Audio Playback

If QoS data is visible but no audio: 

# Check voipmonitor.conf
grep -E "^savertp|^savegraph" /etc/voipmonitor.conf

# Should show:
# savertp = yes
# savegraph = yes (optional)

See RTP and Audio Recording for detailed configuration.

Database Issues

GUI Queries Timeout (40-50 seconds)

MySQL/MariaDB tuning: 

# /etc/mysql/mysql.conf.d/mysqld.cnf or /etc/my.cnf.d/server.cnf

[mysqld]
# Set to 50-70% of available RAM
innodb_buffer_pool_size = 4G

# Reduce disk I/O (slight durability tradeoff)
innodb_flush_log_at_trx_commit = 2

# Increase connection timeout
wait_timeout = 28800
interactive_timeout = 28800

Apache mod_fcgid timeout:

If you see "server side error - check your http server error log. - connection to the web server was lost / interrupted": 

# In httpd.conf or apache2.conf
<IfModule mod_fcgid.c>
    FcgidIdleTimeout 900
    FcgidProcessLifeTime 7200
    FcgidConnectTimeout 300
    FcgidIOTimeout 900
</IfModule>

systemctl restart apache2  # or httpd

Too Many Connections

-- Check current connections
SHOW STATUS LIKE 'Threads_connected';
SHOW VARIABLES LIKE 'max_connections';

-- Increase limit (temporary)
SET GLOBAL max_connections = 500;

-- Permanent: add to my.cnf
-- max_connections = 500

MySQL Swap Memory Warning

If you see swap memory warning on GUI login:

  • Less than 50 MB swap - Safe to ignore, minor performance impact
  • Hundreds of MB or GB - Investigate memory usage, consider increasing RAM or reducing innodb_buffer_pool_size
# Check MySQL memory usage
ps aux | grep mysqld
free -h

Unknown Column in Field List

If GUI shows "Unknown column [table].[column] in 'field list'": 

# Method 1: URL parameter (fastest)
# Add ?check_tables=1 to GUI URL:
# http://your-gui-ip/admin.php?check_tables=1

# Method 2: Command line
cd /var/www/html
php php/run.php dbcheck

# Method 3: Restart sensor (if disable_dbupgradecheck=no)
systemctl restart voipmonitor

Database Corruption

Recovery methods (try in order):

Method 1: Table repair 

mysqlcheck -u root -p --auto-repair voipmonitor

Method 2: Drop and recreate specific table 

-- Backup structure first
SHOW CREATE TABLE problematic_table;

-- Drop and let sensor recreate
DROP TABLE problematic_table;
-- Restart sensor: systemctl restart voipmonitor

Method 3: InnoDB force recovery 

# Add to my.cnf [mysqld] section:
innodb_force_recovery = 1
# Restart MySQL, export data, remove option, reimport

⚠️ Warning: After using innodb_force_recovery, remove the option before resuming normal operations. The database is read-only while this option is set.

Method 4: PCAP restore

If PCAPs are preserved, drop database and let sensor reindex: 

# Edit voipmonitor.conf
reindex_all = yes  # (temporary)

systemctl restart voipmonitor
# Wait for reindexing to complete, then remove reindex_all

See Database_troubleshooting for detailed recovery procedures.

MySQL 8.0 Issues

SYSTEM_USER privilege error: 

GRANT SYSTEM_USER ON *.* TO 'voipmonitor'@'localhost';
GRANT ALL PRIVILEGES ON *.* TO 'voipmonitor'@'localhost' WITH GRANT OPTION;
FLUSH PRIVILEGES;

-- Also set:
SET GLOBAL log_bin_trust_function_creators = 1;

MySQL 8.0.42 crashes:

⚠️ Warning: MySQL 8.0.42 has known bugs causing VoIPmonitor crashes. Upgrade to 8.0.43 or later. 

mysql --version
# If 8.0.42:
sudo apt install --only-upgrade mysql-server-8.0  # Debian/Ubuntu
sudo dnf update mysql-server                       # RHEL

Managed Database: Primary Key Error

For DigitalOcean, AWS RDS, Google Cloud SQL: 

-- Disable in managed DB console or parameter group:
sql_require_primary_key = OFF

GUI Upgrade Issues

Cannot Login After Upgrade

Reset password via database: 

UPDATE users SET password = MD5('newpassword') WHERE username = 'admin';

Redis session issue (login loop): 

redis-cli FLUSHALL
systemctl restart php-fpm

VM Binary Error

cd /var/www/html
php php/run.php upgrade -f

Invalid Compressed Data

Usually caused by incorrect web root ownership: 

chown -R www-data:www-data /var/www/html  # Debian/Ubuntu
chown -R apache:apache /var/www/html       # RHEL/CentOS

Unable to Remove Old Files

# Fix tshark ownership
chown www-data:www-data /var/www/html/bin/tshark*

# Retry upgrade from GUI

Upgrade Not Visible

Check internet connectivity from GUI server: 

curl -I https://www.voipmonitor.org
ping www.voipmonitor.org

Permission Issues

Incorrect Ownership Error

Often caused by missing execute permissions on binaries: 

# Fix bin directory
chmod +x /var/www/html/bin/*

# Verify
ls -la /var/www/html/bin/

NAS Spool Permission Denied

# Use ACLs (recommended)
setfacl -R -m u:www-data:rwx /path/to/nas/spool

# CRITICAL: Set on ALL parent directories too
setfacl -m u:www-data:rx /NAS
setfacl -m u:www-data:rx /NAS/voipmonitor

# Verify
sudo -u www-data ls /path/to/nas/spool

SELinux Blocking mscgen (SIP Call Flow Diagrams)

If SIP call flow diagram shows "convert msc to svg (mscgen): unknown error": 

# Check SELinux denials
ausearch -m avc -ts recent | grep mscgen

# Create policy module
grep mscgen /var/log/audit/audit.log | audit2allow -M mscgen_local
semodule -i mscgen_local.pp

IonCube and PHP Issues

Temp Directory Not Writable

# Check and fix /tmp permissions
ls -ld /tmp
chmod 1777 /tmp

# Check SELinux
getenforce
# If Enforcing, try: setenforce 0

# Check systemd PrivateTmp
systemctl show httpd | grep PrivateTmp
# If true, create override:
# /etc/systemd/system/httpd.service.d/privatetmp.conf
# [Service]
# PrivateTmp=false

PHP CLI vs Web Server Mismatch

# Test as web server user
sudo -u www-data php -r 'echo extension_loaded("ionCube Loader")?"yes":"no";'

# Compare configs
php --ini                    # CLI config
# Create phpinfo: echo '<?php phpinfo();' > /var/www/html/info.php
# Check "Loaded Configuration File" in browser
# Remove after: rm /var/www/html/info.php

License Activation: Server Side Error - Forbidden

This indicates ionCube PHP version incompatibility:

GUI Version PHP Version
v26.37+ PHP 8.3 supported
Older PHP 8.2 or earlier required 
# Check Apache error log
tail -50 /var/log/apache2/error.log | grep -i ioncube

# Solution: Either upgrade GUI to v26.37+ or downgrade PHP to 8.2

Other Issues

Invalid Timezone (GUI Inaccessible)

# Edit directly
nano /var/www/html/config/configuration.php

# Find and fix:
define('TIMEZONE', 'UTC');  # Use valid timezone
define('SENSORS_TIMEZONE', 'UTC');

systemctl restart php-fpm

Valid timezones: UTC, Europe/London, America/New_York, Europe/Berlin, etc.

Faxes Not Displayed

# Install libtiff-tools
apt-get install libtiff-tools    # Debian/Ubuntu
yum install libtiff-tools        # RHEL/CentOS

# Verify
which tiff2pdf

File Attachment Blocked

Files like .xlsx, .docx are blocked for security. Compress to .zip or .gz: 

zip archive.zip your_file.xlsx

RRD Graph Errors After Hardware Change

# Delete corrupted RRD files
rm -rf /var/spool/voipmonitor/rrd/*

# Sensor will recreate them
systemctl restart voipmonitor

/dev/shm Full (Session Logout Issues)

# Check usage
df -h /dev/shm

# Temporary increase
mount -o remount,size=1G /dev/shm

# Permanent: edit /etc/fstab
# tmpfs /dev/shm tmpfs defaults,size=1G 0 0

Concurrent Calls Stats Error

Usually caused by duplicate cron entries: 

# Check for duplicates
grep "voipmonitor\|run.php" /etc/crontab

# Comment out duplicates, keep only one

TShark CVE Security Updates

The bundled tshark may have known CVEs. To update: 

cd /var/www/html/bin

# Download updated binary from Wireshark
wget https://www.wireshark.org/download/automated/linux64/tshark
chmod +x tshark
chown www-data:www-data tshark

Dashboard Edit Icon Grayed Out

User lacks edit permission. Grant via User Management > edit user > enable "Edit Dashboard" permission.

GUI Not Loading (Spool Directory Ownership)

If the GUI is not loading or shows generic error messages, the cause may be incorrect ownership of the spool directory by the web server user. 

# Fix spool directory ownership
chown -R www-data:www-data /var/spool/voipmonitor    # Debian/Ubuntu
# OR
chown -R apache:apache /var/spool/voipmonitor        # RHEL/CentOS

ℹ️ Note: The spool directory path is defined by the spooldir parameter in /etc/voipmonitor.conf. Use the correct path for your configuration.



AI Summary for RAG

Summary: VoIPmonitor GUI troubleshooting guide covering: (1) HTTP 500 errors - try client-side steps first (different browser, incognito, clear cache), then check Apache/PHP error logs and SELinux; (2) No CDR for current day - check sensor status in Settings > Sensors, generate debug log if UP, check partitions/timezone/cdr config if Down; (3) GUI debug mode - add ?debug=31415 to URL; (4) Database timeouts - tune innodb_buffer_pool_size (50-70% RAM), increase mod_fcgid timeouts; (5) Database corruption - use mysqlcheck, drop/recreate tables, or innodb_force_recovery; (6) GUI upgrade issues - reset password via database, fix ownership, run php php/run.php upgrade -f; (7) Permission errors - chmod +x bin/*, use setfacl for NAS; (8) IonCube errors - check SELinux, PHP version compatibility (GUI v26.37+ for PHP 8.3); (9) Schema errors - use ?check_tables=1 URL parameter.

Keywords: HTTP 500, no CDR, sensor status, debug mode, ?debug=31415, innodb_buffer_pool_size, MySQL tuning, database corruption, mysqlcheck, innodb_force_recovery, GUI upgrade, password reset, IonCube, SELinux, PHP 8.3, ?check_tables=1, NAS permissions, setfacl, mod_fcgid timeout, FcgidIOTimeout, mscgen, SIP call flow, tshark CVE, MySQL 8.0.42, SYSTEM_USER privilege, /dev/shm, timezone error, libtiff-tools, file attachment blocked

Key Questions:

  • HTTP 500 error on GUI - what to try first?
  • No CDR or dashboard data for current day - how to diagnose?
  • How to enable GUI debug mode?
  • GUI queries timeout - how to tune MySQL?
  • Database corrupted - which recovery method to use?
  • Cannot login after GUI upgrade - how to reset password?
  • Permission errors with NAS spool - how to fix?
  • IonCube temp directory errors - what causes them?
  • GUI shows "Unknown column in field list" - how to fix?
  • SIP call flow diagram shows error - how to fix SELinux blocking?
  • MySQL 8.0.42 causing crashes - what to do?
  • License activation fails with Forbidden error - what causes it?
Retrieved from "https://www.voipmonitor.org/doc/index.php?title=GUI_troubleshooting&oldid=10531"