Settings

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.

Configuring Sensors for Multi-Sensor Deployments

When multiple VoIPmonitor instances (sniffers) feed data to a single GUI, you must configure unique sensor IDs to identify which specific instance processed a given CDR.

Workflow:

On each sniffer instance, edit /etc/voipmonitor.conf and set a unique id_sensor value (e.g., 1, 2, 3...):

# On Sensor A
id_sensor = 2

# On Sensor B
id_sensor = 3

In the GUI, navigate to Settings > Sensors and add a sensor entry for each instance with the following fields:

- Sensor ID: The numeric ID matching id_sensor 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)

Restart the sniffer service on each instance to apply the changes:

# On each sensor machine
systemctl restart voipmonitor

Newly captured CDRs will now display the source sensor ID in the GUI. The id_sensor is stored in the cdr.id_sensor database column, allowing you to filter and identify which sniffer processed each call.

SSL/TLS Configuration

Sensors can be configured to decrypt TLS-encrypted SIP traffic directly through the GUI. This is particularly useful when VoIPmonitor is not capturing all SIP traffic from specific TLS trunks (e.g., seeing only OPTIONS and 403 responses while INVITEs are missing).

To configure SSL/TLS settings for a sensor:

Navigate to Settings > Sensors
Click the wrench icon next to the affected sensor
In the search field at the top right of the sensor settings dialog, enter ssl_
Configure the required SSL/TLS parameters:

Parameter	Description	Example Value
ssl_key	Path to the private key file (PEM format) for decrypting TLS traffic	`/etc/pki/tls/private/server.key`
ssl_cert	Path to the SSL certificate file (PEM format) matching the private key	`/etc/pki/tls/certs/server.crt`
ssl_ipport	IP address and TLS port of the SIP endpoint to decrypt (without key file path for SSL Key Logger mode, or `IP:port /path/to/key` for Private Key mode)	`192.168.1.10:5061`
ssl	Enable SSL/TLS decryption module on the sensor	`yes`

Important Notes:

The sensor SSL settings correspond to the configuration parameters in /etc/voipmonitor.conf but are managed through the GUI interface
This is an alternative to editing voipmonitor.conf directly - the GUI applies these settings to the sensor
After changing SSL settings, you may need to restart the sniffer service or use the "reload sniffer" button in the GUI control panel
Important Warning for Sensor Configuration Changes: When modifying sensor-level settings (especially parameters loaded via mysqlloadconfig such as dtmf2db, dtmf2pcap, or other sensor options), perform a manual restart instead of using reload. A reload may leave the sniffer in an inconsistent state with some processes holding old configuration values. To safely apply sensor configuration changes:

# Stop the sensor service
systemctl stop voipmonitor

# Check for remaining processes (kill if any)
ps ax | grep voipmonitor

# Start the sensor service
systemctl start voipmonitor

For decryption of traffic using Perfect Forward Secrecy (PFS) ciphers like Diffie-Hellman (DHE/ECDHE), see the TLS decryption guide for the SSL Key Logger method

When to use GUI SSL configuration:

You prefer managing TLS/SSL settings through the web interface instead of editing config files
You have multiple sensors and want to manage SSL keys centrally
You need to quickly enable/disable TLS decryption without editing voipmonitor.conf

For detailed information on TLS decryption methods and limitations (including PFS ciphers), see Tls.

SIP Port Configuration

The sipport parameter controls which SIP signaling ports the sensor listens to. This is critical when you need to capture traffic from devices using non-standard SIP ports (not port 5060).

To configure SIP ports via GUI:

Navigate to Settings > Sensors
Click the wrench icon next to the affected sensor
In the sensor settings dialog search field, enter sipport
Configure the required value:

Parameter	Description	Example Value
sipport	SIP ports to listen on (comma-separated or ranges)	`5060,5080` or `5060,5070-5080`

Default: Port 5060 only
Multiple ports: Use commas (e.g., 5060,5061,5080)
Port ranges: Use hyphens (e.g., 5060,5070-5080)

When to change sipport:

Certain carriers or devices use non-standard SIP ports (e.g., 5080, 6060)
You see missing CDRs for calls from specific IP addresses
Packet captures show SIP traffic on ports other than 5060

After changing sipport:

Manual config file changes: systemctl restart voipmonitor
GUI changes (via reload sniffer button): Settings are applied automatically by the sensor

Important for Client/Server deployments:

If using packetbuffer_sender = yes (packet mirroring mode), you must configure matching sipport settings on BOTH the remote probe and the central server. Different port lists will cause the central server to ignore forwarded packets on ports it does not recognize.

See Sniffer_distributed_architecture#Critical:_sipport_Must_Match_in_Distributed_Deployments for details.

Configuring RTP Storage Limits via GUI

The sensor wrench icon interface allows you to configure disk space limits specifically for RTP (audio) PCAP files. This helps manage disk usage by limiting RTP storage while preserving SIP signaling and chart data, which consume significantly less space.

To configure RTP retention limits for a specific sensor:

Navigate to Settings > Sensors
Click the wrench icon next to the problematic sensor
In the search field at the top right, enter maxpoolrtp
Configure the required RTP storage parameters:

Parameter	Description	Example Value
maxpoolrtpsize	Maximum disk space in MB for RTP PCAP files. When this limit is reached, oldest RTP files are deleted.	`51200` (50 GB)
maxpoolrtpdays	Maximum age in days for RTP PCAP files. Files older than this are deleted. Use either size or time limit (whichever is reached first triggers cleanup).	`30` (30 days)

When to use RTP limits:

A specific sensor has limited disk space compared to others
You want to preserve SIP signaling and chart data longer than audio
Audio files are being deleted prematurely due to overall storage limits
You need to balance storage allocation between RTP, SIP, and chart data

Important Notes:

The first limit that is reached (size or days) triggers cleanup. You can use both parameters for flexible control.
RTP files typically consume 5-10x more disk space than SIP files. Limiting RTP helps preserve smaller, more valuable data types.
GUI settings configured here take priority over settings in /etc/voipmonitor.conf when mysqlloadconfig is enabled (default).
Settings are applied to the specific sensor. Configure RTP limits individually for sensors with different storage constraints.

For more information on data retention strategies, including size-based vs time-based retention, see Data_Cleaning.

Sensor Health Monitoring with RRD Charts

If you experience poor call quality (low MOS scores, choppy playback) and need to determine whether the issue is network-related or caused by the sniffer host being overloaded, use the RRD (Round Robin Database) charts available in the GUI.

Accessing Sensor RRD Charts:

Navigate to Settings > Sensors
Locate the sensor you want to monitor
Click the chart icon next to the sensor entry
This opens the RRD performance graphs for that sensor

Key Metrics to Check:

Metric	Description	What It Indicates
Buffer usage	Shows the percentage of available packet buffer being used	Sensor is approaching capacity limits if consistently high
Packet drops	Counts of packets the sensor could not process	Sensor is overloaded and dropping packets due to high traffic load

Interpreting the Charts:

If you observe:

Buffer usage growing to 100% and remaining at maximum capacity
Packet drops being recorded (non-zero values on the packet drops graph)

This indicates the sniffer host is overloaded and is the source of audio quality issues. The sensor cannot keep up with incoming packet rate, causing packets to be dropped before they can be processed and stored. This results in:

