Re-install the GUI

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.

=kroki}} lang="mermaid"> %%{init: {'flowchart': {'nodeSpacing': 15, 'rankSpacing': 35}}}%% flowchart TD

   A[GUI Not Working] --> B{Identify Issue}
   B -->|Corrupted/PHP Upgrade| C[Check PHP Version]
   C --> D[Backup GUI]
   D --> E[Download & Install]
   E --> F[Browser Refresh]
   F --> G{Working?}
   G -->|Yes| H[Done]
   G -->|ionCube Error| I[Re-download correct PHP ver]
   G -->|500 Error| J[Fix ionCube config]
   G -->|License Issue| K[Remove key.php]
   I --> F
   J --> F
   K --> F

</kroki>

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

1. Open the VoIPmonitor GUI in your browser
2. 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:

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

Database Schema Updates

Automatic Schema Upgrade Safety Mechanism

The VoIPmonitor sensor includes a built-in safety mechanism to protect production databases from automatic schema modifications:

Database Size	Behavior
< 1000 CDRs	Auto-executes schema changes (CREATE TABLE, ALTER TABLE)
≥ 1000 CDRs	Logs required ALTER queries to syslog/journalctl for manual execution

⚠️ Warning: For production databases with ≥ 1000 CDRs, the sniffer will NOT automatically modify tables. Instead, you must manually execute the logged ALTER queries during a low-traffic period (e.g., overnight) to prevent table locking.

Checking for Required Schema Changes

After major version upgrades, database schema may need updates.

Check what's needed:

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

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

Applying Schema Changes

Method	When to Use
Small changes, single schema
Large schemas, off-peak execution
Cross-version upgrade, high-traffic production

Manual execution (off-peak hours):

# Extract ALTER queries from logs
journalctl -u voipmonitor | grep -i alter > /tmp/alters.sql

# Review and edit the SQL file
nano /tmp/alters.sql

# Execute during low-traffic period
mysql -u root -p voipmonitor < /tmp/alters.sql

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

= Connecting to Existing Production Databases

When installing a new sniffer that connects to an existing production database:

1. The 1000 CDR safety mechanism protects large databases from automatic modification 2. Required ALTER queries are logged to /var/log/syslog, /var/log/messages, or journalctl 3. Execute logged queries manually during low-traffic period 4. If running multiple sensors simultaneously, ensure id_sensor is unique per sensor 5. Review hardware-dependent settings: interface, max_buffer_mem, spooldir, maxpoolsize

ℹ️ Note: disable_dbupgradecheck = yes skips all schema checks (rarely needed). Use with caution.

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

1. Before reinstall: Copy licensetoken from Settings → License
2. 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.

See Also

• GUI_installation - Fresh GUI installation
• GUI_troubleshooting - General GUI issues
• 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 php --version, (2) Backup web directory and separately backup configuration.php/key.php, (3) Download correct GUI package using wget with phpver= parameter matching your PHP version, run install-gui.sh, (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: tar -tvf gui.tar.gz | grep "vm-" 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 grep ioncube /etc/* -Inri; empty path errors - restore configuration.php from backup; license issues - delete key.php and re-fetch. Database schema updates: use ?check_tables=1 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?