GUI installation: Difference between revisions

From VoIPmonitor.org
(Add shopping cart troubleshooting to AI Summary for better RAG retrieval)
(Merge content from GUI_Installation (uppercase) - consolidated into single comprehensive page)
 
(12 intermediate revisions by the same user not shown)
Line 1: Line 1:
*Download the latest GUI tar.gz package from http://www.voipmonitor.org/download-gui?version=latest
= GUI Installation =
*Untar to /var/www/ (On debian like systems) or /var/www/html (On redhat like systems) and rename created folder to voipmonitor
*Open web browser and point it to voipmonitor http://yourserver/voipmonitor (you can choose whatever directory you want) and follow installation steps


Note: you need to install the sniffer too - complete installation [[Content#Installaion]]
This guide covers installing the VoIPmonitor Web GUI. The GUI is a PHP web application for viewing CDR data and managing sensors.


= System Requirements =
{{Note|The GUI is separate from the sniffer/sensor. You need to install both - see [[Sniffer_installation|Sniffer Installation]].}}


The VoIPmonitor GUI has specific hardware and software requirements.
== Quick Start ==


=== Hardware Architecture Requirements ===
# Download the latest GUI package from http://www.voipmonitor.org/download-gui?version=latest
# Extract to <code>/var/www/html/</code> (RHEL/CentOS) or <code>/var/www/</code> (Debian/Ubuntu)
# Rename the extracted folder to <code>voipmonitor</code>
# Open <code>http://your-server/voipmonitor</code> in a browser and follow the installation wizard


'''IMPORTANT:''' The VoIPmonitor GUI requires an '''x86 (32-bit or 64-bit) architecture system'''. The GUI is '''not supported''' on aarch64 (ARM64) platforms.
== Prerequisites ==


If you need to run VoIPmonitor on ARM64/aarch64 hardware:
{| class="wikitable"
* The '''sensor/sniffer component''' can be '''compiled from source''' for ARM64 architectures - see [[Sniffer_installation#Compiling_from_Source|Compiling from Source]]
|-
* You must run the '''GUI on a separate x86 system''' that connects to the ARM64 sensor's database
! Component !! Requirement
* This client-server architecture allows the ARM64 sensor to capture traffic while the x86 GUI provides the web interface
|-
| '''Architecture''' || x86 (32/64-bit) only. '''ARM64 not supported''' for GUI.
|-
| '''Web Server''' || Apache2 or Nginx with PHP support
|-
| '''PHP''' || 7.4, 8.1, 8.2, or 8.3 with ionCube Loader
|-
| '''Database''' || MySQL 5.7+ or MariaDB 10.3+
|-
| '''Extensions''' || php-mysql, php-gd, php-curl, php-mbstring, php-zip, php-cli
|}


For more information about supported architectures, see the [[FAQ#What_hardware_architectures_does_the_GUI_support.3F|FAQ entry on architecture support]].
{{Tip|For ARM64 systems: Compile the [[Sniffer_installation#Compiling_from_Source|sensor from source]] on ARM64, then run GUI on a separate x86 server connecting to the same database.}}


= License key =
=== Hosting Environments ===


== Obtaining a Trial License (30 Days) ==
{| class="wikitable"
|-
! Environment !! License Status
|-
| Docker, Kubernetes, LXC, Podman || Fully supported, no special licensing
|-
| VMware, VirtualBox, KVM, Hyper-V || Works normally
|-
| AWS EC2, Azure VMs, GCP || Works normally
|}


For a new installation, you can obtain a 30-day trial license for testing purposes through one of the following methods:
{{Note|1=For cloud instances: '''Stop/Start''' preserves Hardware ID (license OK). '''Terminate/Launch''' changes Hardware ID (requires license reconfiguration or domain-based licensing).}}


=== Method 1: Contact Support ===
== Installation Steps ==


Send a request to the VoIPmonitor support team to obtain a trial license. This method is useful if you encounter issues with automated license generation.
=== Step 1: Prepare the Environment ===


=== Method 2: Members' Area (Automated) ===
Install required packages:


Log in to the VoIPmonitor members' area and find the license token in the "my services" section.
<syntaxhighlight lang="bash">
# Debian/Ubuntu
apt update
apt install apache2 php php-mysql php-gd php-curl php-mbstring mariadb-server unzip wget


==== Troubleshooting Shopping Cart Issues ====
# RHEL/Rocky/AlmaLinux
dnf install httpd php php-mysqlnd php-gd php-curl php-mbstring mariadb-server unzip wget
</syntaxhighlight>
 
=== Step 2: Download and Extract ===
 
<syntaxhighlight lang="bash">
# Download latest GUI (replace phpver with your PHP version: 74, 81, 82, 83)
cd /tmp
wget "https://www.voipmonitor.org/download-gui?version=latest&major=5&allowed&phpver=81" -O gui.tar.gz


If you are unable to complete the trial order process (the checkout does not proceed):
# Extract to web root
tar xzf gui.tar.gz
mv voipmonitor-gui-* /var/www/html/voipmonitor


# Review the items in your shopping cart
# Set permissions
# Ensure there is only one trial product in the cart
chown -R www-data:www-data /var/www/html/voipmonitor  # Debian/Ubuntu
# Remove any duplicate or conflicting items (multiple trial products can block checkout)
# OR
# Proceed with the checkout process once only one trial product remains
chown -R apache:apache /var/www/html/voipmonitor      # RHEL/Rocky
</syntaxhighlight>


This is a common issue - accidentally adding the trial product multiple times to the shopping cart will prevent the automated order from completing.
{{Warning|1=Download the GUI package matching your PHP version. Check with <code>php --version</code>.}}


==== Troubleshooting Email Verification Issues ====
=== Step 3: Complete Web Setup ===


If you are using the Members' Area method and cannot receive the verification email:
# Open browser: <code>http://yourserver/voipmonitor</code>
# Follow the installation wizard to configure database connection
# Enter license token (see [[#License Activation|License Activation]] below)


# Check your inbox and spam/junk folder for the verification email
=== Step 4: Configure Cron Job ===
# If the email contains a typo or is not found, contact support to manually resend the verification email to the correct email address
# Verification links are typically valid for 24 hours - if expired, request a new verification email


If you continue to experience issues receiving the verification email, you can use Method 1 (Contact Support) as an alternative.
The GUI requires a cron job for alerts, reports, and maintenance:


==== Troubleshooting "Only One Trial Is Allowed" Error ====
<syntaxhighlight lang="bash">
echo "* * * * * root php /var/www/html/voipmonitor/php/run.php cron" >> /etc/crontab
</syntaxhighlight>


When using the Members' Area, you may encounter an error stating that only one trial license is allowed. This occurs when:
=== Step 5: Configure Sniffer ===


* You previously used a trial license (even on a different or deleted server)
Ensure the sniffer uses the '''same database''' as the GUI. Edit <code>/etc/voipmonitor.conf</code>:
* The trial status in the back-end system was not properly reset after the trial expired


To resolve this issue:
<syntaxhighlight lang="ini">
mysqlhost = localhost
mysqldb = voipmonitor
mysqlusername = voipmonitor
mysqlpassword = your_password
</syntaxhighlight>


# Contact VoIPmonitor support and explain that the automated portal is showing "only one trial is allowed" for your account
Then restart: <code>systemctl restart voipmonitor</code>
# Specify that you need a trial license for a new installation or testing environment
# Support will manually correct the trial license status in the back-end system
# Once the status is corrected, return to the Members' Area and generate the trial license through the normal automated process


Alternatively, you can bypass this issue entirely by using Method 1 (Contact Support) to request a manual trial license issuance.
== System Requirements ==


To download the license key, visit: http://www.voipmonitor.org/download-gui?version=license
=== Hardware Architecture ===


The license file is located in the web root folder as <code>key.php</code>
{| class="wikitable"
|-
! Component !! Supported Architectures
|-
| '''Web GUI''' || x86 (32-bit and 64-bit) only
|-
| '''Sniffer''' || x86, ARMv7, ARMv8/ARM64
|}


== Activating a License in the GUI ==
{{Warning|The GUI does '''NOT''' support ARM64/aarch64 architecture. If you need to run on ARM64, deploy the sniffer on ARM and connect it to a GUI running on a separate x86 server.}}


VoIPmonitor GUI provides two separate activation methods depending on your scenario. Using the wrong method will result in a "Bad Key Content" error.
For ARM64 deployments, use a split architecture:


=== Online Activation (Recommended) ===
<kroki lang="mermaid">
%%{init: {'flowchart': {'nodeSpacing': 15, 'rankSpacing': 40}}}%%
flowchart LR
    subgraph ARM64["ARM64 Server"]
        S[Sensor] --> DB[(MySQL)]
    end
    subgraph X86["x86 Server"]
        GUI[Web GUI]
    end
    GUI --> DB
</kroki>


Use this method when your server has internet access and you have a license token from the Members' Area or support:
== License Activation ==


# Log in to the GUI
=== Obtaining a Trial License ===
# Navigate to '''Settings > License'''
# Paste your '''license token''' (short text string, NOT the full key) into the '''"License token"''' field
# Click the '''"get/update license key"''' button
# The GUI will automatically fetch and apply the full license from the license server


'''Important:''' The "License token" field is for short tokens only. Do not paste the full multi-line license key into this field.
Request a 30-day trial license:
* '''Option 1:''' Contact VoIPmonitor support
* '''Option 2:''' Generate via Members' Area at voipmonitor.org


=== Offline Activation ===
=== Activating the License ===


Use this method when your server cannot connect to the license server (network restrictions, firewall, air-gapped environment):
<kroki lang="mermaid">
%%{init: {'flowchart': {'nodeSpacing': 15, 'rankSpacing': 40}}}%%
flowchart TB
    A{Internet Access?}
    A -->|Yes| B["Online: Paste token in 'License token' field"]
    A -->|No| C["Offline: Paste full key in 'License key' field"]
    B --> D["Click 'get/update license key'"]
</kroki>


# Contact VoIPmonitor support to obtain the full, formatted license key
'''Online Activation''' (server has internet):
# Log in to the GUI
# Navigate to '''Settings > License'''
# Navigate to '''Settings > License'''
# Paste the '''entire multi-line license key''' into the '''"License key"''' text field
# Paste the short token into '''"License token"''' field
# Ensure you copy all lines (Expires, id, hwid, maxcalls, upgradeexpire, etc.)
# Click '''"get/update license key"'''
# Save the changes


'''Important:''' The "License key" field is for the complete multi-line key. Do not paste a short token into this field.
'''Offline Activation''' (air-gapped server):
# Get full multi-line key from support
# Paste entire key into '''"License key"''' field
# Save changes


=== Troubleshooting "Bad Key Content" Error ===
{{Warning|1=Using the wrong field causes "Bad Key Content" error. Token = short string, Key = multi-line text.}}


If you receive a "Bad Key Content" error, you are likely using the wrong field:
=== License File Location ===


* '''Pasting a full license key into the "License token" field''' → This will fail. Use the "License key" field instead.
The license is stored in <code>key.php</code> in the GUI root directory (e.g., <code>/var/www/html/voipmonitor/key.php</code>).
* '''Pasting a short token into the "License key" field''' → This will fail. Use the "License token" field instead and click "get/update license key".
* '''Incomplete license key''' → For offline activation, ensure you copied ALL lines of the multi-line key.


== Extending a Trial License ==
==== Manual License Update ====


If your testing period requires more than 30 days, you can request a trial license extension:
If automatic activation fails:


# Contact VoIPmonitor support to request an extension of your trial license
<syntaxhighlight lang="bash">
# After the license is extended by support, apply the update in the GUI by clicking the '''"get/update license key"''' button
# Download key from portal: Services > My services
# You do not need to change your server ID when extending the license
# Copy content to key.php on server
# Verify:
php /var/www/voipmonitor/php/apilicensecheck.php?task=licenseCheck
</syntaxhighlight>


== Full Licenses ==
=== Channel-Based Licensing ===


For production use, you can purchase a full license through the VoIPmonitor customer portal. Your license is based on the '''maximum number of concurrent calls''' during your peak hours.
* License is based on '''maximum concurrent calls''' (channels)
* Check current usage: '''Tools > System Status > Concurrent calls'''
* Grace period: If limit exceeded, GUI locks after 14 days
* See [[License]] for detailed information


You can view your current license status and concurrent call usage in the GUI under '''Tools -> System Status -> Concurrent calls'''.
== Post-Installation ==


See the [[FAQ]] for more information about licensing, including:
=== Add Sensors (Multi-Sensor Setup) ===
* How to calculate the number of channels you need
* What happens if you temporarily exceed your license limit
* License warning and blocking behavior
* Upgrading your license via the customer portal


= config/system_configuration.php =
For distributed deployments with multiple sensors:
# In GUI: '''Settings > Sensors > Add'''
# Enter Sensor ID (must match <code>id_sensor</code> in sniffer config)
# Enter Manager IP and Port (default: 5029)


This file allows disabling some features
See [[Settings#Sensors]] for detailed configuration.


=== Disable Live Sniffer Menu ===
== Distribution-Specific Guides ==


To completely remove the Live Sniffer functionality from the GUI (including the menu item), edit the <code>config/system_configuration.php</code> file:
For detailed step-by-step installation on specific distributions, see:
* [[Debian_12]] - Debian 12 (Bookworm) installation
* [[Rocky_9]] - Rocky Linux 9 / AlmaLinux 9 installation
* [[Ubuntu_24.04_LTS]] - Ubuntu 24.04 LTS installation
 
== GUI Configuration Options ==
 
Edit <code>config/system_configuration.php</code> to disable features:


<syntaxhighlight lang="php">
<syntaxhighlight lang="php">
define('DISABLE_LIVE_SNIFFER', true);
define('DISABLE_LIVE_SNIFFER', true);   // Remove Live Sniffer menu
define('DISABLE_REGISTER', true);      // Disable SIP Register view
define('DISABLE_CDR_SHARE', true);      // Disable CDR sharing feature
</syntaxhighlight>
</syntaxhighlight>


When enabled, this constant removes the entire Live Sniffer menu item from the GUI. This is different from hiding play buttons (see FAQ for <code>DISABLE_LIVEPLAY</code>).
For additional configuration constants, see [[GUI_Configuration_PHP]].


'''Important Security Note:''' Even with <code>DISABLE_LIVE_SNIFFER</code> enabled, users with administrator privileges can override global capture settings to enable recording or listening for specific calls. For strict compliance scenarios, ensure users are not granted administrator privileges.
== Troubleshooting ==


=== Other Feature Disabling Options ===
=== "hwid invalid or corrupted" Error ===
 
The GUI cannot read the Hardware ID.
 
'''Solution:'''
<syntaxhighlight lang="bash">
chmod +r /dev/root
</syntaxhighlight>
 
=== "Missing sniffer tables" or "Table 'voipmonitor.cdr' doesn't exist" ===
 
The GUI and sniffer are using different databases.
 
'''Solution:'''
# Check GUI database settings in <code>/var/www/html/voipmonitor/config/configuration.php</code>
# Update sniffer config <code>/etc/voipmonitor.conf</code> to use the same database
# Restart sniffer: <code>systemctl restart voipmonitor</code>
 
{{Warning|Do NOT run schema.sql to "fix" this - the tables already exist in the sniffer's database.}}
 
=== HTTP 500 Errors ===
 
# Try a different browser or incognito mode
# Check PHP and web server error logs:
<syntaxhighlight lang="bash">
tail -f /var/log/apache2/error.log
# or
tail -f /var/log/nginx/error.log
</syntaxhighlight>
# Verify IonCube Loader version matches PHP version
# Test PHP with info file:
<syntaxhighlight lang="bash">
echo "<?php phpinfo(); ?>" > /var/www/html/info.php
# Then access http://your-server/info.php
</syntaxhighlight>
 
=== ionCube Loader Errors ===
 
The ionCube Loader version doesn't match PHP version.
 
'''Solution:'''
# Check PHP version: <code>php --version</code>
# Download correct IonCube loader from [https://www.ioncube.com/loaders.php ioncube.com]
# Place in PHP extensions directory
# Add to php.ini: <code>zend_extension = /path/to/ioncube_loader.so</code>
# Restart web server
 
See [[Re-install_the_GUI]] for details.
 
=== Database Connection Issues ===
 
# Verify MySQL/MariaDB is running: <code>systemctl status mysql</code>
# Test connection: <code>mysql -u voipmonitor -p voipmonitor</code>
# Check credentials in GUI configuration
 
=== "Crontab log is empty" ===
 
The cron job is not configured or not running.
 
'''Solution:'''
<syntaxhighlight lang="bash">
# Add cron job
echo "* * * * * root php /var/www/html/voipmonitor/php/run.php cron" >> /etc/crontab
 
# Test manually
php /var/www/html/voipmonitor/php/run.php cron
</syntaxhighlight>
 
=== License Shows Expired When Valid ===
 
The server cannot reach the license validation server.
 
'''Diagnostic:'''
<syntaxhighlight lang="bash">
curl -I https://download.voipmonitor.org
</syntaxhighlight>
 
'''Solution:''' Allow outbound HTTPS (port 443) to <code>download.voipmonitor.org</code> in your firewall.
 
== See Also ==
 
* [[Sniffer_installation]] - Install the packet capture sensor
* [[Re-install_the_GUI]] - Reinstall or upgrade the GUI
* [[License]] - Detailed licensing information
* [[GUI_troubleshooting]] - Additional troubleshooting
* [[GUI_Configuration_PHP]] - Advanced configuration options
* [[Nginx]] - Configure Nginx as reverse proxy
 
[[Category:Installation]]


define('DISABLE_ISSUE_TRACKER', true);
define('DISABLE_REGISTER', true);
define('DISABLE_CDR_SHARE', true);
define('WIKI_URL', 'http://voipmonitor.org');
define('WIKI_URL', false);
define('APP_WEB', 'http://voipmonitor.org');


== AI Summary for RAG ==
== AI Summary for RAG ==
'''Summary:''' This guide covers the VoIPmonitor GUI installation process, including downloading the package, extracting files, and running the installation wizard. It provides detailed information about obtaining trial licenses (30-day) for new testing installations, including two methods: contacting support or finding license tokens in the "my services" section of the members' area. For the Members' Area method, it includes troubleshooting steps for common issues. First, if you are unable to complete the trial order process (checkout does not proceed), this is typically caused by having multiple trial products in the shopping cart - you must review the cart, ensure only one trial product exists, remove any duplicate or conflicting items, then proceed with checkout. Second, it covers email verification issues: checking spam/junk folders, contacting support to manually resend verification emails, and understanding that verification links are valid for 24 hours. Third, it includes troubleshooting for the "only one trial is allowed" error, which occurs when a previous trial was used; the solution is to contact support to manually correct the trial status in the back-end system, then return to the Members' Area to generate the trial. Alternatively, users can bypass issues by directly contacting support for manual trial issuance. The guide explains how to extend trial licenses beyond 30 days by contacting support and using the "get/update license" button in the GUI without needing to change the server ID.


CRITICAL: License activation in the GUI uses TWO SEPARATE FIELDS. For ONLINE activation (server has internet access), paste the SHORT "license token" into the "License token" field and click "get/update license key" button to automatically fetch the license. For OFFLINE activation (air-gapped or restricted networks), paste the COMPLETE multi-line LICENSE KEY (Expires, id, hwid, maxcalls, upgradeexpire, etc.) into the "License key" field and save. Common "Bad Key Content" errors are caused by using the WRONG field: pasting a full key into "License token" or a short token into "License key" will fail. Also ensure the offline key includes ALL lines, not just the first line.
'''Summary:''' VoIPmonitor GUI installation guide. Prerequisites: x86 architecture (ARM64 not supported for GUI), PHP 7.4/8.x with ionCube, MySQL/MariaDB, Apache/Nginx. Installation steps: (1) Install packages, (2) Download GUI matching PHP version, (3) Extract to webroot, (4) Run web setup wizard, (5) Add cron job for run.php, (6) Configure sniffer to use same database. Docker/Kubernetes/cloud fully supported. License activation: Online uses "License token" field + click button, Offline uses "License key" field with full multi-line key. Common issues: "hwid invalid" = run chmod +r /dev/root; "Missing sniffer tables" = GUI and sniffer using different databases (fix sniffer config, don't run schema.sql); "Crontab log empty" = add cron job.
 
'''Keywords:''' gui installation, web interface, php installation, ionCube, trial license, license activation, license token, license key, bad key content, hwid invalid, /dev/root, docker, kubernetes, container, arm64, x86, missing sniffer tables, crontab log empty, cdr table missing, cron job, run.php, system_configuration.php, DISABLE_LIVE_SNIFFER


It also covers full license purchasing, which is based on maximum concurrent calls during peak hours, and references the FAQ for more details on license calculation, exceeding limits, warnings, blocking behavior, and upgrading licenses. The config/system_configuration.php file allows disabling specific features like live sniffer (DISABLE_LIVE_SNIFFER to remove menu), issue tracker, registration, and CDR sharing. IMPORTANT: DISABLE_LIVE_SNIFFER removes the menu item entirely, while DISABLE_LIVEPLAY only hides play buttons. Admin users can override capture settings to enable recording, so avoid granting admin privileges for strict compliance scenarios.
'''Keywords:''' gui installation, trial license, 30-day trial, license extension, my services, members area, get/update license, concurrent calls, server id, full license, customer portal, license key, license token, online activation, offline activation, bad key content, license token field, license key field, key.php, system configuration, disable features, only one trial allowed, trial status, back-end system, DISABLE_LIVE_SNIFFER, DISABLE_LIVEPLAY, disable live sniffer, disable issue tracker, disable registration, admin privileges, override capture settings, compliance, shopping cart, duplicate products, trial order, checkout, unable to complete order
'''Key Questions:'''
'''Key Questions:'''
* What is the difference between "license token" and "license key" fields in the GUI?
* How do I install the VoIPmonitor GUI?
* Which field should I use for online license activation in VoIPmonitor?
* What PHP version do I need for VoIPmonitor GUI?
* Which field should I use for offline license activation in VoIPmonitor?
* Does VoIPmonitor GUI work on ARM64?
* Why do I get "Bad Key Content" error when pasting my license?
* Does VoIPmonitor GUI work in Docker/Kubernetes?
* How do I activate a license online using a token?
* How do I activate a VoIPmonitor license?
* How do I activate a license offline using the full key?
* What is the difference between "License token" and "License key" fields?
* What should I paste into the "License token" field?
* How do I fix "hwid invalid or corrupted" error?
* What should I paste into the "License key" field?
* How do I fix "Missing sniffer tables" error?
* How do I obtain a trial license for VoIPmonitor?
* How do I add the GUI cron job?
* What is the trial license period?
* Where is the VoIPmonitor license file stored (key.php)?
* How can I get a trial license for a new VoIPmonitor installation?
* How do I disable Live Sniffer in the GUI?
* Where do I find my license token for VoIPmonitor?
* How do I extend my VoIPmonitor trial license beyond 30 days?
* Do I need to change my server ID when extending my license?
* How is the VoIPmonitor license calculated?
* What happens if I exceed my license limit?
* What is the "get/update license" button in the GUI?
* Where do I check my VoIPmonitor license status and concurrent calls?
* What should I do if I cannot complete the trial order process?
* Why does my trial order checkout fail?
* How do I fix duplicate trial products in my shopping cart?
* What should I do if I cannot receive the verification email for a trial license?
* How long is the trial license verification link valid?
* Can support resend the verification email if I made a typo in my email address?
* What should I do if I get an "only one trial is allowed" error?
* How can I fix the trial license status to generate a new trial?
* Why does the automated portal block my trial request?

Latest revision as of 01:18, 10 January 2026

GUI Installation

This guide covers installing the VoIPmonitor Web GUI. The GUI is a PHP web application for viewing CDR data and managing sensors.

ℹ️ Note: The GUI is separate from the sniffer/sensor. You need to install both - see Sniffer Installation.

Quick Start

  1. Download the latest GUI package from http://www.voipmonitor.org/download-gui?version=latest
  2. Extract to /var/www/html/ (RHEL/CentOS) or /var/www/ (Debian/Ubuntu)
  3. Rename the extracted folder to voipmonitor
  4. Open http://your-server/voipmonitor in a browser and follow the installation wizard

Prerequisites

Component Requirement
Architecture x86 (32/64-bit) only. ARM64 not supported for GUI.
Web Server Apache2 or Nginx with PHP support
PHP 7.4, 8.1, 8.2, or 8.3 with ionCube Loader
Database MySQL 5.7+ or MariaDB 10.3+
Extensions php-mysql, php-gd, php-curl, php-mbstring, php-zip, php-cli

💡 Tip: For ARM64 systems: Compile the sensor from source on ARM64, then run GUI on a separate x86 server connecting to the same database.

Hosting Environments

Environment License Status
Docker, Kubernetes, LXC, Podman Fully supported, no special licensing
VMware, VirtualBox, KVM, Hyper-V Works normally
AWS EC2, Azure VMs, GCP Works normally

ℹ️ Note: For cloud instances: Stop/Start preserves Hardware ID (license OK). Terminate/Launch changes Hardware ID (requires license reconfiguration or domain-based licensing).

Installation Steps

Step 1: Prepare the Environment

Install required packages: 

# Debian/Ubuntu
apt update
apt install apache2 php php-mysql php-gd php-curl php-mbstring mariadb-server unzip wget

# RHEL/Rocky/AlmaLinux
dnf install httpd php php-mysqlnd php-gd php-curl php-mbstring mariadb-server unzip wget

Step 2: Download and Extract

# Download latest GUI (replace phpver with your PHP version: 74, 81, 82, 83)
cd /tmp
wget "https://www.voipmonitor.org/download-gui?version=latest&major=5&allowed&phpver=81" -O gui.tar.gz

# Extract to web root
tar xzf gui.tar.gz
mv voipmonitor-gui-* /var/www/html/voipmonitor

# Set permissions
chown -R www-data:www-data /var/www/html/voipmonitor  # Debian/Ubuntu
# OR
chown -R apache:apache /var/www/html/voipmonitor       # RHEL/Rocky

⚠️ Warning: Download the GUI package matching your PHP version. Check with php --version.

Step 3: Complete Web Setup

  1. Open browser: http://yourserver/voipmonitor
  2. Follow the installation wizard to configure database connection
  3. Enter license token (see License Activation below)

Step 4: Configure Cron Job

The GUI requires a cron job for alerts, reports, and maintenance: 

echo "* * * * * root php /var/www/html/voipmonitor/php/run.php cron" >> /etc/crontab

Step 5: Configure Sniffer

Ensure the sniffer uses the same database as the GUI. Edit /etc/voipmonitor.conf: 

mysqlhost = localhost
mysqldb = voipmonitor
mysqlusername = voipmonitor
mysqlpassword = your_password

Then restart: systemctl restart voipmonitor

System Requirements

Hardware Architecture

Component Supported Architectures
Web GUI x86 (32-bit and 64-bit) only
Sniffer x86, ARMv7, ARMv8/ARM64

⚠️ Warning: The GUI does NOT support ARM64/aarch64 architecture. If you need to run on ARM64, deploy the sniffer on ARM and connect it to a GUI running on a separate x86 server.

For ARM64 deployments, use a split architecture:

License Activation

Obtaining a Trial License

Request a 30-day trial license:

  • Option 1: Contact VoIPmonitor support
  • Option 2: Generate via Members' Area at voipmonitor.org

Activating the License

Online Activation (server has internet):

  1. Navigate to Settings > License
  2. Paste the short token into "License token" field
  3. Click "get/update license key"

Offline Activation (air-gapped server):

  1. Get full multi-line key from support
  2. Paste entire key into "License key" field
  3. Save changes

⚠️ Warning: Using the wrong field causes "Bad Key Content" error. Token = short string, Key = multi-line text.

License File Location

The license is stored in key.php in the GUI root directory (e.g., /var/www/html/voipmonitor/key.php).

Manual License Update

If automatic activation fails: 

# Download key from portal: Services > My services
# Copy content to key.php on server
# Verify:
php /var/www/voipmonitor/php/apilicensecheck.php?task=licenseCheck

Channel-Based Licensing

  • License is based on maximum concurrent calls (channels)
  • Check current usage: Tools > System Status > Concurrent calls
  • Grace period: If limit exceeded, GUI locks after 14 days
  • See License for detailed information

Post-Installation

Add Sensors (Multi-Sensor Setup)

For distributed deployments with multiple sensors:

  1. In GUI: Settings > Sensors > Add
  2. Enter Sensor ID (must match id_sensor in sniffer config)
  3. Enter Manager IP and Port (default: 5029)

See Settings#Sensors for detailed configuration.

Distribution-Specific Guides

For detailed step-by-step installation on specific distributions, see:

GUI Configuration Options

Edit config/system_configuration.php to disable features: 

define('DISABLE_LIVE_SNIFFER', true);   // Remove Live Sniffer menu
define('DISABLE_REGISTER', true);       // Disable SIP Register view
define('DISABLE_CDR_SHARE', true);      // Disable CDR sharing feature

For additional configuration constants, see GUI_Configuration_PHP.

Troubleshooting

"hwid invalid or corrupted" Error

The GUI cannot read the Hardware ID.

Solution: 

chmod +r /dev/root

"Missing sniffer tables" or "Table 'voipmonitor.cdr' doesn't exist"

The GUI and sniffer are using different databases.

Solution:

  1. Check GUI database settings in /var/www/html/voipmonitor/config/configuration.php
  2. Update sniffer config /etc/voipmonitor.conf to use the same database
  3. Restart sniffer: systemctl restart voipmonitor

⚠️ Warning: Do NOT run schema.sql to "fix" this - the tables already exist in the sniffer's database.

HTTP 500 Errors

  1. Try a different browser or incognito mode
  2. Check PHP and web server error logs:
tail -f /var/log/apache2/error.log
# or
tail -f /var/log/nginx/error.log
  1. Verify IonCube Loader version matches PHP version
  2. Test PHP with info file:
echo "<?php phpinfo(); ?>" > /var/www/html/info.php
# Then access http://your-server/info.php

ionCube Loader Errors

The ionCube Loader version doesn't match PHP version.

Solution:

  1. Check PHP version: php --version
  2. Download correct IonCube loader from ioncube.com
  3. Place in PHP extensions directory
  4. Add to php.ini: zend_extension = /path/to/ioncube_loader.so
  5. Restart web server

See Re-install_the_GUI for details.

Database Connection Issues

  1. Verify MySQL/MariaDB is running: systemctl status mysql
  2. Test connection: mysql -u voipmonitor -p voipmonitor
  3. Check credentials in GUI configuration

"Crontab log is empty"

The cron job is not configured or not running.

Solution: 

# Add cron job
echo "* * * * * root php /var/www/html/voipmonitor/php/run.php cron" >> /etc/crontab

# Test manually
php /var/www/html/voipmonitor/php/run.php cron

License Shows Expired When Valid

The server cannot reach the license validation server.

Diagnostic: 

curl -I https://download.voipmonitor.org

Solution: Allow outbound HTTPS (port 443) to download.voipmonitor.org in your firewall.

See Also


AI Summary for RAG

Summary: VoIPmonitor GUI installation guide. Prerequisites: x86 architecture (ARM64 not supported for GUI), PHP 7.4/8.x with ionCube, MySQL/MariaDB, Apache/Nginx. Installation steps: (1) Install packages, (2) Download GUI matching PHP version, (3) Extract to webroot, (4) Run web setup wizard, (5) Add cron job for run.php, (6) Configure sniffer to use same database. Docker/Kubernetes/cloud fully supported. License activation: Online uses "License token" field + click button, Offline uses "License key" field with full multi-line key. Common issues: "hwid invalid" = run chmod +r /dev/root; "Missing sniffer tables" = GUI and sniffer using different databases (fix sniffer config, don't run schema.sql); "Crontab log empty" = add cron job.

Keywords: gui installation, web interface, php installation, ionCube, trial license, license activation, license token, license key, bad key content, hwid invalid, /dev/root, docker, kubernetes, container, arm64, x86, missing sniffer tables, crontab log empty, cdr table missing, cron job, run.php, system_configuration.php, DISABLE_LIVE_SNIFFER

Key Questions:

  • How do I install the VoIPmonitor GUI?
  • What PHP version do I need for VoIPmonitor GUI?
  • Does VoIPmonitor GUI work on ARM64?
  • Does VoIPmonitor GUI work in Docker/Kubernetes?
  • How do I activate a VoIPmonitor license?
  • What is the difference between "License token" and "License key" fields?
  • How do I fix "hwid invalid or corrupted" error?
  • How do I fix "Missing sniffer tables" error?
  • How do I add the GUI cron job?
  • Where is the VoIPmonitor license file stored (key.php)?
  • How do I disable Live Sniffer in the GUI?
Retrieved from "https://www.voipmonitor.org/doc/index.php?title=GUI_installation&oldid=10489"