Re-install the GUI: Difference between revisions

From VoIPmonitor.org
(Add information about validating GUI package contents before installation using tar and grep to check for vm-i686 and vm-x86_64 binaries)
m (Reverted edits by Admin (talk) to last revision by Festr)
Tag: Rollback
 
(16 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{DISPLAYTITLE:How to Reinstall the Web GUI}}
{{DISPLAYTITLE:How to Reinstall the Web GUI}}


'''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.'''
'''This guide provides a step-by-step process for safely reinstalling the VoIPmonitor web GUI without losing your data or configuration.'''


== When to Reinstall the GUI ==
== When to Reinstall ==
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.
A reinstallation overwrites GUI application files while preserving your data (CDRs, PCAPs) and configuration (<code>config/configuration.php</code>). 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


== Step 1: Identify Your Server's PHP Version ==
{{Note|This guide assumes you have a previously working GUI with all PHP dependencies (ionCube Loader) already installed.}}
The GUI package is specific to the major PHP version installed on your server. First, determine which version you are running.
 
<pre>
<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:
<syntaxhighlight lang="bash">
php --version
php --version
</pre>
</syntaxhighlight>
Look for the first two numbers (e.g., `8.1`, `8.2`, `7.4`). You will use this to download the correct package.
Note the first two numbers (e.g., <code>8.1</code>, <code>8.2</code>, <code>7.4</code>).


== Step 2: Back Up Your Current GUI Directory ==
{{Warning|1=CLI PHP version may differ from web server PHP version. Create <code>phpinfo();</code> test file to verify web server version if in doubt.}}
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.
 
<pre>
=== Step 2: Backup Current GUI ===
# The default path is /var/www/html, but adjust if you have a custom path
 
<syntaxhighlight lang="bash">
sudo cp -a /var/www/html /var/www/html-backup-$(date +%F)
sudo cp -a /var/www/html /var/www/html-backup-$(date +%F)
</pre>
</syntaxhighlight>
 
{{Warning|1=Always keep a separate backup of <code>configuration.php</code> and <code>key.php</code>. If these become empty during installation, the GUI will fail with "empty path" errors.}}


== Step 3: Download and Run the Installer ==
=== Step 3: Download and Install ===
This process involves downloading the latest GUI package and running its installation script.


;1. Create a temporary directory and download the GUI package:
<syntaxhighlight lang="bash">
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).
<pre>
mkdir /tmp/voipmonitor-gui-install
mkdir /tmp/voipmonitor-gui-install
cd /tmp/voipmonitor-gui-install
cd /tmp/voipmonitor-gui-install


