GUI installation

GUI Installation

Quick Start

1. Download the latest GUI tar.gz package from http://www.voipmonitor.org/download-gui?version=latest
2. Untar to /var/www/ (On Debian-like systems) or /var/www/html (On RedHat-like systems) and rename created folder to voipmonitor
3. Open web browser and point it to http://yourserver/voipmonitor (you can choose whatever directory you want) and follow installation steps

ℹ️ Note: You need to install the sniffer too - see Sniffer Installation

System Requirements

The VoIPmonitor GUI has specific hardware and software requirements.

Hardware Architecture Requirements

⚠️ Warning: The VoIPmonitor GUI requires an x86 (32-bit or 64-bit) architecture system. The GUI is not supported on aarch64 (ARM64) platforms.

If you need to run VoIPmonitor on ARM64/aarch64 hardware:

• The sensor/sniffer component can be compiled from source for ARM64 architectures - see 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 entry on architecture support.

Hosting Environments

The VoIPmonitor GUI is fully supported in various hosting environments.

Containerized Deployment (Docker, Kubernetes)

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

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.

This applies to:

• 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

The VoIPmonitor GUI also runs normally in virtualized environments:

• VMware ESXi, VirtualBox, KVM, Hyper-V, QEMU/KVM: The GUI license works without issues
• AWS EC2, Google Cloud Platform, Azure VMs: License validation works normally

⚠️ Warning: Important distinction for AWS/Cloud:

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

License Key

Obtaining a Trial License (30 Days)

For a new installation, you can obtain a 30-day trial license for testing purposes through one of the following methods:

Method 1: Contact Support

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.

Method 2: Members' Area (Automated)

Log in to the VoIPmonitor members' area and find the license token in the "my services" section.

Troubleshooting Shopping Cart Issues

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

1. Review the items in your shopping cart
2. Ensure there is only one trial product in the cart
3. Remove any duplicate or conflicting items (multiple trial products can block checkout)
4. 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.

Troubleshooting Email Verification Issues

If you are using the Members' Area method and cannot receive the verification email:

1. Check your inbox and spam/junk folder for the verification email
2. If the email contains a typo or is not found, contact support to manually resend the verification email to the correct email address
3. 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.

Troubleshooting "Only One Trial Is Allowed" Error

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

• You previously used a trial license (even on a different or deleted server)
• The trial status in the back-end system was not properly reset after the trial expired

To resolve this issue:

1. Contact VoIPmonitor support and explain that the automated portal is showing "only one trial is allowed" for your account
2. Specify that you need a trial license for a new installation or testing environment
3. Support will manually correct the trial license status in the back-end system
4. 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 key.php in the web root folder of your GUI installation (typically /var/www/voipmonitor or /var/www/html/voipmonitor).

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 /dev/root to detect the Hardware ID (HWID) for license activation.

Solution: Grant Read Permissions on /dev/root

To resolve this issue:

1. SSH into the server where the GUI is installed
2. Run the following command to grant read permissions on the root block device:

chmod +r /dev/root

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

Online Activation (Recommended)

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

1. Log in to the GUI
2. Navigate to Settings > License
3. Paste your license token (short text string, NOT the full key) into the "License token" field
4. Click the "get/update license key" button
5. 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

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

1. Contact VoIPmonitor support to obtain the full, formatted license key
2. Log in to the GUI
3. Navigate to Settings > License
4. Paste the entire multi-line license key into the "License key" text field
5. Ensure you copy all lines (Expires, id, hwid, maxcalls, upgradeexpire, etc.)
6. Save the changes

⚠️ Warning: The "License key" field is for the complete multi-line key. Do not paste a short token into this field.

Troubleshooting "Bad Key Content" Error

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

• Pasting a full license key into the "License token" field → This will fail. Use the "License key" field instead.
• 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

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.

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.

Trial License Workaround:

1. Contact VoIPmonitor support to request a trial license token
2. Navigate to Settings > License in the GUI
3. Paste the trial license token into the "License token" field
4. Click the "get/update license key" button
5. 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:

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

Diagnostic Steps:

From the affected customer server, test network connectivity to the license check server:

# Test DNS resolution
ping -c 3 download.voipmonitor.org

# Test HTTPS connectivity
curl -I https://download.voipmonitor.org

If these commands fail or time out, the firewall or network configuration is blocking access to the license validation server.

Resolution:

1. Configure Firewall: Allow outbound HTTPS (TCP port 443) connections to download.voipmonitor.org

