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.

Capture Rule Limitations

Understanding what capture rules do NOT support is important for planning your recording strategy:

Requirement	Supported	Solution
SIP header-based filtering	NO	Capture rules cannot match based on SIP headers like `X-Custom-Header`. VoIPmonitor does not support capture rules that trigger based on the presence or value of SIP headers.
Source AND Destination combinations	NO	Capture rules for IP addresses use OR logic (e.g., listing two IPs matches traffic involving either one). You cannot create a rule like "IP1 AND IP2" to capture only traffic between specific endpoint pairs.
IP direction matching only	YES	You can specify rules for source IP, destination IP, or both directions.
Phone number direction matching only	YES	You can specify rules for caller number, called number, or both directions.

For scenarios requiring SIP header filtering or complex IP pair combinations, use the filter directive in /etc/voipmonitor.conf with Berkeley Packet Filter (BPF) syntax instead. See Alternatives to Capture Rules below for details.

Rule Options

Capture rules support the following configuration options:

3-State Options

Most 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

RTP Options (4 States)

The RTP capture option has an additional fourth state:

State	Description	Use Case
GLOBAL	Inherits from `savertp` configuration from `voipmonitor.conf`	Use global setting (usually `savertp = yes` or `savertp = header`)
ON	Save full RTP audio payload	Override global to record complete audio for matched calls
OFF	Discard RTP entirely	Disable RTP recording for matched calls
HEADER	Save only RTP headers (no audio payload)	Capture quality metrics (MOS, jitter, packet loss) without storing audio

Example: Set global default to headers only, then record full audio for specific IPs

In voipmonitor.conf:

savertp = header

Then create a GUI capture rule for the IP(s) that need full audio, and set the RTP option to ON.

For more details on savertp = header configuration, see Data Cleaning - Save Only RTP Headers.

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 or compliance scenarios where rules must have limited lifetimes. Important: This setting deletes the rule entirely from the database when the date is reached (the rule is removed, not deactivated). The auto-removal action is NOT logged to the Audit Log.

PCI DSS Compliance Use Case: Selective DTMF Recording

For PCI DSS compliance scenarios where DTMF storage must be disabled globally but troubleshooting capability is required for specific cases:

1. Disable DTMF globally in voipmonitor.conf:

dtmf2db = no

2. Create a capture rule exception for specific traffic:

Access the GUI capture rules interface (Control Panel > Capture Rules) and create a rule matching the specific IP address, telephone number, or domain that requires DTMF troubleshooting. Set the record DTMF option to ON for this rule.

This approach stores DTMF details only for traffic matching the specific criteria in the rule, maintaining PCI DSS compliance for the majority of calls while preserving troubleshooting capabilities for targeted cases.

Key considerations:

Rule scope should be as narrow as possible (specific IP, phone number, or domain) to minimize data retention
Use Auto remove at to automatically delete the rule after the troubleshooting period
Restrict capture rule creation permissions to trusted administrators (see User Management)

Compliance and Auditability Limitations

Capture rules have specific limitations for compliance scenarios requiring strict audit trails:

Requirement	Status	Notes
Automatic rule expiration	Supported	Use the Auto remove at option to delete rules on a specific date. Additionally, an autoexpire timeout feature in user settings prevents users from creating permanent rules.
Track which user created/modified a rule	NOT Supported - Partial	The Audit Log shows the timestamp and IP address of rule modifications, but does NOT record which specific user made a change nor what specific options were changed (e.g., enabling DTMF recording). See Inspection Methods for DTMF Recording for workarounds.
Deactivate rules temporarily	NOT Supported	Rules can only be active or deleted. There is no "disable" or "deactivate" state. The Auto remove at option permanently deletes rules rather than deactivating them.
Log auto-removal to Audit Log	NOT Supported	When a rule expires and is deleted via the Auto remove at option, this action is NOT logged in the Audit Log.

For compliance requirements (such as PCI DSS 4.0), you should:

Use the autoexpire timeout feature in user settings to enforce temporary rule lifetimes
Restrict capture rule creation/deletion permissions to trusted administrators (see User Management)
For compliance scenarios requiring detailed audit trails, implement external tracking via database triggers or scripting based on the filter_ip and filter_telnum tables
Use the inspection methods in the section below to verify current DTMF recording flags on rules

Inspection Methods for DTMF Recording

When you need to verify which capture rules currently have DTMF recording enabled, there is no built-in alert or detailed Audit Log entry. However, you can use the following methods to inspect the current state:

