License

This page explains how channel licensing works in VoIPmonitor, including what constitutes a channel, what happens when you exceed the limit, and how to resolve license lock issues.

What is a Channel License?

A channel license limits the number of concurrent calls processed by the VoIPmonitor GUI. Commercial licenses are sold with a specific channel cap (e.g., 100, 500, 1000 channels).

Licensing in Distributed / Multi-Server Deployments

For distributed architectures with multiple sensors (sniffers) across multiple datacenters:

Single Central GUI + Database + Remote Sensors: One license covers ALL sensors. Deploy remote sniffers in each datacenter, all connecting to a single, central GUI+DB. The license is based on the total number of concurrent channels across all instances, and channels are aggregated across sensors. This simplifies maintenance and licensing. See Architecture Guide and Client-Server Mode for deployment details.

Sensor Definition in Distributed Setup: Each capturing instance (sniffer) is a "sensor", but licensing is counted at the GUI level, not per sensor. If you have 3 sensors in 3 different datacenters, you need ONE GUI license that accommodates the total concurrent call volume from all 3 sensors combined.

Channel Deduplication Across Sensors: The GUI automatically deduplicates CDRs from multiple sensors if they capture the same call. Channels are aggregated - a single call with multiple legs or the same call captured by multiple sensors (e.g., geo-redundancy or overlapping network mirrors) counts as one channel for licensing, provided the last 6 digits of caller and called numbers match.

Advantages of Distributed Licensing Model:
- No per-sensor license multiplication
- Centralized management and billing
- Channel aggregation prevents duplicate counting
- Flexible deployment across physical locations without multiple license purchases

Example Deployment: If you have datacenters in New York, London, and Tokyo with local sensors connecting to a single GUI/DB in Frankfurt, you purchase ONE license sized for the total concurrent channels across all 3 sites (e.g., 500-channel license if peak concurrent calls across all New York + London + Tokyo combined is 450).

What Counts as a Channel?

A channel represents a single, un-mergeable CDR leg tracked and processed by VoIPmonitor.

Understanding channels requires distinguishing between "logical calls" (what users perceive as one conversation) and "CDR legs" (the technical records VoIPmonitor generates).

Basic Channel Counting

For typical call scenarios, VoIPmonitor counts **one channel per call**.

Important: License counting is performed by the GUI, which considers CDRs from all configured sensors (single or multiple servers). The GUI deduplicates multiple CDRs as a single license channel if the last 6 digits of the caller and called numbers are identical across all related CDRs.

This means that if you have multiple sniffers on different servers capturing the same call (for example, geo-redundancy or overlapping network mirrors), the GUI will correctly count this as one channel as long as the phone numbers match (last 6 digits).

For example:

Call from 123456001 to 123456002 = 1 channel (caller and called share last 6 digits: 456001 and 456002)
Call from 123456789 to 987654321 = 1 channel (different numbers do not merge)
Multiple calls to different phone numbers are counted separately
Same call captured by Server A and Server B = 1 channel (GUI deduplicates based on phone number match)

When One Logical Call Consumes Multiple Channels

A single logical phone conversation can generate **multiple separate CDR leg records** that VoIPmonitor cannot automatically merge. When this occurs, each un-mergeable leg is counted as an independent channel for licensing purposes.

This commonly happens in scenarios involving:

Call transfers (attended or blind)
Forking (parallel ringing to multiple destinations)
Re-invites (media session renegotiation)
Complex SIP routing (multiple proxies, B2BUA)

For example:

Simple call: SIP Phone A calls SIP Phone B = 1 CDR = 1 Channel
Complex call: SIP Phone A calls SIP Phone B, which forwards to SIP Phone C. If the transfer creates two distinct legs that cannot be merged, this counts as **2 Channels**.

Why Your License May Require More Channels Than Expected

