Settings: Difference between revisions

From VoIPmonitor.org
(Add troubleshooting for sensors that cannot be deleted due to capture rules (most common deletion error))
(Add Security Settings documentation for CSRF and POST method protection (VG-3065))
 
(22 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{DISPLAYTITLE:GUI Settings Reference}}
{{DISPLAYTITLE:GUI Settings Reference}}
Category:GUI manual
[[Category:GUI manual]]


This page documents the configuration options available in the VoIPmonitor web GUI under the '''Settings''' menu. These settings control how the GUI interacts with sensors, displays data, and manages user preferences.
This page documents the configuration options available in the VoIPmonitor web GUI under the '''Settings''' menu.


== Sensors ==
= Sensors =


If <code>id_sensor</code> is set in <code>/etc/voipmonitor.conf</code> (default is blank), you must create sensor entries here to enable downloading files like PCAP, graphs, and WAV recordings from the GUI.
Configure sensor connections for multi-sensor deployments. Required when <code>id_sensor</code> is set in <code>/etc/voipmonitor.conf</code>.


{| class="wikitable"
{| class="wikitable"
Line 12: Line 12:
! Field !! Description
! Field !! Description
|-
|-
| Sensor ID || The numeric ID matching <code>id_sensor = N</code> in <code>voipmonitor.conf</code>
| Sensor ID || Numeric ID matching <code>id_sensor</code> in voipmonitor.conf
|-
|-
| Name || A descriptive name for the sensor
| Name || Descriptive name for the sensor
|-
|-
| Manager IP || IP address of the sensor for fetching data (PCAP, graph, audio files)
| Manager IP || IP address (or hostname) for fetching data (PCAP, audio files)
|-
|-
| Manager Port || TCP port for the manager API (default: 5029)
| Manager Port || TCP port for manager API (default: 5029)
|-
|-
| Remote database || Database connection parameters for "Legs by CID/header" lookups when sensors use different databases. Leave blank if all sensors share the same database.
| Remote database || Database connection for "Legs by CID/header" lookups when sensors use different databases
|}
|}


[[File:settings-sensors.png]]
== Multi-Sensor Deployment ==


=== Configuring Sensors for Multi-Sensor Deployments ===
<kroki lang="mermaid">
%%{init: {'flowchart': {'nodeSpacing': 15, 'rankSpacing': 40}}}%%
flowchart TB
    subgraph Sensors["Remote Sensors"]
        S1["Sensor A<br/>id_sensor=2"]
        S2["Sensor B<br/>id_sensor=3"]
    end
    subgraph Central["Central Server"]
        GUI["Web GUI"]
        DB[(MySQL)]
    end
    S1 -->|CDR| DB
    S2 -->|CDR| DB
    GUI -->|"Port 5029"| S1
    GUI -->|"Port 5029"| S2
</kroki>


When multiple VoIPmonitor instances (sniffers) feed data to a single GUI, you must configure unique sensor IDs to identify which specific instance processed a given CDR.
'''Setup:'''


'''Workflow:'''
# Set unique <code>id_sensor</code> in each sensor's <code>/etc/voipmonitor.conf</code>
# Add sensor entries in '''Settings > Sensors''' with matching Sensor ID
# Restart sensors: <code>systemctl restart voipmonitor</code>


# On each sniffer instance, edit <code>/etc/voipmonitor.conf</code> and set a unique <code>id_sensor</code> value (e.g., 1, 2, 3...):
{{Tip|For sensors with dynamic IPs, enter a hostname in the Manager IP field, or use [[Sniffer_distributed_architecture|Client-Server mode]].}}
<syntaxhighlight lang="ini">
# On Sensor A
id_sensor = 2
 
# On Sensor B
id_sensor = 3
</syntaxhighlight>
 
# In the GUI, navigate to '''Settings > Sensors''' and add a sensor entry for each instance with the following fields:
** Sensor ID: The numeric ID matching <code>id_sensor</code> in voipmonitor.conf
** Name: A descriptive name for the sensor
** Manager IP: IP address of the sensor for fetching data (PCAP, graph, audio files)
** Manager Port: TCP port for the manager API (default: 5029)
 
'''Restart the sniffer service''' on each instance to apply the changes:
<syntaxhighlight lang="bash">
# On each sensor machine
systemctl restart voipmonitor
</syntaxhighlight>
 
Newly captured CDRs will now display the source sensor ID in the GUI. The <code>id_sensor</code> is stored in the <code>cdr.id_sensor</code> database column, allowing you to filter and identify which sniffer processed each call.
 
=== SSL/TLS Configuration ===
 
Sensors can be configured to decrypt TLS-encrypted SIP traffic directly through the GUI. This is particularly useful when VoIPmonitor is not capturing all SIP traffic from specific TLS trunks (e.g., seeing only OPTIONS and 403 responses while INVITEs are missing).


To configure SSL/TLS settings for a sensor:
== Sensor Configuration via Wrench Icon ==


# Navigate to '''Settings > Sensors'''
Click the '''wrench icon''' next to a sensor to configure parameters. Use the search field to find settings.
# Click the '''wrench icon''' next to the affected sensor
# In the search field at the top right of the sensor settings dialog, enter '''ssl_'''
# Configure the required SSL/TLS parameters:


{| class="wikitable"
{| class="wikitable"
|-
|-
! Parameter !! Description !! Example Value
! Parameter !! Description !! Values
|-
| <code>ssl</code> || Enable TLS decryption || <code>yes</code> / <code>no</code>
|-
|-
| ssl_key || Path to the private key file (PEM format) for decrypting TLS traffic || <code>/etc/pki/tls/private/server.key</code>
| <code>ssl_ipport</code> || IP:port and key path for TLS || <code>192.168.1.10:5061 /path/to/key.pem</code>
|-
|-
| ssl_cert || Path to the SSL certificate file (PEM format) matching the private key || <code>/etc/pki/tls/certs/server.crt</code>
| <code>sipport</code> || SIP ports to capture || <code>5060,5080</code> or <code>5060,5070-5080</code>
|-
|-
| ssl_ipport || IP address and TLS port of the SIP endpoint to decrypt (without key file path for SSL Key Logger mode, or <code>IP:port /path/to/key</code> for Private Key mode) || <code>192.168.1.10:5061</code>
| <code>savertp</code> || RTP recording mode || <code>yes</code> (full), <code>no</code> (none), <code>header</code> (stats only)
|-
|-
| ssl || Enable SSL/TLS decryption module on the sensor || <code>yes</code>
| <code>maxpoolrtpsize</code> || Max RTP storage in MB || <code>51200</code>
|-
| <code>maxpoolrtpdays</code> || Max RTP age in days || <code>30</code>
|}
|}


'''Important Notes:'''
{{Warning|1=GUI settings override <code>voipmonitor.conf</code> when <code>mysqlloadconfig</code> is enabled (default). Changes require a full restart (<code>systemctl stop/start</code>), not reload.}}


* The sensor SSL settings correspond to the configuration parameters in [[Tls|/etc/voipmonitor.conf]] but are managed through the GUI interface
For TLS decryption with PFS ciphers, see [[Tls|TLS Decryption Guide]].
* This is an alternative to editing <code>voipmonitor.conf</code> directly - the GUI applies these settings to the sensor
* After changing SSL settings, you may need to '''restart the sniffer service''' or use the '''"reload sniffer"''' button in the GUI control panel
* '''Important Warning for Sensor Configuration Changes:''' When modifying sensor-level settings (especially parameters loaded via <code>mysqlloadconfig</code> such as <code>dtmf2db</code>, <code>dtmf2pcap</code>, or other sensor options), '''perform a manual restart instead of using reload'''. A reload may leave the sniffer in an inconsistent state with some processes holding old configuration values. To safely apply sensor configuration changes:


<syntaxhighlight lang="bash">
== RRD Health Charts ==
# Stop the sensor service
systemctl stop voipmonitor


# Check for remaining processes (kill if any)
Click the '''chart icon''' next to a sensor to view performance metrics:
ps ax | grep voipmonitor


# Start the sensor service
* '''Buffer usage:''' Approaching 100% indicates capacity limits
systemctl start voipmonitor
* '''Packet drops:''' Non-zero values indicate sensor overload
</syntaxhighlight>
* For decryption of traffic using Perfect Forward Secrecy (PFS) ciphers like Diffie-Hellman (DHE/ECDHE), see [[Tls|the TLS decryption guide]] for the SSL Key Logger method


'''When to use GUI SSL configuration:'''
{{Note|High buffer/drops cause low MOS and choppy audio. Solutions: increase <code>ringbuffer</code> in config, add sensors, use [[DPDK]] or [[Napatech]].}}


* You prefer managing TLS/SSL settings through the web interface instead of editing config files
== Disabling a Sensor ==
* You have multiple sensors and want to manage SSL keys centrally
* You need to quickly enable/disable TLS decryption without editing <code>voipmonitor.conf</code>


For detailed information on TLS decryption methods and limitations (including PFS ciphers), see [[Tls]].
{{Warning|1=The GUI "Disabled" checkbox does NOT stop data collection. The sniffer continues running regardless of GUI status.}}


=== SIP Port Configuration ===
'''To stop data collection:'''
* '''Complete shutdown:''' <code>systemctl stop voipmonitor</code> on the sensor host
* '''Selective blocking:''' Create capture rule with '''Skip = ON''' in '''Control Panel > Capture Rules'''


The <code>sipport</code> parameter controls which SIP signaling ports the sensor listens to. This is critical when you need to capture traffic from devices using non-standard SIP ports (not port 5060).
== Deleting Sensors ==


'''To configure SIP ports via GUI:'''
If deletion fails, the sensor likely has capture rules assigned. Remove rules first via '''Control Panel > Capture Rules'''.


# Navigate to '''Settings > Sensors'''
'''Non-deletable local sensor (GUI+DB only servers):'''
# Click the '''wrench icon''' next to the affected sensor
# In the sensor settings dialog search field, enter '''sipport'''
# Configure the required value:


{| class="wikitable"
On central servers that don't capture traffic, an auto-created "localhost" sensor may appear. To replace it:
|-
! Parameter !! Description !! Example Value
|-
| sipport || SIP ports to listen on (comma-separated or ranges) || <code>5060,5080</code> or <code>5060,5070-5080</code>
|}


* '''Default:''' Port 5060 only
# Set <code>id_sensor = 1</code> in <code>/etc/voipmonitor.conf</code> on the central server
* '''Multiple ports:** Use commas (e.g., <code>5060,5061,5080</code>)
# In GUI: Add new sensor with Manager IP <code>127.0.0.1</code>, same Sensor ID, Port <code>5029</code>
* '''Port ranges:** Use hyphens (e.g., <code>5060,5070-5080</code>)
# Enable "is server in client/server mode" checkbox
# Disable "show active calls from all sensors in active call view" checkbox


'''When to change sipport:'''
= CDR Charts =