Method	Description	Example
Audit Log	Shows when a rule was last modified and from which IP address, but does NOT indicate what specific changes were made (e.g., which options were enabled/disabled).	Check GUI > Users & Audit for login/logout timestamps and filter_ip/filter_telnum table modification timestamps.
Database Query	Query the `filter_ip` and `filter_telnum` tables directly to list all rules where DTMF recording is enabled.	`SELECT ip,INET_NTOA(ip) as ip_addr,direction FROM voipmonitor.filter_ip WHERE dtmf=1;` (for IP-based rules)
Manager API	Connect to the sniffer's manager API port (default 5029) and use the `crules_print` command to display all active capture rules with their flags.	nc SENSOR_IP 5029

Important: These inspection methods show the CURRENT state of capture rules. They do NOT provide a historical audit trail of when specific options (like DTMF recording) were enabled or disabled.

For a historical audit trail, you must implement custom logging (e.g., database triggers or external scripts) that capture changes to the filter_ip and filter_telnum tables over time.

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.

Store pcaps to second spooldir

Capture rules can route PCAP files for specific traffic to a secondary storage directory (spooldir_2) with separate retention policies.

Use Cases:

Legal holds / Compliance: Store calls involving specific phone numbers, carriers, or customer segments in a separate directory that never auto-deletes (or has very long retention).
VIP customers: Apply different retention policies for high-value client traffic.
Regulatory requirements: Store traffic from specific jurisdictions with mandatory long-term retention.

Configuration Steps:

1. Configure spooldir_2 in voipmonitor.conf:

# Define secondary spooldir location
spooldir_2 = /var/spool/voipmonitor2

# Set separate retention for spooldir_2 (optional)
maxpoolsize_2 = 1000G
maxpooldays_2 = 365

If maxpoolsize_2 and maxpooldays_2 are not set, the spooldir_2 will use the same auto-cleaning rules as the primary spooldir.

2. Create a capture rule:

Access the GUI capture rules interface (Control Panel > Capture Rules) and create a rule matching the specific IP addresses or telephone numbers. Enable the Store pcaps to second spooldir option for this rule.

3. Click "Apply" and "reload sniffer" to activate the rule.

Important Notes:

spooldir_2 is NOT an automatic overflow directory. When the primary spooldir becomes full, the cleanspool process deletes the oldest files from the primary directory - it does NOT automatically write to spooldir_2.
Only the PCAP files from calls matching the capture rule are stored in spooldir_2. All other traffic continues to write to the primary spooldir.
You can apply different auto-cleaning rules to spooldir_2 (e.g., maxpoolsize_2, maxpooldays_2) to independently manage retention for special traffic.

For more details on spooldir_2 configuration, see Storage & File Management in the sniffer configuration reference.

On-Demand Audio Generation via GUI

You can configure VoIPmonitor to save RTP packets to a custom location specifically for on-demand audio generation and playback through the GUI. This is useful when you want to store RTP files separately from your main spooldir.

Use Cases:

Separate storage for audio playback:** Keep RTP files on fast local storage (SSD/NVMe) while other data goes to larger HDD storage
On-demand audio generation:** Generate and play back audio files for specific calls through the GUI interface
Selective audio archiving:** Store only selected calls' RTP packets in a dedicated location

Configuration Steps:

1. Configure spooldir_rtp in voipmonitor.conf:

# Set custom directory for RTP packets (for on-demand GUI playback)
spooldir_rtp = /path/to/your/storage

This directory will store RTP packets for calls matching capture rules with recordRTP=ON enabled.

2. Restart the voipmonitor service:

systemctl restart voipmonitor

3. Create a capture rule to enable RTP recording:

Access the GUI capture rules interface (Control Panel > Capture Rules) and create a new rule:

Set the desired criteria (IP addresses, telephone numbers, or leave it global)
Enable the RTP option to ON (this sets recordRTP=ON for the rule)
Save the rule

4. Reload the sniffer:

Click the green reload sniffer button in the GUI Control Panel to apply the new rule.

After this setup:

RTP packets from calls matching your capture rules will be saved to the spooldir_rtp directory you configured
Audio files can be generated and played back through the GUI for those calls
Other files (PCAP, graphs, etc.) continue to use the main spooldir

Important Notes:

spooldir_rtp only affects calls captured by rules with the RTP option set to ON. Without an active capture rule with recordRTP=ON, RTP packets will not be saved to this directory.
The directory specified in spooldir_rtp must exist and be writable by the voipmonitor user before starting the service.
This configuration is separate from the main spooldir and spooldir_2 - it exists specifically for RTP packet storage.

