License: Difference between revisions

From VoIPmonitor.org
(Update AI Summary with Tools Concurrent Calls Stats information)
No edit summary
 
(27 intermediate revisions by one other user not shown)
Line 1: Line 1:
[[Category:Administration]]
[[Category:Administration]]


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.
This page explains VoIPmonitor channel licensing: what counts as a channel, what happens when limits are exceeded, and how to resolve license issues.


== What is a Channel License? ==
== Understanding Channel Licensing ==


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).
=== What is a Channel License? ===


=== What Counts as a Channel? ===
A channel license limits concurrent calls processed by the VoIPmonitor GUI. Commercial licenses specify a channel cap (e.g., 100, 500, 1000 channels).


A **channel** represents a **single, un-mergeable CDR leg** tracked and processed by VoIPmonitor.
{{Note|1='''Key distinction:''' A ''channel'' is a single, un-mergeable CDR leg—not necessarily one logical call. Complex scenarios (transfers, forking, re-invites) can create multiple CDR legs from one conversation.}}


Understanding channels requires distinguishing between "logical calls" (what users perceive as one conversation) and "CDR legs" (the technical records VoIPmonitor generates).
=== What Counts as a Channel? ===
 
==== 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).
{| class="wikitable"
|-
! Scenario !! Channels !! Explanation
|-
| Simple call: A → B || 1 || One CDR leg
|-
| Call ending with 487 (Request Terminated) || 0 || Excluded from counting
|-
| Call transfer: A → B → C (creates 2 legs) || 2 || Each un-mergeable leg counts
|-
| Forking/parallel ring || Multiple || One per destination leg
|-
| Same call captured by 2 sensors || 1 || Deduplicated if last 6 digits match (±10s window)
|}


For example:
'''Deduplication logic:''' The GUI deduplicates CDRs across sensors if the last 6 digits of caller and called numbers match within a ±10-second window. This means geo-redundant captures count as one channel.
* 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 ====
=== Distributed Deployments ===


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.
For multi-sensor architectures:


This commonly happens in scenarios involving:
* '''One license covers all sensors''' connecting to a single central GUI+DB
* '''Call transfers''' (attended or blind)
* Channels are aggregated across all sensors, not multiplied per sensor
* '''Forking''' (parallel ringing to multiple destinations)
* Same call captured by multiple sensors is deduplicated automatically
* '''Re-invites''' (media session renegotiation)
* '''Complex SIP routing''' (multiple proxies, B2BUA)


For example:
'''Example:''' Sensors in New York, London, and Tokyo connecting to Frankfurt GUI = ONE license sized for total concurrent calls across all sites.
* 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 ====
For deployment details, see [[Sniffer_distributed_architecture|Client-Server Mode]].


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.
== License Limit Exceeded ==


== What Happens When the License Limit is Exceeded? ==
=== Timeline ===


When the channel count exceeds your license limit, VoIPmonitor has a grace period before locking:
<kroki lang="mermaid">
%%{init: {'flowchart': {'nodeSpacing': 15, 'rankSpacing': 30}}}%%
flowchart LR
    A[Limit<br/>Exceeded] --> B[Days 1-3:<br/>Grace Period]
    B --> C[Days 4-13:<br/>Lockdown]
    C --> D[Day 14+:<br/>GUI Locked]
    style A fill:#ffcc00
    style B fill:#90EE90
    style C fill:#FFA500
    style D fill:#FF6B6B
</kroki>


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


=== Effects of a Locked GUI ===
{| class="wikitable"
|-
! Blocked !! Still Working
|-
| GUI access, Alerts, Reports, CSV exports || '''Sniffer continues recording all CDRs''' (data is NOT lost)
|}


When the GUI becomes locked after exceeding the license limit for more than 14 consecutive days:
=== Do I Need to Act Immediately After Receiving Alert Emails? ===


* **GUI becomes unusable:** You cannot access the web interface
If you received multiple '''VoIPmonitor license alert''' emails after exceeding the limit once:
* **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 ===
{{Note|1='''No, you do NOT need to act immediately.''' A license upgrade is only necessary if the concurrent call limit is exceeded for '''3 consecutive days'''.}}