If you request a license based on the number of users or logical calls (e.g., estimating 250 channels for 250 concurrent callers), but your traffic pattern involves frequent transfers or forking, the actual monitored volume of un-mergeable CDR legs will be higher. The license tier you receive reflects the reviewed usage pattern to ensure the monitoring system does not lock due to exceeding the channel limit.

What Happens When the License Limit is Exceeded?

When the channel count exceeds your license limit, VoIPmonitor has a grace period before locking:

1. **3-Day Grace Period:** You can exceed the limit for up to 3 consecutive days without any blocking 2. **Day 4 onwards:** The system begins a lockdown process 3. **After 14 Days:** The GUI locks completely

Effects of a Locked GUI

When the GUI becomes locked after exceeding the license limit for more than 14 consecutive days:

**GUI becomes unusable:** You cannot access the web interface
**Alerts are disabled:** No alert notifications will be sent
**Reports are unavailable:** You cannot generate reports
**CSV exports are blocked:** Data export functionality is disabled

What Still Works During Lock

Important: The sniffer continues to operate normally and record all CDRs to the database even when the GUI is locked. Your call data is not lost.

Resolving a License Lock

To unlock your VoIPmonitor GUI after it has been locked due to license limit overage:

Option 1: Upgrade Your License

The recommended solution is to upgrade to a larger channel limit. You can view available license tiers and upgrade directly through the voipmonitor.org portal:

1. Log in to the voipmonitor.org portal 2. Navigate to Services → My services 3. Locate your active VoIPmonitor license in the service list 4. Click the UPGRADE button to view available license tiers 5. Select your desired license tier (e.g., higher channel limit) 6. Follow the checkout process to complete the upgrade 7. After purchase, download the new license key file 8. Install the new license key (see License Key File Location) 9. Restart the GUI service

Option 2: Contact Support for Temporary Increase

If you need immediate access to the GUI without upgrading, contact VoIPmonitor support to request a **temporary license limit increase**.

This is the recommended approach when:

You need to troubleshoot why the channel count is higher than expected
You believe the license check may be incorrectly counting unmerged CDRs
You plan to upgrade later but need access now

Support can:

Temporarily increase your channel limit to unlock the GUI
Investigate whether the license check is incorrectly counting unmerged CDRs
Make permanent license limit adjustments if counting errors are identified

After the temporary increase allows access, you can then decide whether to:

Upgrade to a license tier that supports your expected concurrent call volume
Keep your current tier if the issue was caused by incorrect CDR counting

Option 3: Self-Service Temporary License Increase

If you are receiving daily email alerts about license being over the limit and want a quick, temporary solution without contacting support, you can increase the channel limit yourself using the GUI:

Steps

Log in to the VoIPmonitor GUI
Navigate to Settings > License (or Admin > License)
Click the "Get License Key" button
The system will fetch an updated license key with a **temporary channel limit increase**
This temporary increase lasts for **14 days**

ℹ️ Note: The license check only considers the last **3 weeks of call data** for triggering alerts. After you click "Get License Key" and receive the temporary limit increase, the daily email alerts will stop for 14 days.

This self-service option is ideal when you need to:

Stop the daily license over-limit email alerts immediately
Investigate why your concurrent channel count is higher than expected
Decide whether to upgrade to a higher license tier within the temporary period

After the 14-day temporary period expires, you can:

Click "Get License Key" again if you need more time
Upgrade to a higher license tier if the usage is justified
Reduce your actual concurrent call usage if possible

Option 4: Increase License Limit (If Available)

If you already have a higher tier license available but the limit is currently set lower in your license key configuration:

1. Update your license key configuration to increase the channel limit 2. Restart the GUI service

Option 5: Remove and Re-compute CDRs

If you need to quickly unlock the GUI without upgrading:

# WARNING: This will delete all existing CDRs from the database
# Make sure you have backups or can re-compute from PCAP files

# Stop VoIPmonitor
systemctl stop voipmonitor

# Connect to MySQL and delete CDRs
mysql -u root -p voipmonitor

