Settings: Difference between revisions

From VoIPmonitor.org
No edit summary
(Add Security Settings documentation for CSRF and POST method protection (VG-3065))
 
(69 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{DISPLAYTITLE:GUI Settings Reference}}
[[Category:GUI manual]]
This page documents the configuration options available in the VoIPmonitor web GUI under the '''Settings''' menu.
= Sensors =
= Sensors =


If you set id_sensor in /etc/voipmonitor.conf (default is blank) you must create sensor here if you want to download files from sensor like pcap graph wav etc.
Configure sensor connections for multi-sensor deployments. Required when <code>id_sensor</code> is set in <code>/etc/voipmonitor.conf</code>.
 
{| class="wikitable"
|-
! Field !! Description
|-
| Sensor ID || Numeric ID matching <code>id_sensor</code> 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 ==


*Sensor ID: number defined in /etc/voipmonitor.conf id_sensor = N
<kroki lang="mermaid">
*Name: name of the sensor
%%{init: {'flowchart': {'nodeSpacing': 15, 'rankSpacing': 40}}}%%
*Manager IP, Port: used for fetching data, such as pcap / graph files. Default port is 5029
flowchart TB
*Remote database parameter: this is useful only in case each sensor writes to different database and you want to find relevant legs in the “Legs by [CID|header]” CDR detail tab. If your sensors writes to the same database leave it blank.
    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>


[[File:settings-sensors.png]]
'''Setup:'''


= CDR charts =
# 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>


Predefined charts used in [[Call_Detail_Record_-_CDR#Charts|CDR detail charts section]]
{{Tip|For sensors with dynamic IPs, enter a hostname in the Manager IP field, or use [[Sniffer_distributed_architecture|Client-Server mode]].}}


[[File:settings-cdrcharts.png]]
== Sensor Configuration via Wrench Icon ==


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


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


Since VoIPmonitor sniffer version 7.0RC7 there is new feature [[Sniffer_configuration#custom_headers]] allowing storing custom SIP headers to database - view it and search by it.  
{{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.}}


[[File:customheaderform.png]]
For TLS decryption with PFS ciphers, see [[Tls|TLS Decryption Guide]].


== header field ==
== RRD Health Charts ==
This combo box shows all custom headers which are defined in cdr_next.custome_header*. Those columns are created automatically once you set custom_headers in sniffer voipmonitor.conf [[Sniffer_configuration#custom_headers]] and voipmonitor restarts.


== name ==
Click the '''chart icon''' next to a sensor to view performance metrics:
The name of header used in the WEB GUI CDR header panel.


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


== match in sip by header ==
{{Note|High buffer/drops cause low MOS and choppy audio. Solutions: increase <code>ringbuffer</code> in config, add sensors, use [[DPDK]] or [[Napatech]].}}


Use this header for matching CDR with the same content in CDR section [[Call_Detail_Record_-_CDR#Legs_by_header]]. Practical example is when you have two legs for one call - from your phone to SBC and from SBC to sip provider and you decide that you will put for both legs one unique identifier so both legs will have same string in some custom named header. Please note that you can achieve this also by using [[Sniffer_configuration#match_header]].
== Disabling a Sensor ==


{{Warning|1=The GUI "Disabled" checkbox does NOT stop data collection. The sniffer continues running regardless of GUI status.}}


== show as column ==
'''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'''


== Deleting Sensors ==


Show this header in CDR column.  
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):'''


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


= Load GeoIP data =
# 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


Loads GeoIP data into internal database which is then used for [[Call_Detail_Record_-_CDR#map|CDR detail map]].
= CDR Charts =


[[File:settiongs-loadgeoip.png]]
Define predefined charts for the [[Call_Detail_Record_-_CDR#Charts|CDR detail Charts tab]].


= System configuration =
= CDR Custom Headers =
 
Capture and display custom SIP headers in CDR views. Requires sniffer version 7.0RC7+.
 
== Setup Workflow ==
 
<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>
 
# 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"
 
== Configuration Fields ==
 
{| 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.
|}
 
== Extracting Substrings ==
 
'''Boundary method (recommended):''' Extract between delimiters.
 
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>
 
'''Regexp method:''' Use capture groups for complex patterns.
 
<syntaxhighlight lang="text">
# Extract version from: User-Agent: Asterisk/20.6.0
Regexp: Asterisk/([0-9.]+)
Result: 20.6.0
</syntaxhighlight>
 
{{Warning|1=Regexp MUST include parentheses <code>(...)</code> 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).
 
{| class="wikitable"
|-
! Field !! Description !! Example Usage
|-
| CSeq method || Filter by SIP request method || <code>INVITE</code> to capture only from INVITE requests
|-
| response code || Filter by SIP response code number || <code>300</code> 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:
 
# 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
 
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:
 
<syntaxhighlight lang="sql">
-- 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);
</syntaxhighlight>
 
== Troubleshooting Custom Headers ==
 
{| class="wikitable"
|-
! Problem !! Solution
|-
| Header not captured || Increase <code>snaplen</code> in voipmonitor.conf (default may be too low)
|-
| 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
|}
 
Verify loaded headers: <code>echo 'custom_headers_dump cdr' | nc localhost 5029</code>
 
= Load GeoIP Data =
 
Loads GeoIP data for the [[Call_Detail_Record_-_CDR#Map|CDR Map tab]]. See [[Order_of_GeoIP_processing]] for processing priority.
 
= System Configuration =


== Basic ==
== Basic ==


[[File:settings-sysbasic.png]]
{| class="wikitable"
|-
! Setting !! Description
|-
| WEB URL || Base URL for hyperlinks in emails
|-
| Sniffer data path || PCAP storage directory (default: <code>/var/spool/voipmonitor</code>)
|-
| Sniffer second datapath || Secondary spool directory (<code>spooldir_2</code>)
|-
| Default sensor hostname || Default hostname for sniffer connection
|-
| Default sensor TCP port || Default manager API port (5029)
|}


*WEB URL - URL which will be used for hypertext links. For example in email alerts
{{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.}}
*sniffer data path - Directory path to the sniffer data (default /var/spool/voipmonitor)
*default sensor hostname - default sniffer sensor hostname (localhost). If you have more sensors define it in settings -> sensors
*default sensor TCP port - default sniffer sensor port (5029)


== Database ==
== Database ==


Databse settings
MySQL/MariaDB connection settings.


[[File:settings-sysdb.png]]
'''Custom port:''' Enter host with port in MySQL hostname field: <code>127.0.0.1:33306</code>
 
Also configure <code>mysqlport</code> in <code>/etc/voipmonitor.conf</code>. See [[Database_troubleshooting]] for details.


== National ==
== National ==


[[File:settings-sysnational.png]]
{| class="wikitable"
|-
! 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., <code>00</code>, <code>011</code>)
|-
| Local number || Country name for number normalization
|}
 
{{Tip|1=If CDRs display in UTC instead of local time, set '''Sensors Timezone''' (not regular Timezone) to your sensors' timezone.}}


*Timezone - set correct timezone according to your Country / Town
*National prefix,2,3 - This is for classifying calls to national and international calls. This classification is used in Active calls section.
*Max national number length - Calls with more digits will be international regardless on prefix
*Date format - Date format with default Y-m-d. http://www.php.net/manual/en/function.date.php
*Time format - Time format with default G:i:s. http://www.php.net/manual/en/function.date.php
*Week start
== Intervals ==
== Intervals ==
[[File:settings-sysintervals.png]]
*Default CDR interval - choose default time interval which is used to filter CDR when you enter CDR section. If you set "specified number of days" you can set custom number of days in following config option:
*Default CDR interval in days - this is possible to edit only when you choose "specified number of days" in Default CDR interval
*Default dashboard interval - choose default time interval which is used to filter CDR when you enter dashboard section
*Default Legs by CID interval - Find all related calls which starts +- internal - default 5 seconds
*Default Legs by header interval - Find all related calls which starts +- internal - default 5 seconds


== EMAIL HTTP REFERER ==
Default time filters for CDR view, dashboard, and Legs correlation.
[[File:settings-sysemailhttpreferer.png]]
 
== Email / HTTP Referer ==
 
{| class="wikitable"
|-
! 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:
 
<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
 
# Or search by timestamp
grep "2025-01-09 14:30:" /var/log/exim/main.log
</syntaxhighlight>
 
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.
 
<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.
 
<b>General MTA verification:</b>
<syntaxhighlight lang="bash"># 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
</syntaxhighlight>
== License ==
 
{| class="wikitable"
|-
! 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.


*DEFAULT_EMAIL_FROM - Default email in From header
*Disable email plain text - Some mailers (outlook 2003) does not like plain text and show only plain text part of email messages. If you do not see HTML part enable this option
== GEOIP ==
[[File:settings-sysgeoip.png]]
*Use GEOIP local database - Enable or disable use of internal GEOIP database (if loaded)
*GEOIP maxmind.com KEY - Personal key for maxmind.com geoip service
*GEOIP ipinfodb.com KEY - Personal key for ipinfodb.com
== Advanced ==
== Advanced ==
[[File:settings-sysadvanced.png]]


*Enable CDR group panel - Enable/Disable CDR group bottom panel
{| class="wikitable"
*ENABLE_CDR_FORCE_INDEX_CALLDATE - force index all queries by calldate column which can help on unoptimized mysql installations. Enable it only in case you know exactly what you are doing.
|-
*Enable database IP reverse lookup - If enabled in CDR IP addresses will be named by internal IP database lookup table
! Setting !! Description
*Enable DNS reverse lookup - If enabled in CDR IP address will be named by DNS
|-
*Enable database number lookup - If enabled in CDR tel. numbers will be named by internal prefix database lookup table
| ENABLE_CSRF_CHECK || Enable CSRF protection (recommended for production)
*Disable rtpfirstleg param - Disable --rtp-firstleg when decoding audio from pcap. - disable only in case you know what you are doing.
|-
*Disable URL wav protection - if true, user is not checked against valid session when downloading WAV. Suitable for downloading WAV outside voipmonitor GUI. If you need to secure it, you can set WAV key
| Pcap deduplication before download || Remove duplicate packets from PCAP downloads
*WAV download key - KEY used to download WAV files without user/pass authentication
|-
*Hide SIP domain in CDR - Hide SIP domain in CDR
| Http proxy (for upgrades) || Proxy for GUI/sniffer upgrades: <code>http://proxy:port</code>
*Hide live play - Hide live play in active calls
|-
*Hide WAV play - Hide play buttons in CDR
| Enable GUI to run in iframe || Allow embedding in iframes (disabled by default for security)
*Upload sniffer conf path - Path to sniffer voipmonitor.conf which is used when uploading pcap files.
|-
*CDR share key - String used to generate unique hashes in URL for sharing cdr
| 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:
* <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"
|-
! Placeholder !! Description !! Example
|-
| <code>{date}</code> || Call date || <code>2024-09-27</code>
|-
| <code>{time}</code> || Call time || <code>12-32-49</code>
|-
| <code>{caller}</code> || Caller number || <code>55555</code>
|-
| <code>{called}</code> || Called number || <code>555444333222111</code>
|-
| <code>{id}</code> || CDR ID || <code>ID5</code>
|-
| <code>{callid}</code> || '''(New in 2026.1)''' SIP Call-ID string || <code>abc123@192.168.1.1</code>
|}
'''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"
|-
! Setting !! Default !! Description
|-
| <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>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).
|}
{{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.}}
'''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.
''New in 2026.1''
= Localization =
= Localization =


Localization allows creates national localizations for the whole GUI. It is not yet 100% complete. If you find some words you need to localize and it is not possible, please let us know.  
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 <nowiki>{{paramName}}</nowiki> 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:
<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.
 
== License Update Fails ==
 
'''Cause:''' Firewall blocking outbound HTTPS.
 
'''Fix:''' Allow outbound TCP 443 to <code>voipmonitor.org</code>, or configure HTTP proxy in Advanced settings, or use offline activation.


There can be unlimited localizations and here is form which creates it:
== GUI Not Loading in iframe ==


[[File:settings-localisationform.png]]
'''Fix:''' Enable '''Enable GUI to run in iframe''' in Advanced settings.


[[File:settings-localisationgrid.png]]
== PCAP Download Has Fewer Packets Than GUI Shows ==


The red number items signalize how many items are not localized yet - this is useful in case you upgrade the GUI which has some more features which needs to localize.  
'''Cause:''' Pcap deduplication is enabled (removes retransmissions).


Changes are effective after you logout/login again.
'''Fix:''' Disable '''Pcap deduplication before download''' in Advanced settings.


= Cdr view custom url =
= See Also =


* possibility to add custom link into CDR view (e.g. to the monitoring)
* [[Sniffer_configuration]] - Full voipmonitor.conf reference
* [[Sniffer_distributed_architecture]] - Client-Server mode
* [[Tls]] - TLS/SRTP decryption
* [[Data_Cleaning]] - Storage retention
* [[User_Management]] - User permissions
* [[License]] - License management

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"