'''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.
{{Tip|Receiving multiple emails from a single over-limit event is normal behavior and does not indicate a worsening problem. The system continues monitoring in the background during the grace period.}}


== Resolving a License Lock ==
== Resolving License Issues ==


To unlock your VoIPmonitor GUI after it has been locked due to license limit overage:
=== Option 1: Upgrade License (Recommended) ===


=== Option 1: Upgrade Your License ===
# Log in to [https://www.voipmonitor.org voipmonitor.org] → '''Services''' → '''My services'''
# Click '''UPGRADE''' on your license → select new tier → complete checkout
# Download new <code>key.php</code> and install (see [[#License Key Location|License Key Location]])


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:
=== Option 2: Self-Service Temporary Increase ===


1. Log in to the [[https://www.voipmonitor.org|voipmonitor.org]] portal
For immediate relief without contacting support:
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|License Key File Location]])
9. Restart the GUI service


=== Option 2: Contact Support for Temporary Increase ===
# GUI → '''Settings > License'''
# Click '''"Get License Key"''' button
# Receive '''14-day temporary increase'''


If you need immediate access to the GUI without upgrading, contact VoIPmonitor support to request a **temporary license limit increase**.
{{Tip|The license check considers only the last 3 weeks of call data. After clicking "Get License Key", daily over-limit alerts stop for 14 days.}}


This is the recommended approach when:
=== Option 3: Contact Support ===
* 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:
Support can:
* Temporarily increase your channel limit to unlock the GUI
* Provide temporary channel limit increase
* Investigate whether the license check is incorrectly counting unmerged CDRs
* Investigate incorrect CDR counting
* Make permanent license limit adjustments if counting errors are identified
* Issue emergency 30-day trial license (for expired licenses due to billing issues)
 
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: 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 4: Remove and Re-compute CDRs ===
=== Option 4: Delete CDRs (Destructive) ===


If you need to quickly unlock the GUI without upgrading:
{{Warning|1=This deletes all existing CDRs. Only use as last resort.}}


<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# 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
systemctl stop voipmonitor
 
mysql -u root -p voipmonitor -e "TRUNCATE TABLE cdr; TRUNCATE TABLE cdr_next_partition;"
# 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
systemctl start voipmonitor
</syntaxhighlight>
</syntaxhighlight>


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.
To re-process from PCAP files afterward:
 
'''Note:''' This is a destructive operation. Only use this if you can afford to lose historical CDR data.
 
=== Option 5: Re-compute CDRs from PCAP Files ===
 
If you have PCAP files in your spool directory, you can re-compute CDRs after making changes:
 
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Stop VoIPmonitor
systemctl stop voipmonitor
# Delete old CDRs (see Option 3 above)
# Re-process PCAP files to regenerate CDRs with the new license settings
voipmonitor --config-file /etc/voipmonitor.conf --readpcapdir /var/spool/voipmonitor
voipmonitor --config-file /etc/voipmonitor.conf --readpcapdir /var/spool/voipmonitor
# After processing completes, restart VoIPmonitor normally
systemctl start voipmonitor
</syntaxhighlight>
</syntaxhighlight>


== Monitoring Your Channel Usage ==
=== Trial Expiration ===


You can check your channel usage and license limit in multiple ways:
Before purchasing after trial expiration:


=== Quick View (Current Status) ===
# Check if license already purchased: voipmonitor.org → '''Services''' → '''My services'''
# If purchased but not applied: Get <code>key.php</code> from order email and install it
# Only if no purchase exists: Buy via GUI (About > Buy License) or portal


To see the current channel count:
=== HWID Mismatch Error ===


1. Log in to the VoIPmonitor GUI
'''"license file key.php is for another hwid"''' occurs when hardware ID changed (migration, cloud instance recreation).
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) ===
'''Solution:''' GUI → '''Settings > License''' → '''"Get License"''' button (auto-syncs with current HWID)


For license planning and capacity planning, use the dedicated concurrent calls report:
'''For frequent cloud instance recreation:''' Request '''domain-based licensing''' from support (binds to domain name instead of hardware ID).


1. Navigate to '''Tools > Concurrent Calls Stats'''
=== "get hwid failed" Error ===
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.
'''Problem:''' The GUI displays "get hwid failed" when attempting to update the license key.


If you consistently hit the limit during peak hours, consider upgrading your license to avoid lock situations.
'''Cause:''' The web server user cannot read or execute the Hardware ID binary.


== Troubleshooting Trial Expiration ==
'''Solution:'''


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:
Test if the hwid binary works as the web server user:
<syntaxhighlight lang="bash">
su - www-data -s /bin/bash -c '/var/www/html/bin/hwid-x86_64'
</syntaxhighlight>


=== Step 1: Verify If a License Has Already Been Purchased ===
If this command fails with permission denied, fix the binary permissions:
<syntaxhighlight lang="bash">
chmod +rx /var/www/html/bin/hwid-x86_64
</syntaxhighlight>


The first and most important step is to check if a license purchase has already been completed in the system:
{{Note|Replace '''www-data''' with your web server user (e.g., '''apache''' on RHEL/Rocky systems).}}


1. Log in to the voipmonitor.org portal
=== After License Renewal ===
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:
# GUI → '''Settings > License'''
* Check if the order is still being processed (may take a few minutes to hours)
# Click '''"Change license key"''' to expand options
* Verify the license key has been delivered to the correct email address
# Click '''"Get license key"''' to fetch updated license
* 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.
'''Manual method:''' Paste full license key (all lines: Expires, easycallerid, hwid, id, maxcalls, upgradeexpire) into the license text field.


=== Step 2: Apply the License Key ===
== Monitoring Usage ==


If a license purchase is confirmed but not yet applied:
=== Current Status ===


1. Obtain the license key from the order confirmation email or portal
Check GUI footer or '''About/License''' page for active channels vs. license limit.
2. Apply the key using one of these methods:
  * GUI: Settings > About > License Key field
  * CLI: <code>voipmonitor --set-license-key XXXX-XXXX-XXXX-XXXX</code>
  * Config: Add <code>license_key = "XXXX-XXXX-XXXX-XXXX"</code> to voipmonitor.conf
3. Restart the VoIPmonitor service


=== Step 3: If No Purchase Found in System ===
=== Historical Data ===


Only after verifying that no purchase exists in the system should you guide the user to:
'''Tools > Concurrent Calls Stats''' shows maximum concurrent calls for last 14 days (averaged over 60-minute windows).


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


=== Common Scenarios ===
To disable license notification emails:


* '''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.
# GUI → '''Settings > License'''
* '''License purchased but not yet active:''' The order may still be processing. Check the order status in the portal.
# Clear the email address field for license notifications
* '''Multiple trial warnings sent:''' Automated warnings may continue until the new license key is applied and the service is restarted.
# Save changes