Low MOS scores
Choppy audio playback in the GUI
Missing call data

Solutions for Sensor Overload:

Increase the kernel packet ring buffer size in voipmonitor.conf: ringbuffer = 200 (default: 50, recommended: >= 500 for >100 Mbit traffic). This allows the operating system to buffer more packets before they are passed to VoIPmonitor, reducing kernel-level packet drops.
Add more sensors to distribute the load (Distributed Architecture)
Use specialized capture hardware (DPDK, Native Napatech cards, PF_RING)
Reduce capture scope (more restrictive capture rules)
Upgrade sensor hardware (faster CPU, more RAM)
Reduce PCAP file storage or enable compression

Historical Comparison for Troubleshooting Spikes

When investigating sudden issues like "packetbuffer: MEMORY IS FULL" alarms or bad MOS scores on one sensor:

1. Navigate to Settings > Sensors and click the chart icon next to the affected sensor 2. Once the charts load, locate the From date field in the chart controls 3. Adjust the From date to a period before the issue started (e.g., 1-2 days earlier) 4. Compare the buffer usage chart between the normal and problematic periods 5. Look for sudden spikes or patterns that correlate with the error times

This historical comparison helps identify whether the issue is a gradual buildup (resource exhaustion) or a sudden traffic pattern change (bursty traffic from specific sources).

When to Check RRD Charts:

Use RRD charts to diagnose sensor overload when:

Other platforms show clear audio but VoIPmonitor shows poor quality
Only the sniffer host is affected, not the actual VoIP network
Performance log shows high packet drops or buffer saturation
Buffer usage chart shows a sudden increase correlating with error messages like "packetbuffer: MEMORY IS FULL"

This diagnostic step helps distinguish between network quality issues (jitter, loss in the actual VoIP path) vs. sniffer capacity issues (capturing host overload).

Disabling a Sensor

If you need to temporarily or permanently stop a sensor from collecting data and writing CDRs to the database, you have two options depending on your requirements.

⚠️ Warning: Important: GUI actions do not stop data collection

Toggling "Disabled" or clicking "Delete" for a sensor in the Settings > Sensors interface does NOT stop the underlying VoIPmonitor service. The sensor process continues to capture packets and write to the database regardless of its GUI status. You must use one of the methods below to halt actual data collection.

Option 1: Stop the Service on the Sensor Machine (Complete Shutdown)

To completely stop a sensor from collecting data, you must stop the VoIPmonitor service on the sensor's host machine:

Log into the sensor machine via SSH
Stop the service:

systemctl stop voipmonitor

Verify the sensor appears offline in the GUI

This method:

Completely halts packet capture and database writes
Works for decommissioning sensors permanently
Requires command line access to the sensor host

Option 2: Use Capture Rules with SKIP=ON (Selective Blocking)

To prevent a specific sensor from sending CDRs to the database while keeping the service running, use capture rules:

Navigate to GUI > Capture rules
Create a new rule for the sensor's IP address or phone numbers
Set the Skip option to ON
Configure any additional filters as needed
Save and apply the rule

With SKIP=ON:

The sensor continues to capture packets from the network
No CDRs are generated for matching traffic
No files are created (PCAP, audio, graphs)
RTP analysis is suppressed for matched calls
Useful for selective blocking without stopping the entire service

Important notes on SKIP:

The Skip option only works if the IP address or phone number appears in SIP signaling
It does not work for IPs that are only used in RTP packets (media stream)
For excluding RTP-only traffic, use the filter directive in voipmonitor.conf

For more information on capture rules, see Capture_rules.

Troubleshooting: Non-deletable Local Sensor

In server/probe deployments where the GUI server is not sniffing traffic itself (GUI + Database only), a "local sensor" (often named localhost) may be automatically created in the sensor list. This sensor cannot be deleted through the normal GUI interface.

ℹ️ Note: The auto-created local sensor is counted in SUM counters and charts even if it is not sniffing any traffic. To prevent this from skewing your statistics on a central server that functions solely as a GUI and Database receiver, use the id_sensor override method below.

Solution: Override with Manual Sensor Configuration (Recommended)

To effectively replace the auto-created default local sensor with a manually configured one:

Edit the /etc/voipmonitor.conf file on the central server and set a specific id_sensor:

# On the central GUI + DB only server
id_sensor = 1

In the GUI, navigate to Settings > Sensors
Add a new sensor record with the following details:

- Manager IP: 127.0.0.1
- Sensor ID: The same ID set in the voipmonitor.conf file (e.g., 1)
- Manager Port: 5029 (or your configured manager port)
- Enable the checkbox for "is server in client/server mode"
- Disable the checkbox for "show active calls from all sensors in active call view"

Save the new sensor configuration

This replaces the default auto-created localhost entry with your manual sensor configuration, preventing the default sensor from appearing in statistics and charts.

Alternative Workaround: Duplicate Sensor Method

If you simply need to delete an existing non-deletable sensor entry:

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

ℹ️ Note: This method creates a sensor entry that the GUI recognizes instead of the auto-created one. The id_sensor override method (above) is preferred for central GUI+DB servers as it gives you full control over the sensor configuration and prevents the default sensor from being counted in statistics.

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.

Troubleshooting: Cannot Delete Sensor Due to Capture Rules

If you attempt to delete a sensor from the GUI and receive a pop-up error message, or if the delete action has no effect, the most common cause is that the sensor has capture rules assigned to it. Sensors with active capture rules cannot be deleted until those rules are removed first.

Resolution Steps:

Navigate to Control Panel > Capture Rules
Find any capture rules that are assigned to the sensor you are trying to delete
Rules may be assigned by IP address, phone number, or network range
Delete or reassign the capture rules to a different sensor
After all rules have been removed or reassigned, return to Settings > Sensors
You can now successfully delete the sensor

Why this happens:

Capture rules link to specific sensors for traffic filtering purposes. The GUI enforces referential integrity to prevent orphaned capture rules that would reference non-existent sensors. This safety mechanism ensures deleted rules do not leave behind dangling references that could cause system errors.

Alternative Solution: If You Need to Keep the Rules

If you want to delete a sensor but preserve its capture rules for use with a different sensor:

Navigate to Control Panel > Capture Rules
Edit each capture rule currently assigned to the sensor
Reassign the rule to a different sensor (if your deployment has multiple sensors)
Save the changes
After all rules are reassigned, delete the original sensor

This approach is useful when migrating traffic filtering from one sensor to another without recreating the rules from scratch.

Removing and Reconnecting Sensors

When decommissioning or replacing a sensor, or when you need to refresh the sensor configuration after an upgrade, use the following standard workflow.

Standard Decommissioning Workflow:

Navigate to Settings > Sensors in the GUI
Click the sensor entry you want to remove
Click Delete or Remove to delete the sensor probe entry
Log into the command line of the sensor machine (SSH)
Restart the voipmonitor service on the sensor:

systemctl stop voipmonitor
systemctl start voipmonitor

Return to Settings > Sensors in the GUI
The sensor will automatically reappear in the list after the service restart
Rename the sensor entry as needed if the IP or configuration has changed

How It Works:

When you restart the voipmonitor service on the sensor machine, it automatically re-registers with the GUI if id_sensor is configured in /etc/voipmonitor.conf. The GUI creates a new sensor entry with the current configuration. This workflow ensures that:

