Re-install the GUI: Difference between revisions

From VoIPmonitor.org
m (Reverted edits by Admin (talk) to last revision by Festr)
Tag: Rollback
 
(31 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{DISPLAYTITLE:How to Reinstall the Web GUI}}


= In some rare situations the GUI can gets corrupted =
'''This guide provides a step-by-step process for safely reinstalling the VoIPmonitor web GUI without losing your data or configuration.'''


'''For example:'''
== When to Reinstall ==
# Out of space and upgrade of the GUI already started
# Power loss or kernel crashed during the GUI upgrade
# File system corruption (you need to fix filesystem before proceeding with re-install)


== Re-install the GUI using the install script ==
A reinstallation overwrites GUI application files while preserving your data (CDRs, PCAPs) and configuration (<code>config/configuration.php</code>). Use this procedure when:
''(this requires to have already GUI working before. This howto not covers the ioncube and php packages install steps)''
* 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


'''1)Find php version on a server where is the GUI installed'''
{{Note|This guide assumes you have a previously working GUI with all PHP dependencies (ionCube Loader) already installed.}}
php --version
'''2)You can backup current GUI's files for sure. (It depends on where you have it installed, by default it is in /var/www/html'''
cp -a /var/www/html /var/www/html-bakcup


'''3)Download and unpack the GUI'''
<kroki lang="mermaid">
mkdir /tmp/gui
%%{init: {'flowchart': {'nodeSpacing': 15, 'rankSpacing': 35}}}%%
cd /tmp/gui
flowchart TD
#This is example how to download GUI for php version 5.4 - change ```phpver``` if you need download for different version (or check links list at bottom if this page)
    A[GUI Not Working] --> B{Identify Issue}
wget "http://www.voipmonitor.org/download-gui?version=latest&major=5&allowed&phpver=54" -O w.tar.gz
    B -->|Corrupted/PHP Upgrade| C[Check PHP Version]
tar xzf w.tar.gz
    C --> D[Backup GUI]
cd voipmonitor-gui-*/scripts/
    D --> E[Download & Install]
bash install-gui ../../w.tar.gz
    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>


''(And finish the installation press ENTER to confirm GUI install dir)''
== Installation Steps ==


'''4)Refresh the browser to finish the installation'''
=== Step 1: Identify PHP Version ===


''(in chrome press CTRL+SHIFT+R to flush cache and reload the GUI page)''
The GUI package must match your PHP major version:
<syntaxhighlight lang="bash">
php --version
</syntaxhighlight>
Note the first two numbers (e.g., <code>8.1</code>, <code>8.2</code>, <code>7.4</code>).


'''5)In case that key.php (license file) gets corrupted'''
{{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.}}


''(remove it from GUI installation dir, and refresh the browser. GUI will ask you for license token again, and you can obtain your licence (key.php) with click on a button 'get license key')''
=== Step 2: Backup Current GUI ===


== Links list of latest GUI packages for various php versions ==
<syntaxhighlight lang="bash">
'''php 5.1,5.2'''
sudo cp -a /var/www/html /var/www/html-backup-$(date +%F)
wget 'http://www.voipmonitor.org/download-gui?version=latest&allowed&phpver=5' -O w.tar.gz
</syntaxhighlight>


'''php 5.3'''
{{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.}}
wget 'http://www.voipmonitor.org/download-gui?version=latest&allowed&phpver=53' -O w.tar.gz


'''php 5.4,5.5,5.6,7.0'''
=== Step 3: Download and Install ===
wget 'http://www.voipmonitor.org/download-gui?version=latest&allowed&phpver=56' -O w.tar.gz


'''php 7.1,7.2'''
<syntaxhighlight lang="bash">
wget 'http://www.voipmonitor.org/download-gui?version=latest&allowed&phpver=71' -O w.tar.gz
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
</syntaxhighlight>
 
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'''
 
'''Manual (major changes):'''
<syntaxhighlight lang="bash">
# 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
</syntaxhighlight>
 
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|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 ===
 
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.
 
=== 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 ==
 
'''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:'''
* 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?

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"