Re-install the GUI: Difference between revisions

From VoIPmonitor.org
(Add troubleshooting section for missing GUI files and disk space errors)
m (Reverted edits by Admin (talk) to last revision by Festr)
Tag: Rollback
 
(13 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.


'''Important: Watch for tar extraction errors.''' Pay close attention to the output of the <code>tar</code> 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:
Press '''Enter''' to confirm the default installation path. The script preserves your <code>configuration.php</code> and sets permissions automatically.
<pre>
df -h
</pre>


== Step 4: Finalize the Installation 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.}}
After the script finishes, you must complete the process in your web browser.


;1. Open the VoIPmonitor GUI in your browser.
'''Alternative: Manual Installation'''
;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.
If the automated script fails:
<syntaxhighlight lang="bash">
# Empty web directory (careful!)
sudo rm -rf /var/www/html/*


=== GUI Fails with ionCube Loader Error After Upgrade ===
# 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


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


'''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.
{{Warning|1=Watch for '''"No space left on device"''' errors during tar extraction. Check disk space: <code>df -h</code>}}


;1. Confirm your PHP version:
=== Step 4: Finalize in Browser ===
<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:
# Open the VoIPmonitor GUI in your browser
<pre>
# Perform a hard refresh: '''Ctrl+Shift+R''' (or '''Cmd+Shift+R''' on Mac)
mkdir /tmp/voipmonitor-gui-install
cd /tmp/voipmonitor-gui-install


# For PHP 8.2 (example - change as needed for your version)
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=82" -O gui.tar.gz


# Or for PHP 8.1:
== Offline Installation ==
# 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.
For servers without internet access:


This process replaces only the GUI application files while preserving your configuration and CDR data.
# '''On a machine with internet:''' Download GUI package using wget command from Step 3
# '''Transfer:''' Copy <code>gui.tar.gz</code> to the offline server via SCP or USB
# '''On offline server:''' Follow Steps 2-4 above


=== 500 Server Error After System Update (ionCube Configuration) ===
== Database Schema Updates ==


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.
After major version upgrades, database schema may need updates.


;1. Identify the active PHP version:
'''Automatic (minor changes):'''
<pre>
* Navigate to <code>http://your-gui.com/?check_tables=1</code>
php --version
* Or: '''Tools → System Status → Check MySQL Schema'''
</pre>
Look for the first two numbers (e.g., ''8.2'', ''8.1'', ''7.4'').


;2. Locate all ionCube configuration files:
'''Manual (major changes):'''
<pre>
<syntaxhighlight lang="bash">
grep ioncube /etc/* -Inri
# Check logs for ALTER recommendations
</pre>
sudo journalctl -u voipmonitor -n 50 | grep -i "alter"
This search will list all locations in `/etc` that contain ionCube references. Common locations include:
* <code>/etc/php.d/01_ioncube.ini</code>
* <code>/etc/php.d/ioncube.ini</code>
* <code>/etc/php.ini</code>


;3. Review the ionCube configuration files:
# Execute in MySQL (run during off-peak hours - ALTERs lock tables)
<pre>
mysql -u root -p
cat /etc/php.d/01_ioncube.ini
# Paste ALTER commands from logs
cat /etc/php.d/ioncube.ini
</syntaxhighlight>
</pre>
Check which PHP version the loader was compiled for. For example, a loader named <code>ioncube_loader_lin_7.4.so</code> 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:
For high-traffic environments, consider the '''migration instance method''' to avoid downtime. See [[Redundant_database]] for details.
<pre>
# 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
== Troubleshooting ==
sudo nano /etc/php.d/01_ioncube.ini
# Change: zend_extension = /path/to/wrong/loader.so
# To:    ; zend_extension = /path/to/wrong/loader.so
</pre>


;5. Ensure only the correct ionCube loader for the active PHP version is enabled:
=== ionCube Loader Error ===
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:
If GUI displays ionCube error (including "undefined symbol: zend_string_initerned") after PHP upgrade:
<pre>
grep -n ioncube /etc/php.ini
</pre>
If ionCube references are found in your main <code>php.ini</code> file:
<pre>
sudo nano /etc/php.ini
# Comment out or remove these duplicate entries
</pre>


;7. Restart the web server service:
{{Warning|1=Do NOT downgrade PHP. VoIPmonitor provides GUI packages for PHP 7.4, 8.0, 8.1, and 8.2.}}
<pre>
# On RHEL/CentOS/AlmaLinux/Fedora:
sudo systemctl restart httpd


# On Debian/Ubuntu:
'''Solution:''' Re-download GUI for your web server's PHP version:
sudo systemctl restart apache2
<syntaxhighlight lang="bash">
# or
# First verify web server PHP version (may differ from CLI)
sudo systemctl restart php-fpm
echo '<?php phpinfo(); ?>' > /var/www/html/test.php
</pre>
# Check http://your-server/test.php, then remove test file


;8. Verify the fix:
# Re-download correct version
<pre>
wget "https://www.voipmonitor.org/download-gui?version=latest&major=5&allowed&phpver=82" -O gui.tar.gz
php --version
# Follow Step 3 installation
</pre>
</syntaxhighlight>
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|https://downloads.ioncube.com/loader_downloads/ioncube_loaders_lin_x86-64.tar.gz]].
'''Alternative:''' Download ionCube directly from [https://downloads.ioncube.com/loader_downloads/ioncube_loaders_lin_x86-64.tar.gz ioncube.com] and configure manually.


== Database Schema Updates for Major Version Upgrades ==
=== 500 Server Error (ionCube Config) ===
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) ===
After system update, 500 errors may indicate ionCube configs pointing to wrong PHP version:
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) ===
<syntaxhighlight lang="bash">
After a major version upgrade, the VoIPmonitor sniffer may recommend specific database ALTER commands in its logs. Follow this procedure:
# Find ionCube config files
grep ioncube /etc/* -Inri


;1. Restart the sniffer service:
# Check what version they reference
<pre>sudo systemctl restart voipmonitor</pre>
cat /etc/php.d/01_ioncube.ini


;2. Check the logs for ALTER recommendations:
# Remove or comment out configs for wrong PHP version
<pre>
sudo rm /etc/php.d/01_ioncube.ini  # Or edit and comment with ;
# On systems using journalctl
sudo journalctl -u voipmonitor -n 50 | grep -i "alter"


# On systems using syslog
# Also check main php.ini
sudo tail -n 50 /var/log/syslog | grep -i "alter"
grep -n ioncube /etc/php.ini
</pre>


;3. '''Important Timing Considerations:'''
# Restart web server
* ALTER commands lock tables and will temporarily pause CDR ingestion
sudo systemctl restart httpd  # Or apache2 / php-fpm
* '''Run ALTER commands during off-peak hours''' to minimize production impact
</syntaxhighlight>
* You can run the ALTER commands directly in the database while the sniffer continues to capture packets


;4. Execute the ALTER commands:
=== Empty Path Error After Reinstall ===
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 fails with "empty path" error in <code>fce_config.php</code>, the <code>configuration.php</code> was corrupted:
<pre>sudo systemctl restart voipmonitor</pre>


=== Migration Instance Alternative (High-Traffic Environments) ===
<syntaxhighlight lang="bash">
If you cannot afford the downtime caused by ALTER commands locking tables, consider using the '''migration instance method''':
# Restore from backup
sudo cp /var/www/html-backup-YYYY-MM-DD/config/configuration.php /var/www/html/config/
</syntaxhighlight>


;1. Set up a new MySQL/MariaDB instance with the latest schema
{{Tip|If no backup exists, navigate to GUI URL to re-run the installation wizard and enter database credentials.}}
;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 ===
=== 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.
If GUI asks for license token but you have a valid license:
<syntaxhighlight lang="bash">
sudo rm /var/www/html/key.php
</syntaxhighlight>
Refresh GUI and click '''"get license key"''' to fetch a fresh copy.


;1. Check the tar command output:
=== Re-activating License After Fresh Install ===
Review the output from the <code>tar</code> 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:
# '''Before reinstall:''' Copy ''licensetoken'' from '''Settings → License'''
<pre>
# '''After reinstall:''' Paste token into activation form and click '''"get/update license key"'''
df -h
</pre>
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:
If Hardware ID changed (new server), click '''"Get License"''' in '''Settings → License''' to re-synchronize.
After freeing up disk space, repeat the installation procedure starting from [[Step 1: Identify Your Server's PHP Version|Re-install_the_GUI #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.
== See Also ==
* [[GUI_installation]] - Fresh GUI installation
* [[GUI_troubleshooting]] - General GUI issues
* [[License]] - License management
* [[Redundant_database]] - Migration instance method


=== Corrupted License File ===
== AI Summary for RAG ==
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:
# Remove the old license file from your GUI's installation directory.
#<pre>sudo rm /var/www/html/key.php</pre>
# Refresh the GUI page in your browser.
# 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:
# Log in to your current VoIPmonitor GUI.
# Navigate to '''Settings > License'''.
# Copy the entire ''licensetoken'' string displayed on this page.


;After the fresh database install and new GUI setup:
'''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).
# 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:''' 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).
'''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


== 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. A new troubleshooting subsection covers '''Missing GUI Files After Installation''', a common issue where GUI files appear missing or incomplete after installation. This typically occurs when package extraction fails due to insufficient disk space. The key diagnostic step is to carefully review the `tar` command output during extraction for error messages such as '''"No space left on device"''' or '''"Cannot write"'''. The solution involves: 1) Checking available disk space with `df -h`. 2) If the disk is full, removing unnecessary files (old compressed PCAP files, logs) to free up at least several gigabytes. 3) Re-downloading and reinstalling only after sufficient disk space is available. This section includes the critical warning that reinstalling without first addressing the disk space issue will cause the same incomplete installation failure.
'''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, missing files, incomplete installation, disk space, full disk, "No space left on device", `df -h`, tar extraction error, Cannot write, Rocky Linux, RHEL, CentOS, AlmaLinux, fresh 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?
* 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?
* What should I do if GUI files are missing after installation?
* Why does GUI installation fail on Rocky Linux 9?
* How can I tell if my GUI installation is incomplete?
* What tar error messages indicate disk space problems?
* What do I do if tar shows "No space left on device"?
* How do I check available disk space before installing GUI?
* What command shows if my disk has enough space for VoIPmonitor?
* Why are GUI files missing after a fresh installation?
* How do I diagnose incomplete GUI package extraction?
* What errors indicate tar extraction failed due to disk space?
* How much disk space do I need to install VoIPmonitor GUI?

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"