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:

Set unique id_sensor in each sensor's /etc/voipmonitor.conf
Add sensor entries in Settings > Sensors with matching Sensor ID
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:

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

Add header to /etc/voipmonitor.conf:

custom_headers = X-Cisco-Org-ID

Restart sensor: systemctl restart voipmonitor
Generate a test call
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:

Navigate to Settings > Custom headers > CDR in the GUI
Click Add new
Set Header field to Contact
Set Name to descriptive label (e.g., SIP300RedirectDestinations)
Set Regexp to sip:.*@([0-9]+\.[0-9]+\.[0-9]+\.[0-9]+); to extract the IP address
Set CSeq method to INVITE
Set response code to 300
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.

Settings: Difference between revisions