== Subscription and Renewal Terms ==
{{Note|This only disables license-related emails (warnings, overage, expiration, lock). Other alerts continue normally.}}


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 Key Management ==


=== License Period Structure ===
=== License Key Location ===


Each VoIPmonitor license has two key dates:
<code>/var/www/html/voipmonitor/key.php</code>


* '''Formal End Date:''' The official expiration date of your current license term. This is the date when your paid service period ends.
=== Transferring to New System ===
* '''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 beyond the current grace period end date.
# Copy <code>key.php</code> from old system to new system
# Restart GUI service


=== Active Service Cancellations ===
'''For concurrent operation''' (old + new during migration, or test/dev environments):
* Contact support to configure license for simultaneous multi-server use (preferred)
* Or obtain 30-day trial license for temporary system


If you cancel your VoIPmonitor subscription while the service is still active (before the formal end date):
{{Tip|For test/dev servers, contact support to reconfigure your existing license for multiple servers at no extra cost.}}


* Access to the license and GUI features '''ends on the formal end date''', not at the end of the grace period
=== AWS/Cloud Considerations ===
* 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.
{| class="wikitable"
|-
! Operation !! HWID Changes? !! Action Required
|-
| Stop & Start || Usually No || None
|-
| Reboot || No || None
|-
| Terminate & Launch New || Yes || New license key (use "Get License" button or contact support)
|-
| Auto-scaling Group || Yes per instance || Request domain-based licensing
|}


=== Emergency Access During Transition ===
'''AWS permission fix''' (for "Invalid or corrupted hwid" errors):
<syntaxhighlight lang="bash">
chmod 644 /dev/root
</syntaxhighlight>


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


* Contact VoIPmonitor support to request an '''emergency trial license'''
{| class="wikitable"
* Emergency trial licenses typically last 30 days
|-
* This allows you to maintain service while resolving billing issues
! Term !! Meaning
* Apply the emergency license token in GUI > Settings > License section
|-
| '''Formal End Date''' || When your paid service period ends
|-
| '''Grace Period''' (20 days after) || For automatic renewal processing only—NOT extended access after cancellation
|}


For information on license channel limits and GUI lock behavior, see the sections above on channel licensing.
{{Warning|1=If you cancel, access ends on the Formal End Date, not the grace period end.}}


== License Key File Location ==
'''Emergency access:''' Contact support for 30-day emergency trial license while resolving billing issues.


The license key file is typically located at:
== Known Issue: Incorrect Channel Counting ==
 
<code>/var/www/html/voipmonitor/key.php</code>


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.
{{Warning|1=Known bug: Some calls are incorrectly counted as two channels. Confirmed and escalated to development team.}}


== Transferring a GUI License to a New System ==
'''Symptoms:'''
* License exceeded more frequently than expected
* Tools > Concurrent Calls Stats shows higher peaks than actual call patterns


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.
'''Workaround:''' Contact support for manual channel limit increase (no upgrade required).


=== Using Your Existing License ===
== See Also ==


When moving to a new system:
* [[Billing]] - Call cost calculation
* Copy your existing license file from the old installation
* [[Reports]] - Report configuration
* Upload or install it on the new system
* [[GUI_Installation]] - Installation and upgrade procedures
* Restart the GUI service
* [[Sniffer_distributed_architecture|Client-Server Mode]] - Multi-sensor deployments


The license is typically stored at <code>/var/www/html/voipmonitor/key.php</code>.
=== How Legs Are Correlated ===


=== Running Old and New Systems Concurrently ===
{| class="wikitable"
|-
! Scenario !! Channels !! Explanation
|-
| Simple call: A → B || 1 || One CDR leg
|-
| Call ending with 487 (Request Terminated) || 0 || Excluded from counting
|-
| Call transfer: A → B → C (creates 2 legs) || 1+ || Legs correlated if same call context
|-
| Forking/parallel ring || Multiple || One per destination leg
|-
| Same call captured by 2 sensors || 1 || Deduplicated if last 6 digits match (±10s window)
|}


If you need to keep both the old and new systems running simultaneously during migration:
'''How legs are correlated for license counting:''' CDR legs are treated as a single channel when:
* Legs start within '''5 seconds''' of each other AND
* '''Last 6 digits''''' of BOTH caller AND called numbers match


* Contact VoIPmonitor support to request a **temporary trial license**
This means a single logical call may create multiple CDR legs on the network (e.g., via SBC/B2BUA with generated new Call-IDs) but still count as '''one license channel'''.
* The trial license allows concurrent operation of both systems
* Use the trial license on the new system until migration is complete
* Cancel the trial when ready to retire the old system


This is the recommended approach when you cannot afford downtime during the transition.
'''Cross-sensor deduplication:''' When the same call is captured by multiple sensors, it's deduplicated if the last 6 digits of caller and called numbers match within a ±10-second window. Geo-redundant captures count as one channel.


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


== 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 ==
== AI Summary for RAG ==


'''Summary:''' VoIPmonitor channel licensing limits the number of concurrent calls processed by the GUI, with licenses sold in channel caps (e.g., 100, 500, 1000 channels). What is a channel: A channel represents a single, un-mergeable CDR leg tracked and processed by VoIPmonitor. This is a critical distinction: one logical phone conversation can generate multiple separate CDR leg records that VoIPmonitor cannot automatically merge. Each un-mergeable leg is counted as an independent channel for licensing purposes. Basic channel counting: 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 if multiple sniffers on different servers capture the same call (geo-redundancy or overlapping mirrors), the GUI correctly counts this as one channel as long as phone numbers match (last 6 digits). When one logical call consumes multiple channels: Common scenarios include call transfers (attended or blind), forking (parallel ringing to multiple destinations), re-invites (media session renegotiation), and complex SIP routing (multiple proxies, B2BUA). Example: Simple call Phone A to Phone B = 1 channel; Complex call Phone A to Phone B which forwards to Phone C = 2 channels if the transfer creates two distinct un-mergeable legs. Why license may require more channels than expected: If you request a license based on logical calls but your traffic pattern involves frequent transfers or forking, the actual monitored volume of un-mergeable CDR legs will be higher. The license tier reflects the reviewed usage pattern. Exceeding the limit consequences: 3-day grace period allows exceeding limit without block; after 3 consecutive days over limit, lockdown process begins; after 14 days total, GUI locks completely. When locked, GUI, alerts, reports, and CSV exports become unusable. The sniffer continues recording all CDRs to database even while locked (sniffer does NOT stop). Resolution options: (1) Upgrade license to higher channel limit (recommended), (2) Increase license limit if higher tier available, (3) Remove and re-compute CDRs from database (destructive - TRUNCATE TABLE cdr and cdr_next_partition, then restart), (4) Re-compute CDRs from PCAP files using --readpcapdir. Monitor usage: check GUI footer or About/License page (Gear icon or User menu) for Active channels vs License limit. For historical data and license planning, navigate to Tools > Concurrent Calls Stats which shows maximum concurrent call statistics for the last 14 days, averaged over 60-minute windows - this is specifically designed for GUI licensing compliance and helps identify peak usage patterns for determining required license size. License key file location: /var/www/html/voipmonitor/key.php (provided by VoIPmonitor support). Subscription and renewal terms: Each VoIPmonitor license has two key dates: (1) Formal End Date - the official expiration date when paid service period ends, (2) Grace Period End Date - approximately 20 days after formal end date for automatic renewal processing. When a license is renewed, the new license key extends the formal end date beyond the current grace period end date. Active service cancellations: If you cancel your subscription before the formal end date, access 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. This can appear as "earlier than expected" revocation if you expected access to continue through the grace period. Plan migrations or data exports before formal end date if canceling. Emergency access: If license expires due to payment delays or cancellation, contact VoIPmonitor support to request an emergency trial license (typically 30 days) to maintain service while resolving billing issues. Apply emergency license token in GUI > Settings > License section. Transferring license to new system: Can transfer GUI license to new system installation without re-issuance. The existing license token can be used directly on new installation by copying the license file (typically /var/www/html/voipmonitor/key.php) and restarting GUI service. For concurrent operation of old and new systems during migration, contact support to request a temporary trial license. OS compatibility notes: For RHEL-based distributions (Alma Linux 9.5, Rocky Linux 9, CentOS 9), install PHP 8.2 from remi repository as PHP 8.0 is not supported. Install the ionCube loader that matches the PHP version. Virtual machine clones: License remains valid since Machine ID is preserved, no re-issuance needed, but avoid running identical clones concurrently.
'''Summary:''' VoIPmonitor uses channel licensing to limit concurrent calls processed by the GUI. Key concepts: (1) A channel = one un-mergeable CDR leg (transfers, forking, re-invites can create multiple legs from one call). Calls ending with 487 (Request Terminated) are excluded. (2) Distributed deployments: ONE license covers ALL sensors connecting to a single central GUI+DB. Deduplication occurs if last 6 digits of caller/called numbers match within ±10s window. (3) Exceeding limits: 3-day grace period, then lockdown process, GUI locks at day 14. Sniffer continues recording during lock. (4) Resolution options: Upgrade license, self-service 14-day temporary increase via "Get License Key" button (Settings > License), contact support for temporary increase or emergency trial, or delete CDRs (destructive). (5) Monitor usage via GUI footer or Tools > Concurrent Calls Stats (14-day history). (6) License transfer: Copy key.php to new system; contact support for concurrent multi-server use. (7) HWID mismatch: Use "Get License" button to re-sync; request domain-based licensing for frequent cloud instance recreation. (8) AWS: Stop/Start preserves HWID; Terminate/Launch changes it. Use chmod 644 /dev/root for permission issues. (9) Subscription terms: Formal End Date = service ends; Grace Period = renewal processing only. (10) Known bug: Some calls incorrectly counted as two channels—contact support for temporary limit increase.


'''Keywords:''' channel license, concurrent calls, license limit, GUI lock, license lock, exceed limit, grace period, 14 days lock, unlock GUI, upgrade license, CDR merging, un-mergeable CDR leg, CDR leg, logical call vs CDR leg, call transfer, attended transfer, blind transfer, forking, parallel ringing, re-invite, complex SIP routing, B2BUA, multiple channels per call, one conversation multiple channels, channel definition, what is a channel, channel meaning, caller called numbers, 6 digits, channel count per call, active channels, Tools Concurrent Calls Stats, Tools Concurrent Calls, concurrent calls history, historical channel usage, 14 days statistics, 60 minute averages, license planning, license sizing, peak usage, determine license size, required license channels, license key key.php, re-compute CDR, PCAP restore, sniffer continues recording, GUI locked, alerts disabled, reports unavailable, CSV export blocked, license transfer, move license, new system, new installation, copy license, license token, concurrent systems, dual operation, temporary trial license, trial license, migration, downtime, Alma Linux 9.5, Rocky Linux 9, CentOS 9, PHP 8.2, remi repository, PHP 8.0 not supported, ionCube loader, virtual machine clone, Machine ID, clone, VM clone, license duplication, multiple servers, multiple sniffers, multiple sensors, cross-server, geo-redundancy, duplicate calls, deduplication, CDR deduplication, license deduplication, GUI deduplicates CDRs, multiple instances, distributed monitoring, overcounting license, overlapping mirrors, subscription terms, license renewal, formal end date, grace period end date, subscription cancellation, license expiration, 20 day grace period, automatic renewal, access revoked earlier than expected, license access cancellation, emergency trial license, billing issues
'''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 License Key button, key.php, Tools Concurrent Calls Stats, temporary license increase, 14-day temporary license, self-service license increase, incorrect channel counting, known bug, test server, dev server, AWS, EC2, cloud instances, hardware ID, chmod 644 /dev/root, license notification emails, disable license emails, 487 Request Terminated


