Re-install the GUI: Difference between revisions

Revision as of 11:30, 9 January 2026

This guide provides a step-by-step process for safely reinstalling the VoIPmonitor web GUI without losing your data or configuration.

When to Reinstall

A reinstallation overwrites GUI application files while preserving your data (CDRs, PCAPs) and configuration (config/configuration.php). Use this procedure when:

A GUI upgrade failed due to power loss, full disk, or other interruption
The GUI fails to load after a PHP version upgrade
Apache shows the default welcome page instead of VoIPmonitor
Suspected file corruption in the web directory

ℹ️ Note: This guide assumes you have a previously working GUI with all PHP dependencies (ionCube Loader) already installed.

Installation Steps

Step 1: Identify PHP Version

The GUI package must match your PHP major version:

php --version

Note the first two numbers (e.g., 8.1, 8.2, 7.4).

⚠️ Warning: CLI PHP version may differ from web server PHP version. Create phpinfo(); test file to verify web server version if in doubt.

Step 2: Backup Current GUI

sudo cp -a /var/www/html /var/www/html-backup-$(date +%F)

⚠️ Warning: Always keep a separate backup of configuration.php and key.php. If these become empty during installation, the GUI will fail with "empty path" errors.

Step 3: Download and Install

mkdir /tmp/voipmonitor-gui-install
cd /tmp/voipmonitor-gui-install

# Replace phpver=81 with your version (82, 81, 74, etc.)
wget "https://www.voipmonitor.org/download-gui?version=latest&major=5&allowed&phpver=81" -O gui.tar.gz

# Extract and install
tar xzf gui.tar.gz
cd voipmonitor-gui-*/scripts/
sudo bash install-gui.sh ../../gui.tar.gz

Press Enter to confirm the default installation path. The script preserves your configuration.php and sets permissions automatically.

💡 Tip: Validate package before install: tar -tvf gui.tar.gz | grep "vm-" should show vm-i686 and vm-x86_64 binaries.

Alternative: Manual Installation

If the automated script fails:

# Empty web directory (careful!)
sudo rm -rf /var/www/html/*

# Unpack and set ownership
cd /tmp/voipmonitor-gui-install
tar xzf gui.tar.gz
cp -r voipmonitor-gui-*/. /var/www/html/
sudo chown -R www-data /var/www/html   # Use "apache" on RHEL/CentOS

# Restore configuration from backup
sudo cp /var/www/html-backup-$(date +%F)/config/configuration.php /var/www/html/config/

⚠️ Warning: Watch for "No space left on device" errors during tar extraction. Check disk space: df -h

Step 4: Finalize in Browser

Open the VoIPmonitor GUI in your browser
Perform a hard refresh: Ctrl+Shift+R (or Cmd+Shift+R on Mac)

This ensures the browser loads new assets and performs database schema checks.

Offline Installation

For servers without internet access:

On a machine with internet: Download GUI package using wget command from Step 3
Transfer: Copy gui.tar.gz to the offline server via SCP or USB
On offline server: Follow Steps 2-4 above

Database Schema Updates

After major version upgrades, database schema may need updates.

Automatic (minor changes):

Navigate to http://your-gui.com/?check_tables=1
Or: Tools → System Status → Check MySQL Schema

Manual (major changes):

# Check logs for ALTER recommendations
sudo journalctl -u voipmonitor -n 50 | grep -i "alter"

# Execute in MySQL (run during off-peak hours - ALTERs lock tables)
mysql -u root -p
# Paste ALTER commands from logs

For high-traffic environments, consider the migration instance method to avoid downtime. See Redundant_database for details.

Automatic Schema Safety (1000 CDR Threshold)

VoIPmonitor includes a built-in safety mechanism to prevent accidental schema modifications on production databases:

Database Size	Automatic Behavior
< 1000 CDRs	Auto-modifies tables on service start (new/development databases safe to alter)
>= 1000 CDRs	Logs required ALTER commands to syslog/messages/journalctl (does NOT execute)

Important implications:

Production databases (most have >> 1000 CDRs) are protected by default - ALTER queries are logged but not executed
Administrator action required: For production databases, review logs and run ALTER commands manually during low-traffic periods (e.g., overnight) to prevent table locking
Check logs after service restart: journalctl -u voipmonitor | grep -i alter

ℹ️ Note: The 1000 CDR threshold is handled automatically by the sniffer. No configuration required for this protection.

Troubleshooting

ionCube Loader Error

If GUI displays ionCube error (including "undefined symbol: zend_string_initerned") after PHP upgrade:

⚠️ Warning: Do NOT downgrade PHP. VoIPmonitor provides GUI packages for PHP 7.4, 8.0, 8.1, and 8.2.

Solution: Re-download GUI for your web server's PHP version:

# First verify web server PHP version (may differ from CLI)
echo '<?php phpinfo(); ?>' > /var/www/html/test.php
# Check http://your-server/test.php, then remove test file

# Re-download correct version
wget "https://www.voipmonitor.org/download-gui?version=latest&major=5&allowed&phpver=82" -O gui.tar.gz
# Follow Step 3 installation

Alternative: Download ionCube directly from ioncube.com and configure manually.

