FAQ: Difference between revisions

From VoIPmonitor.org
(Add Q&A about domain-based capture rule wildcards/regex support)
(Add clarification about on-demand audio extraction vs saveaudio option)
 
(130 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]]
| 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]]
* [[Capture_rules|Capture Rules]]
* [[#Compliance|PCI/CALEA]]
|}
|}


== 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 retention?
:See [[Data_Cleaning|Data Cleaning and Retention]] for PCAP cleanup (cleanspool) and CDR retention settings.


;How do I manage disk space and database size?
;Can I run multiple GUI instances for redundancy?
: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]].
:Yes. Requirements:
:* All GUIs connect to the same database
:* PCAP storage accessible via NFS/SSHFS
:* Same <code>key.php</code> license file on each GUI


== CDR (Call Detail Record) View ==
:{{Warning|1='''CRITICAL:''' Enable the cron job on '''only ONE''' GUI instance. Multiple active cron jobs cause duplicate alerts and reports.}}
:<syntaxhighlight lang="bash"># Disable on secondary GUIs:
# * * * * * root php /var/www/html/php/run.php cron</syntaxhighlight>


;What does the small red icon in the CDR view mean?
;Can one GUI display data from multiple sensors?
:The red icon ([[File:Cdrcolumnsredflag.png]]) indicates which party in the call sent the <code>BYE</code> message first, effectively ending the call.
: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.


;How can I use regular expressions to filter calls?
== Platform Support ==
: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>
;What architectures are supported?
:{| class="wikitable"
|-
! Component !! Supported !! Notes
|-
| Sensor || x86 (32/64-bit), ARMv7/v8 || Compile from source for ARM64
|-
| GUI || x86 only || '''Not supported''' on ARM64/aarch64
|}


;Why is there a delay between when a call ends and when it appears in the CDR view?
;Can I run VoIPmonitor on AWS?
: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:
:Yes. For license detection: <code>chmod 644 /dev/root</code>
:* [[SQL queue is growing in a peaktime]]
:* '''Stop/Start instance:''' HWID usually preserved
:* [[Minimizing Delay Between Call End and CDR Database Storage]]
:* '''Terminate/Launch new:''' HWID changes, requires new license key


;How can I enable millisecond precision for timestamps in the CDR view?
;Is Docker supported?
:By default, timestamps are stored with second precision. To enable millisecond precision, please follow the steps in this guide: [[How_to_enable_milliseconds_precision]].
:Yes, but ensure <code>/proc/self/cgroup</code> content doesn't change between restarts (affects HWID stability).


;How do I search for multi-word strings in custom header fields?
;Are cloud databases (RDS, Azure) supported?
: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.
:Yes. Requires MySQL-compatible database with <code>SUPER</code> privilege. If unavailable, set:
:<syntaxhighlight lang="ini">log_bin_trust_function_creators = ON</syntaxhighlight>


:'''Example:''' To search for "Normal Call Clearing", use:
;Why is mysql_native_password deprecated?
:<code>%normal_call_clearing%</code>
:PHP 7.4.4+ supports <code>caching_sha2_password</code> natively. Upgrade PHP and reinstall IonCube Loader. See [[GUI_installation|GUI Installation]].


: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.
== CDR View ==


;Can I generate a report of concurrent calls broken down by individual source IP address?
;What does the red icon mean?
: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.
:Indicates which party sent the <code>BYE</code> message (ended the call).


:'''Workarounds:'''
;How do I filter with regular expressions?
:* Use the [[Reports|Call Summary]] report to see aggregate call statistics per IP (total calls, duration, etc.)
:Prefix with <code>R()</code>. Example: <code>R(^500[0-9]{4}$)</code>
:* 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


== Platform & Environment Support ==
;How do I exclude values from filters?
:Use <code>!</code> prefix:
:* <code>!123456</code> – exclude specific number
:* <code>!00420%</code> – exclude prefix
:* <code>222%, !223%</code> – include 222*, exclude 223*


;What hardware architectures does the sensor support?
;How do I search multi-word strings in custom headers?
: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.
:Use underscore for spaces: <code>%normal_call_clearing%</code>


