Capture rules

From VoIPmonitor.org
Revision as of 18:54, 4 January 2026 by Admin (talk | contribs) (Merge Capture_rules_troubleshooting into main page, improve formatting with tables and diagram, fix structure)

Capture rules allow selective recording of calls to disk based on IP addresses or phone numbers. By default, RTP packets may not be fully saved (or only headers are stored), but rules can enable full RTP recording, call graphs, or SIP signaling capture for specific calls. Rules can also trigger external shell scripts for custom processing.

How Capture Rules Work

The sniffer loads capture rules on startup and supports hot-reloading without service restart. Changes made in the GUI are not automatically applied to the running sniffer - you must click the green "reload sniffer" button in the control panel to apply them.

Rule Options

Capture rules support the following configuration options:

3-State Options

Some options use a 3-state selector:

State Description Use Case
GLOBAL Inherits from global sniffer configuration Enable SIP REGISTER for specific IPs without overriding RTP settings
ON Explicitly enables the option Force RTP recording for matched calls
OFF Explicitly disables the option Disable recording for matched calls

Special Options

Option Description
Skip Ignores matched calls entirely - no files are created, no RTP analysis is performed, and no CDR is generated
Auto remove at Automatically deletes the rule on a specified date (useful for temporary debugging rules)

Script Integration

Rules can trigger external shell scripts when calls match. Configure this via the filtercommand option in voipmonitor.conf. See Sniffer_configuration#filtercommand for details.

GUI Usage

Access capture rules via the GUI control panel:

  1. Navigate to Control Panel (Dashboard)
  2. Click on Capture Rules section
  3. Create rules using IP or TEL number filters
  4. Click the green reload sniffer button to apply changes
IP-based capture rule configuration
Telephone number-based capture rule configuration

Troubleshooting

If changes made to capture rules in the GUI are not being applied, the most common cause is that the reload signal never reached the sensor due to network connectivity issues.

Step 1: Test Manager API Connectivity

Before attempting a reload, verify that the GUI can reach the sensor's Manager API port (default 5029).

Test connectivity from the GUI server: 

# Replace PROBE_IP with your sensor's actual IP address
echo 'getversion' | nc PROBE_IP 5029
Result Meaning Action
Version string (e.g., voipmonitor 8.0.0-SVN.10) Connectivity OK Proceed to Step 2
No output / connection times out Network problem Check firewall and routing
Connection refused Manager API not running Check sensor service status

Common Connectivity Issues

  • Firewall blocking port 5029 - Ensure port 5029/TCP is open on the sensor's firewall
  • Wrong IP address in Settings > Sensors - Verify the Manager IP matches the sensor's actual IP
  • NAT/Routing issue - For sensors behind NAT, use the Server API method (see below)

Step 2: Reload Methods

If connectivity test succeeds, use one of these reload methods:

Method 1: Web GUI Reload Button (Recommended)

  1. Log in to the VoIPmonitor GUI
  2. Navigate to Control Panel (Dashboard)
  3. Click the green reload sniffer button
  4. Check for error messages if reload fails

Method 2: CLI Manager API

echo 'reload' | nc PROBE_IP 5029

Use this method if you cannot access the GUI or need automation.

Method 3: Server API (for Client/Server Mode)

If sensors are in client/server mode and manager ports aren't directly accessible: 

# Step 1: List connected sensors and get sensor_id
echo 'list_active_clients' | nc SERVER_IP 5029

# Step 2: Send reload command via Server API port (default 60024)
echo '{"type_connection":"gui_command","sensor_id":SENSOR_ID,"command":"reload"}' | nc SERVER_IP 60024

Replace SENSOR_ID with the ID from Step 1 and SERVER_IP with the central server's IP.

Step 3: Immediate Workaround - Restart Sniffer

If the reload fails and you cannot resolve the connectivity issue immediately, restart the sniffer service on the sensor: 

# SSH to the sensor
ssh root@SENSOR_IP

# Check current status
systemctl status voipmonitor

# Restart the service (this forces a full reload of all rules)
systemctl restart voipmonitor

Verifying Rules Are Active

After reloading rules, verify they are active:

1. Check logs for reload confirmation: 

# Debian/Ubuntu
tail -f /var/log/syslog | grep voipmonitor

# CentOS/RHEL/AlmaLinux
tail -f /var/log/messages | grep voipmonitor

Look for messages like Rules reloaded or capture rules re-read.

2. Make a test call that should trigger your new rule and verify the recording behavior matches expectations.

3. Monitor CDR view to confirm captured/skipped calls match your rule configuration.

Preventing Future Issues

  • Ensure stable network connectivity between GUI and sensors for reliable rule management
  • Use monitoring tools to detect network connectivity issues early
  • Consider client/server mode if sensors are in different networks - the Server API uses persistent connections that are more reliable

AI Summary for RAG

Summary: This article explains VoIPmonitor's capture rules for selective call recording based on IP addresses or phone numbers. It covers rule configuration options (3-state GLOBAL/ON/OFF, Skip, Auto remove), GUI usage, and script integration via filtercommand. The troubleshooting section explains how to diagnose and fix issues when rule changes are not applied, including testing Manager API connectivity with the getversion command, three reload methods (GUI button, CLI, Server API), and verification steps.

Keywords: capture rules, selective recording, RTP packets, SIP signaling, sniffer reload, GLOBAL option, skip calls, auto-remove, filtercommand, manager api, getversion, port 5029, troubleshooting, reload not working

Key Questions:

  • How do capture rules work in VoIPmonitor?
  • What are the 3-state options (GLOBAL/ON/OFF) for rules?
  • How do I reload rules without restarting the sniffer?
  • What does the Skip option do?
  • How can I auto-delete a rule after a certain date?
  • Can rules trigger external scripts?
  • Why are capture rules not being applied after I change them in the GUI?
  • How do I test if the GUI can reach the sensor's Manager API?
  • How can I reload capture rules if the sensor is behind NAT?
  • How do I verify that capture rules have been reloaded?
Retrieved from "https://www.voipmonitor.org/doc/index.php?title=Capture_rules&oldid=6553"