# Run these commands in MySQL
TRUNCATE TABLE cdr;
TRUNCATE TABLE cdr_next_partition;
-- Also truncate any cdr_partition_* tables
TRUNCATE TABLE cdr_partition_YYYYMM;
EXIT;

# Restart VoIPmonitor
systemctl start voipmonitor

After deleting the CDRs and restarting, the GUI will recalculate the channel count from the remaining data. If the count is now within the license limit, the GUI will unlock.

Note: This is a destructive operation. Only use this if you can afford to lose historical CDR data.

Option 6: Re-compute CDRs from PCAP Files

If you have PCAP files in your spool directory, you can re-compute CDRs after making changes:

# Stop VoIPmonitor
systemctl stop voipmonitor

# Delete old CDRs (see Option 4 above)

# Re-process PCAP files to regenerate CDRs with the new license settings
voipmonitor --config-file /etc/voipmonitor.conf --readpcapdir /var/spool/voipmonitor

# After processing completes, restart VoIPmonitor normally
systemctl start voipmonitor

Monitoring Your Channel Usage

You can check your channel usage and license limit in multiple ways:

Quick View (Current Status)

To see the current channel count:

1. Log in to the VoIPmonitor GUI 2. Check the footer or the **About/License** page (often found under the Gear icon or User menu) 3. Look for **Active channels** vs **License limit**

Historical View (Last 14 Days)

For license planning and capacity planning, use the dedicated concurrent calls report:

1. Navigate to Tools > Concurrent Calls Stats 2. This report shows maximum concurrent call statistics for the last 14 days 3. It is specifically designed for GUI licensing compliance 4. The data is averaged over 60-minute windows to provide a clear view of peak usage

This historical view is particularly useful when determining the required license size, as it allows you to identify your peak usage patterns over an extended period rather than relying on a single snapshot.

If you consistently hit the limit during peak hours, consider upgrading your license to avoid lock situations.

Known Issue: Incorrect Channel Counting in Specific Scenarios

Current Status: There is a known issue where the VoIPmonitor license check incorrectly counts some calls as two separate channels, leading to inflated license usage. This bug has been confirmed and escalated to the development team for a future fix.

Symptoms:

License channel limit is exceeded more frequently than expected based on your actual concurrent call volume
The same individual call appears to be counted as two (or more) separate channels
Tools > Concurrent Calls Stats shows higher peak usage than your actual call patterns suggest

Affected Scenarios: This incorrect counting may occur in specific SIP scenarios where the license deduplication logic fails to recognize that multiple CDR legs represent the same logical call. This is not related to legitimate multi-channel scenarios (such as call transfers, forking, or re-invites), which are correctly counted as separate channels.

Temporary Workaround: As a temporary workaround until the bug is fixed in a future release, contact VoIPmonitor support to manually increase your license channel limit:

Support can temporarily increase your limit to prevent GUI lock due to incorrect counting
This allows continued monitoring while development fixes the underlying bug
No additional license upgrade is required for the temporary period

Reporting Information: If you encounter this issue, please provide VoIPmonitor support with:

Evidence from Tools > Concurrent Calls Stats showing the unexpected channel spike
Specific Call IDs or timestamps showing calls that appear to be double-counted
Your SIP topology description (especially if using unusual routing patterns)

This information helps the development team verify the bug and prioritize the fix.

Troubleshooting Trial Expiration

When a trial period ends, users may see messages indicating their license has expired. Before assuming a new purchase is needed, follow these troubleshooting steps:

Step 1: Verify If a License Has Already Been Purchased

The first and most important step is to check if a license purchase has already been completed in the system:

1. Log in to the voipmonitor.org portal 2. Navigate to Services > My services 3. Check for any active or pending VoIPmonitor license orders 4. Verify the order status (completed, pending, processing)

If a license has already been purchased but is not yet active:

Check if the order is still being processed (may take a few minutes to hours)
Verify the license key has been delivered to the correct email address
Contact VoIPmonitor support if the order status is unclear