500 Server Error (ionCube Config)

After system update, 500 errors may indicate ionCube configs pointing to wrong PHP version:

# Find ionCube config files
grep ioncube /etc/* -Inri

# Check what version they reference
cat /etc/php.d/01_ioncube.ini

# Remove or comment out configs for wrong PHP version
sudo rm /etc/php.d/01_ioncube.ini   # Or edit and comment with ;

# Also check main php.ini
grep -n ioncube /etc/php.ini

# Restart web server
sudo systemctl restart httpd   # Or apache2 / php-fpm

Empty Path Error After Reinstall

If GUI fails with "empty path" error in fce_config.php, the configuration.php was corrupted:

# Restore from backup
sudo cp /var/www/html-backup-YYYY-MM-DD/config/configuration.php /var/www/html/config/

💡 Tip: If no backup exists, navigate to GUI URL to re-run the installation wizard and enter database credentials.

Corrupted License File

If GUI asks for license token but you have a valid license:

sudo rm /var/www/html/key.php

Refresh GUI and click "get license key" to fetch a fresh copy.

Re-activating License After Fresh Install

Before reinstall: Copy licensetoken from Settings → License
After reinstall: Paste token into activation form and click "get/update license key"

If Hardware ID changed (new server), click "Get License" in Settings → License to re-synchronize.

@@ Line 124: / Line 124: @@
 For high-traffic environments, consider the '''migration instance method''' to avoid downtime. See [[Redundant_database]] for details.
+=== Automatic Schema Safety (1000 CDR Threshold) ===
-== Automatic Schema Safety: CDR Count Threshold ==
-=== Automatic Schema Safety: CDR Count Threshold ===
 VoIPmonitor includes a built-in safety mechanism to prevent accidental schema modifications on production databases:
@@ Line 136: / Line 132: @@
 ! Database Size !! Automatic Behavior
 |-
-! '''&lt; 1000 CDRs'''
+! '''< 1000 CDRs'''
 | Auto-modifies tables on service start (new/development databases safe to alter)
 |-
-! '''&gt;= 1000 CDRs'''
+! '''>= 1000 CDRs'''
 | Logs required '''ALTER''' commands to syslog/messages/journalctl (does NOT execute)
 |}
@@ Line 145: / Line 141: @@
 '''Important implications:'''
-* '''Production databases''' (most have &gt;&gt; 1000 CDRs) are protected by default - ALTER queries are logged but not executed
+* '''Production databases''' (most have >> 1000 CDRs) are protected by default - ALTER queries are logged but not executed
 * '''Administrator action required:''' For production databases, review logs and run ALTER commands manually during low-traffic periods (e.g., overnight) to prevent table locking
 * '''Check logs after service restart:''' <code>journalctl -u voipmonitor | grep -i alter</code>
 {{Note|The 1000 CDR threshold is handled automatically by the sniffer. No configuration required for this protection.}}
 == Troubleshooting ==
@@ Line 222: / Line 220: @@
 * [[License]] - License management
 * [[Redundant_database]] - Migration instance method
-== AI Summary for RAG ==
-'''Summary:''' Step-by-step guide for reinstalling VoIPmonitor web GUI to fix corrupted installations or adapt to PHP version changes. Process preserves CDRs, PCAPs, and configuration. Four main steps: (1) Check PHP version with <code>php --version</code>, (2) Backup web directory and separately backup <code>configuration.php</code>/<code>key.php</code>, (3) Download correct GUI package using wget with <code>phpver=</code> parameter matching your PHP version, run <code>install-gui.sh</code>, (4) Hard browser refresh (Ctrl+Shift+R). Critical warnings: extraction errors (disk full) can leave configuration.php empty causing "empty path" errors in fce_config.php - restore from backup. Package validation: <code>tar -tvf gui.tar.gz | grep "vm-"</code> should show vm-i686 and vm-x86_64 binaries. Key troubleshooting: ionCube errors after PHP upgrade - re-download GUI for correct PHP version (do NOT downgrade PHP); 500 errors - find and fix ionCube config files with <code>grep ioncube /etc/* -Inri</code>; empty path errors - restore configuration.php from backup; license issues - delete key.php and re-fetch. Database schema updates: use <code>?check_tables=1</code> for automatic updates, or check logs for ALTER commands after major upgrades (run during off-peak hours as ALTERs lock tables).
-'''Keywords:''' reinstall GUI, corrupted installation, PHP upgrade, ionCube Loader, ionCube error, 500 server error, install-gui.sh, key.php, license, phpver, check_tables, ALTER commands, database schema, disk space, tar extraction, configuration.php, empty path error, fce_config.php, offline installation
-'''Key Questions:'''
-* How do I reinstall the VoIPmonitor GUI?
-* How do I fix the GUI after changing PHP version?
-* How do I fix ionCube Loader errors?
-* How do I fix 500 server error after system update?
-* How do I locate ionCube configuration files?
-* How do I fix corrupted key.php license file?
-* What command downloads GUI for specific PHP version?
-* How do I update database schema after major upgrade?
-* How do I restore configuration.php from backup?
-* How do I re-activate license after fresh install?