'''Key Questions:'''
'''Key Questions:'''
* What is the license formal end date?
* What is the license grace period end date?
* How does the 20-day grace period work for license renewal?
* When does VoIPmonitor license access end after cancellation?
* Does license access end on the formal end date or grace period end date?
* Why was my license access revoked earlier than expected?
* How long is the VoIPmonitor license grace period?
* What happens to my VoIPmonitor license when I cancel?
* How do I get emergency access when my license expires?
* What is the VoIPmonitor subscription renewal structure?
* When should I plan my license migration before cancellation?
* Can I get a temporary license while resolving billing issues?
* What is an emergency trial license for VoIPmonitor?
* What is a channel in VoIPmonitor licensing?
* What is a channel in VoIPmonitor licensing?
* What constitutes a channel in VoIPmonitor licensing?
* Can one call consume multiple license channels?
* How do I transfer a GUI license to a new system?
* What happens when I exceed the channel license limit?
* Can I copy my VoIPmonitor license file to a new server?
* How do I unlock my VoIPmonitor GUI after license lock?
* Do I need to re-issue my license when moving to a new system?
* How do I get a temporary license increase without contacting support?
* Can I run old and new VoIPmonitor systems concurrently with the same license?
* How does licensing work for distributed/multi-server deployments?
* How do I get a temporary trial license for migration?
* Do I need a separate license for each sensor?
* What PHP version is required for Alma Linux 9.5 / Rocky Linux 9?
* How do I check my channel usage vs license limit?
* Do I need to install ionCube loader for the GUI?
* How do I transfer a license to a new system?
* How does VoIPmonitor define a channel for licensing?
* Can I use my existing license on a test or development server?
* Is a channel the same as one phone call in VoIPmonitor?
* How do I fix "license file key.php is for another hwid" error?
* What is the difference between a logical call and a CDR leg?
* What is domain-based licensing?
* Can one logical phone conversation use multiple license channels?
* How do I refresh my license after renewal?
* When does one call consume more than one license channel?
* What happens to my VoIPmonitor license when I terminate an AWS EC2 instance?
* What happens when you transfer a call - does it count as one or multiple channels?
* How do I disable license notification emails?
* Do call forking and re-invites affect channel count in VoIPmonitor?
* Why is my license showing higher channel usage than expected?
* Does VoIPmonitor count each un-mergeable CDR leg as a separate channel?
* Does the sniffer stop recording when the GUI is locked?
* Why did I need more channels in my license than the number of concurrent calls I expected?
* What is the difference between formal end date and grace period?
* Why does my license have more channels than the number of users I estimated?
* How do call transfers affect channel counting in VoIPmonitor licensing?
* What scenarios cause one call to consume multiple channels?
* What happens when I exceed the channel license limit in VoIPmonitor?
* How many days can I exceed the license limit before the GUI locks?
* Does VoIPmonitor stop recording CDRs when the license limit is exceeded?
* How do I unlock my VoIPmonitor GUI after the license limit lock?
* What happens to CDRs when the GUI is locked due to license overage?
* How do I check my channel usage vs license limit in VoIPmonitor?
* How do I find the number of concurrent calls for license sizing?
* Where is the Tools Concurrent Calls Stats in the GUI?
* How do I view concurrent call history for license planning?
* What is the best way to determine required license size?
* Where can I find 14-day concurrent call statistics?
* Can I re-compute CDRs to fix a license lock without upgrading?
* What is the grace period for exceeding the VoIPmonitor channel license?
* Do I have to upgrade my license if the GUI is locked?
* How does VoIPmonitor count channels for licensing?
* How are CDRs merged for channel counting purposes?
* Does the sniffer stop when the license limit is reached?
* What functionality is disabled when the GUI is locked?
* How long can I exceed the channel limit before locking?
* Where is the VoIPmonitor license key file located?
* How do I upgrade my VoIPmonitor channel license?
* Can I delete CDRs to unlock the GUI temporarily?
* Does VoIPmonitor have a trial period for exceeding licenses?
* How does VoIPmonitor count duplicate calls captured by multiple sniffers?
* If I have multiple servers sniffing the same traffic, will I be charged duplicate license channels?
* Does VoIPmonitor deduplicate CDRs from multiple sensors for license counting?
* How do duplicate calls from geo-redundant sniffers affect my license?
* What happens to my license count if multiple servers capture the same call?

