Settings: Difference between revisions

From VoIPmonitor.org
(Add documentation for multiple email recipients in License settings (comma-separated addresses))
(Add Security Settings documentation for CSRF and POST method protection (VG-3065))
 
(48 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 ==


=== SSL/TLS Configuration ===
<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>


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).
'''Setup:'''


To configure SSL/TLS settings for a sensor:
# 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>


# Navigate to '''Settings > Sensors'''
{{Tip|For sensors with dynamic IPs, enter a hostname in the Manager IP field, or use [[Sniffer_distributed_architecture|Client-Server mode]].}}
# Click the '''wrench icon''' next to the affected sensor
 
# In the search field at the top right of the sensor settings dialog, enter '''ssl_'''
== Sensor Configuration via Wrench Icon ==
# Configure the required SSL/TLS parameters:
 
Click the '''wrench icon''' next to a sensor to configure parameters. Use the search field to find settings.


{| class="wikitable"
{| class="wikitable"
|-
|-
! Parameter !! Description !! Example Value
! Parameter !! Description !! Values
|-
| ssl_key || Path to the private key file (PEM format) for decrypting TLS traffic || <code>/etc/pki/tls/private/server.key</code>
|-
|-
| ssl_cert || Path to the SSL certificate file (PEM format) matching the private key || <code>/etc/pki/tls/certs/server.crt</code>
| <code>ssl</code> || Enable TLS decryption || <code>yes</code> / <code>no</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>ssl_ipport</code> || IP:port and key path for TLS || <code>192.168.1.10:5061 /path/to/key.pem</code>
|-
|-
| ssl || Enable SSL/TLS decryption module on the sensor || <code>yes</code>
| <code>sipport</code> || SIP ports to capture || <code>5060,5080</code> or <code>5060,5070-5080</code>
|}
 
'''Important Notes:'''
 
* The sensor SSL settings correspond to the configuration parameters in [[Tls|/etc/voipmonitor.conf]] but are managed through the GUI interface
* 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
* 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:'''
 
* You prefer managing TLS/SSL settings through the web interface instead of editing config files
* 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]].
 
=== Sensor Health Monitoring with RRD Charts ===
 
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.
 
**Accessing Sensor RRD Charts:**
 
# Navigate to '''Settings > Sensors'''
# 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:**
 
{| class="wikitable"
|-
|-
! Metric !! Description !! What It Indicates
| <code>savertp</code> || RTP recording mode || <code>yes</code> (full), <code>no</code> (none), <code>header</code> (stats only)
|-
|-
| Buffer usage || Shows the percentage of available packet buffer being used || Sensor is approaching capacity limits if consistently high
| <code>maxpoolrtpsize</code> || Max RTP storage in MB || <code>51200</code>
|-
|-
| Packet drops || Counts of packets the sensor could not process || Sensor is overloaded and dropping packets due to high traffic load
| <code>maxpoolrtpdays</code> || Max RTP age in days || <code>30</code>
|}
|}


**Interpreting the Charts:**
{{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.}}


If you observe:
For TLS decryption with PFS ciphers, see [[Tls|TLS Decryption Guide]].
* '''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:
== RRD Health Charts ==
* Low MOS scores
* Choppy audio playback in the GUI
* Missing call data


**Solutions for Sensor Overload:**
Click the '''chart icon''' next to a sensor to view performance metrics:


* 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.
* '''Buffer usage:''' Approaching 100% indicates capacity limits
* Add more sensors to distribute the load ([[Sniffer_distributed_architecture|Distributed Architecture]])
* '''Packet drops:''' Non-zero values indicate sensor overload
* 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


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


Use RRD charts to diagnose sensor overload when:
== Disabling a Sensor ==
* 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


This diagnostic step helps distinguish between network quality issues (jitter, loss in the actual VoIP path) vs. sniffer capacity issues (capturing host overload).
{{Warning|1=The GUI "Disabled" checkbox does NOT stop data collection. The sniffer continues running regardless of GUI status.}}


=== Troubleshooting: Non-deletable Local Sensor ===
'''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'''


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.
== Deleting Sensors ==


'''Workaround:'''
If deletion fails, the sensor likely has capture rules assigned. Remove rules first via '''Control Panel > Capture Rules'''.
# 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.
'''Non-deletable local sensor (GUI+DB only servers):'''


=== Troubleshooting: Server Instance Not Appearing in GUI ===
On central servers that don't capture traffic, an auto-created "localhost" sensor may appear. To replace it:


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.
# Set <code>id_sensor = 1</code> in <code>/etc/voipmonitor.conf</code> on the central server
# In GUI: Add new sensor with Manager IP <code>127.0.0.1</code>, same Sensor ID, Port <code>5029</code>
# Enable "is server in client/server mode" checkbox
# Disable "show active calls from all sensors in active call view" checkbox


=== Problem: Sensor Appears in CDRs With Warning But Not in GUI List ===
= CDR Charts =


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:
Define predefined charts for the [[Call_Detail_Record_-_CDR#Charts|CDR detail Charts tab]].
* 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 ===
= CDR Custom Headers =


If your deployment uses server instances that connect directly to the MySQL database, follow these steps:
Capture and display custom SIP headers in CDR views. Requires sniffer version 7.0RC7+.


'''Step 1: Create the server instance entry in the GUI'''
== Setup Workflow ==


# Navigate to '''Settings > Sensors'''
<kroki lang="mermaid">
# Click '''Add new sensor''' or '''New sensor'''
%%{init: {'flowchart': {'nodeSpacing': 10, 'rankSpacing': 30}}}%%
# Configure the following fields:
flowchart LR
** Sensor ID: Enter a unique identifier (e.g., <code>2</code>)
    A[voipmonitor.conf<br/>custom_headers] --> B[Restart Sensor]
** Name: Descriptive name for the server instance (e.g., <code>SBC-Production</code>)
    B --> C[DB Column Created]
** Manager IP: IP address of the server instance (the new hardware's IP)
    C --> D[Settings > CDR<br/>Custom Headers]
** Manager Port: TCP port for the manager connection (default: <code>5029</code>)
    D --> E[CDR List View]
 
</kroki>
'''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:


# Add header to <code>/etc/voipmonitor.conf</code>:
<syntaxhighlight lang="ini">
<syntaxhighlight lang="ini">
# On the new server instance (/etc/voipmonitor.conf)
custom_headers = X-Cisco-Org-ID
managerip  = gui.server.ip    # GUI server IP address
managerport = 5029            # Manager API port (matches GUI Manager Port)
</syntaxhighlight>
</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"


Restart the voipmonitor service after making changes:
== Configuration Fields ==


<syntaxhighlight lang="bash">systemctl restart voipmonitor</syntaxhighlight>
{| class="wikitable"
|-
! 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>
|-
| Select occurrence || <code>First found value</code>, <code>Last found value</code>, or <code>Nth occurrence</code>
|-
| 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.
|}


'''Step 3: Verify network connectivity'''
== Extracting Substrings ==


Ensure bidirectional network connectivity:
'''Boundary method (recommended):''' Extract between delimiters.


* '''GUI host → Server instance:''' GUI must be able to reach the server instance on the configured Manager IP/Port (for data retrieval and control)
Example: From <code>sip:1000@192.168.1.1;tag=123</code>, extract IP:
* '''Server instance → MySQL database:''' Server instance must be able to write CDRs to the MySQL database
* Boundary start: <code>@</code>
* Boundary end: <code>;</code>
* Result: <code>192.168.1.1</code>


Test connectivity from both directions:
'''Regexp method:''' Use capture groups for complex patterns.


<syntaxhighlight lang="bash">
<syntaxhighlight lang="text">
# From GUI host to server instance (verify Manager IP/Port)
# Extract version from: User-Agent: Asterisk/20.6.0
nc -zv server.instance.ip 5029
Regexp: Asterisk/([0-9.]+)
 
Result: 20.6.0
# From server instance to MySQL database
mysql -h mysql.server.ip -u voipmonitor -p voipmonitor -e "SELECT 1"
</syntaxhighlight>
</syntaxhighlight>


Check firewall rules on both systems to ensure:
{{Warning|1=Regexp MUST include parentheses <code>(...)</code> to define what to capture. Without them, the entire match is stored.}}
* 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'''
== Filtering by SIP Method and Response Code ==


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.
You can filter custom header extraction to specific SIP methods (e.g., INVITE) or SIP response codes (e.g., 300, 404).


=== Alternative: Using Modern Client-Server Mode ===
{| class="wikitable"
 
|-
If you are planning a new deployment or can reconfigure your architecture, consider using the modern [[Sniffer_distributed_architecture|Client-Server mode]] which provides:
! Field !! Description !! Example Usage
 
|-
* Encrypted TCP connections between sensors and central server
| CSeq method || Filter by SIP request method || <code>INVITE</code> to capture only from INVITE requests
* Automatic sensor registration (no manual GUI entry required)
|-
* Simplified firewall configuration (single port: 60024 by default)
| response code || Filter by SIP response code number || <code>300</code> to capture only from 300 redirect responses
 
|}
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]]
=== Example: Extract Contact IP from 300 Redirect Responses ===


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


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


[[File:customheaderform.png]]
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.


=== Configuration Fields ===
{{Tip|The CSeq method and response code fields allow you to capture headers from specific SIP messages rather than all headers in the call.}}


;Header Field
== Database Index for Custom Headers ==
: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
Custom header columns are not indexed by default. For frequent queries:
:The display name for this header in the CDR view header panel.


;Match in SIP by Header
<syntaxhighlight lang="sql">
: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.
-- Find table/column location
SELECT dynamic_table, dynamic_column FROM cdr_custom_headers
WHERE header_field = 'X-Custom-Header';


;Show as Column
-- Create index (use values from above query)
:When enabled, displays this header as a column in the CDR list view.
CREATE INDEX idx_custom_header_3 ON cdr_next_2 (custom_header_3);
 
=== Apply Configuration Changes ===
 
'''Important: Restart Required'''
 
After configuring or modifying custom header settings in the GUI, you must '''restart the sensor service''' for the changes to take effect. The restart applies the new configuration so that the sensor begins capturing and storing custom SIP headers as specified.
 
To restart the sensor:
<syntaxhighlight lang="bash">
# Using systemd
systemctl restart voipmonitor
 
# Using init scripts
/etc/init.d/voipmonitor restart
</syntaxhighlight>
</syntaxhighlight>


After restarting, generate new test calls to verify that the custom header is being captured and stored correctly in the database.
== Troubleshooting Custom Headers ==
 
[[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.
 
=== Limitations ===
 
The GUI custom header feature has the following limitations:


{| class="wikitable"
{| class="wikitable"
|-
|-
! Limitation !! Description
! Problem !! Solution
|-
|-
| '''No Regexp extraction''' || Custom headers store the '''complete raw header value'''. There is no option to extract portions using regular expressions (e.g., extracting just an IP address from a SIP URI).
| Header not captured || Increase <code>snaplen</code> in voipmonitor.conf (default may be too low)
|-
|-
| '''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).
| Header truncated || Increase <code>custom_headers_max_size</code> (default: 1024 bytes)
|-
|-
| '''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.).
| Not visible in distributed setup || Check <code>server_destination</code> and <code>server_password</code> on sensor
|}
|}


For advanced header extraction needs, contact VoIPmonitor support to discuss custom development or alternative approaches such as external PCAP processing.
Verify loaded headers: <code>echo 'custom_headers_dump cdr' | nc localhost 5029</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.
= Load GeoIP Data =


[[File:settiongs-loadgeoip.png]]
Loads GeoIP data for the [[Call_Detail_Record_-_CDR#Map|CDR Map tab]]. See [[Order_of_GeoIP_processing]] for processing priority.


== System Configuration ==
= System Configuration =


The System Configuration section contains core settings that affect the overall behavior of the GUI.
== Basic ==
 
=== Basic ===
 
[[File:settings-sysbasic.png]]


{| class="wikitable"
{| class="wikitable"
Line 290: Line 246:
! Setting !! Description
! Setting !! Description
|-
|-
| WEB URL || Base URL for the GUI, used in hypertext links (e.g., in email alerts)
| WEB URL || Base URL for hyperlinks in emails
|-
|-
| Sniffer data path || Directory where sniffer stores data (default: <code>/var/spool/voipmonitor</code>)
| Sniffer data path || PCAP storage directory (default: <code>/var/spool/voipmonitor</code>)
|-
|-
| Default sensor hostname || Default hostname for connecting to the sniffer (default: localhost). For multiple sensors, configure them in Settings > Sensors
| Sniffer second datapath || Secondary spool directory (<code>spooldir_2</code>)
|-
|-
| Default sensor TCP port || Default TCP port for the manager API (default: 5029)
| Default sensor hostname || Default hostname for sniffer connection
|-
| Default sensor TCP port || Default manager API port (5029)
|}
|}


=== Database ===
{{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.}}


Configuration for the MySQL/MariaDB database connection used by the GUI.
== Database ==


[[File:settings-sysdb.png]]
MySQL/MariaDB connection settings.


=== National ===
'''Custom port:''' Enter host with port in MySQL hostname field: <code>127.0.0.1:33306</code>


Settings for localizing call classification and date/time display formats.
Also configure <code>mysqlport</code> in <code>/etc/voipmonitor.conf</code>. See [[Database_troubleshooting]] for details.


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


{| class="wikitable"
{| class="wikitable"
Line 315: Line 273:
! Setting !! Description
! Setting !! Description
|-
|-
| Timezone || Server timezone (format: Country/City, e.g., Europe/Prague)
| Timezone || GUI host timezone (for reports/alerts scheduling)
|-
|-
| National prefix, 2, 3 || Prefixes used to classify calls as national vs. international (used in [[Active_calls|Active calls]] view)
| '''Sensors Timezone''' || '''CDR display timezone''' - set this to fix UTC display issues
|-
|-
| Max national number length || Numbers longer than this are classified as international regardless of prefix
| National prefix || Prefixes for national call classification
|-
|-
| 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]
| International prefix || International dialing prefix (e.g., <code>00</code>, <code>011</code>)
|-
|-
| 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]
| Local number || Country name for number normalization
|-
| Week start || First day of the week for calendar displays
|}
|}


=== Intervals ===
{{Tip|1=If CDRs display in UTC instead of local time, set '''Sensors Timezone''' (not regular Timezone) to your sensors' timezone.}}
 
Default time intervals for various GUI views and filters.
 
[[File:settings-sysintervals.png]]
 
{| class="wikitable"
|-
! 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
|-
| Default CDR interval in days || Number of days for the CDR filter (only editable if above is set to "specified number of days")
|-
| Default dashboard interval || Default time filter when entering the dashboard
|-
| 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 ===
== Intervals ==


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


[[File:settings-sysemailhttpreferer.png]]
== Email / HTTP Referer ==


{| class="wikitable"
{| class="wikitable"
Line 361: Line 298:
| DEFAULT_EMAIL_FROM || Default "From" address for outgoing emails
| 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)
| Disable email plain text || Force HTML-only emails
|}
|}


=== License ===


License and notification email configuration.


[[File:settings-syslicense.png]]
=== Troubleshooting Email Delivery ===


{| class="wikitable"
If users report not receiving verification emails or new user setup emails, verify the email sending status:
|-
! Setting !! Description
|-
| License email || Email address for receiving license issue and overage notification emails
|}


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


'''Disabling License Notification Emails:'''
# Or search by timestamp
grep "2025-01-09 14:30:" /var/log/exim/main.log
</syntaxhighlight>


To stop receiving license issue and overage notification emails:
Look for the response code in the log entry:
# Navigate to '''Settings > License'''
* <code>250 message accepted</code> - Email was successfully delivered to remote server. The issue is on the recipient side (spam folder, quarantine, mail filtering).
# Remove the email address from the "License email" field
* No <code>250</code> code - Email delivery failed at the server level. Check mail queue and server MTA configuration.
# 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.
<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.


=== GeoIP ===
<b>General MTA verification:</b>
<syntaxhighlight lang="bash"># Check if mail agent is running
systemctl status postfix    # or exim4, sendmail


Configuration for GeoIP services used in the CDR Map view.
# Test email from command line
echo "Test message" | mail -s "VoIPmonitor Test" your@email.com


[[File:settings-sysgeoip.png]]
# Check mail queue
mailq
 
# View general mail logs
tail -f /var/log/mail.log    # Debian/Ubuntu
tail -f /var/log/maillog      # RHEL/CentOS
</syntaxhighlight>
== License ==


{| class="wikitable"
{| class="wikitable"
Line 398: Line 341:
! Setting !! Description
! Setting !! Description
|-
|-
| Use GeoIP local database || Enable/disable the internal GeoIP database (if loaded via [[#Load_GeoIP_Data|Load GeoIP Data]])
| License token || Short token for retrieving license from portal
|-
|-
| GeoIP maxmind.com KEY || API key for MaxMind GeoIP service
| License key || Full license key content (multi-line)
|-
|-
| GeoIP ipinfodb.com KEY || API key for IPInfoDB service
| License email || Email for license notifications (leave empty to disable)
|}
|}


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


Advanced configuration options for power users and specific use cases.
== GeoIP ==


[[File:settings-sysadvanced.png]]
Configure API keys for MaxMind or IPInfoDB services.
 
== Advanced ==


{| class="wikitable"
{| class="wikitable"
Line 415: Line 364:
! Setting !! Description
! Setting !! Description
|-
|-
| Enable CDR group panel || Show/hide the group panel at the bottom of the CDR view
| ENABLE_CSRF_CHECK || Enable CSRF protection (recommended for production)
|-
|-
| ENABLE_CDR_FORCE_INDEX_CALLDATE || Force use of the calldate index on CDR queries. Enable only for unoptimized MySQL installations experiencing slow queries
| Pcap deduplication before download || Remove duplicate packets from PCAP downloads
|-
|-
| Enable database IP reverse lookup || Resolve IP addresses to names using the internal IP lookup table
| Http proxy (for upgrades) || Proxy for GUI/sniffer upgrades: <code>http://proxy:port</code>
|-
|-
| Enable DNS reverse lookup || Resolve IP addresses to names using DNS
| Enable GUI to run in iframe || Allow embedding in iframes (disabled by default for security)
|-
|-
| Enable database number lookup || Resolve phone numbers to names using the internal prefix lookup table
| CDR share key || Secret for CDR share URLs
|-
|-
| Disable rtpfirstleg param || Disable the <code>--rtp-firstleg</code> parameter for PCAP audio decoding. Enable only if experiencing audio issues
| 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 URL wav protection || Skip session authentication for WAV file downloads. Use with '''WAV download key''' for secure external access
| DISABLE_FAX || '''(New in 2026.1)''' Disables fax (T.38) file downloading from the GUI.
|}
 
'''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 ===
 
'''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:'''
{| class="wikitable"
|-
|-
| WAV download key || Secret key required for WAV downloads when URL protection is disabled
! Placeholder !! Description !! Example
|-
|-
| Hide SIP domain in CDR || Hide SIP domains in the CDR display
| <code>{date}</code> || Call date || <code>2024-09-27</code>
|-
|-
| Hide live play || Hide live playback buttons in [[Active_calls|Active calls]]
| <code>{time}</code> || Call time || <code>12-32-49</code>
|-
|-
| Hide WAV play || Hide WAV playback buttons in CDR view
| <code>{caller}</code> || Caller number || <code>55555</code>
|-
|-
| Upload sniffer conf path || Path to voipmonitor.conf for PCAP upload functionality
| <code>{called}</code> || Called number || <code>555444333222111</code>
|-
|-
| CDR share key || Secret string used to generate unique hashes for CDR share URLs
| <code>{id}</code> || CDR ID || <code>ID5</code>
|-
|-
| Folder for export CSV || Directory where CSV files from [[Reports#CSV_Export_via_Crontab_Scheduler|crontab scheduler tasks]] are saved
| <code>{callid}</code> || '''(New in 2026.1)''' SIP Call-ID string || <code>abc123@192.168.1.1</code>
|-
|}
| CSV name prefix || Optional prefix for CSV filenames generated by crontab tasks
 
'''Default format:''' <code>{date}_{time}_{caller}_{called}_{id}</code>
 
'''Example output:''' <code>2024-09-27_12-32-49_55555_555444333222111__ID5.pcap</code>
 
'''With Call-ID:''' <code>{date}_{time}_{callid}_{id}</code> → <code>2024-09-27_12-32-49_abc123@192.168.1.1_ID5.pcap</code>
 
 
=== Security Settings ===
 
'''Location:''' Add to <code>php/system_configuration.php</code> (persists after GUI System Configuration changes)
 
<syntaxhighlight lang="php">
<?php
define('ENABLE_CSRF_CHECK', true);
define('ENABLE_POST_METHOD_CHECK', true);
</syntaxhighlight>
 
{| class="wikitable"
|-
|-
| Delete CSV after X days || Auto-delete CSV files older than specified days
! Setting !! Default !! Description
|-
|-
| 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
| <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.
|-
|-
| 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
| <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).
|}
|}


=== Troubleshooting: GUI Upgrades Behind Proxy Servers ===
{{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.}}


If the GUI or sensor upgrade process fails due to network restrictions or firewall blocking direct internet access:
'''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.


'''Solution 1: Configure HTTP Proxy in GUI (Recommended)'''
''New in 2026.1''
# Navigate to '''Settings > System Configuration > Advanced'''
= Localization =
# 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)'''
Create GUI translations. Red numbers indicate untranslated items. Changes apply after logout/login.
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:'''
= CDR View Custom URL =
* [[FAQ#How_do_I_troubleshoot_internet_connectivity_issues|FAQ: Troubleshooting Internet Connectivity]]
* [[GUI_Installation|GUI Installation Guide]]


== Localization ==
Add custom hyperlinks to CDR Commands column. Use <nowiki>{{paramName}}</nowiki> in URL to include CDR values.


Create custom translations for the GUI interface. Localizations are not 100% complete; please report missing translation items.
= Troubleshooting =


[[File:settings-localisationform.png]]
== Sensors Connect to Wrong Destination After Upgrade ==


[[File:settings-localisationgrid.png]]
'''Cause:''' Default sensor hostname/port settings override individual sensor configurations.


* Red numbers indicate untranslated items, which is useful after upgrading to identify new strings
'''Fix:''' Disable '''Default sensor hostname''' and '''Default sensor TCP port''' in Settings > System Configuration > Basic.
* Changes take effect after logout/login


== CDR View Custom URL ==
== GUI Crashes on Settings > Sensors Page ==


Add custom hyperlinks to the CDR view Commands column. This is useful for integrating external monitoring or CRM systems.
'''Cause:''' Too many obsolete sensor records in database.


=== Configuration ===
'''Fix:''' Delete obsolete records directly:
<syntaxhighlight lang="sql">
-- Check count
SELECT COUNT(*) FROM sensors;
-- Delete obsolete entries (adjust WHERE clause)
DELETE FROM sensors WHERE host LIKE '%old-sensor%';
</syntaxhighlight>
All users must log out and back in after cleanup.


Navigate to '''GUI > Settings > CDR view custom URL'''.
== License Update Fails ==


[[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, CDR custom headers with their limitations, 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, and Pcap deduplication before download which can cause packet count mismatches between GUI SIP History and downloaded PCAP files. Key topics: custom headers store raw SIP header values without regexp extraction or delimiter aggregation; 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; 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; 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.
'''Fix:''' Disable '''Pcap deduplication before download''' in Advanced settings.


'''Keywords:''' GUI settings, sensors, CDR custom headers, header limitations, GeoIP, system configuration, timezone, national prefix, date format, intervals, email settings, license settings, license notification emails, overage notification, 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, 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
= See Also =


'''Key Questions:'''
* [[Sniffer_configuration]] - Full voipmonitor.conf reference
* How do I configure sensors in the VoIPmonitor GUI?
* [[Sniffer_distributed_architecture]] - Client-Server mode
* How do I configure SSL/TLS settings for a sensor using the GUI?
* [[Tls]] - TLS/SRTP decryption
* How do I enable TLS decryption for specific trunks through the web interface?
* [[Data_Cleaning]] - Storage retention
* Where do I find SSL/TLS parameters (ssl_key, ssl_cert, ssl_ipport) in the GUI?
* [[User_Management]] - User permissions
* How do I access sensor RRD charts for health monitoring?
* [[License]] - License management
* 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?
* 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?
* How do I create alerts based on CDR 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 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 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?

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"