# For firewalld
firewall-cmd --permanent --add-service=https
firewall-cmd --reload

# For iptables
iptables -A OUTPUT -p tcp --dport 443 -d download.voipmonitor.org -j ACCEPT
service iptables save

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

# Check or set proxy environment variables
export http_proxy=http://proxy.example.com:8080
export https_proxy=http://proxy.example.com:8080

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.

Temporary Workaround:

As an immediate workaround to restore service before fixing the network configuration:

1. Navigate to Settings > License in the GUI
2. Click the "get/update license key" button
3. 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 download.voipmonitor.org 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 key.php file).

1. Log in to the VoIPmonitor customer portal
2. Navigate to Services > My services
3. Find your license in the list and click the license button
4. Copy the entire license key content displayed
5. Locate the key.php file on your GUI server (typically in /var/www/voipmonitor or /var/www/html/voipmonitor)
6. Replace the entire content of key.php with the new license key from the portal
7. Verify the license is updated by running:

php /var/www/voipmonitor/php/apilicensecheck.php?task=licenseCheck

⚠️ Warning: 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., www-data or apache, must be able to read the file).

See also: 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:

1. Contact VoIPmonitor support to request an extension of your trial license
2. After the license is extended by support, apply the update in the GUI by clicking the "get/update license key" button
3. 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:

• 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

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:

Method 1: Retrieve from the GUI

This is the recommended method for retrieving your license token:

1. Log in to your existing VoIPmonitor GUI
2. Navigate to Settings > License
3. Locate the "License token" field
4. 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 key.php file in your GUI installation directory contains the license information.

1. Navigate to your GUI installation directory (typically /var/www/html/voipmonitor or /var/www/voipmonitor)
2. Open the key.php file in a text editor
3. The file contains the license information including the license ID

You can use the license ID found in key.php 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: Can I use my license on multiple servers?

GUI Configuration (system_configuration.php)

The config/system_configuration.php 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 config/system_configuration.php file:

define('DISABLE_LIVE_SNIFFER', true);

When enabled, this constant removes the entire Live Sniffer menu item from the GUI. This is different from hiding play buttons (see FAQ for DISABLE_LIVEPLAY).

⚠️ Warning: Even with DISABLE_LIVE_SNIFFER 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

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');

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:

1. The GUI installation created or configured a database (e.g., via the GUI setup wizard)
2. The sniffer is installed but its configuration (`/etc/voipmonitor.conf`) is pointing to a different database or default settings
3. 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:

sudo nano /etc/voipmonitor.conf

Set the MySQL connection parameters to match your GUI database:

# MySQL connection (these must match the GUI database)
mysqlhost = localhost
mysqlport = 3306
mysqldb = voipmonitor
mysqlusername = root
mysqlpassword = your_password

💡 Tip: You can check which database the GUI is using by looking at the GUI's configuration file at /var/www/voipmonitor/config/configuration.php (or the path where you installed the GUI). Look for the variable named $USERDB or similar database configuration options.

2. Add the GUI Cron Job

The GUI requires a cron job to run maintenance tasks. Add it to the system crontab:

# Add the GUI cron job to the system crontab
# 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

ℹ️ Note: The cron job should run once per minute (* * * * *). Ensure the path to run.php matches your GUI installation directory.

3. Restart the Sniffer Service

Apply the configuration changes by restarting the sniffer:

# Restart using systemd (modern distributions)
sudo systemctl restart voipmonitor

# OR restart using init.d (older distributions)
sudo /etc/init.d/voipmonitor restart

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: sudo php /var/www/voipmonitor/php/run.php cron

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:

# Test connection using the credentials from voipmonitor.conf
mysql -h localhost -P 3306 -u root -p voipmonitor

If you can connect manually, check the sniffer logs for database connection errors:

# View sniffer logs
sudo journalctl -u voipmonitor -f
# OR for init.d systems
sudo tail -f /var/log/voipmonitor/voipmonitor.log

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

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.

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 chmod +r /dev/root
• Premature license expiration: Check firewall allows HTTPS to download.voipmonitor.org
• 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

Key Questions:

• How do I install the VoIPmonitor GUI?
• What architecture does the GUI require (x86 vs ARM64)?
• Does the GUI work in Docker/Kubernetes containers?
• What is the difference between "License token" and "License key" fields?
• How do I fix "hwid invalid or corrupted" error during installation?
• Why does my license show as expired when it should be valid?
• How do I obtain a 30-day trial license?
• How do I extend a trial license?
• 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 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?