Important: Many cases where users believe they need to purchase after trial expiration are actually resolved by finding an existing purchase that simply needs to be applied or activated.

Step 2: Apply the License Key

If a license purchase is confirmed but not yet applied:

1. Obtain the license key from the order confirmation email or portal 2. Apply the key using one of these methods:

  * GUI: Settings > About > License Key field
  * CLI: voipmonitor --set-license-key XXXX-XXXX-XXXX-XXXX
  * Config: Add license_key = "XXXX-XXXX-XXXX-XXXX" to voipmonitor.conf

3. Restart the VoIPmonitor service

Step 3: If No Purchase Found in System

Only after verifying that no purchase exists in the system should you guide the user to:

1. Purchase a license via the GUI (About > Buy License button) or voipmonitor.org store 2. Follow the activation steps above 3. Verify the license is displayed in the GUI About page

Common Scenarios

Trial warning appears but license was purchased: The license key was obtained but not yet applied to the system. Apply the existing key instead of purchasing again.
License purchased but not yet active: The order may still be processing. Check the order status in the portal.
Multiple trial warnings sent: Automated warnings may continue until the new license key is applied and the service is restarted.

Subscription and Renewal Terms

VoIPmonitor licenses have a formal subscription structure with specific dates for renewal and cancellation. Understanding these terms is important when planning license renewals or cancellations.

License Period Structure

Each VoIPmonitor license has two key dates:

Formal End Date: The official expiration date of your current license term. This is the date when your paid service period ends.
Grace Period End Date: Approximately 20 days after the formal end date, provided for automatic renewal processing.

When a license is renewed, the new license key extends the formal end date based on the paid service period shown on your invoice, not on the date of renewal or when you installed the new key. This means your license expiration date always matches the exact end date of the service you paid for.

Active Service Cancellations

If you cancel your VoIPmonitor subscription while the service is still active (before the formal end date):

Access to the license and GUI features ends on the formal end date, not at the end of the grace period
The 20-day grace period is for automatic renewal processing, not extended access after cancellation
If you cancel or do not renew, your license will stop functioning when the formal end date is reached
Plan any migrations or data exports before the formal end date if canceling

This can sometimes appear as "earlier than expected" revocation if you expected access to continue through the grace period. The grace period provides a buffer for renewal processing, not extended usage beyond the formal end date when a service is canceled.

Emergency Access During Transition

If your license expires due to payment delays or cancellation and you need immediate access:

Contact VoIPmonitor support to request an emergency trial license
Emergency trial licenses typically last 30 days
This allows you to maintain service while resolving billing issues
Apply the emergency license token in GUI > Settings > License section

For information on license channel limits and GUI lock behavior, see the sections above on channel licensing.

License Key File Location

The license key file is typically located at:

/var/www/html/voipmonitor/key.php

This file contains your license details including the channel limit. Updates to this file (e.g., when upgrading your license) should be provided by VoIPmonitor support.

Transferring a GUI License to a New System

You can transfer your GUI license to a new system installation without re-issuance. The license token can be used directly on the new installation.

Using Your Existing License

When moving to a new system:

Copy your existing license file from the old installation
Upload or install it on the new system
Restart the GUI service

The license is typically stored at /var/www/html/voipmonitor/key.php.

Running Old and New Systems Concurrently

If you need to keep both the old and new systems running simultaneously during migration, you have two options:

Option 1: Configure Your Existing License for Concurrent Use

The same license token and key can be used for the new platform. Contact VoIPmonitor support to have the license configured to allow simultaneous use during the migration period.

Use your existing license token on both the old and new systems
Contact support to configure the license for concurrent operation
No need for temporary or trial licenses
Simplest approach for most migration scenarios

This is the recommended first option when you need to run both systems during migration.

Option 2: Temporary Trial License

As an alternative, you can obtain a temporary trial license for the new system:

