FAQ

This page provides answers to frequently asked questions and solutions to common issues encountered during the configuration and operation of VoIPmonitor.

Quick Navigation

General Topics	Configuration	Troubleshooting Guides	Files & Compliance
Scaling Licensing Platform Support CDR View	SIP Ports, IPv6, DTMF Admin Tasks Capture Rules	Dedicated Pages: GUI Troubleshooting - HTTP 500, DB corruption, upgrades Sniffer Troubleshooting - no CDRs, packet capture issues Quick Q&A (this page): Password reset, reinstall Network/DNS issues Database table errors	Audio/PCAP PCI Compliance CALEA Compliance

General & Scalability

How does VoIPmonitor scale for high traffic?

For a detailed guide on performance tuning, hardware recommendations, and optimizing the three main system bottlenecks (CPU, Disk I/O, Database), please refer to our comprehensive Scaling and Performance Tuning guide.

How do I manage disk space and database size?

VoIPmonitor uses separate mechanisms for cleaning PCAP files from the filesystem and CDRs from the database. For a complete walkthrough, see the Data Cleaning and Retention guide.

Can I run multiple GUI instances for redundancy or external access?

Yes, you can run multiple GUI instances pointing to the same database and storage. This is useful for creating a second externally accessible GUI (e.g., in a DMZ) or for GUI redundancy while keeping your sensors and database safely within your internal network.

Setup requirements:

• Database access: All GUI instances must connect to the same MySQL/MariaDB database. Ensure the database allows remote connections from each GUI's IP address.
• PCAP storage access: Each GUI needs access to the PCAP files. This is typically achieved via NFS/SSHFS mounting from the primary storage server.
• License configuration: Copy your existing license file (key.php) to each GUI server. If the hardware IDs differ, contact VoIPmonitor support to add the additional HWIDs to your license token.

CRITICAL: Cron Job Conflict

Alerts and daily reports are generated by a cron job that runs every minute on the GUI server. If you enable this cron job on multiple GUI instances, you will receive duplicate alerts and reports.

To prevent conflicts:

1. Enable the cron job on only one GUI instance (typically your primary internal GUI for active monitoring).
2. Disable the cron job on all secondary/redundant GUI instances.
3. Verify that the cron job exists in /etc/crontab or system cron configuration on each server.
4. Comment out or remove the cron line on secondary servers:

# On secondary GUI servers - DISABLE the cron job
# * * * * * root php /var/www/html/php/run.php cron

The GUI without the cron job will still function for viewing data, searching calls, and manual report generation - it simply will not process automated alerts or daily scheduled reports.

CDR (Call Detail Record) View

What does the small red icon in the CDR view mean?

The red icon () indicates which party in the call sent the BYE message first, effectively ending the call.

How can I use regular expressions to filter calls?

The filter bar in the CDR view supports regular expressions. This is useful for finding malformed or unusual data. For example, to find all calls where the caller number contains non-numeric characters, you can use a negative match:

!R(^[+]?[0-9]+$)

Why is there a delay between when a call ends and when it appears in the CDR view?

This delay is typically caused by the database's inability to keep up with the rate of incoming calls, creating a queue of SQL queries on the sensor. For solutions, please read:

• SQL queue is growing in a peaktime
• Minimizing Delay Between Call End and CDR Database Storage

How can I enable millisecond precision for timestamps in the CDR view?

By default, timestamps are stored with second precision. To enable millisecond precision, please follow the steps in this guide: How_to_enable_milliseconds_precision.

How do I search for multi-word strings in custom header fields?

When searching for a multi-word string (e.g., "Normal Call Clearing") in a custom header field, the system interprets spaces as logical OR operators by default. To search for the exact multi-word string, use an underscore (_) as a wildcard character to represent the space.

Example: To search for "Normal Call Clearing", use:

%normal_call_clearing%

The underscore acts as a wildcard that matches a single character (in this case, the space), while the percent (%) matches any number of characters before and after the phrase.

Can I generate a report of concurrent calls broken down by individual source IP address?

No, this functionality is not currently available via the GUI, the Web API, or a simple SQL query. The system can show total concurrent calls over time (in Charts > "number of calls") and can provide call summaries grouped by IP address (in Reports > Call Summary), but there is no built-in function to display concurrent calls per individual source IP over time without creating separate chart series or filters for each IP.

Workarounds:

• Use the Call Summary report to see aggregate call statistics per IP (total calls, duration, etc.)
• Create separate series in Charts for each IP using the Filters tab (requires individual IP filters)
• Create IP Groups to group multiple IPs and create charts per group

Why do caller and called numbers appear swapped in the CDRs?

VoIPmonitor extracts caller and called numbers from the SIP INVITE packet using specific header sources. By default:

• Caller number: Taken from the From header
• Called number: Taken from the To header (default mode)

If the numbers appear swapped, verify the following:

1. Check Default Behavior First, verify this is not simply a misunderstanding of how VoIPmonitor extracts the numbers. The default extraction uses:

• Caller = From header
• Called = To header

You can verify this by opening a call detail in the GUI, navigating to the SIP History tab, and inspecting the From and To headers in the first INVITE packet.

2. Adjust destination_number_mode Configuration If your PBX or SIP devices use a different convention for distinguishing caller/called numbers, you can change the source for the called number in voipmonitor.conf:

[general]
# Default: 1 = To header
# Alternative: 2 = INVITE URI
destination_number_mode = 1

Set destination_number_mode = 2 to use the INVITE Request-URI as the source for the called number instead of the To header. This may resolve swapped number issues in certain PBX configurations.

3. Check for Override Headers Some SIP headers can forcibly update the caller/called numbers. If these are misconfigured, they can cause swapped numbers:

• remoteparty_caller / remoteparty_called - Update numbers from Remote-Party-ID header
• passertedidentity = yes - Use P-Asserted-Identity header for caller
• ppreferredidentity = yes - Use P-Preferred-Identity header for caller

If these options are enabled, try disabling them or verify that the SIP headers contain the correct values:

[general]
# Comment out or remove to disable
# remoteparty_caller = calling
# remoteparty_called = called
# passertedidentity = no
# ppreferredidentity = no

4. Apply Configuration Changes After editing voipmonitor.conf, restart the sensor service:

systemctl restart voipmonitor

5. Test and Verify Generate a new test call and check the CDR to see if the numbers are now correctly assigned to caller and called fields.

For more detailed configuration options, see the Caller/Called Identity Configuration section of the Sniffer Configuration guide.

How do I prevent VoIPmonitor from tracking calls from a specific IP address or SBC?

If VoIPmonitor is capturing calls from a VoIP gateway or SBC that should not be monitored (causing skewed statistics in reports), you can exclude that traffic by using the global filter directive in voipmonitor.conf. This applies a BPF (Berkeley Packet Filter) expression to drop packets from specified IPs before they are processed.

Steps to exclude traffic from a specific IP:

[general]
# Exclude a single IP address
filter = not host 203.0.113.50

# Or exclude multiple IPs
filter = not host 203.0.113.50 and not host 203.0.113.51

# Or exclude entire subnets
filter = not net 203.0.113.0/24

Important Notes:

• The filter directive uses BPF syntax (tcpdump-style expressions)
• Changes to this setting require restarting the sensor service:

systemctl restart voipmonitor

• This filter applies at the packet capture level and prevents any traffic from the specified IPs from being analyzed or stored
• Use not host for single IPs and not net for IPv4 subnets in CIDR notation

Alternative: GUI-Based Filtering (Database Level)

If you want to exclude traffic after it has been captured (but still retain the ability to filter it back in), use the MySQL-based capture rules instead of the global packet filter:

1. Go to the GUI: Configuration > Filter rules
2. Add an IP filter rule for the unwanted IP
3. Set the rule to "Skip" status (this skips creating CDRs for calls matching this IP)
4. Save and click "Reload configuration"

The GUI filter rules are more flexible for temporary exclusions because they do not require service restarts to change. However, the global filter directive is more efficient as it drops the packets before processing.

Why do calls with failover or serial forking show incorrect Last SIP Response?

In scenarios where a PBX uses serial forking or failover (e.g., trying one destination, canceling with 487 Request Terminated, then successfully connecting to another destination with 200 OK), VoIPmonitor may display the intermediate failure response code (487) as the Last SIP Response instead of the final successful response (200 OK). This causes successful calls to be incorrectly marked as FAILED in the CDR.