Latest revision as of 02:20, 10 January 2026


This page explains VoIPmonitor channel licensing: what counts as a channel, what happens when limits are exceeded, and how to resolve license issues.

Understanding Channel Licensing

What is a Channel License?

A channel license limits concurrent calls processed by the VoIPmonitor GUI. Commercial licenses specify a channel cap (e.g., 100, 500, 1000 channels).

ℹ️ Note: Key distinction: A channel is a single, un-mergeable CDR leg—not necessarily one logical call. Complex scenarios (transfers, forking, re-invites) can create multiple CDR legs from one conversation.

What Counts as a Channel?

Scenario Channels Explanation
Simple call: A → B 1 One CDR leg
Call ending with 487 (Request Terminated) 0 Excluded from counting
Call transfer: A → B → C (creates 2 legs) 2 Each un-mergeable leg counts
Forking/parallel ring Multiple One per destination leg
Same call captured by 2 sensors 1 Deduplicated if last 6 digits match (±10s window)

Deduplication logic: The GUI deduplicates CDRs across sensors if the last 6 digits of caller and called numbers match within a ±10-second window. This means geo-redundant captures count as one channel.

Distributed Deployments

For multi-sensor architectures:

  • One license covers all sensors connecting to a single central GUI+DB
  • Channels are aggregated across all sensors, not multiplied per sensor
  • Same call captured by multiple sensors is deduplicated automatically