Log in to voipmonitor.org
Navigate to Services → Order and select a **30-day free trial license**
The trial license allows concurrent operation of both systems
Apply the trial license token on the new system
Cancel the trial when ready to retire the old system and move your paid license

ℹ️ Note: Trial licenses are typically available for 30 days and allow full access to all GUI features during the migration period.

Use this option if you prefer to keep the temporary migration environment separate from your production license.

OS Compatibility Notes

When installing on new operating systems, be aware of PHP version requirements:

RHEL-based distributions (Alma Linux 9.5, Rocky Linux 9, CentOS 9):
- Install PHP 8.2 from the remi repository
- PHP 8.0 is not supported
- Install the ionCube loader that matches your PHP version
- Follow the official installation documentation for your target OS

See GUI_Installation for detailed installation instructions and ionCube loader setup.

Virtual Machine Clones

If you are cloning a virtual machine rather than performing a fresh installation:

The license remains valid since the Machine ID is preserved
No license changes are required
However, avoid running identical clones concurrently as this may cause licensing conflicts

Resolving "license file key.php is for another hwid" Error

If you see the error message **"license file key.php is for another hwid"**, it indicates that the Hardware ID (HWID) of the current server does not match the HWID embedded in your license file (key.php). This typically occurs when:

You migrated the installation to new physical or virtual hardware
You restored a backup from a different environment (e.g., production to development)
A cloud instance was terminated and re-created with a new instance ID

Solution: Use the "Get License" Button

This error can be resolved directly from the GUI without contacting support. The "Get License" button will automatically re-synchronize your license with the current server's HWID.

Steps

Log in to the VoIPmonitor GUI on the affected server
Navigate to Settings > License section
Click the "Get License" button to fetch and install a fresh license key file that matches the current HWID
Verify that the license status changes to OK

The system will automatically detect your server's HWID and regenerate the license accordingly.

When to Contact Support

In rare cases, clicking "Get License" may not resolve the issue. Contact VoIPmonitor support if:

The error persists after clicking the "Get License" button
You need to keep the old server running while setting up the new one (requires a temporary license)
You are moving to a domain-based licensing model instead of hardware-bound licensing

Domain-Based Licensing for Frequent HWID Changes

If you frequently encounter the "another hwid" error due to cloud instance recreation (e.g., in auto-scaling groups or immutable infrastructure deployments), you can request **domain-based licensing** instead.

Domain-based licensing binds your license to your GUI's domain name rather than a specific hardware ID, allowing the license to remain valid even when cloud instances are terminated and recreated.

To switch to domain-based licensing:

Steps

Contact VoIPmonitor support
Provide the domain name used to access your GUI (e.g., your-gui.example.com)
Request to convert your license from hardware-bound to domain-bound

This prevents the need to manually update the license file each time a new instance is launched.

Refreshing License After Renewal

When your license is renewed or extended in the VoIPmonitor portal, your local installation may continue to show the error **"FAILED license file key.php expired"** until the license key is updated.

Using the GUI "Get/Update License" Button

The simplest way to refresh your license after a renewal is to use the built-in button in the GUI:

Steps

Log in to the VoIPmonitor GUI
Navigate to Admin > License or Settings > License
Click the "Get/Update License" button to fetch the latest license file from the VoIPmonitor server
Verify that the license status changes from FAILED to OK and the expiration date reflects your renewed period

This method automatically retrieves the updated license key file without requiring manual download or file upload.

Manual License Key Update

If the GUI button does not work or you prefer to manually update the license key:

Steps

Log in to the VoIPmonitor Portal
Navigate to your license section and download the new key.php file
In the GUI, navigate to Admin > License or Settings > License
Upload the new key.php file
Verify the license status changes to OK

Troubleshooting

**Error persists after clicking "Get/Update License":** Verify that the license has been renewed in the VoIPmonitor portal and the order status is "Active" or "Completed"
**"License file key.php is for another hwid":** See Resolving HWID Mismatch Error
**Browser cache issue:** Try clearing the browser cache or performing a hard refresh (Ctrl+F5)

