Capture rules

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. Use this to completely exclude certain traffic from monitoring. Important: This option only works if the specified IP address or phone number appears in the SIP signalling. It will not work if the IP is only used for RTP packets (the media stream). For excluding traffic that only appears in RTP, use the filter directive in voipmonitor.conf instead.
Auto remove at	Automatically deletes the rule on a specified date. Useful for temporary debugging rules that should not persist indefinitely.

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

Advanced: Managing Rules via Database

For automation, bulk operations, or scripted deployments, you can manipulate capture rules directly in the MySQL database. This method is ideal for:

• Automated provisioning systems
• Bulk rule creation
• Integration with external management tools
• Remote sensor management without GUI access

Database Tables

Capture rules are stored in two tables in the voipmonitor database:

Table	Purpose
filter_ip	IP address and subnet-based rules
filter_telnum	Telephone number prefix-based rules

Adding IP-Based Rules

Rules in the filter_ip table match source or destination IP addresses or subnets.

Key Columns:

Column	Type	Description
ip	INT UNSIGNED	IP address converted using INET_ATON()
mask	TINYINT	Subnet mask in CIDR notation (e.g., 24 for /24)
direction	TINYINT	0 = both, 1 = source, 2 = destination
rtp	TINYINT	1 = SAVE, 2 = DISCARD, 3 = header only

Example: Force-save RTP for all calls from or to the 1.2.3.0/24 network:

INSERT INTO voipmonitor.filter_ip
    (ip, mask, direction, rtp)
VALUES
    (INET_ATON('1.2.3.0'), 24, 0, 1);

Adding Telephone Number-Based Rules

Rules in the filter_telnum table match caller or called number prefixes.

Key Columns:

Column	Type	Description
prefix	VARCHAR	Telephone number prefix to match (e.g., 4420)
fixed_len	TINYINT	Fixed length matching (0 = prefix match)
direction	TINYINT	0 = both, 1 = caller, 2 = called
rtp	TINYINT	1 = SAVE, 2 = DISCARD, 3 = header only

Example 1: Match any direction - force RTP saving when caller or called number starts with 12345:

INSERT INTO voipmonitor.filter_telnum
    (prefix, fixed_len, direction, rtp)
VALUES
    ('12345', 0, 0, 1);

Example 2: Match only destination - force RTP saving only when the called number starts with 98765:

INSERT INTO voipmonitor.filter_telnum
    (prefix, fixed_len, direction, rtp)
VALUES
    ('98765', 0, 2, 1);

Reloading Rules

After adding or modifying rules (via GUI or database), you must signal the sniffer to reload them. Rules do not take effect until reloaded.

Method 1: 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: Manager API (CLI)

For directly accessible sensors, send a reload command to the Manager API port (default 5029):

# Replace SENSOR_IP with your sensor's IP address
echo 'reload' | nc SENSOR_IP 5029

Use this method for automation or when GUI access is not available.

Method 3: Server API (Client/Server Mode)

If sensors are in client/server mode and Manager API ports are not directly accessible, send commands via the central server.

Step 1: Get list of connected sensors and their IDs:

echo 'list_active_clients' | nc SERVER_IP 5029

Example output:

{"count":1,"services":[{"ip":"127.0.0.1","port":54137,"sensor_id":114}]}

Step 2: Send reload command via Server API port (default 60024):

echo '{"type_connection":"gui_command","sensor_id":114,"command":"reload"}' | nc SERVER_IP 60024

The central server forwards the command to the specified remote sensor over its secure channel.

Troubleshooting

If changes made to capture rules in the GUI are not being applied, the most common cause is that the reload signal did not reach 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.

# Replace SENSOR_IP with your sensor's actual IP address
echo 'getversion' | nc SENSOR_IP 5029

Result	Meaning	Action
Version string (e.g., voipmonitor 8.0.0-SVN.10)	Connectivity OK	Proceed to reload
No output / connection times out	Network problem	Check firewall and routing
Connection refused	Manager API not running	Check sensor service status

Common Connectivity Issues

Issue	Solution
Firewall blocking port 5029	Ensure port 5029/TCP is open on the sensor's firewall
Wrong IP in Settings > Sensors	Verify the Manager IP matches the sensor's actual IP address
NAT/Routing issues	For sensors behind NAT, use the Server API method (Method 3 above)

Step 2: Immediate Workaround - Restart Sniffer

If reload fails and connectivity cannot be resolved immediately, restart the sniffer service:

# SSH to the sensor
ssh root@SENSOR_IP

# Check current status
systemctl status voipmonitor

# Restart (forces full reload of all rules)
systemctl restart voipmonitor

Note: Restarting causes a brief interruption in call monitoring.

Verifying Rules Are Active

After reloading rules, verify they are applied:

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
• Use monitoring tools to detect connectivity issues early
• Consider client/server mode for sensors in different networks - uses persistent connections that are more reliable than direct Manager API access

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 for ignoring calls, Auto remove for temporary rules), GUI usage, and script integration via filtercommand. The Skip option only works if the IP or phone number appears in SIP signalling - it will not work if the IP is only used for RTP packets (use the filter directive in voipmonitor.conf instead). The advanced section explains how to programmatically manage rules by directly inserting into the filter_ip and filter_telnum MySQL tables, with detailed column explanations and SQL examples using INET_ATON() for IP conversion. Three reload methods are documented: GUI button (recommended), CLI via Manager API (echo 'reload' | nc), and Server API for client/server deployments using list_active_clients and JSON commands. The troubleshooting section explains how to diagnose connectivity issues using the getversion command, common problems (firewall, wrong IP, NAT), and verification steps.

Keywords: capture rules, selective recording, RTP packets, SIP signaling, filter_ip, filter_telnum, INET_ATON, database, SQL, sniffer reload, GLOBAL option, skip calls, auto-remove, filtercommand, manager api, server api, getversion, port 5029, port 60024, list_active_clients, troubleshooting, client server mode, signalling, media stream, filter directive, exclude traffic

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?
• Does Skip work for RTP packets that don't appear in SIP signalling?
• How can I exclude traffic with IP only in RTP packets?
• How can I auto-delete a rule after a certain date?
• Can rules trigger external scripts?
• How can I add capture rules without using the GUI?
• How to add IP or telephone number based filters directly to the database?
• What do the direction and rtp columns mean in the filter_ip table?
• 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 reload rules on a remote sensor in client/server mode?
• How do I verify that capture rules have been reloaded?