The sensor configuration is refreshed with the latest sensor settings
Old IP addresses or obsolete sensor entries are cleaned up
The system automatically discovers the sensor again after restart

When to Use This Workflow:

After an upgrade that caused errors referencing old/decommissioned sensor IP addresses
When replacing hardware and reusing a new IP address
When you need to refresh sensor configuration settings
When CDRs show warnings about unknown sensors

Note: This standard workflow is different from the emergency cleanup procedure described below, which is used only when the GUI crashes due to thousands of obsolete records.

Troubleshooting: GUI Crashes When Accessing Settings > Sensors

If the web GUI becomes unresponsive or crashes when accessing Settings > Sensors, this is typically caused by a large number of obsolete sensor records in the sensors database table. The GUI processes all sensor entries from this table to render the page, and if there are thousands of stale records (from old sensors, decommissioned hardware, or duplicate IDs), the PHP process may run out of memory or exceed execution time limits.

Symptoms:

Settings > Sensors page does not load or times out
GUI becomes unresponsive when navigating to sensor configuration
PHP error logs show memory exhaustion or timeout errors

Solution: Manually Delete Obsolete Records from Database

Use the MySQL command line to remove obsolete sensor records directly from the database. The standard GUI interface cannot handle the cleanup if the records are already causing the page to crash.

Access the database:
```
mysql -u voipmonitor -p voipmonitor
```

Identify obsolete records: Inspect the sensors table to find entries that correspond to obsolete sensors. Look for rows with old interface names, missing sensor IDs, or duplicates.

-- Example: Find entries referencing old or duplicate IDs
SELECT * FROM sensors WHERE id_sensor IN (1,2,3);
--
-- Check total count of sensors
SELECT COUNT(*) FROM sensors;

Delete obsolete records: Execute DELETE statements for the identified obsolete rows. Be careful with the WHERE clause to ensure you only delete obsolete data.

-- Delete records by id_sensor (replace with actual values after inspection)
DELETE FROM sensors WHERE id_sensor IN (<id1>, <id2>, <id3>);

-- Delete by specific criteria
DELETE FROM sensors WHERE host LIKE '%old-sensor-name%';

Verify cleanup:

-- Check remaining sensor count
SELECT COUNT(*) FROM sensors;

Exit the database:

EXIT;

Critical: Users must log out and log back in All users currently logged into the GUI must log out and then log back in for the sensor list to be refreshed. Simply reloading the page is not sufficient.

Note: The sensors table contains GUI sensor configuration entries, distinct from the sensor_config table which is used for sensor-level parameter overrides when the mysqlloadconfig feature is enabled.

Troubleshooting: Server Instance Not Appearing in GUI

After replacing a server/SBC and reusing its IP address, the server instance may disappear from the GUI sensor list, even though it is sending data and appears in CDRs with a warning.

Problem: Sensor Appears in CDRs With Warning But Not in GUI List

When you replace hardware (server, SBC, sensor host) but reuse the same IP address, the GUI may not automatically rediscover the server instance. CDRs from the new device appear in the database, but:

The server instance is not visible in Settings > Sensors
CDR records contain a warning about unknown sensor or manager connection
The new server is working but not properly registered with the GUI

Solution: Manually Create Server Instance Entry

If your deployment uses server instances that connect directly to the MySQL database, follow these steps:

Step 1: Create the server instance entry in the GUI

Navigate to Settings > Sensors
Click Add new sensor or New sensor
Configure the following fields:

- Sensor ID: Enter a unique identifier (e.g., 2)
- Name: Descriptive name for the server instance (e.g., SBC-Production)
- Manager IP: IP address of the server instance (the new hardware's IP)
- Manager Port: TCP port for the manager connection (default: 5029)

Step 2: Configure managerip and managerport on the server instance

Edit the voipmonitor.conf file on the new server instance to point to the GUI:

# On the new server instance (/etc/voipmonitor.conf)
managerip  = gui.server.ip    # GUI server IP address
managerport = 5029            # Manager API port (matches GUI Manager Port)

Restart the voipmonitor service after making changes:

systemctl restart voipmonitor

Step 3: Verify network connectivity

Ensure bidirectional network connectivity:

GUI host → Server instance: GUI must be able to reach the server instance on the configured Manager IP/Port (for data retrieval and control)
Server instance → MySQL database: Server instance must be able to write CDRs to the MySQL database

Test connectivity from both directions:

# From GUI host to server instance (verify Manager IP/Port)
nc -zv server.instance.ip 5029

# From server instance to MySQL database
mysql -h mysql.server.ip -u voipmonitor -p voipmonitor -e "SELECT 1"

Check firewall rules on both systems to ensure:

TCP/5029 (Manager port) is allowed from GUI to server instance
MySQL port (usually 3306) is allowed from server instance to database

Step 4: Verify server instance status

After configuration, the server instance should appear in Settings > Sensors with a green status indicating it is connected. Any probes or sniffing interfaces connected to that server instance will be automatically discovered and listed under the server instance in the sensor tree.

Alternative: Using Modern Client-Server Mode

If you are planning a new deployment or can reconfigure your architecture, consider using the modern Client-Server mode which provides:

Encrypted TCP connections between sensors and central server
Automatic sensor registration (no manual GUI entry required)
Simplified firewall configuration (single port: 60024 by default)

In Client-Server mode, sensors connect to a central server using server_destination and server_destination_port, and the central server handles SQL database writes. Sensors do not need direct MySQL database access.

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.

How to Add a New Custom SIP Header

To capture and display a custom SIP header (e.g., X-Cisco-Org-ID) in the CDR view, follow this workflow:

1. Configure the sniffer to capture the header

Edit /etc/voipmonitor.conf and add the header name to the custom_headers parameter:

custom_headers = X-Cisco-Org-ID

For multiple headers, separate with commas: custom_headers = X-Cisco-Org-ID, X-Other-Header

2. Restart the sensor service

Restart the sniffer service for the configuration to take effect and for the database columns to be created:

systemctl restart voipmonitor

Important: Custom header data will only be captured for calls made AFTER the restart. Existing CDRs will not have this data.

3. Generate a test call: Place a test call to verify that the header is being captured and stored in the database.

4. Configure GUI display settings

Once the header appears in the database, configure the GUI:

Navigate to Settings > CDR Custom Headers
Select the header from the "Header Field" combo box (it will appear after restart)
Set the display name in the "Name" field (e.g., "Cisco Org ID")
Enable "Show as Column" to display it in the CDR list
Click Save

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.

Restrict to Regex pattern: Optional regular expression pattern to filter which header values are stored in the database. Only headers matching this regex pattern will be captured. For example: ^[0-9]+$ to capture only numeric values.

Boundary start: Optional text marker to define where substring extraction should begin. When specified, only the portion of the SIP header value starting after this text will be stored. For example, if your SIP Contact header is sip:1000@192.168.1.1;user=phone and you want to extract only the username (1000), set Boundary start to sip:.

Boundary end: Optional text marker to define where substring extraction should end. Used together with Boundary start to extract the portion between two delimiters. For example, to extract just the IP from sip:1000@192.168.1.1;tag=as12345, set Boundary start to @ and Boundary end to ;.

Regexp: Optional regular expression pattern to extract specific substring(s) from the SIP header value. Unlike the Restrict to Regex pattern field (which filters which headers to capture), this field extracts a portion of the captured header. The regex should include capture groups using parentheses. Only the first matched capture group will be stored in the database. For example: User-Agent: Asterisk/([0-9.]+) to extract only the version number from the User-Agent header.

⚠️ Warning: The Regexp extraction method is more CPU-intensive than the Boundary method. After enabling Regexp extraction, monitor the system load via Settings > Sensors during peak traffic to assess the impact. The performance impact is generally expected to be minor, but should be monitored for high-volume deployments.

Select occurrence

Controls which occurrence of a SIP header is stored when the same header appears multiple times in a call (common for headers like P-Asserted-Identity that appear in both the initial INVITE and subsequent re-INVITEs).

First found value: Captures the header value from the first occurrence (typically the initial INVITE). This is recommended when you only want the original value from call setup and want to ignore changes during the call (e.g., re-INVITEs during hold, transfers, or session modifications).
Last found value: Captures the header value from the last occurrence found. Use this when you need the most recent value if the header changes during the call.

Example: P-Asserted-Identity in Re-INVITEs

If calls include P-Asserted-Identity in both the initial INVITE and subsequent re-INVITEs (e.g., during hold operations), the system will capture the header for each occurrence. To capture only the initial INVITE value and ignore re-INVITEs:

In Settings > CDR Custom Headers, set Select occurrence to First found value
This stores only the header value from the initial INVITE, ignoring values from subsequent SIP requests

This is particularly useful for ensuring consistent Caller ID information based on the original call setup rather than later modifications during the call session.

Extracting Substrings from SIP Headers

In addition to storing the complete header value, VoIPmonitor can extract specific substrings or parameters from SIP headers using two methods:

Method 1: Boundary Extraction (Recommended for Performance)

The Boundary method extracts the portion of the header value that appears between two text markers.

Example 1: Extracting a parameter from the SIP Contact header

If your SIP Contact header contains:

Contact: <sip:1000@192.168.1.1:5060;+g.3gpp.icsi-ref="urn:urn-7:3gpp-application.ims.icsi.mscc:audio:1";tag=as12345>

To extract only the +g.3gpp.icsi-ref parameter value:

In Settings > CDR Custom Headers:
- Set Header Field to Contact
- Set Boundary start to +g.3gpp.icsi-ref=
- Set Boundary end to ; (semicolon)
- Enable Show as Column
- Click Save

Result: The column will store only urn:urn-7:3gpp-application.ims.icsi.mscc:audio:1

Example 2: Extracting the IP from a SIP URI

For a header like sip:1000@192.168.1.1:5060;tag=123:

Set Boundary start to @
Set Boundary end to :

Result: Stores only 192.168.1.1

= Method 2: Regexp Extraction

The Regexp method extracts values using regular expressions with capture groups. This is more flexible but CPU-intensive.

Important: The regex must include capture groups (...). Only the first capture group will be stored in the database. Not using parentheses in the regex will result in storing the entire matched string instead of the desired substring. If you do not use parentheses, it will NOT work as expected.

Example 3: Extracting a parameter using regex

For the same SIP Contact header example:

Contact: <sip:1000@192.168.1.1:5060;+g.3gpp.icsi-ref="urn:urn-7:3gpp-application.ims.icsi.mscc:audio:1";tag=as12345>

To extract the +g.3gpp.icsi-ref value:

In Settings > CDR Custom Headers:
- Set Header Field to Contact
- Set Regexp to: \+g\.3gpp\.icsi-ref="([^"]+)"
* \+ escapes the plus sign
* \. escapes the dots (match literal periods)
* "([^"]+)" captures the text inside the quotes
* The parentheses (...) define the capture group - this is critical
- Enable Show as Column
- Click Save