Current Status: This behavior is a known issue under investigation by the VoIPmonitor development team. No configuration option is currently available to correct this display issue.

How It Affects You:

• Calls that actually completed successfully may appear as FAILED with Last SIP Response: 487 Request Terminated
• This typically occurs in call forking scenarios where multiple destinations are tried sequentially
• The call recording and audio capture are still correct - only the displayed status/response column is affected
• Call statistics and reports based on the status column may be inaccurate

Workaround: Focus your analysis on the actual SIP signaling flow (in the CDR detail view or SIP History tab) rather than relying solely on the Last SIP Response or status columns. The full SIP trace will show both the intermediate 487 response and the final 200 OK response, allowing you to determine the actual call outcome.

Reporting This Issue: If you encounter this behavior and can provide a packet capture (.pcap) from the sniffing interface along with the affected Call-ID and timestamp, please contact VoIPmonitor support. This diagnostic data helps the development team investigate and resolve the issue.

Platform & Environment Support

What hardware architectures does the sensor support?

The sensor is tested and supported on x86 (32/64-bit) and ARMv7/v8 architectures. If you encounter an error like __sync_fetch_and_sub_8 on an older ARM device, you may need to upgrade your GCC compiler to version 4.8 or newer.

What hardware architectures does the GUI support?

The VoIPmonitor GUI requires an x86 (32/64-bit) architecture system. The GUI is not supported on aarch64 (ARM64) platforms. If you need to run VoIPmonitor on ARM64 hardware:

• The sensor/sniffer component can be compiled from source for ARM64 architectures
• You must run the GUI on a separate x86 system that connects to the ARM64 sensor's database
• For sensor compilation instructions on ARM64, see the Compiling from Source section of the Sniffer Installation guide

Can I run VoIPmonitor on AWS?

Yes, AWS is supported. For the license check to function correctly on some Amazon Machine Images (AMIs), you may need to adjust permissions on the root device file:

chmod 644 /dev/root

Important: Hardware ID behavior on AWS

• Stopping and starting an instance: Usually preserves the hardware ID, so your license will continue to work.
• Terminating and launching a new instance: Changes the hardware ID, requiring a new license key from VoIPmonitor support. There is no automatic re-issuance process for this scenario.
• Alternative: Domain-locked license: As an alternative to hardware binding, a license can be locked to a URL domain instead. Contact VoIPmonitor support if you need this option for dynamic cloud environments.

Is Docker or other container environments supported?

Yes, the GUI and sensor can run in a containerized environment. However, you must ensure that the content of /proc/self/cgroup does not change with every container restart. If it does, the hardware ID will change, and you will be prompted to update your license key after each reboot.

Are hosted/cloud databases (like Amazon RDS, Azure Database) supported?

Yes, VoIPmonitor requires a MySQL-compatible database (MySQL, MariaDB, Percona) and can connect to it regardless of its location. However, the database user requires SUPER privilege for creating functions and triggers.

What if my cloud database (like Azure) does not grant SUPER privilege?

If SUPER privilege is not available, you must manually set the following server variable in your cloud database configuration console:

log_bin_trust_function_creators = ON

Additionally, ensure your database instance has sufficient performance (e.g., at least 1100 IOPS for 5000 concurrent calls on Azure).

Why is MySQL reporting a deprecation warning for mysql_native_password? Can I use caching_sha2_password?

MySQL 8.0 and MySQL 8.4+ (default in Ubuntu 24.04, Debian 12/13, Rocky 9, etc.) default to caching_sha2_password authentication and display deprecation warnings when the older mysql_native_password method is used.

Short Answer: You do not need to force mysql_native_password if your PHP version is 7.4.4 or newer. The VoIPmonitor GUI automatically supports caching_sha2_password when using a modern PHP version with the mysqlnd driver.

Recommended Solution (Best Practice):

1. Upgrade your PHP version to 7.4.4 or newer (recommended: 8.0, 8.1, 8.2, or 8.3).
2. Reinstall the IonCube Loader for your new PHP version. See GUI Installation Guide - Step 3.
3. Reinstall the VoIPmonitor GUI. See GUI Installation Guide - Reinstalling.

After this upgrade, the GUI will automatically use the authentication method configured for your database user (no additional configuration needed). Remove any default_authentication_plugin=mysql_native_password lines from your MySQL configuration.

Alternative Solution (Legacy PHP):

If you must use an older PHP version (before 7.4.4), you can force mysql_native_password by adding the following to your MySQL configuration file:

# /etc/mysql/mysql.conf.d/mysqld.cnf (or /etc/my.cnf.d/mysql-server.cnf on RHEL-based systems)
default_authentication_plugin=mysql_native_password

After making changes, restart the MySQL service and recreate your database user using the old method:

ALTER USER 'voipmonitor'@'127.0.0.1' IDENTIFIED WITH mysql_native_password BY 'YourPassword';
FLUSH PRIVILEGES;

⚠️ Warning: This alternative approach suppresses the warning but uses a deprecated authentication method. Upgrading PHP to 7.4.4+ is strongly recommended for security reasons.

Why is packet mirroring not working on VMWare ESXi 6.5+?

This is often caused by the vSwitch port group being set to VLAN 4095, which activates Virtual Guest Tagging (VGT). In this mode, the guest OS is expected to handle VLAN tags, which can disrupt sniffing.

Solution: Edit the port group settings in vSphere and change the VLAN ID to a specific number (e.g., 0 or your monitoring VLAN ID) instead of 4095.

Configuration & Features

Which VoIP protocols are supported by VoIPmonitor?

VoIPmonitor supports the following protocols for call monitoring and analysis:

• SIP - Session Initiation Protocol (default, port 5060)
• Skinny/SCCP - Cisco Skinny Call Control Protocol (enable with skinny=yes)
• MGCP - Media Gateway Control Protocol (enable with mgcp=yes)
• SS7/ISUP - Signaling System 7 and ISDN User Part monitoring (requires separate database schema)
• Diameter - Diameter protocol support
• RTCP - Real-Time Control Protocol (monitored alongside RTP)

Not Supported

• H.323 is not supported by VoIPmonitor. If you have H.323 traffic, you will not see it in the monitoring system.

Why don't I see SIP packets on ports other than 5060?

By default, the sensor only listens for SIP traffic on UDP/TCP port 5060. To monitor additional SIP ports, you must explicitly define them in voipmonitor.conf. See the sipport configuration guide.

How do I enable IPv6 traffic processing?

By default, IPv6 is disabled. To enable it on a new installation, set ipv6=yes in voipmonitor.conf. If you have existing IPv4 data, enabling IPv6 requires a database migration. For detailed instructions, please see the IPv6 Enabling Guide.

How do I capture and view SIP REGISTER messages?

By default, REGISTER messages are not stored. To enable this, set sip-register=yes in voipmonitor.conf. For details on how active and failed registrations are stored and how to query them via the API, see the documentation on REGISTER monitoring.

How can I capture DTMF tones?

You can enable DTMF capture in voipmonitor.conf:

• For RFC2833 and SIP INFO methods, set: dtmf2db = yes
• For inband DTMF (G.711 codec only, requires more CPU), set: inbanddtmf = yes

Why are quality metrics (MOS, jitter, packet loss) missing for one call leg?

If you see quality metrics (MOS, jitter, packet loss) for the caller (A-leg) but not for the callee (B-leg), or vice versa, this typically indicates that the RTP stream for one leg is not being correctly associated with the call.

Common Cause: NAT IP Address Mismatch In NAT environments, the SDP (Session Description Protocol) in the SIP signaling may announce a public IP address for the RTP media, but the actual RTP packets arrive with a different private IP address. VoIPmonitor uses the SDP IP to match RTP streams to call legs, so when there is a mismatch, the RTP packets for that leg are not processed.

Diagnostic Steps:

1. Check the CDR Detail view for the problematic call.
2. Note the IP addresses in the SDP (shown in the SIP columns or Message Detail).
3. Use a packet capture tool (tcpdump/tshark) to verify the actual IP address of the RTP packets for the missing leg.
4. If the SDP IP and actual RTP IP differ, this is a NAT mismatch scenario.

Solution: Configure natalias Add a natalias mapping to /etc/voipmonitor.conf to tell VoIPmonitor that the actual RTP stream IP (source) corresponds to the SDP-announced IP (destination):

