Re-install the GUI

From VoIPmonitor.org
Revision as of 19:35, 6 January 2026 by Admin (talk | contribs) (Add offline upgrade section for servers without internet access)


This guide provides a step-by-step process for safely reinstalling the VoIPmonitor web GUI. This procedure is the recommended solution for fixing a corrupted installation or adapting the GUI to a new PHP version after a system upgrade.

When to Reinstall the GUI

A reinstallation overwrites the core GUI application files without affecting your data (CDRs and PCAPs) or your primary configuration (`config/configuration.php`). It is the correct solution for scenarios such as:

  • A failed or incomplete GUI upgrade due to a power loss, full disk, or other interruption.
  • The GUI fails to load after a server operating system or PHP version upgrade.
  • Suspected file corruption in the GUI's web directory.
  • The Apache default welcome page or a generic index.html page is displayed instead of the VoIPmonitor GUI after an update or upgrade.

Note: This guide assumes you have a previously working GUI and that all necessary PHP dependencies (like ionCube Loader) are already installed.

Reinstallation Process Overview

Step 1: Identify Your Server's PHP Version

The GUI package is specific to the major PHP version installed on your server. First, determine which version you are running. 

php --version

Look for the first two numbers (e.g., 8.1, 8.2, 7.4). You will use this to download the correct package.

Step 2: Back Up Your Current GUI Directory

Before making any changes, it is crucial to create a backup of your entire web directory. This allows you to revert easily if anything goes wrong. 

# The default path is /var/www/html, but adjust if you have a custom path
sudo cp -a /var/www/html /var/www/html-backup-$(date +%F)

⚠️ Warning: The installation script attempts to preserve configuration.php and key.php. However, if these files become empty or corrupted during the reinstallation process, the GUI may fail to load with errors about empty paths in fce_config.php or similar configuration files. Always keep a separate backup of your configuration.

Step 3: Download and Run the Installer

This process involves downloading the latest GUI package and running its installation script.

ℹ️ Note: For servers without internet access, see Offline Upgrade below to download the files on another machine and transfer them via USB/SCP.

1. Create a temporary directory and download the GUI package

The following command downloads the latest GUI package compatible with your PHP version. Replace 81 with your version number (e.g., 82 for PHP 8.2, 74 for PHP 7.4). 

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

# Example for PHP 8.1 (change phpver=81 accordingly)
wget "https://www.voipmonitor.org/download-gui?version=latest&major=5&allowed&phpver=81" -O gui.tar.gz
2. (Optional) Validate the package contents before installation

If you need to verify that the downloaded GUI package contains the required binaries before installation (for example, in automated deployment scenarios or when you do not have a license available), you can check the package contents without extracting it: 

# List the package contents and search for the required architecture binaries
tar -tvf gui.tar.gz | grep "vm-"

The expected output should include:

  • voipmonitor-gui-*/bin/vm-i686 (32-bit architecture binary)
  • voipmonitor-gui-*/bin/vm-x86_64 (64-bit architecture binary)

These binaries are essential for the VoIPmonitor GUI operation. If the search returns no results, the package may be incomplete or corrupted.

3. Extract the archive and run the installer
tar xzf gui.tar.gz
cd voipmonitor-gui-*/scripts/
sudo bash install-gui.sh ../../gui.tar.gz

The script will ask you to confirm the installation path. Press Enter to confirm the default path (e.g., /var/www/html). The script will then unpack the new GUI files over your existing installation.

ℹ️ Note: The install-gui.sh script automatically preserves your config/configuration.php file and sets appropriate file permissions.

4. Alternative: Manual unpacking (if you prefer full control)

If you need more control over the installation process or if the automated script encounters issues, you can manually empty the directory and unpack the files: 

# Empty the web directory (be very careful with this command!)
sudo rm -rf /var/www/html/*

# Unpack the GUI package
cd /tmp/voipmonitor-gui-install
tar xzf gui.tar.gz
cp -r voipmonitor-gui-*/. /var/www/html/