;Can I run VoIPmonitor on AWS?
;Why are caller/called numbers swapped?
: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:
: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]].
:<syntaxhighlight lang="bash">chmod 644 /dev/root</syntaxhighlight>


;Is Docker or other container environments supported?
;Why is there a delay before CDRs appear?
: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.
:Database can't keep up. See [[Database_troubleshooting#SQL_Queue_and_CDR_Delays|SQL Queue Troubleshooting]].


;Are hosted/cloud databases (like Amazon RDS, Azure Database) supported?
== Protocols & Ports ==
: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?
;Which protocols are supported?
:If <code>SUPER</code> privilege is not available, you must manually set the following server variable in your cloud database configuration console:
:{| class="wikitable"
:<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).
! 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 <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]].


;Why is packet mirroring not working on VMWare ESXi 6.5+?
;How do I capture REGISTER messages?
: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.
:Set <code>sip-register=yes</code>. See [[Register|REGISTER Monitoring]].
:'''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 ==
;How do I capture DTMF?
:<syntaxhighlight lang="ini">dtmf2db = yes          # RFC2833 and SIP INFO
inbanddtmf = yes        # G.711 only, CPU intensive</syntaxhighlight>


;Why don't I see SIP packets on ports other than 5060?
== RTP & Quality Metrics ==
: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?
;Why are quality metrics (MOS, jitter) missing for one call leg?
: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]].
:Usually NAT mismatch – SDP announces different IP than actual RTP source.


;How do I capture and view SIP REGISTER messages?
:'''Solution:''' Configure <code>natalias</code> mapping:
: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]].
:<syntaxhighlight lang="ini"># Map public IP to private IP
natalias = 1.2.3.4 10.0.0.100</syntaxhighlight>


;How can I capture DTMF tones?
:See [[Sniffer_configuration#NAT|NAT Configuration]] for details.
: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>


;How can I use the sensor's manager API securely?
;Why is RTP not correctly associated after moving SIP/RTP to different NICs?
: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.
:Enable memory blocks for multi-interface scenarios:
:<syntaxhighlight lang="ini">auto_enable_use_blocks = yes</syntaxhighlight>


;How does VoIPmonitor handle AudioCodes-tunneled traffic?
;Why do recordings mix audio from different calls?
:VoIPmonitor can process traffic encapsulated in AudioCodes' proprietary tunneling protocol. For setup details, see the [[audiocodes_tunneling|AudioCodes Tunneling guide]].
:Enable SDP verification on both sides:
:<syntaxhighlight lang="ini">rtp_check_both_sides_by_sdp = yes</syntaxhighlight>


;Can wildcards or regular expressions be used in domain-based capture rules?
== Licensing ==
: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:
;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


{| class="wikitable"
;What happens if I exceed my limit?
:{| class="wikitable"
|-
|-
! Rule Type !! Matching Supported !! Example
! Duration !! Effect
|-
|-
| '''IP Addresses''' || CIDR subnet masks (wildcard networks) || <code>1.2.3.0/24</code> matches all IPs in that range
| 1-2 days || Warning only, self-clearing
|-
|-
| '''Telephone Numbers''' || Prefix matching (equivalent to wildcard) || <code>4420</code> matches <code>4420*</code>
| 3+ consecutive days || GUI blocked
|-
| '''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.
;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:'''
:# '''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


== Licensing ==
;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.


;How do I determine the number of license channels I need?
;I get "Bad Key Content" error?
:The license is based on the '''maximum number of concurrent calls''' during your peak hours. It is not based on the number of phones or endpoints. You can find your peak usage by navigating in the GUI to '''Tools → System Status → Concurrent calls''', which shows data for the past 14 days. The system intelligently groups multiple call legs (e.g., for a single bridged call) so they only count as one channel towards your license.
:You're using the wrong field. Short tokens go in "License token" field, then click "get/update license key".


;What happens if my call volume temporarily exceeds my license limit?
;How do I transfer a license to a new server?
:'''Important:''' The license alert is temporary and self-clearing.
:# Get token from old GUI ('''Settings > License''') or customer portal
: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.
:# On new GUI: paste token, click '''get/update license key'''
:# '''IMPORTANT:''' Disable cron on old server to prevent conflicts