For more details on spooldir_rtp and other storage configuration options, see Storage & File Management in the sniffer configuration reference.

GUI Usage

Access capture rules via the GUI control panel:

Navigate to Control Panel (Dashboard)
Click on Capture Rules section
Create rules using IP or TEL number filters
Click the green reload sniffer button to apply changes

Telephone number-based capture rule configuration

Saving Only RTP Headers

To capture only RTP headers (without audio payload) while reducing storage overhead by up to 90%:

Option A: Apply to all calls globally using voipmonitor.conf

In /etc/voipmonitor.conf, set:

savertp = header

This applies to all calls captured by the sensor. Restart the sniffer to apply changes.

Option B: Use GUI Capture Rules for selective header-only capture

Access capture rules via the GUI control panel:

Navigate to Control Panel (Dashboard)
Click on Capture Rules section
Create or edit a rule (IP-based or telephone number-based)
In the RTP dropdown, select the options:
- HEADER - Save only RTP headers (no audio payload)
- Use this to capture quality metrics (MOS, jitter, packet loss) without storing audio
- Significantly reduces storage (up to 90% reduction vs full audio)
Click Apply
Click the green reload sniffer button to apply changes

Selective OPTIONS Recording

Capture rules support selective recording of SIP OPTIONS (qualify pings), SUBSCRIBE, and NOTIFY messages for specific IP addresses or phone numbers. This allows you to monitor OPTIONS pings for critical endpoints without saving packets globally across all traffic.

To enable selective OPTIONS recording:

In voipmonitor.conf, set the global setting to prevent saving for all IPs:

save-sip-options = no

In the GUI Capture Rules interface, create an IP-based rule for the specific endpoint
Enable the Record OPTIONS option for that rule
Click Apply and reload sniffer

This configuration saves OPTIONS packets to PCAP files only for the specified IP addresses, satisfying requirements like "save OPTIONS packets for specific IPs without saving them for all traffic."

The PCAP files for OPTIONS will appear in the GUI under SIP Opt/subsc/notify active or stored and will only include traffic matching the capture rule(s).

For more information on SIP OPTIONS configuration and storage settings, see SIP_OPTIONS/SUBSCRIBE/NOTIFY.

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)

Log in to the VoIPmonitor GUI
Navigate to Control Panel (Dashboard)
Click the green reload sniffer button
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

Audio Recording Despite savertp=header or saveaudio=no

If audio is being captured even though your local /etc/voipmonitor.conf has savertp = header or saveaudio = no, the most likely cause is that **capture rules are overriding your global settings**.

Capture rules with the RTP option set to ON (or explicit SAVE) will force full RTP audio recording for matched calls, regardless of your global savertp or saveaudio configuration. This is by design - capture rules provide granular control to override global settings for specific IPs, phone numbers, or subnets.

Troubleshooting Steps:

1. Confirm audio is actually being saved:

  * Open the VoIPmonitor GUI
  * Navigate to the CDR table and find a recently captured call
  * Click on the call and attempt to create a WAV file
  * If audio is successfully extracted, the issue is confirmed

2. Check for active capture rules:

  * Navigate to GUI > Control Panel > Capture Rules
  * Look for any rules with the recordRTP option set to ON or SAVE
  * Even a single active rule with recordRTP enabled can trigger audio recording

3. Disable or remove the conflicting rules:

  * Either delete the rules entirely, or
  * Set the recordRTP option to OFF or GLOBAL to inherit from your local configuration
  * Click the green reload sniffer button to apply changes
  * Alternatively, wait up to one minute for automatic application

4. Verify the fix:

  * Make new test calls and check that audio is no longer being captured
  * Attempt to create WAV files in the GUI to confirm audio is not extracted

If the issue persists after removing all capture rules, check if database-based configuration overrides are active (see mysqlloadconfig in the sniffer configuration reference for details on database priority).

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

Alternatives to Capture Rules

Capture rules are not always the best solution for traffic filtering. The following alternatives may be more appropriate for specific scenarios depending on CPU constraints, filtering precision, and call merging behavior.

Using the `filter` Directive in voipmonitor.conf

For excluding packets from a specific IP address that do NOT appear in SIP signalling (RTP-only traffic) or when you need to exclude a single IP from a merged CDR without affecting other call legs, use the filter directive in the sensor's configuration file (/etc/voipmonitor.conf).

When to use filter instead of Capture Rules:

The IP address only appears in RTP packets (media stream), not in SIP signalling
You need to exclude a specific IP from a merged CDR without skipping unrelated call legs
Capture rules with the Skip option are skipping more calls than intended due to shared infrastructure (SBC, proxy load balancer)
You need to capture traffic only between specific IP pairs (AND logic, not OR). For example, capture calls only between "Host A AND Host B" or " (Host A AND Host C) OR (Host D AND Host E)"