# Set correct ownership for web server files
# Use "www-data" for Debian/Ubuntu, or "apache" for RHEL/CentOS/AlmaLinux
sudo chown -R www-data /var/www/html

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

Important: Watch for tar extraction errors. Pay close attention to the output of the tar command during extraction. If you see errors such as "No space left on device", this indicates your disk is full and the installation will be incomplete. In this case, you must free up disk space before attempting installation again. To check available disk space: 

df -h

Step 4: Finalize the Installation in Your Browser

After the script finishes, you must complete the process in your web browser.

1. Open the VoIPmonitor GUI in your browser.
2. Perform a hard refresh to bypass your browser's cache. In most browsers, the shortcut is Ctrl+Shift+R (or Cmd+Shift+R on Mac).

This final step ensures that your browser loads the latest assets and that any necessary database schema checks are performed. Your GUI should now be fully restored and operational.

Offline Upgrade (Servers Without Internet Access)

If your server does not have internet access or if standard web interface upgrades fail with "Unable to connect to upgrade server!" errors, you can perform an offline upgrade by downloading the files on another machine with internet access and transferring them to the target server.

GUI Offline Upgrade

Follow these steps to upgrade the GUI without internet access:

1. On a machine WITH internet access, determine the PHP version

Check the PHP version on your offline server: php --version

2. On the machine WITH internet access, download the GUI package

Use the same URL as shown in Step 3, replacing 81 with your PHP version: 

# Example for PHP 8.1 (adjust phpver= as needed)
wget "https://www.voipmonitor.org/download-gui?version=latest&major=5&allowed&phpver=81" -O gui.tar.gz
3. Transfer the file to your offline server

Use SCP or a USB flash drive to transfer gui.tar.gz to the offline server's /tmp directory.

4. On the offline server, complete Steps 2-4 from the main installation

Back up your current GUI directory (Step 2), extract and install the package (Step 3), and perform the browser refresh (Step 4).

ℹ️ Note: For detailed backup, extraction, and configuration restoration steps, see Step 2 and Step 3.

GUI Fails with ionCube Loader Error After Upgrade

If the VoIPmonitor GUI fails to load and displays an ionCube Loader error (including errors like "undefined symbol: zend_string_initerned") after upgrading your operating system or PHP version, this indicates that the ionCube Loader installed on your system is incompatible with your PHP version.

Do NOT downgrade PHP. VoIPmonitor provides GUI packages for all major PHP versions including PHP 8.2, PHP 8.1, PHP 8.0, and PHP 7.4.

Important: Check both CLI and web server PHP versions. The command-line PHP version may differ from the web server's PHP version. You must ensure the ionCube Loader matches the PHP version used by the web server.

1. Check the CLI PHP version
php --version

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

2. Check the web server's PHP version
# Create a test file in your web root directory
echo '<?php phpinfo(); ?>' > /var/www/html/test.php

# Access this file in your browser: http://your-server.com/test.php
# Look for the PHP version at the top of the page

Compare the CLI and web server PHP versions. If they differ, the GUI (and ionCube Loader) on your web server must match the web server's PHP version, not the CLI version.

After checking, remove the test file: 

rm /var/www/html/test.php
3. Primary solution: Re-download the GUI package for your web server PHP version. The VoIPmonitor GUI includes pre-configured ionCube loaders for all major PHP versions. This is usually the easiest solution.
mkdir /tmp/voipmonitor-gui-install
cd /tmp/voipmonitor-gui-install

# For PHP 8.2 on web server (example - change as needed)
wget "https://www.voipmonitor.org/download-gui?version=latest&major=5&allowed&phpver=82" -O gui.tar.gz

# Or for PHP 8.1 on web server:
# wget "https://www.voipmonitor.org/download-gui?version=latest&major=5&allowed&phpver=81" -O gui.tar.gz
4. Follow the installation steps in #Step 3: Download and Run the Installer above to complete the reinstallation.

