Re-install the GUI: Difference between revisions

From VoIPmonitor.org
(Add section on re-activating license after fresh database install using licensetoken)
m (Reverted edits by Admin (talk) to last revision by Festr)
Tag: Rollback
 
(20 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>).
 
{{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.}}
 
=== Step 2: Backup Current GUI ===


== Step 2: Back Up Your Current GUI Directory ==
<syntaxhighlight lang="bash">
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>
# The default path is /var/www/html, but adjust if you have a custom path
sudo cp -a /var/www/html /var/www/html-backup-$(date +%F)
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. 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.


== Step 4: Finalize the Installation in Your Browser ==
'''Automatic (minor changes):'''
After the script finishes, you must complete the process in your web browser.
* Navigate to <code>http://your-gui.com/?check_tables=1</code>
* Or: '''Tools → System Status → Check MySQL Schema'''


;1. Open the VoIPmonitor GUI in your browser.
'''Manual (major changes):'''
;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).
<syntaxhighlight lang="bash">
# Check logs for ALTER recommendations
sudo journalctl -u voipmonitor -n 50 | grep -i "alter"


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.
# Execute in MySQL (run during off-peak hours - ALTERs lock tables)
mysql -u root -p
# Paste ALTER commands from logs
</syntaxhighlight>
 
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 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` 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"