GUI installation: Difference between revisions

From VoIPmonitor.org
(Review: opravy formátování - přidání sekce License File Location, oprava Note/Tip šablon (přidání 1= a code tagů))
(Merge content from GUI_Installation (uppercase) - consolidated into single comprehensive page)
 
(2 intermediate revisions by the same user not shown)
Line 1: Line 1:
= GUI Installation =
= GUI Installation =


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


# Download the latest GUI tar.gz package from http://www.voipmonitor.org/download-gui?version=latest
{{Note|The GUI is separate from the sniffer/sensor. You need to install both - see [[Sniffer_installation|Sniffer Installation]].}}
# Untar to <code>/var/www/</code> (On Debian-like systems) or <code>/var/www/html</code> (On RedHat-like systems) and rename created folder to <code>voipmonitor</code>
# Open web browser and point it to <code>http://yourserver/voipmonitor</code> (you can choose whatever directory you want) and follow installation steps


{{Note|You need to install the sniffer too - see [[Sniffer_installation|Sniffer Installation]]}}
== Quick Start ==


== System 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


The VoIPmonitor GUI has specific hardware and software requirements.
== Prerequisites ==


=== Hardware Architecture Requirements ===
{| class="wikitable"
|-
! 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
|}


{{Warning|The VoIPmonitor GUI requires an '''x86 (32-bit or 64-bit) architecture system'''. The GUI is '''not supported''' on aarch64 (ARM64) platforms.}}
{{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.}}


If you need to run VoIPmonitor on ARM64/aarch64 hardware:
=== Hosting Environments ===
* 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
* This client-server architecture allows the ARM64 sensor to capture traffic while the x86 GUI provides the web interface


<kroki lang="mermaid">
{| class="wikitable"
%%{init: {'flowchart': {'nodeSpacing': 15, 'rankSpacing': 40}}}%%
|-
flowchart TB
! Environment !! License Status
    subgraph ARM64["ARM64 Server"]
|-
        S[Sensor/Sniffer]
| Docker, Kubernetes, LXC, Podman || Fully supported, no special licensing
        DB[(MySQL Database)]
|-
    end
| VMware, VirtualBox, KVM, Hyper-V || Works normally
    subgraph X86["x86 Server"]
|-
        GUI[Web GUI]
| AWS EC2, Azure VMs, GCP || Works normally
    end
|}
    S --> DB
    GUI --> DB
</kroki>


