GUI installation: Difference between revisions

From VoIPmonitor.org
(Review: oprava struktury nadpisů, formátování kódu (pre->syntaxhighlight), markdown->wiki syntax, zkrácení AI Summary)
(Merge content from GUI_Installation (uppercase) - consolidated into single comprehensive page)
 
(5 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
|}


'''IMPORTANT:''' 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


For more information about supported architectures, see the [[FAQ#What_hardware_architectures_does_the_GUI_support.3F|FAQ entry on architecture support]].
{| 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
|}


== Hosting Environments ==
{{Note|1=For cloud instances: '''Stop/Start''' preserves Hardware ID (license OK). '''Terminate/Launch''' changes Hardware ID (requires license reconfiguration or domain-based licensing).}}


The VoIPmonitor GUI is fully supported in various hosting environments.
== Installation Steps ==


=== Containerized Deployment (Docker, Kubernetes) ===
=== Step 1: Prepare the Environment ===


Running the VoIPmonitor web UI inside a container (Docker, Kubernetes, or other containerization technologies) is '''fully supported''' and will '''not cause any licensing issues'''.
Install required packages:


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.
<syntaxhighlight lang="bash">
# Debian/Ubuntu
apt update
apt install apache2 php php-mysql php-gd php-curl php-mbstring mariadb-server unzip wget


This applies to:
# RHEL/Rocky/AlmaLinux
* Docker containers
dnf install httpd php php-mysqlnd php-gd php-curl php-mbstring mariadb-server unzip wget
* Kubernetes pods
</syntaxhighlight>
* Other containerization technologies (LXC, Podman, etc.)
* Cloud-based container services (AWS ECS, Azure Container Instances, Google Cloud Run, etc.)


=== Virtual Machines and Cloud Instances ===
=== Step 2: Download and Extract ===


The VoIPmonitor GUI also runs normally in virtualized environments:
<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


* '''VMware ESXi, VirtualBox, KVM, Hyper-V, QEMU/KVM''': The GUI license works without issues
# Extract to web root
* '''AWS EC2, Google Cloud Platform, Azure VMs''': License validation works normally
tar xzf gui.tar.gz
mv voipmonitor-gui-* /var/www/html/voipmonitor


'''Important distinction for AWS/Cloud:'''
# Set permissions
* '''Stop/Start an instance''': The Hardware ID typically remains the same, so your license continues to work
chown -R www-data:www-data /var/www/html/voipmonitor  # Debian/Ubuntu
* '''Terminate and launch a new instance''': The Hardware ID changes, requiring a new license or reconfiguration
# OR
chown -R apache:apache /var/www/html/voipmonitor      # RHEL/Rocky
</syntaxhighlight>


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.
{{Warning|1=Download the GUI package matching your PHP version. Check with <code>php --version</code>.}}


== License Key ==
=== Step 3: Complete Web Setup ===


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


For a new installation, you can obtain a 30-day trial license for testing purposes through one of the following methods:
=== Step 4: Configure Cron Job ===


==== Method 1: Contact Support ====
The GUI requires a cron job for alerts, reports, and maintenance:


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.
<syntaxhighlight lang="bash">
echo "* * * * * root php /var/www/html/voipmonitor/php/run.php cron" >> /etc/crontab
</syntaxhighlight>


==== Method 2: Members' Area (Automated) ====
=== Step 5: Configure Sniffer ===


Log in to the VoIPmonitor members' area and find the license token in the "my services" section.
Ensure the sniffer uses the '''same database''' as the GUI. Edit <code>/etc/voipmonitor.conf</code>:


===== Troubleshooting Shopping Cart Issues =====
<syntaxhighlight lang="ini">
mysqlhost = localhost
mysqldb = voipmonitor
mysqlusername = voipmonitor
mysqlpassword = your_password
</syntaxhighlight>


If you are unable to complete the trial order process (the checkout does not proceed):
Then restart: <code>systemctl restart voipmonitor</code>


# Review the items in your shopping cart
== System Requirements ==
# 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


This is a common issue - accidentally adding the trial product multiple times to the shopping cart will prevent the automated order from completing.
=== Hardware Architecture ===


===== Troubleshooting Email Verification Issues =====
{| class="wikitable"
|-
! Component !! Supported Architectures
|-
| '''Web GUI''' || x86 (32-bit and 64-bit) only
|-
| '''Sniffer''' || x86, ARMv7, ARMv8/ARM64
|}


If you are using the Members' Area method and cannot receive the verification email:
{{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.}}


# Check your inbox and spam/junk folder for the verification email
For ARM64 deployments, use a split architecture:
# 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.
<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>


===== Troubleshooting "Only One Trial Is Allowed" Error =====
== License Activation ==


When using the Members' Area, you may encounter an error stating that only one trial license is allowed. This occurs when:
=== Obtaining a Trial License ===


* You previously used a trial license (even on a different or deleted server)
Request a 30-day trial license:
* The trial status in the back-end system was not properly reset after the trial expired
* '''Option 1:''' Contact VoIPmonitor support
* '''Option 2:''' Generate via Members' Area at voipmonitor.org


To resolve this issue:
=== Activating the License ===


# Contact VoIPmonitor support and explain that the automated portal is showing "only one trial is allowed" for your account
<kroki lang="mermaid">
# Specify that you need a trial license for a new installation or testing environment
%%{init: {'flowchart': {'nodeSpacing': 15, 'rankSpacing': 40}}}%%
# Support will manually correct the trial license status in the back-end system
flowchart TB
# Once the status is corrected, return to the Members' Area and generate the trial license through the normal automated process
    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>


Alternatively, you can bypass this issue entirely by using Method 1 (Contact Support) to request a manual trial license issuance.
'''Online Activation''' (server has internet):
# Navigate to '''Settings > License'''
# Paste the short token into '''"License token"''' field
# Click '''"get/update license key"'''


To download the license key, visit: http://www.voipmonitor.org/download-gui?version=license
'''Offline Activation''' (air-gapped server):
# Get full multi-line key from support
# Paste entire key into '''"License key"''' field
# Save changes


The license file is located in the web root folder as <code>key.php</code>
{{Warning|1=Using the wrong field causes "Bad Key Content" error. Token = short string, Key = multi-line text.}}


=== Troubleshooting "License token is empty" or "hwid invalid or corrupted" ===
=== License File Location ===


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.
The license is stored in <code>key.php</code> in the GUI root directory (e.g., <code>/var/www/html/voipmonitor/key.php</code>).


==== Solution: Grant Read Permissions on /dev/root ====
==== Manual License Update ====


To resolve this issue:
If automatic activation fails:


# 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">
<syntaxhighlight lang="bash">
chmod +r /dev/root
# 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>
</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.
=== Channel-Based Licensing ===


=== Activating a License in the GUI ===
* 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


VoIPmonitor GUI provides two separate activation methods depending on your scenario. Using the wrong method will result in a "Bad Key Content" error.
== Post-Installation ==


==== Online Activation (Recommended) ====
=== Add Sensors (Multi-Sensor Setup) ===


Use this method when your server has internet access and you have a license token from the Members' Area or support:
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)


# Log in to the GUI
See [[Settings#Sensors]] for detailed configuration.
# 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.
== Distribution-Specific Guides ==


==== Offline Activation ====
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


Use this method when your server cannot connect to the license server (network restrictions, firewall, air-gapped environment):
== GUI Configuration Options ==


# Contact VoIPmonitor support to obtain the full, formatted license key
Edit <code>config/system_configuration.php</code> to disable features:
# 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


'''Important:''' The "License key" field is for the complete multi-line key. Do not paste a short token into this field.
<syntaxhighlight lang="php">
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>


==== Troubleshooting "Bad Key Content" Error ====
For additional configuration constants, see [[GUI_Configuration_PHP]].


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


* '''Pasting a full license key into the "License token" field''' → This will fail. Use the "License key" field instead.
=== "hwid invalid or corrupted" Error ===
* '''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 ====
The GUI cannot read the Hardware ID.


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.
'''Solution:'''
 
<syntaxhighlight lang="bash">
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.
chmod +r /dev/root
 
</syntaxhighlight>
'''Trial License Workaround:'''
 
# Contact VoIPmonitor support to request a trial license token
# 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.
 
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.
 
==== Troubleshooting Premature License Expiration Errors ====
 
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.


'''Symptom:'''
=== "Missing sniffer tables" or "Table 'voipmonitor.cdr' doesn't exist" ===
* License shows as expired or invalid on the customer server
* Same license works correctly on the central server
* License expiration date in voipmonitor.org portal shows the license is still valid


'''Primary Cause: Network Blocking'''
The GUI and sniffer are using different databases.


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.
'''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>


'''Diagnostic Steps:'''
{{Warning|Do NOT run schema.sql to "fix" this - the tables already exist in the sniffer's database.}}


From the affected customer server, test network connectivity to the license check server:
=== HTTP 500 Errors ===


# Try a different browser or incognito mode
# Check PHP and web server error logs:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Test DNS resolution
tail -f /var/log/apache2/error.log
ping -c 3 download.voipmonitor.org
# or
 
tail -f /var/log/nginx/error.log
# Test HTTPS connectivity
curl -I https://download.voipmonitor.org
</syntaxhighlight>
</syntaxhighlight>
 
# Verify IonCube Loader version matches PHP version
If these commands fail or time out, the firewall or network configuration is blocking access to the license validation server.
# Test PHP with info file:
 
'''Resolution:'''
 
1. '''Configure Firewall:''' Allow outbound HTTPS (TCP port 443) connections to <code>download.voipmonitor.org</code>
 
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# For firewalld
echo "<?php phpinfo(); ?>" > /var/www/html/info.php
firewall-cmd --permanent --add-service=https
# Then access http://your-server/info.php
firewall-cmd --reload
 
# For iptables
iptables -A OUTPUT -p tcp --dport 443 -d download.voipmonitor.org -j ACCEPT
service iptables save
</syntaxhighlight>
</syntaxhighlight>


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


<syntaxhighlight lang="bash">
The ionCube Loader version doesn't match PHP version.
# Check or set proxy environment variables
export http_proxy=http://proxy.example.com:8080
export https_proxy=http://proxy.example.com:8080
</syntaxhighlight>


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.
'''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


'''Temporary Workaround:'''
See [[Re-install_the_GUI]] for details.


As an immediate workaround to restore service before fixing the network configuration:
=== Database Connection Issues ===


# Navigate to '''Settings > License''' in the GUI
# Verify MySQL/MariaDB is running: <code>systemctl status mysql</code>
# Click the '''"get/update license key"''' button
# Test connection: <code>mysql -u voipmonitor -p voipmonitor</code>
# This forces an immediate license check if the server is reachable at that moment
# Check credentials in GUI configuration


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.
=== "Crontab log is empty" ===


==== Manually Updating License from Customer Portal ====
The cron job is not configured or not running.


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).
'''Solution:'''
<syntaxhighlight lang="bash">
# Add cron job
echo "* * * * * root php /var/www/html/voipmonitor/php/run.php cron" >> /etc/crontab


# Log in to the VoIPmonitor customer portal
# Test manually
# Navigate to '''Services > My services'''
php /var/www/html/voipmonitor/php/run.php cron
# Find your license in the list and click the '''license''' button
</syntaxhighlight>
# 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: <code>php /var/www/voipmonitor/php/apilicensecheck.php?task=licenseCheck</code>


'''Important:'''
=== License Shows Expired When Valid ===
* 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)
* When pasting the key content, replace ALL previous content (do not append or partially update)
* Common causes for file update issues include: file ownership problems, insufficient write permissions, or the web server caching old file content


See also: [[WEB_API#Check_License|Check License API]] for verifying license status.
The server cannot reach the license validation server.


=== Extending a Trial License ===
'''Diagnostic:'''
 
<syntaxhighlight lang="bash">
If your testing period requires more than 30 days, you can request a trial license extension:
curl -I https://download.voipmonitor.org
 
</syntaxhighlight>
# Contact VoIPmonitor support to request an extension of your trial license
# 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 ===
 
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.
 
You can view your current license status and concurrent call usage in the GUI under '''Tools -> System Status -> Concurrent calls'''.


See the [[FAQ]] for more information about licensing, including:
'''Solution:''' Allow outbound HTTPS (port 443) to <code>download.voipmonitor.org</code> in your firewall.
* 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


=== Retrieving a License Token from an Existing Installation ===
== See Also ==


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:
* [[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


==== Method 1: Retrieve from the GUI ====
[[Category:Installation]]


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>).
'''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.
=== 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');
define('WIKI_URL', false);
define('APP_WEB', 'http://voipmonitor.org');
</syntaxhighlight>


== 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 Issues:'''
* "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
'''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?

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"