# Mapping format: natalias = <public_ip> <private_ip>
# This tells VoIPmonitor that RTP from public_ip matches SDP announcements with private_ip
natalias = 1.2.3.4 10.0.0.100

Important: natalias works bidirectionally The natalias directive creates a two-way mapping. You can specify the IPs in either order:

# Both formats are equivalent - they create the same bidirectional mapping:
natalias = 1.2.3.4 10.0.0.100
# OR
natalias = 10.0.0.100 1.2.3.4

You can add multiple natalias lines if you have multiple mappings.

Troubleshooting: Try reversing the IP order If RTP association fails after adding natalias, try reversing the IP addresses in the configuration:

# Original attempt (did not work)
natalias = 1.2.3.4 10.0.0.100

# Try reversing (swapping the order)
natalias = 10.0.0.100 1.2.3.4

Restart the sniffer after making this change and test again.

Advanced: Checking for Port Mismatches If you have verified IP addresses match but still see missing audio, the issue may be a port mismatch:

1. Capture packets from a problematic call

tshark -i eth0 -Y "sip" -w /tmp/test_call.pcap

2. Compare SDP-advertised ports with actual RTP ports

# Extract SDP RTP ports from SIP INVITE in the capture
tshark -r /tmp/test_call.pcap -Y "sip" -T fields -e rtp.setup

# Extract actual RTP ports from traffic
tshark -r /tmp/test_call.pcap -Y "rtp" -T fields -e udp.srcport

3. If the ports do NOT match

An external device (such as an SBC, media server, or load balancer) is modifying the media ports between SIP signaling and actual RTP transmission. This is outside VoIPmonitor's control.

Solution: Fix the configuration on the external device to preserve port consistency, or configure it to use ports that match the SDP announcements exactly. VoIPmonitor requires SDP ports and actual RTP ports to match for call correlation.

Apply the configuration:

# Edit configuration
vi /etc/voipmonitor.conf

# Restart sniffer
systemctl restart voipmonitor

After restarting the sniffer, new calls should display quality metrics for both legs. For existing calls in the database, you can use the PCAP import feature with the same natalias configuration to reprocess and show the metrics.

For additional NAT-related configuration options, see NAT Configuration in the Sniffer Configuration reference.

Why are RTP packets not associated with the correct call legs after moving SIP and RTP to different NICs or VLANs?

This typically occurs when SIP signaling and RTP media arrive on different network interfaces, NICs, or VLANs, and the packet correlation logic needs adjustment.

Root Cause: When SIP and RTP traffic paths change (e.g., SIP on eth0/VLAN 10 and RTP on eth1/VLAN 20), the sniffer may incorrectly match RTP packets to call legs if the internal packet buffering and defragmentation logic is not optimized for multi-interface scenarios.

Solution: Set auto_enable_use_blocks = yes in /etc/voipmonitor.conf and restart the sniffer service:

# Edit configuration
echo "auto_enable_use_blocks = yes" >> /etc/voipmonitor.conf

# Restart sniffer
systemctl restart voipmonitor

This option enables memory blocks for proper packet processing across multiple interfaces. It is required in two scenarios: (1) deduplication when receiving duplicate packets from multiple sources, and (2) correct RTP association when SIP and RTP arrive on different interfaces, NICs, or VLANs. See Sniffer Configuration for details.

Additional Checks:

• Verify interface in voipmonitor.conf includes all relevant NICs (e.g., interface = eth0,eth1)
• Check vlan_siprtpsame = no (allows different VLANs for SIP and RTP)
• If IP addresses changed due to NAT, configure natalias for proper mapping

Why do call recordings show audio from multiple different calls or have one-way audio when network stats look fine?

This occurs when RTP packets from different calls are being incorrectly matched to the wrong SIP call legs, causing audio mixing or silence on one side despite normal network statistics.

Root Cause: In complex SIP deployments with multiple endpoints, SBCs, or NAT environments, the sniffer may associate RTP packets to incorrect call legs based on port matching alone. This happens when the IP:port-based matching logic does not consider SDP (Session Description Protocol) information for both sides of the call.

Solution: Enable rtp_check_both_sides_by_sdp = yes in /etc/voipmonitor.conf:

# Edit configuration
vi /etc/voipmonitor.conf
# Add or modify:
rtp_check_both_sides_by_sdp = yes

# Restart sniffer
systemctl restart voipmonitor

This option forces the sniffer to verify RTP packets by checking both source and destination IP:port against SDP information, ensuring correct RTP stream assignment to call legs.

Configuration Options:

• no: Disabled (default)
• yes: Verify both sides per SDP
• keep_rtp_packets: Same as 'yes' but store unverified packets for debugging
• strict: Allow unverified packets until first verified packet arrives
• very_strict: No unverified packets allowed at any time

When to Use:

• Call recordings contain audio from multiple different calls
• One-way audio occurs when network stats (jitter, packet loss, MOS) appear normal
• RTP streams appear partially associated or completely missing in CDRs
• Deployments with complex NAT scenarios or Session Border Controllers (SBCs)

Important Notes:

• Use keep_rtp_packets when debugging to preserve extraneous packets for analysis
• For multi-interface deployments, you may need to combine with auto_enable_use_blocks = yes
• See RTP Tracking & SDP Configuration for additional related options

Verification:

After enabling this option, verify the fix by:

1. Check that new call recordings show correct audio (no mixing from other calls)
2. Review CDR RTP statistics - should show complete audio on both legs

• Use the GUI to play back recent calls and confirm audio quality

How can I use the sensor's manager API securely?

Modern sniffer versions (32.0+) have API encryption enabled by default. Please refer to the Manager API Encryption guide for examples on how to use the API with or without encryption.

How does VoIPmonitor handle AudioCodes-tunneled traffic?

VoIPmonitor can process traffic encapsulated in AudioCodes' proprietary tunneling protocol. For setup details, see the AudioCodes Tunneling guide.

Can wildcards or regular expressions be used in domain-based capture rules?

No, domain-based capture rules only support exact string matching. Wildcards and regular expressions are not supported for domain matching in capture rules.

For different rule types, VoIPmonitor supports the following matching methods:

Rule Type	Matching Supported	Example
IP Addresses	CIDR subnet masks (wildcard networks)	1.2.3.0/24 matches all IPs in that range
Telephone Numbers	Prefix matching (equivalent to wildcard)	4420 matches 4420*
SIP Domains	Exact match only	example.com ONLY matches example.com, not sub.example.com

If you need more complex domain matching logic (such as patterns or subdomains), you must use the filtercommand option with an external script, or use regular expressions in the CDR view filter bar for searching recorded calls.

Licensing

How do I determine the number of license channels I need?

The license is based on the maximum number of concurrent calls during your peak hours. It is not based on the number of phones or endpoints. You can find your peak usage by navigating in the GUI to Tools → System Status → Concurrent calls, which shows data for the past 14 days.

The system calculates the maximum concurrent calls by averaging over 1-hour periods, and checks this once per day. In distributed environments with multiple sensors feeding a central GUI, a single logical call is counted only once regardless of how many sensors processed it (the system correlates call legs by matching the last 6 digits of the caller and called numbers within a time window).

What happens if my call volume temporarily exceeds my license limit?

Important: The license alert is temporary and self-clearing.

If you exceed your concurrent call limit for a single day or occasionally, a warning message will appear in the GUI. This warning is temporary and will disappear automatically once your call volume returns to normal levels. No manual action is required to clear the warning.

When does the GUI become locked?

The GUI only becomes fully locked if the license limit is exceeded for three or more consecutive days.

What happens if I exceed my license for three consecutive days?

If high usage persists for three consecutive days within the 14-day grace period, the license will be temporarily blocked. To resolve this, you can:

1. Click the "get/update license" button in the GUI (Settings > License) - This will automatically fetch a temporary complimentary channel limit increase to unblock your system immediately. This is provided as a self-service option without requiring support contact upfront. The temporary increase will automatically revert to your original limit after a specified period (typically two weeks).
2. Delete the CDRs from the spike period via the GUI filter and delete tools (to reset the statistics).
3. Upgrade your license to a higher channel count via the voipmonitor.org customer portal.
4. Wait for the next 14-day window - the system allows spikes in different 14-day periods.

The GUI shows "expires in 30 days" and I'm concerned this is caused by exceeding my license limit. Is this related to overage?

No, the "expires in 30 days" message is completely unrelated to license overage events and is part of the normal monthly subscription cycle.