Example: Sensors in New York, London, and Tokyo connecting to Frankfurt GUI = ONE license sized for total concurrent calls across all sites.

For deployment details, see Client-Server Mode.

License Limit Exceeded

Timeline

Effects When Locked

Blocked Still Working
GUI access, Alerts, Reports, CSV exports Sniffer continues recording all CDRs (data is NOT lost)

Do I Need to Act Immediately After Receiving Alert Emails?

If you received multiple VoIPmonitor license alert emails after exceeding the limit once:

ℹ️ Note: No, you do NOT need to act immediately. A license upgrade is only necessary if the concurrent call limit is exceeded for 3 consecutive days.

💡 Tip: Receiving multiple emails from a single over-limit event is normal behavior and does not indicate a worsening problem. The system continues monitoring in the background during the grace period.

Resolving License Issues

Option 1: Upgrade License (Recommended)

  1. Log in to voipmonitor.org → Services → My services
  2. Click UPGRADE on your license → select new tier → complete checkout
  3. Download new key.php and install (see License Key Location)

Option 2: Self-Service Temporary Increase

For immediate relief without contacting support:

  1. GUI → Settings > License
  2. Click "Get License Key" button
  3. Receive 14-day temporary increase

💡 Tip: The license check considers only the last 3 weeks of call data. After clicking "Get License Key", daily over-limit alerts stop for 14 days.

