Re-install the GUI: Difference between revisions

From VoIPmonitor.org
No edit summary
m (Reverted edits by Admin (talk) to last revision by Festr)
Tag: Rollback
 
(21 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>


== Step 3: Download and Run the Installer ==
{{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.}}
This process involves downloading the latest GUI package and running its installation script.


;1. Create a temporary directory and download the GUI package:
=== Step 3: Download and Install ===
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>
<syntaxhighlight lang="bash">
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. 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.
 
Press '''Enter''' to confirm the default installation path. The script preserves your <code>configuration.php</code> and sets permissions automatically.
 
{{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.}}
 
'''Alternative: Manual Installation'''
 
If the automated script fails:
<syntaxhighlight lang="bash">
# 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/
</syntaxhighlight>
 
{{Warning|1=Watch for '''"No space left on device"''' errors during tar extraction. Check disk space: <code>df -h</code>}}
 
=== Step 4: Finalize in Browser ===
 
# Open the VoIPmonitor GUI in your browser
# 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:
 
# '''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
 
== Database Schema Updates ==
 
After major version upgrades, database schema may need updates.
 
'''Automatic (minor changes):'''
* Navigate to <code>http://your-gui.com/?check_tables=1</code>
* Or: '''Tools → System Status → Check MySQL Schema'''


== Step 4: Finalize the Installation in Your Browser ==
'''Manual (major changes):'''
After the script finishes, you must complete the process in your web browser.
<syntaxhighlight lang="bash">
# Check logs for ALTER recommendations
sudo journalctl -u voipmonitor -n 50 | grep -i "alter"


;1. Open the VoIPmonitor GUI in your browser.
# Execute in MySQL (run during off-peak hours - ALTERs lock tables)
;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).
mysql -u root -p
# Paste ALTER commands from logs
</syntaxhighlight>


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.
For high-traffic environments, consider the '''migration instance method''' to avoid downtime. See [[Redundant_database]] for details.


== Troubleshooting ==
== Troubleshooting ==
=== ionCube Loader Error ===
If GUI displays ionCube error (including "undefined symbol: zend_string_initerned") after PHP upgrade:
{{Warning|1=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:
<syntaxhighlight lang="bash">
# 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
</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.}}
=== 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 Install ===
 
# '''Before reinstall:''' Copy ''licensetoken'' from '''Settings → License'''
# '''After reinstall:''' Paste token into activation form and click '''"get/update license key"'''
 
If Hardware ID changed (new server), click '''"Get License"''' in '''Settings → License''' to re-synchronize.
 
== See Also ==
* [[GUI_installation]] - Fresh GUI installation
* [[GUI_troubleshooting]] - General GUI issues
* [[License]] - License management
* [[Redundant_database]] - Migration instance method


== AI Summary for RAG ==
== 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` and then running the included `install-gui.sh` script. 4) Finalizing the process with a hard browser refresh (Ctrl+Shift+R) to clear the cache. A troubleshooting section explains how to resolve a corrupted license by deleting the `key.php` file and re-fetching the license via the GUI.
 
'''Keywords:''' reinstall, reinstalling, GUI, fix, corrupted, upgrade, PHP version, `install-gui.sh`, `key.php`, license, backup, web interface, `a2enmod`, `wget`
'''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 update database schema after major upgrade?
* How do I restore configuration.php from backup?
* How do I re-activate license after fresh install?

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"