For more information about supported architectures, see the [[FAQ#What_hardware_architectures_does_the_GUI_support.3F|FAQ entry on architecture support]].
{{Note|1=For cloud instances: '''Stop/Start''' preserves Hardware ID (license OK). '''Terminate/Launch''' changes Hardware ID (requires license reconfiguration or domain-based licensing).}}


== Hosting Environments ==
== Installation Steps ==


The VoIPmonitor GUI is fully supported in various hosting environments.
=== Step 1: Prepare the Environment ===


=== Containerized Deployment (Docker, Kubernetes) ===
Install required packages:


Running the VoIPmonitor web UI inside a container (Docker, Kubernetes, or other containerization technologies) is '''fully supported''' and will '''not cause any licensing issues'''.
<syntaxhighlight lang="bash">
# Debian/Ubuntu
apt update
apt install apache2 php php-mysql php-gd php-curl php-mbstring mariadb-server unzip wget


The GUI license validation works normally in containerized environments without requiring special licensing configurations. You can run the GUI in a container without needing to contact support for domain-based licensing or multiple server licensing.
# RHEL/Rocky/AlmaLinux
dnf install httpd php php-mysqlnd php-gd php-curl php-mbstring mariadb-server unzip wget
</syntaxhighlight>


This applies to:
=== Step 2: Download and Extract ===
* Docker containers
* Kubernetes pods
* Other containerization technologies (LXC, Podman, etc.)
* Cloud-based container services (AWS ECS, Azure Container Instances, Google Cloud Run, etc.)


=== Virtual Machines and Cloud Instances ===
<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


The VoIPmonitor GUI also runs normally in virtualized environments:
# Extract to web root
tar xzf gui.tar.gz
mv voipmonitor-gui-* /var/www/html/voipmonitor


* '''VMware ESXi, VirtualBox, KVM, Hyper-V, QEMU/KVM''': The GUI license works without issues
# Set permissions
* '''AWS EC2, Google Cloud Platform, Azure VMs''': License validation works normally
chown -R www-data:www-data /var/www/html/voipmonitor  # Debian/Ubuntu
# OR
chown -R apache:apache /var/www/html/voipmonitor      # RHEL/Rocky
</syntaxhighlight>


{{Warning|1='''Important distinction for AWS/Cloud:'''
{{Warning|1=Download the GUI package matching your PHP version. Check with <code>php --version</code>.}}
* '''Stop/Start an instance''': The Hardware ID typically remains the same, so your license continues to work
* '''Terminate and launch a new instance''': The Hardware ID changes, requiring a new license or reconfiguration}}


If you frequently destroy and recreate cloud instances and want to avoid license reconfiguration, you may request domain-based licensing from VoIPmonitor support as an alternative to hardware ID binding.
=== Step 3: Complete Web Setup ===


== License Key ==
# Open browser: <code>http://yourserver/voipmonitor</code>
# Follow the installation wizard to configure database connection
# Enter license token (see [[#License Activation|License Activation]] below)


=== Obtaining a Trial License (30 Days) ===
=== Step 4: Configure Cron Job ===


For a new installation, you can obtain a 30-day trial license for testing purposes through one of the following methods:
The GUI requires a cron job for alerts, reports, and maintenance:


==== Method 1: Contact Support ====
<syntaxhighlight lang="bash">
echo "* * * * * root php /var/www/html/voipmonitor/php/run.php cron" >> /etc/crontab
</syntaxhighlight>


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 5: Configure Sniffer ===


==== Method 2: Members' Area (Automated) ====
Ensure the sniffer uses the '''same database''' as the GUI. Edit <code>/etc/voipmonitor.conf</code>:


Log in to the VoIPmonitor members' area and find the license token in the "my services" section.
<syntaxhighlight lang="ini">
mysqlhost = localhost
mysqldb = voipmonitor
mysqlusername = voipmonitor
mysqlpassword = your_password
</syntaxhighlight>


===== Troubleshooting Shopping Cart Issues =====
Then restart: <code>systemctl restart voipmonitor</code>


If you are unable to complete the trial order process (the checkout does not proceed):
== System Requirements ==


# Review the items in your shopping cart
=== Hardware Architecture ===
# Ensure there is only one trial product in the cart
# Remove any duplicate or conflicting items (multiple trial products can block checkout)
# Proceed with the checkout process once only one trial product remains


{{Tip|This is a common issue - accidentally adding the trial product multiple times to the shopping cart will prevent the automated order from completing.}}
{| class="wikitable"
|-
! Component !! Supported Architectures
|-
| '''Web GUI''' || x86 (32-bit and 64-bit) only
|-
| '''Sniffer''' || x86, ARMv7, ARMv8/ARM64
|}


===== Troubleshooting Email Verification Issues =====
{{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.}}


If you are using the Members' Area method and cannot receive the verification email:
For ARM64 deployments, use a split architecture:


# Check your inbox and spam/junk folder for the verification email
<kroki lang="mermaid">
# If the email contains a typo or is not found, contact support to manually resend the verification email to the correct email address
%%{init: {'flowchart': {'nodeSpacing': 15, 'rankSpacing': 40}}}%%
# Verification links are typically valid for 24 hours - if expired, request a new verification email
flowchart LR
    subgraph ARM64["ARM64 Server"]
        S[Sensor] --> DB[(MySQL)]
    end
    subgraph X86["x86 Server"]
        GUI[Web GUI]
    end
    GUI --> DB
</kroki>


If you continue to experience issues receiving the verification email, you can use Method 1 (Contact Support) as an alternative.
== License Activation ==


===== Troubleshooting "Only One Trial Is Allowed" Error =====
=== Obtaining a Trial License ===


When using the Members' Area, you may encounter an error stating that only one trial license is allowed. This occurs when:
Request a 30-day trial license:
* '''Option 1:''' Contact VoIPmonitor support
* '''Option 2:''' Generate via Members' Area at voipmonitor.org


* You previously used a trial license (even on a different or deleted server)
=== Activating the License ===
* The trial status in the back-end system was not properly reset after the trial expired
 
To resolve this issue:
 
# Contact VoIPmonitor support and explain that the automated portal is showing "only one trial is allowed" for your account
# 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.
 
=== License File Location ===
 
The license file is stored as <code>key.php</code> in the web root folder of your GUI installation (typically <code>/var/www/voipmonitor</code> or <code>/var/www/html/voipmonitor</code>).
 
To download a license key directly, visit: http://www.voipmonitor.org/download-gui?version=license
 
=== Troubleshooting "License token is empty" or "hwid invalid or corrupted" ===
 
If you encounter the error messages "license token is empty" and "hwid invalid or corrupted" during the initial VoIPmonitor GUI installation, this is typically caused by missing read permissions on the root block device. The GUI requires read access to <code>/dev/root</code> to detect the Hardware ID (HWID) for license activation.
 
==== Solution: Grant Read Permissions on /dev/root ====
 
To resolve this issue:
 
# SSH into the server where the GUI is installed
# Run the following command to grant read permissions on the root block device:
<syntaxhighlight lang="bash">
chmod +r /dev/root
</syntaxhighlight>
# Retry accessing the GUI in your web browser and complete the license activation
 
After granting read permissions, the GUI will be able to properly detect the Hardware ID and you can proceed with entering your license token or license key.
 
=== Activating a License in the GUI ===
 
VoIPmonitor GUI provides two separate activation methods depending on your scenario. Using the wrong method will result in a "Bad Key Content" error.


<kroki lang="mermaid">
<kroki lang="mermaid">
Line 149: Line 150:
flowchart TB
flowchart TB
     A{Internet Access?}
     A{Internet Access?}
     A -->|Yes| B[Online Activation]
     A -->|Yes| B["Online: Paste token in 'License token' field"]
     A -->|No| C[Offline Activation]
     A -->|No| C["Offline: Paste full key in 'License key' field"]
    B --> D["Use 'License token' field"]
     B --> D["Click 'get/update license key'"]
     B --> E["Click 'get/update license key'"]
    C --> F["Use 'License key' field"]
    C --> G["Paste full multi-line key"]
</kroki>
</kroki>


==== Online Activation (Recommended) ====
'''Online Activation''' (server has internet):
 
Use this method when your server has internet access and you have a license token from the Members' Area or support:
 
# Log in to the GUI
# Navigate to '''Settings > License'''
# Navigate to '''Settings > License'''
# Paste your '''license token''' (short text string, NOT the full key) into the '''"License token"''' field
# Paste the short token into '''"License token"''' field
# Click the '''"get/update license key"''' button
# Click '''"get/update license key"'''
# The GUI will automatically fetch and apply the full license from the license server


{{Warning|The "License token" field is for short tokens only. Do not paste the full multi-line license key into this field.}}
'''Offline Activation''' (air-gapped server):
# Get full multi-line key from support
# Paste entire key into '''"License key"''' field
# Save changes


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


Use this method when your server cannot connect to the license server (network restrictions, firewall, air-gapped environment):
=== License File Location ===


# Contact VoIPmonitor support to obtain the full, formatted license key
The license is stored in <code>key.php</code> in the GUI root directory (e.g., <code>/var/www/html/voipmonitor/key.php</code>).
# Log in to the GUI
# Navigate to '''Settings > License'''
# Paste the '''entire multi-line license key''' into the '''"License key"''' text field
# Ensure you copy all lines (Expires, id, hwid, maxcalls, upgradeexpire, etc.)
# Save the changes


{{Warning|The "License key" field is for the complete multi-line key. Do not paste a short token into this field.}}
==== Manual License Update ====


==== Troubleshooting "Bad Key Content" Error ====
If automatic activation fails:


If you receive a "Bad Key Content" error, you are likely using the wrong field:
<syntaxhighlight lang="bash">
# Download key from portal: Services > My services
# Copy content to key.php on server
# Verify:
php /var/www/voipmonitor/php/apilicensecheck.php?task=licenseCheck
</syntaxhighlight>


* '''Pasting a full license key into the "License token" field''' → This will fail. Use the "License key" field instead.
=== Channel-Based Licensing ===
* '''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.


==== Troubleshooting "Something is wrong on this configuration page" Error ====
* 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


If you receive the error message "Something is wrong on this configuration page. Check the content" when attempting to update your license, but you notice that the expiration date appears to change momentarily, you can use a trial license as a temporary workaround.
== Post-Installation ==


This error can occur due to various issues such as license server communication problems, license key validation issues, or file permission problems preventing the GUI from properly writing the updated license file.
=== Add Sensors (Multi-Sensor Setup) ===


'''Trial License Workaround:'''
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)


# Contact VoIPmonitor support to request a trial license token
See [[Settings#Sensors]] for detailed configuration.
# Navigate to '''Settings > License''' in the GUI
# Paste the trial license token into the '''"License token"''' field
# Click the '''"get/update license key"''' button
# This will apply a temporary 30-day trial license


This workaround allows you to continue using the GUI with full functionality while the underlying license update issue is investigated and resolved by support. The trial license serves as a temporary solution until the main license issue can be fixed.
== Distribution-Specific Guides ==


{{Note|After the main license issue is resolved, you can revert to your permanent license by clicking "get/update license key" with your original license token.}}
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


==== Troubleshooting Premature License Expiration Errors ====
== GUI Configuration Options ==


If your license appears to expire prematurely on a customer server, displaying an error even though the license is valid on the central VoIPmonitor server, this is typically caused by network connectivity issues preventing the GUI from reaching the license validation server.
Edit <code>config/system_configuration.php</code> to disable features:


'''Symptom:'''
<syntaxhighlight lang="php">
* License shows as expired or invalid on the customer server
define('DISABLE_LIVE_SNIFFER', true);  // Remove Live Sniffer menu
* Same license works correctly on the central server
define('DISABLE_REGISTER', true);      // Disable SIP Register view
* License expiration date in voipmonitor.org portal shows the license is still valid
define('DISABLE_CDR_SHARE', true);      // Disable CDR sharing feature
</syntaxhighlight>


'''Primary Cause: Network Blocking'''
For additional configuration constants, see [[GUI_Configuration_PHP]].


The GUI requires outbound HTTPS access to the license check server to validate and update the license. If the customer server is behind a restrictive firewall or has network routing issues, this validation fails, causing the GUI to report the license as expired.
== Troubleshooting ==


'''Diagnostic Steps:'''
=== "hwid invalid or corrupted" Error ===


From the affected customer server, test network connectivity to the license check server:
The GUI cannot read the Hardware ID.


'''Solution:'''
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Test DNS resolution
chmod +r /dev/root
ping -c 3 download.voipmonitor.org
 
# Test HTTPS connectivity
curl -I https://download.voipmonitor.org
</syntaxhighlight>
</syntaxhighlight>


If these commands fail or time out, the firewall or network configuration is blocking access to the license validation server.
=== "Missing sniffer tables" or "Table 'voipmonitor.cdr' doesn't exist" ===
 
'''Resolution:'''


1. '''Configure Firewall:''' Allow outbound HTTPS (TCP port 443) connections to <code>download.voipmonitor.org</code>
The GUI and sniffer are using different databases.


<syntaxhighlight lang="bash">
'''Solution:'''
# For firewalld
# Check GUI database settings in <code>/var/www/html/voipmonitor/config/configuration.php</code>
firewall-cmd --permanent --add-service=https
# Update sniffer config <code>/etc/voipmonitor.conf</code> to use the same database
firewall-cmd --reload
# Restart sniffer: <code>systemctl restart voipmonitor</code>


# For iptables
{{Warning|Do NOT run schema.sql to "fix" this - the tables already exist in the sniffer's database.}}
iptables -A OUTPUT -p tcp --dport 443 -d download.voipmonitor.org -j ACCEPT
service iptables save
</syntaxhighlight>


2. '''Check Proxy Settings:''' If your network uses a proxy server, ensure the GUI or PHP configuration includes the proper proxy settings:
=== HTTP 500 Errors ===


# Try a different browser or incognito mode
# Check PHP and web server error logs:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Check or set proxy environment variables
tail -f /var/log/apache2/error.log
export http_proxy=http://proxy.example.com:8080
# or
export https_proxy=http://proxy.example.com:8080
tail -f /var/log/nginx/error.log
</syntaxhighlight>
</syntaxhighlight>
 
# Verify IonCube Loader version matches PHP version
3. '''Verify Network Routing:''' Ensure there is no routing gateway or NAT configuration preventing HTTPS connections to external domains. Check with your network administrator if needed.
# Test PHP with info file:
 
'''Temporary Workaround:'''
 
As an immediate workaround to restore service before fixing the network configuration:
 
# Navigate to '''Settings > License''' in the GUI
# Click the '''"get/update license key"''' button
# This forces an immediate license check if the server is reachable at that moment
 
This manual update can temporarily restore functionality if the server has intermittent connectivity issues. However, permanent resolution requires fixing the firewall or network configuration to allow consistent access to <code>download.voipmonitor.org</code> over HTTPS.
 
==== Manually Updating License from Customer Portal ====
 
Use this method when you need to update the license file directly from the VoIPmonitor customer portal (for example, when the GUI license interface is not working properly, or when you need to manually replace the <code>key.php</code> file).
 
# Log in to the VoIPmonitor customer portal
# Navigate to '''Services > My services'''
# Find your license in the list and click the '''license''' button
# Copy the entire license key content displayed
# Locate the <code>key.php</code> file on your GUI server (typically in <code>/var/www/voipmonitor</code> or <code>/var/www/html/voipmonitor</code>)
# Replace the entire content of <code>key.php</code> with the new license key from the portal
# Verify the license is updated by running:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
php /var/www/voipmonitor/php/apilicensecheck.php?task=licenseCheck
echo "<?php phpinfo(); ?>" > /var/www/html/info.php
# Then access http://your-server/info.php
</syntaxhighlight>
</syntaxhighlight>


{{Warning|1=When pasting the key content, replace ALL previous content (do not append or partially update). Ensure you have the correct file permissions set (web server user, e.g., <code>www-data</code> or <code>apache</code>, must be able to read the file).}}
=== ionCube Loader Errors ===
 
See also: [[WEB_API#Check_License|Check License API]] for verifying license status.
 
=== Extending a Trial License ===
 
If your testing period requires more than 30 days, you can request a trial license extension:


# Contact VoIPmonitor support to request an extension of your trial license
The ionCube Loader version doesn't match PHP version.
# After the license is extended by support, apply the update in the GUI by clicking the '''"get/update license key"''' button
# You do not need to change your server ID when extending the license


=== Full Licenses ===
'''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


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.
See [[Re-install_the_GUI]] for details.


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


See the [[FAQ]] for more information about licensing, including:
# Verify MySQL/MariaDB is running: <code>systemctl status mysql</code>
* How to calculate the number of channels you need
# Test connection: <code>mysql -u voipmonitor -p voipmonitor</code>
* What happens if you temporarily exceed your license limit
# Check credentials in GUI configuration
* License warning and blocking behavior
* Upgrading your license via the customer portal


=== Retrieving a License Token from an Existing Installation ===
=== "Crontab log is empty" ===


If you need to find the license token for an existing VoIPmonitor installation (for example, to set up a new development or test system), you can retrieve it using one of the following methods:
The cron job is not configured or not running.
 
==== Method 1: Retrieve from the GUI ====
 
This is the recommended method for retrieving your license token:
 
# Log in to your existing VoIPmonitor GUI
# Navigate to '''Settings > License'''
# Locate the '''"License token"''' field
# Copy the short text string displayed there
 
==== Method 2: Retrieve from key.php File (Alternative) ====
 
If you cannot access the GUI or need to recover the license programmatically, the <code>key.php</code> file in your GUI installation directory contains the license information.
 
# Navigate to your GUI installation directory (typically <code>/var/www/html/voipmonitor</code> or <code>/var/www/voipmonitor</code>)
# Open the <code>key.php</code> file in a text editor
# The file contains the license information including the license ID
 
You can use the license ID found in <code>key.php</code> to retrieve your full license from the GUI or by contacting VoIPmonitor support.
 
==== Using the Token on a New Development/Test System ====
 
The license token is cryptographically bound to the Hardware ID (HWID) of the server it was generated for.
 
* '''If the new test system has the SAME Hardware ID''' (e.g., a cloned VM or restored backup): You can paste this token directly into the '''"License token"''' field on the new system and click '''"get/update license key"'''.
* '''If the new test system has a DIFFERENT Hardware ID''' (e.g., a new VM or physical server): The token from the old installation '''will not work''' automatically.
** '''Solution:''' Contact VoIPmonitor support to have your license token reconfigured to allow multiple servers (specifically for the test/dev environment). Once support adds the new HWID to your license, you can use the same token or a new one provided by them.
 
See also: [[License#Can_I_use_my_license_on_multiple_servers|Can I use my license on multiple servers?]]
 
== GUI Configuration (system_configuration.php) ==
 
The <code>config/system_configuration.php</code> file allows disabling some features.
 
=== Disable Live Sniffer Menu ===
 
To completely remove the Live Sniffer functionality from the GUI (including the menu item), edit the <code>config/system_configuration.php</code> file:
 
<syntaxhighlight lang="php">
define('DISABLE_LIVE_SNIFFER', true);
</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>).
 
{{Warning|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.}}
 
=== Other Feature Disabling Options ===
 
<syntaxhighlight lang="php">
define('DISABLE_ISSUE_TRACKER', true);
define('DISABLE_REGISTER', true);
define('DISABLE_CDR_SHARE', true);
define('WIKI_URL', 'http://voipmonitor.org');  // Custom wiki URL
// define('WIKI_URL', false);                  // Disable wiki link
define('APP_WEB', 'http://voipmonitor.org');
</syntaxhighlight>
 
== Troubleshooting Common Installation Issues ==
 
=== "Missing sniffer tables", "Crontab log is empty", and "Table 'voipmonitor.cdr' doesn't exist" Errors ===
 
If you see these errors in the GUI after installation, it typically indicates that the GUI and sniffer are configured to use different databases, or the GUI cron job is not running.
 
{{Warning|This is NOT a missing schema issue. Do NOT run schema.sql as this will likely recreate tables that already exist elsewhere.}}
 
==== Root Cause ====
 
These errors commonly occur when:
# The GUI installation created or configured a database (e.g., via the GUI setup wizard)
# The sniffer is installed but its configuration (`/etc/voipmonitor.conf`) is pointing to a different database or default settings
# The GUI's maintenance cron job was not added to the system crontab
 
==== Solution ====
 
'''1. Configure the Sniffer to Use the GUI's Database'''
 
Edit the sniffer configuration file and ensure it connects to the same database that the GUI uses:


'''Solution:'''
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
sudo nano /etc/voipmonitor.conf
# Add cron job
</syntaxhighlight>
echo "* * * * * root php /var/www/html/voipmonitor/php/run.php cron" >> /etc/crontab
 
Set the MySQL connection parameters to match your GUI database:


<syntaxhighlight lang="ini">
# Test manually
# MySQL connection (these must match the GUI database)
php /var/www/html/voipmonitor/php/run.php cron
mysqlhost = localhost
mysqlport = 3306
mysqldb = voipmonitor
mysqlusername = root
mysqlpassword = your_password
</syntaxhighlight>
</syntaxhighlight>


{{Tip|1=You can check which database the GUI is using by looking at the GUI's configuration file at <code>/var/www/voipmonitor/config/configuration.php</code> (or the path where you installed the GUI). Look for the variable named <code>$USERDB</code> or similar database configuration options.}}
=== License Shows Expired When Valid ===
 
'''2. Add the GUI Cron Job'''


The GUI requires a cron job to run maintenance tasks. Add it to the system crontab:
The server cannot reach the license validation server.


'''Diagnostic:'''
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Add the GUI cron job to the system crontab
curl -I https://download.voipmonitor.org
# Replace /var/www/voipmonitor with your actual GUI installation path
echo "* * * * * root php /var/www/voipmonitor/php/run.php cron" | sudo tee -a /etc/crontab
</syntaxhighlight>
</syntaxhighlight>


{{Note|1=The cron job should run once per minute (<code>* * * * *</code>). Ensure the path to <code>run.php</code> matches your GUI installation directory.}}
'''Solution:''' Allow outbound HTTPS (port 443) to <code>download.voipmonitor.org</code> in your firewall.


'''3. Restart the Sniffer Service'''
== See Also ==


Apply the configuration changes by restarting the sniffer:
* [[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


<syntaxhighlight lang="bash">
[[Category:Installation]]
# Restart using systemd (modern distributions)
sudo systemctl restart voipmonitor


# OR restart using init.d (older distributions)
sudo /etc/init.d/voipmonitor restart
</syntaxhighlight>
'''4. Verify the Fix'''
Refresh the GUI in your browser (press Ctrl+F5 for a hard refresh). The "Missing sniffer tables" error should disappear, and you should see data populating in the dashboard if traffic is being captured.
{{Note|The "Crontab log is empty" message may persist briefly (up to one minute) until the cron job has executed at least once. You can force it to run immediately by executing the command manually: <code>sudo php /var/www/voipmonitor/php/run.php cron</code>}}
=== Sniffer Not Writing to GUI Database but GUI Database Exists ===
If the database exists and has tables, but the sniffer is not capturing data, verify the database connection:
<syntaxhighlight lang="bash">
# Test connection using the credentials from voipmonitor.conf
mysql -h localhost -P 3306 -u root -p voipmonitor
</syntaxhighlight>
If you can connect manually, check the sniffer logs for database connection errors:
<syntaxhighlight lang="bash">
# View sniffer logs
sudo journalctl -u voipmonitor -f
# OR for init.d systems
sudo tail -f /var/log/voipmonitor/voipmonitor.log
</syntaxhighlight>
Look for error messages like "MySQL connection failed" or "Can't connect to MySQL server". These indicate a connectivity or authentication issue.


== AI Summary for RAG ==
== AI Summary for RAG ==


'''Summary:''' VoIPmonitor GUI installation guide covering download, extraction, and setup wizard. The GUI requires x86 architecture (ARM64 not supported for GUI, only sensor can be compiled for ARM). Fully supported in Docker, Kubernetes, and cloud environments (AWS, Azure, GCP) without special licensing. For cloud instances: Stop/Start preserves Hardware ID; Terminate/Launch requires license reconfiguration.
'''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.
 
'''License Activation:''' Two methods exist - Online (paste short token into "License token" field, click "get/update") and Offline (paste full multi-line key into "License key" field). Using wrong field causes "Bad Key Content" error.
 
'''Common Installation Issues:'''
* "Missing sniffer tables", "Crontab log is empty", and "Table 'voipmonitor.cdr' doesn't exist": Caused by GUI and sniffer configured to use different databases. Fix: Configure sniffer's `mysqlhost`, `mysqlport`, `mysqldb`, `mysqlusername`, `mysqlpassword` in `/etc/voipmonitor.conf` to match GUI database, add cron job `* * * * * root php /var/www/voipmonitor/php/run.php cron` to `/etc/crontab`, restart sniffer service. Do NOT run schema.sql.
* Sniffer not writing to GUI database: Check database connection with `mysql -h ...` and sniffer logs via `journalctl -u voipmonitor -f`
* "hwid invalid or corrupted" during installation: Run <code>chmod +r /dev/root</code>
* Premature license expiration: Check firewall allows HTTPS to <code>download.voipmonitor.org</code>
* Trial limitations: Contact support if "only one trial allowed" error appears
* Configuration page errors: Use trial license as temporary workaround


'''Keywords:''' gui installation, trial license, license activation, license token, license key, bad key content, hwid invalid, /dev/root permissions, docker, kubernetes, container, cloud instance, aws ec2, azure, gcp, hardware id, offline activation, online activation, key.php, system_configuration.php, DISABLE_LIVE_SNIFFER, missing sniffer tables, crontab log is empty, table voipmonitor.cdr does not exist, cron job, run.php cron
'''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:'''
'''Key Questions:'''
* How do I install the VoIPmonitor GUI?
* How do I install the VoIPmonitor GUI?
* What architecture does the GUI require (x86 vs ARM64)?
* What PHP version do I need for VoIPmonitor GUI?
* Does the GUI work in Docker/Kubernetes containers?
* 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?
* What is the difference between "License token" and "License key" fields?
* How do I fix "hwid invalid or corrupted" error during installation?
* How do I fix "hwid invalid or corrupted" error?
* Why does my license show as expired when it should be valid?
* How do I fix "Missing sniffer tables" error?
* How do I obtain a 30-day trial license?
* How do I add the GUI cron job?
* How do I extend a trial license?
* Where is the VoIPmonitor license file stored (key.php)?
* What causes "Bad Key Content" error when activating license?
* How do I manually update the license from the customer portal?
* Can I use my license on multiple servers?
* How do I disable Live Sniffer in the GUI?
* How do I disable Live Sniffer in the GUI?
* How do I fix "Missing sniffer tables", "Crontab log is empty", and "Table 'voipmonitor.cdr' doesn't exist" errors?
* Where do I configure the GUI cron job (run.php cron)?
* How do I make the sniffer use the same database as the GUI?

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"