Settings

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 (initial INVITE) or Last found value

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.

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

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

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

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

• 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

AI Summary for RAG

Summary: GUI Settings reference covering: Sensors configuration (multi-sensor deployments, SSL/TLS via wrench icon, sipport, savertp modes, RTP limits, RRD health charts, disabling/deleting sensors); CDR Custom Headers (capture workflow, configuration fields including Select occurrence for re-INVITE handling, Boundary and Regexp extraction methods, database indexing); System Configuration (Basic settings with default sensor hostname/port that override individual configs, Database with custom port format host:port, National with Sensors Timezone for CDR display vs regular Timezone for GUI scheduling, Intervals, Email, License with update button and notification email control, GeoIP, Advanced with CSRF, PCAP deduplication, HTTP proxy for upgrades, iframe embedding); Localization; CDR View Custom URL. Key troubleshooting: sensors connecting wrong destination after upgrade (disable default hostname/port), non-deletable local sensor on GUI+DB servers (use id_sensor override method), GUI crash on sensors page (delete obsolete DB records), license update failures (firewall/proxy config), PCAP packet count mismatch (deduplication setting).

Keywords: GUI settings, sensors, sensor configuration, wrench icon, SSL/TLS decryption, sipport, savertp, RTP recording, RTP headers only, RRD charts, buffer usage, packet drops, disable sensor, delete sensor, capture rules SKIP, non-deletable local sensor, id_sensor override, CDR custom headers, custom_headers, Select occurrence, first found value, Boundary extraction, Regexp extraction, database index, system configuration, default sensor hostname, default sensor TCP port, sensors timezone, CDR timezone, international prefix, license update, license email, firewall requirements, HTTP proxy, CSRF protection, iframe embedding, pcap deduplication, localization, custom URL

Key Questions:

• How do I configure sensors in VoIPmonitor GUI?
• How do I configure SSL/TLS decryption via the GUI wrench icon?
• How do I disable audio recording (savertp) via GUI?
• Why are sensors connecting to wrong destination after upgrade?
• How do I disable the auto-created local sensor on GUI+DB only servers?
• Why can't I delete a sensor from the GUI?
• How do I configure CDR custom headers?
• How do I extract substrings from SIP headers?
• What is Select occurrence field for custom headers?
• How do I add database index for custom headers?
• How do I fix CDR times displaying in UTC?
• How do I update license after payment?
• How do I disable license notification emails?
• What firewall rules are required for VoIPmonitor?
• Why does downloaded PCAP have fewer packets than GUI shows?
• How do I enable GUI to run in iframe?

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.