* Certain carriers or devices use non-standard SIP ports (e.g., 5080, 6060)
Define predefined charts for the [[Call_Detail_Record_-_CDR#Charts|CDR detail Charts tab]].
* You see missing CDRs for calls from specific IP addresses
* Packet captures show SIP traffic on ports other than 5060


'''After changing sipport:'''
= CDR Custom Headers =
* Manual config file changes: <code>systemctl restart voipmonitor</code>
* GUI changes (via '''reload sniffer''' button): Settings are applied automatically by the sensor


'''Important for Client/Server deployments:'''
Capture and display custom SIP headers in CDR views. Requires sniffer version 7.0RC7+.


If using <code>packetbuffer_sender = yes</code> (packet mirroring mode), you must configure matching <code>sipport</code> settings on BOTH the remote probe and the central server. Different port lists will cause the central server to ignore forwarded packets on ports it does not recognize.
== Setup Workflow ==


See [[Sniffer_distributed_architecture#Critical:_sipport_Must_Match_in_Distributed_Deployments]] for details.
<kroki lang="mermaid">
%%{init: {'flowchart': {'nodeSpacing': 10, 'rankSpacing': 30}}}%%
flowchart LR
    A[voipmonitor.conf<br/>custom_headers] --> B[Restart Sensor]
    B --> C[DB Column Created]
    C --> D[Settings > CDR<br/>Custom Headers]
    D --> E[CDR List View]
</kroki>


=== Configuring RTP Storage Limits via GUI
# Add header to <code>/etc/voipmonitor.conf</code>:
<syntaxhighlight lang="ini">
custom_headers = X-Cisco-Org-ID
</syntaxhighlight>
# Restart sensor: <code>systemctl restart voipmonitor</code>
# Generate a test call
# Configure in '''Settings > CDR Custom Headers''': select header, set Name, enable "Show as Column"


The sensor wrench icon interface allows you to configure disk space limits specifically for RTP (audio) PCAP files. This helps manage disk usage by limiting RTP storage while preserving SIP signaling and chart data, which consume significantly less space.
== Configuration Fields ==
 
To configure RTP retention limits for a specific sensor:
 
# Navigate to '''Settings > Sensors'''
# Click the '''wrench icon''' next to the problematic sensor
# In the search field at the top right, enter '''maxpoolrtp'''
# Configure the required RTP storage parameters:


{| class="wikitable"
{| class="wikitable"
|-
|-
! Parameter !! Description !! Example Value
! Field !! Description
|-
| Header Field || SIP header to capture (from dropdown after restart)
|-
| Name || Display label in GUI
|-
| Match in SIP by Header || Enable for [[Call_Detail_Record_-_CDR#Legs_by_header|Legs by header]] correlation
|-
| Show as Column || Display in CDR list view
|-
| Restrict to Regex pattern || Filter which values to capture
|-
| Boundary start/end || Extract substring between delimiters
|-
| Regexp || Extract using regex with capture groups <code>(...)</code>
|-
|-
| maxpoolrtpsize || Maximum disk space in MB for RTP PCAP files. When this limit is reached, oldest RTP files are deleted. || <code>51200</code> (50 GB)
| Select occurrence || <code>First found value</code>, <code>Last found value</code>, or <code>Nth occurrence</code>
|-
|-
| maxpoolrtpdays || Maximum age in days for RTP PCAP files. Files older than this are deleted. Use either size or time limit (whichever is reached first triggers cleanup). || <code>30</code> (30 days)
| Nth occurrence || '''(New in 2026.01)''' When "Nth occurrence" is selected, specify which occurrence number to extract (e.g., <code>2</code> for second occurrence). Uses packet timestamps for accurate ordering even when packet reordering is disabled.
|}
|}


'''When to use RTP limits:'''
== Extracting Substrings ==


* A specific sensor has limited disk space compared to others
'''Boundary method (recommended):''' Extract between delimiters.
* You want to preserve SIP signaling and chart data longer than audio
* Audio files are being deleted prematurely due to overall storage limits
* You need to balance storage allocation between RTP, SIP, and chart data


'''Important Notes:'''
Example: From <code>sip:1000@192.168.1.1;tag=123</code>, extract IP:
* Boundary start: <code>@</code>
* Boundary end: <code>;</code>
* Result: <code>192.168.1.1</code>


* The first limit that is reached (size or days) triggers cleanup. You can use both parameters for flexible control.
'''Regexp method:''' Use capture groups for complex patterns.
* RTP files typically consume 5-10x more disk space than SIP files. Limiting RTP helps preserve smaller, more valuable data types.
* GUI settings configured here take priority over settings in <code>/etc/voipmonitor.conf</code> when <code>mysqlloadconfig</code> is enabled (default).
* Settings are applied to the specific sensor. Configure RTP limits individually for sensors with different storage constraints.


For more information on data retention strategies, including size-based vs time-based retention, see [[Data_Cleaning]].
<syntaxhighlight lang="text">
 
# Extract version from: User-Agent: Asterisk/20.6.0
=== Sensor Health Monitoring with RRD Charts ===
Regexp: Asterisk/([0-9.]+)
 
Result: 20.6.0
If you experience poor call quality (low MOS scores, choppy playback) and need to determine whether the issue is network-related or caused by the sniffer host being overloaded, use the RRD (Round Robin Database) charts available in the GUI.
</syntaxhighlight>


**Accessing Sensor RRD Charts:**
{{Warning|1=Regexp MUST include parentheses <code>(...)</code> to define what to capture. Without them, the entire match is stored.}}


# Navigate to '''Settings > Sensors'''
== Filtering by SIP Method and Response Code ==
# Locate the sensor you want to monitor
# Click the '''chart icon''' next to the sensor entry
# This opens the RRD performance graphs for that sensor


**Key Metrics to Check:**
You can filter custom header extraction to specific SIP methods (e.g., INVITE) or SIP response codes (e.g., 300, 404).


{| class="wikitable"
{| class="wikitable"
|-
|-
! Metric !! Description !! What It Indicates
! Field !! Description !! Example Usage
|-
|-
| Buffer usage || Shows the percentage of available packet buffer being used || Sensor is approaching capacity limits if consistently high
| CSeq method || Filter by SIP request method || <code>INVITE</code> to capture only from INVITE requests
|-
|-
| Packet drops || Counts of packets the sensor could not process || Sensor is overloaded and dropping packets due to high traffic load
| response code || Filter by SIP response code number || <code>300</code> to capture only from 300 redirect responses
|}
|}


**Interpreting the Charts:**
=== Example: Extract Contact IP from 300 Redirect Responses ===
 
If you observe:
* '''Buffer usage growing to 100%''' and remaining at maximum capacity
* '''Packet drops being recorded''' (non-zero values on the packet drops graph)
 
This indicates the sniffer host is overloaded and is the source of audio quality issues. The sensor cannot keep up with incoming packet rate, causing packets to be dropped before they can be processed and stored. This results in:
* Low MOS scores
* Choppy audio playback in the GUI
* Missing call data
 
**Solutions for Sensor Overload:**
 
* Increase the kernel packet ring buffer size in <code>voipmonitor.conf</code>: <code>ringbuffer = 200</code> (default: 50, recommended: >= 500 for >100 Mbit traffic). This allows the operating system to buffer more packets before they are passed to VoIPmonitor, reducing kernel-level packet drops.
* Add more sensors to distribute the load ([[Sniffer_distributed_architecture|Distributed Architecture]])
* Use specialized capture hardware ([[DPDK|DPDK]], [[Napatech|Native Napatech cards]], [[PF_RING|PF_RING]])
* Reduce capture scope (more restrictive [[Capture_rules|capture rules]])
* Upgrade sensor hardware (faster CPU, more RAM)
* Reduce PCAP file storage or enable compression
 
**Historical Comparison for Troubleshooting Spikes**
 
When investigating sudden issues like "packetbuffer: MEMORY IS FULL" alarms or bad MOS scores on one sensor:
 
1. Navigate to '''Settings > Sensors''' and click the '''chart icon''' next to the affected sensor
2. Once the charts load, locate the '''From''' date field in the chart controls
3. Adjust the '''From''' date to a period '''before the issue started''' (e.g., 1-2 days earlier)
4. Compare the '''buffer usage''' chart between the normal and problematic periods
5. Look for sudden spikes or patterns that correlate with the error times
 
This historical comparison helps identify whether the issue is a gradual buildup (resource exhaustion) or a sudden traffic pattern change (bursty traffic from specific sources).
 
**When to Check RRD Charts:**
 
Use RRD charts to diagnose sensor overload when:
* Other platforms show clear audio but VoIPmonitor shows poor quality
* Only the sniffer host is affected, not the actual VoIP network
* Performance log shows high packet drops or buffer saturation
* Buffer usage chart shows a sudden increase correlating with error messages like "packetbuffer: MEMORY IS FULL"
 
This diagnostic step helps distinguish between network quality issues (jitter, loss in the actual VoIP path) vs. sniffer capacity issues (capturing host overload).
 
=== Disabling a Sensor ===
 
If you need to temporarily or permanently stop a sensor from collecting data and writing CDRs to the database, you have two options depending on your requirements.
 
{{Warning|
'''Important: GUI actions do not stop data collection'''
 
Toggling "Disabled" or clicking "Delete" for a sensor in the '''Settings > Sensors''' interface does NOT stop the underlying VoIPmonitor service. The sensor process continues to capture packets and write to the database regardless of its GUI status. You must use one of the methods below to halt actual data collection.
}}
 
'''Option 1: Stop the Service on the Sensor Machine (Complete Shutdown)'''
 
To completely stop a sensor from collecting data, you must stop the VoIPmonitor service on the sensor's host machine:
 
# Log into the sensor machine via SSH
# Stop the service:
<syntaxhighlight lang="bash">
systemctl stop voipmonitor
</syntaxhighlight>
# Verify the sensor appears offline in the GUI
 
This method:
* Completely halts packet capture and database writes
* Works for decommissioning sensors permanently
* Requires command line access to the sensor host
 
'''Option 2: Use Capture Rules with SKIP=ON (Selective Blocking)'''
 
To prevent a specific sensor from sending CDRs to the database while keeping the service running, use capture rules:
 
# Navigate to '''GUI > Capture rules'''
# Create a new rule for the sensor's IP address or phone numbers
# Set the '''Skip''' option to '''ON'''
# Configure any additional filters as needed
# Save and apply the rule
 
With '''SKIP=ON''':
* The sensor continues to capture packets from the network
* No CDRs are generated for matching traffic
* No files are created (PCAP, audio, graphs)
* RTP analysis is suppressed for matched calls
* Useful for selective blocking without stopping the entire service
 
'''Important notes on SKIP:'''
* The Skip option only works if the IP address or phone number appears in SIP signaling
* It does not work for IPs that are only used in RTP packets (media stream)
* For excluding RTP-only traffic, use the <code>filter</code> directive in <code>voipmonitor.conf</code>
 
For more information on capture rules, see [[Capture_rules]].
 
=== Troubleshooting: Non-deletable Local Sensor ===
 
In server/probe deployments where the GUI server is not sniffing traffic itself, a "local sensor" may be automatically created in the sensor list. This sensor cannot be deleted through the normal GUI interface.
 
'''Workaround:'''
# In '''Settings > Sensors''', add a new sensor with the same Sensor ID, name, and settings as the non-deletable local sensor
# After saving, the original automatically created sensor should either disappear or become deletable
# You can then remove the duplicate entry if both sensors appear
 
This occurs because the GUI automatically creates a sensor entry when it detects that <code>id_sensor</code> is set in the configuration but no active capture is configured on the GUI host.
 
=== Troubleshooting: Cannot Delete Sensor Due to Capture Rules ===
 
If you attempt to delete a sensor from the GUI and receive a pop-up error message, or if the delete action has no effect, the most common cause is that the sensor has '''capture rules assigned to it'''. Sensors with active capture rules cannot be deleted until those rules are removed first.
 
'''Resolution Steps:'''
 
# Navigate to '''Control Panel > Capture Rules'''
# Find any capture rules that are assigned to the sensor you are trying to delete
# Rules may be assigned by IP address, phone number, or network range
# Delete or reassign the capture rules to a different sensor
# After all rules have been removed or reassigned, return to '''Settings > Sensors'''
# You can now successfully delete the sensor
 
'''Why this happens:'''
 
Capture rules link to specific sensors for traffic filtering purposes. The GUI enforces referential integrity to prevent orphaned capture rules that would reference non-existent sensors. This safety mechanism ensures deleted rules do not leave behind dangling references that could cause system errors.
 
'''Alternative Solution: If You Need to Keep the Rules'''
 
If you want to delete a sensor but preserve its capture rules for use with a different sensor:
 
# Navigate to '''Control Panel > Capture Rules'''
# Edit each capture rule currently assigned to the sensor
# Reassign the rule to a different sensor (if your deployment has multiple sensors)
# Save the changes
# After all rules are reassigned, delete the original sensor
 
This approach is useful when migrating traffic filtering from one sensor to another without recreating the rules from scratch.
 
=== Removing and Reconnecting Sensors ===
 
When decommissioning or replacing a sensor, or when you need to refresh the sensor configuration after an upgrade, use the following standard workflow.
 
'''Standard Decommissioning Workflow:'''
 
# Navigate to '''Settings > Sensors''' in the GUI
# Click the sensor entry you want to remove
# Click '''Delete''' or '''Remove''' to delete the sensor probe entry
# Log into the command line of the sensor machine (SSH)
# Restart the voipmonitor service on the sensor:
<syntaxhighlight lang="bash">
systemctl stop voipmonitor
systemctl start voipmonitor
</syntaxhighlight>
# Return to '''Settings > Sensors''' in the GUI
# The sensor will automatically reappear in the list after the service restart
# Rename the sensor entry as needed if the IP or configuration has changed
 
'''How It Works:'''


When you restart the voipmonitor service on the sensor machine, it automatically re-registers with the GUI if <code>id_sensor</code> is configured in <code>/etc/voipmonitor.conf</code>. The GUI creates a new sensor entry with the current configuration. This workflow ensures that:
To filter CDRs for calls involving SIP 300 redirect responses and identify the redirect destination IP:
* The sensor configuration is refreshed with the latest sensor settings
* Old IP addresses or obsolete sensor entries are cleaned up
* The system automatically discovers the sensor again after restart


'''When to Use This Workflow:'''
# Navigate to '''Settings > Custom headers > CDR''' in the GUI
# Click '''Add new'''
# Set '''Header field''' to <code>Contact</code>
# Set '''Name''' to descriptive label (e.g., <code>SIP300RedirectDestinations</code>)
# Set '''Regexp''' to <code>sip:.*@([0-9]+\.[0-9]+\.[0-9]+\.[0-9]+);</code> to extract the IP address
# Set '''CSeq method''' to <code>INVITE</code>
# Set '''response code''' to <code>300</code>
# Save the configuration


* After an upgrade that caused errors referencing old/decommissioned sensor IP addresses
Use the new custom header and '''Last SIP response code''' as filters in the CDR list to identify calls with 300 redirects and their destinations.
* When replacing hardware and reusing a new IP address
* When you need to refresh sensor configuration settings
* When CDRs show warnings about unknown sensors


'''Note:''' This standard workflow is different from the emergency cleanup procedure described below, which is used only when the GUI crashes due to thousands of obsolete records.
{{Tip|The CSeq method and response code fields allow you to capture headers from specific SIP messages rather than all headers in the call.}}


=== Troubleshooting: GUI Crashes When Accessing Settings > Sensors ===
== Database Index for Custom Headers ==


If the web GUI becomes unresponsive or crashes when accessing '''Settings > Sensors''', this is typically caused by a large number of obsolete sensor records in the <code>sensors</code> database table. The GUI processes all sensor entries from this table to render the page, and if there are thousands of stale records (from old sensors, decommissioned hardware, or duplicate IDs), the PHP process may run out of memory or exceed execution time limits.
Custom header columns are not indexed by default. For frequent queries:


'''Symptoms:'''
* Settings > Sensors page does not load or times out
* GUI becomes unresponsive when navigating to sensor configuration
* PHP error logs show memory exhaustion or timeout errors
'''Solution: Manually Delete Obsolete Records from Database'''
Use the MySQL command line to remove obsolete sensor records directly from the database. The standard GUI interface cannot handle the cleanup if the records are already causing the page to crash.
<ol>
<li>'''Access the database:'''
<syntaxhighlight lang="bash">
mysql -u voipmonitor -p voipmonitor
</syntaxhighlight></li>
<li>'''Identify obsolete records:'''
Inspect the <code>sensors</code> table to find entries that correspond to obsolete sensors. Look for rows with old interface names, missing sensor IDs, or duplicates.
<syntaxhighlight lang="sql">
<syntaxhighlight lang="sql">
-- Example: Find entries referencing old or duplicate IDs
-- Find table/column location
SELECT * FROM sensors WHERE id_sensor IN (1,2,3);
SELECT dynamic_table, dynamic_column FROM cdr_custom_headers
--
WHERE header_field = 'X-Custom-Header';
-- Check total count of sensors
SELECT COUNT(*) FROM sensors;
</syntaxhighlight></li>


<li>'''Delete obsolete records:'''
-- Create index (use values from above query)
Execute <code>DELETE</code> statements for the identified obsolete rows. Be careful with the <code>WHERE</code> clause to ensure you only delete obsolete data.
CREATE INDEX idx_custom_header_3 ON cdr_next_2 (custom_header_3);
<syntaxhighlight lang="sql">
-- Delete records by id_sensor (replace with actual values after inspection)
DELETE FROM sensors WHERE id_sensor IN (<id1>, <id2>, <id3>);
 
-- Delete by specific criteria
DELETE FROM sensors WHERE host LIKE '%old-sensor-name%';
</syntaxhighlight></li>
 
<li>'''Verify cleanup:'''
<syntaxhighlight lang="sql">
-- Check remaining sensor count
SELECT COUNT(*) FROM sensors;
</syntaxhighlight>
</syntaxhighlight>
Exit the database:
<syntaxhighlight lang="sql">EXIT;</syntaxhighlight></li>


<li>'''Critical: Users must log out and log back in'''
== Troubleshooting Custom Headers ==
All users currently logged into the GUI must log out and then log back in for the sensor list to be refreshed. Simply reloading the page is not sufficient.</li>
</ol>
 
'''Note:''' The <code>sensors</code> table contains GUI sensor configuration entries, distinct from the <code>sensor_config</code> table which is used for sensor-level parameter overrides when the <code>mysqlloadconfig</code> feature is enabled.
 
=== Troubleshooting: Server Instance Not Appearing in GUI ===
 
After replacing a server/SBC and reusing its IP address, the server instance may disappear from the GUI sensor list, even though it is sending data and appears in CDRs with a warning.
 
=== Problem: Sensor Appears in CDRs With Warning But Not in GUI List ===
 
When you replace hardware (server, SBC, sensor host) but reuse the same IP address, the GUI may not automatically rediscover the server instance. CDRs from the new device appear in the database, but:
* The server instance is not visible in '''Settings > Sensors'''
* CDR records contain a warning about unknown sensor or manager connection
* The new server is working but not properly registered with the GUI
 
=== Solution: Manually Create Server Instance Entry ===
 
If your deployment uses server instances that connect directly to the MySQL database, follow these steps:
 
'''Step 1: Create the server instance entry in the GUI'''
 
# Navigate to '''Settings > Sensors'''
# Click '''Add new sensor''' or '''New sensor'''
# Configure the following fields:
** Sensor ID: Enter a unique identifier (e.g., <code>2</code>)
** Name: Descriptive name for the server instance (e.g., <code>SBC-Production</code>)
** Manager IP: IP address of the server instance (the new hardware's IP)
** Manager Port: TCP port for the manager connection (default: <code>5029</code>)
 
'''Step 2: Configure managerip and managerport on the server instance'''
 
Edit the <code>voipmonitor.conf</code> file on the new server instance to point to the GUI:
 
<syntaxhighlight lang="ini">
# On the new server instance (/etc/voipmonitor.conf)
managerip  = gui.server.ip    # GUI server IP address
managerport = 5029            # Manager API port (matches GUI Manager Port)
</syntaxhighlight>
 
Restart the voipmonitor service after making changes:
 
<syntaxhighlight lang="bash">systemctl restart voipmonitor</syntaxhighlight>
 
'''Step 3: Verify network connectivity'''
 
Ensure bidirectional network connectivity:
 
* '''GUI host → Server instance:''' GUI must be able to reach the server instance on the configured Manager IP/Port (for data retrieval and control)
* '''Server instance → MySQL database:''' Server instance must be able to write CDRs to the MySQL database
 
Test connectivity from both directions:
 
<syntaxhighlight lang="bash">
# From GUI host to server instance (verify Manager IP/Port)
nc -zv server.instance.ip 5029
 
# From server instance to MySQL database
mysql -h mysql.server.ip -u voipmonitor -p voipmonitor -e "SELECT 1"
</syntaxhighlight>
 
Check firewall rules on both systems to ensure:
* TCP/5029 (Manager port) is allowed from GUI to server instance
* MySQL port (usually 3306) is allowed from server instance to database
 
'''Step 4: Verify server instance status'''
 
After configuration, the server instance should appear in '''Settings > Sensors''' with a green status indicating it is connected. Any probes or sniffing interfaces connected to that server instance will be automatically discovered and listed under the server instance in the sensor tree.
 
=== Alternative: Using Modern Client-Server Mode ===
 
If you are planning a new deployment or can reconfigure your architecture, consider using the modern [[Sniffer_distributed_architecture|Client-Server mode]] which provides:
 
* Encrypted TCP connections between sensors and central server
* Automatic sensor registration (no manual GUI entry required)
* Simplified firewall configuration (single port: 60024 by default)
 
In Client-Server mode, sensors connect to a central server using <code>server_destination</code> and <code>server_destination_port</code>, and the central server handles SQL database writes. Sensors do not need direct MySQL database access.
 
== CDR Charts ==
 
This section allows you to define predefined charts that appear in the [[Call_Detail_Record_-_CDR#Charts|CDR detail view's Charts tab]]. These charts provide quick visual analysis for specific call records based on caller/called information.
 
[[File:settings-cdrcharts.png]]
 
== CDR Custom Headers ==
 
Since sniffer version 7.0RC7, VoIPmonitor can store custom SIP headers in the database for viewing and searching in the GUI. For the sniffer configuration, see [[Sniffer_configuration#custom_headers]].
 
=== How to Add a New Custom SIP Header ===
 
To capture and display a custom SIP header (e.g., <code>X-Cisco-Org-ID</code>) in the CDR view, follow this workflow:
 
;1. Configure the sniffer to capture the header
:Edit <code>/etc/voipmonitor.conf</code> and add the header name to the <code>custom_headers</code> parameter:
:<syntaxhighlight lang="ini">
custom_headers = X-Cisco-Org-ID
</syntaxhighlight>
:For multiple headers, separate with commas: <code>custom_headers = X-Cisco-Org-ID, X-Other-Header</code>
 
;2. Restart the sensor service
:Restart the sniffer service for the configuration to take effect and for the database columns to be created:
:<syntaxhighlight lang="bash">
systemctl restart voipmonitor
</syntaxhighlight>
:'''Important:''' Custom header data will only be captured for calls made AFTER the restart. Existing CDRs will not have this data.
 
;3. Generate a test call
:Place a test call to verify that the header is being captured and stored in the database.
 
;4. Configure GUI display settings
:Once the header appears in the database, configure the GUI:
:* Navigate to '''Settings > CDR Custom Headers'''
:* Select the header from the "Header Field" combo box (it will appear after restart)
:* Set the display name in the "Name" field (e.g., "Cisco Org ID")
:* Enable "Show as Column" to display it in the CDR list
:* Click '''Save'''
 
[[File:customheaderform.png]]
 
=== Configuration Fields ===
 
;Header Field
:Combo box listing available headers from the <code>cdr_next.custom_header*</code> database columns. These are automatically created when you add headers to <code>custom_headers</code> in <code>voipmonitor.conf</code> and restart the sniffer.
 
;Name
:The display name for this header in the CDR view header panel.
 
;Match in SIP by Header
:When enabled, this header is used for matching CDRs in the [[Call_Detail_Record_-_CDR#Legs_by_header|Legs by header]] tab. This is useful when you have a unique correlation identifier that links multiple call legs (e.g., from phone to SBC, and from SBC to provider). Alternative method: [[Sniffer_configuration#matchheader|matchheader]] in voipmonitor.conf.
 
;Show as Column
:When enabled, displays this header as a column in the CDR list view.
 
;Restrict to Regex pattern
:Optional regular expression pattern to filter which header values are stored in the database. Only headers matching this regex pattern will be captured. For example: <code>^[0-9]+$</code> to capture only numeric values.
 
;Select occurrence
:Controls which occurrence of a SIP header is stored when the same header appears multiple times in a call (common for headers like <code>P-Asserted-Identity</code> that appear in both the initial INVITE and subsequent re-INVITEs).
:* '''First found value:''' Captures the header value from the first occurrence (typically the initial INVITE). This is recommended when you only want the original value from call setup and want to ignore changes during the call (e.g., re-INVITEs during hold, transfers, or session modifications).
:* '''Last found value:''' Captures the header value from the last occurrence found. Use this when you need the most recent value if the header changes during the call.
 
'''Example: P-Asserted-Identity in Re-INVITEs'''
 
If calls include <code>P-Asserted-Identity</code> in both the initial INVITE and subsequent re-INVITEs (e.g., during hold operations), the system will capture the header for each occurrence. To capture only the initial INVITE value and ignore re-INVITEs:
 
# In '''Settings > CDR Custom Headers''', set '''Select occurrence''' to '''First found value'''
# This stores only the header value from the initial INVITE, ignoring values from subsequent SIP requests
 
This is particularly useful for ensuring consistent Caller ID information based on the original call setup rather than later modifications during the call session.
 
=== When is a Restart Required? ===
 
Restarting the sensor service is only required in the following scenarios:
 
*'''After adding NEW headers to voipmonitor.conf:''' When you add new header names to the <code>custom_headers</code> parameter in <code>/etc/voipmonitor.conf</code>, a restart is required to create the database columns and begin capturing data.
*'''After changing sniffer capture parameters:''' If you modify <code>snaplen</code>, <code>custom_headers_max_size</code>, or other capture-related parameters in <code>voipmonitor.conf</code>, restart to apply the changes.
 
Restart is NOT required for GUI-only changes such as:
* Modifying the display name ("Name" field)
* Toggling "Show as Column" or "Match in SIP by Header"
* Adding or changing regex patterns in "Restrict to Regex pattern"
 
To restart the sensor:
<syntaxhighlight lang="bash">
# Using systemd
systemctl restart voipmonitor
 
# Using init scripts
/etc/init.d/voipmonitor restart
</syntaxhighlight>
 
[[File:customheaderscdrpanel.png]]
 
=== Filtering Custom Headers ===
 
After configuring custom headers in the GUI, they appear in the CDR filter form where you can search for them using special values:
 
*'''Find all CDRs with this header present:''' Use the <code>%</code> wildcard as the filter value. This matches any non-empty value.
*'''Find all CDRs without this header:''' Type <code>NULL</code> (or leave empty) as the filter value to find calls where this header was not present.
*'''Specific value search:''' Enter the exact header value (or use <code>%</code> as a wildcard for partial matches, e.g., <code>sip:%</code> to find SIP URIs).
 
These filters appear in the CDR filter form after you have processed at least one call containing the custom header.
 
=== Troubleshooting: Header Capture Issues ===
 
If custom SIP headers are not being captured at all or are showing truncated content in the database, check the sniffer configuration parameters in <code>voipmonitor.conf</code>:


{| class="wikitable"
{| class="wikitable"
|-
|-
! Problem !! Cause !! Solution
! Problem !! Solution
|-
|-
| '''Complete header not captured''' || SIP packets are truncated before the custom header content is fully captured | In <code>voipmonitor.conf</code>, increase the <code>snaplen</code> parameter to capture larger packets: <code>snaplen = 3200</code> (or higher for long headers). The default may be too low for extended SIP headers used in STIR/SHAKEN (e.g., <code>P-Asserted-Identity</code> with <code>verstat</code> parameters).
| Header not captured || Increase <code>snaplen</code> in voipmonitor.conf (default may be too low)
|-
|-
| '''Header content truncated''' || Custom header value exceeds the maximum allowed size | In <code>voipmonitor.conf</code>, increase the <code>custom_headers_max_size</code> parameter (default: 1024 bytes): <code>custom_headers_max_size = 2048</code>. Headers longer than this value will be truncated during capture.
| Header truncated || Increase <code>custom_headers_max_size</code> (default: 1024 bytes)
|-
| Not visible in distributed setup || Check <code>server_destination</code> and <code>server_password</code> on sensor
|}
|}


=== Performance Optimization: Database Index for Custom Headers ===
Verify loaded headers: <code>echo 'custom_headers_dump cdr' | nc localhost 5029</code>


Custom header columns in <code>cdr_next_X</code> tables are '''not indexed by default''' to maintain high database write performance. If you plan to perform frequent or large-scale queries on a specific custom header, you should manually create a database index on that column to prevent full table scans.
= Load GeoIP Data =


'''Step 1: Find the table and column for your custom header'''
Loads GeoIP data for the [[Call_Detail_Record_-_CDR#Map|CDR Map tab]]. See [[Order_of_GeoIP_processing]] for processing priority.


First, query the <code>cdr_custom_headers</code> lookup table to identify where your header is stored:
= System Configuration =
 
<syntaxhighlight lang="sql">
-- Find the dynamic table and column for your custom header
SELECT dynamic_table, dynamic_column
FROM cdr_custom_headers
WHERE header_field = 'X-Custom-Header';
</syntaxhighlight>


'''Example Result:'''
== Basic ==


{| class="wikitable"
{| class="wikitable"
|-
|-
! dynamic_table !! dynamic_column
! Setting !! Description
|-
|-
| 2 || 3
| WEB URL || Base URL for hyperlinks in emails
|}
 
This means your header is stored in <code>cdr_next_2</code> table, column <code>custom_header_3</code>.
 
'''Step 2: Create the index manually'''
 
Execute the <code>CREATE INDEX</code> command using the table and column values found above:
 
<syntaxhighlight lang="sql">
-- Syntax: CREATE INDEX <index_name> ON <table_name> (<column_name>);
CREATE INDEX idx_custom_header_3 ON cdr_next_2 (custom_header_3);
</syntaxhighlight>
 
Choose a descriptive index name following your naming convention (e.g., <code>idx_header_X_Custom_Header</code>).
 
'''Important Considerations:'''
 
{{Warning|
'''Performance Impact:''' Adding indexes increases database load during CDR insertion (write speed). Only create indexes on headers that are actively and frequently queried. Each additional index consumes disk space and slows down INSERT operations.
}}
 
* '''Partitioned Tables:''' If you use <code>cdr_partition_by_hours</code> or daily partitioning, the index is created on all partitions automatically. This benefits query performance on recent data.
* '''Query Validation:''' Use <code>EXPLAIN</code> to verify the database uses your new index:
<syntaxhighlight lang="sql">
EXPLAIN SELECT cdr_ID FROM cdr_next_2 WHERE custom_header_3 = 'test_value';
</syntaxhighlight>
*  **Good Result:** <code>type: ref</code> (Index lookup is used)
*  **Bad Result:** <code>type: ALL</code> (Full table scan - index is not being used)
 
=== Limitations ===
 
The GUI custom header feature has the following limitations:
 
{| class="wikitable"
|-
|-
! Limitation !! Description
| Sniffer data path || PCAP storage directory (default: <code>/var/spool/voipmonitor</code>)
|-
|-
| '''No Regexp extraction''' || Custom headers store the '''complete raw header value'''. While you can use the "Restrict to Regex pattern" field to filter which headers to capture, you cannot extract partial values such as just an IP address from a SIP URI (e.g., extracting <code>192.168.1.1</code> from <code>sip:192.168.1.1</code>).
| Sniffer second datapath || Secondary spool directory (<code>spooldir_2</code>)
|-
|-
| '''No Delimiter aggregation''' || If a SIP header appears multiple times in a message (e.g., multiple Contact headers in a SIP 300 response), only one value is stored. Controlled by <code>custom_headers_last_value</code> in voipmonitor.conf (first or last occurrence).
| Default sensor hostname || Default hostname for sniffer connection
|-
|-
| '''No per-method filtering''' || Custom headers are captured from all SIP messages. There is no option to capture only from specific SIP methods (INVITE, BYE, etc.) or response codes (200, 300, etc.).
| Default sensor TCP port || Default manager API port (5029)
|}
|}


For advanced header extraction needs, contact VoIPmonitor support to discuss custom development or alternative approaches such as external PCAP processing.
{{Warning|1=If sensors connect to wrong destination after upgrade, disable '''Default sensor hostname''' and '''Default sensor TCP port''' in this section. When enabled, sensors ignore individual Manager IP/Port settings.}}
 
=== Alternative: Populating Custom Headers from External Databases ===
 
When carrier or routing information is stored in an external database (not in SIP signaling), you can populate custom header columns using direct SQL updates from the external data source.
 
{{InfoBox|
'''Use Case vs SIP Capture:''' This method is useful when you have external data (e.g., carrier billing records) that is not available in SIP signaling. If you can add the carrier ID as a SIP header in the INVITE message, capturing via SIP traffic (see above) is preferred as it requires no external synchronization.
}}
 
=== Step-by-Step: Import Carrier Data from External Database ===
 
'''Step 1: Create the Custom Header Column'''
 
Even if the data will be populated externally, you must define the header to create the database column:
 
1. Add to <code>/etc/voipmonitor.conf</code>:
<syntaxhighlight lang="ini">
custom_headers = x-termination-carrier
</syntaxhighlight>
2. Restart the sensor:
<syntaxhighlight lang="bash">
systemctl restart voipmonitor
</syntaxhighlight>
3. Configure in GUI > Settings > CDR Custom Headers (set Name and enable "Show as Column")
 
'''Step 2: Find the Table and Column Location'''
 
Query the <code>cdr_custom_headers</code> lookup table to identify where your custom header is stored:
 
<syntaxhighlight lang="sql">
SELECT dynamic_table, dynamic_column
FROM cdr_custom_headers
WHERE header_field = 'x-termination-carrier';
</syntaxhighlight>
 
''Example Result:'' <code>dynamic_table = 2</code>, <code>dynamic_column = 1</code>
 
This means the data is stored in table <code>cdr_next_2</code> and column <code>custom_header_1</code>.
 
'''Step 3: Create Synchronization Script'''
 
Create a script (Python, PHP, or shell) to populate the custom header from your external database. The script connects to both databases and updates records based on a matching key.
 
''' Matching Keys: '''
* <code>cdr_ID</code>: Internal VoIPmonitor CDR ID (most reliable if available in external DB)
* Time and numbers: <code>callend</code> time + <code>caller</code>/<code>called</code> (less reliable)
 
'''SQL Example''' (run via cron):
 
<syntaxhighlight lang="sql">
-- Update VoIPmonitor table with carrier data from external database
-- Assuming external table 'external_billing' has 'cdr_id' and 'carrier_name'
 
UPDATE cdr_next_2 cn
JOIN external_db.billing eb ON cn.cdr_ID = eb.cdr_id
SET cn.custom_header_1 = eb.carrier_name
WHERE eb.carrier_name IS NOT NULL;
</syntaxhighlight>
 
{{Warning|
'''Permissions Required:''' You must have UPDATE permissions on VoIPmonitor's <code>cdr_next_X</code> tables. Only update records you are certain match correctly. Test with SELECT queries first before running UPDATE statements.
}}
 
'''Step 4: Create Charts Using the Imported Data'''
 
Once the data is synchronized, create charts filtering by the custom header:
 
1. Navigate to <code>GUI > CDR > Charts</code>
2. Click <code>+</code> to create a new chart
3. Add series with filters like <code>x-termination-carrier = CarrierA</code>
4. Each carrier appears as a separate line on the chart
 
For detailed information on charting custom headers, see [[Charts#Creating_Percentage_Comparisons_for_Custom_SIP_Headers|Charts: Creating Percentage Comparisons for Custom SIP Headers]].
 
'''Performance Considerations'''
 
* Schedule sync scripts during off-peak hours to reduce database load
* Index the matching column (<code>cdr_ID</code>) in both databases if not already indexed
* Ensure <code>cdr_ID</code> is included in your external database for reliable matching
* Consider using database connection pooling for frequent sync operations
 
=== Distributed Architecture: Headers Not Visible in Central GUI ===
 
If your deployment uses multiple sensors connected to a central GUI, and custom SIP headers are not appearing for calls from a specific sensor despite being configured and present in the traffic, the issue is typically that the sensor is not sending CDRs to the central database.
 
'''Core Issue: Sensor Not Connected to Central Server'''
 
The sensor may be capturing custom headers locally but not transmitting them to the central GUI database because:
* The <code>server_destination</code> configuration is incorrect or missing on the sensor
* The <code>server_destination_port</code> does not match the central server's <code>server_bind_port</code>
* The <code>server_password</code> is incorrect
* The sensor entry in the GUI has conflicting configuration
 
'''Solution Workflow:'''
 
;1. Verify sensor configuration:
On the affected sensor, check <code>/etc/voipmonitor.conf</code>:
<syntaxhighlight lang="ini">
# /etc/voipmonitor.conf on the SENSOR
id_sensor              = 2
server_destination      = central.server.ip
server_destination_port = 60024  # Must match server_bind_port on central server
server_password        = your_strong_password
 
# For Local Processing mode (recommended)
packetbuffer_sender    = no
</syntaxhighlight>
 
Use a working sensor's configuration as a reference if available.
 
;2. Delete and re-register the sensor in GUI:
Sometimes stale sensor entries in the GUI database can cause connection issues.
# Navigate to '''Settings > Sensors'''
# Click the entry for the problematic sensor
# Click '''Delete''' to remove it
# Restart the sensor service:
<syntaxhighlight lang="bash">
systemctl restart voipmonitor
</syntaxhighlight>
# The sensor will automatically re-register with the GUI
 
;3. Verify connection:
After restarting, check that the sensor appears in '''Settings > Sensors''' with a connected status. Generate a test call and verify the custom headers appear in the CDR list.
 
'''Key Point:''' The <code>server_destination</code>, <code>server_destination_port</code>, and <code>server_password</code> settings control the encrypted TCP connection from the sensor to the central server. Without this connection, CDRs (including custom headers) cannot be transmitted to the central database.
 
For complete distributed architecture documentation, see [[Sniffer_distributed_architecture|Distributed Architecture: Client-Server Mode]].
 
=== Troubleshooting ===
 
If custom SIP header data is correctly stored in the database and available for filtering but not displayed in the CDR list, follow these diagnostic steps:
 
'''Verify the sniffer has loaded the custom header configuration:'''
 
Use the manager API to confirm that the custom headers are loaded into the sniffer's memory:
 
<syntaxhighlight lang="bash">
# Create a temporary path for the manager socket
echo 'manager_file start /tmp/vmsck' | nc <manager_ip> <manager_port>
 
# Check loaded CDR custom headers
echo 'custom_headers_dump cdr' | nc -U /tmp/vmsck
 
# Cleanup
rm -f /tmp/vmsck
</syntaxhighlight>
 
Replace <code>&lt;manager_ip&gt;</code> and <code>&lt;manager_port&gt;</code> with your sensor's manager connection settings (configured in [[Settings#Sensors|Settings > Sensors]] or in <code>voipmonitor.conf</code> with <code>managerip</code> and <code>managerport</code>). The default manager port is <code>5029</code>.
 
If no headers are listed, verify that:
* You have added the header names to the <code>custom_headers</code> directive in <code>voipmonitor.conf</code>
* You have restarted the voipmonitor service after adding headers
* The <code>cdr_custom_headers</code> table contains the expected entries
 
'''Verify the data is present in the database:'''
 
Check that the custom header data is actually being captured and stored:
 
<syntaxhighlight lang="sql">
-- Step 1: Find the dynamic table and column for your custom header
SELECT dynamic_table, dynamic_column
FROM cdr_custom_headers
WHERE header_field = '<your_header_name>'\G
 
-- Step 2: Query the actual CDR data to confirm values are stored
SELECT cdr_ID, calldate, custom_header_<column_number>
FROM cdr_next_<table_number>
WHERE custom_header_<column_number> IS NOT NULL
ORDER BY cdr_ID DESC
LIMIT 1\G
</syntaxhighlight>
 
Replace <code>&lt;your_header_name&gt;</code>, <code>&lt;table_number&gt;</code>, and <code>&lt;column_number&gt;</code> with the values returned by the first query.
 
'''Check for manual changes to the database:'''
 
{{Warning|
'''Do NOT manually modify''' the <code>cdr_custom_headers</code> table outside of the GUI. Manual changes (inserting, updating, or deleting records directly in the database) can cause synchronization issues between the GUI, the sniffer, and the actual data storage. Always use the GUI Settings > CDR Custom Headers interface to manage custom header definitions.
}}
 
If you suspect manual changes were made, compare the entries in <code>cdr_custom_headers</code> with the headers listed in the manager API output and the columns present in the <code>cdr_next_*</code> tables.
 
'''Check for GUI rendering issues:'''
 
If the header data exists in the database but does not display in the CDR list, enable GUI debug mode to check for JavaScript errors:
 
<syntaxhighlight lang="text">
Append ?debug=31415 to any GUI URL (e.g., https://your-gui.com/cdr/?debug=31415)
</syntaxhighlight>
 
Then open your browser's Developer Console (F12) and look for JavaScript errors that might indicate a rendering problem. Common issues include:
* Browser cache issues (try clearing cache or using incognito mode)
* JavaScript conflicts from browser extensions
* GUI service not restarted after configuration changes
 
'''Summary: Troubleshooting Checklist'''
* [ ] Header appears in <code>custom_headers_dump cdr</code> manager API output
* [ ] <code>cdr_custom_headers</code> table has correct mapping
* [ ] Data exists in the appropriate <code>cdr_next_*</code> table
* [ ] No manual modifications to <code>cdr_custom_headers</code> were made
* [ ] "Show as Column" checkbox is enabled in Settings > CDR Custom Headers
* [ ] Voipmonitor service has been restarted after configuration changes
* [ ] No JavaScript errors in browser console (enable debug mode with <code>?debug=31415</code>)
 
== Load GeoIP Data ==
 
Loads GeoIP data into the internal database for the [[Call_Detail_Record_-_CDR#Map|CDR detail Map tab]], which displays geographic locations of call participants.


[[File:settiongs-loadgeoip.png]]
== Database ==


== System Configuration ==
MySQL/MariaDB connection settings.


The System Configuration section contains core settings that affect the overall behavior of the GUI.
'''Custom port:''' Enter host with port in MySQL hostname field: <code>127.0.0.1:33306</code>


=== Basic ===
Also configure <code>mysqlport</code> in <code>/etc/voipmonitor.conf</code>. See [[Database_troubleshooting]] for details.


[[File:settings-sysbasic.png]]
== National ==


{| class="wikitable"
{| class="wikitable"
Line 902: Line 273:
! Setting !! Description
! Setting !! Description
|-
|-
| WEB URL || Base URL for the GUI, used in hypertext links (e.g., in email alerts)
| Timezone || GUI host timezone (for reports/alerts scheduling)
|-
|-
| Sniffer data path || Directory where sniffer stores data (default: <code>/var/spool/voipmonitor</code>)
| '''Sensors Timezone''' || '''CDR display timezone''' - set this to fix UTC display issues
|-
|-
| Sniffer second datapath || Path to the second spool directory (<code>spooldir_2</code>) configured in the sensor. This allows the GUI to access PCAP files stored in the secondary spool location. When configuring <code>spooldir_2</code> in <code>/etc/voipmonitor.conf</code>, set this field to the same path to enable the GUI to download PCAP, graph, and audio files from that location.
| National prefix || Prefixes for national call classification
|-
|-
| Default sensor hostname || Default hostname for connecting to the sniffer (default: localhost). For multiple sensors, configure them in Settings > Sensors
| International prefix || International dialing prefix (e.g., <code>00</code>, <code>011</code>)
|-
|-
| Default sensor TCP port || Default TCP port for the manager API (default: 5029)
| Local number || Country name for number normalization
|}
|}


=== Database ===
{{Tip|1=If CDRs display in UTC instead of local time, set '''Sensors Timezone''' (not regular Timezone) to your sensors' timezone.}}
 
Configuration for the MySQL/MariaDB database connection used by the GUI.


[[File:settings-sysdb.png]]
== Intervals ==


=== National ===
Default time filters for CDR view, dashboard, and Legs correlation.


Settings for localizing call classification and date/time display formats.
== Email / HTTP Referer ==
 
[[File:settings-sysnational.png]]


{| class="wikitable"
{| class="wikitable"
Line 929: Line 296:
! Setting !! Description
! Setting !! Description
|-
|-
| Timezone || Server timezone for the GUI host (format: Country/City, e.g., Europe/Prague). This setting is used for scheduling reports and alerts generated by the GUI. It does NOT affect CDR data timestamps.
| DEFAULT_EMAIL_FROM || Default "From" address for outgoing emails
|-
|-
| Sensors Timezone || Timezone for sensors sending CDR data to this database (format: Country/City, e.g., Europe/London). This setting controls how CDR timestamps are displayed in the GUI. Set this to match the timezone where your sensors are operating. All sensors sending data to this database should use the same timezone. This is the primary setting for correcting CDR timezone display issues.
| Disable email plain text || Force HTML-only emails
|-
| National prefix, 2, 3 || Prefixes used to classify calls as national vs. international (used in [[Active_calls|Active calls]] view)
|-
| Max national number length || Numbers longer than this are classified as international regardless of prefix
|-
| International prefix || Prefix used for international calls from your country (e.g., <code>0011</code> for Australia, <code>00</code> for many countries, <code>011</code> for US/Canada)
|-
| Local number || Your country name or local region for number normalization (e.g., <code>Australia</code>, <code>United States</code>, <code>Czech Republic</code>)
|-
| Date format || PHP date format string (default: <code>Y-m-d</code>). See [https://www.php.net/manual/en/datetime.format.php PHP DateTime format]
|-
| Time format || PHP time format string (default: <code>G:i:s</code>). See [https://www.php.net/manual/en/datetime.format.php PHP DateTime format]
|-
| Week start || First day of the week for calendar displays
|}
|}


{{InfoBox|
'''CDR Timezone Troubleshooting:'''


If CDR times are displaying in UTC instead of local timezone (e.g., showing in UTC instead of BST):


* The fix is to set '''Sensors Timezone''' (NOT the regular '''Timezone''' setting) to the correct timezone for your sensors
=== Troubleshooting Email Delivery ===
* Ensure all sensors sending data to this database are configured to use the same timezone
* If a sensor's OS timezone differs from the Sensors Timezone setting, you can override it by editing <code>/etc/voipmonitor.conf</code> on the sensor and using the <code>timezone</code> or <code>utc</code> options
* The regular '''Timezone''' setting is for the GUI host itself (report scheduling, alerts), not for CDR data display
}}


=== Troubleshooting: International Numbers Not Displaying Correctly ===
If users report not receiving verification emails or new user setup emails, verify the email sending status:


If international numbers are not displaying or being handled correctly (e.g., missing country codes, showing in local format when they should be international), the local number and international prefix settings in the GUI may need to be configured.
<b>For Exim mail servers:</b>
<syntaxhighlight lang="bash"># Check Exim mail log for delivery attempts
grep "recipient@example.com" /var/log/exim/main.log


'''Common Symptoms:'''
# Or search by timestamp
* International numbers appear in local format only
grep "2025-01-09 14:30:" /var/log/exim/main.log
* Country codes are missing from displayed numbers
</syntaxhighlight>
* Numbers are not being classified as international
* International calls are grouped incorrectly


'''Solution: Configure Local Number and International Prefix Settings'''
Look for the response code in the log entry:
* <code>250 message accepted</code> - Email was successfully delivered to remote server. The issue is on the recipient side (spam folder, quarantine, mail filtering).
* No <code>250</code> code - Email delivery failed at the server level. Check mail queue and server MTA configuration.


# Navigate to '''Settings > System Configuration > National'''
<b>If logs confirm successful delivery:</b> Inform the client that the email left the server successfully and advise them to check their Spam, Bulk, or Junk folders, or consult their internal IT team regarding mail filtering policies.
# Set the '''Local number''' field to your country name (e.g., <code>Australia</code>, <code>United States</code>, <code>Czech Republic</code>)
# Set the '''International prefix''' field to the international dialing prefix for your country:
** Australia: <code>0011</code>
** United States/Canada: <code>011</code>
** Many European countries: <code>00</code>
** Japan: <code>010</code>
# Save the settings


'''Example: Australia'''
<b>General MTA verification:</b>
For an Australian deployment:
<syntaxhighlight lang="bash"># Check if mail agent is running
* '''Local number:''' <code>Australia</code>
systemctl status postfix    # or exim4, sendmail
* '''International prefix:''' <code>0011</code>


These settings ensure that VoIPmonitor correctly normalizes and displays international numbers based on your local numbering plan.
# Test email from command line
echo "Test message" | mail -s "VoIPmonitor Test" your@email.com


=== Intervals ===
# Check mail queue
mailq


Default time intervals for various GUI views and filters.
# View general mail logs
 
tail -f /var/log/mail.log    # Debian/Ubuntu
[[File:settings-sysintervals.png]]
tail -f /var/log/maillog      # RHEL/CentOS
</syntaxhighlight>
== License ==


{| class="wikitable"
{| class="wikitable"
Line 997: Line 341:
! Setting !! Description
! Setting !! Description
|-
|-
| Default CDR interval || Default time filter when entering the CDR section. If set to "specified number of days", configure in the next option
| License token || Short token for retrieving license from portal
|-
|-
| Default CDR interval in days || Number of days for the CDR filter (only editable if above is set to "specified number of days")
| License key || Full license key content (multi-line)
|-
|-
| Default dashboard interval || Default time filter when entering the dashboard
| License email || Email for license notifications (leave empty to disable)
|-
| Default Legs by CID interval || Time window (+/-) for finding related calls in the Legs by CID tab (default: 5 seconds)
|-
| Default Legs by header interval || Time window (+/-) for finding related calls in the Legs by header tab (default: 5 seconds)
|}
|}


=== Email / HTTP Referer ===
'''Update license after payment:''' Click '''get/update license key''' button.


Email configuration settings.
'''Manual activation:''' Copy full license key from portal (Services > My services) and paste into License key field.


[[File:settings-sysemailhttpreferer.png]]
'''Disable notification emails:''' Remove email from "License email" field.
 
{| class="wikitable"
|-
! Setting !! Description
|-
| DEFAULT_EMAIL_FROM || Default "From" address for outgoing emails
|-
| Disable email plain text || Enable to force HTML-only emails. Useful for mail clients that display only plain text incorrectly (e.g., older Outlook versions)
|}


=== License ===
== GeoIP ==


License and notification email configuration.
Configure API keys for MaxMind or IPInfoDB services.


[[File:settings-syslicense.png]]
== Advanced ==


{| class="wikitable"
{| class="wikitable"
Line 1,033: Line 364:
! Setting !! Description
! Setting !! Description
|-
|-
| License token || Short text token for retrieving license key from VoIPmonitor portal
| ENABLE_CSRF_CHECK || Enable CSRF protection (recommended for production)
|-
| License key || Full license key content (multi-line text)
|-
|-
| get/update license key || Button to fetch or update the license from the VoIPmonitor portal
| Pcap deduplication before download || Remove duplicate packets from PCAP downloads
|-
|-
| License email || Email address for receiving license issue and overage notification emails
| Http proxy (for upgrades) || Proxy for GUI/sniffer upgrades: <code>http://proxy:port</code>
|}
 
'''Updating License After Payment:'''
 
After purchasing or renewing a license through the voipmonitor.org portal, update your GUI license as follows:
 
# Navigate to '''Settings > License'''
# Click the '''get/update license key''' button
 
The GUI will automatically fetch your updated license from the portal if the payment has been processed. You do not need to manually enter a license key or token unless automatic retrieval fails.
 
'''Manually Retrieving License from Portal:'''
 
If the automatic update does not work, retrieve your license directly from the portal:
 
# Log in to https://www.voipmonitor.org
# Navigate to '''Services > My services'''
# Locate your VoIPmonitor license
# Click to view the license details
# Copy the full license key content
# Paste it into the '''License key''' field in '''Settings > License'''
 
'''Note:''' The license key is displayed as multi-line text. Ensure you copy the entire content when pasting.
 
To configure the license expiry notification for multiple recipients, enter all email addresses separated by a comma (e.g., <code>user1@example.com,user2@example.com</code>).
 
'''Disabling License Notification Emails:'''
 
To stop receiving license issue and overage notification emails:
# Navigate to '''Settings > License'''
# Remove the email address from the "License email" field
# Save the changes
 
'''Note:''' This only disables license-related notification emails. Other automated emails (QoS alerts, daily reports, sensor health alerts) will continue to function.
 
=== GeoIP ===
 
Configuration for GeoIP services used in the CDR Map view.
 
[[File:settings-sysgeoip.png]]
 
{| class="wikitable"
|-
|-
! Setting !! Description
| Enable GUI to run in iframe || Allow embedding in iframes (disabled by default for security)
|-
|-
| Use GeoIP local database || Enable/disable the internal GeoIP database (if loaded via [[#Load_GeoIP_Data|Load GeoIP Data]])
| CDR share key || Secret for CDR share URLs
|-
|-
| GeoIP maxmind.com KEY || API key for MaxMind GeoIP service
| Always enable 2FA dialog || '''(New in 2026.1)''' Always show 2FA input field in login dialog, even for users without 2FA enabled. Useful for external authentication systems that require 2FA code.
|-
|-
| GeoIP ipinfodb.com KEY || API key for IPInfoDB service
| DISABLE_FAX || '''(New in 2026.1)''' Disables fax (T.38) file downloading from the GUI.
|}
|}


=== Advanced ===
'''Firewall requirements:''' Allow outbound HTTPS to:
* <code>voipmonitor.org</code> - License updates
* <code>download.voipmonitor.org</code> - Software upgrades
* <code>share.voipmonitor.org</code> - CDR sharing
* <code>reports.voipmonitor.org</code> - Debug reports
=== Batch Download Filename Format ===


Advanced configuration options for power users and specific use cases.
'''Location:''' GUI > Settings > System Configuration > Advanced > '''Set the format of the filename for saving'''


[[File:settings-sysadvanced.png]]
Controls the filename pattern for PCAP/audio files in batch download ZIP archives.


'''Available placeholders:'''
{| class="wikitable"
{| class="wikitable"
|-
|-
! Setting !! Description
! Placeholder !! Description !! Example
|-
| Enable CDR group panel || Show/hide the group panel at the bottom of the CDR view
|-
| ENABLE_CDR_FORCE_INDEX_CALLDATE || Force use of the calldate index on CDR queries. Enable only for unoptimized MySQL installations experiencing slow queries
|-
| ENABLE_CSRF_CHECK || Enable CSRF (Cross-Site Request Forgery) protection in the GUI. When enabled, the GUI validates CSRF tokens for state-changing operations, increasing session security and mitigating certain types of web attacks. Set to <code>TRUE</code> to enable. Recommended for production environments
|-
|-
| Enable database IP reverse lookup || Resolve IP addresses to names using the internal IP lookup table
| <code>{date}</code> || Call date || <code>2024-09-27</code>
|-
|-
| Enable DNS reverse lookup || Resolve IP addresses to names using DNS
| <code>{time}</code> || Call time || <code>12-32-49</code>
|-
|-
| Enable database number lookup || Resolve phone numbers to names using the internal prefix lookup table
| <code>{caller}</code> || Caller number || <code>55555</code>
|-
|-
| Disable rtpfirstleg param || Disable the <code>--rtp-firstleg</code> parameter for PCAP audio decoding. Enable only if experiencing audio issues
| <code>{called}</code> || Called number || <code>555444333222111</code>
|-
|-
| Disable URL wav protection || Skip session authentication for WAV file downloads. Use with '''WAV download key''' for secure external access
| <code>{id}</code> || CDR ID || <code>ID5</code>
|-
|-
| WAV download key || Secret key required for WAV downloads when URL protection is disabled
| <code>{callid}</code> || '''(New in 2026.1)''' SIP Call-ID string || <code>abc123@192.168.1.1</code>
|-
| Hide SIP domain in CDR || Hide SIP domains in the CDR display
|-
| Hide live play || Hide live playback buttons in [[Active_calls|Active calls]]
|-
| Hide WAV play || Hide WAV playback buttons in CDR view
|-
| Upload sniffer conf path || Path to voipmonitor.conf for PCAP upload functionality
|-
| CDR share key || Secret string used to generate unique hashes for CDR share URLs
|-
| Folder for export CSV || Directory where CSV files from [[Reports#CSV_Export_via_Crontab_Scheduler|crontab scheduler tasks]] are saved
|-
| CSV name prefix || Optional prefix for CSV filenames generated by crontab tasks
|-
| Delete CSV after X days || Auto-delete CSV files older than specified days
|-
| Pcap deduplication before download || Enable to remove duplicate and retransmitted SIP/RTP packets when downloading PCAP files from the GUI. This may cause a mismatch between the packet count shown in the GUI SIP History and the packet count in the downloaded PCAP file. Disable to ensure the downloaded PCAP contains all captured packets including duplicates
|-
| Http proxy (for upgrades) || Proxy server address and port for automatic GUI and sniffer upgrades via the web interface. Required when the VoIPmonitor server is behind a corporate firewall or proxy and cannot connect directly to download.voipmonitor.org or github.com. Format: <code>http://proxy-server-ip:port</code> or <code>http://username:password@proxy-server-ip:port</code> for authenticated proxies
|-
| Enable GUI to run in iframe || Allow the GUI to be loaded in an <code>iframe</code> (embed the VoIPmonitor interface in other web applications). Set to <code>true</code> to enable. This is required when hosting the GUI in subfolders (e.g., <code>/ucloud</code>, <code>/unite</code>) within an iframe. By default, the GUI sends security headers that prevent iframe embedding for clickjacking protection
|}
|}


=== Troubleshooting: GUI Upgrades Behind Proxy Servers ===
'''Default format:''' <code>{date}_{time}_{caller}_{called}_{id}</code>


If the GUI or sensor upgrade process fails due to network restrictions or firewall blocking direct internet access:
'''Example output:''' <code>2024-09-27_12-32-49_55555_555444333222111__ID5.pcap</code>


'''Solution 1: Configure HTTP Proxy in GUI (Recommended)'''
'''With Call-ID:''' <code>{date}_{time}_{callid}_{id}</code> → <code>2024-09-27_12-32-49_abc123@192.168.1.1_ID5.pcap</code>
# Navigate to '''Settings > System Configuration > Advanced'''
# Find the '''Http proxy (for upgrades)''' field
# Enter your proxy server address: <code>http://proxy-server-ip:port</code>
# If authentication is required, include credentials: <code>http://username:password@proxy-server-ip:port</code>
# Save the settings
# Retry the GUI upgrade (Settings > System > Upgrade) or sensor upgrade (Settings > Sensors)


'''Solution 2: Proxy for Remote Sensors (curlproxy)'''
For remote sensors that need to download packages independently, configure the <code>curlproxy</code> parameter directly on the sensor:
# SSH into the remote sensor server
# Edit the sensor configuration: <code>sudo nano /etc/voipmonitor.conf</code>
# Add or modify the <code>curlproxy</code> line in the <code>[general]</code> section:
<syntaxhighlight lang="ini">
[general]
curlproxy = http://proxy-server-ip:port
</syntaxhighlight>
# Restart the sensor service: <code>sudo systemctl restart voipmonitor</code>
# Retry the upgrade from the GUI (Settings > Sensors)


'''References:'''
=== Security Settings ===
* [[FAQ#How_do_I_troubleshoot_internet_connectivity_issues|FAQ: Troubleshooting Internet Connectivity]]
* [[GUI_Installation|GUI Installation Guide]]


=== Troubleshooting: Firewall Requirements for VoIPmonitor Functions ===
'''Location:''' Add to <code>php/system_configuration.php</code> (persists after GUI System Configuration changes)


If your VoIPmonitor server has outbound network connections blocked by a firewall for security purposes, certain functions will fail without specific domain whitelisting.
<syntaxhighlight lang="php">
 
<?php
'''Symptoms of blocked outbound connections:'''
define('ENABLE_CSRF_CHECK', true);
* Automatic license updates fail (license key expiration warnings)
define('ENABLE_POST_METHOD_CHECK', true);
* GUI and sniffer upgrades fail via the web interface
</syntaxhighlight>
* "Share CDR" feature cannot send CDRs to the sharing server
* "Generate debug report" feature cannot upload the report
* Support sessions cannot connect
 
'''Required Outbound Domain Whitelist:'''
 
To ensure proper functionality when operating behind a restrictive firewall, configure firewall rules to allow the VoIPmonitor server to make outbound HTTPS connections to the following domains:


{| class="wikitable"
{| class="wikitable"
|-
|-
! Domain !! Purpose
! Setting !! Default !! Description
|-
| <code>voipmonitor.org</code> || License key expiration updates and renewal checks
|-
| <code>download.voipmonitor.org</code> || Automatic GUI and sniffer binary upgrades via web interface
|-
| <code>share.voipmonitor.org</code> || "Share CDR" feature for sending call data to the sharing server
|-
|-
| <code>reports.voipmonitor.org</code> || "Generate debug report" feature for uploading diagnostic reports
| <code>ENABLE_CSRF_CHECK</code> || <code>false</code> || '''(Recommended)''' Enables CSRF token validation for state-changing requests. Protects against Cross-Site Request Forgery attacks where malicious websites could execute actions on behalf of authenticated users.
|-
|-
| <code>vm1.voipmonitor.org</code> (IP: 37.157.192.45) || Support sessions and remote access
| <code>ENABLE_POST_METHOD_CHECK</code> || <code>false</code> || '''(Recommended)''' Enforces POST method for state-changing operations. Prevents attacks via GET requests (e.g., password change via malicious link).
|}
|}


'''Protocol and Port Requirements:'''
{{Warning|1=For production environments, both settings should be enabled to protect against account takeover attacks (CVSS 7.5). Without these protections, an attacker could change user passwords or 2FA settings via CSRF.}}
* '''Protocol:''' HTTPS (TCP port 443)
* '''Direction:''' Outbound initiations from the VoIPmonitor server
* '''Destination:''' Specific domains listed above (resolve to their current IP addresses via DNS)


'''License Check Mechanism:'''
'''Why system_configuration.php?''' Settings in <code>configuration.php</code> are overwritten when System Configuration is saved via GUI. Place security settings in <code>system_configuration.php</code> to ensure they persist.


The license expiration status is checked automatically by a cronjob that runs every minute:
''New in 2026.1''
 
= Localization =
<syntaxhighlight lang="bash">
# Automatic license check (runs every minute via cron)
php /var/www/html/php/run.php cron
</syntaxhighlight>


You can also manually trigger a license check update:
Create GUI translations. Red numbers indicate untranslated items. Changes apply after logout/login.


<syntaxhighlight lang="bash">
= CDR View Custom URL =
# Manually check and update license status
php /var/www/html/php/run.php runUpdateLicenseKey
</syntaxhighlight>


If the license check fails due to firewall blocking, VoIPmonitor may show incorrect expiration warnings or fail to renew licenses automatically.
Add custom hyperlinks to CDR Commands column. Use <nowiki>{{paramName}}</nowiki> in URL to include CDR values.


'''Alternative Approaches:'''
= Troubleshooting =


If your security policy does not allow direct outbound connections to specific domains:
== Sensors Connect to Wrong Destination After Upgrade ==


1. '''Use HTTP Proxy:''' Configure the <code>Http proxy (for upgrades)</code> setting in Settings > System Configuration > Advanced to route connections through an approved corporate proxy server
'''Cause:''' Default sensor hostname/port settings override individual sensor configurations.
2. '''Manual Upgrade Method:''' Download packages manually on a machine with internet access and transfer via SCP/SFTP to the restricted server (see [[GUI_Installation|manual upgrade instructions]])
3. '''Offline License Activation:''' For license management without internet access, use the offline method by retrieving the full multi-line license key from the voipmonitor.org portal and pasting it manually into Settings > License (see [[License|license documentation]])


'''Configuration Example (iptables):'''
'''Fix:''' Disable '''Default sensor hostname''' and '''Default sensor TCP port''' in Settings > System Configuration > Basic.


To allow outbound connections to VoIPmonitor domains using iptables:
== GUI Crashes on Settings > Sensors Page ==


<syntaxhighlight lang="bash">
'''Cause:''' Too many obsolete sensor records in database.
# Allow outbound HTTPS to voipmonitor.org
iptables -A OUTPUT -p tcp -d voipmonitor.org --dport 443 -j ACCEPT


# Allow outbound HTTPS to download.voipmonitor.org
'''Fix:''' Delete obsolete records directly:
iptables -A OUTPUT -p tcp -d download.voipmonitor.org --dport 443 -j ACCEPT
<syntaxhighlight lang="sql">
 
-- Check count
# Allow outbound HTTPS to share.voipmonitor.org
SELECT COUNT(*) FROM sensors;
iptables -A OUTPUT -p tcp -d share.voipmonitor.org --dport 443 -j ACCEPT
-- Delete obsolete entries (adjust WHERE clause)
 
DELETE FROM sensors WHERE host LIKE '%old-sensor%';
# Allow outbound HTTPS to reports.voipmonitor.org
iptables -A OUTPUT -p tcp -d reports.voipmonitor.org --dport 443 -j ACCEPT
 
# Allow outbound HTTPS to vm1.voipmonitor.org (IP: 37.157.192.45)
iptables -A OUTPUT -p tcp -d 37.157.192.45 --dport 443 -j ACCEPT
 
# Save iptables rules
service iptables save
</syntaxhighlight>
</syntaxhighlight>
All users must log out and back in after cleanup.


'''Note:''' IP addresses for VoIPmonitor domains may change over time. For long-term firewall configurations, consider using DNS-based firewall rules, whitelist the authoritative DNS servers for these domains, or periodically review and update IP-based rules.
== License Update Fails ==
 
=== Troubleshooting: GUI in iframe Not Loading Properly ===
 
If the VoIPmonitor GUI is embedded in an <code>iframe</code> (e.g., from another web application) and fails to load or shows 301 redirect errors:
 
'''Symptoms:'''
* Iframe displays error messages or blank content
* 301 redirect when accessing subfolder URLs (e.g., <code>/ucloud</code>, <code>/unite</code>)
* Browser console shows refused to load in iframe errors
 
'''Solution: Enable iframe Support in System Configuration'''
 
The GUI sends security headers (such as <code>X-Frame-Options</code>) by default to prevent clickjacking attacks. To allow the GUI to run in an iframe:
 
# Navigate to '''Settings > System Configuration > Advanced'''
# Find the '''Enable GUI to run in iframe''' setting
# Set it to <code>true</code>
# Save the settings
# Re-test the iframe functionality
 
Apply this setting to all relevant GUI installations/folders if you have multiple instances (e.g., <code>/ucloud</code> and <code>/unite</code>).
 
'''Additional Notes:'''
* This is a GUI-level setting for security header configuration, not a web server configuration
* After enabling, the browser should be able to load the GUI content within the iframe
* For security reasons, only enable this if you trust the parent application hosting the iframe
 
=== Troubleshooting: License Key Renewal Failures ===
 
If the "get/update license key" button fails or the license cannot be renewed automatically, the most common cause is a firewall blocking outbound HTTPS connections to the VoIPmonitor portal.
 
'''Primary Solution: Configure Firewall Rules'''
 
The GUI requires outbound access to the VoIPmonitor portal servers via HTTPS (TCP port 443). Configure your firewall to allow:
 
<syntaxhighlight lang="bash">
# Example: Allow outbound HTTPS to voipmonitor.org
sudo firewall-cmd --permanent --add-service=https
# Or allow specific traffic
sudo firewall-cmd --permanent --add-rich-rule='rule family="ipv4" destination address="voipmonitor.org" port protocol="tcp" port="443" accept'
sudo firewall-cmd --reload</syntaxhighlight>
 
For iptables-based firewalls:
<syntaxhighlight lang="bash">
# Allow outbound HTTPS to voipmonitor.org
sudo iptables -A OUTPUT -p tcp -d voipmonitor.org --dport 443 -j ACCEPT
sudo iptables -A INPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
# Save rules (distribution-specific)
sudo iptables-save | sudo tee /etc/iptables/rules.v4</syntaxhighlight>
 
For corporate environments with restrictive firewalls or outbound web proxies, contact your network administrator to:
* Allow outbound HTTPS (port 443) to <code>voipmonitor.org</code>
* Allow access to <code>download.voipmonitor.org</code> and <code>github.com</code> (for upgrades)
* Configure any necessary proxy settings (see [[#Troubleshooting:_GUI_Upgrades_Behind_Proxy_Servers|GUI Upgrades Behind Proxy Servers]])
 
'''Alternative Solutions'''
 
If you cannot configure firewall rules or have no internet access:
 
*'''Option 1: Use HTTP Proxy'''
Configure the <code>Http proxy (for upgrades)</code> setting in [[#Advanced|Settings > System Configuration > Advanced]] if a corporate proxy is available. This setting routes HTTPS requests including license renewal through an approved proxy server.
 
*'''Option 2: Offline Activation (Last Resort)'''
If network access is completely blocked, use offline activation:
# Log in to https://www.voipmonitor.org
# Navigate to '''Services > My services'''
# Locate your VoIPmonitor license
# Click the '''license''' button
# Copy the '''full license key content''' (multi-line text including Expires, id, hwid, maxcalls, etc.)
# Paste the full content into the '''License key''' field in Settings > License
# Click '''Save'''
 
'''Verification'''
After configuring firewall rules or updating the license:
# Return to '''Settings > License'''
# Click the '''get/update license key''' button
# Verify the license status shows as current and not expired
 
== Localization ==
 
Create custom translations for the GUI interface. Localizations are not 100% complete; please report missing translation items.
 
[[File:settings-localisationform.png]]
 
[[File:settings-localisationgrid.png]]
 
* Red numbers indicate untranslated items, which is useful after upgrading to identify new strings
* Changes take effect after logout/login
 
== CDR View Custom URL ==
 
Add custom hyperlinks to the CDR view Commands column. This is useful for integrating external monitoring or CRM systems.
 
=== Configuration ===
 
Navigate to '''GUI > Settings > CDR view custom URL'''.


[[File:cdr_view_custom_url.png]]
'''Cause:''' Firewall blocking outbound HTTPS.


You can include CDR parameters in the URL using two methods:
'''Fix:''' Allow outbound TCP 443 to <code>voipmonitor.org</code>, or configure HTTP proxy in Advanced settings, or use offline activation.


# '''Via Parameters and Custom headers items:''' Values are appended as query parameters (e.g., <code>?paramName=value</code>)
== GUI Not Loading in iframe ==
# '''Directly in URL:''' Use <nowiki>{{paramName}}</nowiki> syntax, which is replaced with the actual value


=== Display ===
'''Fix:''' Enable '''Enable GUI to run in iframe''' in Advanced settings.


Configured custom URLs appear as links in the Commands column of the CDR view.
== PCAP Download Has Fewer Packets Than GUI Shows ==


== AI Summary for RAG ==
'''Cause:''' Pcap deduplication is enabled (removes retransmissions).


'''Summary:''' This article documents VoIPmonitor GUI settings including sensor configuration (with SSL/TLS parameters for decrypting encrypted SIP traffic), sensor health monitoring via RRD charts (buffer usage and packet drops graphs to diagnose sniffer host overload), troubleshooting server instances that do not appear in the GUI after hardware replacement, HISTORICAL COMPARISON FOR TROUBLESHOOTING SPIKES (adjust From date in sensor RRD charts to compare buffer usage before and after issue started - useful for sudden issues like packetbuffer: MEMORY IS FULL alarms or bad MOS scores on one sensor), disabling sensors to stop data collection, TROUBLESHOOTING SENSOR DELETION: two common scenarios - (1) Non-deletable local sensors in server/probe deployments where the GUI server has id_sensor configured but no active capture, solved by creating a duplicate sensor entry; (2) Sensors that cannot be deleted because they have capture rules assigned - THE MOST COMMON CAUSE OF SENSOR DELETION ERRORS is active capture rules assigned to the sensor. To delete a sensor with capture rules, navigate to Control Panel > Capture Rules, find and/or delete rules assigned to the sensor, then delete the sensor from Settings > Sensors. The GUI prevents deletion of sensors with active capture rules to maintain referential integrity and prevent orphaned rules. An alternative solution allows preserving capture rules by reassigning them to a different sensor before deletion - useful for migrating traffic filtering between sensors without recreating rules. CDR custom headers with their limitations and performance optimization (database index creation), distributed architecture troubleshooting for custom headers not visible in central GUI, GeoIP data loading, system configuration (basic, database, national, intervals, email, license, GeoIP, advanced), localization, and custom CDR URLs. Advanced settings include Http proxy (for upgrades) for configuring proxy servers behind firewalls, Pcap deduplication before download which can cause packet count mismatches between GUI SIP History and downloaded PCAP files, and ENABLE_CSRF_CHECK for security hardening by enabling CSRF (Cross-Site Request Forgery) protection tokens in the GUI to mitigate web attacks. CDR CUSTOM HEADERS: Settings > CDR Custom Headers allows capturing custom SIP headers (like X-Cisco-Org-ID) into database columns for viewing and searching; require adding header name to custom_headers in voipmonitor.conf and restarting sniffer to create database columns; configuration fields include Header Field, Name, Match in SIP by Header, Show as Column, Restrict to Regex pattern, and Select occurrence; SELECT OCCURRENCE FIELD controls which occurrence of a SIP header is stored when the same header appears multiple times in a call (common for headers like P-Asserted-Identity that appear in both initial INVITE and subsequent re-INVITEs); First found value captures header from first occurrence (typically initial INVITE) and ignores re-INVITEs during hold/transfers/session modifications- recommended when only original value from call setup is needed; Last found value captures final occurrence if header changes during call; to capture only initial P-Asserted-Identity and ignore re-INVITE values, set Select occurrence to First found value in Settings > CDR Custom Headers; this ensures consistent Caller ID based on original call setup rather than later modifications; custom headers limitations include no regexp extraction, no delimiter aggregation for multiple header values, and no per-method filtering. FIREWALL REQUIREMENTS: If outbound network connections are blocked by a firewall, VoIPmonitor functions will fail without domain whitelisting. Required outbound domains: voipmonitor.org for license key expiration updates, download.voipmonitor.org for GUI/sniffer auto-upgrades, share.voipmonitor.org for "Share CDR" feature, reports.voipmonitor.org for "Generate debug report" uploads, and vm1.voipmonitor.org (IP: 37.157.192.45) for support sessions. Protocol: HTTPS (TCP port 443) outbound. License check runs automatically via cronjob "php /var/www/html/php/run.php cron" every minute, manually trigger with "php /var/www/html/php/run.php runUpdateLicenseKey". Alternative approaches if direct outbound connections not allowed: (1) Configure HTTP proxy in Settings > System Configuration > Advanced > Http proxy (for upgrades), (2) Manual package download and SCP/SFTP transfer, (3) Offline license activation using full multi-line license key from voipmonitor.org portal pasted into Settings > License. Example iptables rules provided for whitelisting VoIPmonitor domains. Key topics: Enable GUI to run in iframe setting in Settings > System Configuration > Advanced allows embedding the VoIPmonitor GUI in iframes for subfolders like /ucloud or /unite - by default the GUI sends security headers (X-Frame-Options) to prevent iframe embedding for clickjacking protection; GUI in iframe not loading properly with 301 redirect errors can be fixed by enabling the "Enable GUI to run in iframe" setting to true; ENABLE_CSRF_CHECK in Settings > System Configuration > Advanced enables CSRF token validation for state-changing operations to increase session security and mitigate web attacks including XSS vulnerabilities - set to TRUE to enable and recommended for production environments; LICENSE UPDATE: After purchasing or renewing a license through voipmonitor.org portal, navigate to Settings > License and click the "get/update license key" button - the GUI automatically fetches your updated license if payment has been processed (no manual entry needed); if automatic retrieval fails, retrieve license manually from portal: log in to voipmonitor.org, navigate to Services > My services, locate license, view details, copy full license key content (multi-line text), paste into License key field in Settings > License; license token is a short text string for retrieving license key; license key field accepts full multi-line license key content; "get/update license key" button fetches license from VoIPmonitor portal; SENSOR DISABLE: Disabling a sensor in the GUI does NOT stop it from collecting data - the sensor process continues to capture and write to the database regardless of GUI status. To stop data collection permanently, run "systemctl stop voipmonitor" on the sensor host machine. Alternatively, use capture rules with SKIP=ON to prevent CDRs from being written to the database while keeping the service running for selective blocking; custom headers store raw SIP header values without regexp extraction or delimiter aggregation; DATABASE INDEX OPTIMIZATION: Custom header columns in cdr_next_X tables are NOT indexed by default to maintain high database write performance - to optimize performance for frequent or large-scale queries on custom SIP headers, manually create a database index by first querying cdr_custom_headers to find dynamic_table and dynamic_column (e.g., header 'X-Custom-Header' stored in cdr_next_2, column custom_header_3), then execute CREATE INDEX idx_custom_header_3 ON cdr_next_2 (custom_header_3) - adding indexes increases database load during CDR insertion so only create indexes on frequently queried headers; use EXPLAIN to verify the database uses your index (type: ref is index lookup, type: ALL is full table scan); if using cdr_partition_by_hours or daily partitioning, index is automatically created on all partitions; sensor SSL settings (ssl_key, ssl_cert, ssl_ipport) can be configured via GUI wrench icon; sensor health monitoring via RRD charts (Settings > Sensors > chart icon) showing buffer usage and packet drops to diagnose sniffer overload vs network quality issues; sensor troubleshooting for non-deletable local sensors in server/probe deployments; sensor troubleshooting for sensors that cannot be deleted due to capture rules - DELETE CAPTURE RULES FIRST; server instance troubleshooting when replacing hardware (server/SBC) and reusing IP address - requires manually creating sensor entry in Settings > Sensors and configuring managerip/managerport in voipmonitor.conf on the new server instance; DISTRIBUTED ARCHITECTURE: Custom headers not visible in central GUI for specific sensor despite being configured - check sensor's server_destination, server_destination_port, and server_password in /etc/voipmonitor.conf; delete sensor entry from GUI Settings > Sensors and restart sniffer service to re-register; without correct server_destination configuration, sensor captures headers locally but does not transmit CDRs to central database; GUI and sensor upgrades behind proxy servers can be configured via Settings > System Configuration > Advanced > Http proxy (for upgrades) or via curlproxy in voipmonitor.conf for remote sensors; license notification emails can be disabled by removing the email address in Settings > License; license email supports multiple recipients by entering email addresses separated by a comma (e.g., user1@example.com,user2@example.com); troubleshooting CDR custom headers not being captured or showing truncated content - check snaplen parameter (increase to 3200 or higher for long SIP headers like STIR/SHAKEN P-Asserted-Identity with verstat parameters) and custom_headers_max_size parameter (increase from default 1024 if header content is truncated); CDR timezone configuration - use "Sensors Timezone" setting in Settings > System Configuration > National to fix CDR times displaying in UTC instead of local timezone; the regular "Timezone" setting is for GUI host (reports, alerts), not for CDR data; all sensors sending data to the same database should use the same timezone; sensor OS timezone can be overridden via timezone or utc options in voipmonitor.conf; INTERNATIONAL NUMBERS CONFIGURATION: For international numbers not displaying or being handled correctly (missing country codes, showing in local format when they should be international, numbers not being classified as international, international calls grouped incorrectly), configure the local number (country name) and international prefix settings in Settings > System Configuration > National; set Local number to your country name (e.g., Australia, United States, Czech Republic); set International prefix to the international dialing prefix for your country (e.g., 0011 for Australia, 011 for US/Canada, 00 for many European countries, 010 for Japan); example: Australia deployment should use Local number = Australia, International prefix = 0011; these settings ensure VoIPmonitor correctly normalizes and displays international numbers based on your local numbering plan.
'''Fix:''' Disable '''Pcap deduplication before download''' in Advanced settings.


'''Keywords:''' GUI settings, sensors, disable sensor, stop sensor, capture rules SKIP, skip CDRs, stop data collection, duplicate records, sensor disabled GUI, CDR custom headers, header limitations, select occurrence, first found value, last found value, custom header occurrence, header multiple occurrences, re-INVITE header capture, initial INVITE header, P-Asserted-Identity re-INVITE, capture first header only, ignore re-INVITE headers, custom header occurrence selection, GeoIP, system configuration, timezone, national prefix, date format, intervals, email settings, license settings, license notification emails, overage notification, multiple recipients, comma-separated emails, LICENSE UPDATE, update license after payment, get/update license key button, Settings > License, license token, license key, retrieve license from portal, voipmonitor.org portal, Services > My services, copy license key, paste license key, multi-line license key, license not received after payment, license update automatically, manual license update, advanced settings, localization, custom URL, CSV export, ssl_key, ssl_cert, ssl_ipport, tls decryption, ssl configuration, pcap deduplication, packet count mismatch, missing packets in PCAP, RRD charts, sensor health monitoring, buffer usage, packet drops, sniffer overload, choppy audio, poor call quality, MOS score, sensor capacity limits, HISTORICAL COMPARISON, From date, adjust From date, compare buffer usage before after, troubleshooting spikes, sudden packetbuffer MEMORY IS FULL, bad MOS scores on one sensor, buffer usage chart sudden increase, server instance troubleshooting, hardware replacement, SBC replacement, reusing IP address, managerip, managerport, server not appearing in GUI, CDR warning about unknown sensor, proxy, http proxy, proxy server, firewall, corporate proxy, GUI upgrade, sensor upgrade, curlproxy, proxy authentication, FIREWALL REQUIREMENTS, firewall whitelist, firewall rules, outbound connections, blocked outbound traffic, network restrictions, voipmonitor.org whitelist, download.voipmonitor.org whitelist, share.voipmonitor.org whitelist, reports.voipmonitor.org whitelist, vm1.voipmonitor.org whitelist, TCP 443, HTTPS outbound, license check cronjob, runUpdateLicenseKey, iptables firewall, network security, firewall blocked, license update firewall, share CDR firewall, debug report firewall, support sessions firewall, custom headers troubleshooting, snaplen, custom_headers_max_size, header capture issues, SIP packet capture, STIR, SHAKEN, P-Asserted-Identity, verstat, truncated headers, long SIP headers, CDR timezone, sensors timezone, UTC time display, BST time display, incorrect CDR times, iframe, embed, X-Frame-Options, clickjacking, GUI in iframe, iframe 301 redirect, ucloud, unite, subfolder, security headers, distributed architecture, custom headers not visible central GUI, sensor not sending CDRs to central database, server_destination, server_destination_port, server_password, delete sensor from GUI, re-register sensor, sensor configuration wrong, headers captured locally not in central GUI, CSRF, ENABLE_CSRF_CHECK, CSRF protection, cross-site request forgery, web security, XSS vulnerability mitigation, session security, security hardening, database index, index custom header, database performance, cdr_custom_headers table, dynamic_table, dynamic_column, CREATE INDEX, query optimization, custom header queries slow, EXPLAIN query, database indexes not indexed by default, partitioned tables index, full table scan, index lookup performance, international numbers, local number, international prefix, country code, international calls display, numbers not displaying correctly, Settings > System Configuration > National, normalize international numbers, Australia 0011, US Canada 011, Europe 00, Japan 010, international number configuration, cannot delete sensor, sensor deletion error, delete sensor failed, pop-up error sensor, sensor capture rules, sensor assigned to capture rule, sensor has capture rules, delete capture rule first, capture rule blocking sensor deletion, non-deletable sensor, sensor deletion troubleshooting, remove capture rule before sensor, referential integrity, orphaned capture rules, migrate capture rules between sensors, reassign capture rules, sensor cleanup, decommission sensor, sensor migration
= See Also =


'''Key Questions:'''
* [[Sniffer_configuration]] - Full voipmonitor.conf reference
* How do I use sensor RRD charts to troubleshoot sudden issues like packetbuffer: MEMORY IS FULL alarms?
* [[Sniffer_distributed_architecture]] - Client-Server mode
* How do I adjust the From date in sensor RRD charts to compare buffer usage before and after the issue started?
* [[Tls]] - TLS/SRTP decryption
* How do I historically compare buffer usage on sensor RRD charts to identify the cause of bad MOS scores?
* [[Data_Cleaning]] - Storage retention
* What does a sudden increase in buffer usage chart indicate on a sensor RRD chart?
* [[User_Management]] - User permissions
* How can I use the buffer usage chart to correlate with error messages like "packetbuffer: MEMORY IS FULL"?
* [[License]] - License management
* How do I check if a single sensor has different buffer usage patterns compared to other sensors?
* How do I diagnose sudden bad MOS scores on one sensor using sensor RRD charts?
* How do I compare buffer usage patterns before and after errors started on sensor RRD charts?
* How do I disable a sensor in the GUI?
* Why is the sensor still collecting data when disabled in the GUI?
* How do I stop a sensor from writing to the database?
* How do I use capture rules with SKIP to stop data collection?
* What is the difference between disabling a sensor in GUI vs systemctl stop?
* How do I prevent duplicate records from a disabled sensor?
* How do I temporarily stop a sensor without SSH access?
* What happens when I click Disable on a sensor in Settings?
* Why does deleting a sensor in GUI not stop data collection?
* How do I stop voipmonitor service on sensor machine?
* Can I use capture rules to selectively stop data from a sensor?
* How do I configure the "select occurrence" field in CDR custom headers?
* What is the difference between "first found value" and "last found value" for custom SIP headers?
* How do I capture only the initial INVITE header and ignore re-INVITEs?
* Why are my custom SIP headers capturing multiple values from re-INVITEs?
* How do I use "select occurrence first found value" to prevent P-Asserted-Identity from being captured from re-INVITEs?
* How do I update my license after payment in VoIPmonitor GUI?
* Where do I click to get/update license key after purchasing a license?
* How do I manually retrieve my license key from the VoIPmonitor portal?
* My license key was not received after payment, what should I do?
* How do I use the get/update license key button in Settings > License?
* Do I need to manually enter the license key after payment?
* How do I paste the full license key content in Settings > License?
* What is the license token field used for in Settings > License?
* How do I copy my license key from voipmonitor.org portal?
* How do I configure sensors in the VoIPmonitor GUI?
* How do I enable CSRF protection in the GUI?
* Where do I find the ENABLE_CSRF_CHECK setting?
* How do I enable CSRF token validation to mitigate XSS vulnerabilities?
* What is ENABLE_CSRF_CHECK and how does it increase session security?
* How do I enable the GUI to run in an iframe?
* How do I fix 301 redirect errors when loading the GUI in an iframe?
* Where is the "Enable GUI to run in iframe" setting located?
* Why does the GUI not load when embedded in an iframe from another application?
* How do I enable iframe support for subfolders like /ucloud or /unite?
* How do I fix CDR times displaying in UTC instead of local timezone?
* Where do I set the sensors timezone for CDR data?
* What is the difference between "Timezone" and "Sensors Timezone" in Settings?
* How do I configure timezone for multiple sensors sending to the same database?
* How do I configure SSL/TLS settings for a sensor using the GUI?
* How do I enable TLS decryption for specific trunks through the web interface?
* Where do I find SSL/TLS parameters (ssl_key, ssl_cert, ssl_ipport) in the GUI?
* How do I access sensor RRD charts for health monitoring?
* How do I check if the sniffer host is overloaded using RRD charts?
* What do buffer usage and packet drops graphs indicate in sensor RRD charts?
* How can I tell if poor call quality is caused by the sniffer host vs network issues?
* What does buffer usage at 100% mean for VoIPmonitor sensor performance?
* How do I delete a non-deletable local sensor in a server/probe deployment?
* Why can I not delete a sensor from the GUI?
* I receive a pop-up error when trying to delete a sensor, what should I do?
* How do I delete a sensor that has capture rules assigned?
* What causes sensor deletion errors in the GUI?
* How do I remove capture rules assigned to a sensor?
* Can I preserve capture rules when deleting a sensor?
* How do I migrate capture rules to a different sensor?
* How do I decommission a sensor with active capture rules?
* What is referential integrity for capture rules?
* How do I clean up old sensors with capture rules?
* How do I remove a sensor that is blocking deletion?
* How do I create and configure CDR custom headers?
* Can I extract part of a SIP header using regexp in custom headers?
* Can I aggregate multiple occurrences of a SIP header?
* What are the limitations of CDR custom headers?
* Why are my custom SIP headers not being captured or showing truncated content?
* How do I capture long SIP headers like P-Asserted-Identity for STIR/SHAKEN?
* What is the snaplen parameter in voipmonitor.conf and how does it affect custom header capture?
* What is the custom_headers_max_size parameter in voipmonitor.conf?
* How do I fix truncated custom header content in the database?
* How do I create alerts based on CDR custom headers?
* How do I add a database index to a custom SIP header for better query performance?
* Why are queries on custom SIP headers slow?
* Are custom header columns in the database indexed by default?
* How do I create a database index on custom_header_3 in cdr_next_2?
* How do I find which table and column stores my custom SIP header?
* What is the cdr_custom_headers table used for?
* How does adding indexes on custom headers affect database performance?
* How do I verify the database is using an index for custom header queries?
* What is the difference between type: ref and type: ALL in EXPLAIN results?
* Should I create indexes on all custom SIP headers?
* How does partitioning affect database indexes on custom headers?
* How do I load GeoIP data for the map view?
* What system configuration options are available?
* How do I set national prefixes and date/time formats?
* What interval settings control CDR and dashboard filters?
* How do I configure GeoIP services?
* How do I create GUI localizations?
* How do I add custom URLs to the CDR view?
* How do I export CDRs to CSV via crontab scheduler?
* Why are custom SIP headers not visible in the central GUI for a specific sensor in a distributed deployment?
* How do I fix custom headers not appearing in central GUI when they capture locally on the sensor?
* Where are server_destination, server_destination_port, and server_password configured in distributed architecture?
* How do I re-register a sensor with the central GUI after configuration changes?
* International numbers are not displaying or being handled correctly - how do I fix this?
* How do I configure local number and international prefix settings in the GUI?
* Where do I set the international dialing prefix for my country in VoIPmonitor?
* What international prefix should I use for Australia?
* What international prefix should I use for United States or Canada?
* What international prefix should I use for European countries?
* How do I configure VoIPmonitor for Australian international number display?
* What is the local number setting used for in Settings > System Configuration > National?
* International calls are grouped incorrectly - what settings need to be configured?
* Country codes are missing from displayed numbers - how do I fix this?
* When should I delete and recreate a sensor entry in Settings > Sensors?
* 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?
* Where do I configure license notification email addresses?
* How do I configure multiple recipients for license expiry notification emails?
* How do I stop receiving license issue and overage notification emails?
* What should I do if a server/SBC does not appear in the GUI after replacing hardware and reusing the IP address?
* How do I manually create a server instance entry in the GUI?
* What are managerip and managerport configuration options in voipmonitor.conf?
* After replacing a server/SBC, why does data appear in CDRs with warnings but the sensor is not visible in Settings > Sensors?
* How do I configure network connectivity for server instances that connect directly to MySQL database?
* Can I switch from the old server instance architecture to modern Client-Server mode?
* How do I configure HTTP proxy for GUI and sensor upgrades?
* Where is the Http proxy (for upgrades) setting in the GUI?
* How do I configure proxy server in Settings > System Configuration?
* How do I fix GUI upgrade failures behind a corporate proxy or firewall?
* How do I configure curlproxy for remote sensors?
* What is the format for HTTP proxy configuration in VoIPmonitor?
* What domains does VoIPmonitor need to access for normal operation?
* How do I configure firewall to allow outbound VoIPmonitor connections?
* What outbound network access is required for VoIPmonitor license updates?
* What ports need to be open for VoIPmonitor to download updates?
* Why does VoIPmonitor fail to update license key after I installed it?
* Which VoIPmonitor domains should be whitelisted in the firewall?
* What are the firewall requirements for VoIPmonitor Share CDR feature?
* What outbound domains does VoIPmonitor need for generating debug reports?
* How do I configure firewall rules for VoIPmonitor support sessions?
* What happens if firewall blocks outbound connections from VoIPmonitor?
* How do I whitelist voipmonitor.org in the firewall for license updates?
* How do I whitelist download.voipmonitor.org for GUI and sniffer upgrades?
* How do I whitelist share.voipmonitor.org for Share CDR feature?
* How do I whitelist reports.voipmonitor.org for debug report uploads?
* How do I whitelist vm1.voipmonitor.org for support sessions?
* What IP addresses does VoIPmonitor use for license checks and updates?
* What IP address is vm1.voipmonitor.org?
* How do I configure iptables to allow outbound HTTPS to VoIPmonitor servers?
* What is the license check cronjob and how does it work?
* How do I manually trigger VoIPmonitor license check?
* What is the run.php runUpdateLicenseKey command for?
* How often does VoIPmonitor check license expiration?
* Does VoIPmonitor work without internet access?
* Does VoIPmonitor work offline without network connectivity?
* What are the alternatives to direct outbound connections for VoIPmonitor?
* Can I use VoIPmonitor with all outbound connections blocked by firewall?
* How do I do offline license activation in VoIPmonitor?

Latest revision as of 16:09, 19 January 2026


This page documents the configuration options available in the VoIPmonitor web GUI under the Settings menu.

Sensors

Configure sensor connections for multi-sensor deployments. Required when id_sensor is set in /etc/voipmonitor.conf.

Field Description
Sensor ID Numeric ID matching id_sensor in voipmonitor.conf
Name Descriptive name for the sensor
Manager IP IP address (or hostname) for fetching data (PCAP, audio files)
Manager Port TCP port for manager API (default: 5029)
Remote database Database connection for "Legs by CID/header" lookups when sensors use different databases

Multi-Sensor Deployment

Setup:

  1. Set unique id_sensor in each sensor's /etc/voipmonitor.conf
  2. Add sensor entries in Settings > Sensors with matching Sensor ID
  3. Restart sensors: systemctl restart voipmonitor

💡 Tip: For sensors with dynamic IPs, enter a hostname in the Manager IP field, or use Client-Server mode.

Sensor Configuration via Wrench Icon

Click the wrench icon next to a sensor to configure parameters. Use the search field to find settings.

Parameter Description Values
ssl Enable TLS decryption yes / no
ssl_ipport IP:port and key path for TLS 192.168.1.10:5061 /path/to/key.pem
sipport SIP ports to capture 5060,5080 or 5060,5070-5080
savertp RTP recording mode yes (full), no (none), header (stats only)
maxpoolrtpsize Max RTP storage in MB 51200
maxpoolrtpdays Max RTP age in days 30

⚠️ Warning: GUI settings override voipmonitor.conf when mysqlloadconfig is enabled (default). Changes require a full restart (systemctl stop/start), not reload.

For TLS decryption with PFS ciphers, see TLS Decryption Guide.

RRD Health Charts

Click the chart icon next to a sensor to view performance metrics:

  • Buffer usage: Approaching 100% indicates capacity limits
  • Packet drops: Non-zero values indicate sensor overload

ℹ️ Note: High buffer/drops cause low MOS and choppy audio. Solutions: increase ringbuffer in config, add sensors, use DPDK or Napatech.

Disabling a Sensor

⚠️ Warning: The GUI "Disabled" checkbox does NOT stop data collection. The sniffer continues running regardless of GUI status.

To stop data collection:

  • Complete shutdown: systemctl stop voipmonitor on the sensor host
  • Selective blocking: Create capture rule with Skip = ON in Control Panel > Capture Rules

Deleting Sensors

If deletion fails, the sensor likely has capture rules assigned. Remove rules first via Control Panel > Capture Rules.

Non-deletable local sensor (GUI+DB only servers):

On central servers that don't capture traffic, an auto-created "localhost" sensor may appear. To replace it:

  1. Set id_sensor = 1 in /etc/voipmonitor.conf on the central server
  2. In GUI: Add new sensor with Manager IP 127.0.0.1, same Sensor ID, Port 5029
  3. Enable "is server in client/server mode" checkbox
  4. Disable "show active calls from all sensors in active call view" checkbox

CDR Charts

Define predefined charts for the CDR detail Charts tab.

CDR Custom Headers

Capture and display custom SIP headers in CDR views. Requires sniffer version 7.0RC7+.

Setup Workflow

  1. Add header to /etc/voipmonitor.conf:
custom_headers = X-Cisco-Org-ID
  1. Restart sensor: systemctl restart voipmonitor
  2. Generate a test call
  3. Configure in Settings > CDR Custom Headers: select header, set Name, enable "Show as Column"

Configuration Fields

Field Description
Header Field SIP header to capture (from dropdown after restart)
Name Display label in GUI
Match in SIP by Header Enable for Legs by header correlation
Show as Column Display in CDR list view
Restrict to Regex pattern Filter which values to capture
Boundary start/end Extract substring between delimiters
Regexp Extract using regex with capture groups (...)
Select occurrence First found value, Last found value, or Nth occurrence
Nth occurrence (New in 2026.01) When "Nth occurrence" is selected, specify which occurrence number to extract (e.g., 2 for second occurrence). Uses packet timestamps for accurate ordering even when packet reordering is disabled.

Extracting Substrings

Boundary method (recommended): Extract between delimiters.

Example: From sip:1000@192.168.1.1;tag=123, extract IP:

  • Boundary start: @
  • Boundary end: ;
  • Result: 192.168.1.1

Regexp method: Use capture groups for complex patterns. 

# Extract version from: User-Agent: Asterisk/20.6.0
Regexp: Asterisk/([0-9.]+)
Result: 20.6.0

⚠️ Warning: Regexp MUST include parentheses (...) to define what to capture. Without them, the entire match is stored.

Filtering by SIP Method and Response Code

You can filter custom header extraction to specific SIP methods (e.g., INVITE) or SIP response codes (e.g., 300, 404).

Field Description Example Usage
CSeq method Filter by SIP request method INVITE to capture only from INVITE requests
response code Filter by SIP response code number 300 to capture only from 300 redirect responses

Example: Extract Contact IP from 300 Redirect Responses

To filter CDRs for calls involving SIP 300 redirect responses and identify the redirect destination IP:

  1. Navigate to Settings > Custom headers > CDR in the GUI
  2. Click Add new
  3. Set Header field to Contact
  4. Set Name to descriptive label (e.g., SIP300RedirectDestinations)
  5. Set Regexp to sip:.*@([0-9]+\.[0-9]+\.[0-9]+\.[0-9]+); to extract the IP address
  6. Set CSeq method to INVITE
  7. Set response code to 300
  8. Save the configuration

Use the new custom header and Last SIP response code as filters in the CDR list to identify calls with 300 redirects and their destinations.

💡 Tip: The CSeq method and response code fields allow you to capture headers from specific SIP messages rather than all headers in the call.

Database Index for Custom Headers

Custom header columns are not indexed by default. For frequent queries: 

-- Find table/column location
SELECT dynamic_table, dynamic_column FROM cdr_custom_headers
WHERE header_field = 'X-Custom-Header';

-- Create index (use values from above query)
CREATE INDEX idx_custom_header_3 ON cdr_next_2 (custom_header_3);

Troubleshooting Custom Headers

Problem Solution
Header not captured Increase snaplen in voipmonitor.conf (default may be too low)
Header truncated Increase custom_headers_max_size (default: 1024 bytes)
Not visible in distributed setup Check server_destination and server_password on sensor

Verify loaded headers: echo 'custom_headers_dump cdr' | nc localhost 5029

Load GeoIP Data

Loads GeoIP data for the CDR Map tab. See Order_of_GeoIP_processing for processing priority.

System Configuration

Basic

Setting Description
WEB URL Base URL for hyperlinks in emails
Sniffer data path PCAP storage directory (default: /var/spool/voipmonitor)
Sniffer second datapath Secondary spool directory (spooldir_2)
Default sensor hostname Default hostname for sniffer connection
Default sensor TCP port Default manager API port (5029)

⚠️ Warning: If sensors connect to wrong destination after upgrade, disable Default sensor hostname and Default sensor TCP port in this section. When enabled, sensors ignore individual Manager IP/Port settings.

Database

MySQL/MariaDB connection settings.

Custom port: Enter host with port in MySQL hostname field: 127.0.0.1:33306

Also configure mysqlport in /etc/voipmonitor.conf. See Database_troubleshooting for details.

National

Setting Description
Timezone GUI host timezone (for reports/alerts scheduling)
Sensors Timezone CDR display timezone - set this to fix UTC display issues
National prefix Prefixes for national call classification
International prefix International dialing prefix (e.g., 00, 011)
Local number Country name for number normalization

💡 Tip: If CDRs display in UTC instead of local time, set Sensors Timezone (not regular Timezone) to your sensors' timezone.

Intervals

Default time filters for CDR view, dashboard, and Legs correlation.

Email / HTTP Referer

Setting Description
DEFAULT_EMAIL_FROM Default "From" address for outgoing emails
Disable email plain text Force HTML-only emails


Troubleshooting Email Delivery

If users report not receiving verification emails or new user setup emails, verify the email sending status:

For Exim mail servers: 

# Check Exim mail log for delivery attempts
grep "recipient@example.com" /var/log/exim/main.log

# Or search by timestamp
grep "2025-01-09 14:30:" /var/log/exim/main.log

Look for the response code in the log entry:

  • 250 message accepted - Email was successfully delivered to remote server. The issue is on the recipient side (spam folder, quarantine, mail filtering).
  • No 250 code - Email delivery failed at the server level. Check mail queue and server MTA configuration.

If logs confirm successful delivery: Inform the client that the email left the server successfully and advise them to check their Spam, Bulk, or Junk folders, or consult their internal IT team regarding mail filtering policies.

General MTA verification: 

# Check if mail agent is running
systemctl status postfix     # or exim4, sendmail

# Test email from command line
echo "Test message" | mail -s "VoIPmonitor Test" your@email.com

# Check mail queue
mailq

# View general mail logs
tail -f /var/log/mail.log     # Debian/Ubuntu
tail -f /var/log/maillog      # RHEL/CentOS

License

Setting Description
License token Short token for retrieving license from portal
License key Full license key content (multi-line)
License email Email for license notifications (leave empty to disable)

Update license after payment: Click get/update license key button.

Manual activation: Copy full license key from portal (Services > My services) and paste into License key field.

Disable notification emails: Remove email from "License email" field.

GeoIP

Configure API keys for MaxMind or IPInfoDB services.

Advanced

Setting Description
ENABLE_CSRF_CHECK Enable CSRF protection (recommended for production)
Pcap deduplication before download Remove duplicate packets from PCAP downloads
Http proxy (for upgrades) Proxy for GUI/sniffer upgrades: http://proxy:port
Enable GUI to run in iframe Allow embedding in iframes (disabled by default for security)
CDR share key Secret for CDR share URLs
Always enable 2FA dialog (New in 2026.1) Always show 2FA input field in login dialog, even for users without 2FA enabled. Useful for external authentication systems that require 2FA code.
DISABLE_FAX (New in 2026.1) Disables fax (T.38) file downloading from the GUI.

Firewall requirements: Allow outbound HTTPS to:

  • voipmonitor.org - License updates
  • download.voipmonitor.org - Software upgrades
  • share.voipmonitor.org - CDR sharing
  • reports.voipmonitor.org - Debug reports

Batch Download Filename Format

Location: GUI > Settings > System Configuration > Advanced > Set the format of the filename for saving

Controls the filename pattern for PCAP/audio files in batch download ZIP archives.

Available placeholders:

Placeholder Description Example
{date} Call date 2024-09-27
{time} Call time 12-32-49
{caller} Caller number 55555
{called} Called number 555444333222111
{id} CDR ID ID5
{callid} (New in 2026.1) SIP Call-ID string abc123@192.168.1.1

Default format: {date}_{time}_{caller}_{called}_{id}

Example output: 2024-09-27_12-32-49_55555_555444333222111__ID5.pcap

With Call-ID: {date}_{time}_{callid}_{id} → 2024-09-27_12-32-49_abc123@192.168.1.1_ID5.pcap


Security Settings

Location: Add to php/system_configuration.php (persists after GUI System Configuration changes) 

<?php
define('ENABLE_CSRF_CHECK', true);
define('ENABLE_POST_METHOD_CHECK', true);
Setting Default Description
ENABLE_CSRF_CHECK false (Recommended) Enables CSRF token validation for state-changing requests. Protects against Cross-Site Request Forgery attacks where malicious websites could execute actions on behalf of authenticated users.
ENABLE_POST_METHOD_CHECK false (Recommended) Enforces POST method for state-changing operations. Prevents attacks via GET requests (e.g., password change via malicious link).

⚠️ Warning: For production environments, both settings should be enabled to protect against account takeover attacks (CVSS 7.5). Without these protections, an attacker could change user passwords or 2FA settings via CSRF.

Why system_configuration.php? Settings in configuration.php are overwritten when System Configuration is saved via GUI. Place security settings in system_configuration.php to ensure they persist.

New in 2026.1

Localization

Create GUI translations. Red numbers indicate untranslated items. Changes apply after logout/login.

CDR View Custom URL

Add custom hyperlinks to CDR Commands column. Use {{paramName}} in URL to include CDR values.

Troubleshooting

Sensors Connect to Wrong Destination After Upgrade

Cause: Default sensor hostname/port settings override individual sensor configurations.

Fix: Disable Default sensor hostname and Default sensor TCP port in Settings > System Configuration > Basic.

GUI Crashes on Settings > Sensors Page

Cause: Too many obsolete sensor records in database.

Fix: Delete obsolete records directly: 

-- Check count
SELECT COUNT(*) FROM sensors;
-- Delete obsolete entries (adjust WHERE clause)
DELETE FROM sensors WHERE host LIKE '%old-sensor%';

All users must log out and back in after cleanup.

License Update Fails

Cause: Firewall blocking outbound HTTPS.

Fix: Allow outbound TCP 443 to voipmonitor.org, or configure HTTP proxy in Advanced settings, or use offline activation.

GUI Not Loading in iframe

Fix: Enable Enable GUI to run in iframe in Advanced settings.

PCAP Download Has Fewer Packets Than GUI Shows

Cause: Pcap deduplication is enabled (removes retransmissions).

Fix: Disable Pcap deduplication before download in Advanced settings.

See Also

Retrieved from "https://www.voipmonitor.org/doc/index.php?title=Settings&oldid=10804"