Option 3: Contact Support

Support can:

  • Provide temporary channel limit increase
  • Investigate incorrect CDR counting
  • Issue emergency 30-day trial license (for expired licenses due to billing issues)

Option 4: Delete CDRs (Destructive)

⚠️ Warning: This deletes all existing CDRs. Only use as last resort. 

systemctl stop voipmonitor
mysql -u root -p voipmonitor -e "TRUNCATE TABLE cdr; TRUNCATE TABLE cdr_next_partition;"
systemctl start voipmonitor

To re-process from PCAP files afterward: 

voipmonitor --config-file /etc/voipmonitor.conf --readpcapdir /var/spool/voipmonitor

Trial Expiration

Before purchasing after trial expiration:

  1. Check if license already purchased: voipmonitor.org → Services → My services
  2. If purchased but not applied: Get key.php from order email and install it
  3. Only if no purchase exists: Buy via GUI (About > Buy License) or portal

HWID Mismatch Error

"license file key.php is for another hwid" occurs when hardware ID changed (migration, cloud instance recreation).

Solution: GUI → Settings > License → "Get License" button (auto-syncs with current HWID)

For frequent cloud instance recreation: Request domain-based licensing from support (binds to domain name instead of hardware ID).

"get hwid failed" Error

Problem: The GUI displays "get hwid failed" when attempting to update the license key.

Cause: The web server user cannot read or execute the Hardware ID binary.

Solution:

Test if the hwid binary works as the web server user: 

su - www-data -s /bin/bash -c '/var/www/html/bin/hwid-x86_64'

If this command fails with permission denied, fix the binary permissions: 

chmod +rx /var/www/html/bin/hwid-x86_64

ℹ️ Note: Replace www-data with your web server user (e.g., apache on RHEL/Rocky systems).

After License Renewal

  1. GUI → Settings > License
  2. Click "Change license key" to expand options
  3. Click "Get license key" to fetch updated license

Manual method: Paste full license key (all lines: Expires, easycallerid, hwid, id, maxcalls, upgradeexpire) into the license text field.

Monitoring Usage

Current Status

Check GUI footer or About/License page for active channels vs. license limit.

Historical Data

Tools > Concurrent Calls Stats shows maximum concurrent calls for last 14 days (averaged over 60-minute windows).

Notification Emails

To disable license notification emails:

  1. GUI → Settings > License
  2. Clear the email address field for license notifications
  3. Save changes

ℹ️ Note: This only disables license-related emails (warnings, overage, expiration, lock). Other alerts continue normally.

License Key Management

License Key Location

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