;When does the GUI become locked?
;Can I use one license on multiple servers (test/dev)?
:The GUI only becomes fully locked if the license limit is exceeded for '''three or more consecutive days'''.
:Yes. Contact support to reconfigure your token for multiple HWIDs.


;What happens if I exceed my license for three consecutive days?
;What are the available license tiers?
:If high usage persists for three consecutive days within the 14-day grace period, the license will be temporarily blocked. To resolve this, you must either:
:10, 35, 50, 100, 150, 200, 350, 500, 750, 1000, 1250, 1500, 1750, 2000
:# 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.


== Audio & PCAP Files ==
== Audio & PCAP Files ==


;How can I bulk download audio or PCAP files?
;Why does call recording stop after exactly 4 hours?
: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]].
:Default <code>absolute_timeout = 14400</code> (4 hours). Increase or disable:
:<syntaxhighlight lang="ini">absolute_timeout = 43200  # 12 hours
# absolute_timeout = 0    # Unlimited (watch memory usage)</syntaxhighlight>


;Why does the GUI download button download the entire merged PCAP instead of only the filtered packets?
;Why are WAV files missing for non-G.711 codecs (Opus, G.729)?
: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.
:Requires <code>vmcodecs</code> binary from GUI package. Install GUI, then restart sensor.


:'''Workarounds:'''
;Why is audio playback garbled?
:* 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.
:DTLS-SRTP encryption. Configure SSL Key Logger for decryption. See [[Tls|TLS/SRTP Decryption]].
:* 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 .wav audio files not generated for calls using non-G.711 codecs (e.g., Opus, G.729)?
;Why can't I download PCAP files?
: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.
:Files deleted by retention limits. Check:
:<syntaxhighlight lang="bash">grep maxpoolsize /etc/voipmonitor.conf
grep maxpooldays /etc/voipmonitor.conf</syntaxhighlight>
:Increase limits and restart. See [[Data_Cleaning|Data Cleaning]].


: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.
;Why does downloaded PCAP have fewer packets than GUI shows?
:'''Pcap deduplication before download''' is enabled. Disable in '''Settings > System Configuration > Advanced'''.


