Settings

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.

Sensors

If id_sensor is set in /etc/voipmonitor.conf (default is blank), you must create sensor entries here to enable downloading files like PCAP, graphs, and WAV recordings from the GUI.

Field	Description
Sensor ID	The numeric ID matching id_sensor = N in voipmonitor.conf
Name	A descriptive name for the sensor
Manager IP	IP address of the sensor for fetching data (PCAP, graph, audio files)
Manager Port	TCP port for the manager API (default: 5029)
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.

Troubleshooting: Non-deletable Local Sensor

In server/probe deployments where the GUI server is not sniffing traffic itself, a "local sensor" may be automatically created in the sensor list. This sensor cannot be deleted through the normal GUI interface.

Workaround:

1. In Settings > Sensors, add a new sensor with the same Sensor ID, name, and settings as the non-deletable local sensor
2. After saving, the original automatically created sensor should either disappear or become deletable
3. 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 id_sensor is set in the configuration but no active capture is configured on the GUI host.

CDR Charts

This section allows you to define predefined charts that appear in the CDR detail view's Charts tab. These charts provide quick visual analysis for specific call records based on caller/called information.

CDR Custom Headers

Since sniffer version 7.0RC7, VoIPmonitor can store custom SIP headers in the database for viewing and searching in the GUI. For the sniffer configuration, see Sniffer_configuration#custom_headers.

Configuration Fields

Header Field

Combo box listing available headers from the cdr_next.custom_header* database columns. These are automatically created when you add headers to custom_headers in voipmonitor.conf and restart the sniffer.

Name

The display name for this header in the CDR view header panel.

Match in SIP by Header

When enabled, this header is used for matching CDRs in the 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: matchheader in voipmonitor.conf.

Show as Column

When enabled, displays this header as a column in the CDR list view.

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 % wildcard as the filter value. This matches any non-empty value.
• Find all CDRs without this header: Type NULL (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 % as a wildcard for partial matches, e.g., sip:% 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:

Limitation	Description
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).
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 custom_headers_last_value in voipmonitor.conf (first or last occurrence).
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.).

For advanced header extraction needs, contact VoIPmonitor support to discuss custom development or alternative approaches such as external PCAP processing.

Load GeoIP Data

Loads GeoIP data into the internal database for the CDR detail Map tab, which displays geographic locations of call participants.

System Configuration

The System Configuration section contains core settings that affect the overall behavior of the GUI.

Basic

Setting	Description
WEB URL	Base URL for the GUI, used in hypertext links (e.g., in email alerts)
Sniffer data path	Directory where sniffer stores data (default: /var/spool/voipmonitor)
Default sensor hostname	Default hostname for connecting to the sniffer (default: localhost). For multiple sensors, configure them in Settings > Sensors
Default sensor TCP port	Default TCP port for the manager API (default: 5029)

Database

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

National

Settings for localizing call classification and date/time display formats.

Setting	Description
Timezone	Server timezone (format: Country/City, e.g., Europe/Prague)
National prefix, 2, 3	Prefixes used to classify calls as national vs. international (used in Active calls view)
Max national number length	Numbers longer than this are classified as international regardless of prefix
Date format	PHP date format string (default: Y-m-d). See PHP DateTime format
Time format	PHP time format string (default: G:i:s). See PHP DateTime format
Week start	First day of the week for calendar displays

Intervals

Default time intervals for various GUI views and filters.

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

Email configuration settings.

Setting	Description
DEFAULT_EMAIL_FROM	Default "From" address for outgoing emails
Disable email plain text	Enable to force HTML-only emails. Useful for mail clients that display only plain text incorrectly (e.g., older Outlook versions)

GeoIP

Configuration for GeoIP services used in the CDR Map view.

Setting	Description
Use GeoIP local database	Enable/disable the internal GeoIP database (if loaded via Load GeoIP Data)
GeoIP maxmind.com KEY	API key for MaxMind GeoIP service
GeoIP ipinfodb.com KEY	API key for IPInfoDB service

Advanced

Advanced configuration options for power users and specific use cases.

Setting	Description
Enable CDR group panel	Show/hide the group panel at the bottom of the CDR view
ENABLE_CDR_FORCE_INDEX_CALLDATE	Force use of the calldate index on CDR queries. Enable only for unoptimized MySQL installations experiencing slow queries
Enable database IP reverse lookup	Resolve IP addresses to names using the internal IP lookup table
Enable DNS reverse lookup	Resolve IP addresses to names using DNS
Enable database number lookup	Resolve phone numbers to names using the internal prefix lookup table
Disable rtpfirstleg param	Disable the --rtp-firstleg parameter for PCAP audio decoding. Enable only if experiencing audio issues
Disable URL wav protection	Skip session authentication for WAV file downloads. Use with WAV download key for secure external access
WAV download key	Secret key required for WAV downloads when URL protection is disabled
Hide SIP domain in CDR	Hide SIP domains in the CDR display
Hide live play	Hide live playback buttons in Active calls
Hide WAV play	Hide WAV playback buttons in CDR view
Upload sniffer conf path	Path to voipmonitor.conf for PCAP upload functionality
CDR share key	Secret string used to generate unique hashes for CDR share URLs
Folder for export CSV	Directory where CSV files from crontab scheduler tasks are saved
CSV name prefix	Optional prefix for CSV filenames generated by crontab tasks
Delete CSV after X days	Auto-delete CSV files older than specified days

Localization

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

• Red numbers indicate untranslated items, which is useful after upgrading to identify new strings
• Changes take effect after logout/login

CDR View Custom URL

Add custom hyperlinks to the CDR view Commands column. This is useful for integrating external monitoring or CRM systems.

Configuration

Navigate to GUI > Settings > CDR view custom URL.

You can include CDR parameters in the URL using two methods:

1. Via Parameters and Custom headers items: Values are appended as query parameters (e.g., ?paramName=value)
2. Directly in URL: Use {{paramName}} syntax, which is replaced with the actual value

Display

Configured custom URLs appear as links in the Commands column of the CDR view.

AI Summary for RAG

Summary: This article documents VoIPmonitor GUI settings including sensor configuration, CDR custom headers with their limitations, GeoIP data loading, system configuration (basic, database, national, intervals, email, GeoIP, advanced), localization, and custom CDR URLs. Key topics: custom headers store raw SIP header values without regexp extraction or delimiter aggregation; sensor troubleshooting for non-deletable local sensors in server/probe deployments.

Keywords: GUI settings, sensors, CDR custom headers, header limitations, GeoIP, system configuration, timezone, national prefix, date format, intervals, advanced settings, localization, custom URL, CSV export

Key Questions:

• How do I configure sensors in the VoIPmonitor GUI?
• 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?