Result: Stores only urn:urn-7:3gpp-application.ims.icsi.mscc:audio:1

⚠️ Warning: Without capture groups (parentheses), the regex will match and store the entire matched string (e.g., +g.3gpp.icsi-ref="value"), not just the value inside. Always include parentheses around the part you want to extract.

Example 4: Extracting User-Agent version number

For a header like: User-Agent: Asterisk/20.6.0

Set Regexp to: Asterisk/([0-9.]+)

Result: Stores only 20.6.0

= Performance Comparison

Method	CPU Impact	Flexibility	Use Case
Boundary	Low	Moderate	Simple delimiter-based extraction (recommended for most cases)
Regexp	Moderate to High	High	Complex patterns, data validation, special character handling

💡 Tip: The Boundary method is recommended for production deployments due to lower CPU impact. Use Regexp only when Boundary extraction is not sufficient for your use case. Monitor system load via Settings > Sensors after enabling Regexp extraction.

When is a Restart Required?

Restarting the sensor service is only required in the following scenarios:

After adding NEW headers to voipmonitor.conf: When you add new header names to the custom_headers parameter in /etc/voipmonitor.conf, a restart is required to create the database columns and begin capturing data.
After changing sniffer capture parameters: If you modify snaplen, custom_headers_max_size, or other capture-related parameters in voipmonitor.conf, restart to apply the changes.

Restart is NOT required for GUI-only changes such as:

Modifying the display name ("Name" field)
Toggling "Show as Column" or "Match in SIP by Header"
Adding or changing regex patterns in "Restrict to Regex pattern"

To restart the sensor:

# Using systemd
systemctl restart voipmonitor

# Using init scripts
/etc/init.d/voipmonitor restart

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.

Troubleshooting: Header Capture Issues

If custom SIP headers are not being captured at all or are showing truncated content in the database, check the sniffer configuration parameters in voipmonitor.conf:

Problem	Cause	Solution
Complete header not captured	In `voipmonitor.conf`, increase the `snaplen` parameter to capture larger packets: `snaplen = 3200` (or higher for long headers). The default may be too low for extended SIP headers used in STIR/SHAKEN (e.g., `P-Asserted-Identity` with `verstat` parameters).
Header content truncated	In `voipmonitor.conf`, increase the `custom_headers_max_size` parameter (default: 1024 bytes): `custom_headers_max_size = 2048`. Headers longer than this value will be truncated during capture.

Performance Optimization: Database Index for Custom Headers

Custom header columns in cdr_next_X tables are not indexed by default to maintain high database write performance. If you plan to perform frequent or large-scale queries on a specific custom header, you should manually create a database index on that column to prevent full table scans.

Step 1: Find the table and column for your custom header

First, query the cdr_custom_headers lookup table to identify where your header is stored:

-- Find the dynamic table and column for your custom header
SELECT dynamic_table, dynamic_column
FROM cdr_custom_headers
WHERE header_field = 'X-Custom-Header';

Example Result:

dynamic_table	dynamic_column
2	3

This means your header is stored in cdr_next_2 table, column custom_header_3.

Step 2: Create the index manually

Execute the CREATE INDEX command using the table and column values found above:

-- Syntax: CREATE INDEX <index_name> ON <table_name> (<column_name>);
CREATE INDEX idx_custom_header_3 ON cdr_next_2 (custom_header_3);

Choose a descriptive index name following your naming convention (e.g., idx_header_X_Custom_Header).

Important Considerations:

⚠️ Warning: Performance Impact: Adding indexes increases database load during CDR insertion (write speed). Only create indexes on headers that are actively and frequently queried. Each additional index consumes disk space and slows down INSERT operations.