• For monthly licenses, the GUI always displays a 30-day countdown to the next billing/subscription period. This is standard behavior for all monthly subscription plans.
• This countdown is not triggered by exceeding your channel limit - it purely reflects your monthly subscription billing cycle.
• A single day or occasional overage will NOT cause your license to expire or change this countdown.
• Your license will only be blocked if you exceed the limit for three or more consecutive days (see previous question), and this blocking is temporary and reversible.
• When you see "expires in 30 days," it simply means your monthly billing period will renew in 30 days assuming you continue your subscription.

If you are concerned about expiration, contact VoIPmonitor support to verify your subscription status and billing information.

I get an "Invalid or corrupted hwid" error when trying to activate my license. What should I do?

There are two common causes for this error. Check which scenario applies to your situation:

Scenario 1: License key formatting issue (most common)

The license key is a multi-line text block that contains several fields such as Expires, easycallerid, id, and upgradeexpire. A very common mistake is copying only the first line of the key instead of the entire multi-line block.

• Ensure you select and copy the entire license key text (all lines) from your license email or customer portal.
• Paste the complete multi-line key into the activation field in the GUI.
• Do not truncate or remove any lines from the key.

Scenario 2: Hardware ID detection issue

If you have entered the complete license key correctly and still receive this error, the system may be unable to generate or read the hardware ID (HWID). This is most common in specific environments:

• AWS EC2: Run chmod 644 /dev/root to fix permissions on the root device.
• Docker/Containers: Ensure the container ID in /proc/self/cgroup does not change between restarts.
• Corrupted license file: Remove /var/www/html/key.php and re-fetch the license via the "get license key" button in the GUI.

Scenario 3: HWID not generated or invisible in GUI

If you are installing the GUI on a new server and the hardware ID (HWID) cannot be generated or detected automatically, or if the GUI shows a blank or missing HWID field, you can manually generate the HWID using the hwid binary.

Steps to manually generate HWID:

1. SSH into your server as root.
2. Navigate to the GUI installation's bin directory (default is /var/www/html/bin or /var/www/voipmonitor/bin).
3. Run the hwid binary as the web server user to generate the hardware ID:

For Debian/Ubuntu systems using Apache:

runuser -u www-data -- ./hwid-x86_64

For Red Hat/CentOS systems using Apache:

sudo -u apache ./hwid-x86_64

For Nginx systems (adjust user as needed):

runuser -u nginx -- ./hwid-x86_64