Transferring to New System

  1. Copy key.php from old system to new system
  2. Restart GUI service

For concurrent operation (old + new during migration, or test/dev environments):

  • Contact support to configure license for simultaneous multi-server use (preferred)
  • Or obtain 30-day trial license for temporary system

💡 Tip: For test/dev servers, contact support to reconfigure your existing license for multiple servers at no extra cost.

AWS/Cloud Considerations

Operation HWID Changes? Action Required
Stop & Start Usually No None
Reboot No None
Terminate & Launch New Yes New license key (use "Get License" button or contact support)
Auto-scaling Group Yes per instance Request domain-based licensing

AWS permission fix (for "Invalid or corrupted hwid" errors): 

chmod 644 /dev/root

Subscription Terms

Term Meaning
Formal End Date When your paid service period ends
Grace Period (20 days after) For automatic renewal processing only—NOT extended access after cancellation

⚠️ Warning: If you cancel, access ends on the Formal End Date, not the grace period end.

Emergency access: Contact support for 30-day emergency trial license while resolving billing issues.

Known Issue: Incorrect Channel Counting

⚠️ Warning: Known bug: Some calls are incorrectly counted as two channels. Confirmed and escalated to development team.

Symptoms:

  • License exceeded more frequently than expected
  • Tools > Concurrent Calls Stats shows higher peaks than actual call patterns

Workaround: Contact support for manual channel limit increase (no upgrade required).

See Also

How Legs Are Correlated

Scenario Channels Explanation
Simple call: A → B 1 One CDR leg
Call ending with 487 (Request Terminated) 0 Excluded from counting
Call transfer: A → B → C (creates 2 legs) 1+ Legs correlated if same call context
Forking/parallel ring Multiple One per destination leg
Same call captured by 2 sensors 1 Deduplicated if last 6 digits match (±10s window)

How legs are correlated for license counting: CDR legs are treated as a single channel when:

  • Legs start within 5 seconds of each other AND
  • Last 6 digits of BOTH caller AND called numbers match

This means a single logical call may create multiple CDR legs on the network (e.g., via SBC/B2BUA with generated new Call-IDs) but still count as one license channel.

Cross-sensor deduplication: When the same call is captured by multiple sensors, it's deduplicated if the last 6 digits of caller and called numbers match within a ±10-second window. Geo-redundant captures count as one channel.





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 (transfers, forking, re-invites can create multiple legs from one call). Calls ending with 487 (Request Terminated) are excluded. (2) Distributed deployments: ONE license covers ALL sensors connecting to a single central GUI+DB. Deduplication occurs if last 6 digits of caller/called numbers match within ±10s window. (3) Exceeding limits: 3-day grace period, then lockdown process, GUI locks at day 14. Sniffer continues recording during lock. (4) Resolution options: Upgrade license, self-service 14-day temporary increase via "Get License Key" button (Settings > License), contact support for temporary increase or emergency trial, or delete CDRs (destructive). (5) Monitor usage via GUI footer or Tools > Concurrent Calls Stats (14-day history). (6) License transfer: Copy key.php to new system; contact support for concurrent multi-server use. (7) HWID mismatch: Use "Get License" button to re-sync; request domain-based licensing for frequent cloud instance recreation. (8) AWS: Stop/Start preserves HWID; Terminate/Launch changes it. Use chmod 644 /dev/root for permission issues. (9) Subscription terms: Formal End Date = service ends; Grace Period = renewal processing only. (10) Known bug: Some calls incorrectly counted as two channels—contact support for temporary limit increase.

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 License Key button, key.php, Tools Concurrent Calls Stats, temporary license increase, 14-day temporary license, self-service license increase, incorrect channel counting, known bug, test server, dev server, AWS, EC2, cloud instances, hardware ID, chmod 644 /dev/root, license notification emails, disable license emails, 487 Request Terminated

Key Questions:

  • What is a channel in VoIPmonitor licensing?
  • Can one call consume multiple license channels?
  • What happens when I exceed the channel license limit?
  • How do I unlock my VoIPmonitor GUI after license lock?
  • How do I get a temporary license increase without contacting support?
  • How does licensing work for distributed/multi-server deployments?
  • Do I need a separate license for each sensor?
  • How do I check my channel usage vs license limit?
  • How do I transfer a license to a new system?
  • Can I use my existing license on a test or development server?
  • 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 happens to my VoIPmonitor license when I terminate an AWS EC2 instance?
  • How do I disable license notification emails?
  • Why is my license showing higher channel usage than expected?
  • Does the sniffer stop recording when the GUI is locked?
  • What is the difference between formal end date and grace period?
Retrieved from "https://www.voipmonitor.org/doc/index.php?title=License&oldid=10555"