Partitioned Tables: If you use cdr_partition_by_hours or daily partitioning, the index is created on all partitions automatically. This benefits query performance on recent data.
Query Validation: Use EXPLAIN to verify the database uses your new index:

EXPLAIN SELECT cdr_ID FROM cdr_next_2 WHERE custom_header_3 = 'test_value';

Good Result: type: ref (Index lookup is used)
Bad Result: type: ALL (Full table scan - index is not being used)

Limitations

The GUI custom header feature has the following limitations:

Limitation	Description
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.).

💡 Tip: You CAN extract partial values from SIP headers! Use the Boundary start/end or Regexp fields in Settings > CDR Custom Headers. See the Extracting Substrings from SIP Headers section above for detailed examples.

Alternative: Populating Custom Headers from External Databases

When carrier or routing information is stored in an external database (not in SIP signaling), you can populate custom header columns using direct SQL updates from the external data source.

ℹ️ Note: Use Case vs SIP Capture: This method is useful when you have external data (e.g., carrier billing records) that is not available in SIP signaling. If you can add the carrier ID as a SIP header in the INVITE message, capturing via SIP traffic (see above) is preferred as it requires no external synchronization.

Step-by-Step: Import Carrier Data from External Database

Step 1: Create the Custom Header Column

Even if the data will be populated externally, you must define the header to create the database column:

1. Add to /etc/voipmonitor.conf:

custom_headers = x-termination-carrier

2. Restart the sensor:

systemctl restart voipmonitor

3. Configure in GUI > Settings > CDR Custom Headers (set Name and enable "Show as Column")

Step 2: Find the Table and Column Location

Query the cdr_custom_headers lookup table to identify where your custom header is stored:

SELECT dynamic_table, dynamic_column
FROM cdr_custom_headers
WHERE header_field = 'x-termination-carrier';

Example Result: dynamic_table = 2, dynamic_column = 1

This means the data is stored in table cdr_next_2 and column custom_header_1.

Step 3: Create Synchronization Script

Create a script (Python, PHP, or shell) to populate the custom header from your external database. The script connects to both databases and updates records based on a matching key.

Matching Keys:

cdr_ID: Internal VoIPmonitor CDR ID (most reliable if available in external DB)
Time and numbers: callend time + caller/called (less reliable)

SQL Example (run via cron):

-- Update VoIPmonitor table with carrier data from external database
-- Assuming external table 'external_billing' has 'cdr_id' and 'carrier_name'

UPDATE cdr_next_2 cn
JOIN external_db.billing eb ON cn.cdr_ID = eb.cdr_id
SET cn.custom_header_1 = eb.carrier_name
WHERE eb.carrier_name IS NOT NULL;

⚠️ Warning: Permissions Required: You must have UPDATE permissions on VoIPmonitor's cdr_next_X tables. Only update records you are certain match correctly. Test with SELECT queries first before running UPDATE statements.

Step 4: Create Charts Using the Imported Data

Once the data is synchronized, create charts filtering by the custom header:

1. Navigate to GUI > CDR > Charts 2. Click + to create a new chart 3. Add series with filters like x-termination-carrier = CarrierA 4. Each carrier appears as a separate line on the chart

For detailed information on charting custom headers, see Charts: Creating Percentage Comparisons for Custom SIP Headers.

Performance Considerations

Schedule sync scripts during off-peak hours to reduce database load
Index the matching column (cdr_ID) in both databases if not already indexed
Ensure cdr_ID is included in your external database for reliable matching
Consider using database connection pooling for frequent sync operations

Distributed Architecture: Headers Not Visible in Central GUI

If your deployment uses multiple sensors connected to a central GUI, and custom SIP headers are not appearing for calls from a specific sensor despite being configured and present in the traffic, the issue is typically that the sensor is not sending CDRs to the central database.

Core Issue: Sensor Not Connected to Central Server

The sensor may be capturing custom headers locally but not transmitting them to the central GUI database because:

The server_destination configuration is incorrect or missing on the sensor
The server_destination_port does not match the central server's server_bind_port
The server_password is incorrect
The sensor entry in the GUI has conflicting configuration

Solution Workflow:

1. Verify sensor configuration

On the affected sensor, check /etc/voipmonitor.conf:

# /etc/voipmonitor.conf on the SENSOR
id_sensor               = 2
server_destination      = central.server.ip
server_destination_port = 60024   # Must match server_bind_port on central server
server_password         = your_strong_password

# For Local Processing mode (recommended)
packetbuffer_sender     = no

Use a working sensor's configuration as a reference if available.

2. Delete and re-register the sensor in GUI

Sometimes stale sensor entries in the GUI database can cause connection issues.

Navigate to Settings > Sensors
Click the entry for the problematic sensor
Click Delete to remove it
Restart the sensor service:

systemctl restart voipmonitor

The sensor will automatically re-register with the GUI

3. Verify connection

After restarting, check that the sensor appears in Settings > Sensors with a connected status. Generate a test call and verify the custom headers appear in the CDR list.

Key Point: The server_destination, server_destination_port, and server_password settings control the encrypted TCP connection from the sensor to the central server. Without this connection, CDRs (including custom headers) cannot be transmitted to the central database.

For complete distributed architecture documentation, see Distributed Architecture: Client-Server Mode.

Troubleshooting

If custom SIP header data is correctly stored in the database and available for filtering but not displayed in the CDR list, follow these diagnostic steps:

Verify the sniffer has loaded the custom header configuration:

Use the manager API to confirm that the custom headers are loaded into the sniffer's memory:

# Create a temporary path for the manager socket
echo 'manager_file start /tmp/vmsck' | nc <manager_ip> <manager_port>

# Check loaded CDR custom headers
echo 'custom_headers_dump cdr' | nc -U /tmp/vmsck

# Cleanup
rm -f /tmp/vmsck

Replace <manager_ip> and <manager_port> with your sensor's manager connection settings (configured in Settings > Sensors or in voipmonitor.conf with managerip and managerport). The default manager port is 5029.

If no headers are listed, verify that:

You have added the header names to the custom_headers directive in voipmonitor.conf
You have restarted the voipmonitor service after adding headers
The cdr_custom_headers table contains the expected entries

Verify the data is present in the database:

Check that the custom header data is actually being captured and stored:

-- Step 1: Find the dynamic table and column for your custom header
SELECT dynamic_table, dynamic_column
FROM cdr_custom_headers
WHERE header_field = '<your_header_name>'\G

-- Step 2: Query the actual CDR data to confirm values are stored
SELECT cdr_ID, calldate, custom_header_<column_number>
FROM cdr_next_<table_number>
WHERE custom_header_<column_number> IS NOT NULL
ORDER BY cdr_ID DESC
LIMIT 1\G

Replace <your_header_name>, <table_number>, and <column_number> with the values returned by the first query.

Check for manual changes to the database:

⚠️ Warning: Do NOT manually modify the cdr_custom_headers table outside of the GUI. Manual changes (inserting, updating, or deleting records directly in the database) can cause synchronization issues between the GUI, the sniffer, and the actual data storage. Always use the GUI Settings > CDR Custom Headers interface to manage custom header definitions.

If you suspect manual changes were made, compare the entries in cdr_custom_headers with the headers listed in the manager API output and the columns present in the cdr_next_* tables.

Check for GUI rendering issues:

