License: Difference between revisions
(Add AWS instance lifecycle details and clarify concurrent call check behavior) |
(Update AI Summary for RAG to prominently feature emergency trial license for expired licenses due to non-payment) |
||
| Line 573: | Line 573: | ||
== AI Summary for RAG == | == 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 (within +/- 10-second window). (3) Exceeding limits: GUI locks when licensed limit is exceeded for 3 consecutive days. System checks maximum peak concurrent calls averaged over 60-minute window, once per day. Users can verify license call count at Tools > Concurrent Calls Stats (correct path - NOT System Status). (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) AWS EC2 behavior: Stopping and starting an instance usually preserves hardware ID (license remains valid). Terminating and launching a new instance changes the ID, requiring a new license key from support (no automatic re-issuance). Use chmod 644 /dev/root to fix AWS permission issues preventing license validation. (10) After renewal: Click "Get/Update License" button to fetch updated license file. License key location: /var/www/html/voipmonitor/key.php. (11) 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. | '''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 (within +/- 10-second window). (3) Exceeding limits: GUI locks when licensed limit is exceeded for 3 consecutive days. System checks maximum peak concurrent calls averaged over 60-minute window, once per day. Users can verify license call count at Tools > Concurrent Calls Stats (correct path - NOT System Status). (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) AWS EC2 behavior: Stopping and starting an instance usually preserves hardware ID (license remains valid). Terminating and launching a new instance changes the ID, requiring a new license key from support (no automatic re-issuance). Use chmod 644 /dev/root to fix AWS permission issues preventing license validation. (10) After renewal: Click "Get/Update License" button to fetch updated license file. License key location: /var/www/html/voipmonitor/key.php. (11) EMERGENCY TRIAL LICENSE FOR EXPIRED LICENSES: If your license expires due to non-payment, payment delays, overdue payment, cancellation, or billing issues, contact VoIPmonitor support to request a 30-day emergency trial license. This allows you to maintain service immediately while resolving billing issues - NO payment required before access. Apply the emergency license token in GUI > Settings > License section. The emergency trial license provides service continuity pending payment resolution. (12) 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, 3 consecutive days, unlock GUI, upgrade license, CDR leg, un-mergeable CDR, call transfer, forking, re-invite, distributed licensing, multi-server, multiple sensors, channel aggregation, deduplication, last 6 digits, 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, test server, dev server, development server, test environment, dev environment, test server licensing, dev server licensing, no extra cost, multiple servers, concurrent use, reconfigure license, AWS, EC2, cloud instances, hardware ID, stop start, terminate launch, auto-scaling group, chmod 644 /dev/root | '''Keywords:''' channel license, concurrent calls, license limit, GUI lock, grace period, 14 days lock, 3 consecutive days, unlock GUI, upgrade license, CDR leg, un-mergeable CDR, call transfer, forking, re-invite, distributed licensing, multi-server, multiple sensors, channel aggregation, deduplication, last 6 digits, license transfer, HWID mismatch, domain-based licensing, license renewal, formal end date, grace period end date, emergency trial license, emergency license, 30-day trial, 30 day trial, license expired, expired license, non-payment, nonpayment, payment delay, payment issue, overdue payment, unpaid license, billing issue, credit hold, service interruption, restore service, service continuity, service interruption risk, license expiration, expired due to non-payment, 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, test server, dev server, development server, test environment, dev environment, test server licensing, dev server licensing, no extra cost, multiple servers, concurrent use, reconfigure license, AWS, EC2, cloud instances, hardware ID, stop start, terminate launch, auto-scaling group, chmod 644 /dev/root | ||
'''Key Questions:''' | '''Key Questions:''' | ||
* What is a channel in VoIPmonitor licensing? | * What is a channel in VoIPmonitor licensing? | ||
* What can I do if my VoIPmonitor license expires due to non-payment? | |||
* Can I get a 30-day emergency trial license for service interruption risk? | |||
* How do I restore service when my license expired because payment wasn't made? | |||
* Can support provide an emergency license for payment delays or billing issues? | |||
* How do I get service continuity while resolving overdue payment or unpaid license? | |||
* What happens when VoIPmonitor licenses expire due to non-payment? | |||
* Can I get a replacement license if my license expired because of payment issues? | |||
* Why is the VoIPmonitor license check incorrectly counting some calls as two separate channels? | * Why is the VoIPmonitor license check incorrectly counting some calls as two separate channels? | ||
* Is there a known bug in license channel counting? | * Is there a known bug in license channel counting? | ||
Revision as of 20:50, 7 January 2026
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 within a +/- 10-second window.
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)
487 Request Terminated Exclusion
Calls that end with a SIP response code of 487 Request Terminated are not included in the channel count. This exclusion applies to both license channel counting and the concurrent calls reporting tools.
💡 Tip: The 487 response is typically sent during call cancellation scenarios (e.g., when a call is canceled by the caller before it is established, or during call forking when unmatched forked legs are terminated). Since these terminated legs do not represent established voice conversations, they are excluded from both license channel counting and concurrent call statistics.
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:
- 3-Day Grace Period: You can exceed the limit for up to 3 consecutive days without any blocking
- Day 4 onwards: The system begins a lockdown process
- 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:
- Log in to the voipmonitor.org portal
- Navigate to Services → My services
- Locate your active VoIPmonitor license in the service list
- Click the UPGRADE button to view available license tiers
- Select your desired license tier (e.g., higher channel limit)
- Follow the checkout process to complete the upgrade
- After purchase, download the new license key file
- Install the new license key (see License Key File Location)
- 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:
- Update your license key configuration to increase the channel limit
- Restart the GUI service
Option 5: Remove CDRs (Destructive)
⚠️ Warning: This is a destructive operation that will delete all existing CDRs from the database. Only use this as a last resort if you can afford to lose historical CDR data.
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.
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 5 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:
- Log in to the VoIPmonitor GUI
- Check the footer or the About/License page (often found under the Gear icon or User menu)
- Look for Active channels vs License limit
Historical View (Last 14 Days)
For license planning and capacity planning, use the dedicated concurrent calls report:
- Navigate to Tools > Concurrent Calls Stats
- This report shows maximum concurrent call statistics for the last 14 days
- It is specifically designed for GUI licensing compliance
- 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
⚠️ Warning: 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:
- Log in to the voipmonitor.org portal
- Navigate to Services > My services
- Check for any active or pending VoIPmonitor license orders
- 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:
- Obtain the license key from the order confirmation email or portal
- 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
- 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:
- Purchase a license via the GUI (About > Buy License button) or voipmonitor.org store
- Follow the activation steps above
- 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, or for a test/dev/production environment, 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 multiple systems (old + new, or production + test/dev)
- Contact support to configure the license for concurrent operation
- No need for temporary or trial licenses
- Simplest approach for most scenarios including test/dev environments
- Works for: migrations, test environments, dev environments, and temporary production setups
- Can be reconfigured by support at no extra cost for multiple server use
This is the recommended first option when you need to run both systems during migration.
💡 Tip: If you need to license a test or development server at no extra charge, contact VoIPmonitor support to reconfigure your existing license for use on multiple servers. This is the preferred solution compared to getting a separate trial license.
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.
ℹ️ Note: There is NO automatic re-issuance process for cloud instances. When an AWS instance is terminated and a new one launched (changing the hardware ID), you must contact support to obtain a new license key, or switch to domain-based licensing as an alternative.
AWS Instance Lifecycle and Hardware ID Behavior
When running VoIPmonitor on AWS EC2 instances, understanding how instance lifecycle affects your license is important:
Instance operations have different effects on the Hardware ID (HWID) and license validity:
| Operation | HWID Change | License Status | Action Required |
|---|---|---|---|
| Stop & Start | Typically preserved | License remains valid | No action needed |
| Reboot | Preserved | License remains valid | No action needed |
| Terminate & Launch New | Changes | License invalid | New license key required from support |
| Auto-scaling Group | Changes per instance | License invalid per instance | Request domain-based licensing |
⚠️ Warning: Terminating an EC2 instance and launching a new instance will change the hardware ID, requiring a new license key from VoIPmonitor support. Use the "Get License" button in the GUI to attempt automatic re-synchronization first, but if this fails, contact support for manual license re-issuance. No fully automatic re-issuance process is available.
For AWS instances, you may also encounter permissions issues that prevent license validation. See the Cloud Service documentation for AWS-specific license configuration.
AWS EC2 Permission Fix
On AWS EC2 instances, the license check may fail with "Invalid or corrupted hwid" errors because the sensor cannot consistently read the hardware ID. Fix this by adjusting permissions on the root device file:
# Fix permissions for AWS AMIs to allow license validation
chmod 644 /dev/root
This command allows VoIPmonitor to read the hardware ID correctly on AWS AMIs.
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 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 Settings > License (or Admin > License)
- Click the "Change license key" button to expand the license options section
- Within the expanded section, click the "Get license key" button to fetch the latest license file from the VoIPmonitor billing server
- Verify that the license status changes from FAILED to OK, the expiration date reflects your renewed period, and the channel limit shows the new upgraded tier
This method automatically retrieves the updated license file with the latest channel limit and expiration date from the billing server without requiring manual download or file upload.
💡 Tip: If the "Get license key" button fails with a PHP error or timeout, this usually indicates a network connectivity issue. Ensure your server can access https://download.voipmonitor.org on port 443 and that no firewall or proxy is blocking the connection.
Manual License Key Update
If the GUI button does not work or you prefer to manually update the license key, you have two methods:
Method 1: Paste License Key in GUI (Recommended)
When your server cannot reach the license server (e.g., firewall, proxy, or network restrictions), you can paste the full license key directly in the GUI text field:
- Steps
- Request the full, formatted license key from VoIPmonitor support
- Log in to the VoIPmonitor GUI
- Navigate to Admin > License or Settings > License
- Locate the license key text field (often labelled as "License Key" or "Paste Key Here")
- Paste the entire license key block, including all lines:
Expireseasycalleridhwididmaxcallsupgradeexpire
- Click Save or Apply Changes
- Verify the license status changes to OK
ℹ️ Note: You must paste ALL lines from the license key block. Missing any of the required fields will cause the license to be rejected or not work correctly.
Method 2: Upload key.php File
Alternatively, if you have the license file:
- Steps
- Log in to the VoIPmonitor Portal
- Navigate to your license section and download the new
key.phpfile - In the GUI, navigate to Admin > License or Settings > License
- Upload the new
key.phpfile - 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)
Related Topics
- Billing - Learn about billing features and call cost calculation
- CDR_Summary - Pre-aggregated CDR data for faster queries
- Reports - Configure and generate VoIPmonitor reports
- GUI_Installation - GUI installation and upgrade procedures
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 (within +/- 10-second window). (3) Exceeding limits: GUI locks when licensed limit is exceeded for 3 consecutive days. System checks maximum peak concurrent calls averaged over 60-minute window, once per day. Users can verify license call count at Tools > Concurrent Calls Stats (correct path - NOT System Status). (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) AWS EC2 behavior: Stopping and starting an instance usually preserves hardware ID (license remains valid). Terminating and launching a new instance changes the ID, requiring a new license key from support (no automatic re-issuance). Use chmod 644 /dev/root to fix AWS permission issues preventing license validation. (10) After renewal: Click "Get/Update License" button to fetch updated license file. License key location: /var/www/html/voipmonitor/key.php. (11) EMERGENCY TRIAL LICENSE FOR EXPIRED LICENSES: If your license expires due to non-payment, payment delays, overdue payment, cancellation, or billing issues, contact VoIPmonitor support to request a 30-day emergency trial license. This allows you to maintain service immediately while resolving billing issues - NO payment required before access. Apply the emergency license token in GUI > Settings > License section. The emergency trial license provides service continuity pending payment resolution. (12) 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, 3 consecutive days, unlock GUI, upgrade license, CDR leg, un-mergeable CDR, call transfer, forking, re-invite, distributed licensing, multi-server, multiple sensors, channel aggregation, deduplication, last 6 digits, license transfer, HWID mismatch, domain-based licensing, license renewal, formal end date, grace period end date, emergency trial license, emergency license, 30-day trial, 30 day trial, license expired, expired license, non-payment, nonpayment, payment delay, payment issue, overdue payment, unpaid license, billing issue, credit hold, service interruption, restore service, service continuity, service interruption risk, license expiration, expired due to non-payment, 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, test server, dev server, development server, test environment, dev environment, test server licensing, dev server licensing, no extra cost, multiple servers, concurrent use, reconfigure license, AWS, EC2, cloud instances, hardware ID, stop start, terminate launch, auto-scaling group, chmod 644 /dev/root
Key Questions:
- What is a channel in VoIPmonitor licensing?
- What can I do if my VoIPmonitor license expires due to non-payment?
- Can I get a 30-day emergency trial license for service interruption risk?
- How do I restore service when my license expired because payment wasn't made?
- Can support provide an emergency license for payment delays or billing issues?
- How do I get service continuity while resolving overdue payment or unpaid license?
- What happens when VoIPmonitor licenses expire due to non-payment?
- Can I get a replacement license if my license expired because of payment issues?
- 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?
- Can I use my existing license on a test or development server?
- How do I license a test/dev environment without additional cost?
- Can support reconfigure my license for multiple servers?
- Do I need a separate license for test servers?
- 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?
- What happens to my VoIPmonitor license when I stop and start an AWS EC2 instance?
- What happens to my VoIPmonitor license when I terminate and launch a new AWS EC2 instance?
- How do I fix "Invalid or corrupted hwid" error on AWS EC2 instances?
- Is there automatic re-issuance for AWS licenses when instances are recreated?
- What is the difference between stopping and terminating an AWS EC2 instance for VoIPmonitor licensing?