GUI troubleshooting: Difference between revisions

From VoIPmonitor.org
(Add Key Question for web portal inaccessibility after GUI upgrade)
(Rewrite: konsolidace a vylepšení struktury - zkráceno z ~4000 na ~540 řádků)
Tag: Replaced
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.


{| class="wikitable" style="width:100%; background:#f8f9fa; border:2px solid #00A7E3; margin-bottom:20px;"
== Quick Navigation ==
 
{| class="wikitable"
! Category !! Common Issues
|-
| [[#Access Issues|Access Issues]] || HTTP 500, blank screen, single user cannot access
|-
|-
! colspan="3" style="background:#00A7E3; color:white; font-size:1.2em; padding:10px;" | Quick Navigation - GUI Troubleshooting
| [[#No Data Issues|No Data Issues]] || No CDR for today, empty dashboard, missing calls
|-
|-
! style="width:33%; background:#e0f4fc; padding:8px; vertical-align:top;" | First Steps & Common Issues
| [[#Database Issues|Database Issues]] || Timeouts, corruption, connections, schema errors
! style="width:33%; background:#fef3e2; padding:8px; vertical-align:top;" | Database & Performance
! style="width:33%; background:#f1f5f9; padding:8px; vertical-align:top;" | Upgrade & Configuration
|-
|-
| style="vertical-align:top; padding:10px;" |
| [[#GUI Upgrade Issues|GUI Upgrade Issues]] || Cannot login, blank screen, VM Binary error
'''Start Here'''
|-
* [[#HTTP 500 Error - Firstline Troubleshooting|HTTP 500 Error]] - ''try browser steps first''
| [[#Permission Issues|Permission Issues]] || Ownership errors, NAS access, binary execution
* [[#Specific User Cannot Access GUI (Network vs Application Level)|User Cannot Access GUI]]
|-
* [[#GUI Debug Mode|Debug Mode]] - ''?debug=31415''
| [[#IonCube and PHP Issues|IonCube/PHP Issues]] || Loader errors, temp directory, PHP version
 
|-
'''Common Problems'''
| [[#Other Issues|Other Issues]] || Timezone, fax, attachments, RRD graphs
* [[#No_CDR_or_Dashboard_Data_for_Current_Day|No CDR for Current Day]]
* [[#Known GUI Bugs and Workarounds|Known GUI Bugs]]
* [[#Faxes Cannot Be Displayed in the GUI|Faxes Not Displayed]]
* [[#RRD Graph Errors After Hardware Upgrades|RRD Graph Errors]]
* [[#SIP Call Flow Diagram Error: "convert msc to svg (mscgen): unknown error"|SIP Call Flow Diagram Error - SELinux]]
* [[#File Attachment Blocked (xlsx, docx, Other File Extensions)|File Attachment Blocked]]
| style="vertical-align:top; padding:10px;" |
'''Performance Issues'''
* [[#GUI Queries Time Out (Slow Dashboard or CDR Performance)|Queries Time Out]] - ''MySQL tuning''
* [[#MySQL/MariaDB Connection Limit Issues|Connection Limit Issues]]
 
'''Database Problems'''
* [[#CDR_View_Error_-_Use_?check_tables=1_Parameter|CDR View Error]] - ''use ?check_tables=1''
* [[#MySQL/MariaDB Database Corruption|Database Corruption]] - ''5 recovery methods''
* [[#MySQL Swap Memory Warning (Safe to Ignore)|MySQL Swap Warning]] - ''when to ignore 50 MB''
* [[#Alternative: MySQL General Log|MySQL Debug Log]]
 
'''Stats Issues'''
* [[#Concurrent Calls Stats Server-Side Error Caused by Duplicate Cron Jobs|Concurrent Calls Stats Error]]
| style="vertical-align:top; padding:10px;" |
'''Upgrade Issues'''
* [[#Unable to Log In After GUI Upgrade|Cannot Log In After Upgrade]] - ''password reset''
* [[#GUI Upgrade Issues|GUI Upgrade Issues]] - ''all scenarios''
 
'''Permissions'''
* [[#Incorrect Ownership / Permission Errors|Ownership/Permission Errors]]
* [[#Permission Denied for NAS-Mounted Spool Directories|NAS Spool Permissions]]
 
'''Server Configuration'''
* [[#IonCube Loader Issues|IonCube Loader Issues]]
* [[#/dev/shm Filesystem Capacity Issues|/dev/shm Capacity]]
* [[#GUI Inaccessible Due to Invalid Timezone Setting|Invalid Timezone]]
|}
|}


== HTTP 500 Error - Firstline Troubleshooting ==
== Access Issues ==
 
If you encounter an HTTP 500 error when accessing the VoIPmonitor GUI after installation or during normal operation, start with these client-side troubleshooting steps BEFORE assuming a server-side issue. Many HTTP 500 errors are caused by browser-related issues rather than server configuration problems.
 
=== Client-Side Troubleshooting (FIRST, try these in order) ===
 
==== Step 1: Try a Different Web Browser ====
 
First, test whether the issue is specific to your current browser by accessing the GUI using a different browser.
 
* If you are using Chrome, try Firefox or Edge
* If you are using Firefox, try Chrome or Edge
* If you are using Safari, try Chrome or Firefox
 
If the GUI loads correctly in a different browser, the issue is specific to your original browser (likely cache, cookies, or extensions).
 
==== Step 2: Try Incognito or Private Browsing Mode ====
 
Open the GUI in an incognito or private browsing window in your current browser.
 
* Chrome/Edge: Press <code>Ctrl+Shift+N</code> (Windows) or <code>Cmd+Shift+N</code> (Mac)
* Firefox: Press <code>Ctrl+Shift+P</code> (Windows) or <code>Cmd+Shift+P</code> (Mac)
* Safari: Press <code>Cmd+Shift+N</code>
 
Incognito mode disables browser extensions and uses a fresh session without cached data. If the GUI works in incognito mode, the issue is caused by browser extensions or cache/cookies.
 
==== Step 3: Clear Browser Cache and Cookies ====
 
If the issue persists, clear your browser's cache and cookies:
 
'''For Chrome/Edge:'''
* Windows/Linux: Press <code>Ctrl+Shift+Delete</code>
* Mac: Press <code>Cmd+Shift+Delete</code>
* Select "Cached images and files" and "Cookies and other site data"
* Click "Clear data"
 
'''For Firefox:'''
* Windows/Linux: Press <code>Ctrl+Shift+Delete</code>
* Mac: Press <code>Cmd+Shift+Delete</code>
* Select "Cache" and "Cookies"
* Click "Clear Now"
 
'''For Safari:'''
* Press <code>Cmd+Option+E</code> to clear cache
* Preferences > Privacy > Manage Website Data to clear cookies
 
After clearing the cache and cookies, refresh the page and try accessing the GUI again.
 
==== Step 4: Disable Browser Extensions ====


Browser extensions (plugins) can sometimes interfere with web applications, causing HTTP 500 errors. Try the following:
=== HTTP 500 Error ===


* Temporarily disable all extensions in your browser
'''Client-side steps (try first):'''
* Refresh the GUI page to see if the error is resolved
# Different browser or incognito mode
* If the GUI works with extensions disabled, re-enable extensions one at a time to identify the problematic extension
# Clear browser cache (Ctrl+Shift+Delete)
# Disable browser extensions
# Try from a different network


If disabling extensions resolves the issue, you may need to add an exception for the VoIPmonitor GUI URL or use the GUI in a browser without the problematic extension.
'''Server-side diagnosis:'''


=== Moving to Server-Side Troubleshooting ===
If you have completed ALL client-side troubleshooting steps above and the HTTP 500 error persists across multiple browsers, in incognito mode, and after clearing cache/cookies, then proceed to server-side troubleshooting:
* Check PHP error logs for specific error messages
* Verify IonCube Loader configuration matches your PHP version (see [[Re-install_the_GUI]])
* Test PHP functionality: Create a simple <code>info.php</code> file with <code>&lt;?php phpinfo(); ?&gt;</code> and access it to verify PHP is working
* Check web server status and error logs (<code>/var/log/apache2/error.log</code> or <code>/var/log/httpd/error_log</code>)
The server-side troubleshooting section below provides detailed guidance for diagnosing common server configuration issues.
== Specific User Cannot Access GUI (Network vs Application Level) ==
If a specific user cannot access the VoIPmonitor GUI while other users can successfully access it, and the server appears to be running correctly, you should determine whether the issue is at the application level (VoIPmonitor configuration) or network level (connectivity issues).
=== Troubleshooting Flow ===
Follow this diagnostic workflow to identify the root cause:
==== Step 1: Check for IP-Based Login Restrictions (Application Level) ====
First, verify whether the VoIPmonitor application is blocking the user's login through IP-based restrictions.
1. Log in to the VoIPmonitor GUI as an administrator
2. Navigate to '''GUI > Users & Audit > Users'''
3. Edit the affected user's profile
4. Click the '''Secure users''' tab
5. Check the '''Enable remote addresses''' field
If this field contains IP addresses and the user's current IP is not listed, this is blocking the login. Add the user's current IP address or clear the whitelist to allow access from any location.
For detailed information on IP-based login restrictions, see the [[User_Management]] page.
==== Step 2: Verify Server Connectivity Using tcpdump (Network Level) ====
If IP-based restrictions are not the cause, determine whether the server is responding to connection attempts by using `tcpdump` to monitor network traffic.
1. On the VoIPmonitor server, run a tcpdump capture on the GUI port (typically port 80 for HTTP or 443 for HTTPS):
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Monitor HTTP traffic
# Check Apache error log
sudo tcpdump -i any -n port 80
tail -100 /var/log/apache2/error.log    # Debian/Ubuntu
tail -100 /var/log/httpd/error_log      # RHEL/CentOS


# Monitor HTTPS traffic
# Check PHP-FPM log
sudo tcpdump -i any -n port 443
tail -100 /var/log/php-fpm/www-error.log
</syntaxhighlight>


2. From the affected user's machine, attempt to access the GUI (e.g., open the login page in a browser)
# Check SELinux
 
getenforce
3. Observe the tcpdump output on the server:
# If "Enforcing", try temporarily: setenforce 0
 
==== Scenario A: No Traffic Visible ====
If tcpdump shows **no packets** from the client's IP address:
* The client is not reaching the server at all
* Check network routing and firewall rules on intermediate devices
* Verify the client is using the correct server address
* Engage the network team to investigate routing issues
 
==== Scenario B: Only SYN Packets Visible ====
If tcpdump shows only TCP SYN packets from the client (no SYN-ACK responses):
* The server receives the connection request but is not responding
* The GUI service may not be running or listening on the expected port
* Check the web server status: `systemctl status apache2` or `systemctl status httpd`
* Check if the service is listening on the correct port: `netstat -tuln | grep -E '80|443'`
 
==== Scenario C: SYN and SYN-ACK Packets Present ====
If tcpdump shows **both** an incoming TCP SYN packet from the user's IP and an outgoing TCP SYN-ACK packet to the user's IP:
* The server is responding correctly
* The problem is in the network path between the server and the client
* Likely causes: firewall or router blocking the return traffic
* Engage the network team to investigate routing or firewall rules
 
=== Example tcpdump Output ===
 
<syntaxhighlight lang="bash">
# Successful connection attempt (SYN, SYN-ACK visible)
IP 192.168.1.50.50000 > 10.0.0.10.80: Flags [S], seq 0, win 64240, options [mss 1460,sackOK,TS val...]
IP 10.0.0.10.80 > 192.168.1.50.50000: Flags [S.], seq 0, ack 1, win 28960, options [mss 1460,sackOK,TS val...]
# The server is responding correctly - issue is likely return traffic being blocked
</syntaxhighlight>
</syntaxhighlight>


=== Additional Network Troubleshooting ===
{{Tip|For detailed SQL query debugging, add <code>?debug=31415</code> to any GUI URL and check browser console (F12).}}
 
If tcpdump indicates a network-level issue, perform these additional checks:
 
* **Test from server:** Can you curl the GUI from the server itself? `curl http://localhost/`
* **Test from local network:** Can a user on the same local network as the server access it?
* **Check firewall rules:** `sudo iptables -L -n` or `sudo firewall-cmd --list-all`
* **Check routing tables:** `ip route show` or `route -n`
* **Traceroute:** Run `traceroute <server-ip>` from the affected client to identify where the path breaks
 
=== Summary ===
 
When a specific user cannot access the GUI while others can:
 
* **Application-level cause:** Check IP-based login restrictions in User Management first
* **Network-level cause:** Use tcpdump to verify whether the server is receiving and responding to connection attempts
* If SYN and SYN-ACK packets are visible, the server is working correctly - the issue is network infrastructure blocking return traffic
 
 
== GUI Debug Mode ==
 
The GUI debug mode allows you to see SQL queries and other debugging information directly in your browser's Developer Console.
 
=== Enabling Debug Mode ===
 
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:
 
<code>http://your-server/voipmon/admin.php?debug=31415</code>
 
This enables the following features:
* 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 ===
 
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.
 
 
 
== CDR View Error - Use ?check_tables=1 Parameter ==
 
If you encounter an error when accessing the CDR (Call Detail Records) view in the VoIPmonitor GUI (even after a server restart), this is often caused by database table inconsistencies. The GUI provides a built-in mechanism to check and fix table structure issues.


=== Solution: Admin URL with ?check_tables=1 ===
=== Single User Cannot Access ===


The quickest fix is to access the VoIPmonitor admin URL with the <code>?check_tables=1</code> parameter appended. This triggers an automatic table check and schema update process.
If one user cannot access GUI while others can:


==== Step 1: Access the Admin URL with the Table Check Parameter ===
# '''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>


Open your web browser and navigate to the VoIPmonitor admin URL with <code>?check_tables=1</code> appended to the end:
=== Blank Screen After Upgrade ===


<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
https://<your-voipmonitor-domain>/voipmonitor/admin.php?check_tables=1
# Check for conflicting PEAR file
</syntaxhighlight>
ls -la /usr/share/pear/constants.php
# If exists, remove it:
rm /usr/share/pear/constants.php


Replace <code><your-voipmonitor-domain></code> with your actual VoIPmonitor server address (e.g., <code>voipmonitor.yourcompany.com</code> or <code>192.168.1.100</code>).
# Check SELinux
getenforce
# If Enforcing, temporarily disable: setenforce 0


==== Step 2: Wait for Table Check to Complete ===
# Clear browser cache
 
# Press Ctrl+F5 in browser
The GUI will automatically check all database tables and perform schema updates if necessary. This process may take several seconds to a few minutes depending on the database size and the number of tables that need verification/updating.
 
You should see a progress indicator or confirmation message indicating the table check has completed successfully.
 
==== Step 3: Navigate Back to CDR View ===
 
After the table check completes, navigate back to the CDR view in the GUI:
 
# Click on '''CDR''' or '''Call Detail Records''' in the navigation menu
# Verify that the CDR view now loads correctly without errors
 
The error should now be resolved.
 
=== When This Fix Applies ===
 
Use this solution when:
* CDR view displays an error instead of call list
* The error occurs after a database migration or schema change
* The error persists even after restarting the VoIPmonitor server
* Other GUI sections work correctly (e.g., Dashboard, Settings) but CDR does not
 
=== Common CDR View Error Messages ===
 
Typical error messages that indicate a table structure issue include:
* "Table doesn't exist" errors
* "Unknown column" errors
* SQL errors referencing missing database objects
 
=== Alternative: Check MySQL Schema in GUI ===
 
If the <code>?check_tables=1</code> parameter does not resolve the issue, you can also run the table check from the GUI interface:
 
# Navigate to '''Tools -> System Status'''
# Click on the '''Check MySQL Schema''' button
# If the system reports missing tables or schema issues, click '''Start Upgrade / Run SQL''' to apply fixes
 
=== Prevention: Disable disable_dbupgradecheck Parameter ===
 
To prevent future table structure issues, ensure that automatic database schema upgrades are enabled in your VoIPmonitor sensor configuration:
 
<syntaxhighlight lang="ini">
# In /etc/voipmonitor.conf - ensure this line is disabled or set to no:
# disable_dbupgradecheck = no
</syntaxhighlight>
</syntaxhighlight>


If <code>disable_dbupgradecheck = yes</code> is present, the sensor will skip automatic table creation and schema updates, which can lead to inconsistencies between the database schema and GUI expectations. Comment out or remove this line to enable automatic schema maintenance.
== No Data Issues ==


=== No CDR or Dashboard Data for Current Day ===


'''Step 1: Check sensor status'''


== No CDR or Dashboard Data for Current Day ==
Navigate to '''Settings > Sensors''' in GUI:
* '''Status UP''' - Sensor connected, proceed to Step 2
* '''Status Down''' - Sensor disconnected, see [[#Sensor Down|Sensor Down]] below


If the VoIPmonitor GUI displays CDR or dashboard data for previous days but not for the current day, follow this diagnostic workflow to identify the root cause and gather information for support.
'''Step 2: Generate debug log (if sensor UP)'''


=== Step 1: Check Sniffer/Sensor Status ===
Navigate to '''Tools > Generate Debug Log''' and share the link with VoIPmonitor support.


The first step is to verify whether the VoIPmonitor sensor service is running and actively capturing traffic.
'''Step 3: Check common causes'''


# Navigate to '''Settings -> Sensors'''
{| class="wikitable"
# Check the status of each sensor
! Cause !! Diagnosis !! Solution
 
|-
Possible statuses and their meanings:
| 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>
* '''UP''' (green): The sensor is running and actively monitoring network traffic
|-
* '''Down''' (red): The sensor service is not running or has stopped unexpectedly
| Timezone mismatch || GUI shows different time than DB || Settings > System Configuration > National > Timezone
* '''Warning''' (yellow): The sensor is running but experiencing issues
|-
| CDR disabled || Check voipmonitor.conf || Ensure <code>cdr = yes</code>
|-
| Spool directory || Check <code>spooldir</code> path || Verify path exists and has correct permissions
|}


=== Step 2: If Sensor Status is UP ===
{{Note|If GUI shows yesterday's data but not today's, the most common cause is a missing database partition.}}


If the sensor shows "UP" status but no data appears for the current day:
==== Sensor Down ====


# Navigate to '''GUI -> Tools -> Generate Debug Log'''
# Enter your email address in the provided field
# Click '''Generate Debug Log'''
# A link to the debug log will be sent to your email
# Share this link with VoIPmonitor support for further investigation
The debug log contains:
* System configuration details
* Sensor status and performance metrics
* Recent error messages
* Network interface information
* Packet capture statistics
This diagnostic information allows support to quickly identify the specific cause of the issue without requiring remote access.
=== Step 3: If Sensor Status is Down ===
If the sensor shows "Down" status:
# Log in to the sensor server via SSH as root
# Check the sensor service status:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Check sensor service
systemctl status voipmonitor
systemctl status voipmonitor
</syntaxhighlight>


# Review the sensor logs for error messages:
<syntaxhighlight lang="bash">
# View recent logs
# View recent logs
journalctl -u voipmonitor -n 100
journalctl -u voipmonitor -n 500


# Or follow logs in real-time
# Check database connectivity
journalctl -u voipmonitor -f
mysql -h DB_HOST -u voipmonitor -p -e "SELECT 1"
</syntaxhighlight>


# Attempt to restart the sensor:
# Restart if needed
<syntaxhighlight lang="bash">
systemctl restart voipmonitor
systemctl restart voipmonitor
systemctl status voipmonitor
</syntaxhighlight>
If the sensor will not start or crashes immediately after restart, this typically requires deeper investigation. Provide VoIPmonitor support with:
* SSH root access to the sensor host
* Output of <code>journalctl -u voipmonitor -n 500</code>
* Output of <code>ps aux | grep voipmonitor</code>
=== Step 4: Common Causes and Solutions ===
After verifying sensor status and checking logs, these are the most common causes for missing current-day data:
==== Database Partition Issues ====
VoIPmonitor stores CDRs in daily partitions. If the partition for "today" does not exist, the database cannot write new rows.
# Check partitions in MySQL:
<syntaxhighlight lang="sql">
SHOW PARTITIONS FROM cdr;
</syntaxhighlight>
# Look for gaps in the partition list (e.g., p20231027 followed by p20231029 but missing p20231028)
# Add missing partition if needed:
<syntaxhighlight lang="sql">
ALTER TABLE cdr ADD PARTITION (PARTITION p20231028 VALUES LESS THAN (TO_DAYS('2023-10-29')));
</syntaxhighlight>
</syntaxhighlight>


{{Note|Prevent future partition issues by ensuring the partition maintenance script runs daily in crontab. See the [[Maintenance]].}}
=== No Audio Playback ===
 
==== Timezone Mismatch ====


If the GUI and database servers are in different timezones, "Current Day" in the GUI may query a future date that does not exist in the database.
If QoS data is visible but no audio:


# Check server timezone:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
date
# Check voipmonitor.conf
</syntaxhighlight>
grep -E "^savertp|^savegraph" /etc/voipmonitor.conf
 
# Check GUI timezone:
Navigate to '''Settings -> System Configuration -> National''' and verify the "Timezone" setting


# Ensure both are configured to match your region
# Should show:
 
# savertp = yes
==== Configuration Issues ====
# savegraph = yes (optional)
 
Verify that CDR collection is enabled in <code>voipmonitor.conf</code>:
 
<syntaxhighlight lang="ini">
# /etc/voipmonitor.conf
 
# CDR saving must be enabled
cdr = yes
 
# Verify spool directory is writable
spooldir = /var/spool/voipmonitor
</syntaxhighlight>
 
After making configuration changes:
<syntaxhighlight lang="bash">
systemctl restart voipmonitor
</syntaxhighlight>
</syntaxhighlight>


=== Step 5: Verify Data Capture ===
See [[Sniffer_configuration#RTP_and_Audio_Recording|RTP and Audio Recording]] for detailed configuration.
 
After addressing the issue, verify that new calls are being captured:
 
# Make a test call
# Navigate to '''CDR View''' and select "Last Hour" or "Today" time range
# The new call should appear immediately in the CDR list
 
# Check sensor throughput in Settings > Sensors to see live packet counts
# Monitor logs for any new errors:
<syntaxhighlight lang="bash">
journalctl -u voipmonitor -f
</syntaxhighlight>
 
=== When to Contact Support ===
 
If you have completed the above steps and the issue persists, gather this information before contacting support:
 
* Sensor status from Settings > Sensors (screenshot or status description)
* Debug log link from Tools > Generate Debug Log
* Sensor logs: <code>journalctl -u voipmonitor -n 500</code>
* Configuration excerpt: <code>grep -E "^(cdr|spooldir|interface|sipport)" /etc/voipmonitor.conf</code>
* MySQL partition output: <code>SHOW PARTITIONS FROM cdr</code>
 
 
 
 
== GUI Queries Time Out (Slow Dashboard or CDR Performance) ==
 
If GUI queries consistently time out after 40-50 seconds when viewing data over long periods (e.g., dashboards, CDR lists), this is typically caused by database performance issues rather than web server timeout limits. The MySQL/MariaDB database needs tuning to handle large data queries efficiently.
 
=== Symptoms ===
 
* GUI queries time out after approximately 40-50 seconds when viewing dashboards or CDR data over extended time ranges
* Timeout occurs consistently when querying large datasets (e.g., last 7 days or longer)
* Increasing web server timeout settings does not resolve the issue
* Database query performance is slow when aggregating large amounts of CDR data


=== Root Cause ===
== Database Issues ==


The MySQL/MariaDB database is not optimally configured for the volume of data being queried. The primary bottleneck is usually inadequate `innodb_buffer_pool_size` configuration, which limits how much data InnoDB can cache in memory. This forces frequent disk reads for large queries, causing timeouts.
=== GUI Queries Timeout (40-50 seconds) ===


=== Solution: Tune MySQL for Better Performance ===
'''MySQL/MariaDB tuning:'''
 
==== Step 1: Optimize innodb_buffer_pool_size ====
 
The most critical parameter is `innodb_buffer_pool_size`, which defines how much memory InnoDB uses to cache data and indexes.


<syntaxhighlight lang="ini">
<syntaxhighlight lang="ini">
# /etc/mysql/my.cnf or /etc/mysql/mariadb.conf.d/50-server.cnf
# /etc/mysql/mysql.conf.d/mysqld.cnf or /etc/my.cnf.d/server.cnf


[mysqld]
[mysqld]
# Buffer pool size: use 50-70% of available RAM on dedicated database servers
# Set to 50-70% of available RAM
# For shared servers (GUI + MySQL on same host), use approximately half of available RAM
innodb_buffer_pool_size = 4G
innodb_buffer_pool_size = 14G  # Example: 14GB for a 32GB shared server
</syntaxhighlight>


{{Tip|For shared servers where VoIPmonitor and MySQL run on the same host, use approximately half of the available RAM: <code>(Total RAM - VoIPmonitor memory - OS overhead) / 2</code>. For dedicated database servers, use 50-70% of total RAM.}}
# Reduce disk I/O (slight durability tradeoff)
 
==== Step 2: Configure InnoDB Flush Settings ====
 
<syntaxhighlight lang="ini">
[mysqld]
# Flush logs to OS cache, write to disk once per second (faster, minimal data loss risk)
innodb_flush_log_at_trx_commit = 2
innodb_flush_log_at_trx_commit = 2
</syntaxhighlight>
{{Warning|1=For extreme scenarios (4,000+ concurrent calls, UI lag, extremely high CDR insertion rates), see [[High-Performance_VoIPmonitor_and_MySQL_Setup_Manual]] for specialized configurations including <code>innodb_flush_log_at_trx_commit=0</code>.}}
==== Step 3: Enable Additional Optimizations ====
<syntaxhighlight lang="ini">
[mysqld]
# Store each table in its own file (essential for partitioning)
innodb_file_per_table = 1
# LZ4 compression for modern MariaDB (reduces I/O)
innodb_compression_algorithm = lz4
</syntaxhighlight>
==== Step 4: Restart MySQL and Verify Configuration ====
After making changes to the MySQL configuration file:
<syntaxhighlight lang="bash">
# Restart MySQL/MariaDB
systemctl restart mysql      # or systemctl restart mariadb
# Verify the new settings are active
mysql -e "SHOW VARIABLES LIKE 'innodb_buffer_pool_size';"
mysql -e "SHOW VARIABLES LIKE 'innodb_flush_log_at_trx_commit';"
</syntaxhighlight>
==== Step 5: Apply to All Database Instances ====
If you are running a replication setup (master-slave, master-master, or Galera cluster), apply these configuration changes to all database instances and restart each one.
=== Additional Optimizations for SSD Storage ===
If the database is running on SSD or NVMe storage:


1. Ensure RAID controller cache policy is set to '''WriteBack''' for RPM disks (not needed for SSDs)
# Increase connection timeout
2. Consider enabling <code>innodb_flush_method=O_DIRECT</code> in MySQL configuration (see [[High-Performance_VoIPmonitor_and_MySQL_Setup_Manual]] for details)
wait_timeout = 28800
3. Ensure <code>innodb_io_capacity</code> is set appropriately for SSD performance
interactive_timeout = 28800
 
=== Prevention: Ongoing Performance Monitoring ===
 
Monitor database performance in the VoIPmonitor syslog:
 
<syntaxhighlight lang="bash">
# Monitor SQL queue depth (SQLq) - growing consistently indicates database bottleneck
tail -f /var/log/syslog | grep SQLq
</syntaxhighlight>
</syntaxhighlight>


For detailed guidance on scaling and performance tuning, see the [[Scaling]] documentation. For extreme high-performance scenarios (4,000+ concurrent calls, very high CPS), see [[High-Performance_VoIPmonitor_and_MySQL_Setup_Manual]].
'''Apache mod_fcgid timeout:'''


=== When Web Server Timeout Settings DO Apply ===
If you see "server side error - check your http server error log. - connection to the web server was lost / interrupted":
 
Increasing PHP/Nginx timeout settings is appropriate when:
* Queries complete successfully but exceed default 60-second limits
* Database performance is confirmed to be good (fast query execution)
* Timeout behavior varies or shows proxy errors
 
In these cases, adjust web server settings instead:
 
'''For PHP-FPM:'''
* PHP: <code>max_execution_time</code> in php.ini
* PHP-FPM pool: <code>request_terminate_timeout</code>
* Nginx: <code>fastcgi_read_timeout</code>
 
'''For Apache with mod_fcgid:'''
If your GUI intermittently shows "server side error - check your http server error log. - connection to the web server was lost / interrupted," check the Apache error logs for timeout-related messages from the proxy_fcgi module. If you see mod_fcgid timeout errors, increase the mod_fcgid timeout values in your Apache configuration:
 
The mod_fcgid module controls how long Apache waits for PHP FastCGI processes to complete. Add or adjust these directives in httpd.conf, apache2.conf, or a relevant virtual host/directory configuration block:


<syntaxhighlight lang="apache">
<syntaxhighlight lang="apache">
# In httpd.conf or apache2.conf
<IfModule mod_fcgid.c>
<IfModule mod_fcgid.c>
     # Time to wait for a connection to the FastCGI process
     FcgidIdleTimeout 900
     FcgidConnectTimeout 1200
     FcgidProcessLifeTime 7200
 
     FcgidConnectTimeout 300
     # Time to wait for FastCGI responses
     FcgidIOTimeout 900
     FcgidIOTimeout 1200
 
    # Maximum lifetime of any FastCGI process
    FcgidProcessLifeTime 1200
 
    # Maximum idle time for a FastCGI process before it's terminated
    FcgidIdleTimeout 1200
 
    # Maximum time waiting for output from FastCGI application
    FcgidOutputBufferSize 65536
</IfModule>
</IfModule>
</syntaxhighlight>
</syntaxhighlight>
After making these changes, restart Apache/httpd.


<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# CentOS/RHEL/AlmaLinux
systemctl restart apache2  # or httpd
sudo systemctl restart httpd
 
# Debian/Ubuntu
sudo systemctl restart apache2
</syntaxhighlight>
</syntaxhighlight>


Monitor the GUI to see if the intermittent server-side errors are resolved.
=== Too Many Connections ===
 
The timeout value (1200 seconds = 20 minutes in this example) should be adjusted based on your specific requirements. Values of 600-1200 seconds (10-20 minutes) are common for VoIPmonitor GUI operations that may take longer due to large data queries.
 
However, for consistent 40-50 second timeouts on long-period queries, database performance tuning is the correct solution.
 
 
== Known GUI Bugs and Workarounds ==
 
=== Dashboard Edit Icon Grayed Out ===
 
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.
 
==== Symptoms ====
 
* Admin users cannot rename dashboards
* Edit icons on the "Manage Dashboards" page are grayed out (disabled)
* The issue affects all admin users, not just specific accounts
* The `readonly` directive in `voipmonitor.conf` is NOT enabled
 
==== Workaround ====
 
The edit icon within the dashboard view may not work, but users can successfully rename dashboards directly from the main list of dashboards:
 
# Navigate to the main dashboard list (not within a specific dashboard)
# Find the dashboard you want to rename in the list
# Use the rename option available in the main dashboard list
 
The issue of editing metrics from the "Manage Dashboards" page is under investigation and does not currently have a workaround.
 
==== Note ====
 
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.
 
 
== 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.
 
=== Unable to Log In After GUI Upgrade ===
 
If users cannot log in to the GUI immediately after an upgrade, or if login attempts fail or redirect back to the login screen, the issue may be caused by stale authentication data in the user accounts. This can happen especially when using alternative PHP session storage backends (such as Redis) instead of the default `/dev/shm`.
 
==== Symptoms ====
 
* Users cannot log in to the GUI after an upgrade
* Login page accepts credentials but redirects back to login screen (login loop)
* Issue affects all users or specific user accounts
* Browser cache clearing (see [[#Browser Cache Issues After GUI Upgrade]]) does not resolve the issue
* Using non-standard PHP session handlers (Redis, memcached, etc.)
 
==== Root Cause ====
 
After a VoIPmonitor GUI upgrade, stale authentication data or session remnants may exist in user accounts or the session storage backend. The GUI upgrade may have changed internal authentication structures or session handling, making existing authentication data incompatible with the new version. This is particularly noticeable when using Redis or other custom session storage instead of the default `/dev/shm` filesystem.
 
==== Solution: Reset User Password via Database ====
 
Resetting the password for the affected user account clears any stale authentication data and allows the user to log in with the new credentials on the upgraded GUI.
 
<syntaxhighlight lang="bash">
# Connect to the VoIPmonitor database
mysql -u root -p voipmonitor
</syntaxhighlight>
 
Run the SQL command to reset the password:


<syntaxhighlight lang="sql">
<syntaxhighlight lang="sql">
-- Replace 'admin' with the actual username
-- Check current connections
-- Replace 'newpassword' with a temporary password
SHOW STATUS LIKE 'Threads_connected';
UPDATE users SET password = MD5('newpassword') WHERE username = 'admin';
SHOW VARIABLES LIKE 'max_connections';
</syntaxhighlight>
 
After resetting the password:
 
# Log in to the GUI using the temporary password
# Immediately change the password through the GUI settings for security
 
{{Warning|The <code>MD5()</code> hash is legacy functionality. Log in immediately and change your password through the GUI to ensure proper security.}}
 
==== Additional Troubleshooting ====
 
If password reset does not resolve the issue, also check:
 
* Clear browser cache and cookies (see [[#Browser Cache Issues After GUI Upgrade]])
* Restart the web server: <code>systemctl restart apache2</code> or <code>systemctl restart httpd</code>
* Restart PHP-FPM: <code>systemctl restart php-fpm</code> (if using PHP-FPM)
* Check if session storage backend (Redis, memcached) is running and accessible
 
For detailed information on user management and authentication, see the [[User_Management]] page.
 
=== 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)'''
-- Increase limit (temporary)
SET GLOBAL max_connections = 500;


Perform a hard refresh to force the browser to reload all assets:
-- Permanent: add to my.cnf
* Windows/Linux: Press <code>Ctrl+F5</code> or <code>Ctrl+Shift+R</code>
-- max_connections = 500
* 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>
</syntaxhighlight>


Look for error patterns like:
=== MySQL Swap Memory Warning ===
* <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
If you see swap memory warning on GUI login:
sudo systemctl restart apache2


# For nginx with PHP-FPM
* '''Less than 50 MB swap''' - Safe to ignore, minor performance impact
sudo systemctl restart php-fpm
* '''Hundreds of MB or GB''' - Investigate memory usage, consider increasing RAM or reducing innodb_buffer_pool_size
</syntaxhighlight>
 
==== Step 3: Verify Local Access ====
After restarting, verify that the web server is responding locally:


<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Test local access to web server
# Check MySQL memory usage
wget -O - http://127.0.0.1
ps aux | grep mysqld
free -h
</syntaxhighlight>
</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.
=== Unknown Column in Field List ===


==== Step 4: Check Firewall Rules ====
If GUI shows "Unknown column [table].[column] in 'field list'":
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">
<syntaxhighlight lang="bash">
# Check firewalld rules (RHEL/CentOS/AlmaLinux)
# Method 1: URL parameter (fastest)
sudo firewall-cmd --list-all
# Add ?check_tables=1 to GUI URL:
# http://your-gui-ip/admin.php?check_tables=1


# Check iptables rules
# Method 2: Command line
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
cd /var/www/html
php php/run.php dbcheck


# Execute the forced upgrade command
# Method 3: Restart sensor (if disable_dbupgradecheck=no)
php php/run.php upgrade -f
systemctl restart voipmonitor
</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>
</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:
=== Database Corruption ===


<syntaxhighlight lang="bash">
'''Recovery methods (try in order):'''
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:


'''Method 1: Table repair'''
<syntaxhighlight lang="bash">
<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.
=== SIP Call Flow Diagram Error: "convert msc to svg (mscgen): unknown error" ===
If you attempt to view a SIP call flow diagram from the CDR SIP history and receive the error **"error in convert msc to svg (mscgen): unknown error"**, this is typically caused by SELinux blocking the execution of the mscgen binary. This issue occurs on RHEL/CentOS/AlmaLinux systems where SELinux is enabled by default.
==== Diagnosis: Check SELinux Audit Logs ====
First, verify that SELinux is blocking the mscgen binary by checking the audit logs:
<syntaxhighlight lang="bash">
# Check recent SELinux denials for mscgen
sudo ausearch -m avc -ts recent | grep mscgen
# Alternatively, grep the audit log directly
sudo grep mscgen /var/log/audit/audit.log
</syntaxhighlight>
If you see AVC denial entries mentioning mscgen, SELinux is blocking its execution.
==== Solution: Create SELinux Policy Module for mscgen ====
Use the `audit2allow` tool to generate and install a custom SELinux policy module that permits mscgen execution:
<syntaxhighlight lang="bash">
# Step 1: Generate a local policy module from the audit log
# This reads the denial and creates a policy to allow it
sudo grep mscgen /var/log/audit/audit.log | sudo audit2allow -M mscgen_local
# Step 2: Install the newly created policy module
sudo semodule -i mscgen_local.pp
</syntaxhighlight>
After installing the policy module, verify that the SIP call flow diagrams now render correctly by:
# Refreshing the GUI page
# Clicking on the SIP history for any CDR
# Confirming the sequence diagram displays without error
==== Alternative: Disable SELinux (Not Recommended) ====
If creating a custom policy module is not feasible, you can disable SELinux entirely. However, this is not recommended for production systems as it reduces security.
'''Permanently disable SELinux:'''
Edit the SELinux configuration file:
<syntaxhighlight lang="bash">
sudo nano /etc/selinux/config
</syntaxhighlight>
Change <code>SELINUX=enforcing</code> to:
<syntaxhighlight lang="ini">
SELINUX=disabled
</syntaxhighlight>
Reboot the server:
<syntaxhighlight lang="bash">
sudo reboot
</syntaxhighlight>
'''Temporarily disable SELinux (for testing):'''
<syntaxhighlight lang="bash">
# Temporarily switch SELinux to permissive mode
sudo setenforce 0
</syntaxhighlight>
After disabling SELinux, the GUI should load correctly and SIP diagrams should render.
==== Related Information ====
The `mscgen` tool is used by the VoIPmonitor GUI to convert SIP message sequence chart (MSC) data into SVG graphics for display in the browser. When SELinux is in enforcing mode, it blocks this execution by default because the standard SELinux policies do not include rules for allowing mscgen. Creating a custom policy module via `audit2allow` is the secure and recommended approach to resolve this while maintaining SELinux protection.
=== 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:
<syntaxhighlight lang="ini">
SELINUX=disabled
</syntaxhighlight>
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.
=== Updating TShark for CVE Security Fixes ===
The VoIPmonitor GUI includes a bundled `tshark` binary (version 3.6.2-2) used by the SIP History feature for packet decoding. If security scanners report vulnerabilities for this bundled tshark version, you can manually update the tshark binary to address CVEs.
==== Background ====
The GUI relies on the tshark binary for SIP History functionality. Security scanners may flag the bundled tshark version as having CVEs when analyzing the GUI installation.
==== Manual TShark Update Procedure ====
To update tshark to address CVEs, follow these steps:
<syntaxhighlight lang="bash">
# 1. Download the updated tshark binary
wget -O tshark-4.4.6-x86_64.gz [DOWNLOAD_URL_FROM_SUPPORT]
# 2. Navigate to the GUI bin directory
# Default locations:
# Debian/Ubuntu: /var/www/voipmonitor/bin/
# CentOS/RHEL: /var/www/html/voipmonitor/bin/
cd /var/www/voipmonitor/bin/
# 3. Backup the existing tshark binary
sudo cp tshark tshark.backup
# 4. Extract the new tshark binary
zcat /path/to/downloaded/tshark-4.4.6-x86_64.gz | sudo tee tshark > /dev/null
# 5. Set executable permissions
sudo chmod +x tshark
# 6. Set ownership to web server user
# Debian/Ubuntu:
sudo chown www-data:www-data tshark
# CentOS/RHEL:
sudo chown apache:apache tshark
# Nginx:
sudo chown nginx:nginx tshark
# 7. Verify the new version
./tshark --version
</syntaxhighlight>
{{Warning|Obtain the correct download URL from VoIPmonitor support. The compressed tshark binary should be downloaded from an official source provided by VoIPmonitor support.}}
==== Future Automation ====
Future GUI versions will include an automated mechanism for updating the bundled tshark binary to address security vulnerabilities without manual intervention.
==== Verification ====
After updating, verify that SIP History functionality continues to work correctly:
# Navigate to the GUI CDR view
# Click on any call with SIP History data
# Ensure SIP packets display correctly without errors
=== 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.
=== Server Side Error - Forbidden: ionCube PHP Version Incompatibility ===
When clicking the <code>get/update license key</code> button in the GUI, you may receive a "Server side error - Forbidden" pop-up message. This error typically occurs when there is a PHP version incompatibility with ionCube Loader, which is required by the VoIPmonitor GUI.
==== Symptoms ====
* "Server side error - Forbidden" message appears when activating a license token
* License activation fails without providing specific error details in the GUI
* The error occurs after clicking "get/update license key" in Settings > License
==== Root Cause ====
The VoIPmonitor GUI uses ionCube Loader to protect its PHP code. Each GUI version is built for specific PHP versions, and ionCube Loader only supports the PHP versions it was compiled for.
For example:
* GUI versions before v26.37 require PHP 8.2 or earlier
* GUI v26.37 and later versions support PHP 8.3
* If you have PHP 8.3 but an older GUI (pre-v26.37), ionCube will fail to load
==== Diagnosis ====
Check your web server error logs for ionCube-related errors:
<syntaxhighlight lang="bash">
# Check Apache error log
tail -f /var/log/apache2/error.log
# Or for Nginx with PHP-FPM
tail -f /var/log/php8.3-fpm.log
# or
tail -f /var/log/nginx/error.log
</syntaxhighlight>
Look for error messages similar to:
<code>The file /var/www/voipmonitor/php/gui.php requires the ionCube PHP Loader ioncube_loader_lin_8.3.so to be installed by the server administrator.</code>
Or:
<code>Failed loading /usr/lib/php/20230831/ioncube_loader_lin_8.2.so: /usr/lib/php/20230831/ioncube_loader_lin_8.2.so: undefined symbol: zval_useable</code>
==== Solution: Match PHP Version to GUI Version ====
You have two options to resolve this issue:
===== Option A: Downgrade PHP Version (Recommended for Older GUI) =====
If you are using an older GUI version (before v26.37) and have PHP 8.3 installed, downgrade to PHP 8.2:
<syntaxhighlight lang="bash">
# On Debian/Ubuntu with PHP 8.3 installed
sudo apt-get update
sudo apt-get install php8.2 php8.2-cli php8.2-fpm php8.2-mysql php8.2-gd php8.2-zip php8.2-xml php8.2-mbstring php8.2-curl
# Disable PHP 8.3 and enable PHP 8.2
sudo a2dismod php8.3
sudo a2enmod php8.2
# Update PHP-FPM if using it
sudo systemctl disable php8.3-fpm
sudo systemctl enable php8.2-fpm
# Restart web server
sudo systemctl restart apache2  # or php8.2-fpm if using FPM
</syntaxhighlight>
===== Option B: Upgrade GUI to Match PHP Version =====
If you want to keep PHP 8.3, upgrade to GUI v26.37 or later:
<syntaxhighlight lang="bash">
# Download the latest GUI version supporting PHP 8.3
cd /tmp
wget https://download.voipmonitor.org/sniffer-develop/voipmonitor-gui-2025.12.0-SVN.XX.tar.gz
# Backup current GUI installation
sudo cp -r /var/www/voipmonitor /var/www/voipmonitor.backup
# Extract and install
sudo tar -xzf voipmonitor-gui-2025.12.0-SVN.XX.tar.gz -C /var/www/
sudo mv /var/www/voipmonitor-gui* /var/www/voipmonitor
# Restore configuration
sudo cp /var/www/voipmonitor.backup/php/configuration.php /var/www/voipmonitor/php/configuration.php
# Set permissions
sudo chown -R www-data:www-data /var/www/voipmonitor
</syntaxhighlight>
{{Tip|Check the latest GUI version at https://github.com/voipmonitor/sniffer-gui/releases to confirm PHP 8.3 support.}}
==== Verification ====
After changing the PHP version or upgrading the GUI:
1. Restart the web server:
<syntaxhighlight lang="bash">
sudo systemctl restart apache2  # or php8.2-fpm/php8.3-fpm
</syntaxhighlight>
2. Verify PHP version:
<syntaxhighlight lang="bash">
php -v
</syntaxhighlight>
3. Check web server error logs for any remaining ionCube errors
4. Navigate to Settings > License in the GUI and click <code>get/update license key</code>
The license activation should now work without the "Server side error - Forbidden" message.
==== Reference ====
* For ionCube loader information, see https://downloads.ioncube.com/loader_downloads
* PHP version compatibility information is documented in the GUI release notes
== 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 Swap Memory Warning (Safe to Ignore) ==
When logging into the VoIPmonitor GUI, you may encounter a MySQL error or warning related to swap memory usage. This warning indicates that the MySQL/MariaDB database process is using some swap space.
=== When to Ignore This Warning ===
This warning '''can be safely ignored''' if the amount of swap memory used by the database is small (typically '''less than 50 MB''').
{{Tip|Small amounts of swap usage (under 50 MB) by MySQL are normal and do not indicate a problem. The warning is informational only.}}
=== When to Take Action ===
You should investigate further if:
* Swap usage grows significantly larger than 50 MB (e.g., several hundred MB or GB)
* The warning is accompanied by performance issues or slow GUI responses
* System memory is consistently exhausted
* Multiple MySQL processes show high swap usage
{{Warning|1=High swap usage (significantly above 50 MB) can indicate a performance issue. Monitor the system and investigate memory usage trends if the warning persists.}}
=== Checking Swap Usage ===
To verify how much swap MySQL is actually using:
<syntaxhighlight lang="bash">
# Check overall system swap usage
free -m
# Check swap usage per process (MySQL)
# Find MySQL process ID
pidof mysqld
# Check specific process swap usage
sudo cat /proc/$(pidof mysqld)/smaps | grep -i swap
# Monitor swap usage in real-time
watch -n 5 'free -m && echo "---" && sudo cat /proc/$(pidof mysqld)/smaps | grep -i swap'
</syntaxhighlight>
=== Understanding the Warning ===
MySQL may use swap space under the following circumstances:
* Normal operation: Small, temporary swap usage during memory allocation
* InnoDB buffer pool adjustment: MySQL adjusts memory usage dynamically
* Background processes: Maintenance and cleanup operations may temporarily use swap
These scenarios are typically harmless when swap usage remains below the 50 MB threshold.
=== See Also ===
* [[Swap|Swap Configuration and Swappiness Tuning]]
* [[#GUI Queries Time Out (Slow Dashboard or CDR Performance)|MySQL Performance Tuning]]
== 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: Database in Read-Only Mode (innodb_force_recovery Already Set) ===
If the MariaDB/MySQL database is running but in a read-only state, this may be because <code>innodb_force_recovery</code> is already set in the MySQL configuration. This parameter deliberately puts the database into read-only recovery mode after corruption recovery. Once corruption is resolved, you must remove this setting to return the database to normal operation.
'''When to use this solution:'''
* MySQL/MariaDB service is running and accessible
* Database is in read-only mode (writes fail, but reads work)
* <code>innodb_force_recovery</code> line exists in configuration file (values 1-6)
* You have already completed corruption recovery and no longer need read-only mode
* You want to restore normal write access to the database
==== Step 1: Check for innodb_force_recovery Setting ====
Check if <code>innodb_force_recovery</code> is enabled in the MySQL configuration.
<syntaxhighlight lang="bash">
# Check MySQL configuration for innodb_force_recovery
grep -i "innodb_force_recovery" /etc/my.cnf
# or
grep -i "innodb_force_recovery" /etc/mysql/my.cnf
</syntaxhighlight>
If you see a line like <code>innodb_force_recovery=4</code> (or values 1-6), this is causing the read-only state. Note the value for reference.
==== Step 2: Comment Out the innodb_force_recovery Line ====
Edit the MySQL configuration file and comment out or remove the <code>innodb_force_recovery</code> line.
<syntaxhighlight lang="bash">
# Edit the MySQL configuration file
sudo nano /etc/my.cnf
# or
sudo nano /etc/mysql/my.cnf
</syntaxhighlight>
Find the line in the <code>[mysqld]</code> section:
<syntaxhighlight lang="ini">
[mysqld]
# innodb_force_recovery=4  <-- Comment out this line by adding # at the beginning
</syntaxhighlight>
'''Important:''' You must completely remove the parameter. Setting it to zero (<code>innodb_force_recovery=0</code>) is equivalent to the default, but commenting it out is clearer.
Alternatively, you can delete the line entirely.
==== Step 3: Restart MySQL/MariaDB Service ====
Restart the database service to apply the configuration change.
<syntaxhighlight lang="bash">
# Restart MySQL/MariaDB service
systemctl restart mysql
# or
systemctl restart mariadb
# Verify the service is running
systemctl status mysql
# or
systemctl status mariadb
</syntaxhighlight>
==== Step 4: Verify Write Access Works ====
Test that the database is now in read-write mode.
<syntaxhighlight lang="bash">
# Test write access from MySQL console
mysql -u root -p voipmonitor -e "INSERT INTO cdr_test (test_column) VALUES ('TEST');"
# Clean up test record
mysql -u root -p voipmonitor -e "DROP TABLE IF EXISTS cdr_test;"
</syntaxhighlight>
If the INSERT command succeeds without errors, the database is now in read-write mode. You should also verify that VoIPmonitor can write to the database normally by checking the sensor logs.
<syntaxhighlight lang="bash">
# Check sensor logs for database write activity
journalctl -u voipmonitor -f
</syntaxhighlight>
=== 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
mysqlcheck -u root -p --auto-repair voipmonitor
</syntaxhighlight>
</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.
'''Method 2: Drop and recreate specific table'''
 
'''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">
<syntaxhighlight lang="sql">
REPAIR TABLE cdr, cdr_next_partition, cdr_partition_202501, sip, message;
-- Backup structure first
</syntaxhighlight>
SHOW CREATE TABLE problematic_table;
 
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">
-- Drop and let sensor recreate
# Check table sizes
DROP TABLE problematic_table;
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;"
-- Restart sensor: systemctl restart voipmonitor
</syntaxhighlight>
</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.
'''Method 3: InnoDB force recovery'''
 
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">
<syntaxhighlight lang="ini">
[general]
# Add to my.cnf [mysqld] section:
# Automatically delete old data
innodb_force_recovery = 1
cleandatabase = 90
# Restart MySQL, export data, remove option, reimport
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
 
=== Solution: Drop and Recreate Individual Tables (Missing .ibd Files After OS Migration) ===
 
If you have migrated your server operating system (e.g., from CentOS 7 to Rocky 8 or similar OS upgrades) and encounter SQL error messages indicating missing .ibd files for specific tables when accessing the VoIPmonitor GUI, this indicates that InnoDB tablespace files for those tables are missing or incompatible.
 
This commonly happens after OS migrations when raw database files (.ibd) were copied between systems with different MySQL/MariaDB versions.
 
'''Symptoms:'''
* SQL error when logging into the VoIPmonitor webpage
* Error message mentions missing .ibd file for specific tables
* Example error: <code>Table 'table_name' doesn't exist in engine</code>
* Error occurs for specific tables (not the entire database)
 
'''Important Considerations:'''
* Dropping a table will permanently delete all data in that table
* For CDR tables like <code>cdr</code>, this represents permanent loss of call records
* GUI configuration tables (like <code>sensors</code>, <code>users</code>) will be recreated empty by the VoIPmonitor sensor
* After recreating tables, you may need to reconfigure items in the GUI
 
==== Step 1: Identify Affected Tables ====
 
Check the SQL error message(s) displayed in the GUI or MySQL logs for the specific table names affected.
 
<syntaxhighlight lang="bash">
# Check MySQL error logs for missing table errors
tail -100 /var/log/mysql/error.log | grep "errno: 2"
# or
tail -100 /var/log/mariadb/mariadb.log | grep "doesn't exist in engine"
</syntaxhighlight>
 
The error message typically includes the table name(s) and often provides the CREATE TABLE statement.
 
==== Step 2: Access the MySQL Database ====
 
Connect to MySQL/MariaDB:
 
<syntaxhighlight lang="bash">
mysql -u root -p voipmonitor
</syntaxhighlight>
 
Replace <code>voipmonitor</code> with your database name if using a custom name.
 
==== Step 3: Drop the Corrupted Table ====
 
For each problematic table mentioned in the error message, run the DROP TABLE command:
 
<syntaxhighlight lang="sql">
DROP TABLE IF EXISTS table_name;
</syntaxhighlight>
 
Example:
<syntaxhighlight lang="sql">
DROP TABLE IF EXISTS cdr_partition_20250103_12;
DROP TABLE IF EXISTS sensors_cache;
</syntaxhighlight>
 
==== Step 4: Recreate the Table ====
 
Recreate the table using the CREATE TABLE command provided in the SQL error message. The error message typically includes a complete CREATE TABLE statement that you can copy and execute.
 
<syntaxhighlight lang="sql">
CREATE TABLE cdr_partition_20250103_12 (
  -- Table structure from error message
) ENGINE=InnoDB;
</syntaxhighlight>
 
==== Alternative: Automatic Recreation via GUI ====
 
For many GUI-related tables (configuration tables, user tables, sensor settings), the VoIPmonitor sensor can automatically recreate missing tables. Simply:
 
# Log out of the VoIPmonitor GUI
# Log back into the VoIPmonitor GUI
 
The sensor will detect missing tables during the login process and recreate them with default schema values.
 
==== Step 5: Verify System Functionality ====
 
After dropping and recreating the tables, verify that the system is operating correctly:
 
# Access the VoIPmonitor web GUI and log in
# Check that sensor status is green in the GUI
# Confirm that new calls are being captured (monitor syslog/journalctl)
# Verify GUI functionality (no missing tables errors)
 
==== Example Complete Workflow ====
 
<syntaxhighlight lang="bash">
# 1. Check MySQL error logs
tail -100 /var/log/mysql/error.log
 
# Example error output:
# InnoDB: Can't open file ./voipmonitor/sensors_cache.ibd'
# MySQL Error: Table 'voipmonitor.sensors_cache' doesn't exist in the engine
 
# 2. Connect to MySQL
mysql -u root -p voipmonitor
 
# 3. Drop the corrupted table
DROP TABLE IF EXISTS sensors_cache;
 
# 4. Recreate the table using CREATE TABLE from error message
# Copy the CREATE TABLE statement from the error message
CREATE TABLE sensors_cache (
    -- ... table structure from error ...
) ENGINE=InnoDB;
 
# 5. Exit MySQL
EXIT;
 
# 6. Access the GUI and log in
# If the table was a GUI configuration table, the sensor may recreate it automatically
</syntaxhighlight>
 
=== 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 Individual Tables (Simplest for missing .ibd files after OS migration):'''
* MySQL/MariaDB service is running and accessible
* SQL error indicates missing .ibd files for specific tables after OS migration
* Error message includes CREATE TABLE statement
* You want to restore specific tables without dropping the entire database
* CDR data in affected tables is acceptable to lose or tables can be auto-recreated
 
This method drops corrupted individual tables and recreates them. See the <code>Solution: Drop and Recreate Individual Tables</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>
</syntaxhighlight>


Replace the database name <code>voipmonitor</code> if you are using a custom database name in your configuration.
{{Warning|After using innodb_force_recovery, remove the option before resuming normal operations. The database is read-only while this option is set.}}
 
==== 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.
'''Method 4: PCAP restore'''


If PCAPs are preserved, drop database and let sensor reindex:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Start the primary sensor (or server sensor in client/server mode)
# Edit voipmonitor.conf
systemctl start voipmonitor
reindex_all = yes # (temporary)
 
# 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
systemctl restart voipmonitor
# Wait for reindexing to complete, then remove reindex_all
</syntaxhighlight>
</syntaxhighlight>


==== Advanced: Preserving GUI Configuration Before Dropping ====
See [[Database_troubleshooting]] for detailed recovery procedures.
 
If you wish to keep your GUI settings (users, sensors, alerts, dashboards) before proceeding with the drop and recreate method, you must first back up the GUI configuration using the <code>innodb_force_recovery</code> parameter to force the database into read-only recovery mode.
 
'''Use this method when:'''
* MySQL/MariaDB is running but the voipmonitor database is corrupted
* You need to preserve GUI configuration (users, sensors, settings)
* You are willing to lose all CDR data
 
{{Warning|1=If MySQL fails to start due to InnoDB assertion failures, see the [[#Solution: Using innodb_force_recovery (Recommended for Filesystem Corruption and InnoDB Assertion Failures)|innodb_force_recovery for MySQL startup failures]] section below.}}
 
===== Step A: Enable innodb_force_recovery =====
 
Temporarily add the recovery parameter to MySQL's configuration to start it in read-only mode.
 
<syntaxhighlight lang="bash">
# Edit MySQL configuration
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.
 
===== Step B: Restart MySQL and Back Up GUI Configuration =====
 
<syntaxhighlight lang="bash">
# Restart MySQL to apply the change
systemctl restart mysql
# or
systemctl restart mariadb
</syntaxhighlight>
 
With MySQL in recovery mode, back up the GUI configuration.
 
<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 C: Disable innodb_force_recovery and Drop Database =====
=== MySQL 8.0 Issues ===
 
Remove the recovery parameter and proceed with the drop and recreate procedure.
 
Edit MySQL configuration and comment out the recovery line:
 
<syntaxhighlight lang="ini">
[mysqld]
# innodb_force_recovery=6
</syntaxhighlight>
 
Restart MySQL and drop the corrupted database:
 
<syntaxhighlight lang="bash">
# Restart MySQL
systemctl restart mysql
 
# Drop the corrupted database
mysql -u root -p
</syntaxhighlight>


'''SYSTEM_USER privilege error:'''
<syntaxhighlight lang="sql">
<syntaxhighlight lang="sql">
DROP DATABASE IF EXISTS voipmonitor;
GRANT SYSTEM_USER ON *.* TO 'voipmonitor'@'localhost';
EXIT;
GRANT ALL PRIVILEGES ON *.* TO 'voipmonitor'@'localhost' WITH GRANT OPTION;
</syntaxhighlight>
 
===== Step D: Recreate Database and Restore GUI Configuration =====
 
Restart the sensor to create a fresh database, then restore the GUI configuration.
 
<syntaxhighlight lang="bash">
# Start the sensor to create the database
systemctl start voipmonitor
 
# Wait for the sensor to create the database tables
# Monitor logs: journalctl -u voipmonitor -f
 
# Once the database is created, restore GUI configuration
cd /var/www/html
php php/run.php restoreGuiTables -t config -f /root/backup.zip
</syntaxhighlight>
 
Your GUI configuration (users, sensors, capture rules, alerts, dashboards) will be restored. See the [[Backing_Up_GUI_Configuration#IMPORTANT: What IS and IS NOT Transferred|Backing Up GUI Configuration]] page for details on what is and is not transferred during restore.
 
[[#Solution: Using innodb_force_recovery (Recommended for Filesystem Corruption and InnoDB Assertion Failures)|Alternative innodb_force_recovery method]]: For cases where MySQL fails to start due to InnoDB assertion failures or filesystem corruption, see the section below which covers a different recovery approach.
 
=== 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:
 
<syntaxhighlight lang="text">
[Note] A temporary password is generated for root@localhost: <random password here>
</syntaxhighlight>
 
'''Copy this temporary password''' - you will need it to log in and set a new permanent password.
 
===== Setting a New Permanent Root Password =====
 
With the temporary password, log in and set a new password:
 
<syntaxhighlight lang="bash">
# Log in to MySQL using the temporary password
mysql -u root -p
# When prompted, paste the temporary password from the log file
</syntaxhighlight>
 
In the MySQL console, set a new password:
 
<syntaxhighlight lang="sql">
-- Set new root password
ALTER USER 'root'@'localhost' IDENTIFIED BY 'NewStrongPassword123!';
 
-- Use mysql_native_password authentication (required by VoIPmonitor)
ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY 'NewStrongPassword123!';
 
FLUSH PRIVILEGES;
FLUSH PRIVILEGES;
EXIT;
</syntaxhighlight>


Replace <code>NewStrongPassword123!</code> with your own strong password.
-- Also set:
 
SET GLOBAL log_bin_trust_function_creators = 1;
===== Creating MySQL Users for VoIPmonitor =====
 
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.
 
<syntaxhighlight lang="bash">
# 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:
 
<syntaxhighlight lang="sql">
-- Create user for VoIPmonitor GUI
CREATE USER 'voipmonitor'@'localhost' IDENTIFIED WITH mysql_native_password BY 'YourGUIStrongPassword';
 
-- 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>
</syntaxhighlight>


Update your VoIPmonitor configuration files (<code>/etc/voipmonitor.conf</code> for the sniffer and GUI configuration) with these MySQL credentials.
'''MySQL 8.0.42 crashes:'''
 
==== 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:
{{Warning|MySQL 8.0.42 has known bugs causing VoIPmonitor crashes. Upgrade to 8.0.43 or later.}}
 
<syntaxhighlight lang="ini">
[mysqld]
# innodb_force_recovery=6  <-- Comment out or remove this line
</syntaxhighlight>
 
Then start MySQL:


<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
systemctl start mysql
mysql --version
# or
# If 8.0.42:
systemctl start mariadb
sudo apt install --only-upgrade mysql-server-8.0  # Debian/Ubuntu
 
sudo dnf update mysql-server                      # RHEL
# Verify MySQL is running
systemctl status mysql
</syntaxhighlight>
</syntaxhighlight>


MySQL should now be able to start with a fresh, empty database.
=== Managed Database: Primary Key Error ===
 
==== Step 7: Create VoIPmonitor Database ====


Create a new database for VoIPmonitor:
For DigitalOcean, AWS RDS, Google Cloud SQL:
 
<syntaxhighlight lang="bash">
mysql -u root -p
</syntaxhighlight>
 
Run the following SQL commands:


<syntaxhighlight lang="sql">
<syntaxhighlight lang="sql">
CREATE DATABASE voipmonitor;
-- Disable in managed DB console or parameter group:
CREATE USER 'voipmonitor'@'localhost' IDENTIFIED BY 'your_password_here';
sql_require_primary_key = OFF
GRANT ALL PRIVILEGES ON voipmonitor.* TO 'voipmonitor'@'localhost';
FLUSH PRIVILEGES;
EXIT;
</syntaxhighlight>
</syntaxhighlight>


==== Step 8: Restore GUI Configuration ====
== GUI Upgrade Issues ==
 
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 ====
=== Cannot Login After Upgrade ===
 
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
! Meaning
|-
| 1
| (SRV_FORCE_IGNORE_CORRUPT) Runs the server even if it detects a corrupt page
|-
| 2
| (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.
 
=== 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:


'''Reset password via database:'''
<syntaxhighlight lang="sql">
<syntaxhighlight lang="sql">
CREATE DATABASE voipmonitor;
UPDATE users SET password = MD5('newpassword') WHERE username = 'admin';
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>
</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.
'''Redis session issue (login loop):'''
 
==== Step 7: Monitor the Restore Process ====
 
Monitor the restore progress:
 
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Monitor sniffer output for progress
redis-cli FLUSHALL
journalctl -u voipmonitor -f
systemctl restart php-fpm
 
# Alternatively, check the database for new CDR records
mysql -u root -p voipmonitor -e "SELECT COUNT(*) FROM cdr;"
</syntaxhighlight>
</syntaxhighlight>


==== Step 8: Restart Normal Service ====
=== VM Binary Error ===
 
Once the restore is complete, restart the sniffer in normal operation mode:


<syntaxhighlight lang="bash">
<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
cd /var/www/html
 
php php/run.php upgrade -f
# 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>
</syntaxhighlight>


=== Verifying the Fix ===
=== Invalid Compressed Data ===
 
Test that the binaries can be executed by the web server user:


Usually caused by incorrect web root ownership:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# For Debian/Ubuntu (www-data)
chown -R www-data:www-data /var/www/html # Debian/Ubuntu
su - www-data -s /bin/bash -c "/var/www/html/bin/sox-x86_64 --version"
chown -R apache:apache /var/www/html       # RHEL/CentOS
# 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.
=== Unable to Remove Old Files ===
 
=== Troubleshooting Symlinks ===
 
Sometimes the `bin` directory contains symlinks to other locations. Check both the symlink and its target:


<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Check if files are symlinks and their targets
# Fix tshark ownership
ls -lah bin/
chown www-data:www-data /var/www/html/bin/tshark*


# If a symlink cannot be accessed, check permissions on the target
# Retry upgrade from GUI
# 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>
</syntaxhighlight>


=== Reproducing the Error ===
=== Upgrade Not Visible ===
 
To verify that missing execute permissions cause this error, you can temporarily remove execute permissions:


Check internet connectivity from GUI server:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Remove execute permissions (reproduces the error)
curl -I https://www.voipmonitor.org
chmod -x bin/sox-x86_64
ping www.voipmonitor.org
 
# Test the GUI - should show "incorrect ownership" error
 
# Restore execute permissions
chmod +x bin/sox-x86_64
</syntaxhighlight>
</syntaxhighlight>


=== Common Binaries in bin/ Directory ===
== Permission Issues ==
 
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 ====
=== Incorrect Ownership Error ===
 
Determine which user account runs your web server process:


Often caused by missing execute permissions on binaries:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Debian/Ubuntu
# Fix bin directory
ps aux | grep -E 'apache2|nginx' | grep -v grep
chmod +x /var/www/html/bin/*


# CentOS/RHEL
# Verify
ps aux | grep -E 'httpd|nginx' | grep -v grep
ls -la /var/www/html/bin/
</syntaxhighlight>
</syntaxhighlight>


Common web server users:
=== NAS Spool Permission Denied ===
* 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">
<syntaxhighlight lang="bash">
# Grant read/write/execute access to web server user
# Use ACLs (recommended)
# Debian/Ubuntu
setfacl -R -m u:www-data:rwx /path/to/nas/spool
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 ====
# CRITICAL: Set on ALL parent directories too
setfacl -m u:www-data:rx /NAS
setfacl -m u:www-data:rx /NAS/voipmonitor


If the NAS is mounted at a path like `/NAS/voipmonitor/spool`, you must ensure the web server user can traverse all parent directories:
# Verify
 
<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
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>
</syntaxhighlight>


If the command succeeds and lists files without errors, permissions are correct.
=== SELinux Blocking mscgen (SIP Call Flow Diagrams) ===
 
==== Step 6: Verify NAS Mount Permissions ====


Check that the NAS mount itself has appropriate permissions in `/etc/fstab` or your mount command:
If SIP call flow diagram shows "convert msc to svg (mscgen): unknown error":


<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# View current mount options
# Check SELinux denials
mount | grep /path/to/nas/spool
ausearch -m avc -ts recent | grep mscgen


# Check /etc/fstab for mount configuration
# Create policy module
grep /path/to/nas/spool /etc/fstab
grep mscgen /var/log/audit/audit.log | audit2allow -M mscgen_local
semodule -i mscgen_local.pp
</syntaxhighlight>
</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.
== IonCube and PHP Issues ==
 
=== 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 ==
=== Temp Directory Not Writable ===
 
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">
<syntaxhighlight lang="bash">
# Debian/Ubuntu
# Check and fix /tmp permissions
sudo apt update && sudo apt upgrade -y
ls -ld /tmp
 
chmod 1777 /tmp
# 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 ====
# Check SELinux
 
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
getenforce
# If Enforcing, try: setenforce 0


# Common values: Enforcing (active), Permissive (logging only), Disabled
# Check systemd PrivateTmp
 
# 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
systemctl show httpd | grep PrivateTmp
# or
# If true, create override:
systemctl show apache2 | grep PrivateTmp
# /etc/systemd/system/httpd.service.d/privatetmp.conf
 
# [Service]
# For PHP-FPM
# PrivateTmp=false
systemctl show php-fpm | grep PrivateTmp
</syntaxhighlight>
</syntaxhighlight>


If PrivateTmp is enabled (value=1), disable it in the service file:
=== PHP CLI vs Web Server Mismatch ===


<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Create override directory if it doesn't exist
# Test as web server user
sudo mkdir -p /etc/systemd/system/httpd.service.d
sudo -u www-data php -r 'echo extension_loaded("ionCube Loader")?"yes":"no";'


# Create override file
# Compare configs
sudo nano /etc/systemd/system/httpd.service.d/privatetmp.conf
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
</syntaxhighlight>
</syntaxhighlight>


Add the following content:
=== License Activation: Server Side Error - Forbidden ===


<syntaxhighlight lang="ini">
This indicates ionCube PHP version incompatibility:
[Service]
PrivateTmp=false
</syntaxhighlight>


Then reload and restart:
{| 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">
# Reload systemd and restart the service
# Check Apache error log
sudo systemctl daemon-reload
tail -50 /var/log/apache2/error.log | grep -i ioncube
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">
# Solution: Either upgrade GUI to v26.37+ or downgrade PHP to 8.2
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:
== Other Issues ==
* <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
=== Invalid Timezone (GUI Inaccessible) ===
sudo chmod 1777 /tmp
</syntaxhighlight>
 
'''Important:''' Clean up after troubleshooting:


<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
rm /var/www/html/info.php
# Edit directly
</syntaxhighlight>
nano /var/www/html/config/configuration.php


==== Step 5: Check open_basedir restrictions ====
# Find and fix:
define('TIMEZONE', 'UTC');  # Use valid timezone
define('SENSORS_TIMEZONE', 'UTC');


If the above steps don't resolve the issue, check if PHP's <code>open_basedir</code> is restricting access to the temp directory:
systemctl restart php-fpm
 
<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>
</syntaxhighlight>


Ensure the temp directory is included in the list, e.g.:
Valid timezones: <code>UTC</code>, <code>Europe/London</code>, <code>America/New_York</code>, <code>Europe/Berlin</code>, etc.
 
<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 ====
=== Faxes Not Displayed ===
 
To diagnose the issue, run the exact command the GUI uses as the web server user instead of root:


<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Test IonCube extension as the web server user
# Install libtiff-tools
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
apt-get install libtiff-tools    # Debian/Ubuntu
yum install libtiff-tools        # RHEL/CentOS


# For CentOS/RHEL systems, replace www-data with apache
# Verify
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
which tiff2pdf
</syntaxhighlight>
</syntaxhighlight>


If this command returns "no" but the same command as root returns "yes", there is a configuration difference between users.
=== File Attachment Blocked ===
 
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:


Files like .xlsx, .docx are blocked for security. Compress to .zip or .gz:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Check which configuration file CLI PHP uses
zip archive.zip your_file.xlsx
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>
</syntaxhighlight>


==== Verify zend_extension Directive Placement ====
=== RRD Graph Errors After Hardware Change ===
 
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">
<syntaxhighlight lang="bash">
# Check for IonCube in web server config
# Delete corrupted RRD files
grep -r "ioncube_loader" /etc/php/*/apache2/conf.d/
rm -rf /var/spool/voipmonitor/rrd/*
grep -r "ioncube_loader" /etc/php/*/fpm/conf.d/
# or for CentOS/RHEL
grep -r "ioncube_loader" /etc/php.d/


# Check CLI config
# Sensor will recreate them
grep -r "ioncube_loader" /etc/php/*/cli/conf.d/
systemctl restart voipmonitor
</syntaxhighlight>
</syntaxhighlight>


If the web server config is missing the <code>zend_extension = ioncube_loader_lin_*.so</code> line, add it in the appropriate directory:
=== /dev/shm Full (Session Logout Issues) ===


<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Example for PHP 8.1 on Debian/Ubuntu (Apache)
# Check usage
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
df -h /dev/shm


# Check how much space is used by session files
# Temporary increase
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
mount -o remount,size=1G /dev/shm


# Verify the new size
# Permanent: edit /etc/fstab
df -h /dev/shm
# tmpfs /dev/shm tmpfs defaults,size=1G 0 0
</syntaxhighlight>
</syntaxhighlight>


Adjust the size parameter (<code>size=1G</code>) based on your server's RAM and expected number of concurrent users.
=== Concurrent Calls Stats Error ===
 
==== Permanent Configuration (Persistent After Reboot) ====
 
To make the size increase permanent, edit the <code>/etc/fstab</code> file:


Usually caused by duplicate cron entries:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Edit /etc/fstab as root
# Check for duplicates
sudo nano /etc/fstab
grep "voipmonitor\|run.php" /etc/crontab
</syntaxhighlight>


Find the line for <code>/dev/shm</code>. It typically looks like this:
# Comment out duplicates, keep only one
 
<syntaxhighlight lang="text">
tmpfs /dev/shm tmpfs defaults 0 0
</syntaxhighlight>
</syntaxhighlight>


Modify it to include the size parameter:
=== TShark CVE Security Updates ===


<syntaxhighlight lang="text">
The bundled tshark may have known CVEs. To update:
tmpfs /dev/shm tmpfs defaults,size=1G 0 0
</syntaxhighlight>
 
Save the file and apply the changes without rebooting:


<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Remount all filesystems from /etc/fstab
cd /var/www/html/bin
mount -a


# Verify the new size
# Download updated binary from Wireshark
df -h /dev/shm
wget https://www.wireshark.org/download/automated/linux64/tshark
chmod +x tshark
chown www-data:www-data tshark
</syntaxhighlight>
</syntaxhighlight>


=== Prevention: Session Cleanup Configuration ===
=== Dashboard Edit Icon Grayed Out ===
 
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
 
 
== 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:
 
<syntaxhighlight lang="php">
define('TIMEZONE', 'InvalidTimezone123');
define('SENSORS_TIMEZONE', 'InvalidTimezone123');
</syntaxhighlight>
 
Change the values to a valid timezone identifier. Use a valid timezone string from the PHP timezone database:
 
<syntaxhighlight lang="php">
define('TIMEZONE', 'Europe/Lisbon');
define('SENSORS_TIMEZONE', 'Europe/Lisbon');
</syntaxhighlight>
 
''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">
# For PHP-FPM
sudo systemctl restart php-fpm
 
# Or for Apache with mod_php
sudo systemctl restart apache2
</syntaxhighlight>
 
==== Step 6: Verify GUI Access ====
 
Open your web browser and navigate to your VoIPmonitor GUI URL. The interface should now be accessible.
 
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.
 
=== Prevention ===
 
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:
 
* Do not use custom or made-up timezone names
* Do not use 3-letter abbreviations (e.g., "EST", "CST") - these are ambiguous and not recommended
* Use the "Region/City" format (e.g., "America/New_York") for unambiguous timezone specification
 
=== Related Information ===
 
* Timezone settings are stored in <code>/var/www/html/config/configuration.php</code>
* PHP requires valid timezone identifiers that match the IANA timezone database
* 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 ==
 
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.
 
=== Symptoms ===
 
* Accessing the 'Concurrent calls stats' section in the GUI results in a generic 'server-side error'
* The error may be accompanied by database-related error messages
* The issue occurs suddenly on pages that previously worked correctly
* Other GUI sections may work normally
 
=== Root Cause ===
 
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.
 
=== Solution: Identify and Remove Duplicate Cron Entries ===
 
==== Step 1: Check the System Crontab ====
 
Examine the system crontab file for duplicate entries:
 
<syntaxhighlight lang="bash">
# View the system crontab
sudo nano /etc/crontab
</syntaxhighlight>
 
Look for lines similar to:
 
<syntaxhighlight lang="text">
* * * * * root php /var/www/html/php/run.php cron
</syntaxhighlight>
 
If you see two (or more) identical or similar VoIPmonitor cron job entries, this is the cause of the issue.
 
==== Step 2: Comment Out Duplicate Entries ====
 
Comment out all but one of the duplicate cron job entries by adding a `#` at the beginning of the line:
 
<syntaxhighlight lang="bash">
# Example: Keep only one active entry
* * * * * root php /var/www/html/php/run.php cron
 
# Comment out duplicates
# * * * * * root php /var/www/html/php/run.php cron
</syntaxhighlight>
 
==== Step 3: Apply the Changes ====
 
Save the file and exit the editor. Reload the cron service to apply the changes:
 
<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
 
 
== 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.
 
 
 
== File Attachment Blocked (xlsx, docx, Other File Extensions) ==
 
If you attempt to attach a file (such as .xlsx, .docx, or other formats) and the file is blocked by the system, this is due to file extension filtering in VoIPmonitor GUI for security reasons.
 
=== Symptoms ===
 
* File attachment with certain extensions (.xlsx, .docx, etc.) is blocked during upload
* Upload process prevents the file from being sent
* Block occurs when attaching files to tickets or sending emails
 
=== Solution: Compress the File ===
 
The workaround is to compress the file into an archive format that is permitted by the system.
 
==== Step 1: Compress the File ===
 
Use an archive format such as .zip or .gz:
 
<syntaxhighlight lang="bash">
# Create a ZIP archive
zip archive.zip your_file.xlsx
 
# Or using tar and gzip
tar -czf archive.tar.gz your_file.xlsx
</syntaxhighlight>
 
==== Step 2: Attach the Compressed Archive ===
 
Upload the compressed archive (.zip or .gz) instead of the original file. The recipient can extract and use the file normally.
 
{{Note|This is a security feature to prevent the upload of potentially dangerous file types. Compressing files into archives is the standard workaround.}}
 
=== Related Information ===
 
* This restriction applies to various file types including spreadsheets, documents, and other office formats
* The compression method can use any standard archive format (.zip, .gz, .tar.gz, etc.)
* No configuration change is required to use this workaround
 
 
== NXDOMAIN Errors with Secure DNS (DNS-over-HTTPS/TLS) ==
 
If you receive NXDOMAIN errors for VoIPmonitor-related domains only when Secure DNS is enabled in your browser, this typically indicates an issue with the specific secure DNS provider rather than the actual domain resolution.
 
=== Symptoms ===
 
* NXDOMAIN errors occur only when Secure DNS (DoH/DoT) is enabled
* Standard DNS resolution works correctly
* Issue affects VoIPmonitor domains but may not affect other sites
 
=== Diagnostic Steps ===
 
1. Check which secure DNS provider is configured in your browser (Chrome: navigate to <code>chrome://settings/security</code> and look under "Use secure DNS")
 
2. Verify the issue occurs only with Secure DNS enabled by temporarily disabling it and confirming the domain resolves normally
 
3. Test standard DNS resolution from the command line to confirm the domain is valid:
<syntaxhighlight lang="bash">
nslookup www.voipmonitor.org
dig www.voipmonitor.org
</syntaxhighlight>
 
=== Solution ===
 
* Try switching to a different Secure DNS provider (e.g., Cloudflare 1.1.1.1, Google 8.8.8.8)
* Temporarily disable Secure DNS for VoIPmonitor access
* Contact your Secure DNS provider if the issue persists
 
== Database Tables Do Not Exist (Missing Required Tables) ==
 
If the VoIPmonitor sensor logs errors indicating that required database tables do not exist and the service fails to create them automatically on startup, follow this troubleshooting guide.
 
=== Optional Tables Requiring Configuration ===
 
Some VoIPmonitor database tables are optional and will not be created automatically unless explicitly enabled in the configuration.
 
Common optional tables include:
* <code>cdr_problems_by_comb</code> - Requires <code>cdr_problems_by_comb=yes</code> in <code>voipmonitor.conf</code>
 
If you see an error like <code>Table 'voipmonitor.cdr_problems_by_comb' doesn't exist</code>:
 
<syntaxhighlight lang="bash">
# Edit configuration
nano /etc/voipmonitor.conf
 
# Add:
cdr_problems_by_comb=yes
 
# Restart service
systemctl restart voipmonitor
</syntaxhighlight>
 
=== Step 1: Check Database Privileges ===
 
The MySQL/MariaDB user must have privileges to create and alter database schema:
 
<syntaxhighlight lang="sql">
-- Check privileges
SHOW GRANTS FOR 'voipmonitor'@'localhost';


-- Grant if needed
User lacks edit permission. Grant via '''User Management''' > edit user > enable "Edit Dashboard" permission.
GRANT ALL PRIVILEGES ON voipmonitor.* TO 'voipmonitor'@'localhost';
FLUSH PRIVILEGES;
</syntaxhighlight>
 
=== Step 2: Check disable_dbupgradecheck Configuration ===
 
If <code>disable_dbupgradecheck</code> is enabled, the sensor will skip automatic table creation:
 
<syntaxhighlight lang="ini">
# In voipmonitor.conf - ensure this is disabled:
disable_dbupgradecheck = no
</syntaxhighlight>
 
=== Step 3: Restart and Verify ===
 
<syntaxhighlight lang="bash">
systemctl restart voipmonitor
journalctl -u voipmonitor -f  # Watch for table creation messages
</syntaxhighlight>
 
== Managed Database: sql_require_primary_key Error ==
 
When using a managed MySQL database (DigitalOcean, AWS RDS, Google Cloud SQL), VoIPmonitor may fail to create tables with errors about missing primary keys.
 
=== Symptoms ===
 
* Error: <code>tables being created without primary keys</code>
* CDRs are not being saved
* Table creation fails on managed database platforms
 
=== Root Cause ===
 
Managed database platforms often enforce <code>sql_require_primary_key=ON</code> for replication compatibility. Some VoIPmonitor internal tables may not have primary keys defined.
 
=== Solution ===
 
Disable the primary key requirement in your managed database configuration panel:
 
<syntaxhighlight lang="sql">
-- In managed DB console or parameter group:
sql_require_primary_key = OFF
</syntaxhighlight>
 
After changing this setting, restart VoIPmonitor to retry table creation.
 
== MariaDB System Table Corruption After OS Upgrade ==
 
After upgrading the OS (e.g., Debian 11 to 13) and reinstalling VoIPmonitor, MariaDB may report errors about incorrect table definitions in the system <code>mysql</code> database.
 
=== Symptoms ===
 
* Errors referencing <code>mysql.column_stats</code> or other system tables
* VoIPmonitor fails to create routines due to insufficient user privileges
* Error: <code>Column count of mysql.proc is wrong</code>
 
=== Solution ===
 
Run MariaDB upgrade to fix system tables:
 
<syntaxhighlight lang="bash">
# Run the upgrade script
mysql_upgrade -u root -p
 
# Or for newer MariaDB versions
mariadb-upgrade -u root -p
 
# Restart MariaDB
systemctl restart mariadb
</syntaxhighlight>
 
If issues persist, you may need to reinstall MariaDB system tables:
 
<syntaxhighlight lang="bash">
# Backup first!
mysqldump -u root -p mysql > /tmp/mysql_backup.sql
 
# Reinstall system tables
mysql_install_db --user=mysql
</syntaxhighlight>
 
== VoIPmonitor Server Crashes After MySQL/MariaDB Upgrade ==
 
After a system upgrade that includes MySQL/MariaDB version change, VoIPmonitor may crash or become inaccessible.
 
=== Symptoms ===
 
* VoIPmonitor primary server crashes after system upgrade
* Sensors cannot connect
* Web GUI is unavailable
* Database connection errors in logs
* Frequent service crashes during high traffic
 
=== Common Causes ===
 
1. **Known buggy MySQL version** - '''MySQL 8.0.42 has known bugs''' that cause server crashes and database connection failures with high-traffic VoIPmonitor deployments
2. **Incompatible stored procedures** - MySQL/MariaDB upgrade changed routine syntax
3. **Authentication plugin change** - MySQL 8.0 uses caching_sha2_password by default
4. **System table corruption** - See MariaDB System Table Corruption section above
 
=== Solution ===
 
'''Step 1: Check MySQL version'''
 
<syntaxhighlight lang="bash">
mysql --version
</syntaxhighlight>
 
'''Step 2: If MySQL 8.0.42, upgrade to 8.0.43 or later'''
 
MySQL 8.0.42 contains bugs that cause instability with VoIPmonitor. Upgrade to 8.0.43+:
 
<syntaxhighlight lang="bash">
# Backup database first
mysqldump -u root -p --all-databases > /var/lib/mysql-backup.sql
 
# Debian/Ubuntu
sudo apt update
sudo apt install --only-upgrade mysql-server-8.0
 
# RHEL/CentOS/Rocky/AlmaLinux
sudo dnf update mysql-server
</syntaxhighlight>
 
'''Step 3: Standard troubleshooting (if not version 8.0.42)'''
 
<syntaxhighlight lang="bash">
# 1. Check MySQL/MariaDB status
systemctl status mysql
systemctl status mariadb
 
# 2. Check error logs
tail -100 /var/log/mysql/error.log
 
# 3. Run upgrade script
mysql_upgrade -u root -p
 
# 4. Restart services
systemctl restart mysql
systemctl restart voipmonitor
</syntaxhighlight>
 
'''Step 4: Monitor the system'''
 
<syntaxhighlight lang="bash">
# Check VoIPmonitor logs
journalctl -u voipmonitor -f
 
# Verify sensors can connect in GUI: Settings > Sensors
</syntaxhighlight>
 
{{Note|1=After any system upgrade that includes MySQL changes, always check the MySQL version first. Avoid MySQL 8.0.42 - use 8.0.43 or later.}}
 
== MySQL 8.0 SYSTEM_USER Privilege Error ==
 
VoIPmonitor sniffer fails to start or connect to the database with errors like <code>create routine store_001 failed</code> and <code>Access denied; you need the SYSTEM_USER privilege</code>.
 
=== Symptoms ===
 
* Error: <code>Access denied; you need (at least one of) the SYSTEM_USER privilege(s) for this operation</code>
* Occurs on MySQL 8.0 even with SUPER and ALL PRIVILEGES granted
* Stored procedure creation fails
 
=== Root Cause ===
 
MySQL 8.0 introduced stricter privilege requirements. The <code>SYSTEM_USER</code> privilege is needed for certain operations.
 
=== Solution ===
 
<syntaxhighlight lang="sql">
-- Grant SYSTEM_USER privilege
GRANT SYSTEM_USER ON *.* TO 'voipmonitor'@'localhost';
 
-- Or grant all required privileges
GRANT ALL PRIVILEGES ON *.* TO 'voipmonitor'@'localhost' WITH GRANT OPTION;
FLUSH PRIVILEGES;
</syntaxhighlight>
 
If the issue persists, check if the <code>log_bin_trust_function_creators</code> variable is set:
 
<syntaxhighlight lang="sql">
SET GLOBAL log_bin_trust_function_creators = 1;
</syntaxhighlight>
 
== GUI Error: Unknown Column in Field List ==
 
A 'Server side error' pop-up appears in the GUI with the message <code>Unknown column [table].[column] in 'field list'</code>.
 
=== Symptoms ===
 
* Server side error pop-up in GUI
* Error mentions unknown column in field list
* GUI functionality is partially broken
 
=== Root Cause ===
 
The database schema is out of sync with the GUI version. This typically happens after:
* GUI upgrade without database migration
* Manual database modifications
* Incomplete upgrade process
 
=== Solution ===
 
The simplest way to fix this error is to use the built-in table check/repair functionality:
 
<syntaxhighlight lang="bash">
# Method 1: Using ?check_tables=1 parameter (Fastest - Recommended)
# Add this parameter to your GUI URL and load the page
# Example: http://your-gui-ip/admin.php?check_tables=1
 
# Navigate to your VoIPmonitor GUI in a web browser
# Add ?check_tables=1 to the end of the URL in the address bar
# Press Enter and wait for the table check and repair process to complete
# Navigate back to the CDR section to verify the error is resolved
</syntaxhighlight>
 
{{Tip|This method works by triggering the GUI's automatic table checking and repair routine, which adds missing columns and updates the database schema to match the current GUI version.}}
 
If the above method does not resolve the issue, try the alternative methods below:
 
<syntaxhighlight lang="bash">
# Method 2: Through GUI (if accessible)
# Navigate to: Settings > System Configuration > Database > Check MySQL Schema
 
# Method 3: Via command line
cd /var/www/html
php php/run.php dbcheck
 
# Method 4: Restart sensor with schema check enabled
# Ensure disable_dbupgradecheck=no in voipmonitor.conf
systemctl restart voipmonitor
</syntaxhighlight>
 
If specific columns are missing, you may need to add them manually:
 
<syntaxhighlight lang="sql">
-- Example: Check table structure
DESCRIBE cdr;
 
-- Add missing column (example)
ALTER TABLE cdr ADD COLUMN missing_column_name VARCHAR(255);
</syntaxhighlight>


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


'''Summary:''' Comprehensive VoIPmonitor GUI troubleshooting guide covering: (1) HTTP 500 errors - start with client-side steps (different browser, incognito mode, clear cache, disable extensions) before server-side diagnosis; (2) No CDR for current day - check sensor status in Settings > Sensors; if UP, navigate to Tools > Generate Debug Log and share link with support; if Down, check sensor service status and logs with systemctl status voipmonitor and journalctl -u voipmonitor -n 500; common causes include database partition issues (SHOW PARTITIONS FROM cdr, add missing partition with ALTER TABLE cdr ADD PARTITION), timezone mismatch between GUI and database (Settings > System Configuration > National > Timezone), configuration issues (cdr = yes in voipmonitor.conf); (3) Single user access issues - check IP whitelist in User Management, use tcpdump for network diagnosis; (4) GUI Debug Mode - add ?debug=31415 to URL to see SQL queries in browser console; (5) Slow GUI/timeouts - tune MySQL innodb_buffer_pool_size (50-70% RAM), innodb_flush_log_at_trx_commit=2 for database; for Apache mod_fcgid web server timeouts ("server side error - check your http server error log. - connection to the web server was lost / interrupted"), increase FcgidIdleTimeout, FcgidProcessLifeTime, FcgidConnectTimeout, FcgidIOTimeout in httpd.conf/apache2.conf and restart Apache; (6) Known GUI Bugs - Dashboard edit icon grayed out due to missing edit permission; (7) GUI Upgrade Issues - Unable to log in after upgrade (reset user password via database UPDATE users SET password = MD5('newpassword')), Invalid compressed data (fix web root ownership), VM Binary error (php php/run.php upgrade -f), Upgrade not visible (check internet connectivity), unable to remove old files (fix tshark ownership), Browser cache (Ctrl+F5), Blank screen (remove /usr/share/pear/constants.php or disable SELinux); (8) TShark CVE security updates - bundled tshark version 3.6.2-2 may have CVEs, manually update by downloading new binary and replacing in GUI bin directory (/var/www/voipmonitor/bin/); (9) File attachment blocked (.xlsx, .docx, etc.) - compress file to .zip or .gz archive as workaround; (10) MySQL max_connections exhausted - increase to 500+; (11) MySQL swap memory warning on login - can safely ignore if less than 50 MB, only indicates performance issue if swap usage grows significantly larger (hundreds MB or GB); (12) Database corruption - five methods: table repair (mysqlcheck), drop/recreate individual tables (missing .ibd), drop/recreate database, innodb_force_recovery, PCAP restore; Database read-only mode - remove innodb_force_recovery from my.cnf; (13) RRD graph errors after hardware upgrade - delete corrupted RRD files; (14) Faxes not displayed - install libtiff-tools; (15) Permission errors - check bin/ directory execute permissions; (16) NAS spool permissions - setfacl for www-data on all parent directories; (17) SIP call flow diagram error - "convert msc to svg (mscgen): unknown error" caused by SELinux blocking mscgen binary; fix by checking audit logs (ausearch -m avc -ts recent | grep mscgen) and creating SELinux policy module (grep mscgen /var/log/audit/audit.log | audit2allow -M mscgen_local; semodule -i mscgen_local.pp); (18) IonCube/SELinux issues - disable SELinux or configure properly, check PHP CLI vs web server environment difference; Server side error - Forbidden during license activation - ionCube PHP version incompatibility; GUI uses ionCube Loader which requires specific PHP versions; GUI v26.37+ supports PHP 8.3, older GUI requires PHP 8.2 or earlier; check Apache error log (/var/log/apache2/error.log) for ionCube errors; solution: either downgrade PHP to 8.2 (older GUI) or upgrade GUI to v26.37+ (keep PHP 8.3); (19) /dev/shm capacity - increase size in /etc/fstab or reduce session lifetime; (20) Invalid timezone - edit /var/www/html/config/configuration.php directly; (21) Concurrent calls stats error - remove duplicate cron jobs; (22) MySQL general log for debugging; (23) Unknown column in field list error - add ?check_tables=1 to URL to trigger automatic schema repair (fastest method, e.g., http://your-gui/admin.php?check_tables=1), or use Settings > System Configuration > Database > Check MySQL Schema, or run php php/run.php dbcheck from /var/www/html.
'''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 current day, sensor status, Settings Sensors, Tools Generate Debug Log, database partitions, ALTER TABLE cdr ADD PARTITION, SHOW PARTITIONS, timezone mismatch, cdr yes, spooldir, GUI troubleshooting, browser cache, incognito mode, debug mode, ?debug=31415, innodb_buffer_pool_size, MySQL tuning, GUI timeout, tcpdump, IP whitelist, timezone error, savertp, RTP audio, max_connections, MySQL swap memory warning, 50 MB swap threshold, safe to ignore, swap usage check, pidof mysqld, database corruption, mysqlcheck, innodb_force_recovery, DROP DATABASE, PCAP restore, NAS permissions, setfacl, GUI upgrade, cannot log in after upgrade, password reset, Redis session storage, login loop after upgrade, tshark ownership, tshark CVE, tshark security update, bundled tshark, SIP History, CVE vulnerability, tshark binary update, tshark-4.4.6, file attachment blocked, upload blocked, file extension blocked, xlsx blocked, docx blocked, zip file, compressed archive, IonCube, SELinux, ionCube Loader, PHP version incompatibility, PHP 8.2, PHP 8.3, license activation forbidden, server side error forbidden, GUI v26.37, downgrade PHP, ioncube_loader_lin, duplicate cron, apilicensecheck.php, VM Binary, RRD errors, libtiff-tools, /dev/shm, configuration.php, MySQL 8.0.42, MySQL upgrade crash, server crashes after MySQL upgrade, mod_fcgid, FcgidTimeout, FcgidIdleTimeout, FcgidIOTimeout, FcgidProcessLifeTime, FcgidConnectTimeout, proxy_fcgi, Apache timeout, httpd timeout, server side error, web server error log, connection lost interrupted, mscgen, SIP call flow diagram, SIP sequence diagram, CDR SIP history, convert msc to svg, unknown error, audit2allow, SELinux audit log, AVC denial, mscgen_local.pp, semodule, ?check_tables=1, unknown column in field list, check tables, table check, database schema repair, database schema update
'''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:'''
* No CDR or dashboard data for current day - what are the first steps?
* How to check sensor status in VoIPmonitor GUI?
* What to do if sensor shows UP but no today's data?
* What to do if sensor shows Down status?
* How to generate debug log for support?
* Database partition missing today's data - how to fix?
* HTTP 500 error on GUI - what to try first?
* HTTP 500 error on GUI - what to try first?
* GUI shows blank screen after upgrade - what to check?
* No CDR or dashboard data for current day - how to diagnose?
* GUI queries timeout after 40-50 seconds - how to fix with MySQL tuning?
* How to enable GUI debug mode?
* One user cannot access GUI while others can - what to check?
* GUI queries timeout - how to tune MySQL?
* How to enable GUI debug mode to see SQL queries?
* GUI inaccessible after invalid timezone setting - how to recover?
* No audio playback in GUI but QoS visible - what's wrong?
* File attachment blocked (.xlsx, .docx, etc.) - how to upload?
* Security scan reports CVEs for bundled tshark - how to update tshark binary?
* MySQL Too many connections error - how to fix?
* MySQL swap memory warning on login - can I safely ignore?
* Database in read-only mode after recovery - how to exit?
* GUI upgrade fails with VM Binary error - what command to run?
* GUI upgrade fails with "Invalid compressed data" - what causes it?
* Database corrupted - which recovery method to use?
* Database corrupted - which recovery method to use?
* NAS spool permission denied for GUI - how to fix?
* Cannot login after GUI upgrade - how to reset password?
* Concurrent calls stats shows server error - what causes it?
* Permission errors with NAS spool - how to fix?
* Web portal inaccessible after GUI upgrade - what is the first step to fix?
* IonCube temp directory errors - what causes them?
* GUI intermittently shows "server side error - check your http server error log. - connection to the web server was lost / interrupted" - how to fix?
* GUI shows "Unknown column in field list" - how to fix?
* Apache mod_fcgid timeout errors causing GUI crashes - what settings to adjust?
* SIP call flow diagram shows error - how to fix SELinux blocking?
* Users cannot log in after GUI upgrade - how to fix?
* MySQL 8.0.42 causing crashes - what to do?
* How to reset user password in VoIPmonitor database?
* License activation fails with Forbidden error - what causes it?
* Login loop after upgrade with Redis sessions - what to do?
* How to use tcpdump to diagnose GUI access issues?
* What is the forced CLI upgrade command for GUI?
* How to find MySQL temporary password after mysqld --initialize?
* RRD graphs show errors after hardware upgrade - how to fix?
* Faxes cannot be displayed in GUI - what package is missing?
* GUI shows "Unknown column [table].[column] in 'field list'" error - how to fix?
* Where is the GUI bin directory located for tshark updates?
* How to manually update bundled tshark for CVE fixes?
* SIP call flow diagram shows "convert msc to svg (mscgen): unknown error" - how to fix?
* Dashboard edit icon is grayed out - why?
* VoIPmonitor crashes after MySQL upgrade - what version to avoid?
* MySQL 8.0.42 causing server crashes - how to fix?
* "Server side error - Forbidden" when activating license - what causes this?
* License token activation fails with server side error - how to fix?
* ionCube Loader errors in Apache log - how to resolve PHP version incompatibility?

Revision as of 16:51, 8 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:

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.

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=10201"