This process replaces only the GUI application files while preserving your configuration and CDR data.

5. Alternative solution: Download ionCube Loader directly (only if GUI reinstallation does not resolve the issue)
# Download from the official ionCube website
cd /tmp
wget https://downloads.ioncube.com/loader_downloads/ioncube_loaders_lin_x86-64.tar.gz

# Extract the archive
tar xzf ioncube_loaders_lin_x86-64.tar.gz

# Copy the correct loader for your web server PHP version
# Example for PHP 8.2:
sudo cp ioncube/ioncube_loader_lin_8.2.so /usr/lib64/php/modules/

# Edit the PHP configuration to load it
sudo nano /etc/php.d/ioncube.ini
# Add this line:
zend_extension = /usr/lib64/php/modules/ioncube_loader_lin_8.2.so

# Restart the web server
sudo systemctl restart httpd
# or
sudo systemctl restart apache2
# or
sudo systemctl restart php-fpm

500 Server Error After System Update (ionCube Configuration)

If the VoIPmonitor GUI returns a 500 server error and becomes completely inaccessible after a system update (particularly operating system or PHP version upgrades), this may indicate that ionCube configuration files on your system are pointing to the wrong PHP version. Unlike the basic ionCube error message (which is resolved by re-downloading the GUI), this issue requires fixing system-level PHP configuration files.

1. Identify the active PHP version
php --version

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

2. Locate all ionCube configuration files
grep ioncube /etc/* -Inri

This search will list all locations in /etc that contain ionCube references. Common locations include:

  • /etc/php.d/01_ioncube.ini
  • /etc/php.d/ioncube.ini
  • /etc/php.ini
3. Review the ionCube configuration files
cat /etc/php.d/01_ioncube.ini
cat /etc/php.d/ioncube.ini

Check which PHP version the loader was compiled for. For example, a loader named ioncube_loader_lin_7.4.so will not work if your active PHP version is 8.1 or 8.2.

4. Remove or comment out configuration files pointing to incorrect PHP versions
# Remove specific files pointing to wrong PHP version
sudo rm /etc/php.d/01_ioncube.ini

# Or comment out lines by adding ; at the beginning
sudo nano /etc/php.d/01_ioncube.ini
# Change: zend_extension = /path/to/wrong/loader.so
# To:     ; zend_extension = /path/to/wrong/loader.so
5. Ensure only the correct ionCube loader for the active PHP version is enabled

After removing incorrect configurations, verify that a correct ionCube loader exists and is enabled. The file should reference a loader compiled for your active PHP version.

6. Remove redundant ionCube entries from the main php.ini
grep -n ioncube /etc/php.ini

If ionCube references are found in your main php.ini file: 

sudo nano /etc/php.ini
# Comment out or remove these duplicate entries
7. Restart the web server service
# On RHEL/CentOS/AlmaLinux/Fedora:
sudo systemctl restart httpd

# On Debian/Ubuntu:
sudo systemctl restart apache2
# or
sudo systemctl restart php-fpm
8. Verify the fix
php --version

The command should now execute successfully without errors. The GUI should be accessible again.

Note: If fixing the ionCube configuration files does not resolve the issue, the ionCube loader may not be installed for your current PHP version. In that case, download and install the appropriate ionCube loader from the official ionCube website.

Database Schema Updates for Major Version Upgrades

When performing a major version upgrade (e.g., from v25.2 to v25.3 or later), the database schema may undergo changes. While the automatic schema check (?check_tables=1) handles many simple changes, some upgrades require manual intervention.

Automatic Schema Update (Minor Changes)

For most schema changes, you can use the integrated schema check:

  • Append ?check_tables=1 to your GUI URL (e.g., http://your-gui.com/?check_tables=1)
  • Or navigate to Tools → System Status → Check MySQL Schema
  • Review any listed changes and click Start Upgrade / Run SQL

Manual ALTER Commands (Major Changes)

After a major version upgrade, the VoIPmonitor sniffer may recommend specific database ALTER commands in its logs. Follow this procedure:

1. Restart the sniffer service
sudo systemctl restart voipmonitor
2. Check the logs for ALTER recommendations
# On systems using journalctl
sudo journalctl -u voipmonitor -n 50 | grep -i "alter"

# On systems using syslog
sudo tail -n 50 /var/log/syslog | grep -i "alter"
3. Important Timing Considerations:
  • ALTER commands lock tables and will temporarily pause CDR ingestion
  • Run ALTER commands during off-peak hours to minimize production impact
  • You can run the ALTER commands directly in the database while the sniffer continues to capture packets
4. Execute the ALTER commands

Open the MySQL/MariaDB prompt and paste the output from the logs: 

mysql -u root -p
-- (Paste the ALTER commands here)
5. After running ALTERs, restart the sniffer
sudo systemctl restart voipmonitor

Migration Instance Alternative (High-Traffic Environments)

If you cannot afford the downtime caused by ALTER commands locking tables, consider using the migration instance method:

1. Set up a new MySQL/MariaDB instance with the latest schema
2. Configure a migration sensor to read from the old database and write to the new one
3. The migration sensor replays all CDRs to the new instance with the updated schema
4. Once migration is complete, switch the GUI and sensors to use the new database
5. This approach avoids production impact but requires temporary storage for the duplicate database

Troubleshooting

GUI Fails to Load with Empty Path Error After Reinstallation

If the GUI fails to load after reinstallation and displays an error mentioning empty paths in fce_config.php or similar configuration files, this indicates that the configuration.php file became empty or corrupted during the installation process.

⚠️ Warning: The installation script attempts to preserve configuration.php and key.php. However, extraction errors (such as disk space issues) can leave these files in an incomplete or empty state, causing the GUI initialization to fail.

Solution
Restore configuration.php from backup
  1. Locate your backup created in #Step 2: Back Up Your Current GUI Directory: 
    ls -la /var/www/html-backup-*/
  2. Find the backup directory with the date when you performed the reinstallation.
  1. Restore the configuration.php file from the backup: 
    # Replace YYYY-MM-DD with your backup date