:'''To resolve this issue:'''
;How do I bulk download audio/PCAP files?
:# '''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>.
:Use GUI API. See [[download_of_pcap_files_audio_files_using_GUI's_api|Bulk Download Guide]].
:# '''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.
:# '''Restart the sensor''' after installing the GUI to apply the changes.
:# '''For existing .raw files''': Re-process the spooldir content after GUI installation to generate the missing audio files.


:'''Note:''' Your license key must include support for the specific codec (e.g., Opus Codec Pack) for transcoding to work. Free licenses typically only support G.711.
;Can VoIPmonitor detect voicemail calls?
:'''No automatic detection''' by analyzing RTP audio. Workarounds:
:* Filter by voicemail pilot number
:* Track SIP 302 redirects (<code>save_sip_history = all</code>)
:* Capture custom SIP headers your PBX adds


;How do I convert existing WAV audio files to OGG to save space?
;How do I convert WAV to OGG?
: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">cd /var/spool/voipmonitor
 
<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 ==


== Administration & Troubleshooting ==
;How do I reset admin password?
:See [[User_Management|User Management]].


;How do I fix "bad gso: type: 1, size: 1448" or kernel errors related to network offloading?
;How do I fix GUI after PHP/OS upgrade?
: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.
:Re-run installation. See [[Re-install_the_GUI|Re-install GUI]].


:'''Symptoms:'''
;How do I enable debug mode?
:* Kernel messages like: <code>ens3: bad gso: type: 1, size: 1448</code>
:Add <code>?debug=31415</code> to URL. See [[GUI_troubleshooting#GUI_Debug_Mode|GUI Debug Mode]].
:* Errors may mention UDP Fragmentation Offload (UFO)
:* Packet capture issues during VoIPmonitor operation


:'''Solution:''' Disable the offload features on the affected interface:
;How do I fix "Unknown column" errors after database upgrade?
<syntaxhighlight lang="bash">
:Access: <code>https://your-gui/admin.php?check_tables=1</code>
# Check MTU (should be > 1448, typically 1500)
:{{Note|1=Do NOT use "Check MySQL Schema" button in Tools - that's for millisecond precision only.}}
ip addr show eth0


# Disable offload features (replace ens3 with your interface name)
;Can I run multiple sensor instances on one host?
ethtool -K ens3 gso off tso off gro off lro off
: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 ==


# Verify the change persists (check kernel logs)
=== PCI Compliance ===
dmesg -T | grep -i gso
</syntaxhighlight>


:To make changes '''persistent across reboots''', create a systemd service:
;How do I disable audio recording?
<syntaxhighlight lang="ini">
:<syntaxhighlight lang="ini">savertp = header    # Headers only, no audio
# /etc/systemd/system/disable-offload.service
savertp = no        # No RTP at all
[Unit]
dtmf2db = no        # No DTMF to database
Description=Disable network offloads for VoIPmonitor
dtmf2pcap = no      # No DTMF to PCAP</syntaxhighlight>
After=network.target


[Service]
;How do I selectively record calls?
Type=oneshot
:Use [[Capture_rules|Capture Rules]] to enable/disable recording based on IP, number, or SIP headers.
ExecStart=/usr/sbin/ethtool -K ens3 gso off tso off gro off lro off


[Install]
;How do I disable live listening?
WantedBy=multi-user.target
:* '''Settings > System Configuration > Advanced:''' Enable "Hide live play" and "Hide WAV play"
</syntaxhighlight>
:* 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="bash">
;How do I export data to CALEA systems?
# Enable and start the service
:Use GUI API methods <code>getPCAP</code> and <code>getVoiceRecording</code>. See [[CALEA_compliance|CALEA Integration Guide]].
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.
== See Also ==


;How do I reset a lost admin password for the GUI?
* [[Sniffer_troubleshooting|Sniffer Troubleshooting]] - packet capture, missing CDRs
:Please follow the instructions in the [[User_Management|User Management guide]].
* [[GUI_troubleshooting|GUI Troubleshooting]] - HTTP 500, database issues
* [[Sniffer_configuration|Sniffer Configuration Reference]]
* [[License|Licensing Details]]
* [[Data_Cleaning|Data Cleaning and Retention]]


;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]].


== 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.
== AI Summary for RAG ==
 
;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?
'''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.
: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.
 
== AI Summary for RAG ==
'''Summary:''' Comprehensive FAQ covering VoIPmonitor configuration and troubleshooting. Topics include: CDR analysis (delay causes, regex filters, custom header search with underscore wildcards), platform support (AWS, Docker, VMWare ESXi VLAN 4095 fix, Azure cloud databases), configuration (SIP ports, IPv6, DTMF, REGISTER messages), licensing (concurrent channels, temporary warnings, 3-day lock), audio/PCAP files (bulk download, WAV-to-OGG conversion, vmcodecs requirement for non-G.711 codecs), and PCI compliance (selective recording via capture rules).


'''Keywords:''' faq, troubleshooting, cdr, sipport, ipv6, dtmf, license, concurrent calls, aws, docker, vmware, azure, wav, ogg, vmcodecs, pci compliance, capture rules, gso, ethtool, custom header
'''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:'''
* Why is there a delay between call end and CDR appearance?
* How do I fix "Invalid or corrupted hwid" license error?
* How is VoIPmonitor licensing calculated?
* Why does call recording stop after 4 hours?
* What happens if I exceed my license limit?
* Why are quality metrics missing for one call leg?
* Why are audio files not generated for non-G.711 codecs?
* How do I run multiple GUI instances without duplicate alerts?
* How do I fix "bad gso" kernel errors?
* What protocols does VoIPmonitor support (H.323? MEGACO?)?
* How do I search for multi-word strings in custom headers?
* 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?
* How do I disable audio recording for PCI compliance?
* Does VoIPmonitor GUI run on ARM64?

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"