If the header data exists in the database but does not display in the CDR list, enable GUI debug mode to check for JavaScript errors:

Append ?debug=31415 to any GUI URL (e.g., https://your-gui.com/cdr/?debug=31415)

Then open your browser's Developer Console (F12) and look for JavaScript errors that might indicate a rendering problem. Common issues include:

Browser cache issues (try clearing cache or using incognito mode)
JavaScript conflicts from browser extensions
GUI service not restarted after configuration changes

Summary: Troubleshooting Checklist

[ ] Header appears in custom_headers_dump cdr manager API output
[ ] cdr_custom_headers table has correct mapping
[ ] Data exists in the appropriate cdr_next_* table
[ ] No manual modifications to cdr_custom_headers were made
[ ] "Show as Column" checkbox is enabled in Settings > CDR Custom Headers
[ ] Voipmonitor service has been restarted after configuration changes
[ ] No JavaScript errors in browser console (enable debug mode with ?debug=31415)

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`)
Sniffer second datapath	Path to the second spool directory (`spooldir_2`) configured in the sensor. This allows the GUI to access PCAP files stored in the secondary spool location. When configuring `spooldir_2` in `/etc/voipmonitor.conf`, set this field to the same path to enable the GUI to download PCAP, graph, and audio files from that location.
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)

⚠️ Warning: Troubleshooting: Sensors connect to wrong destination after upgrade

After a software upgrade, if sensors connect to the incorrect destination (e.g., the GUI server instead of the intended remote sensor), this is typically caused by default sensor hostname and default sensor TCP port being enabled.

When these default settings are enabled, sensors ignore their individual Manager IP/Port configuration from Settings > Sensors and use the default values instead. After an upgrade, this can cause sensors to connect to localhost or an outdated destination.

Solution:

Navigate to Settings > System Configuration > Basic
Disable default sensor hostname (clear the checkbox/field)
Disable default sensor TCP port (clear the checkbox/field)
Save the changes
Restart the sniffer service on affected sensors:

systemctl restart voipmonitor

After disabling these defaults, sensors will use their individual Manager IP and Manager Port settings from Settings > Sensors.

Database

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

==== Custom MySQL Port Configuration

By default, VoIPmonitor connects to MySQL/MariaDB using the standard port 3306. If your database server uses a custom port, you must update both the sniffer configuration and the GUI configuration.

Symptoms of incorrect port configuration:

GUI shows "Database connection failed" errors
Sniffer logs contain "Can't connect to MySQL server" message
CDR data is not appearing in the GUI even though the sniffer is running

Configuration Steps:

1. **Configure the Sniffer (Sensor):**

Edit /etc/voipmonitor.conf and set the mysqlport parameter:

# /etc/voipmonitor.conf
mysqlport = 33306

Restart the sniffer service after changing the configuration:

systemctl restart voipmonitor

2. **Configure the GUI:**

There are two ways to configure the GUI to use a custom MySQL port:

Option A: Via GUI Settings (Recommended)

Navigate to Settings > System Configuration > Database
Find the MySQL hostname field
Enter the host and port in the format hostname:port, for example: 127.0.0.1:33306 or db-server.example.com:33306
Save the configuration

⚠️ Warning: After changing the database connection settings, you may need to restart your web server or PHP-FPM service for the changes to take effect

Option B: Via configuration.php

Alternatively, you can edit the configuration file directly (typically located at /var/www/html/voipmonitor/php/configuration.php or /var/www/html/config/configuration.php).

Find or add the MYSQL_HOST definition and include the port in the hostname string:

// configuration.php

// Include port number in the hostname (colon-separated)
define('MYSQL_HOST', '127.0.0.1:33306');
define('MYSQL_USER', 'root');
define('MYSQL_PASS', 'your_password');
define('MYSQL_DB',   'voipmonitor');

ℹ️ Note: Some older GUI versions may use different constants. Check your configuration.php file for the exact constant names used in your installation. Common variations include DB_HOST, DB_PORT, or using a PHP array configuration pattern

Verification:

After configuring both the sniffer and GUI:

1. Check the sniffer logs for successful database connection:

# Check if sniffer is connecting to the correct port
systemctl status voipmonitor
tail -f /var/log/syslog | grep voipmonitor

2. Verify the GUI can connect to the database:

Open the VoIPmonitor web interface in your browser
If the page loads without errors, the connection is successful
Check the GUI connection status in Settings > System > Tools

3. Test with a live call:

Make a test call through your VoIP system
Verify the CDR appears in the GUI within a few seconds

Common Port Configuration Scenarios:

Scenario	Sniffer Configuration	GUI Configuration
Default MySQL port (local)	`mysqlport = 3306` (or omit parameter)	`MYSQL_HOST = "localhost"`
Custom MySQL port (local)	`mysqlport = 33306`	`MYSQL_HOST = "127.0.0.1:33306"`
Custom MySQL port (remote)	`mysqlport = 33306`	`MYSQL_HOST = "db-server:33306"`
SSH tunnel to remote DB	`mysqlport = 3307` (tunnel port)	`MYSQL_HOST = "localhost:3307"`

Related Documentation:

Sniffer Configuration - Full reference for voipmonitor.conf parameters
Secure Database Connection with SSL/TLS - For encrypted database connections
GUI Configuration PHP - For editing configuration.php directly
Database Troubleshooting - Common database-related issues and solutions

National

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

Setting	Description
Timezone	Server timezone for the GUI host (format: Country/City, e.g., Europe/Prague). This setting is used for scheduling reports and alerts generated by the GUI. It does NOT affect CDR data timestamps.
Sensors Timezone	Timezone for sensors sending CDR data to this database (format: Country/City, e.g., Europe/London). This setting controls how CDR timestamps are displayed in the GUI. Set this to match the timezone where your sensors are operating. All sensors sending data to this database should use the same timezone. This is the primary setting for correcting CDR timezone display issues.
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
International prefix	Prefix used for international calls from your country (e.g., `0011` for Australia, `00` for many countries, `011` for US/Canada)
Local number	Your country name or local region for number normalization (e.g., `Australia`, `United States`, `Czech Republic`)
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

💡 Tip: CDR Timezone Troubleshooting:

If CDR times are displaying in UTC instead of local timezone (e.g., showing in UTC instead of BST):

The fix is to set Sensors Timezone (NOT the regular Timezone setting) to the correct timezone for your sensors
Ensure all sensors sending data to this database are configured to use the same timezone
If a sensor's OS timezone differs from the Sensors Timezone setting, you can override it by editing /etc/voipmonitor.conf on the sensor and using the timezone or utc options
The regular Timezone setting is for the GUI host itself (report scheduling, alerts), not for CDR data display

Troubleshooting: International Numbers Not Displaying Correctly

If international numbers are not displaying or being handled correctly (e.g., missing country codes, showing in local format when they should be international), the local number and international prefix settings in the GUI may need to be configured.

Common Symptoms:

International numbers appear in local format only
Country codes are missing from displayed numbers
Numbers are not being classified as international
International calls are grouped incorrectly

Solution: Configure Local Number and International Prefix Settings

Navigate to Settings > System Configuration > National
Set the Local number field to your country name (e.g., Australia, United States, Czech Republic)
Set the International prefix field to the international dialing prefix for your country:

- Australia: 0011
- United States/Canada: 011
- Many European countries: 00
- Japan: 010

Save the settings

Example: Australia For an Australian deployment:

Local number: Australia
International prefix: 0011

These settings ensure that VoIPmonitor correctly normalizes and displays international numbers based on your local numbering plan.

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)

License

License and notification email configuration.

File:Settings-syslicense.png

Setting	Description
License token	Short text token for retrieving license key from VoIPmonitor portal
License key	Full license key content (multi-line text)
get/update license key	Button to fetch or update the license from the VoIPmonitor portal
License email	Email address for receiving license issue and overage notification emails

Updating License After Payment:

After purchasing or renewing a license through the voipmonitor.org portal, update your GUI license as follows:

Navigate to Settings > License
Click the get/update license key button

The GUI will automatically fetch your updated license from the portal if the payment has been processed. You do not need to manually enter a license key or token unless automatic retrieval fails.

Manually Retrieving License from Portal:

If the automatic update does not work, retrieve your license directly from the portal:

Log in to https://www.voipmonitor.org
Navigate to Services > My services
Locate your VoIPmonitor license
Click to view the license details
Copy the full license key content
Paste it into the License key field in Settings > License

Note: The license key is displayed as multi-line text. Ensure you copy the entire content when pasting.

To configure the license expiry notification for multiple recipients, enter all email addresses separated by a comma (e.g., user1@example.com,user2@example.com).

Disabling License Notification Emails:

To stop receiving license issue and overage notification emails:

Navigate to Settings > License
Remove the email address from the "License email" field
Save the changes

Note: This only disables license-related notification emails. Other automated emails (QoS alerts, daily reports, sensor health alerts) will continue to function.

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_CSRF_CHECK	Enable CSRF (Cross-Site Request Forgery) protection in the GUI. When enabled, the GUI validates CSRF tokens for state-changing operations, increasing session security and mitigating certain types of web attacks. Set to `TRUE` to enable. Recommended for production environments
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
Pcap deduplication before download	Enable to remove duplicate and retransmitted SIP/RTP packets when downloading PCAP files from the GUI. This may cause a mismatch between the packet count shown in the GUI SIP History and the packet count in the downloaded PCAP file. Disable to ensure the downloaded PCAP contains all captured packets including duplicates
Http proxy (for upgrades)	Proxy server address and port for automatic GUI and sniffer upgrades via the web interface. Required when the VoIPmonitor server is behind a corporate firewall or proxy and cannot connect directly to download.voipmonitor.org or github.com. Format: `http://proxy-server-ip:port` or `http://username:password@proxy-server-ip:port` for authenticated proxies
Enable GUI to run in iframe	Allow the GUI to be loaded in an `iframe` (embed the VoIPmonitor interface in other web applications). Set to `true` to enable. This is required when hosting the GUI in subfolders (e.g., `/ucloud`, `/unite`) within an iframe. By default, the GUI sends security headers that prevent iframe embedding for clickjacking protection

Troubleshooting: GUI Upgrades Behind Proxy Servers

If the GUI or sensor upgrade process fails due to network restrictions or firewall blocking direct internet access:

Solution 1: Configure HTTP Proxy in GUI (Recommended)

Navigate to Settings > System Configuration > Advanced
Find the Http proxy (for upgrades) field
Enter your proxy server address: http://proxy-server-ip:port
If authentication is required, include credentials: http://username:password@proxy-server-ip:port
Save the settings
Retry the GUI upgrade (Settings > System > Upgrade) or sensor upgrade (Settings > Sensors)

Solution 2: Proxy for Remote Sensors (curlproxy) For remote sensors that need to download packages independently, configure the curlproxy parameter directly on the sensor:

SSH into the remote sensor server
Edit the sensor configuration: sudo nano /etc/voipmonitor.conf
Add or modify the curlproxy line in the [general] section:

[general]
curlproxy = http://proxy-server-ip:port

Restart the sensor service: sudo systemctl restart voipmonitor
Retry the upgrade from the GUI (Settings > Sensors)

References:

Troubleshooting: Firewall Requirements for VoIPmonitor Functions

If your VoIPmonitor server has outbound network connections blocked by a firewall for security purposes, certain functions will fail without specific domain whitelisting.

Symptoms of blocked outbound connections:

Automatic license updates fail (license key expiration warnings)
GUI and sniffer upgrades fail via the web interface
"Share CDR" feature cannot send CDRs to the sharing server
"Generate debug report" feature cannot upload the report
Support sessions cannot connect

Required Outbound Domain Whitelist:

To ensure proper functionality when operating behind a restrictive firewall, configure firewall rules to allow the VoIPmonitor server to make outbound HTTPS connections to the following domains:

Domain	Purpose
`voipmonitor.org`	License key expiration updates and renewal checks
`download.voipmonitor.org`	Automatic GUI and sniffer binary upgrades via web interface
`share.voipmonitor.org`	"Share CDR" feature for sending call data to the sharing server
`reports.voipmonitor.org`	"Generate debug report" feature for uploading diagnostic reports
`vm1.voipmonitor.org` (IP: 37.157.192.45)	Support sessions and remote access

Protocol and Port Requirements:

Protocol: HTTPS (TCP port 443)
Direction: Outbound initiations from the VoIPmonitor server
Destination: Specific domains listed above (resolve to their current IP addresses via DNS)

License Check Mechanism:

The license expiration status is checked automatically by a cronjob that runs every minute:

# Automatic license check (runs every minute via cron)
php /var/www/html/php/run.php cron

You can also manually trigger a license check update:

# Manually check and update license status
php /var/www/html/php/run.php runUpdateLicenseKey

If the license check fails due to firewall blocking, VoIPmonitor may show incorrect expiration warnings or fail to renew licenses automatically.

Alternative Approaches:

If your security policy does not allow direct outbound connections to specific domains:

1. Use HTTP Proxy: Configure the Http proxy (for upgrades) setting in Settings > System Configuration > Advanced to route connections through an approved corporate proxy server 2. Manual Upgrade Method: Download packages manually on a machine with internet access and transfer via SCP/SFTP to the restricted server (see manual upgrade instructions) 3. Offline License Activation: For license management without internet access, use the offline method by retrieving the full multi-line license key from the voipmonitor.org portal and pasting it manually into Settings > License (see license documentation)

Configuration Example (iptables):

To allow outbound connections to VoIPmonitor domains using iptables:

# Allow outbound HTTPS to voipmonitor.org
iptables -A OUTPUT -p tcp -d voipmonitor.org --dport 443 -j ACCEPT

# Allow outbound HTTPS to download.voipmonitor.org
iptables -A OUTPUT -p tcp -d download.voipmonitor.org --dport 443 -j ACCEPT

# Allow outbound HTTPS to share.voipmonitor.org
iptables -A OUTPUT -p tcp -d share.voipmonitor.org --dport 443 -j ACCEPT

# Allow outbound HTTPS to reports.voipmonitor.org
iptables -A OUTPUT -p tcp -d reports.voipmonitor.org --dport 443 -j ACCEPT

# Allow outbound HTTPS to vm1.voipmonitor.org (IP: 37.157.192.45)
iptables -A OUTPUT -p tcp -d 37.157.192.45 --dport 443 -j ACCEPT

# Save iptables rules
service iptables save

Note: IP addresses for VoIPmonitor domains may change over time. For long-term firewall configurations, consider using DNS-based firewall rules, whitelist the authoritative DNS servers for these domains, or periodically review and update IP-based rules.

Troubleshooting: GUI in iframe Not Loading Properly

If the VoIPmonitor GUI is embedded in an iframe (e.g., from another web application) and fails to load or shows 301 redirect errors:

Symptoms:

Iframe displays error messages or blank content
301 redirect when accessing subfolder URLs (e.g., /ucloud, /unite)
Browser console shows refused to load in iframe errors

Solution: Enable iframe Support in System Configuration

The GUI sends security headers (such as X-Frame-Options) by default to prevent clickjacking attacks. To allow the GUI to run in an iframe:

Navigate to Settings > System Configuration > Advanced
Find the Enable GUI to run in iframe setting
Set it to true
Save the settings
Re-test the iframe functionality

Apply this setting to all relevant GUI installations/folders if you have multiple instances (e.g., /ucloud and /unite).

Additional Notes:

This is a GUI-level setting for security header configuration, not a web server configuration
After enabling, the browser should be able to load the GUI content within the iframe
For security reasons, only enable this if you trust the parent application hosting the iframe

Troubleshooting: License Key Renewal Failures

If the "get/update license key" button fails or the license cannot be renewed automatically, the most common cause is a firewall blocking outbound HTTPS connections to the VoIPmonitor portal.

Primary Solution: Configure Firewall Rules

The GUI requires outbound access to the VoIPmonitor portal servers via HTTPS (TCP port 443). Configure your firewall to allow:

# Example: Allow outbound HTTPS to voipmonitor.org
sudo firewall-cmd --permanent --add-service=https
# Or allow specific traffic
sudo firewall-cmd --permanent --add-rich-rule='rule family="ipv4" destination address="voipmonitor.org" port protocol="tcp" port="443" accept'
sudo firewall-cmd --reload

For iptables-based firewalls:

# Allow outbound HTTPS to voipmonitor.org
sudo iptables -A OUTPUT -p tcp -d voipmonitor.org --dport 443 -j ACCEPT
sudo iptables -A INPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
# Save rules (distribution-specific)
sudo iptables-save | sudo tee /etc/iptables/rules.v4

For corporate environments with restrictive firewalls or outbound web proxies, contact your network administrator to:

Allow outbound HTTPS (port 443) to voipmonitor.org
Allow access to download.voipmonitor.org and github.com (for upgrades)
Configure any necessary proxy settings (see GUI Upgrades Behind Proxy Servers)

Alternative Solutions

If you cannot configure firewall rules or have no internet access:

Option 1: Use HTTP Proxy

Configure the Http proxy (for upgrades) setting in Settings > System Configuration > Advanced if a corporate proxy is available. This setting routes HTTPS requests including license renewal through an approved proxy server.

Option 2: Offline Activation (Last Resort)

If network access is completely blocked, use offline activation:

Log in to https://www.voipmonitor.org
Navigate to Services > My services
Locate your VoIPmonitor license
Click the license button
Copy the full license key content (multi-line text including Expires, id, hwid, maxcalls, etc.)
Paste the full content into the License key field in Settings > License
Click Save

Verification After configuring firewall rules or updating the license:

Return to Settings > License
Click the get/update license key button
Verify the license status shows as current and not expired

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: sensor configuration (multi-sensor deployments, SSL/TLS decryption via GUI wrench icon, SIP port configuration, RTP storage limits), sensor health monitoring via RRD charts (buffer usage, packet drops for diagnosing overload), disabling sensors (GUI "Disabled" option does NOT stop data collection - use systemctl stop or capture rules with SKIP=ON), non-deletable local sensor troubleshooting (on central GUI+DB servers, the auto-created local sensor defaults to being counted in SUM counters and charts; solution is to set id_sensor in voipmonitor.conf and add manual sensor configuration with Manager IP 127.0.0.1, same Sensor ID, Manager Port 5029, enable "is server in client/server mode", disable "show active calls from all sensors in active call view" - this replaces and overrides the default localhost entry, preventing it from appearing in statistics), sensor deletion troubleshooting (cannot delete sensors with active capture rules - delete rules first via Control Panel > Capture Rules), CDR custom headers (configuration, Select occurrence field for handling re-INVITEs, database index optimization, limitations), system configuration (default sensor hostname and TCP port - when enabled, sensors ignore individual Manager IP/Port settings and use defaults, causing wrong destination after upgrade; solution is to disable both defaults and restart sensors), system configuration (timezone settings - use "Sensors Timezone" for CDR display, international number prefixes), license management (get/update license key button, firewall requirements for license checks, license email configuration for controlling "Channels limit reached" and license expiration notification emails - remove email address to disable these alerts), advanced settings (HTTP proxy for upgrades, CSRF protection, iframe embedding), localization, and custom CDR URLs. Key troubleshooting: firewall must allow outbound HTTPS to voipmonitor.org and download.voipmonitor.org for license updates and upgrades; sensors connecting to wrong destination after upgrade is caused by enabled default sensor hostname/port settings; central GUI+DB servers have auto-created local sensor counted in SUM counters - use id_sensor override method to replace it.

Keywords: GUI settings, sensors, sensor configuration, SSL/TLS decryption, RRD charts, buffer usage, packet drops, disable sensor, capture rules SKIP, sensor deletion, capture rules blocking deletion, non-deletable local sensor, auto-created local sensor, default localhost sensor, SUM counters, charts, central GUI server, GUI DB only, id_sensor override, replace local sensor, central server sensor, CDR custom headers, custom_headers, select occurrence, first found value, P-Asserted-Identity, database index, system configuration, default sensor hostname, default sensor TCP port, wrong destination after upgrade, sensors connect wrong host, sensors timezone, CDR timezone, international prefix, local number, license update, get/update license key, license email, Channels limit reached, license expiration alert, disable notification emails, license notifications, firewall requirements, HTTP proxy, curlproxy, CSRF protection, iframe embedding, localization, custom URL

Key Questions:

How do I configure sensors in the VoIPmonitor GUI?
How do I configure SSL/TLS decryption for a sensor via the GUI?
How do I disable the default local sensor on a central GUI+DB only server?
Why is the auto-created local sensor counted in SUM counters and charts?
How do I use id_sensor to override the default local sensor on a central server?
How do I configure a manual sensor entry to replace the default localhost sensor?
Why are my sensors connecting to the wrong destination after a software upgrade?
How do I fix sensors connecting to localhost instead of their Manager IP?
What are default sensor hostname and default sensor TCP port settings?
Should I enable or disable default sensor hostname and TCP port?
How do I access sensor RRD charts for health monitoring?
How do I disable a sensor and stop it from collecting data?
Why can I not delete a sensor from the GUI?
How do I delete a sensor that has capture rules assigned?
How do I configure CDR custom headers?
What is the "select occurrence" field in CDR custom headers?
How do I capture only the initial INVITE header and ignore re-INVITEs?
How do I add a database index to a custom SIP header?
How do I fix CDR times displaying in UTC instead of local timezone?
How do I configure international number prefixes?
How do I update my license after payment?
What firewall rules are required for VoIPmonitor license updates?
How do I configure HTTP proxy for GUI upgrades?
How do I disable "Channels limit reached" notification emails?
Where do I configure the license email for notifications?
How do I enable the GUI to run in an iframe?
How do I enable CSRF protection in the GUI?