GUI installation

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:

• Debian_12 - Debian 12 (Bookworm) installation
• Rocky_9 - Rocky Linux 9 / AlmaLinux 9 installation
• Ubuntu_24.04_LTS - Ubuntu 24.04 LTS installation

GUI Configuration Options

Edit 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

• 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

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?