1. Copy the HWID string that appears in the output.
2. Log in to the VoIPmonitor services portal (http://www.voipmonitor.org/services).
3. Navigate to your license and associate it with this new HWID to generate an updated license key.
4. Return to the GUI and paste the new license key into the license activation field.
5. Save to activate the license.

Scenario 4: Trial token requested from different machine

If you requested a trial license token on one machine but are attempting to use it on a different system (such as a VM or cloud instance), you will receive an "invalid or corrupted hwid" error because the token is cryptographically bound to the hardware ID of the original machine where the request was made.

• Quick workaround for trial licenses: Contact VoIPmonitor support and request a pre-generated license key for the VM's hardware ID. Support can generate the full key directly for you without requiring you to use the token or self-service portal, which may be restricted (e.g., "only one trial allowed" per account).
• Provide the VM's hardware ID: Log in to the VoIPmonitor GUI on the target VM, navigate to Settings > License, and copy the displayed Hardware ID. Include this in your support request.
• Advantage of this approach: Obtaining a full pre-generated license key from support bypasses the token system entirely and avoids HWID mismatch issues, especially useful for trial scenarios where the portal may block additional trial generation for the same account.

If the above steps do not resolve the issue

If you have verified the license key format and fixed any HWID detection problems, but the error persists, this indicates the license key may have been generated for a different hardware ID. Follow these steps:

• Contact VoIPmonitor support to verify your license and report the error.
• Provide the full multi-line license key and your manually generated HWID when contacting support.
• Support will verify the key and regenerate it to match the correct hardware ID if a mismatch is found.

Scenario 5: Consider domain-based licensing as an alternative

If your infrastructure frequently changes hardware IDs (e.g., containerized environments, cloud deployments with changing cgroups), or if you cannot stabilize the HWID despite following the steps above, you can request that your license be switched from hardware-based to domain-based licensing.

Advantages of domain-based licensing:

• Eliminates HWID mismatch errors entirely.
• Ideal for cloud/container environments where hardware identification is unstable.
• Allows license portability without requiring support intervention for each infrastructure change.

Steps to switch to domain-based licensing:

1. Identify your License ID from the VoIPmonitor Settings > License page.
2. Contact VoIPmonitor support and request to switch your license from hardware-based to domain-based validation.
3. Provide the License ID and the desired domain name (typically your server's FQDN, e.g., monitor.example.com).

• Wait for support to confirm the license conversion.
• Log in to your VoIPmonitor GUI and reload the license via Settings > License > get/update license key.
• The system will now validate against the domain instead of hardware ID.

I get a "license file key.php is for another hwid" error after changing my server hardware. How do I fix this?

This error occurs when you have replaced or modified hardware (motherboard, network card, moved to a new VM, etc.) and the hardware ID (HWID) embedded in your license no longer matches the new server configuration.

Quick Solution (Recommended)

Most license tokens support automatic re-issuance for updated HWID. Try these steps:

1. Log in to the VoIPmonitor web GUI.
2. Navigate to Settings > License.
3. Click the get/update license key button.
4. Click the recheck button to synchronize the license with your new hardware ID.
5. The system should automatically fetch and apply a license key matching the new HWID.

Important: This workflow is acceptable as long as the HWID changes only when you actually modify server hardware. If the HWID changes without any hardware modifications, contact VoIPmonitor support to investigate the issue.

Manual Solution (If automatic update fails)

If the automatic update method above does not work, or if you receive an error, follow these manual steps:

1. Navigate to your GUI installation's bin directory (/var/www/html/bin or /var/www/voipmonitor/bin).
2. Generate the new hardware ID using the hwid binary as the web server user:

For Debian/Ubuntu (Apache):

runuser -u www-data -- ./hwid-x86_64

For Red Hat/CentOS/AlmaLinux (Apache):

sudo -u apache ./hwid-x86_64

For Nginx:

runuser -u nginx -- ./hwid-x86_64

1. Copy the new HWID string that appears in the output.
2. Log in to the [VoIPmonitor Services Portal](https://www.voipmonitor.org/services) and associate your license with this new HWID.
3. Return to the GUI and paste the updated full license key into the License key field under Settings > License.

Troubleshooting

• If the HWID changes frequently without hardware changes, there may be a container configuration issue. Ensure the container ID in /proc/self/cgroup does not change on each restart.
• For AWS EC2 instances, verify /dev/root has correct permissions: chmod 644 /dev/root.
• If automatic HWID updates fail repeatedly, contact VoIPmonitor support to verify your license configuration.

I get a "Bad Key Content" error when pasting my license. What should I do?

This error most commonly occurs when you have used the wrong field for your license type. The GUI has two different license fields with different purposes:

Problem: Using the wrong field for online activation

1. If you obtained a license token (short text string) from the Members' Area or a trial license link, do NOT paste it into the "License key" field.
2. The "License key" field is for offline activation only, where the full multi-line license key is pasted directly.
3. Pasting a short token into the "License key" field will result in "Bad Key Content" error.

Solution:

1. Navigate to Settings > License.
2. Paste your license token (short text string) into the "License token" field.
3. Click the "get/update license key" button to automatically fetch and apply the license.
4. The system will connect to the VoIPmonitor license server and download your license key automatically.

Important: The two fields have different purposes

• License token field: Short token string from Members' Area or trial license link. Use this for online activation with the "get/update license key" button.
• License key field: Full multi-line license key formatted content. Use this only for offline activation when pasting the complete key file content (includes fields like Expires, hwid, id, maxcalls, upgradeexpire, etc.).

For detailed installation instructions including trial license setup, see GUI Installation - License Key.

How do I manually update my license when the automatic update fails?

If the VoIPmonitor server cannot reach the license server due to network restrictions, firewall, or proxy configuration issues, you can manually update the license through the web GUI.

1. Contact VoIPmonitor support to obtain the full, formatted license key.
2. Log in to the VoIPmonitor web GUI.
3. Navigate to Settings > License (or click the "get/update license" button if available).
4. Paste the entire multi-line license key into the provided text field.
5. Save the changes to apply the new license.

Important: Make sure you copy the complete license key including all lines (Expired, easycallerid, hwid, id, maxcalls, upgradeexpire, etc.). Truncating or omitting lines will cause activation errors. See the question above about "Invalid or corrupted hwid" for more details about license key formatting.

For persistent connectivity issues preventing automatic license updates, see FAQ#How_do_I_troubleshoot_internet_connectivity_issues for network and proxy configuration troubleshooting.

The GUI shows a "download failed" error when trying to update the license key. How do I troubleshoot this issue?

If the GUI displays a "download failed" error when you click the "get/update license" button, this typically indicates a connectivity issue preventing your server from reaching the VoIPmonitor license server.

Step 1: Ping the license server From your VoIPmonitor server, test basic connectivity to the license server:

ping 78.24.12.71

• If the ping succeeds (receives responses), your server can reach the license server. The issue may be with firewall rules blocking HTTPS (port 443) specifically.
• If the ping fails (no responses or "Destination host unreachable"), there is a network connectivity issue.

Step 2: Check firewall rules If the ping succeeds but the license update still fails, verify that outbound HTTPS connections (port 443) are not blocked:

# Check if firewalld is being used
systemctl status firewalld

# List blocked/rejected outbound rules if using firewalld
firewall-cmd --list-all

# Check iptables rules
iptables -L -n | grep -E "443|REJECT|DROP"

Ensure that your firewall allows outbound connections to the license server on port 443.

Step 3: Test HTTPS connectivity to the license server Test whether your server can make HTTPS connections to the VoIPmonitor services:

# Test HTTPS connectivity to VoIPmonitor services
curl -I https://www.voipmonitor.org
curl -I https://www.voipmonitor.org/services

If these commands work but the license update still fails, the issue may be specific to the license server endpoint. Contact VoIPmonitor support with the results of the ping and curl tests.

Step 4: Check for proxy configuration If your network requires a proxy server to access the internet, ensure it is correctly configured for the GUI:

# Check if wget or curl has proxy settings set
env | grep -i proxy

# Test through proxy if applicable (example)
curl -x http://proxy-server:port -I https://www.voipmonitor.org

For GUI-specific proxy configuration, check your web server environment or contact support for guidance.

For persistent connectivity issues preventing automatic license updates, see FAQ#How_do_I_troubleshoot_internet_connectivity_issues for network and proxy configuration troubleshooting.

I purchased a license upgrade but my server still shows the old channel limit. What should I do?

After purchasing a license upgrade from the customer portal, your local VoIPmonitor server may temporarily continue to show the previous channel limit. Follow these steps to diagnose and resolve the issue.

Step 1: Check the Customer Portal

1. Log in to the [VoIPmonitor Customer Portal](https://www.voipmonitor.org/).
2. Navigate to Services > My Services.
3. Locate your upgraded service and verify that the license maxcalls value in the portal reflects your new channel limit.

Step 2: If the Portal Shows the Correct New Limit

If the portal displays your upgraded channel limit but your local server still shows the old limit, the issue is on your server side (it has not yet retrieved the updated license). Follow these steps:

1. Log in to the VoIPmonitor web GUI.
2. Navigate to Settings > License.
3. Click the get/update license button to retrieve the updated license.
4. Refresh the page and verify that the "Max concurrent calls" value now reflects your new limit.

If the automatic update fails due to network issues, you can manually paste the license key from the portal. See How do I manually update my license when the automatic update fails? for detailed instructions.

Step 3: If the Portal Still Shows the Old Limit (Backend Discrepancy)

If the customer portal itself is showing your OLD channel limit after an upgrade was processed (e.g., you purchased 500 channels but the portal still shows 350), this indicates a backend discrepancy on the VoIPmonitor licensing server. In this case:

1. Do NOT attempt to manually update your server - it will receive the same outdated license information.
2. Contact VoIPmonitor support immediately via the customer portal or email to report the discrepancy.
3. Provide your service details and confirmation of the upgrade purchase.
4. Once support confirms the issue is fixed on the licensing server backend, proceed with updating your license as described in Step 2.

Step 4: Verify the Fix

After updating your license (either automatically or manually), confirm the change is active:

1. In the GUI, navigate to Tools > System Status > License.
2. Verify that "Max concurrent calls" displays your new, upgraded limit.
3. If you had exceeded your previous limit, check the status in Tools > System Status > GUI status to ensure the lock warning has cleared (locks occur only after 3+ consecutive days of exceeding the limit).

What happens to my license if I stop and restart an AWS instance?

If you stop and start an AWS EC2 instance, the hardware ID typically remains the same, so your license will continue to work. However, if you terminate the instance and launch a new one, the hardware ID will change and you will need a new license key. Automatic re-issuance is not available - you must contact support to obtain a new license.

Can I license VoIPmonitor based on a URL/domain instead of hardware ID?

Yes, as an alternative to hardware binding, you can request that your license be locked to a URL domain (for web-based deployments). Contact VoIPmonitor support to configure domain-based licensing if you have a scenario where hardware binding is impractical (e.g., frequently changing infrastructure or cloud deployments).

How do I determine which license key belongs to which instance when I have multiple keys?

If you have multiple VoIPmonitor instances and multiple license keys, you can identify which key belongs to which already-licensed instance using the License ID shown in the GUI and the Services section of the voipmonitor.org customer portal.

1. Log in to the GUI of the already licensed VoIPmonitor instance.
2. Navigate to Settings > License and note the License ID displayed in the license information.
3. Log in to the voipmonitor.org customer portal and navigate to Services > My Services.
4. Identify the License IDs for your available license keys in the customer portal.
5. Find the license key that has the same License ID as the one you noted from the GUI - this key activates that specific instance.
6. Apply the license key with the different License ID to the unlicensed instance you want to license.

This method allows you to systematically match each license key to its corresponding instance without trial-and-error.

How do I transfer my VoIPmonitor license from an old instance to a new one?

To move your VoIPmonitor license to a new server, follow these steps:

Step 1: Get your license token from one of these sources:

• Option A: From the old GUI (if accessible)*

1. Log in to the Web GUI of the old instance.
2. Navigate to Settings > License.
3. Click the change license key option.
4. Copy the token from the licensetoken field.

• Option B: From the VoIPmonitor customer portal (always available)*

1. Log in to the [VoIPmonitor Members' Area](https://www.voipmonitor.org/membersarea).
2. Navigate to Services > My Services.
3. Locate your license service and copy the License Token for that license.

Step 2: Activate the license on the new instance

• On the new server's VoIPmonitor GUI:*

1. Navigate to Settings > License.
2. Paste the license token into the licensetoken field.
3. Click the get/update license key button to activate the license.

Step 3: Verify the license is active on the new server

Check that the license shows as "Licensed" in Settings > License and verify the correct channel limit is displayed in Tools > System Status > License.

Step 4: Disable the license check cron on the old server (IMPORTANT)

After confirming the new instance is licensed, you must disable the license check cronjob on the old GUI server to prevent simultaneous license usage.

1. SSH to the old GUI server.
2. Check the cron configuration:

cat /etc/crontab | grep checkLicense

1. Disable the license check cronjob by commenting out the line:

# Comment out or remove this line on the OLD server
# * * * * * root php /var/www/html/php/run.php checkLicense

,# You can also check system cron directories:

# Check for cron files containing checkLicense
grep -r "checkLicense" /etc/cron.d/ /etc/cron.* /var/spool/cron/

,# After disabling the cron job, the old instance can be safely decommissioned.

Important Notes:

• The license is tied to the hardware ID (HWID). If the new server has a different HWID and you receive an error during activation, contact [VoIPmonitor support](https://www.voipmonitor.org/support-ticket) to have the license re-issued for the new hardware.
• For temporary migration periods where both old and new servers need to run simultaneously, contact support to enable multi-server licensing on your token. See Can I use my license on multiple servers? for details.
• Do not copy the key.php file from the old server to the new server. It contains HWID-specific information and will not work on a different hardware configuration.

Can I use my license on multiple servers (e.g., for a test/development environment)?

Yes, VoIPmonitor support can reconfigure your existing license token to be valid on multiple servers. This is useful for licensing a test or development environment, server migration, or backup/redundancy purposes without incurring additional costs.

To enable multi-server licensing:

1. Contact VoIPmonitor support via the customer portal or email
2. Specify that you need your license configured for multiple servers and your use case (test/dev, migration, backup, etc.)
3. Provide the server ID (hardware ID) for each server where you will use the license
4. Support will reconfigure your license token to accept all specified servers

Once reconfigured, you can use the same license key on all authorized servers. Multi-server licensing is typically provided at no additional cost for test/development environments, temporary migration periods, or backup scenarios, provided both GUI instances access the same CDRs (i.e., the same database and storage). Support team approval is required.

Note: If you need a license for a completely new installation without an existing license, VoIPmonitor provides a 30-day trial license. You can obtain a trial license from the voipmonitor.org customer portal (logged in users) or by contacting support directly.

What should I do if my VoIPmonitor license has expired due to non-payment?

If your license has expired because of payment processing delays or other payment issues, you can prevent service interruption by requesting an emergency trial license.

Immediate Recovery Steps:

1. Contact VoIPmonitor support immediately to request a 30-day emergency trial license for your server.
2. Provide your server ID (hardware ID) when requesting the emergency trial license.
3. Once support generates the trial license token, apply it to your GUI by navigating to Settings > License. Paste the trial license token (short text string, NOT the full key) into the "License token" field and click the "get/update license key" button to automatically fetch and apply your license.
4. The trial license will restore full functionality for 30 days, giving you time to resolve the payment issue.

Important Considerations:

• This emergency trial license is a temporary measure to prevent service interruption while payment is being processed.
• After completing the payment for your permanent license renewal, you will need to replace the trial license key with your new permanent license key.
• Contact support again after payment completion to receive your permanent license key.

To verify your license status after applying the trial license, navigate to Tools > System Status > License in the GUI or run the license check command:

php /var/www/html/php/run.php checkLicense -v

My paid license is not activating automatically and appears stuck. How do I fix this?

If you have a valid paid license but automatic activation is failing and the license appears to be stuck in an incorrect or "manually set" state, this is typically a backend licensing server issue, not a local file corruption problem.

Symptoms:

• You have purchased a paid license (automatic recurring billing)
• The license is not activating automatically despite using the "get/update license" button
• The license status in the customer portal or GUI shows it is set to "manual" mode instead of automatic

Solution: Contact Support for Backend Correction

1. Contact VoIPmonitor support via the customer portal or email
2. Explain that your paid license is not activating automatically and appears stuck in a manually set state
3. Provide your license details (License ID, server hardware ID, and your customer account information)
4. Wait for support to correct the license status on the backend licensing server

After Backend Correction:

1. Log in to the VoIPmonitor web GUI
2. Navigate to Settings > License
3. Click the "get/update license" button to fetch the corrected license information

Important Distinction

This is different from a "corrupted license file" issue (which typically occurs after a fresh install or reinstallation, where deleting `key.php` and re-fetching is the solution). A backend status issue requires correction by VoIPmonitor support on the licensing server itself.

If you are experiencing this issue after a fresh GUI installation or reinstallation, check the Re-install the GUI - Troubleshooting section to determine if this is a file corruption issue instead.

Why might my granted license channel count be higher than what I requested?

If you request a specific number of channels (e.g., 250) but receive a license for more channels (e.g., 350), this is typically due to a discrepancy between licensed call count and actual call count. This occurs when:

• CDR merging criteria for licensing: The licensing system merges multiple CDR legs (counting them as 1 channel) ONLY if BOTH conditions are met:

• The last 6 digits of the caller number and the last 6 digits of the called number match
• The calls start within a +/- 10-second window

• When merging does NOT apply: If these conditions are not met, each call leg is counted as a separate channel. Common example: When a 3-digit internal extension (e.g., "101") calls a 10-digit national number (e.g., "5551234567"), the last 6 digits do NOT match ("101" cannot match the last 6 digits of "5551234567"), so they are counted as two separate channels.

• This is not unique to your deployment: This behavior affects all VoIPmonitor installations. If your traffic pattern typically generates call legs where the 6-digit suffixes do not match (short extensions calling long numbers, or international calls), the actual licensed call count will be higher than your logical call count.

• Other scenarios creating un-mergeable legs: In complex SIP scenarios (e.g., call transfers through an SBC, call forking, re-invites, or SIP trunking), what appears as one logical call may generate multiple separate CDR records that cannot be automatically merged.

This is not an error - the system correctly identifies that your traffic volume requires more licensed channels than your initial estimate based on logical call counts. The granted license tier reflects the reviewed usage pattern to ensure your monitoring is not unexpectedly locked.

Do I need to change my extension numbering scheme to reduce license count?

No, you should NOT modify your extension numbering scheme just to reduce the licensed channel count. The license system reflects the actual processing load on the sensor (each leg requires packet capture, decoding, and storage).

• Do NOT compromise your PBX design: Changing extension length or dialing patterns for licensing reasons may introduce operational issues or break integration with external systems.

• If license cost is the concern: Consider requesting a higher license tier that accommodates your actual traffic pattern rather than trying to manipulate call leg merging.

• Verify the count is accurate: Check Tools → System Status → Concurrent calls in the GUI to see the actual CDR leg count over the past 14 days. This view shows the data used for license calculations.

What are the available commercial license tiers?

VoIPmonitor commercial licenses are available in the following standard channel tiers:

10, 35, 50, 100, 150, 200, 350, 500, 750, 1000, 1250, 1500, 1750, 2000

When you request a license or upgrade through the customer portal, the system will assign the tier that best fits the reviewed usage. If your request falls between tiers (e.g., 250 channels), you will receive the next higher available tier (e.g., 350 channels) to accommodate your actual traffic.

Audio & PCAP Files

Why are RTP packets still being recorded even when savertp is set to no?

Check your packetbuffer_sender configuration option in /etc/voipmonitor.conf. If packetbuffer_sender is set to yes (Packet Mirroring mode), this can cause unexpected RTP recording behavior.

To fix this issue:

• Locate the packetbuffer_sender option in /etc/voipmonitor.conf
• Set packetbuffer_sender to no, or comment out the line (default is no)
• Restart the VoIPmonitor service: systemctl restart voipmonitor

For more information about client-server modes and the packetbuffer_sender option, see Distributed Architecture: Client-Server Mode.

How can I bulk download audio or PCAP files?

You can use the GUI API to script bulk downloads. Please see the guide: Bulk Download using API.

Why does the GUI download button download the entire merged PCAP instead of only the filtered packets?

This is the current functionality of the GUI download button in the CDR view. When you click to download a PCAP file, it will always include the entire merged packet capture for that call, regardless of any filters or views you have applied in the interface.

Workarounds:

• If you need to extract only specific packets, download the full PCAP file and use a tool like Wireshark to apply filters and export the specific packets you need.
• For advanced scripting or bulk extraction workflows, you can use the command-line tools described in the Manual PCAP Extraction from spooldir guide.

Why are users unable to download PCAP files for calls, both recent and older ones?

If PCAP files cannot be downloaded for calls, this typically means the files have been deleted due to retention/purging limits. Unlike "download button not working" issues (which would show browser errors), this situation results from the files automatically being removed from the spool directory by the cleaner process.

Diagnosis: Check Retention Limits

1. Log in to the VoIPmonitor sensor server
2. Check the maximum spool size configured:

grep maxpoolsize /etc/voipmonitor.conf

1. Check the maximum days configured:

grep maxpooldays /etc/voipmonitor.conf

1. Check current spool directory usage:

du -h --max-depth=1 /var/spool/voipmonitor | tail -20

Resolution: Increase Retention Limits

Edit /etc/voipmonitor.conf to increase the storage limit:

# Example: Increase to 400 GB (in MB)
maxpoolsize = 409600

# Optional: Also set a time-based limit (whichever limit is hit first will trigger cleanup)
maxpooldays = 90

Apply changes:

systemctl restart voipmonitor

Note: After increasing the limit, ONLY NEW calls will be retained longer. Previously deleted PCAP files cannot be recovered from the spool directory. If you need to recover old data, check if you have backups of the spool directory from before the files were deleted.

For more details on retention policies and troubleshooting, see Data Cleaning - Disk Full Troubleshooting.

Differentiating from Download Button Issues:

Symptom	Root Cause	Solution
Download button works but files are missing or download fails with "file not found"	PCAP files were deleted by retention limits (maxpoolsize/maxpooldays)	Increase retention limits per above
Download button shows browser console errors (Chrome: ERR_BLOCKED_BY_RESPONSE)	Nginx X-Frame-Options blocking downloads	See Chrome/Nginx download fix
Download button loads indefinitely or fails with network errors	Sensor Manager configuration issue	Check GUI Settings > Sensors configuration

Why does the downloaded PCAP file have fewer packets than shown in the GUI SIP History?

If you notice that the downloaded PCAP file is missing SIP packets (e.g., INVITE, CANCEL, DTMF) that are visible in the VoIPmonitor GUI's SIP history/diagram, the most likely cause is the "Pcap deduplication before download" setting being enabled in the GUI.

Root Cause:

The "Pcap deduplication before download" option is designed to remove duplicate and retransmitted SIP/RTP packets from downloaded PCAP files to reduce file size. However, the GUI SIP History displays ALL packets seen by the sensor (including duplicates and retransmissions). This can cause a noticeable mismatch between the packet count shown in the GUI and the packet count in the downloaded PCAP file.

Solution: Disable Pcap Deduplication Before Download

To ensure the downloaded PCAP contains all captured packets including duplicates and retransmissions:

1. Log in to the VoIPmonitor GUI with administrator privileges
2. Navigate to Settings > System Configuration > Advanced
3. Find the Pcap deduplication before download option
4. Disable (uncheck) this option
5. Save the changes

After saving, new PCAP downloads will include all captured packets (duplicates and retransmissions included), making the message count consistent with what is shown in the GUI SIP History tab.

Important Notes:

• This setting only affects NEW PCAP downloads - it does not retroactively fix previously downloaded files
• Disabling deduplication will result in larger PCAP file sizes because duplicate and retransmitted packets are preserved
• This is a GUI-only setting affecting downloads - it does not change how packets are stored in the spool directory or how CDR data is processed
• If you only need specific packets and want smaller file sizes, you may prefer to keep deduplication enabled and use Wireshark filters on the downloaded file to isolate specific packets

Why are some SIP messages missing when viewing exported PCAP files in Wireshark?

When viewing PCAP files exported from VoIPmonitor in Wireshark, you may notice that some SIP messages (particularly INVITEs) are missing even though they appear in the VoIPmonitor GUI's SIP History tab. This is NOT a VoIPmonitor issue - the packets are present in the PCAP file, but Wireshark is hiding them due to TCP sequence number analysis.

Root Cause:

Wireshark's TCP analysis feature examines packet sequence numbers. When TCP packets arrive in a way that Wireshark considers "out of order" (which can happen during TCP/TLS reassembly or when packets are reordered in transit), Wireshark marks those packets as problematic and may suppress their dissection, making SIP messages invisible in the protocol hierarchy.

This is particularly common with:

• TLS-protected SIP over TCP (SIP-TLS on port 5061)
• Calls processed via IPFIX or packet mirroring
• TCP-based SIP signaling

Solution: Disable TCP Sequence Analysis in Wireshark:

1. Open your PCAP file in Wireshark
2. Navigate to Edit > Preferences
3. Expand Protocols section and click on TCP
4. Uncheck the option "Analyze TCP sequence numbers" (or similar wording depending on Wireshark version)
5. Click OK to apply the setting
6. The missing SIP messages should now appear in the packet list

Alternatively, you can apply a display filter to force Wireshark to show all packets regardless of TCP analysis:

tcp.analysis.lost_segment == FALSE or sip

Important Notes:

• The SIP packets are always present in the exported PCAP file - VoIPmonitor fully captures all signaling
• This is purely a Wireshark display preference, not a data loss issue
• Other packet analyzers (tcpdump, tshark) will show all packets by default
• You only need to change this setting in your local Wireshark installation, not in VoIPmonitor

Why are .wav audio files not generated for calls using non-G.711 codecs (e.g., Opus, G.729)?

The VoIPmonitor sensor can generate audio files (WAV/OGG/MP3) natively for G.711 (a-law/μ-law) codecs. However, for non-G.711 codecs (such as Opus, G.729, G.723, G.726, etc.), the sensor requires an external helper binary named vmcodecs to perform the codec transcoding.

This vmcodecs binary is exclusively distributed within the GUI installation package and is required to create audio files from non-G.711 codec recordings.

To resolve this issue:

1. Install the GUI package (even if you don't plan to use the web interface). The GUI package includes the necessary vmcodecs binary in <gui-installation-path>/bin/vmcodecs.
2. Ensure vmcodecs is accessible to the sensor - it must be in a directory that is in the system's $PATH or the sensor's working directory.
3. Restart the sensor after installing the GUI to apply the changes.
4. For existing .raw files: Re-process the spooldir content after GUI installation to generate the missing audio files.

Note: Your license key must include support for the specific codec (e.g., Opus Codec Pack) for transcoding to work. Free licenses typically only support G.711.

Why is audio playback garbled or distorted?

If audio recordings play but sound garbled, distorted, or unintelligible, the most common cause is DTLS-SRTP encryption on the RTP streams. Without proper decryption keys, VoIPmonitor cannot decode the encrypted media, resulting in audio that sounds like noise or static.

How to Identify DTLS-SRTP Encrypted Calls:

Check the SIP signaling (INVITE message) for the following indicators:

• SDP crypto attributes: Look for a=crypto lines in the SDP which indicate SRTP encryption
• DTLS fingerprint: Look for a=fingerprint or a=setup attributes which indicate DTLS-SRTP negotiation
• RTP encryption: Encrypted packets will appear as random data when viewed in Wireshark

Solution: Configure DTLS-SRTP Decryption

To enable audio playback for encrypted calls, VoIPmonitor must have access to the decryption keys. This is achieved using the SSL Key Logger method.

1. The SSL Key Logger is installed on the SBC or PBX that terminates the calls
2. It captures DTLS session keys from memory using the LD_PRELOAD mechanism
3. Keys are sent over the network to the VoIPmonitor sensor
4. VoIPmonitor uses these keys to decrypt the DTLS handshake and derive SRTP master keys

For detailed setup instructions, see the Tls documentation, specifically the Method 2: SSL Key Logger section. The guide covers:

• Compiling the sslkeylog.so library
• Configuring Asterisk, Kamailio, FreeSWITCH, or other SIP applications
• Setting up VoIPmonitor to receive session keys
• Correct ssl_ipport syntax for key logger mode
• TCP mode for secure key transport

Common Configuration Pitfalls:

• Wrong ssl_ipport syntax:** When using SSL Key Logger, ssl_ipport must NOT include a path to a key file (e.g., ssl_ipport = 192.168.1.50:5061 is correct, but ssl_ipport = 192.168.1.50:5061 /path/to/key.pem will fail)
• Keys sent to wrong destination:** In distributed architectures with packetbuffer_sender=yes, keys must go to the central server IP, not localhost or the remote client sensor
• PBX not configured: The PBX/SBC must have sslkeylog.so preloaded via LD_PRELOAD or equivalent mechanism

Distinguishing From Other Audio Issues:

If audio is completely silent or WAV files are not generated for non-G.711 codecs (Opus, G.729, etc.), see the previous FAQ entry about the vmcodecs binary. The vmcodecs issue is about missing transcoding capability, while garbled audio typically indicates encryption.

Why are call durations truncated and RTP streams delayed after importing PCAP files into a new VoIPmonitor instance?

This issue typically occurs when the import environment configuration does not match the original probe configuration, particularly for NAT-related settings.

Root Cause: When processing PCAP files, the sniffer needs the same NAT configuration as the original capture probe to correctly correlate call legs. Missing NAT configuration can cause:

• Truncated calls: Call ends prematurely because the cleanup logic triggers incorrectly
• RTP delays/graph errors: Jitter buffer simulation becomes unsynchronized

Solution:

1. Mirror the original probe configuration

Ensure the import configuration file mirrors the original probe settings, except for options like bind.

2. Add natalias configuration

Add the natalias option to the import configuration to map public IPs to private IPs:

natalias = 1.1.1.1 10.0.0.3
natalias = 2.2.2.2 10.0.0.4

Multiple natalias lines can be used if multiple NAT mappings are required. See NAT Configuration in the sniffer configuration reference.

3. Check GUI/DB Settings priority

Settings in Settings -> Sensors in the GUI have higher priority than voipmonitor.conf. If id_sensor is set in the config file, ensure that:

• The sensor entry in Settings > Sensors has matching configuration
• NAT-related settings are also configured in the GUI if database is managing sensor settings
• The GUI does not override your config file settings

Verification: After applying these configuration changes, re-import or re-process the PCAP files and verify that:

• Call durations match the expected length
• RTP streams are synchronized in the graph view
• No RTP delays or gaps appear in the audio playback

How do I convert existing WAV audio files to OGG to save space?

If you have existing recordings saved as .wav and wish to convert them to the more efficient .ogg format to save disk space, you can run the following sequence of commands directly in your spool directory (e.g., /var/spool/voipmonitor):

# Navigate to your spool directory first
cd /var/spool/voipmonitor

# Step 1: Find all .wav files and convert each one to .ogg using ffmpeg.
# This command preserves the original filename, only changing the extension.
find ./ -name '*.wav' -exec bash -c 'ffmpeg -i "$0" -vn -acodec libvorbis "${0%.wav}.ogg"' {} \;

# Step 2: After confirming the conversion was successful, delete all the original .wav files.
find ./ -name '*.wav' -exec rm -f {} \;

# Step 3: Set the web server user (e.g., www-data) as the owner of all files.
# This is crucial for the GUI to be able to read and play the new .ogg files.
chown -R www-data:www-data ./

The 'live play' audio feature is disabled in the GUI. How do I re-enable it?

If the live play functionality for listening to active calls is disabled or the play buttons are not visible in the Active Calls view, this is controlled by a PHP configuration constant in the GUI configuration file.

To re-enable live play:

1. Access the GUI host server via SSH or terminal.
2. Edit the configuration file located at:

/var/www/html/voipmonitor/configuration.php

(The path may vary slightly depending on your installation, typically under /var/www/html/ or /var/www/)

1. Find the DISABLE_LIVEPLAY constant:

define('DISABLE_LIVEPLAY', true);

1. Change the value from true to false:

define('DISABLE_LIVEPLAY', false);

1. Save the file and exit the editor.
2. Log out of the GUI and log back in to see the play buttons for compatible active calls (typically G.711 a-law and μ-law codecs).

Note: Live playback requires the sensor to be actively capturing calls with G.711 codec. Other codecs may not be supported for live listening.

If you encounter performance issues after enabling live play (high CPU usage during busy call periods), you can revert the change by setting the value back to true.

Administration & Troubleshooting

For detailed troubleshooting procedures, see:

• GUI Troubleshooting - HTTP 500, database issues, upgrade problems
• Sniffer Troubleshooting - packet capture, missing CDRs, service issues

How do I reset a lost admin password for the GUI?

See the User Management guide.

How do I fix a corrupted GUI installation or reinstall it?

See Re-install the GUI guide.

The GUI stopped working after a server OS or PHP version upgrade. How do I fix it?

Re-run the GUI installation script. See GUI Installation guide.

How do I reinstall or upgrade the sniffer to the latest version?

Download the latest static binary. See Latest Sniffer guide.

Can I run multiple instances of the sniffer on a single host?

Yes. See Multiple Sniffer Instances guide.

What user actions are recorded in the Audit Log?

Login/Logout, playing/downloading WAV/PCAP files, showing FAX, batch download, CDR filter usage.

How do I enable debug mode or troubleshoot GUI issues?

Add ?debug=31415 to the URL. For detailed steps, see GUI Debug Mode.

Why do the colors for SIP response codes in dashboard graphs change automatically?

Colors are dynamically assigned based on the response codes present in your current data. This is expected behavior to provide visual distinction between different response types.

When installing a new sensor connecting to an existing production database, will it modify the schema?

For databases with >1000 CDRs, schema changes require manual approval via GUI. See disable_dbupgradecheck parameter.

PCI Compliance

VoIPmonitor is designed to be PCI compliance-ready. You have granular control over what data is stored to disk and to the database.

How do I turn off audio recording and DTMF capture globally?

• To prevent RTP (audio) payload from being stored while still capturing headers for analysis, use savertp=header in voipmonitor.conf.
• To disable RTP capture entirely, use savertp=no.
• To prevent DTMF tones (from SIP INFO or RFC2833) from being saved to the database and PCAP files, use:

dtmf2db = no
dtmf2pcap = no

How do I selectively record or not record audio/DTMF?

VoIPmonitor's powerful Capture Rules allow you to define conditional logic. You can create rules based on IP address, telephone number, SIP domain, or any SIP header to selectively turn audio or DTMF recording ON or OFF for specific calls, enabling you to meet strict compliance requirements.

How do I completely disable live call monitoring and CDR audio playback?

To fully disable live call listening and CDR playback capabilities, you need to configure both the sensor and GUI layers:

• Disable Live Sniffer menu: Edit config/system_configuration.php in your GUI installation directory and add:

define('DISABLE_LIVE_SNIFFER', true);

This removes the entire Live Sniffer menu item from the GUI.

• Hide play buttons from Active Calls and CDR views: In the GUI, navigate to Settings > System Configuration > Advanced and enable both Hide live play and Hide WAV play options.

Alternatively, edit configuration.php in the GUI directory and modify:

define('DISABLE_LIVEPLAY', true);

• Important security consideration: Users with administrator privileges can override global capture settings (including savertp mode) to enable recording or listening for specific calls. For strict PCI or compliance scenarios, ensure users are not granted administrator privileges. See User Management: Permissions for details on user access levels.

CALEA Compliance

VoIPmonitor supports CALEA (Communications Assistance for Law Enforcement Act) compliance by providing programmatic access to recorded call data through its GUI API.

Are third-party vendors available for CALEA integration?

VoIPmonitor does not provide a list of specific CALEA vendors or products. However, VoIPmonitor records SIP and RTP streams (PCAP files and audio recordings) that can be programmatically accessed via the GUI API. This allows you to create custom scripts or mechanisms to automatically share call data with your chosen third-party CALEA compliance system. For implementation details, see the CALEA Compliance Integration Guide.

How can I export data to third-party CALEA systems?

Use the GUI API methods getPCAP and getVoiceRecording to retrieve recorded data programmatically, then forward it to your third-party CALEA compliance system using custom scripts or middleware. See the CALEA Compliance Integration Guide for detailed information.

AI Summary for RAG

Summary: VoIPmonitor FAQ covering configuration and common questions. Topics include: CDR analysis (regex filters, custom header search, red BYE icon), platform support (AWS, Docker, VMWare ESXi, Azure, cloud databases), configuration (SIP ports, IPv6, DTMF, REGISTER, capture rules, protocol support: SIP, Skinny/SCCP, MGCP, SS7, Diameter, RTCP; H.323 NOT supported), licensing (concurrent channels calculation, trial licenses, HWID issues, multi-server licensing, license transfer, channel tiers), audio/PCAP files (bulk download, WAV-to-OGG conversion, vmcodecs for non-G.711, RTP recording settings, PCAP deduplication), quality metrics (MOS, jitter, packet loss missing from one call leg due to NAT IP mismatch), PCI compliance (selective recording with capture rules, global disable options), CALEA compliance (API-based third-party integration), multiple GUI instances for redundancy (CRITICAL: cron job must be enabled on only ONE instance to prevent duplicate alerts). For detailed troubleshooting procedures (HTTP 500, database corruption, upgrade issues), see GUI_troubleshooting. For sniffer issues (packet capture, missing CDRs), see Sniffer_troubleshooting.

Keywords: faq, cdr, sipport, ipv6, dtmf, license, concurrent calls, aws, docker, vmware, azure, wav, ogg, pci compliance, calea compliance, capture rules, custom header, license key, trial license, multi-server, multiple gui, cron job, duplicate alerts, natalias, quality metrics, MOS, jitter, packet loss, protocol support, SIP, Skinny, SCCP, H.323 not supported, bulk download, PCAP deduplication

Key Questions:

• How do I determine the number of license channels I need?
• What happens if my call volume exceeds my license limit?
• Can I use my license on multiple servers?
• How do I transfer my VoIPmonitor license to a new server?
• What platforms does VoIPmonitor support (AWS, Docker, VMWare)?
• Why don't I see SIP packets on ports other than 5060?
• How do I enable IPv6 traffic processing?
• How can I capture DTMF tones?
• Which VoIP protocols are supported by VoIPmonitor?
• How do I convert WAV audio files to OGG to save space?
• Why are quality metrics missing for one call leg?
• How do I disable audio recording for PCI compliance?
• Can I run multiple GUI instances for redundancy?
• What does the red icon in CDR view mean?
• How can I use regular expressions to filter calls?