GUI installation

From VoIPmonitor.org
Revision as of 16:48, 8 January 2026 by Admin (talk | contribs) (Rewrite: consolidated structure, clearer installation steps, moved detailed license troubleshooting to License page)

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.

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

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

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

⚠️ Warning: The GUI requires x86 architecture (32-bit or 64-bit). It is not supported on ARM64/aarch64.

For ARM64 deployments, use a split architecture:

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

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

For detailed licensing information, see License.

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.

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

ionCube Loader Errors

The ionCube Loader version doesn't match PHP version.

Solution: Download GUI package matching your PHP version, or install correct ionCube Loader. See Re-install_the_GUI for details.

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.

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=10090"