Syntax and Examples:

# Exclude all packets from a specific IP address (recommended for single IPs)
filter = not host 187.60.50.46

# Exclude multiple specific IPs
filter = not host 187.60.50.46 and not host 192.168.1.100

# Exclude an entire subnet
filter = not net 10.0.0.0/8

# Capture traffic only between specific IP pairs (AND logic)
# Example: Capture only traffic between Host A and Host B (in both directions)
filter = host 192.168.1.10 and host 10.0.0.5

# Capture traffic between multiple IP pairs using OR combinations
# Example: Capture traffic between (Host A AND Host B) OR (Host A AND Host C)
filter = (host 192.168.1.10 and host 10.0.0.5) or (host 192.168.1.10 and host 10.0.0.6)

Important Considerations:

CPU Impact: The filter option uses libpcap's Berkeley Packet Filter (BPF) engine, which processes every packet. This adds CPU load to the sensor. For high-traffic environments, this may significantly impact performance.
Must restart sniffer: Changes to filter require a full service restart (systemctl restart voipmonitor) to take effect, unlike capture rules which can be reloaded dynamically.
Router/firewall filtering is better: For the best performance, drop unwanted packets at the network infrastructure level (router, firewall, or layer-3 switch) BEFORE they reach the sensor's network interface card. This completely eliminates the CPU overhead on the VoIPmonitor sensor.

For detailed documentation on the filter directive and its BPF syntax, see = filter in the sniffer configuration reference.

AI Summary for RAG

Summary: VoIPmonitor capture rules enable selective call recording based on IP addresses or phone numbers. Key features include 3-state options (GLOBAL/ON/OFF), RTP 4-state (adds HEADER for metadata-only), Skip (ignore calls entirely), and Auto remove at (time-limited rules). Critical limitations: SIP header-based filtering NOT supported, IP combinations use OR logic only (no AND). For complex filtering, use the filter directive with BPF syntax. Selective OPTIONS recording allows saving SIP OPTIONS for specific IPs when save-sip-options = no globally. PCI DSS compliance: set dtmf2db = no globally, enable DTMF per-rule for troubleshooting. Compliance limitations: auto-expiration supported, but user tracking partial (Audit Log shows IP/timestamp only), no temporary deactivation, auto-removal not logged. Inspection methods: crules_print via Manager API, database queries (WHERE dtmf=1). Rules stored in filter_ip/filter_telnum tables. Reload via GUI button, Manager API (echo 'reload' | nc IP 5029), or Server API for client/server mode. Troubleshooting: Audio recording despite savertp=header usually caused by capture rules with RTP=ON overriding global settings. Storage options: spooldir_2 for separate retention (legal holds, VIP), spooldir_rtp for on-demand GUI audio generation - both require active capture rules.

Keywords: capture rules, selective recording, RTP packets, filter_ip, filter_telnum, INET_ATON, sniffer reload, GLOBAL option, skip calls, auto-remove, filtercommand, manager api, port 5029, client server mode, filter directive, BPF, PCI DSS, DTMF, dtmf2db, crules_print, SIP OPTIONS, Record OPTIONS, save-sip-options, capture rule limitations, SIP header filtering not supported, IP pair combinations, AND logic, spooldir_2, legal hold, retention policies, maxpoolsize_2, savertp override, recordRTP, mysqlloadconfig, spooldir_rtp, on-demand audio generation, GUI audio playback

Key Questions:

How do capture rules work in VoIPmonitor?
What are the 3-state and 4-state options for capture rules?
What are the limitations of capture rules (SIP headers, IP AND logic)?
How do I reload rules without restarting the sniffer?
Why is audio recorded despite savertp=header? Can capture rules override global settings?
What does the Skip option do? Does it work for RTP-only IPs?
How can I auto-delete a rule after a certain date?
How can I add capture rules directly to the database?
How do I use spooldir_2 for legal holds or VIP retention?
Is spooldir_2 an automatic overflow directory?
How do I configure on-demand audio generation with spooldir_rtp?
How can I use capture rules for PCI DSS compliance with selective DTMF?
How do I inspect which rules have DTMF enabled (crules_print, database query)?
Is capture rule modification tracked in the Audit Log?
How do I enable selective OPTIONS recording for specific IPs?
How do I reload rules on a remote sensor behind NAT?
What is the filter directive alternative for complex IP pair filtering?