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:
- 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 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 tocustom_headersinvoipmonitor.confand 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:
- Via Parameters and Custom headers items: Values are appended as query parameters (e.g.,
?paramName=value) - 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?