AI Summary for RAG

Summary: VoIPmonitor uses channel licensing to limit concurrent calls processed by the GUI. Key concepts: (1) A channel = one un-mergeable CDR leg (not necessarily one logical call - transfers, forking, re-invites can create multiple CDR legs from one conversation). (2) Distributed deployments: ONE license covers ALL sensors across multiple datacenters when connecting to a single central GUI+DB. Channel aggregation deduplicates same calls captured by multiple sensors if last 6 digits of caller/called numbers match. (3) Exceeding limits: 3-day grace period, lockdown starts day 4, GUI locks completely after 14 days. When locked, GUI/alerts/reports disabled but sniffer continues recording CDRs. (4) Resolution options: Option 1 - Upgrade license; Option 2 - Contact support for temporary increase; Option 3 - Self-service temporary increase via GUI: Go to Settings > License, click "Get License Key" button to get 14-day temporary limit increase (license check considers last 3 weeks of call data, stops daily alerts); Option 4 - Increase limit if already purchased; Option 5 - TRUNCATE TABLE cdr (destructive). (5) Monitor usage via GUI footer or Tools > Concurrent Calls Stats (14-day history). (6) Subscription terms: Formal End Date is when paid service ends; 20-day Grace Period is for automatic renewal processing only (NOT extended access after cancellation). (7) License transfer: Copy key.php to new system; for concurrent operation during migration, contact support to configure license for simultaneous use. (8) HWID mismatch error: Use "Get License" button in Settings > License to re-synchronize. For frequent cloud instance recreation, request domain-based licensing. (9) After renewal: Click "Get/Update License" button to fetch updated license file. License key location: /var/www/html/voipmonitor/key.php. (10) KNOWN BUG: License check may incorrectly count some calls as two separate channels, leading to inflated license usage. If you see license limit exceeded more frequently than expected with Tools Concurrent Calls Stats showing higher peaks than actual call patterns, this is a known confirmed bug escalated to development team. Temporary workaround: Contact VoIPmonitor support to manually increase license channel limit (no upgrade required). Not related to legitimate multi-channel scenarios like transfers/forking which are correctly counted separately.

Keywords: channel license, concurrent calls, license limit, GUI lock, grace period, 14 days lock, unlock GUI, upgrade license, CDR leg, un-mergeable CDR, call transfer, forking, re-invite, distributed licensing, multi-server, multiple sensors, channel aggregation, deduplication, license transfer, HWID mismatch, domain-based licensing, license renewal, formal end date, grace period end date, emergency trial license, Get License button, Get/Update License button, Get License Key button, key.php, Tools Concurrent Calls Stats, temporary license increase, 14-day temporary license, 3 weeks call data, daily license alerts, stop license alerts, self-service license increase, incorrect channel counting, known bug, inflated license usage, double-counted calls, manual license increase, license support workaround

Key Questions:

What is a channel in VoIPmonitor licensing?
Why is the VoIPmonitor license check incorrectly counting some calls as two separate channels?
Is there a known bug in license channel counting?
How can I get a temporary license increase for the incorrect channel counting bug?
Can one call consume multiple license channels?
How can I stop daily license over-limit email alerts?
How do I get a temporary 14-day license increase without contacting support?
How does licensing work for distributed/multi-server deployments?
Do I need a separate license for each sensor?
What happens when I exceed the channel license limit?
How do I unlock my VoIPmonitor GUI after license lock?
How do I check my channel usage vs license limit?
Where is the Tools Concurrent Calls Stats?
How do I transfer a license to a new system?
Can I run old and new systems concurrently during migration?
How do I fix "license file key.php is for another hwid" error?
What is domain-based licensing?
How do I refresh my license after renewal?
What is the difference between formal end date and grace period end date?
Does the sniffer stop recording when the GUI is locked?