sudo cp /var/www/html-backup-YYYY-MM-DD/config/configuration.php /var/www/html/config/configuration.php
#
  1. If your GUI uses the root web directory: 
    sudo cp /var/www/html-backup-YYYY-MM-DD/configuration.php /var/www/html/configuration.php
#
  1. Perform a hard refresh in your browser (Ctrl+Shift+R or Cmd+Shift+R).

💡 Tip: If you cannot access your backup, you will need to re-run the installation wizard to recreate the configuration. Navigate to the GUI URL in your browser and follow the setup prompts to enter your database credentials.

Missing GUI Files After Installation

If you have completed the installation but GUI files appear to be missing or incomplete (e.g., the GUI shows errors or missing features), this typically indicates that the package extraction did not complete successfully.

1. Check the tar command output

Review the output from the tar extraction step during installation. Look for error messages such as:

  • "No space left on device" - Your disk is full, preventing files from being written
  • "Cannot write: No space left on device" - Same issue as above
  • "tar: Error exit delayed from previous errors" - May indicate incomplete extraction
2. Verify available disk space
df -h

Check that your disk partition has sufficient free space (at least several GB for a complete VoIPmonitor installation). If the disk is full, you must:

  • Remove unnecessary files or old compressed PCAP files to free up space
  • Move data to another partition or external storage
  • Consider upgrading your disk capacity
3. Re-download and reinstall with sufficient disk space

After freeing up disk space, repeat the installation procedure starting from #Step 1: Identify Your Server's PHP Version.

Note: If disk space was the issue, reinstalling without first freeing space will fail again, producing the same incomplete installation.

Corrupted License File

If, after reinstalling, the GUI asks for a license token but you already have a valid license, your key.php file may have been corrupted.

