Re-install the GUI

From VoIPmonitor.org
Revision as of 07:11, 6 January 2026 by Admin (talk | contribs) (Add section on fixing 500 server error caused by ionCube configuration mismatch after system update)


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.

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

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)

Step 3: Download and Run the Installer

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

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.

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.

GUI Fails with ionCube Loader Error After Upgrade

If the VoIPmonitor GUI fails to load and displays an ionCube Loader error after upgrading your operating system or PHP version, this indicates that your GUI package was built for a different PHP version. The solution is to re-download the GUI package specifically built for your current 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.

1. Confirm your PHP version
php --version

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

2. Download the correct GUI package for your PHP version
mkdir /tmp/voipmonitor-gui-install
cd /tmp/voipmonitor-gui-install

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

# Or for PHP 8.1:
# wget "https://www.voipmonitor.org/download-gui?version=latest&major=5&allowed&phpver=81" -O gui.tar.gz
3. Follow the installation steps in Re-install_the_GUI #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.

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 https://downloads.ioncube.com/loader_downloads/ioncube_loaders_lin_x86-64.tar.gz.

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

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.
  2. sudo rm /var/www/html/key.php
  3. Refresh the GUI page in your browser.
  4. 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: This method works as long as your Hardware ID (HWID) has not changed. If you have moved to a completely new server with a different HWID, you will need to contact VoIPmonitor support to regenerate the license token for the new server.

AI Summary for RAG

Summary: This guide provides a step-by-step tutorial on how to safely reinstall the VoIPmonitor web GUI to fix issues like a corrupted installation or to adapt to a new PHP version after an OS upgrade. It clarifies that this process does not affect user data. The procedure involves four main steps: 1) Identifying the server's PHP version using `php --version`. 2) Creating a full backup of the web directory (`/var/www/html`) as a precaution. 3) Downloading the correct GUI package for the specific PHP version using `wget`. An optional validation step allows checking package contents before installation: use `tar -tvf gui.tar.gz |grep "vm-"` to verify that the GUI package contains the required architecture binaries (`vm-i686` for 32-bit and `vm-x86_64` for 64-bit). This is useful for automated deployment scenarios or when you do not have a license available to run the standard `install-gui.sh` script. After validation, run the included `install-gui.sh` script. 4) Finalizing the process with a hard browser refresh (Ctrl+Shift+R) to clear the cache. A critical troubleshooting section addresses the common scenario where the GUI fails with an ionCube Loader error after an OS or PHP upgrade: the solution is to re-download the GUI package specifically built for the current PHP version using the `phpver=` parameter (e.g., `phpver=82` for PHP 8.2, `phpver=81` for PHP 8.1). Importantly, this guide emphasizes that VoIPmonitor provides GUI packages for all major PHP versions (8.2, 8.1, 8.0, 7.4) and users should NOT downgrade PHP; instead, re-download the matching GUI package. A specialized section covers fixing a 500 server error after a system update caused by system-level ionCube configuration files pointing to the wrong PHP version. This requires: 1) Checking the active PHP version with `php --version`. 2) Locating all ionCube configuration files using `grep ioncube /etc/* -Inri`. Common locations include `/etc/php.d/01_ioncube.ini`, `/etc/php.d/ioncube.ini`, and `/etc/php.ini`. 3) Reviewing configuration files to check which PHP version the loader was compiled for (e.g., `ioncube_loader_lin_7.4.so` for PHP 7.4). 4) Removing or commenting out configuration files pointing to incorrect PHP versions (e.g., `sudo rm /etc/php.d/01_ioncube.ini`). 5) Ensuring only the correct ionCube loader for the active PHP version is enabled. 6) Removing redundant ionCube entries from the main `php.ini` (`grep -n ioncube /etc/php.ini`). 7) Restarting the web server (`systemctl restart httpd` or `systemctl restart apache2` or `systemctl restart php-fpm`). 8) Verifying the fix with `php --version`. A dedicated section explains database schema updates for major version upgrades, including the automatic `?check_tables=1` method, checking `journalctl` or `syslog` for recommended ALTER commands after sniffer restart, important timing considerations (ALTERs lock tables and pause CDR ingestion, so run during off-peak hours), and the migration instance alternative for high-traffic environments. A troubleshooting section explains how to resolve a corrupted license by deleting the `key.php` file and re-fetching the license via the GUI, and how to re-activate a license after a fresh database install by copying the `licensetoken` from Settings > License before reinstalling and pasting it into the new setup. Keywords: reinstall, reinstalling, GUI, fix, corrupted, upgrade, PHP version, PHP 8.2, PHP 8.1, ionCube Loader, ionCube error, ionCube configuration, `grep ioncube`, `grep ioncube /etc/* -Inri`, `/etc/php.d/01_ioncube.ini`, `/etc/php.d/ioncube.ini`, `/etc/php.ini`, 500 server error, system update, system-level configuration, `install-gui.sh`, `key.php`, license, backup, web interface, `a2enmod`, `wget`, phpver, licensetoken, re-activate license, database reinstall, database schema, ALTER commands, `check_tables=1`, `journalctl`, syslog, off-peak hours, migration instance, major version upgrade, CDR ingestion pause, table locks, vm-i686, vm-x86_64, validate package, package validation, validate GUI package, tar -tvf, grep vm-, automated deployment, package contents, binary validation, architecture binary Key Questions:

  • How do I reinstall the VoIPmonitor GUI?
  • What should I do if the GUI is broken after an update?
  • How can I fix the GUI after changing my server's PHP version?
  • What are the steps to run the `install-gui.sh` script?
  • How do I fix a corrupted `key.php` license file?
  • How can I safely back up my GUI files before a reinstallation?
  • What is the command to download the latest GUI for a specific PHP version?
  • How do I re-activate my license after performing a fresh install of the database?
  • How can I use the licensetoken to restore my license without contacting support?
  • What should I do before reinstalling the database to preserve my license?
  • How do I update the database schema after a major GUI upgrade?
  • Where do I find recommended ALTER commands after a version upgrade?
  • Why should I run ALTER commands during off-peak hours?
  • What is the migration instance method for database schema updates?
  • How do I use `?check_tables=1` to update the database schema?
  • What happens to CDR ingestion when running ALTER commands?
  • The GUI fails with an ionCube Loader error, how do I fix it?
  • Does VoIPmonitor support PHP 8.2?
  • Do I need to downgrade PHP to fix an ionCube error?
  • What is the correct wget command to download the GUI for PHP 8.2?
  • How do I download the GUI package for a specific PHP version using phpver parameter?
  • How can I validate a GUI package before installation?
  • How do I check if a GUI package contains the required binaries?
  • What is the command to verify vm-i686 and vm-x86_64 binaries in a GUI tar.gz package?
  • How can I validate a VoIPmonitor GUI package without a license?
  • What command shows the contents of a GUI tar.gz package without extracting it?
  • What are the required binaries in a VoIPmonitor GUI package?
  • How do I fix a 500 server error after a system update?
  • What should I do if the GUI returns a 500 error after upgrading PHP?
  • How do I locate ionCube configuration files on my system?
  • What is the command to find all ionCube references in /etc?
  • How do I fix ionCube configuration pointing to the wrong PHP version?
  • Where are ionCube configuration files located on Linux?
  • How do I remove incorrect ionCube entries from /etc/php.ini?
  • How do I fix ionCube loader version mismatch after OS upgrade?
Retrieved from "https://www.voipmonitor.org/doc/index.php?title=Re-install_the_GUI&oldid=8206"