FAQ: Difference between revisions

From VoIPmonitor.org
(Add FAQ: How to exclude traffic from specific IP address or SBC)
(Add clarification about on-demand audio extraction vs saveaudio option)
 
(57 intermediate revisions by the same user not shown)
Line 2: Line 2:
[[Category:GUI manual]]
[[Category:GUI manual]]


'''This page provides answers to frequently asked questions and solutions to common issues encountered during the configuration and operation of VoIPmonitor.'''
'''Quick answers to frequently asked questions. For detailed troubleshooting, see [[Sniffer_troubleshooting|Sniffer Troubleshooting]] and [[GUI_troubleshooting|GUI Troubleshooting]].'''


== Quick Navigation ==
== Quick Navigation ==
{| class="wikitable" style="width:100%; margin-bottom:20px;"
{| class="wikitable" style="width:100%; margin-bottom:20px;"
|-
|-
! style="width:25%; background:#e6f2ff;" | General Topics
! style="width:25%; background:#e6f2ff;" | General
! style="width:25%; background:#e6ffe6;" | Configuration
! style="width:25%; background:#e6ffe6;" | Configuration
! style="width:25%; background:#fff2e6;" | Troubleshooting
! style="width:25%; background:#fff2e6;" | Licensing
! style="width:25%; background:#ffe6e6;" | Files & Compliance
! style="width:25%; background:#ffe6e6;" | Audio & Files
|-
|-
| style="vertical-align:top; padding:8px;" |
| style="vertical-align:top; padding:8px;" |
* [[#General & Scalability|Scaling]]
* [[#General_&_Architecture|Architecture]]
* [[#Licensing|Licensing]]
* [[#Platform_Support|Platform Support]]
* [[#Platform & Environment Support|Platform Support]]
* [[#CDR_View|CDR View]]
| style="vertical-align:top; padding:8px;" |
| style="vertical-align:top; padding:8px;" |
* [[#Configuration & Features|SIP Ports]]
* [[#Protocols_&_Ports|Protocols & Ports]]
* [[#Configuration & Features|IPv6]]
* [[#RTP_&_Quality_Metrics|RTP & Quality]]
* [[#Configuration & Features|DTMF]]
* [[Capture_rules|Capture Rules]]
| style="vertical-align:top; padding:8px;" |
| style="vertical-align:top; padding:8px;" |
* [[#CDR (Call Detail Record) View|CDR Issues]]
* [[#Licensing|Channels & Limits]]
* [[#Administration & Troubleshooting|Admin Tasks]]
* [[#Licensing|HWID Issues]]
* [[GUI_troubleshooting|GUI Debug]]
* [[#Licensing|License Transfer]]
* [[#General & Scalability|MySQL Support]]
* [[#Administration & Troubleshooting|Network Connectivity]]
* [[#Administration & Troubleshooting|Secure DNS Issues]]
* [[#Administration & Troubleshooting|Missing Database Tables]]
* [[#Administration & Troubleshooting|MariaDB System Table Corruption After OS Upgrade]]
* [[#Administration & Troubleshooting|VoIPmonitor Server Crashes After MySQL Upgrade]]
* [[#Administration & Troubleshooting|Missing Database Columns]]
| style="vertical-align:top; padding:8px;" |
| style="vertical-align:top; padding:8px;" |
* [[#Audio & PCAP Files|Audio/PCAP]]
* [[#Audio_&_PCAP_Files|Recording Limits]]
* [[#PCI compliance|PCI Compliance]]
* [[#Audio_&_PCAP_Files|Codec Support]]
* [[#CALEA Compliance|CALEA Compliance]]
* [[#Compliance|PCI/CALEA]]
* [[Capture_rules|Capture Rules]]
|}
|}


== General & Scalability ==
== General & Architecture ==


;How does VoIPmonitor scale for high traffic?
;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|Scaling and Performance Tuning guide]].
:For hardware recommendations and optimization of CPU, Disk I/O, and Database bottlenecks, see [[Scaling|Scaling and Performance Tuning]].
 
;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|Data Cleaning and Retention guide]].


;Can I run multiple GUI instances for redundancy or external access?
;How do I manage disk space and database retention?
: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.
:See [[Data_Cleaning|Data Cleaning and Retention]] for PCAP cleanup (cleanspool) and CDR retention settings.


:Setup requirements:
;Can I run multiple GUI instances for redundancy?
:* '''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.
:Yes. Requirements:
:* '''PCAP storage access:''' Each GUI needs access to the PCAP files. This is typically achieved via NFS/SSHFS mounting from the primary storage server.
:* All GUIs connect to the same database
:* '''License configuration:''' Copy your existing license file (<code>key.php</code>) to each GUI server. If the hardware IDs differ, contact VoIPmonitor support to add the additional HWIDs to your license token.
:* PCAP storage accessible via NFS/SSHFS
:* Same <code>key.php</code> license file on each GUI


:'''CRITICAL: Cron Job Conflict'''
:{{Warning|1='''CRITICAL:''' Enable the cron job on '''only ONE''' GUI instance. Multiple active cron jobs cause duplicate alerts and reports.}}
: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'''.
:<syntaxhighlight lang="bash"># Disable on secondary GUIs:
 
:To prevent conflicts:
:# Enable the cron job on '''only one GUI instance''' (typically your primary internal GUI for active monitoring).
:# Disable the cron job on all secondary/redundant GUI instances.
:# Verify that the cron job exists in <code>/etc/crontab</code> or system cron configuration on each server.
:# Comment out or remove the cron line on secondary servers:
::<syntaxhighlight lang="bash"># On secondary GUI servers - DISABLE the cron job
# * * * * * root php /var/www/html/php/run.php cron</syntaxhighlight>
# * * * * * root php /var/www/html/php/run.php cron</syntaxhighlight>


: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.
;Can one GUI display data from multiple sensors?
:Yes. Use the '''Client-Server architecture''' (v20+):
:* '''Local Processing''' (<code>packetbuffer_sender=no</code>): Sensors analyze locally, send CDRs only
:* '''Packet Mirroring''' (<code>packetbuffer_sender=yes</code>): Sensors forward raw packets to central server
:See [[Sniffer_distributed_architecture|Distributed Architecture]] for full configuration.


== CDR (Call Detail Record) View ==
== Platform Support ==


;What does the small red icon in the CDR view mean?
;What architectures are supported?
:The red icon ([[File:Cdrcolumnsredflag.png]]) indicates which party in the call sent the <code>BYE</code> message first, effectively ending the call.
:{| class="wikitable"
 
|-
;How can I use regular expressions to filter calls?
! Component !! Supported !! Notes
: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:
|-
:<code>!R(^[+]?[0-9]+$)</code>
| Sensor || x86 (32/64-bit), ARMv7/v8 || Compile from source for ARM64
 
|-
;Why is there a delay between when a call ends and when it appears in the CDR view?
| GUI || x86 only || '''Not supported''' on ARM64/aarch64
: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 (<code>_</code>) as a wildcard character to represent the space.
 
:'''Example:''' To search for "Normal Call Clearing", use:
:<code>%normal_call_clearing%</code>
 
:The underscore acts as a wildcard that matches a single character (in this case, the space), while the percent (<code>%</code>) 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 [[Reports|Call Summary]] report to see aggregate call statistics per IP (total calls, duration, etc.)
:* Create separate series in [[Charts|Charts]] for each IP using the Filters tab (requires individual IP filters)
:* Create [[Groups|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 <code>From</code> header
:* '''Called number:''' Taken from the <code>To</code> 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 <code>From</code> and <code>To</code> headers in the first <code>INVITE</code> 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 <code>voipmonitor.conf</code>:
 
<syntaxhighlight lang="ini">[general]
# Default: 1 = To header
# Alternative: 2 = INVITE URI
destination_number_mode = 1</syntaxhighlight>
 
Set <code>destination_number_mode = 2</code> 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:
 
:* <code>remoteparty_caller</code> / <code>remoteparty_called</code> - Update numbers from Remote-Party-ID header
:* <code>passertedidentity = yes</code> - Use P-Asserted-Identity header for caller
:* <code>ppreferredidentity = yes</code> - 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:
<syntaxhighlight lang="ini">[general]
# Comment out or remove to disable
# remoteparty_caller = calling
# remoteparty_called = called
# passertedidentity = no
# ppreferredidentity = no</syntaxhighlight>
 
'''4. Apply Configuration Changes'''
After editing <code>voipmonitor.conf</code>, restart the sensor service:
<syntaxhighlight lang="bash">systemctl restart voipmonitor</syntaxhighlight>
 
'''5. Test and Verify'''
Generate a new test call and check the CDR to see if the numbers are now correctly assigned to <code>caller</code> and <code>called</code> fields.
 
For more detailed configuration options, see the [[Sniffer_configuration#Caller/Called_Identity_Configuration|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 <code>filter</code> directive in <code>voipmonitor.conf</code>. 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:'''
 
:<syntaxhighlight lang="ini">[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</syntaxhighlight>
 
:'''Important Notes:'''
 
:* The <code>filter</code> directive uses BPF syntax (tcpdump-style expressions)
:* Changes to this setting require restarting the sensor service:
::<syntaxhighlight lang="bash">systemctl restart voipmonitor</syntaxhighlight>
:* This filter applies at the packet capture level and prevents any traffic from the specified IPs from being analyzed or stored
:* Use <code>not host</code> for single IPs and <code>not net</code> 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:
 
:# Go to the GUI: Configuration > Filter rules
:# Add an IP filter rule for the unwanted IP
:# Set the rule to "Skip" status (this skips creating CDRs for calls matching this IP)
:# 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 <code>filter</code> directive is more efficient as it drops the packets before processing.
 
== 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 <code>__sync_fetch_and_sub_8</code> 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 [[Sniffer_installation#Compiling_from_Source|Compiling from Source]] section of the Sniffer Installation guide


;Can I run VoIPmonitor on AWS?
;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:
:Yes. For license detection: <code>chmod 644 /dev/root</code>
:<syntaxhighlight lang="bash">chmod 644 /dev/root</syntaxhighlight>
:* '''Stop/Start instance:''' HWID usually preserved
:* '''Terminate/Launch new:''' HWID changes, requires new license key


:'''Important: Hardware ID behavior on AWS'''
;Is Docker supported?
:* '''Stopping and starting an instance:''' Usually preserves the hardware ID, so your license will continue to work.
:Yes, but ensure <code>/proc/self/cgroup</code> content doesn't change between restarts (affects HWID stability).
:* '''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?
;Are cloud databases (RDS, Azure) supported?
:Yes, the GUI and sensor can run in a containerized environment. However, you must ensure that the content of <code>/proc/self/cgroup</code> 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.
:Yes. Requires MySQL-compatible database with <code>SUPER</code> privilege. If unavailable, set:
 
;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 <code>SUPER</code> privilege for creating functions and triggers.
 
;What if my cloud database (like Azure) does not grant SUPER privilege?
:If <code>SUPER</code> privilege is not available, you must manually set the following server variable in your cloud database configuration console:
:<syntaxhighlight lang="ini">log_bin_trust_function_creators = ON</syntaxhighlight>
:<syntaxhighlight lang="ini">log_bin_trust_function_creators = ON</syntaxhighlight>
: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 <code>caching_sha2_password</code> authentication and display deprecation warnings when the older <code>mysql_native_password</code> method is used.
:'''Short Answer:''' You do not need to force <code>mysql_native_password</code> if your PHP version is 7.4.4 or newer. The VoIPmonitor GUI automatically supports <code>caching_sha2_password</code> when using a modern PHP version with the mysqlnd driver.
:'''Recommended Solution (Best Practice):'''
:# Upgrade your PHP version to 7.4.4 or newer (recommended: 8.0, 8.1, 8.2, or 8.3).
:# Reinstall the IonCube Loader for your new PHP version. See [[GUI_Installation#Step_3:_Install_or_Update_the_IonCube_Loader|GUI Installation Guide - Step 3]].
:# Reinstall the VoIPmonitor GUI. See [[GUI_Installation#Re-installing_or_Upgrading_the_GUI|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 <code>default_authentication_plugin=mysql_native_password</code> lines from your MySQL configuration.
:'''Alternative Solution (Legacy PHP):'''
:If you must use an older PHP version (before 7.4.4), you can force <code>mysql_native_password</code> by adding the following to your MySQL configuration file:
:<syntaxhighlight lang="ini"># /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</syntaxhighlight>
:After making changes, restart the MySQL service and recreate your database user using the old method:
:<syntaxhighlight lang="sql">ALTER USER 'voipmonitor'@'127.0.0.1' IDENTIFIED WITH mysql_native_password BY 'YourPassword';
FLUSH PRIVILEGES;</syntaxhighlight>
:{{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 <code>skinny=yes</code>)
:* '''MGCP''' - Media Gateway Control Protocol (enable with <code>mgcp=yes</code>)
:* '''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 <code>voipmonitor.conf</code>. See the [[Sniffer_configuration#sipport|sipport configuration guide]].
;How do I enable IPv6 traffic processing?
:By default, IPv6 is disabled. To enable it on a new installation, set <code>ipv6=yes</code> in <code>voipmonitor.conf</code>. If you have existing IPv4 data, enabling IPv6 requires a database migration. For detailed instructions, please see the [[How_to_enable_ipv6_processing|IPv6 Enabling Guide]].
;How do I capture and view SIP REGISTER messages?
:By default, <code>REGISTER</code> messages are not stored. To enable this, set <code>sip-register=yes</code> in <code>voipmonitor.conf</code>. For details on how active and failed registrations are stored and how to query them via the API, see the [[Register|documentation on REGISTER monitoring]].
;How can I capture DTMF tones?
:You can enable DTMF capture in <code>voipmonitor.conf</code>:
:* For '''RFC2833''' and '''SIP INFO''' methods, set: <code>dtmf2db = yes</code>
:* For '''inband DTMF''' (G.711 codec only, requires more CPU), set: <code>inbanddtmf = yes</code>
;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:'''
# Check the CDR Detail view for the problematic call.
# Note the IP addresses in the SDP (shown in the SIP columns or Message Detail).
# Use a packet capture tool (tcpdump/tshark) to verify the actual IP address of the RTP packets for the missing leg.
# If the SDP IP and actual RTP IP differ, this is a NAT mismatch scenario.
'''Solution: Configure natalias'''
Add a <code>natalias</code> mapping to <code>/etc/voipmonitor.conf</code> to tell VoIPmonitor that the actual RTP stream IP (source) corresponds to the SDP-announced IP (destination):
<syntaxhighlight lang="ini"># 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</syntaxhighlight>
'''Important: natalias works bidirectionally'''
The <code>natalias</code> directive creates a two-way mapping. You can specify the IPs in either order:
<syntaxhighlight lang="ini"># 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</syntaxhighlight>


You can add multiple <code>natalias</code> lines if you have multiple mappings.
;Why is mysql_native_password deprecated?
:PHP 7.4.4+ supports <code>caching_sha2_password</code> natively. Upgrade PHP and reinstall IonCube Loader. See [[GUI_installation|GUI Installation]].


'''Troubleshooting: Try reversing the IP order'''
== CDR View ==
If RTP association fails after adding <code>natalias</code>, try reversing the IP addresses in the configuration:
<syntaxhighlight lang="ini"># Original attempt (did not work)
natalias = 1.2.3.4 10.0.0.100


# Try reversing (swapping the order)
;What does the red icon mean?
natalias = 10.0.0.100 1.2.3.4</syntaxhighlight>
:Indicates which party sent the <code>BYE</code> message (ended the call).
Restart the sniffer after making this change and test again.


'''Advanced: Checking for Port Mismatches'''
;How do I filter with regular expressions?
If you have verified IP addresses match but still see missing audio, the issue may be a '''port mismatch''':
:Prefix with <code>R()</code>. Example: <code>R(^500[0-9]{4}$)</code>


;1. Capture packets from a problematic call:
;How do I exclude values from filters?
<syntaxhighlight lang="bash">tshark -i eth0 -Y "sip" -w /tmp/test_call.pcap</syntaxhighlight>
:Use <code>!</code> prefix:
:* <code>!123456</code> – exclude specific number
:* <code>!00420%</code> – exclude prefix
:* <code>222%, !223%</code> – include 222*, exclude 223*


;2. Compare SDP-advertised ports with actual RTP ports:
;How do I search multi-word strings in custom headers?
<syntaxhighlight lang="bash"># Extract SDP RTP ports from SIP INVITE in the capture
:Use underscore for spaces: <code>%normal_call_clearing%</code>
tshark -r /tmp/test_call.pcap -Y "sip" -T fields -e rtp.setup


# Extract actual RTP ports from traffic
;Why are caller/called numbers swapped?
tshark -r /tmp/test_call.pcap -Y "rtp" -T fields -e udp.srcport</syntaxhighlight>
:VoIPmonitor extracts from SIP headers (<code>From</code>/<code>To</code>). Check <code>destination_number_mode</code> setting. See [[Call_Detail_Record_-_CDR|CDR Documentation]].


;3. If the ports do NOT match:
;Why is there a delay before CDRs appear?
: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.
:Database can't keep up. See [[Database_troubleshooting#SQL_Queue_and_CDR_Delays|SQL Queue Troubleshooting]].
:'''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:'''
== Protocols & Ports ==
<syntaxhighlight lang="bash"># Edit configuration
vi /etc/voipmonitor.conf


# Restart sniffer
;Which protocols are supported?
systemctl restart voipmonitor</syntaxhighlight>
:{| class="wikitable"
 
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 <code>natalias</code> configuration to reprocess and show the metrics.
 
For additional NAT-related configuration options, see [[Sniffer_configuration#NAT|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 <code>auto_enable_use_blocks = yes</code> in <code>/etc/voipmonitor.conf</code> and restart the sniffer service:
:<syntaxhighlight lang="bash"># Edit configuration
echo "auto_enable_use_blocks = yes" >> /etc/voipmonitor.conf
 
# Restart sniffer
systemctl restart voipmonitor
</syntaxhighlight>
 
: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#auto_enable_use_blocks|Sniffer Configuration]] for details.
 
:'''Additional Checks:'''
:* Verify <code>interface</code> in <code>voipmonitor.conf</code> includes all relevant NICs (e.g., <code>interface = eth0,eth1</code>)
:* Check <code>vlan_siprtpsame = no</code> (allows different VLANs for SIP and RTP)
:* If IP addresses changed due to NAT, configure <code>natalias</code> 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 <code>rtp_check_both_sides_by_sdp = yes</code> in <code>/etc/voipmonitor.conf</code>:
:<syntaxhighlight lang="bash"># Edit configuration
vi /etc/voipmonitor.conf
# Add or modify:
rtp_check_both_sides_by_sdp = yes
 
# Restart sniffer
systemctl restart voipmonitor
</syntaxhighlight>
 
: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:'''
:* <code>no</code>: Disabled (default)
:* <code>yes</code>: Verify both sides per SDP
:* <code>keep_rtp_packets</code>: Same as 'yes' but store unverified packets for debugging
:* <code>strict</code>: Allow unverified packets until first verified packet arrives
:* <code>very_strict</code>: 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 <code>keep_rtp_packets</code> when debugging to preserve extraneous packets for analysis
:* For multi-interface deployments, you may need to combine with <code>auto_enable_use_blocks = yes</code>
:* See [[Sniffer_configuration#RTP_Tracking_.26_SDP|RTP Tracking & SDP Configuration]] for additional related options
 
:'''Verification:'''
:After enabling this option, verify the fix by:
:# Check that new call recordings show correct audio (no mixing from other calls)
:# 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 [[Encryption_in_manager_api_customer|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|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:
 
{| class="wikitable"
|-
|-
! Rule Type !! Matching Supported !! Example
! Supported !! Not Supported
|-
|-
| '''IP Addresses''' || CIDR subnet masks (wildcard networks) || <code>1.2.3.0/24</code> matches all IPs in that range
| SIP, Skinny/SCCP, MGCP, SS7/ISUP, Diameter, RTCP || '''H.323''', '''MEGACO/H.248'''
|-
| '''Telephone Numbers''' || Prefix matching (equivalent to wildcard) || <code>4420</code> matches <code>4420*</code>
|-
| '''SIP Domains''' || Exact match only || <code>example.com</code> ONLY matches <code>example.com</code>, not <code>sub.example.com</code>
|}
|}


:If you need more complex domain matching logic (such as patterns or subdomains), you must use the <code>filtercommand</code> option with an external script, or use regular expressions in the CDR view filter bar for searching recorded calls.
;Why don't I see SIP on ports other than 5060?
:Configure additional ports in <code>voipmonitor.conf</code>:
:<syntaxhighlight lang="ini">sipport = 5060,5080,8088,8089</syntaxhighlight>
:See [[Sniffer_configuration#sipport|sipport configuration]].


;How do I enable IPv6?
:Set <code>ipv6=yes</code> in config. Existing databases require migration. See [[How_to_enable_ipv6_processing|IPv6 Guide]].


== Licensing ==
;How do I capture REGISTER messages?
:Set <code>sip-register=yes</code>. See [[Register|REGISTER Monitoring]].


;How do I determine the number of license channels I need?
;How do I capture DTMF?
: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.
:<syntaxhighlight lang="ini">dtmf2db = yes          # RFC2833 and SIP INFO
: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).
inbanddtmf = yes        # G.711 only, CPU intensive</syntaxhighlight>


;What happens if my call volume temporarily exceeds my license limit?
== RTP & Quality Metrics ==
:'''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?
;Why are quality metrics (MOS, jitter) missing for one call leg?
:The GUI only becomes fully locked if the license limit is exceeded for '''three or more consecutive days'''.
:Usually NAT mismatch – SDP announces different IP than actual RTP source.


;What happens if I exceed my license for three consecutive days?
:'''Solution:''' Configure <code>natalias</code> mapping:
: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:
:<syntaxhighlight lang="ini"># Map public IP to private IP
:# '''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).
natalias = 1.2.3.4 10.0.0.100</syntaxhighlight>
:# Delete the CDRs from the spike period via the GUI filter and delete tools (to reset the statistics).
:# Upgrade your license to a higher channel count via the voipmonitor.org customer portal.
:# 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?
:See [[Sniffer_configuration#NAT|NAT Configuration]] for details.
: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.
;Why is RTP not correctly associated after moving SIP/RTP to different NICs?
:Enable memory blocks for multi-interface scenarios:
:<syntaxhighlight lang="ini">auto_enable_use_blocks = yes</syntaxhighlight>


;I get an "Invalid or corrupted hwid" error when trying to activate my license. What should I do?
;Why do recordings mix audio from different calls?
:There are two common causes for this error. Check which scenario applies to your situation:
:Enable SDP verification on both sides:
:<syntaxhighlight lang="ini">rtp_check_both_sides_by_sdp = yes</syntaxhighlight>


:'''Scenario 1: License key formatting issue (most common)'''
== Licensing ==
:The license key is a multi-line text block that contains several fields such as <code>Expires</code>, <code>easycallerid</code>, <code>id</code>, and <code>upgradeexpire</code>. 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 <code>chmod 644 /dev/root</code> to fix permissions on the root device.
:* '''Docker/Containers:''' Ensure the container ID in <code>/proc/self/cgroup</code> does not change between restarts.
:* '''Corrupted license file:''' Remove <code>/var/www/html/key.php</code> 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 <code>hwid</code> binary.
 
:'''Steps to manually generate HWID:'''
:# SSH into your server as root.
:# Navigate to the GUI installation's <code>bin</code> directory (default is <code>/var/www/html/bin</code> or <code>/var/www/voipmonitor/bin</code>).
:# Run the <code>hwid</code> binary as the web server user to generate the hardware ID:
::For Debian/Ubuntu systems using Apache:
:: <syntaxhighlight lang="bash">runuser -u www-data -- ./hwid-x86_64</syntaxhighlight>
::For Red Hat/CentOS systems using Apache:
:: <syntaxhighlight lang="bash">sudo -u apache ./hwid-x86_64</syntaxhighlight>
::For Nginx systems (adjust user as needed):
:: <syntaxhighlight lang="bash">runuser -u nginx -- ./hwid-x86_64</syntaxhighlight>
:# Copy the HWID string that appears in the output.
:# Log in to the VoIPmonitor services portal (http://www.voipmonitor.org/services).
:# Navigate to your license and associate it with this new HWID to generate an updated license key.
:# Return to the GUI and paste the new license key into the license activation field.
:# 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:'''
:# Identify your '''License ID''' from the VoIPmonitor '''Settings > License''' page.
:# Contact VoIPmonitor support and request to switch your license from hardware-based to domain-based validation.
:# Provide the License ID and the desired domain name (typically your server's FQDN, e.g., <code>monitor.example.com</code>).
:* 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:
:# Log in to the VoIPmonitor web GUI.
:# Navigate to '''Settings > License'''.
:# Click the '''get/update license key''' button.
:# Click the '''recheck''' button to synchronize the license with your new hardware ID.
:# 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:
:# Navigate to your GUI installation's <code>bin</code> directory (<code>/var/www/html/bin</code> or <code>/var/www/voipmonitor/bin</code>).
:# Generate the new hardware ID using the <code>hwid</code> binary as the web server user:
::For Debian/Ubuntu (Apache):
:: <syntaxhighlight lang="bash">runuser -u www-data -- ./hwid-x86_64</syntaxhighlight>
::For Red Hat/CentOS/AlmaLinux (Apache):
:: <syntaxhighlight lang="bash">sudo -u apache ./hwid-x86_64</syntaxhighlight>
::For Nginx:
:: <syntaxhighlight lang="bash">runuser -u nginx -- ./hwid-x86_64</syntaxhighlight>
:# Copy the new HWID string that appears in the output.
:# Log in to the [VoIPmonitor Services Portal](https://www.voipmonitor.org/services) and associate your license with this new HWID.
:# 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 <code>/proc/self/cgroup</code> does not change on each restart.
:* For AWS EC2 instances, verify <code>/dev/root</code> has correct permissions: <code>chmod 644 /dev/root</code>.
:* 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'''
:# 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.
:# The "License key" field is for offline activation only, where the full multi-line license key is pasted directly.
:# Pasting a short token into the "License key" field will result in "Bad Key Content" error.
 
:'''Solution:'''
:# Navigate to '''Settings > License'''.
:# Paste your '''license token''' (short text string) into the '''"License token"''' field.
:# Click the '''"get/update license key"''' button to automatically fetch and apply the license.
:# 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|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.
 
:# Contact VoIPmonitor support to obtain the full, formatted license key.
:# Log in to the VoIPmonitor web GUI.
:# Navigate to '''Settings > License''' (or click the "get/update license" button if available).
:# Paste the '''entire multi-line license key''' into the provided text field.
:# 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:
 
<syntaxhighlight lang="bash">ping 78.24.12.71</syntaxhighlight>
 
* 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:
 
<syntaxhighlight lang="bash"># 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"</syntaxhighlight>
 
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:
 
<syntaxhighlight lang="bash"># Test HTTPS connectivity to VoIPmonitor services
curl -I https://www.voipmonitor.org
curl -I https://www.voipmonitor.org/services</syntaxhighlight>
 
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:
 
<syntaxhighlight lang="bash"># 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</syntaxhighlight>
 
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'''
:# Log in to the [VoIPmonitor Customer Portal](https://www.voipmonitor.org/).
:# Navigate to '''Services > My Services'''.
:# 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:
:# Log in to the VoIPmonitor web GUI.
:# Navigate to '''Settings > License'''.
:# Click the '''get/update license''' button to retrieve the updated license.
:# 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 [[FAQ#How_do_I_manually_update_my_license_when_the_automatic_update_fails|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:
:# Do NOT attempt to manually update your server - it will receive the same outdated license information.
:# '''Contact VoIPmonitor support immediately via the customer portal or email to report the discrepancy.'''
:# Provide your service details and confirmation of the upgrade purchase.
:# 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:
:# In the GUI, navigate to '''Tools > System Status > License'''.
:# Verify that "Max concurrent calls" displays your new, upgraded limit.
:# 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.
 
:# Log in to the GUI of the '''already licensed''' VoIPmonitor instance.
:# Navigate to '''Settings > License''' and note the '''License ID''' displayed in the license information.
:# Log in to the voipmonitor.org customer portal and navigate to '''Services > My Services'''.
:# Identify the License IDs for your available license keys in the customer portal.
:# Find the license key that has the same License ID as the one you noted from the GUI - this key activates that specific instance.
:# 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:'''<br>
*'''Option A: From the old GUI (if accessible)'''*
:# Log in to the Web GUI of the old instance.
:# Navigate to '''Settings > License'''.
:# Click the '''change license key''' option.
:# Copy the token from the '''licensetoken''' field.
 
*'''Option B: From the VoIPmonitor customer portal (always available)'''*
:# Log in to the [VoIPmonitor Members' Area](https://www.voipmonitor.org/membersarea).
:# Navigate to '''Services > My Services'''.
:# Locate your license service and copy the '''License Token''' for that license.
 
:'''Step 2: Activate the license on the new instance'''<br>
*On the new server's VoIPmonitor GUI:*
:# Navigate to '''Settings > License'''.
:# Paste the license token into the '''licensetoken''' field.
:# Click the '''get/update license key''' button to activate the license.
 
:'''Step 3: Verify the license is active on the new server'''<br>
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)'''<br>
After confirming the new instance is licensed, you must disable the license check cronjob on the old GUI server to prevent simultaneous license usage.
:# SSH to the old GUI server.
:# Check the cron configuration:
:: <syntaxhighlight lang="bash">cat /etc/crontab | grep checkLicense</syntaxhighlight>
:# Disable the license check cronjob by commenting out the line:
:: <syntaxhighlight lang="bash"># Comment out or remove this line on the OLD server
# * * * * * root php /var/www/html/php/run.php checkLicense</syntaxhighlight>
,# You can also check system cron directories:
:: <syntaxhighlight lang="bash"># Check for cron files containing checkLicense
grep -r "checkLicense" /etc/cron.d/ /etc/cron.* /var/spool/cron/</syntaxhighlight>
,# 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_.28e.g..2C_for_a_test.2Fdevelopment_environment.29.3F|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:
:# Contact VoIPmonitor support via the customer portal or email
:# Specify that you need your license configured for multiple servers and your use case (test/dev, migration, backup, etc.)
:# Provide the server ID (hardware ID) for each server where you will use the license
:# 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:'''
:# Contact VoIPmonitor support immediately to request a '''30-day emergency trial license''' for your server.
:# Provide your server ID (hardware ID) when requesting the emergency trial license.
:# 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.
:# 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:
:<syntaxhighlight lang="bash">php /var/www/html/php/run.php checkLicense -v</syntaxhighlight>
 
;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'''
:# Contact VoIPmonitor support via the customer portal or email
:# Explain that your paid license is not activating automatically and appears stuck in a manually set state
:# Provide your license details (License ID, server hardware ID, and your customer account information)
:# Wait for support to correct the license status on the backend licensing server
 
:'''After Backend Correction:'''
:# Log in to the VoIPmonitor web GUI
:# Navigate to '''Settings > License'''
:# 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|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.
;How are license channels calculated?
:Based on '''maximum concurrent calls''' (averaged hourly, checked daily). View in '''Tools → System Status → Concurrent calls'''.
:* Calls are deduplicated if last 6 digits of caller/called match within ±10 seconds
:* 487 Request Terminated responses are NOT counted


:* '''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.
;What happens if I exceed my limit?
 
:{| class="wikitable"
:* '''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 <code>packetbuffer_sender</code> configuration option in <code>/etc/voipmonitor.conf</code>. If <code>packetbuffer_sender</code> is set to <code>yes</code> (Packet Mirroring mode), this can cause unexpected RTP recording behavior.
 
:To fix this issue:
:* Locate the <code>packetbuffer_sender</code> option in <code>/etc/voipmonitor.conf</code>
:* Set <code>packetbuffer_sender</code> to <code>no</code>, or comment out the line (default is <code>no</code>)
:* Restart the VoIPmonitor service: <code>systemctl restart voipmonitor</code>
 
:For more information about client-server modes and the <code>packetbuffer_sender</code> option, see [[Sniffer_distributed_architecture|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: [[download_of_pcap_files_audio_files_using_GUI's_api|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|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'''
 
:# Log in to the VoIPmonitor sensor server
:# Check the maximum spool size configured:
:<syntaxhighlight lang="bash">grep maxpoolsize /etc/voipmonitor.conf</syntaxhighlight>
:# Check the maximum days configured:
:<syntaxhighlight lang="bash">grep maxpooldays /etc/voipmonitor.conf</syntaxhighlight>
:# Check current spool directory usage:
:<syntaxhighlight lang="bash">du -h --max-depth=1 /var/spool/voipmonitor | tail -20</syntaxhighlight>
 
:'''Resolution: Increase Retention Limits'''
 
Edit <code>/etc/voipmonitor.conf</code> to increase the storage limit:
:<syntaxhighlight lang="ini"># 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</syntaxhighlight>
 
Apply changes:
:<syntaxhighlight lang="bash">systemctl restart voipmonitor</syntaxhighlight>
 
:'''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#Troubleshooting:_Disk_Full_/_Files_Disappearing|Data Cleaning - Disk Full Troubleshooting]].
 
:'''Differentiating from Download Button Issues:'''
 
{| class="wikitable"
|-
|-
! Symptom !! Root Cause !! Solution
! Duration !! Effect
|-
|-
| 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
| 1-2 days || Warning only, self-clearing
|-
|-
| Download button shows browser console errors (Chrome: <code>ERR_BLOCKED_BY_RESPONSE</code>) || Nginx X-Frame-Options blocking downloads || See [[Cannot_download_pcap/audio_from_spooldir_when_using_chrome_and_nginx|Chrome/Nginx download fix]]
| 3+ consecutive days || GUI blocked
|-
| 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?
;How do I unblock a locked GUI?
: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.
:In '''Settings > License''', click '''get/update license key''' – this grants a temporary increase automatically.


:'''Root Cause:'''
;I get "Invalid or corrupted hwid" error. What do I do?
:'''Common causes:'''
:# '''Incomplete key:''' Copy the '''entire''' multi-line license key, not just the first line
:# '''Wrong field:''' Use "License token" for short tokens, "License key" for full multi-line keys
:# '''AWS:''' Run <code>chmod 644 /dev/root</code>
:# '''Docker:''' Ensure container ID doesn't change on restart
:# '''Trial on different machine:''' Contact support for a pre-generated key


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.
;I get "license file key.php is for another hwid" after hardware change?
:In '''Settings > License''', click '''get/update license key''' then '''recheck''' to fetch new key for current HWID.


:'''Solution: Disable Pcap Deduplication Before Download'''
;I get "Bad Key Content" error?
:You're using the wrong field. Short tokens go in "License token" field, then click "get/update license key".


To ensure the downloaded PCAP contains all captured packets including duplicates and retransmissions:
;How do I transfer a license to a new server?
:# Get token from old GUI ('''Settings > License''') or customer portal
:# On new GUI: paste token, click '''get/update license key'''
:# '''IMPORTANT:''' Disable cron on old server to prevent conflicts


# Log in to the VoIPmonitor GUI with administrator privileges
;Can I use one license on multiple servers (test/dev)?
# Navigate to '''Settings > System Configuration > Advanced'''
:Yes. Contact support to reconfigure your token for multiple HWIDs.
# Find the '''Pcap deduplication before download''' option
# '''Disable (uncheck)''' this option
# 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.
;What are the available license tiers?
:10, 35, 50, 100, 150, 200, 350, 500, 750, 1000, 1250, 1500, 1750, 2000


:'''Important Notes:'''
== Audio & PCAP Files ==
 
:* 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:'''


# Open your PCAP file in Wireshark
;Why does call recording stop after exactly 4 hours?
# Navigate to '''Edit > Preferences'''
:Default <code>absolute_timeout = 14400</code> (4 hours). Increase or disable:
# Expand '''Protocols''' section and click on '''TCP'''
:<syntaxhighlight lang="ini">absolute_timeout = 43200  # 12 hours
# Uncheck the option '''"Analyze TCP sequence numbers"''' (or similar wording depending on Wireshark version)
# absolute_timeout = 0    # Unlimited (watch memory usage)</syntaxhighlight>
# Click '''OK''' to apply the setting
# 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:
;Why are WAV files missing for non-G.711 codecs (Opus, G.729)?
:<code>tcp.analysis.lost_segment == FALSE or sip</code>
:Requires <code>vmcodecs</code> binary from GUI package. Install GUI, then restart sensor.


:'''Important Notes:'''
;Why is audio playback garbled?
:DTLS-SRTP encryption. Configure SSL Key Logger for decryption. See [[Tls|TLS/SRTP Decryption]].


:* The SIP packets are always present in the exported PCAP file - VoIPmonitor fully captures all signaling
;Why can't I download PCAP files?
:* This is purely a Wireshark display preference, not a data loss issue
:Files deleted by retention limits. Check:
:* Other packet analyzers (tcpdump, tshark) will show all packets by default
:<syntaxhighlight lang="bash">grep maxpoolsize /etc/voipmonitor.conf
:* You only need to change this setting in your local Wireshark installation, not in VoIPmonitor
grep maxpooldays /etc/voipmonitor.conf</syntaxhighlight>
:Increase limits and restart. See [[Data_Cleaning|Data Cleaning]].


:;Why are .wav audio files not generated for calls using non-G.711 codecs (e.g., Opus, G.729)?
;Why does downloaded PCAP have fewer packets than GUI shows?
: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 <code>vmcodecs</code> to perform the codec transcoding.
:'''Pcap deduplication before download''' is enabled. Disable in '''Settings > System Configuration > Advanced'''.


:This <code>vmcodecs</code> binary is '''exclusively distributed within the GUI installation package''' and is required to create audio files from non-G.711 codec recordings.
;How do I bulk download audio/PCAP files?
:Use GUI API. See [[download_of_pcap_files_audio_files_using_GUI's_api|Bulk Download Guide]].


:'''To resolve this issue:'''
;Can VoIPmonitor detect voicemail calls?
:# '''Install the GUI package''' (even if you don't plan to use the web interface). The GUI package includes the necessary <code>vmcodecs</code> binary in <code><gui-installation-path>/bin/vmcodecs</code>.
:'''No automatic detection''' by analyzing RTP audio. Workarounds:
:# '''Ensure <code>vmcodecs</code> is accessible''' to the sensor - it must be in a directory that is in the system's <code>$PATH</code> or the sensor's working directory.
:* Filter by voicemail pilot number
:# '''Restart the sensor''' after installing the GUI to apply the changes.
:* Track SIP 302 redirects (<code>save_sip_history = all</code>)
:# '''For existing .raw files''': Re-process the spooldir content after GUI installation to generate the missing audio files.
:* Capture custom SIP headers your PBX adds


:'''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.
;How do I convert WAV to OGG?
 
:<syntaxhighlight lang="bash">cd /var/spool/voipmonitor
;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 <code>a=crypto</code> lines in the SDP which indicate SRTP encryption
:* '''DTLS fingerprint:''' Look for <code>a=fingerprint</code> or <code>a=setup</code> 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.
 
:# The SSL Key Logger is installed on the SBC or PBX that terminates the calls
:# It captures DTLS session keys from memory using the <code>LD_PRELOAD</code> mechanism
:# Keys are sent over the network to the VoIPmonitor sensor
:# 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 <code>sslkeylog.so</code> library
:* Configuring Asterisk, Kamailio, FreeSWITCH, or other SIP applications
:* Setting up VoIPmonitor to receive session keys
:* Correct <code>ssl_ipport</code> syntax for key logger mode
:* TCP mode for secure key transport
 
:'''Common Configuration Pitfalls:'''
 
:* '''Wrong ssl_ipport syntax:** When using SSL Key Logger, <code>ssl_ipport</code> must NOT include a path to a key file (e.g., <code>ssl_ipport = 192.168.1.50:5061</code> is correct, but <code>ssl_ipport = 192.168.1.50:5061 /path/to/key.pem</code> will fail)
:* '''Keys sent to wrong destination:** In distributed architectures with <code>packetbuffer_sender=yes</code>, keys must go to the central server IP, not localhost or the remote client sensor
:* '''PBX not configured:''' The PBX/SBC must have <code>sslkeylog.so</code> preloaded via <code>LD_PRELOAD</code> 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 <code>vmcodecs</code> binary. The <code>vmcodecs</code> 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 <code>bind</code>.
 
:'''2. Add natalias configuration'''
:Add the <code>natalias</code> option to the import configuration to map public IPs to private IPs:
:<syntaxhighlight lang="ini">
natalias = 1.1.1.1 10.0.0.3
natalias = 2.2.2.2 10.0.0.4
</syntaxhighlight>
:Multiple <code>natalias</code> lines can be used if multiple NAT mappings are required. See [[Sniffer_configuration#NAT|NAT Configuration]] in the sniffer configuration reference.
 
:'''3. Check GUI/DB Settings priority'''
:Settings in <code>Settings -> Sensors</code> in the GUI have higher priority than <code>voipmonitor.conf</code>. If <code>id_sensor</code> 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 <code>.wav</code> and wish to convert them to the more efficient <code>.ogg</code> format to save disk space, you can run the following sequence of commands directly in your spool directory (e.g., <code>/var/spool/voipmonitor</code>):
 
<syntaxhighlight lang="bash">
# 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"' {} \;
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 {} \;
find ./ -name '*.wav' -exec rm -f {} \;
chown -R www-data:www-data ./</syntaxhighlight>


# Step 3: Set the web server user (e.g., www-data) as the owner of all files.
;How do I enable live call listening?
# This is crucial for the GUI to be able to read and play the new .ogg files.
:Edit <code>configuration.php</code>:
chown -R www-data:www-data ./
:<syntaxhighlight lang="php">define('DISABLE_LIVEPLAY', false);</syntaxhighlight>
</syntaxhighlight>
:See [[GUI_Configuration_PHP|GUI Configuration]] for details.
;Why is transfer throughput to external storage (S3, CloudBerry) limited?
:VoIPmonitor does not impose speed limits on external storage transfers. If you see artificial throughput caps (e.g., 40 Mbps):<br>
# '''Verify bandwidth''' from your host to the internet is sufficient<br>
# '''Check third-party tool configuration''' (e.g., CloudBerry, s3fs, rclone) - the bottleneck is typically in these tools, not VoIPmonitor<br>
# For '''controlled bandwidth limiting''', use <code>rsync</code> via cron job with <code>--bwlimit</code> or the <code>tar_move</code> option - both allow bandwidth management
== Administration ==


;The 'live play' audio feature is disabled in the GUI. How do I re-enable it?
;How do I reset admin password?
: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.
:See [[User_Management|User Management]].


:'''To re-enable live play:'''
;How do I fix GUI after PHP/OS upgrade?
:Re-run installation. See [[Re-install_the_GUI|Re-install GUI]].


:# '''Access the GUI host server''' via SSH or terminal.
;How do I enable debug mode?
:# '''Edit the configuration file''' located at:
:Add <code>?debug=31415</code> to URL. See [[GUI_troubleshooting#GUI_Debug_Mode|GUI Debug Mode]].
::<code>/var/www/html/voipmonitor/configuration.php</code>
::(The path may vary slightly depending on your installation, typically under <code>/var/www/html/</code> or <code>/var/www/</code>)
:# '''Find the DISABLE_LIVEPLAY constant''':
::<syntaxhighlight lang="php">define('DISABLE_LIVEPLAY', true);</syntaxhighlight>
:# '''Change the value from true to false''':
::<syntaxhighlight lang="php">define('DISABLE_LIVEPLAY', false);</syntaxhighlight>
:# '''Save the file''' and exit the editor.
:# '''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.
;How do I fix "Unknown column" errors after database upgrade?
:Access: <code>https://your-gui/admin.php?check_tables=1</code>
:{{Note|1=Do NOT use "Check MySQL Schema" button in Tools - that's for millisecond precision only.}}


: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 <code>true</code>.
;Can I run multiple sensor instances on one host?
:Yes. See [[Multiple_sniffer_instancies|Multiple Instances Guide]].
;Users from the same organization cannot view each other's support tickets. How can we share access?
:Support tickets are associated with individual email addresses. To enable team-wide ticket visibility, '''merge all user accounts under a single main email address'''. Contact VoIPmonitor support to consolidate multiple accounts into one organization account.
== Compliance ==


== Administration & Troubleshooting ==
=== PCI Compliance ===


;The voipmonitor service fails to start, reporting an error for a network interface that no longer exists and has been removed from the main configuration file. How do I fix this?
;How do I disable audio recording?
:This occurs when stale configuration entries remain in the database and override your file settings. When <code>mysqlloadconfig = yes</code> (the default), the sensor loads configuration parameters from the <code>sensor_config</code> database table, which can contain references to network interfaces that have been renamed or removed.
:<syntaxhighlight lang="ini">savertp = header    # Headers only, no audio
savertp = no        # No RTP at all
dtmf2db = no        # No DTMF to database
dtmf2pcap = no      # No DTMF to PCAP</syntaxhighlight>


:'''Solution 1: Remove stale entries via GUI (Recommended)'''
;How do I selectively record calls?
:
:Use [[Capture_rules|Capture Rules]] to enable/disable recording based on IP, number, or SIP headers.
:# Log in to the VoIPmonitor Web GUI.
:# Navigate to '''Settings > Sensors'''.
:# Find the sensor entry corresponding to this server.
:# Edit the '''Interface''' field to match the correct (current) interface name or remove it entirely if it should be blank.
:# Save the changes and restart the voipmonitor service: <code>systemctl restart voipmonitor</code>


:'''Solution 2: Remove stale entries directly from the database'''
;How do I disable live listening?
:
:* '''Settings > System Configuration > Advanced:''' Enable "Hide live play" and "Hide WAV play"
If you prefer to use SQL or do not have access to the GUI, you can directly delete the stale configuration from the <code>sensor_config</code> table:
:* Edit <code>configuration.php</code>: <code>define('DISABLE_LIVEPLAY', true);</code>
:* Edit <code>config/system_configuration.php</code>: <code>define('DISABLE_LIVE_SNIFFER', true);</code>
{{Note|1='''Understanding audio in VoIPmonitor:''' By default, the GUI extracts audio '''on-demand''' from stored RTP packets in PCAP files (when <code>savertp = yes</code>). The <code>saveaudio</code> option creates '''pre-generated''' audio files and is NOT required for audio playback. Setting <code>savertp = header</code> disables audio playback because RTP payload is not stored. See [[Sniffer_configuration#Understanding_Audio_Playback_vs_Pre-Generated_Files|Audio Playback vs Pre-Generated Files]] for details.}}
=== CALEA Compliance ===


<syntaxhighlight lang="sql"># Access the voipmonitor database
;How do I export data to CALEA systems?
mysql -u voipmonitor -p voipmonitor
:Use GUI API methods <code>getPCAP</code> and <code>getVoiceRecording</code>. See [[CALEA_compliance|CALEA Integration Guide]].


# Locate the stale configuration entry (replace old_interface_name with the interface that no longer exists)
== See Also ==
SELECT * FROM sensor_config WHERE interface LIKE '%old_interface_name%';


# Delete the identified row using its ID (replace <found_id> with the actual id from the SELECT query above)
* [[Sniffer_troubleshooting|Sniffer Troubleshooting]] - packet capture, missing CDRs
DELETE FROM sensor_config WHERE id=<found_id>;
* [[GUI_troubleshooting|GUI Troubleshooting]] - HTTP 500, database issues
* [[Sniffer_configuration|Sniffer Configuration Reference]]
* [[License|Licensing Details]]
* [[Data_Cleaning|Data Cleaning and Retention]]


# Exit the database
EXIT;
</syntaxhighlight>


:After deleting the stale entries, restart the voipmonitor service:
<syntaxhighlight lang="bash">systemctl restart voipmonitor</syntaxhighlight>


:'''Solution 3: Disable database configuration loading'''
:
If you prefer to manage all configuration via the config file only, you can disable database loading:
:# Edit <code>/etc/voipmonitor.conf</code>: <code>nano /etc/voipmonitor.conf</code>
:# Add or modify the line: <code>mysqlloadconfig = no</code>
:# Restart the service: <code>systemctl restart voipmonitor</code>


:{{Warning|This will disable the ability to change settings via the GUI "Settings > Sensors" for this machine. }}


:For more information on <code>mysqlloadconfig</code>, see [[Sniffer_configuration#mysqlloadconfig|Sniffer Configuration]].


;Why do the colors for SIP response codes in dashboard graphs change automatically?
:This is a known limitation of the charting system. The dominant SIP response code automatically takes the 'green' color, which can make it difficult to interpret trends consistently over time.


:'''Current Status:''' There is no current workaround to force fixed colors for specific SIP response codes. A feature request (VG-3031) has been created to make the colors for response codes settable.


:'''What This Means:**
== AI Summary for RAG ==
:* The chart color assignment is dynamic and adjusts based on which response code appears most frequently
:* Charts that show SIP response codes (such as 200 OK, 404 Not Found, 500 Server Error) will not maintain consistent colors across different time periods
:* You cannot manually assign specific colors to specific response codes
 
:'''Future Solution:''' Wait for a future VoIPmonitor release where the feature request VG-3031 is implemented, which will allow users to configure fixed colors for response codes.
 
;How do I fix "bad gso: type: 1, size: 1448" or kernel errors related to network offloading?
:This error appears in the kernel logs when VoIPmonitor is running and indicates an issue with Generic Segmentation Offload (GSO), TCP Segmentation Offload (TSO), or other network interface offload features.
 
:'''Symptoms:'''
:* Kernel messages like: <code>ens3: bad gso: type: 1, size: 1448</code>
:* Errors may mention UDP Fragmentation Offload (UFO)
:* Packet capture issues during VoIPmonitor operation
 
:'''Solution:''' Disable the offload features on the affected interface:
<syntaxhighlight lang="bash">
# Check MTU (should be > 1448, typically 1500)
ip addr show eth0
 
# Disable offload features (replace ens3 with your interface name)
ethtool -K ens3 gso off tso off gro off lro off
 
# Verify the change persists (check kernel logs)
dmesg -T | grep -i gso
</syntaxhighlight>
 
:To make changes '''persistent across reboots''', create a systemd service:
<syntaxhighlight lang="ini">
# /etc/systemd/system/disable-offload.service
[Unit]
Description=Disable network offloads for VoIPmonitor
After=network.target
 
[Service]
Type=oneshot
ExecStart=/usr/sbin/ethtool -K ens3 gso off tso off gro off lro off
 
[Install]
WantedBy=multi-user.target
</syntaxhighlight>
 
<syntaxhighlight lang="bash">
# Enable and start the service
systemctl enable disable-offload.service
systemctl start disable-offload.service
</syntaxhighlight>
 
:If the issue persists after disabling offloads, consider updating the system's kernel and network interface drivers to the latest versions.
 
;How do I reset a lost admin password for the GUI?
:Please follow the instructions in the [[User_Management|User Management guide]].
 
;How do I fix a corrupted GUI installation or reinstall it?
:A reinstallation can fix issues with corrupted files or incorrect permissions. See the guide here: [[Re-install_the_GUI]].
 
;The GUI stopped working after a server OS or PHP version upgrade. How do I fix it?
:This usually requires re-running the GUI installation script to align with the new PHP version. See: [[GUI_Installation#Re-installing_the_GUI]].
 
;How do I reinstall or upgrade the sniffer to the latest version?
:Instructions for downloading and installing the latest static binary are here: [[Sniffer_installation|Sniffer Installation]].
 
;Can I run multiple instances of the sniffer on a single host?
:Yes, this is possible for advanced use cases. See the guide: [[Multiple_sniffer_instancies]].
 
;What user actions are recorded in the Audit Log?
:The Audit Log tracks the following security-sensitive actions in the GUI:
:* Login / Logout
:* Playing or downloading WAV/PCAP files
:* Showing a FAX
:* Using the batch download feature
:* Applying a filter in the CDR view
 
;How do I enable debug mode or troubleshoot GUI issues?
:For GUI debugging techniques including enabling debug mode to see SQL queries, please see the [[GUI_troubleshooting|GUI Troubleshooting guide]].
 
;How do I troubleshoot internet connectivity issues (cannot download updates, source code, or access external resources)?
:If the sensor server cannot connect to external resources such as download servers, GitHub, or package repositories, follow this troubleshooting process:
 
:'''Step 1: Verify basic network connectivity'''
:<syntaxhighlight lang="bash"># Test if the server can reach external hosts
ping -c 4 8.8.8.8
 
# Test DNS resolution
ping -c 4 google.com
</syntaxhighlight>
 
:If these commands fail, the issue is with network configuration or routing. Check:
:* Network interface configuration: <code>ip addr show</code>
:* Default gateway: <code>ip route show</code>
:* DNS configuration: <code>cat /etc/resolv.conf</code>
 
:'''Step 2: Check firewall rules for outbound connections'''
:<syntaxhighlight lang="bash"># Check if firewalld is being used
systemctl status firewalld
 
# List open ports if using firewalld
firewall-cmd --list-ports
 
# Check iptables rules if applicable
iptables -L -n | grep -E "ACCEPT|REJECT|DROP"
</syntaxhighlight>
 
:Ensure that outbound connections on HTTP (port 80) and HTTPS (port 443) are not blocked. The server needs to reach:
:* <code>download.voipmonitor.org</code> (for software downloads)
:* <code>github.com</code> (for source code)
:* Package repository servers (dnf/yum/apt repositories)
 
:'''Step 3: Test connectivity to specific hosts'''
:<syntaxhighlight lang="bash"># Test HTTPS connectivity to GitHub
curl -I https://github.com
 
# Test connectivity to VoIPmonitor download server
curl -I https://www.voipmonitor.org
 
# Test package repository (for RHEL/CentOS/AlmaLinux)
dnf repolist
 
# Test package repository (for Debian/Ubuntu)
apt-get update
</syntaxhighlight>
 
:If <code>curl</code> commands time out or fail, check for:
:* Proxy server requirements (corporate networks often require HTTP proxy)
:* Firewall rules blocking outbound HTTPS
:* Network routing issues
 
:'''Step 4: Configure HTTP proxy (if required by your network)'''
:If your network requires a proxy server, configure the <code>curlproxy</code> parameter in <code>/etc/voipmonitor.conf</code> to enable sensor updates and downloads:
:<syntaxhighlight lang="ini">
[general]
# Replace with your actual proxy address and port
curlproxy = http://proxy-server-ip:port
</syntaxhighlight>
 
:Then restart the sensor:
:<syntaxhighlight lang="bash">systemctl restart voipmonitor</syntaxhighlight>
 
:'''Alternative: Use environment-wide proxy settings'''
:For package managers and system-wide proxy access, configure environment variables:
:<syntaxhighlight lang="bash">
# Set system-wide proxy (add to /etc/profile or /etc/environment)
export http_proxy="http://proxy-server-ip:port"
export https_proxy="http://proxy-server-ip:port"
 
# For package managers, configure in their settings files
# RHEL/CentOS/AlmaLinux: /etc/dnf/dnf.conf
proxy=http://proxy-server-ip:port
 
# Debian/Ubuntu: /etc/apt/apt.conf
Acquire::http::Proxy "http://proxy-server-ip:port";
</syntaxhighlight>
 
;I receive NXDOMAIN errors for VoIPmonitor-related domains only when Secure DNS (DNS-over-HTTPS/TLS) is enabled in my browser. How do I troubleshoot this?
:NXDOMAIN errors that occur only when Secure DNS is enabled typically indicate an issue with the specific secure DNS provider rather than the actual domain resolution. Secure DNS providers may have caching issues, incomplete records, or temporary outages that differ from standard DNS resolution.
 
:'''Diagnostic steps:'''
 
:1. Check which secure DNS provider is configured in your browser (Chrome: navigate to <code>chrome://settings/security</code> and look under "Use secure DNS")
 
:2. Verify the issue occurs only with Secure DNS enabled by temporarily disabling it and confirming the domain resolves normally
 
:3. Test standard DNS resolution from the command line to confirm the domain is valid:
:<syntaxhighlight lang="bash">dig www.voipmonitor.org</syntaxhighlight>
 
:4. Test DNS-over-HTTPS resolution directly against a provider's API to isolate the issue:
:<syntaxhighlight lang="bash"># Test Google's DNS-over-HTTPS API
curl -s "https://dns.google/resolve?name=www.voipmonitor.org&type=A" | jq</syntaxhighlight>
 
:If <code>dig</code> successfully resolves the domain but Chrome Secure DNS fails, the issue is with your configured secure DNS provider. Try switching to an alternative secure DNS provider (e.g., switch from Cloudflare to Google, or vice versa) in your browser settings.
 
:If direct DoH queries (via curl) also fail, this indicates a temporary issue with that DNS provider's service. Switching providers typically resolves the problem.
 
=== Missing Database Tables ===
 
;VoIPmonitor logs errors that required database tables do not exist and fails to create them on restart. How do I fix this?
:If the VoIPmonitor sensor logs errors indicating that required database tables (such as <code>cdr_stat_values</code>, <code>cdr_problems_by_ip</code>, or others) do not exist and the service fails to create them automatically on startup, first determine if the table is required or optional.
 
:'''Optional Tables Requiring Configuration'''
 
Some VoIPmonitor database tables are optional and will not be created automatically unless explicitly enabled in the configuration. These tables are only created when their corresponding configuration option is set in <code>voipmonitor.conf</code>.


:Common optional tables include:
'''Summary:''' VoIPmonitor FAQ organized by topic. General: scaling (link to Scaling page), multiple GUI instances (requires same DB, NFS storage, single cron job to prevent duplicate alerts), client-server architecture for multi-sensor. Platform: x86 required for GUI (ARM64 not supported), AWS/Docker/cloud DB supported. CDR: regex filters with R() prefix, exclusion with ! prefix, underscore for multi-word search. Protocols: SIP, Skinny/SCCP, MGCP, SS7, Diameter supported; H.323 and MEGACO NOT supported. RTP: natalias for NAT mismatch causing missing quality metrics, auto_enable_use_blocks for multi-interface, rtp_check_both_sides_by_sdp for mixed audio. Licensing: concurrent calls averaged hourly, 3+ consecutive days over limit locks GUI, get/update button for temporary increase, common HWID errors (incomplete key, wrong field, AWS chmod, Docker cgroup). Audio: absolute_timeout default 4 hours (14400s), vmcodecs needed for non-G.711, DTLS-SRTP causes garbled audio. Admin: admin.php?check_tables=1 for schema errors after DB upgrade. Compliance: savertp=header/no for PCI, capture rules for selective recording, DISABLE_LIVEPLAY for hiding playback.
:* <code>cdr_problems_by_comb</code> - Requires <code>cdr_problems_by_comb=yes</code> in <code>voipmonitor.conf</code>
 
:If you see an error like <code>Table 'voipmonitor.cdr_problems_by_comb' doesn't exist</code>:
 
:# Open your VoIPmonitor configuration file (usually <code>/etc/voipmonitor.conf</code>):
::<syntaxhighlight lang="bash">nano /etc/voipmonitor.conf</syntaxhighlight>
 
:# Add or enable the configuration option that creates the missing table. For <code>cdr_problems_by_comb</code>:
::<syntaxhighlight lang="ini">cdr_problems_by_comb=yes</syntaxhighlight>
 
:# Save the file and restart the VoIPmonitor service to create the table:
::<syntaxhighlight lang="bash">systemctl restart voipmonitor</syntaxhighlight>
 
:'''Common Error Messages for Required Tables:'''
:* <code>Table 'cdr_problems_by_ip' doesn't exist</code>
:* <code>Table 'cdr_stat_values' doesn't exist</code>
:* Errors during database initialization or schema creation
 
:'''Step 1: Check Database Privileges'''
:The MySQL/MariaDB user configured in <code>voipmonitor.conf</code> (the <code>mysqlusername</code> parameter) must have privileges to create and alter database schema.
 
:# Log in to your MySQL/MariaDB console:
:<syntaxhighlight lang="bash">mysql -u root -p</syntaxhighlight>
 
:# Check the current privileges for the VoIPmonitor user:
:<syntaxhighlight lang="sql">SHOW GRANTS FOR 'voipmonitor'@'localhost';</syntaxhighlight>
 
:# If the user lacks <code>CREATE</code>, <code>ALTER</code>, or <code>DROP</code> privileges, grant them:
:<syntaxhighlight lang="sql">GRANT ALL PRIVILEGES ON voipmonitor.* TO 'voipmonitor'@'localhost';
FLUSH PRIVILEGES;
EXIT;</syntaxhighlight>
 
:'''Step 2: Check the disable_dbupgradecheck Configuration'''
:If the <code>disable_dbupgradecheck</code> option is enabled in <code>voipmonitor.conf</code>, the sensor will skip the automatic database schema upgrade and table creation process.
 
:# Open your configuration file:
:<syntaxhighlight lang="bash">nano /etc/voipmonitor.conf</syntaxhighlight>
 
:# Search for <code>disable_dbupgradecheck</code>. Ensure it is either commented out or set to <code>no</code>:
:<syntaxhighlight lang="ini"># disable_dbupgradecheck = yes  <-- Comment this out or set to 'no'
disable_dbupgradecheck = no</syntaxhighlight>
 
:# Save the file and exit the editor.
 
:'''Step 3: Restart the Service and Monitor Logs'''
:After correcting privileges and configuration, restart the sensor and watch the logs:
 
:<syntaxhighlight lang="bash">
# Restart the service
systemctl restart voipmonitor
 
# Monitor the initialization process
journalctl -u voipmonitor -f
</syntaxhighlight>
 
:You should see messages indicating the creation of functions, partitions, and tables. If errors persist, proceed to Step 4.
 
:'''Step 4: Manual Table Recreation (If Auto-Creation Fails)'''
:In some cases, tables may be in a corrupted state or the automatic creation process may repeatedly fail. In these situations, manually dropping and recreating the tables is required.
 
:# Connect to the database:
:<syntaxhighlight lang="bash">mysql -u voipmonitor -p voipmonitor</syntaxhighlight>
:(Replace <code>voipmonitor</code> with your actual database name and username if different.)
 
:# Drop the problematic tables if they exist:
:<syntaxhighlight lang="sql">DROP TABLE IF EXISTS cdr_problems_by_ip;
DROP TABLE IF EXISTS cdr_stat_values;</syntaxhighlight>
 
:# Manually recreate the tables using the correct <code>CREATE TABLE</code> SQL statements. You can obtain the schema definition from:
::* The <code>Tools -&gt; System Status -&gt; Check MySQL Schema</code> option in the Web GUI (if accessible)
::* A working VoIPmonitor installation of the same version
::* VoIPmonitor support
 
:# After recreating the tables, exit MySQL:
:<syntaxhighlight lang="sql">EXIT;</syntaxhighlight>
 
:# Restart the VoIPmonitor sensor:
:<syntaxhighlight lang="bash">systemctl restart voipmonitor</syntaxhighlight>
 
:'''Step 5: Verify the Fix'''
:Check that the sensor is running without table-related errors:
 
:<syntaxhighlight lang="bash">
# Check service status
systemctl status voipmonitor
 
# Monitor logs for any errors
journalctl -u voipmonitor -f
</syntaxhighlight>
 
:The errors regarding missing tables should cease, and the sensor should operate normally.
 
:'''Prevention:'''
:* Ensure the database user always has sufficient privileges (<code>ALL PRIVILEGES</code> on the VoIPmonitor database schema).
:* Keep <code>disable_dbupgradecheck</code> disabled (<code>no</code> or commented) to allow automatic schema updates.
:* Monitor database upgrade logs after VoIPmonitor version updates to catch schema issues early.
 
=== Managed MySQL Database - Table Creation Errors ===
 
;Using a managed MySQL database (e.g., DigitalOcean, AWS RDS, Google Cloud SQL), VoIPmonitor cannot create tables and reports errors about tables being created without primary keys. CDRs are not being saved. How do I fix this?
 
:Symptoms include:
:* CDRs are not being saved to the database after a fresh install
:* GUI reports errors about being unable to create tables without a primary key
:* MySQL error messages similar to: <code>ERROR 3750 (HY000): Unable to create or change a table without a primary key</code>
:* Some managed database services (DigitalOcean, AWS Aurora, Google Cloud SQL) enable the <code>sql_require_primary_key</code> system variable by default
 
:'''Root Cause:'''
 
:Some managed MySQL database providers enforce a requirement that all tables must have a primary key by setting the <code>sql_require_primary_key</code> system variable to <code>ON</code>. VoIPmonitor creates several database tables (such as temporary tables, cache tables, and statistics tables) that intentionally do not have primary keys due to their specific use cases (e.g., high write performance, data deduplication by unique key combinations, or transient data storage). The <code>sql_require_primary_key</code> restriction prevents these tables from being created, which blocks the entire database initialization process.
 
:'''Solution: Disable sql_require_primary_key'''
 
:Disable the <code>sql_require_primary_key</code> system variable in your managed MySQL database configuration. The exact method depends on your cloud provider.
 
:'''For DigitalOcean Managed MySQL:'''
 
:# Log in to the DigitalOcean Control Panel
:# Navigate to <code>Databases</code> > select your MySQL cluster
:# Click <code>Settings</code> tab
:# Locate the <code>SQL Mode</code> configuration section
:# Remove <code>sql_require_primary_key</code> from the SQL mode (or set <code>sql_require_primary_key=OFF</code> if your provider supports this as a separate setting)
:# Save the configuration changes. The database cluster will restart automatically.
 
:'''For AWS RDS MySQL:'''
 
:# Connect to your RDS instance using a user with administrative privileges
:# Run the following SQL command to check the current setting:
:<syntaxhighlight lang="sql">SHOW VARIABLES LIKE 'sql_require_primary_key';</syntaxhighlight>
 
:# To disable it temporarily (until the instance restarts):
:<syntaxhighlight lang="sql">SET GLOBAL sql_require_primary_key = OFF;</syntaxhighlight>
 
:# To make it persistent, create or modify a parameter group in the AWS RDS console:
:#* Go to <code>RDS</code> > <code>Parameter Groups</code>
:#* Create a new parameter group or select an existing one
:#* Search for <code>sql_require_primary_key</code>
:#* Set the value to <code>0</code> (disabled)
:#* Associate the modified parameter group with your RDS instance
:#* Reboot the RDS instance for changes to take effect
 
:'''For Google Cloud SQL:'''
 
:# Go to <code>Google Cloud Console</code> > <code>SQL</code> > select your instance
:# Click <code>Edit</code>
:# Scroll to <code>Flags</code> section
:# Add a flag: <code>sql_require_primary_key=off</code>
:# Click <code>Save</code> and confirm the instance restart
 
:'''For Other Providers:'''
 
:# Check your provider's documentation for configuring SQL modes or system variables
:# Look for settings related to <code>sql_require_primary_key</code>, <code>sql_mode</code>, or database flags
:# Disable or remove <code>sql_require_primary_key</code> from the configuration
 
:'''Verifying the Fix'''
 
:After disabling <code>sql_require_primary_key</code>, restart VoIPmonitor and verify that tables are being created correctly:
 
:<syntaxhighlight lang="bash"># Restart the sensor
systemctl restart voipmonitor
 
# Monitor the logs to ensure tables are created successfully
journalctl -u voipmonitor -f</syntaxhighlight>
 
:You should see messages indicating that CDRs are being written to the database and no more primary key related errors.
 
:'''Alternative: Self-Hosted MySQL/MariaDB'''
 
:If you cannot disable <code>sql_require_primary_key</code> on your managed database service, consider deploying a self-hosted MySQL or MariaDB instance. Many Linux distributions provide packages (e.g., via apt or yum) that allow full control over database configuration without such restrictions.
 
=== Database Upgrade Safety Mechanism for Production Databases ===
 
;When installing a new VoIPmonitor sensor and connecting it to an existing production database, will it automatically modify the database schema and cause downtime? How does the production safety mechanism work?
 
:The VoIPmonitor sensor includes a built-in safety mechanism to protect production databases from automatic schema modifications that could cause downtime or table locks.
 
:'''How the Safety Mechanism Works:'''
 
;New Databases or Small Databases (< 1000 CDRs):
:When the sensor starts on a new database or a database with fewer than 1000 CDRs, it will automatically create tables, modify the schema, and apply all necessary upgrades. This is safe because there is minimal data at risk.
 
;Large Production Databases (> 1000 CDRs):
:If the database contains more than 1000 CDR records, the sensor will '''not''' automatically execute schema changes (such as <code>ALTER TABLE</code> commands that add or modify columns). Instead, it will log the required SQL statements to the system logs for manual review and execution during a controlled maintenance window.
 
:'''Behavior When Connecting to a Large Production Database:'''
 
:# The sensor detects that the database has more than 1000 CDRs
:# Instead of running <code>ALTER TABLE</code> commands immediately, it logs the required SQL changes to:
:* <code>/var/log/syslog</code> or <code>/var/log/messages</code> (depending on your distribution)
:* <code>journalctl -u voipmonitor</code> (systemd-based systems)
:# The sensor continues operating normally with the existing schema structure
:# The administrator can review the logged SQL statements and execute them manually during a low-traffic period (e.g., overnight) to prevent table locking during production hours
 
:'''Checking for Logged Upgrade Queries:'''
 
To see if any schema upgrade queries have been logged, check the sniffer logs:
 
<syntaxhighlight lang="bash">
# On systemd systems
journalctl -u voipmonitor | grep -i "alter\|upgrade"
 
# On traditional systems
grep -i "alter\|upgrade" /var/log/syslog
grep -i "alter\|upgrade" /var/log/messages
</syntaxhighlight>
 
:'''Manual Execution of Upgrade Queries:'''
 
If you find logged SQL statements that need to be applied:
 
:# Review each statement carefully to ensure it matches your intended changes
:# Schedule a maintenance window during low-traffic hours
:# Execute the SQL statements manually:
:<syntaxhighlight lang="bash">mysql -u voipmonitor -p voipmonitor</syntaxhighlight>
:<syntaxhighlight lang="sql">
-- Paste each SQL statement here, one at a time:
ALTER TABLE cdr ADD COLUMN new_column INT DEFAULT 0;
-- (example - use the actual logged statements)
</syntaxhighlight>
:# Restart the sensor after applying the changes:
:<syntaxhighlight lang="bash">systemctl restart voipmonitor</syntaxhighlight>
 
:'''Important Considerations for Distributed Environments:'''
 
If you are running multiple sensors (old and new) simultaneously against the same production database:
 
:* Ensure each sensor has a unique <code>id_sensor</code> value in <code>voipmonitor.conf</code> to avoid data collision
:* Only one sensor should manage partition operations if multiple sensors write to the same database (see <code>disable_partition_operations</code> in [[Sniffer_configuration|Sniffer Configuration]])
:* Review and adjust hardware-dependent settings on the new sensor such as:
:** <code>interface</code> - Network interface for packet capture
:** <code>max_buffer_mem</code> - Maximum memory for packet buffer
:** <code>spooldir</code> - Directory for PCAP/RTP spool files
:** <code>maxpoolsize</code> - Maximum RTP pool size
 
:'''When to Use disable_dbupgradecheck:'''
 
The <code>disable_dbupgradecheck</code> configuration parameter can be used to completely disable the schema upgrade check, but this is '''rarely necessary''' given the built-in safety mechanism for large databases.
 
Consider disabling the check only if:
:* Your production database schema is explicitly older than the sensor software version, and you want to manage all schema changes manually
:* You want to prevent any automatic checks or logging of upgrade queries
:* You have a specific database maintenance workflow that does not use the sensor's upgrade detection
 
;See also: [[Sniffer_configuration#disable_dbupgradecheck|disable_dbupgradecheck parameter documentation]]
 
=== MariaDB System Table Corruption After OS Upgrade ===
 
;After upgrading the OS (e.g., Debian 11 to 13) and reinstalling VoIPmonitor, MariaDB reports errors about incorrect table definitions in the system <code>mysql</code> database (e.g., <code>mysql.column_stats</code>) and VoIPmonitor fails to create routines due to insufficient user privileges. How do I fix this?
 
:This issue occurs because:
:* A major OS upgrade typically installs a newer version of MariaDB (e.g., MariaDB 10.11+ on Debian 13)
:* The existing MariaDB system databases may not be fully compatible or may be corrupted
:* The <code>voipmonitor</code> database user may lack the required privileges for the new MariaDB version
 
:'''Common Error Messages:'''
:* <code>Table 'mysql.column_stats' doesn't exist</code>
:* <code>Incorrect table definition; there can be only one auto column and it must be defined as a key</code>
:* <code>CREATE FUNCTION command denied to user 'voipmonitor'@'...' for table '...'</code>
 
:'''Solution: Reinitialize MariaDB System Databases'''
:{{Warning|This procedure will delete all MariaDB databases and their data. The VoIPmonitor database will need to be recreated. If you need to preserve existing data, export it first using <code>mysqldump</code>.}}
 
:# '''Stop the MariaDB service''':
:<syntaxhighlight lang="bash">systemctl stop mariadb</syntaxhighlight>
 
:# '''Backup the MariaDB data directory (if you need to preserve any data)''':
:<syntaxhighlight lang="bash">cp -a /var/lib/mysql /var/lib/mysql.backup</syntaxhighlight>
 
:# '''Delete the entire MariaDB data directory''':
:<syntaxhighlight lang="bash">rm -rf /var/lib/mysql/* /var/lib/mysql/.* 2>/dev/null || true</syntaxhighlight>
 
:# '''Start the MariaDB service to reinitialize system databases cleanly''':
:<syntaxhighlight lang="bash">systemctl start mariadb</syntaxhighlight>
:The service will create fresh system databases (<code>mysql</code>, <code>information_schema</code>, <code>performance_schema</code>, etc.).
 
:# '''Create the VoIPmonitor database user with correct privileges''':
:<syntaxhighlight lang="bash">mysql</syntaxhighlight>
Once in the MySQL console, run:
:<syntaxhighlight lang="sql">CREATE USER 'voipmonitor'@'127.0.0.1' IDENTIFIED BY 'YourPassword';
GRANT ALL ON voipmonitor.* TO 'voipmonitor'@'127.0.0.1';
GRANT SUPER ON *.* TO 'voipmonitor'@'127.0.0.1';
FLUSH PRIVILEGES;</syntaxhighlight>
{{Note|The <code>GRANT SUPER</code> privilege is required for VoIPmonitor to create stored procedures and triggers in newer MariaDB versions.}}
 
:# '''Create the VoIPmonitor database''':
:<syntaxhighlight lang="sql">CREATE DATABASE voipmonitor;
EXIT;</syntaxhighlight>
 
:# '''Restart VoIPmonitor services''':
:<syntaxhighlight lang="bash">systemctl restart voipmonitor</syntaxhighlight>
:On startup, the sensor will automatically create the required tables, functions, and triggers in the new database.
 
:'''Alternative: Configure MariaDB Without SUPER Privilege'''{{Warning|If you cannot grant <code>SUPER</code> privilege (e.g., cloud-hosted database), you must set <code>log_bin_trust_function_creators = ON</code> in the MariaDB configuration.}}
 
:# Edit the MariaDB server configuration:
:<syntaxhighlight lang="bash">nano /etc/mysql/mariadb.conf.d/50-server.cnf</syntaxhighlight>
 
:# Add the following line under the <code>[mysqld]</code> section:
:<syntaxhighlight lang="ini">[mysqld]
log_bin_trust_function_creators = ON</syntaxhighlight>
 
:# Restart MariaDB to apply the change:
:<syntaxhighlight lang="bash">systemctl restart mariadb</syntaxhighlight>
 
:'''Prevention:'''
:* After major OS upgrades, check MariaDB system table compatibility before reinstalling VoIPmonitor
:* Run <code>mariadb-upgrade</code> (or <code>mysql_upgrade</code> on older systems) to update system databases if not performing a full reinitialization
:* Ensure the <code>voipmonitor</code> database user has appropriate privileges for your MariaDB version
 
=== VoIPmonitor Server Crashes After MySQL Upgrade ===
 
;VoIPmonitor primary server crashes and becomes inaccessible after a system upgrade. Sensors cannot connect, and the web GUI is unavailable. What caused this and how do I fix it?
 
:This issue typically occurs when MySQL was upgraded to version '''8.0.42''', which contains bugs that can cause server crashes and database connection failures with VoIPmonitor.
 
:'''Root Cause:'''
:* MySQL version 8.0.42 has known bugs that cause instability with high-traffic VoIPmonitor deployments
:* Symptoms include: frequent server crashes, sensor connectivity failures, GUI unresponsiveness, and database connection errors
:* This often appears after a system or software upgrade that updated MySQL to 8.0.42
 
:'''Solution: Upgrade MySQL to 8.0.43 or Later'''
 
:# '''Check current MySQL version''':
:<syntaxhighlight lang="bash">mysql --version</syntaxhighlight>
 
:# '''If version is 8.0.42, upgrade to 8.0.43 or later''':
 
:* On Debian/Ubuntu systems:
::<syntaxhighlight lang="bash">sudo apt update
sudo apt install --only-upgrade mysql-server-8.0</syntaxhighlight>
 
:* On RHEL/CentOS/Rocky/AlmaLinux systems:
::<syntaxhighlight lang="bash">sudo dnf update mysql-server</syntaxhighlight>
 
:# '''Follow standard MySQL upgrade procedures''':
:* Backup your database before upgrading:
::<syntaxhighlight lang="bash">mysqldump -u root -p --all-databases > /var/lib/mysql-backup.sql</syntaxhighlight>
 
:* Stop MySQL service before upgrade:
::<syntaxhighlight lang="bash">systemctl stop mysql
# or for MariaDB:
systemctl stop mariadb</syntaxhighlight>
 
:* Perform the upgrade via your package manager
 
:* Start MySQL service after upgrade:
::<syntaxhighlight lang="bash">systemctl start mysql
# or for MariaDB:
systemctl start mariadb</syntaxhighlight>
 
:# '''Restart VoIPmonitor services''':
:<syntaxhighlight lang="bash">systemctl restart voipmonitor
# If using Apache/Nginx for GUI:
systemctl restart apache2
# or
systemctl restart httpd</syntaxhighlight>
 
:# '''Monitor the system''':
:* Check VoIPmonitor logs for errors: <code>journalctl -u voipmonitor -f</code>
:* Verify sensors can connect in the GUI under <code>Settings > Sensors</code>
:* Check GUI accessibility in your web browser
:* Monitor for recurring crashes - if issues persist, consider database restoration from backup
 
:'''If Issues Persist After Upgrade:'''
 
:# Restore database from backup (if needed):
:<syntaxhighlight lang="bash">mysql -u root -p < /var/lib/mysql-backup.sql</syntaxhighlight>
 
:# Consider a fresh database setup if the upgrade was incomplete
:# Contact VoIPmonitor support for additional assistance if crashes continue
 
:'''Prevention:'''
:* After any system upgrade that includes MySQL changes, check the MySQL version immediately
:* Test all VoIPmonitor functionality after MySQL upgrades
:* Keep MySQL updated to stable versions - avoid 8.0.42, use 8.0.43 or later
:* Maintain regular database backups before any major system changes
 
=== MySQL 8.0: Create Routine Fails with SYSTEM_USER Privilege Error ===
 
;VoIPmonitor sniffer fails to start or connect to the database, with logs showing errors like `create routine store_001 failed` and `Access denied; you need (at least one of) the SYSTEM_USER privilege(s) for this operation`. This occurs on MySQL 8.0 even if the user has been granted SUPER and ALL PRIVILEGES. How do I fix this?
 
:This issue occurs because MySQL 8.0 introduced the `SYSTEM_USER` privilege as a more granular alternative to the deprecated `SUPER` privilege. When binary logging is enabled, creating stored routines (functions and procedures) requires either `SYSTEM_USER` or `SUPER` privilege. Granting `SUPER` alone may not be sufficient in some MySQL 8.0 configurations.
 
:'''Solution 1: Grant SYSTEM_USER Privilege (Recommended for MySQL 8.0)'''
 
Connect to your MySQL console and grant the `SYSTEM_USER` privilege:
<syntaxhighlight lang="bash">mysql -u root -p</syntaxhighlight>
 
Once in the MySQL console, run:
<syntaxhighlight lang="sql">GRANT SYSTEM_USER ON *.* TO 'voipmonitor_user'@'localhost';
FLUSH PRIVILEGES;</syntaxhighlight>
Replace `voipmonitor_user` and `localhost` with your actual username and host.
 
Restart the VoIPmonitor sniffer service:
<syntaxhighlight lang="bash">systemctl restart voipmonitor</syntaxhighlight>
 
:'''Solution 2: Enable log_bin_trust_function_creators (Alternative)'''
 
If you cannot grant `SYSTEM_USER` or `SUPER` privileges (e.g., cloud-hosted database with restricted permissions), you can relax the restriction on creating functions by setting `log_bin_trust_function_creators = 1` in your MySQL configuration.
 
Edit the MySQL server configuration file (e.g., `/etc/mysql/my.cnf` or `/etc/my.cnf.d/mysql-server.cnf`):
<syntaxhighlight lang="bash">nano /etc/mysql/my.cnf</syntaxhighlight>
 
Add or uncomment the following line under the `[mysqld]` section:
<syntaxhighlight lang="ini">[mysqld]
log_bin_trust_function_creators = ON</syntaxhighlight>
 
Restart the MySQL service to apply the change:
<syntaxhighlight lang="bash">systemctl restart mysql</syntaxhighlight>
 
Restart the VoIPmonitor sniffer service:
<syntaxhighlight lang="bash">systemctl restart voipmonitor</syntaxhighlight>
 
:{{Note|The `SYSTEM_USER` privilege is the direct solution for MySQL 8.0. The `log_bin_trust_function_creators` workaround allows function creation without special privileges but affects binary logging behavior. Choose the approach that best fits your security and operational requirements.}}
 
=== Missing or Outdated Database Columns ===
 
;A 'Server side error' pop-up appears in the GUI with the message 'Unknown column [table].[column] in 'field list''. How do I fix this?
:This error occurs when the database schema is out of sync with the installed GUI or Sniffer version. The application expects a column that does not exist in the current database. This typically happens after an update where the automatic schema upgrade was skipped or failed.
 
:'''Common Error Messages:'''
:* <code>Unknown column 'Sensors.color_rowview' in 'field list'</code>
:* <code>Unknown column 'cdr.new_field_name' in 'field list'</code>
:* Any error referencing a missing column in a table that exists
 
:'''Solution: Check and Repair Tables via GUI'''
 
The fastest way to fix missing or outdated database columns is to use the built-in table repair feature in the VoIPmonitor GUI:
 
# Open the VoIPmonitor GUI in your web browser
# Add <code>?check_tables=1</code> to the end of the URL in the address bar
:* Example: <code>http://<your_gui_ip>/admin.php?check_tables=1</code>
:* Example with hostname: <code>https://voipmonitor.example.com/admin.php?check_tables=1</code>
# Press Enter to load the URL
# Wait for the table check and repair process to complete
# Navigate back to the section where the error occurred (e.g., CDR view) to verify the fix
 
The <code>?check_tables=1</code> parameter triggers an automatic database schema check and repair process. This will add any missing columns, update table structures, and ensure your database matches the expected schema for your software version.
 
:'''If the Error Persists:'''
 
If the <code>?check_tables=1</code> solution does not resolve the issue:
 
# Ensure the database user has <code>ALTER</code> privilege on the VoIPmonitor database. See the [[#Missing_Database_Tables|Missing Database Tables]] section for instructions on checking and granting privileges.
# Check that <code>disable_dbupgradecheck</code> is not enabled in <code>voipmonitor.conf</code> (see [[#Missing_Database_Tables|Missing Database Tables]]).
# Restart the VoIPmonitor sensor after applying <code>?check_tables=1</code>: <syntaxhighlight lang="bash">systemctl restart voipmonitor</syntaxhighlight>
# Check the sensor logs for schema validation errors: <syntaxhighlight lang="bash">journalctl -u voipmonitor -f</syntaxhighlight>
 
:'''Prevention:'''
:* Run <code>?check_tables=1</code> after every major VoIPmonitor GUI or Sniffer update to ensure the database schema is synchronized.
:* Keep <code>disable_dbupgradecheck</code> disabled to allow automatic schema updates.
:* Monitor database upgrade logs after software updates.
 
== 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 <code>savertp=header</code> in <code>voipmonitor.conf</code>.
:* To disable RTP capture entirely, use <code>savertp=no</code>.
:* To prevent DTMF tones (from SIP INFO or RFC2833) from being saved to the database and PCAP files, use:
:<syntaxhighlight lang="ini">
dtmf2db = no
dtmf2pcap = no
</syntaxhighlight>
 
;How do I selectively record or not record audio/DTMF?
:VoIPmonitor's powerful '''[[Capture_rules|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 <code>config/system_configuration.php</code> in your GUI installation directory and add:
::<syntaxhighlight lang="php">define('DISABLE_LIVE_SNIFFER', true);</syntaxhighlight>
::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 <code>Hide live play</code> and <code>Hide WAV play</code> options.
::Alternatively, edit <code>configuration.php</code> in the GUI directory and modify:
::<syntaxhighlight lang="php">define('DISABLE_LIVEPLAY', true);</syntaxhighlight>
 
:* '''Important security consideration:''' Users with administrator privileges can override global capture settings (including <code>savertp</code> 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|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|CALEA Compliance Integration Guide]].
 
;How can I export data to third-party CALEA systems?
:Use the GUI API methods <code>getPCAP</code> and <code>getVoiceRecording</code> to retrieve recorded data programmatically, then forward it to your third-party CALEA compliance system using custom scripts or middleware. See the [[CALEA_compliance|CALEA Compliance Integration Guide]] for detailed information.
 
== AI Summary for RAG ==
'''Summary:''' Comprehensive FAQ covering VoIPmonitor configuration and troubleshooting. Topics include: CDR analysis (regex filters, custom header search), platform support (AWS, Docker, VMWare ESXi, Azure), configuration (SIP ports, IPv6, DTMF, REGISTER, capture rules), protocol support (SIP, Skinny/SCCP, MGCP, SS7, Diameter, RTCP; H.323 NOT supported), licensing (concurrent channels, trial licenses, HWID issues including trial token requested from different machine workaround, multi-server licensing, "download failed" error when updating license key - troubleshoot by ping to 78.24.12.71 license server, check firewall rules for port 443, test HTTPS connectivity with curl, check proxy configuration), audio/PCAP files (bulk download, WAV-to-OGG conversion, vmcodecs for non-G.711, DTLS-SRTP decryption, Wireshark display issues with missing SIP messages, RTP still recording despite savertp=no due to packetbuffer_sender=yes), quality metrics (MOS, jitter, packet loss missing from one call leg due to NAT IP mismatch, natalias configuration), database troubleshooting (missing tables, schema upgrades, production database safety mechanism: auto-modify for databases with under 1000 CDRs, log ALTER queries for databases with over 1000 CDRs to syslog/journalctl for manual execution, MariaDB corruption after OS upgrades, MySQL 8.0 SYSTEM_USER privilege error, MySQL 8.0.42 crash bug, check_tables=1 fix), GUI issues (SIP response code color limitation in charts), network connectivity (ping tests, DNS resolution, firewall rules ports 80/443, curl connectivity to GitHub/download servers, dnf repolist, apt-get update, http proxy configuration, curlproxy, secure DNS issues), PCI compliance (selective recording), completely disabling live call monitoring (DISABLE_LIVE_SNIFFER, DISABLE_LIVEPLAY, Hide live play, Hide WAV play), admin privilege override warning, CALEA compliance (API-based third-party integration), and multiple GUI instances for redundancy. CRITICAL: Multiple GUI instances require the cron job to be enabled on only ONE instance; enabling it on multiple GUIs causes duplicate alerts and reports. Disable the cron job (/etc/crontab or system cron) on all secondary/redundant GUI instances.


'''Keywords:''' faq, troubleshooting, cdr, sipport, ipv6, dtmf, license, concurrent calls, aws, docker, vmware, azure, wav, ogg, vmcodecs, pci compliance, calea compliance, capture rules, gso, ethtool, custom header, invalid hwid, license key, trial license, trial token different machine, pre-generated license key, multi-server, missing database tables, schema upgrade, 1000 CDR, 1000 cdr, production database, safety mechanism, automatic schema modification, ALTER TABLE, disable_dbupgradecheck, check_tables, mariadb corruption, os upgrade, super privilege, multiple gui, cron job, duplicate alerts, crontab, secondary gui, redundant gui, external gui, DMZ gui, mysql_native_password, caching_sha2_password, natalias, auto_enable_use_blocks, dtls-srtp, ssl key logger, SIP response code colors, chart colors, VG-3031, mysql 8.0 system_user privilege, mysql 8.0.42 crash, mysql upgrade, server crashes after upgrade, wireshark, tcp sequence analysis, missing sip messages, pcap export, ipfix, license upgrade, backend discrepancy, channel limit, quality metrics, MOS, jitter, packet loss, missing quality metrics, one call leg, NAT mismatch, bad key content, license token field, savertp, packetbuffer_sender, RTP recording, Packet Mirroring mode, DISABLE_LIVE_SNIFFER, DISABLE_LIVEPLAY, live play, enable live play, hide live play, hide wav play, audio playback, play button, completely disable recording, disable live calls, disable cdr playback, admin privileges, override capture rules, configuration.php, pcap deduplication, deduplication before download, missing packets in PCAP, packet count mismatch, GUI SIP History, downloaded PCAP missing packets, retransmission, duplicate packets, import PCAP, Load PCAP GUI, truncated calls, RTP delays, new VoIPmonitor instance, configuration mirroring, sensor settings priority, gui override config, internet connectivity, network troubleshooting, cannot connect to internet, cannot download updates, gateway, firewall, outbound connections, github.com, source code, multi-leg CDR, CDR legs, un-mergeable CDR, call transfer license discrepancy, license tier, license channels, granted license, license tiers list, call legs counted separately, download failed, license server ip, ping license server, 78.24.12.71, sql_require_primary_key, managed mysql database, digitalocean, aws rds, google cloud sql, primary key error, cloud database, unable to create table without primary key, create routine failed, access denied system_user privilege, create routine store_001 failed, protocol support, SIP, Skinny, SCCP, MGCP, SS7, Diameter, RTCP, H.323 not supported, voip protocols supported, voip protocols not supported, h323 unsupported
'''Keywords:''' faq, license, hwid, concurrent calls, absolute_timeout, natalias, auto_enable_use_blocks, rtp_check_both_sides_by_sdp, vmcodecs, savertp, capture rules, multiple gui, cron duplicate alerts, admin.php check_tables, schema error, H.323 not supported, MEGACO not supported, ARM64 not supported, sipport, ipv6, dtmf, PCI compliance, CALEA


'''Key Questions:'''
'''Key Questions:'''
* How do I fix RTP packets being recorded even when savertp is set to no?
* How do I fix "Invalid or corrupted hwid" license error?
* How do I enable the live play audio feature in the GUI?
* Why does call recording stop after 4 hours?
* How do I determine the number of license channels I need?
* Why are quality metrics missing for one call leg?
* The GUI shows a "download failed" error when trying to update the license key. How do I troubleshoot this issue?
* How do I run multiple GUI instances without duplicate alerts?
* How do I ping the VoIPmonitor license server to test connectivity?
* What protocols does VoIPmonitor support (H.323? MEGACO?)?
* What is the IP address of the VoIPmonitor license server?
* How do I fix "Unknown column" database errors after upgrade?
* How do I get a trial license for VoIPmonitor?
* Can VoIPmonitor automatically detect voicemail calls?
* Can I use my license on multiple servers for a test/development environment without additional cost?
* How do I transfer my license to a new server?
* What should I do if my license has expired due to non-payment?
* I purchased a license upgrade but my server still shows the old channel limit. What should I do?
* Why are audio files not generated for non-G.711 codecs?
* Why is audio playback garbled or distorted?
* Why is audio playback garbled or distorted?
* How do I fix "bad gso" kernel errors?
* Why are quality metrics (MOS, jitter, packet loss) missing for one call leg?
* Why are call durations truncated and RTP streams delayed after importing PCAP files into a new VoIPmonitor instance?
* How do I fix truncated calls and RTP delays when importing PCAP files?
* How do I configure natalias for PCAP imports?
* How do I disable audio recording for PCI compliance?
* How do I disable audio recording for PCI compliance?
* How do I completely disable live call monitoring and CDR audio playback?
* Does VoIPmonitor GUI run on ARM64?
* Are third-party vendors available for CALEA integration?
* How can I export data to third-party CALEA systems?
* Can wildcards be used in domain-based capture rules?
* When connecting a new VoIPmonitor sensor to an existing production database with many CDRs, will it automatically alter the database schema?
* What is the database schema upgrade safety mechanism for production databases?
* How do I check for logged ALTER TABLE queries when connecting a new sensor to a production database?
* How do I fix missing database tables errors?
* How do I fix MariaDB errors after OS upgrade?
* How do I fix VoIPmonitor server crashes after MySQL upgrade?
* How do I fix MySQL 8.0 SYSTEM_USER privilege error?
* VoIPmonitor sniffer fails to start or connect to the database, with logs showing errors like 'create routine store_001 failed' and 'Access denied; you need (at least one of) the SYSTEM_USER privilege(s) for this operation'. This occurs on MySQL 8.0 even if the user has been granted SUPER and ALL PRIVILEGES. How do I fix this?
* Using a managed MySQL database (e.g. DigitalOcean, AWS RDS, Google Cloud SQL), VoIPmonitor cannot create tables and reports errors about tables being created without primary keys. How do I fix this?
* How do I disable sql_require_primary_key in a managed MySQL database?
* Why are CDRs not being saved to the database when using a DigitalOcean managed MySQL database?
* How do I fix 'unable to create a table without a primary key' errors in MySQL?
* How do I fix 'Unknown column' errors in the GUI?
* Can I run multiple GUI instances for redundancy?
* What happens if I enable cron jobs on multiple GUI instances?
* How do I prevent duplicate alerts when running multiple GUI instances?
* Why are RTP packets not associated with correct call legs after network changes?
* Why does the downloaded PCAP file have fewer packets than shown in the GUI SIP History?
* How do I disable Pcap deduplication before download to include all packets in downloaded PCAP?
* Why do I see missing SIP messages in Wireshark when viewing exported PCAP files?
* Why do the colors for SIP response codes in dashboard graphs change automatically?
* Why might my granted license channel count be higher than what I requested?
* What are the available commercial license tiers?

Latest revision as of 11:21, 13 January 2026


Quick answers to frequently asked questions. For detailed troubleshooting, see Sniffer Troubleshooting and GUI Troubleshooting.

Quick Navigation

General Configuration Licensing Audio & Files

General & Architecture

How does VoIPmonitor scale for high traffic?
For hardware recommendations and optimization of CPU, Disk I/O, and Database bottlenecks, see Scaling and Performance Tuning.
How do I manage disk space and database retention?
See Data Cleaning and Retention for PCAP cleanup (cleanspool) and CDR retention settings.
Can I run multiple GUI instances for redundancy?
Yes. Requirements:
  • All GUIs connect to the same database
  • PCAP storage accessible via NFS/SSHFS
  • Same key.php license file on each GUI

⚠️ Warning: CRITICAL: Enable the cron job on only ONE GUI instance. Multiple active cron jobs cause duplicate alerts and reports. 

# Disable on secondary GUIs:
# * * * * * root php /var/www/html/php/run.php cron
Can one GUI display data from multiple sensors?
Yes. Use the Client-Server architecture (v20+):
  • Local Processing (packetbuffer_sender=no): Sensors analyze locally, send CDRs only
  • Packet Mirroring (packetbuffer_sender=yes): Sensors forward raw packets to central server
See Distributed Architecture for full configuration.

Platform Support

What architectures are supported?
Component Supported Notes
Sensor x86 (32/64-bit), ARMv7/v8 Compile from source for ARM64
GUI x86 only Not supported on ARM64/aarch64
Can I run VoIPmonitor on AWS?
Yes. For license detection: chmod 644 /dev/root
  • Stop/Start instance: HWID usually preserved
  • Terminate/Launch new: HWID changes, requires new license key
Is Docker supported?
Yes, but ensure /proc/self/cgroup content doesn't change between restarts (affects HWID stability).
Are cloud databases (RDS, Azure) supported?
Yes. Requires MySQL-compatible database with SUPER privilege. If unavailable, set:
log_bin_trust_function_creators = ON
Why is mysql_native_password deprecated?
PHP 7.4.4+ supports caching_sha2_password natively. Upgrade PHP and reinstall IonCube Loader. See GUI Installation.

CDR View

What does the red icon mean?
Indicates which party sent the BYE message (ended the call).
How do I filter with regular expressions?
Prefix with R(). Example: R(^500[0-9]{4}$)
How do I exclude values from filters?
Use ! prefix:
  • !123456 – exclude specific number
  • !00420% – exclude prefix
  • 222%, !223% – include 222*, exclude 223*
How do I search multi-word strings in custom headers?
Use underscore for spaces: %normal_call_clearing%
Why are caller/called numbers swapped?
VoIPmonitor extracts from SIP headers (From/To). Check destination_number_mode setting. See CDR Documentation.
Why is there a delay before CDRs appear?
Database can't keep up. See SQL Queue Troubleshooting.

Protocols & Ports

Which protocols are supported?
Supported Not Supported
SIP, Skinny/SCCP, MGCP, SS7/ISUP, Diameter, RTCP H.323, MEGACO/H.248
Why don't I see SIP on ports other than 5060?
Configure additional ports in voipmonitor.conf:
sipport = 5060,5080,8088,8089
See sipport configuration.
How do I enable IPv6?
Set ipv6=yes in config. Existing databases require migration. See IPv6 Guide.
How do I capture REGISTER messages?
Set sip-register=yes. See REGISTER Monitoring.
How do I capture DTMF?
dtmf2db = yes           # RFC2833 and SIP INFO
inbanddtmf = yes        # G.711 only, CPU intensive

RTP & Quality Metrics

Why are quality metrics (MOS, jitter) missing for one call leg?
Usually NAT mismatch – SDP announces different IP than actual RTP source.
Solution: Configure natalias mapping:
# Map public IP to private IP
natalias = 1.2.3.4 10.0.0.100
See NAT Configuration for details.
Why is RTP not correctly associated after moving SIP/RTP to different NICs?
Enable memory blocks for multi-interface scenarios:
auto_enable_use_blocks = yes
Why do recordings mix audio from different calls?
Enable SDP verification on both sides:
rtp_check_both_sides_by_sdp = yes

Licensing

How are license channels calculated?
Based on maximum concurrent calls (averaged hourly, checked daily). View in Tools → System Status → Concurrent calls.
  • Calls are deduplicated if last 6 digits of caller/called match within ±10 seconds
  • 487 Request Terminated responses are NOT counted
What happens if I exceed my limit?
Duration Effect
1-2 days Warning only, self-clearing
3+ consecutive days GUI blocked
How do I unblock a locked GUI?
In Settings > License, click get/update license key – this grants a temporary increase automatically.
I get "Invalid or corrupted hwid" error. What do I do?
Common causes:
  1. Incomplete key: Copy the entire multi-line license key, not just the first line
  2. Wrong field: Use "License token" for short tokens, "License key" for full multi-line keys
  3. AWS: Run chmod 644 /dev/root
  4. Docker: Ensure container ID doesn't change on restart
  5. Trial on different machine: Contact support for a pre-generated key
I get "license file key.php is for another hwid" after hardware change?
In Settings > License, click get/update license key then recheck to fetch new key for current HWID.
I get "Bad Key Content" error?
You're using the wrong field. Short tokens go in "License token" field, then click "get/update license key".
How do I transfer a license to a new server?
  1. Get token from old GUI (Settings > License) or customer portal
  2. On new GUI: paste token, click get/update license key
  3. IMPORTANT: Disable cron on old server to prevent conflicts
Can I use one license on multiple servers (test/dev)?
Yes. Contact support to reconfigure your token for multiple HWIDs.
What are the available license tiers?
10, 35, 50, 100, 150, 200, 350, 500, 750, 1000, 1250, 1500, 1750, 2000

Audio & PCAP Files

Why does call recording stop after exactly 4 hours?
Default absolute_timeout = 14400 (4 hours). Increase or disable:
absolute_timeout = 43200   # 12 hours
# absolute_timeout = 0     # Unlimited (watch memory usage)
Why are WAV files missing for non-G.711 codecs (Opus, G.729)?
Requires vmcodecs binary from GUI package. Install GUI, then restart sensor.
Why is audio playback garbled?
DTLS-SRTP encryption. Configure SSL Key Logger for decryption. See TLS/SRTP Decryption.
Why can't I download PCAP files?
Files deleted by retention limits. Check:
grep maxpoolsize /etc/voipmonitor.conf
grep maxpooldays /etc/voipmonitor.conf
Increase limits and restart. See Data Cleaning.
Why does downloaded PCAP have fewer packets than GUI shows?
Pcap deduplication before download is enabled. Disable in Settings > System Configuration > Advanced.
How do I bulk download audio/PCAP files?
Use GUI API. See Bulk Download Guide.
Can VoIPmonitor detect voicemail calls?
No automatic detection by analyzing RTP audio. Workarounds:
  • Filter by voicemail pilot number
  • Track SIP 302 redirects (save_sip_history = all)
  • Capture custom SIP headers your PBX adds
How do I convert WAV to OGG?
cd /var/spool/voipmonitor
find ./ -name '*.wav' -exec bash -c 'ffmpeg -i "$0" -vn -acodec libvorbis "${0%.wav}.ogg"' {} \;
find ./ -name '*.wav' -exec rm -f {} \;
chown -R www-data:www-data ./
How do I enable live call listening?
Edit configuration.php:
define('DISABLE_LIVEPLAY', false);
See GUI Configuration for details.
Why is transfer throughput to external storage (S3, CloudBerry) limited?
VoIPmonitor does not impose speed limits on external storage transfers. If you see artificial throughput caps (e.g., 40 Mbps):
  1. Verify bandwidth from your host to the internet is sufficient
  2. Check third-party tool configuration (e.g., CloudBerry, s3fs, rclone) - the bottleneck is typically in these tools, not VoIPmonitor
  3. For controlled bandwidth limiting, use rsync via cron job with --bwlimit or the tar_move option - both allow bandwidth management

Administration

How do I reset admin password?
See User Management.
How do I fix GUI after PHP/OS upgrade?
Re-run installation. See Re-install GUI.
How do I enable debug mode?
Add ?debug=31415 to URL. See GUI Debug Mode.
How do I fix "Unknown column" errors after database upgrade?
Access: https://your-gui/admin.php?check_tables=1

ℹ️ Note: Do NOT use "Check MySQL Schema" button in Tools - that's for millisecond precision only.

Can I run multiple sensor instances on one host?
Yes. See Multiple Instances Guide.
Users from the same organization cannot view each other's support tickets. How can we share access?
Support tickets are associated with individual email addresses. To enable team-wide ticket visibility, merge all user accounts under a single main email address. Contact VoIPmonitor support to consolidate multiple accounts into one organization account.

Compliance

PCI Compliance

How do I disable audio recording?
savertp = header    # Headers only, no audio
savertp = no        # No RTP at all
dtmf2db = no        # No DTMF to database
dtmf2pcap = no      # No DTMF to PCAP
How do I selectively record calls?
Use Capture Rules to enable/disable recording based on IP, number, or SIP headers.
How do I disable live listening?
  • Settings > System Configuration > Advanced: Enable "Hide live play" and "Hide WAV play"
  • Edit configuration.php: define('DISABLE_LIVEPLAY', true);
  • Edit config/system_configuration.php: define('DISABLE_LIVE_SNIFFER', true);

ℹ️ Note: Understanding audio in VoIPmonitor: By default, the GUI extracts audio on-demand from stored RTP packets in PCAP files (when savertp = yes). The saveaudio option creates pre-generated audio files and is NOT required for audio playback. Setting savertp = header disables audio playback because RTP payload is not stored. See Audio Playback vs Pre-Generated Files for details.

CALEA Compliance

How do I export data to CALEA systems?
Use GUI API methods getPCAP and getVoiceRecording. See CALEA Integration Guide.

See Also





AI Summary for RAG

Summary: VoIPmonitor FAQ organized by topic. General: scaling (link to Scaling page), multiple GUI instances (requires same DB, NFS storage, single cron job to prevent duplicate alerts), client-server architecture for multi-sensor. Platform: x86 required for GUI (ARM64 not supported), AWS/Docker/cloud DB supported. CDR: regex filters with R() prefix, exclusion with ! prefix, underscore for multi-word search. Protocols: SIP, Skinny/SCCP, MGCP, SS7, Diameter supported; H.323 and MEGACO NOT supported. RTP: natalias for NAT mismatch causing missing quality metrics, auto_enable_use_blocks for multi-interface, rtp_check_both_sides_by_sdp for mixed audio. Licensing: concurrent calls averaged hourly, 3+ consecutive days over limit locks GUI, get/update button for temporary increase, common HWID errors (incomplete key, wrong field, AWS chmod, Docker cgroup). Audio: absolute_timeout default 4 hours (14400s), vmcodecs needed for non-G.711, DTLS-SRTP causes garbled audio. Admin: admin.php?check_tables=1 for schema errors after DB upgrade. Compliance: savertp=header/no for PCI, capture rules for selective recording, DISABLE_LIVEPLAY for hiding playback.

Keywords: faq, license, hwid, concurrent calls, absolute_timeout, natalias, auto_enable_use_blocks, rtp_check_both_sides_by_sdp, vmcodecs, savertp, capture rules, multiple gui, cron duplicate alerts, admin.php check_tables, schema error, H.323 not supported, MEGACO not supported, ARM64 not supported, sipport, ipv6, dtmf, PCI compliance, CALEA

Key Questions:

  • How do I fix "Invalid or corrupted hwid" license error?
  • Why does call recording stop after 4 hours?
  • Why are quality metrics missing for one call leg?
  • How do I run multiple GUI instances without duplicate alerts?
  • What protocols does VoIPmonitor support (H.323? MEGACO?)?
  • How do I fix "Unknown column" database errors after upgrade?
  • Can VoIPmonitor automatically detect voicemail calls?
  • How do I transfer my license to a new server?
  • Why is audio playback garbled or distorted?
  • How do I disable audio recording for PCI compliance?
  • Does VoIPmonitor GUI run on ARM64?
Retrieved from "https://www.voipmonitor.org/doc/index.php?title=FAQ&oldid=10684"