License: Difference between revisions

From VoIPmonitor.org
(Add manual license key paste in GUI method for offline/network-restricted servers)
(Rewrite: consolidated structure, removed redundancy, added tables for clarity)
(4 intermediate revisions by the same 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? ===


=== Licensing in Distributed / Multi-Server Deployments ===
A channel license limits concurrent calls processed by the VoIPmonitor GUI. Commercial licenses specify a channel cap (e.g., 100, 500, 1000 channels).


For distributed architectures with multiple sensors (sniffers) across multiple datacenters:
{{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.}}
 
* '''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|Architecture Guide]] and [[Sniffer_distributed_architecture|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? ===
=== What Counts as a Channel? ===


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


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.
=== Distributed Deployments ===


This commonly happens in scenarios involving:
For multi-sensor architectures:
* '''Call transfers''' (attended or blind)
* '''Forking''' (parallel ringing to multiple destinations)
* '''Re-invites''' (media session renegotiation)
* '''Complex SIP routing''' (multiple proxies, B2BUA)


For example:
* '''One license covers all sensors''' connecting to a single central GUI+DB
* Simple call: SIP Phone A calls SIP Phone B = 1 CDR = 1 Channel
* Channels are aggregated across all sensors, not multiplied per sensor
* 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'''.
* Same call captured by multiple sensors is deduplicated automatically


==== Why Your License May Require More Channels Than Expected ====
'''Example:''' Sensors in New York, London, and Tokyo connecting to Frankfurt GUI = ONE license sized for total concurrent calls across all sites.


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.
For deployment details, see [[Sniffer_distributed_architecture|Client-Server Mode]].


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


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


<kroki lang="mermaid">
<kroki lang="mermaid">
%%{init: {'flowchart': {'nodeSpacing': 15, 'rankSpacing': 30}}}%%
flowchart LR
flowchart LR
     A[License Limit<br/>Exceeded] --> B[Days 1-3:<br/>Grace Period]
     A[Limit<br/>Exceeded] --> B[Days 1-3:<br/>Grace Period]
     B --> C[Days 4-13:<br/>Lockdown Process]
     B --> C[Days 4-13:<br/>Lockdown]
     C --> D[Day 14+:<br/>GUI Locked]
     C --> D[Day 14+:<br/>GUI Locked]
     style A fill:#ffcc00
     style A fill:#ffcc00
     style B fill:#90EE90
     style B fill:#90EE90
Line 85: Line 58:
</kroki>
</kroki>


# '''3-Day Grace Period:''' You can exceed the limit for up to 3 consecutive days without any blocking
=== Effects When Locked ===
# '''Day 4 onwards:''' The system begins a lockdown process
# '''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:
== Resolving License Issues ==


* '''GUI becomes unusable:''' You cannot access the web interface
=== Option 1: Upgrade License (Recommended) ===
* '''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 ===
# 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]])


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


== Resolving a License Lock ==
For immediate relief without contacting support:


To unlock your VoIPmonitor GUI after it has been locked due to license limit overage:
# GUI → '''Settings > License'''
# Click '''"Get License Key"''' button
# Receive '''14-day temporary increase'''


=== Option 1: Upgrade Your License ===
{{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.}}


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 3: Contact Support ===
 
# Log in to the [https://www.voipmonitor.org 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|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:
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: 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.}}
=== Option 4: Delete CDRs (Destructive) ===


This self-service option is ideal when you need to:
{{Warning|1=This deletes all existing CDRs. Only use as last resort.}}
* 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|1=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:


<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:
 
=== 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:
 
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# 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
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:
 
=== 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|1=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 ===
Before purchasing after trial expiration:


* License channel limit is exceeded more frequently than expected based on your actual concurrent call volume
# Check if license already purchased: voipmonitor.org → '''Services''' → '''My services'''
* The same individual call appears to be counted as two (or more) separate channels
# If purchased but not applied: Get <code>key.php</code> from order email and install it
* Tools > Concurrent Calls Stats shows higher peak usage than your actual call patterns suggest
# Only if no purchase exists: Buy via GUI (About > Buy License) or portal


=== Affected Scenarios ===
=== HWID Mismatch Error ===


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.
'''"license file key.php is for another hwid"''' occurs when hardware ID changed (migration, cloud instance recreation).


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


As a temporary workaround until the bug is fixed in a future release, contact VoIPmonitor support to manually increase your license channel limit:
'''For frequent cloud instance recreation:''' Request '''domain-based licensing''' from support (binds to domain name instead of hardware ID).
* 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 ===
=== After License Renewal ===


If you encounter this issue, please provide VoIPmonitor support with:
# GUI → '''Settings > License'''
* Evidence from Tools > Concurrent Calls Stats showing the unexpected channel spike
# Click '''"Change license key"''' to expand options
* Specific Call IDs or timestamps showing calls that appear to be double-counted
# Click '''"Get license key"''' to fetch updated license
* Your SIP topology description (especially if using unusual routing patterns)


This information helps the development team verify the bug and prioritize the fix.
'''Manual method:''' Paste full license key (all lines: Expires, easycallerid, hwid, id, maxcalls, upgradeexpire) into the license text field.


== Troubleshooting Trial Expiration ==
== Monitoring Usage ==


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:
=== Current Status ===


=== Step 1: Verify If a License Has Already Been Purchased ===
Check GUI footer or '''About/License''' page for active channels vs. license limit.


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


# Log in to the voipmonitor.org portal
'''Tools > Concurrent Calls Stats''' shows maximum concurrent calls for last 14 days (averaged over 60-minute windows).
# 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:
=== Notification Emails ===
* 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.
To disable license notification emails:


=== Step 2: Apply the License Key ===
# GUI → '''Settings > License'''
# Clear the email address field for license notifications
# Save changes


If a license purchase is confirmed but not yet applied:
{{Note|This only disables license-related emails (warnings, overage, expiration, lock). Other alerts continue normally.}}


# Obtain the license key from the order confirmation email or portal
== License Key Management ==
# 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
# Restart the VoIPmonitor service


=== Step 3: If No Purchase Found in System ===
=== License Key Location ===
 
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:


<code>/var/www/html/voipmonitor/key.php</code>
<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.
=== Transferring to New System ===


== Transferring a GUI License to a New System ==
# Copy <code>key.php</code> from old system to new system
# Restart GUI service


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


=== Using Your Existing License ===
{{Tip|For test/dev servers, contact support to reconfigure your existing license for multiple servers at no extra cost.}}


When moving to a new system:
=== AWS/Cloud Considerations ===
* 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 <code>/var/www/html/voipmonitor/key.php</code>.
{| 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
|}


=== Running Old and New Systems Concurrently ===
'''AWS permission fix''' (for "Invalid or corrupted hwid" errors):
 
<syntaxhighlight lang="bash">
If you need to keep both the old and new systems running simultaneously during migration, you have two options:
chmod 644 /dev/root
 
</syntaxhighlight>
==== Option 1: Configure Your Existing License for Concurrent Use ====
 
The same license token and key can be used for the new platform. Contact VoIPmonitor support to have the license configured to allow simultaneous use during the migration period.
 
* Use your existing license token on both the old and new systems
* Contact support to configure the license for concurrent operation
* No need for temporary or trial licenses
* Simplest approach for most migration scenarios
 
This is the recommended first option when you need to run both systems during migration.
 
==== Option 2: Temporary Trial License ====
 
As an alternative, you can obtain a temporary trial license for the new system:
 
* Log in to [https://www.voipmonitor.org 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., <code>your-gui.example.com</code>)
# Request to convert your license from hardware-bound to domain-bound
 
This prevents the need to manually update the license file each time a new instance is launched.
 
== Refreshing License After Renewal ==
 
When your license is renewed or extended in the VoIPmonitor portal, your local installation may continue to show the error '''"FAILED license file key.php expired"''' until the license key is updated.
 
=== Using the GUI "Get 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 <code>https://download.voipmonitor.org</code> on port 443 and that no firewall or proxy is blocking the connection.}}
== Subscription Terms ==


=== Manual License Key Update ===
{| class="wikitable"
|-
! 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
|}


If the GUI button does not work or you prefer to manually update the license key, you have two methods:
{{Warning|1=If you cancel, access ends on the Formal End Date, not the grace period end.}}


==== Method 1: Paste License Key in GUI (Recommended) ====
'''Emergency access:''' Contact support for 30-day emergency trial license while resolving billing issues.


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:
== Known Issue: Incorrect Channel Counting ==


;Steps:
{{Warning|1=Known bug: Some calls are incorrectly counted as two channels. Confirmed and escalated to development team.}}
# 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:
#* <code>Expires</code>
#* <code>easycallerid</code>
#* <code>hwid</code>
#* <code>id</code>
#* <code>maxcalls</code>
#* <code>upgradeexpire</code>
# Click '''Save''' or '''Apply Changes'''
# Verify the license status changes to '''OK'''


{{Note|1=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.}}
'''Symptoms:'''
* License exceeded more frequently than expected
* Tools > Concurrent Calls Stats shows higher peaks than actual call patterns


==== Method 2: Upload key.php File ====
'''Workaround:''' Contact support for manual channel limit increase (no upgrade required).


Alternatively, if you have the license file:
== See Also ==


;Steps:
* [[Billing]] - Call cost calculation
# Log in to the [https://www.voipmonitor.org VoIPmonitor Portal]
* [[Reports]] - Report configuration
# Navigate to your license section and download the new <code>key.php</code> file
* [[GUI_Installation]] - Installation and upgrade procedures
# In the GUI, navigate to '''Admin > License''' or '''Settings > License'''
* [[Sniffer_distributed_architecture|Client-Server Mode]] - Multi-sensor deployments
# Upload the new <code>key.php</code> file
# Verify the license status changes to '''OK'''
 
=== Troubleshooting ===
 
* '''Error persists after clicking "Get/Update License":''' Verify that the license has been renewed in the VoIPmonitor portal and the order status is "Active" or "Completed"
* '''"License file key.php is for another hwid":''' See [[#Resolving "license file key.php is for another hwid" Error|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 ==
== AI Summary for RAG ==


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

Revision as of 16:48, 8 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)

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

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

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