Solution
  1. Remove the old license file from your GUI's installation directory: 
    sudo rm /var/www/html/key.php
  2. Refresh the GUI page in your browser.
  3. You will be prompted to enter your license token again. Click the "get license key" button to have the system automatically fetch and install a fresh copy of your key.php file.

Re-activating License After Fresh Database Install

If you perform a fresh installation of the VoIPmonitor database (or a complete OS re-install where the web directory was reset), you can quickly re-activate your license using the licensetoken field without needing to contact support.

Before the reinstall
  1. Log in to your current VoIPmonitor GUI.
  2. Navigate to Settings > License.
  3. Copy the entire licensetoken string displayed on this page.
After the fresh database install and new GUI setup
  1. Access the VoIPmonitor GUI (you will be presented with the license activation/welcome form).
  2. Paste the previously copied licensetoken into the form.
  3. Click the "get/update license key" button to download and activate your license for the new setup.

Note: If your Hardware ID (HWID) has changed (e.g., you moved to a new server), you can resolve this by clicking the "Get License" button in Settings > License. The system will automatically re-synchronize your license with the current server's HWID. Only contact VoIPmonitor support if the error persists after clicking "Get License" or if you need to run both old and new systems concurrently during migration (requires a temporary trial license).

AI Summary for RAG

Summary: Step-by-step guide for reinstalling the VoIPmonitor web GUI to fix corrupted installations or adapt to PHP version changes. The process preserves user data (CDRs, PCAPs) and configuration. Four main steps: 1) Check PHP version with php --version, 2) Backup web directory (CRITICAL - separate backup of configuration.php and key.php), 3) Download correct GUI package using wget with phpver= parameter (e.g., phpver=82 for PHP 8.2), run install-gui.sh, 4) Hard browser refresh (Ctrl+Shift+R). Important: Extraction errors (disk full) can leave configuration.php empty, causing GUI failures with "empty path" errors in fce_config.php - restore from /var/www/html-backup-YYYY-MM-DD/config/configuration.php or /var/www/html-backup-YYYY-MM-DD/configuration.php (backup location). The install-gui.sh script automatically preserves config/configuration.php and sets permissions. Alternative manual method: empty directory with rm -rf /var/www/html/*, unpack with cp -r voipmonitor-gui-*/. /var/www/html/, set ownership with chown -R www-data /var/www/html, restore config from backup. Optional package validation: tar -tvf gui.tar.gz | grep "vm-" checks for required binaries (vm-i686, vm-x86_64). Key troubleshooting: ionCube errors after PHP upgrade - re-download GUI for correct PHP version (do NOT downgrade PHP); 500 errors - locate and fix ionCube config files with grep ioncube /etc/* -Inri, remove configs pointing to wrong PHP version; empty path/configuration errors after reinstall - restore configuration.php from backup (use ls -la /var/www/html-backup-*/ to find backup date); license issues - delete key.php and re-fetch; missing files - check disk space with df -h. 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=1, ALTER commands, database schema, disk space, tar extraction, vm-i686, vm-x86_64, package validation, manual unpacking, chown, ownership, configuration restoration, configuration.php, empty path error, fce_config.php

Key Questions:

  • How do I reinstall the VoIPmonitor GUI?
  • How can I fix the GUI after changing my server's PHP version?
  • The GUI fails with an ionCube Loader error, how do I fix it?
  • How do I fix a 500 server error after a system update?
  • How do I locate ionCube configuration files on my system?
  • How do I fix a corrupted key.php license file?
  • What is the command to download the latest GUI for a specific PHP version?
  • How do I update the database schema after a major GUI upgrade?
  • What should I do if GUI files are missing after installation?
  • How can I validate a GUI package before installation?
  • How do I re-activate my license after a fresh database install?
  • The GUI fails to load with an empty path error in fce_config.php after reinstalling, how do I fix it?
  • How do I restore configuration.php from backup after GUI reinstallation?
Retrieved from "https://www.voipmonitor.org/doc/index.php?title=Re-install_the_GUI&oldid=9358"