# Example for PHP 8.1 (change phpver=81 accordingly)
# 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
wget "https://www.voipmonitor.org/download-gui?version=latest&major=5&allowed&phpver=81" -O gui.tar.gz
</pre>
;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:
<pre>
# List the package contents and search for the required architecture binaries
tar -tvf gui.tar.gz |grep "vm-"
</pre>
The expected output should include:
* <code>voipmonitor-gui-*/bin/vm-i686</code> (32-bit architecture binary)
* <code>voipmonitor-gui-*/bin/vm-x86_64</code> (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:
# Extract and install
<pre>
tar xzf gui.tar.gz
tar xzf gui.tar.gz
cd voipmonitor-gui-*/scripts/
cd voipmonitor-gui-*/scripts/
sudo bash install-gui.sh ../../gui.tar.gz
sudo bash install-gui.sh ../../gui.tar.gz
</pre>
</syntaxhighlight>
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 ==
Press '''Enter''' to confirm the default installation path. The script preserves your <code>configuration.php</code> and sets permissions automatically.
After the script finishes, you must complete the process in your web browser.


;1. Open the VoIPmonitor GUI in your browser.
{{Tip|1=Validate package before install: <code>tar -tvf gui.tar.gz {{!}} grep "vm-"</code> should show <code>vm-i686</code> and <code>vm-x86_64</code> binaries.}}
;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.
'''Alternative: Manual Installation'''


=== GUI Fails with ionCube Loader Error After Upgrade ===
If the automated script fails:
<syntaxhighlight lang="bash">
# Empty web directory (careful!)
sudo rm -rf /var/www/html/*


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.
# 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


'''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.
# Restore configuration from backup
sudo cp /var/www/html-backup-$(date +%F)/config/configuration.php /var/www/html/config/
</syntaxhighlight>


;1. Confirm your PHP version:
{{Warning|1=Watch for '''"No space left on device"''' errors during tar extraction. Check disk space: <code>df -h</code>}}
<pre>
php --version
</pre>
Look for the first two numbers (e.g., ''8.2'', ''8.1'', ''7.4'').


;2. Download the correct GUI package for your PHP version:
=== Step 4: Finalize in Browser ===
<pre>
mkdir /tmp/voipmonitor-gui-install
cd /tmp/voipmonitor-gui-install


# For PHP 8.2 (example - change as needed for your version)
# Open the VoIPmonitor GUI in your browser
wget "https://www.voipmonitor.org/download-gui?version=latest&major=5&allowed&phpver=82" -O gui.tar.gz
# Perform a hard refresh: '''Ctrl+Shift+R''' (or '''Cmd+Shift+R''' on Mac)


# Or for PHP 8.1:
This ensures the browser loads new assets and performs database schema checks.
# wget "https://www.voipmonitor.org/download-gui?version=latest&major=5&allowed&phpver=81" -O gui.tar.gz
</pre>


;3. Follow the installation steps in [[Step 3: Download and Run the Installer|Re-install_the_GUI #Step 3: Download and Run the Installer]] above to complete the reinstallation.
== Offline Installation ==


This process replaces only the GUI application files while preserving your configuration and CDR data.
For servers without internet access:


== Database Schema Updates for Major Version Upgrades ==
# '''On a machine with internet:''' Download GUI package using wget command from Step 3
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.
# '''Transfer:''' Copy <code>gui.tar.gz</code> to the offline server via SCP or USB
# '''On offline server:''' Follow Steps 2-4 above


=== Automatic Schema Update (Minor Changes) ===
== Database Schema Updates ==
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 &rarr; System Status &rarr; Check MySQL Schema'''
* Review any listed changes and click '''Start Upgrade / Run SQL'''


=== Manual ALTER Commands (Major Changes) ===
After major version upgrades, database schema may need updates.
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:
'''Automatic (minor changes):'''
<pre>sudo systemctl restart voipmonitor</pre>
* Navigate to <code>http://your-gui.com/?check_tables=1</code>
* Or: '''Tools → System Status → Check MySQL Schema'''


;2. Check the logs for ALTER recommendations:
'''Manual (major changes):'''
<pre>
<syntaxhighlight lang="bash">
# On systems using journalctl
# Check logs for ALTER recommendations
sudo journalctl -u voipmonitor -n 50 | grep -i "alter"
sudo journalctl -u voipmonitor -n 50 | grep -i "alter"


# On systems using syslog
# Execute in MySQL (run during off-peak hours - ALTERs lock tables)
sudo tail -n 50 /var/log/syslog | grep -i "alter"
mysql -u root -p
</pre>
# Paste ALTER commands from logs
</syntaxhighlight>
 
For high-traffic environments, consider the '''migration instance method''' to avoid downtime. See [[Redundant_database]] for details.


;3. '''Important Timing Considerations:'''
== Troubleshooting ==
* 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:
=== ionCube Loader Error ===
Open the MySQL/MariaDB prompt and paste the output from the logs:
<pre>mysql -u root -p
-- (Paste the ALTER commands here)
</pre>


;5. After running ALTERs, restart the sniffer:
If GUI displays ionCube error (including "undefined symbol: zend_string_initerned") after PHP upgrade:
<pre>sudo systemctl restart voipmonitor</pre>


=== Migration Instance Alternative (High-Traffic Environments) ===
{{Warning|1=Do NOT downgrade PHP. VoIPmonitor provides GUI packages for PHP 7.4, 8.0, 8.1, and 8.2.}}
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
'''Solution:''' Re-download GUI for your web server's PHP version:
;2. Configure a migration sensor to read from the old database and write to the new one
<syntaxhighlight lang="bash">
;3. The migration sensor replays all CDRs to the new instance with the updated schema
# First verify web server PHP version (may differ from CLI)
;4. Once migration is complete, switch the GUI and sensors to use the new database
echo '<?php phpinfo(); ?>' > /var/www/html/test.php
;5. This approach avoids production impact but requires temporary storage for the duplicate database
# 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
</syntaxhighlight>
 
'''Alternative:''' Download ionCube directly from [https://downloads.ioncube.com/loader_downloads/ioncube_loaders_lin_x86-64.tar.gz ioncube.com] and configure manually.
 
=== 500 Server Error (ionCube Config) ===
 
After system update, 500 errors may indicate ionCube configs pointing to wrong PHP version:
 
<syntaxhighlight lang="bash">
# 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
</syntaxhighlight>
 
=== Empty Path Error After Reinstall ===
 
If GUI fails with "empty path" error in <code>fce_config.php</code>, the <code>configuration.php</code> was corrupted:
 
<syntaxhighlight lang="bash">
# Restore from backup
sudo cp /var/www/html-backup-YYYY-MM-DD/config/configuration.php /var/www/html/config/
</syntaxhighlight>
 
{{Tip|If no backup exists, navigate to GUI URL to re-run the installation wizard and enter database credentials.}}


== Troubleshooting ==
=== Corrupted License File ===
=== 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:
If GUI asks for license token but you have a valid license:
# Remove the old license file from your GUI's installation directory.
<syntaxhighlight lang="bash">
#<pre>sudo rm /var/www/html/key.php</pre>
sudo rm /var/www/html/key.php
# Refresh the GUI page in your browser.
</syntaxhighlight>
# 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.
Refresh GUI and click '''"get license key"''' to fetch a fresh copy.


=== Re-activating License After Fresh Database Install ===
=== Re-activating License After Fresh 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:
# '''Before reinstall:''' Copy ''licensetoken'' from '''Settings → License'''
# Log in to your current VoIPmonitor GUI.
# '''After reinstall:''' Paste token into activation form and click '''"get/update license key"'''
# Navigate to '''Settings > License'''.
# Copy the entire ''licensetoken'' string displayed on this page.


;After the fresh database install and new GUI setup:
If Hardware ID changed (new server), click '''"Get License"''' in '''Settings → License''' to re-synchronize.
# Access the VoIPmonitor GUI (you will be presented with the license activation/welcome form).
# Paste the previously copied ''licensetoken'' into the form.
# 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.
== See Also ==
* [[GUI_installation]] - Fresh GUI installation
* [[GUI_troubleshooting]] - General GUI issues
* [[License]] - License management
* [[Redundant_database]] - Migration instance method


== AI Summary for RAG ==
== 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 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, `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
'''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:'''
'''Key Questions:'''
* How do I reinstall the VoIPmonitor GUI?
* How do I reinstall the VoIPmonitor GUI?
* What should I do if the GUI is broken after an update?
* How do I fix the GUI after changing PHP version?
* How can I fix the GUI after changing my server's PHP version?
* How do I fix ionCube Loader errors?
* What are the steps to run the `install-gui.sh` script?
* How do I fix 500 server error after system update?
* How do I fix a corrupted `key.php` license file?
* How do I locate ionCube configuration files?
* How can I safely back up my GUI files before a reinstallation?
* How do I fix corrupted key.php license file?
* What is the command to download the latest GUI for a specific PHP version?
* What command downloads GUI for specific PHP version?
* How do I re-activate my license after performing a fresh install of the database?
* How do I update database schema after major upgrade?
* How can I use the licensetoken to restore my license without contacting support?
* How do I restore configuration.php from backup?
* What should I do before reinstalling the database to preserve my license?
* How do I re-activate license after fresh install?
* 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?

Latest revision as of 11:36, 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

  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

After major version upgrades, database schema may need updates.

Automatic (minor changes):

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.

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

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?
Retrieved from "https://www.voipmonitor.org/doc/index.php?title=Re-install_the_GUI&oldid=10330"