(Add crules_print command to verify active capture rules loaded by sensor)
(8 intermediate revisions by the same user not shown)
Line 2:
Line 2:
__TOC__
__TOC__
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.
Capture rules enable selective recording of calls based on IP addresses or phone numbers. By default, RTP packets may not be fully saved, but rules can enable full RTP recording, call graphs, or SIP signaling capture for specific calls. Rules can also trigger external shell scripts.
== How Capture Rules Work ==
== 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.
The sniffer loads capture rules on startup and supports hot-reloading without service restart. Changes in the GUI are '''not''' automatically applied - click the green '''reload sniffer''' button to apply them.
<kroki lang="plantuml">
<kroki lang="plantuml">
Line 20:
Line 20:
rectangle "Sensor\n(Manager API\nport 5029)" as sensor
rectangle "Sensor\n(Manager API\nport 5029)" as sensor
database "MySQL\nfilter_ip\nfilter_telnum" as db
database "MySQL\nfilter_ip\nfilter_telnum" as db
file "voipmonitor.conf" as config
gui -down-> db : 1. Save rules
gui -down-> db : 1. Save rules
gui -right-> sensor : 2. Send reload
gui -right-> sensor : 2. Send reload
sensor -down-> db : 3. Re-read rules
sensor -down-> db : 3. Re-read rules
sensor -left-> config : 3. Re-read config
sensor -up-> gui : 4. Success/error
sensor -up-> gui : 4. Success/error
Line 35:
Line 33:
</kroki>
</kroki>
== Capture Rule Limitations ==
== Limitations ==
Understanding what capture rules do NOT support is important for planning your recording strategy:
{{Warning|1=Understand what capture rules do NOT support before planning your recording strategy.}}
{| class="wikitable"
{| class="wikitable"
Line 43:
Line 41:
! Requirement !! Supported !! Solution
! Requirement !! Supported !! Solution
|-
|-
| '''SIP header-based filtering''' || '''NO''' || Capture rules cannot match based on SIP headers like <code>X-Custom-Header</code>. VoIPmonitor does not support capture rules that trigger based on the presence or value of SIP headers.
| '''SIP header-based filtering''' || '''NO''' || Use <code>filter</code> directive in <code>voipmonitor.conf</code> with BPF syntax
|-
|-
| '''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.
| '''Source AND Destination combinations''' || '''NO''' || IP rules use OR logic only. Use <code>filter</code> directive for AND logic
|-
|-
| '''IP direction matching only''' || '''YES''' || You can specify rules for source IP, destination IP, or both directions.
| '''IP direction matching''' || '''YES''' || Rules support source, destination, or both directions
|-
|-
| '''Phone number direction matching only''' || '''YES''' || You can specify rules for caller number, called number, or both directions.
| '''Phone number direction''' || '''YES''' || Rules support caller, called, or both directions
|}
|}
For scenarios requiring SIP header filtering or complex IP pair combinations, use the <code>filter</code> directive in <code>/etc/voipmonitor.conf</code> with Berkeley Packet Filter (BPF) syntax instead. See [[#Alternatives_to_Capture_Rules|Alternatives to Capture Rules]] below for details.
== Rule Options ==
== Rule Options ==
Capture rules support the following configuration options:
=== 3-State Options ===
=== 3-State Options ===
Some options use a 3-state selector:
{| class="wikitable"
{| class="wikitable"
Line 66:
Line 58:
! State !! Description !! Use Case
! State !! Description !! Use Case
|-
|-
| '''GLOBAL''' || Inherits from global sniffer configuration || Enable SIP REGISTER for specific IPs without overriding RTP settings
| '''GLOBAL''' || Inherits from global sniffer config || Enable SIP REGISTER for specific IPs without overriding RTP settings
|-
|-
| '''ON''' || Explicitly enables the option || Force RTP recording for matched calls
| '''ON''' || Explicitly enables the option || Force recording for matched calls
|-
|-
| '''OFF''' || Explicitly disables the option || Disable recording for matched calls
| '''OFF''' || Explicitly disables the option || Disable recording for matched calls
|}
|}
=== Special Options ===
=== RTP Options (4 States) ===
{| class="wikitable"
{| class="wikitable"
|-
|-
! Option !! Description
! State !! Description
|-
| '''GLOBAL''' || Inherits from <code>savertp</code> in <code>voipmonitor.conf</code>
|-
| '''ON''' || Save full RTP audio payload
|-
|-
| '''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 <code>filter</code> directive in <code>voipmonitor.conf</code> instead.
| '''OFF''' || Discard RTP entirely
|-
|-
| '''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.
| '''HEADER''' || Save only RTP headers - captures quality metrics (MOS, jitter) without audio (up to 90% storage reduction)
|}
|}
=== PCI DSS Compliance Use Case: Selective DTMF Recording ===
'''Example:''' Set global default to headers, then record full audio for specific IPs:
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:'''
<syntaxhighlight lang="ini">
<syntaxhighlight lang="ini">
dtmf2db = no
# voipmonitor.conf
savertp = header
</syntaxhighlight>
</syntaxhighlight>
'''2. Create a capture rule exception for specific traffic:**
Then create a GUI capture rule for needed IP(s) with RTP option set to '''ON'''.
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.
=== Special Options ===
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 [[Settings|User Management]])
=== Compliance and Auditability Limitations ===
Capture rules have specific limitations for compliance scenarios requiring strict audit trails:
{| class="wikitable"
{| class="wikitable"
|-
|-
! Requirement !! Status !! Notes
! Option !! Description
|-
| 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|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 [[Settings|User Management]])
* For compliance scenarios requiring detailed audit trails, implement external tracking via database triggers or scripting based on the <code>filter_ip</code> and <code>filter_telnum</code> 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:
{| class="wikitable"
|-
|-
! Method !! Description !! Example
| '''Skip''' || Ignores matched calls entirely - no CDR, no files, no analysis. '''Only works if IP/number appears in SIP signalling''' (not RTP-only traffic). For RTP-only exclusion, use the <code>filter</code> directive.
|-
|-
| '''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.
| '''Auto remove at''' || Deletes the rule on specified date. '''Note:''' Permanently deletes the rule (not deactivates), and deletion is NOT logged in Audit Log.
|-
| '''Database Query''' | Query the <code>filter_ip</code> and <code>filter_telnum</code> tables directly to list all rules where DTMF recording is enabled. | <code>SELECT ip,INET_NTOA(ip) as ip_addr,direction FROM voipmonitor.filter_ip WHERE dtmf=1;</code> (for IP-based rules)
|-
| '''Manager API''' | Connect to the sniffer's manager API port (default 5029) and use the <code>crules_print</code> command to display all active capture rules with their flags. | <code>echo 'crules_print' | nc SENSOR_IP 5029</code>
|}
|}
'''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 <code>filter_ip</code> and <code>filter_telnum</code> tables over time.
=== Script Integration ===
=== Script Integration ===
Rules can trigger external shell scripts when calls match. Configure this via the <code>filtercommand</code> option in <code>voipmonitor.conf</code>. See [[Sniffer_configuration#filtercommand]] for details.
Rules can trigger external shell scripts via <code>filtercommand</code> option. See [[Sniffer_configuration#filtercommand|Sniffer Configuration]].
=== Store pcaps to second spooldir ===
Capture rules can route PCAP files for specific traffic to a secondary storage directory (<code>spooldir_2</code>) with separate retention policies.
== Storage Options ==
'''Use Cases:'''
=== Secondary Spooldir (spooldir_2) ===
* '''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).
Route PCAP files for specific traffic to a secondary storage with separate retention policies.
* '''VIP customers:''' Apply different retention policies for high-value client traffic.
* '''Regulatory requirements:** Store traffic from specific jurisdictions with mandatory long-term retention.
'''1. Configure spooldir_2 in voipmonitor.conf:'''
<syntaxhighlight lang="ini">
<syntaxhighlight lang="ini">
# Define secondary spooldir location
# voipmonitor.conf
spooldir_2 = /var/spool/voipmonitor2
spooldir_2 = /var/spool/voipmonitor2
# Set separate retention for spooldir_2 (optional)
maxpoolsize_2 = 1000G
maxpoolsize_2 = 1000G
maxpooldays_2 = 365
maxpooldays_2 = 365
</syntaxhighlight>
</syntaxhighlight>
If <code>maxpoolsize_2</code> and <code>maxpooldays_2</code> are not set, the spooldir_2 will use the same auto-cleaning rules as the primary spooldir.
Then create a capture rule and enable '''Store pcaps to second spooldir'''.
'''2. Create a capture rule:'''
{{Note|1=<code>spooldir_2</code> is NOT automatic overflow. When primary fills up, cleanspool deletes oldest files - it does NOT write to spooldir_2.}}
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.
=== On-Demand Audio (spooldir_rtp) ===
'''3. Click "Apply" and "reload sniffer" to activate the rule.'''
Store RTP packets separately for on-demand GUI audio playback:
'''Important Notes:'''
<syntaxhighlight lang="ini">
# voipmonitor.conf
* <code>spooldir_2</code> is '''NOT''' an automatic overflow directory. When the primary <code>spooldir</code> becomes full, the <code>cleanspool</code> process deletes the oldest files from the primary directory - it does NOT automatically write to <code>spooldir_2</code>.
spooldir_rtp = /path/to/fast/storage
* Only the PCAP files from calls matching the capture rule are stored in <code>spooldir_2</code>. All other traffic continues to write to the primary <code>spooldir</code>.
</syntaxhighlight>
* You can apply different auto-cleaning rules to <code>spooldir_2</code> (e.g., <code>maxpoolsize_2</code>, <code>maxpooldays_2</code>) to independently manage retention for special traffic.
For more details on <code>spooldir_2</code> configuration, see [[Sniffer_configuration#Storage_.26_File_Management_.28Spooldir.29|Storage & File Management]] in the sniffer configuration reference.
Create a capture rule with RTP option set to '''ON''' to save to this location.
== GUI Usage ==
== GUI Usage ==
Access capture rules via the GUI control panel:
# Navigate to '''Control Panel''' (Dashboard)
# Navigate to '''Control Panel''' (Dashboard)
# Click on '''Capture Rules''' section
# Click '''Capture Rules''' section
# Create rules using '''IP''' or '''TEL number''' filters
# Create rules using '''IP''' or '''TEL number''' filters
# Click the green '''reload sniffer''' button to apply changes
# Click green '''reload sniffer''' button to apply
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.
Save SIP OPTIONS packets for specific IPs only:
To enable selective OPTIONS recording:
# In '''voipmonitor.conf''', set the global setting to prevent saving for all IPs:
<syntaxhighlight lang="ini">
<syntaxhighlight lang="ini">
# voipmonitor.conf - disable global OPTIONS saving
save-sip-options = no
save-sip-options = no
</syntaxhighlight>
</syntaxhighlight>
# In the GUI Capture Rules interface, create an IP-based rule for the specific endpoint
Then create an IP-based capture rule with '''Record OPTIONS''' enabled. See [[SIP_OPTIONS/SUBSCRIBE/NOTIFY]] for details.
# 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."
== Use Cases ==
=== PCI DSS: Selective DTMF Recording ===
Disable DTMF globally but enable for troubleshooting specific traffic:
<syntaxhighlight lang="ini">
# voipmonitor.conf
dtmf2db = no
</syntaxhighlight>
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).
Create a capture rule for specific IP/number with '''record DTMF''' set to '''ON'''.
For more information on SIP OPTIONS configuration and storage settings, see [[SIP_OPTIONS/SUBSCRIBE/NOTIFY]].
{{Tip|1=Use '''Auto remove at''' to limit rule lifetime. Keep scope narrow (specific IP/number) to minimize data retention.}}
<br clear="all"/>
=== Compliance Audit Limitations ===
== Advanced: Managing Rules via Database ==
{| class="wikitable"
|-
! Requirement !! Status !! Notes
|-
| Automatic rule expiration || Supported || '''Auto remove at''' option; also '''autoexpire timeout''' in user settings
|-
| Track who modified rules || Partial || Audit Log shows timestamp/IP only, NOT user or specific changes
|-
| Temporary deactivation || NOT Supported || Rules can only be active or deleted
|-
| Log auto-removal || NOT Supported || Expiration deletions not logged
|}
For automation, bulk operations, or scripted deployments, you can manipulate capture rules directly in the MySQL database. This method is ideal for:
'''Inspection methods for DTMF-enabled rules:'''
* '''Database:''' <code>SELECT ip, INET_NTOA(ip), direction FROM filter_ip WHERE dtmf=1;</code>
| <code>rtp</code> || TINYINT || 1=SAVE, 2=DISCARD, 3=header only
|}
|}
'''Example 1:''' Match any direction - force RTP saving when caller or called number starts with <code>12345</code>:
<syntaxhighlight lang="sql">
INSERT INTO voipmonitor.filter_telnum
(prefix, fixed_len, direction, rtp)
VALUES
('12345', 0, 0, 1);
</syntaxhighlight>
'''Example 2:''' Match only destination - force RTP saving only when the '''called''' number starts with <code>98765</code>:
<syntaxhighlight lang="sql">
<syntaxhighlight lang="sql">
INSERT INTO voipmonitor.filter_telnum
-- Force RTP when called number starts with 98765
(prefix, fixed_len, direction, rtp)
INSERT INTO voipmonitor.filter_telnum (prefix, fixed_len, direction, rtp)
VALUES
VALUES ('98765', 0, 2, 1);
('98765', 0, 2, 1);
</syntaxhighlight>
</syntaxhighlight>
== Reloading Rules ==
== 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.
Rules do NOT take effect until reloaded.
=== Method 1: GUI Reload Button (Recommended) ===
# Log in to the VoIPmonitor GUI
=== Method 1: GUI (Recommended) ===
# Navigate to '''Control Panel''' (Dashboard)
# Click the green '''reload sniffer''' button
# Check for error messages if reload fails
=== Method 2: Manager API (CLI) ===
Click green '''reload sniffer''' button in Control Panel.
For directly accessible sensors, send a reload command to the Manager API port (default 5029):
=== Method 2: Manager API ===
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Replace SENSOR_IP with your sensor's IP address
echo 'reload' | nc SENSOR_IP 5029
echo 'reload' | nc SENSOR_IP 5029
</syntaxhighlight>
</syntaxhighlight>
Use this method for automation or when GUI access is not available.
=== Method 3: Server API (Client/Server Mode) ===
=== Method 3: Server API (Client/Server Mode) ===
If sensors are in [[Sniffer_distributed_architecture|client/server mode]] and Manager API ports are not directly accessible, send commands via the central server.
For sensors behind NAT using [[Sniffer_distributed_architecture|distributed architecture]]:
<kroki lang="plantuml">
@startuml
skinparam shadowing false
skinparam defaultFontName Arial
skinparam sequenceMessageAlign center
skinparam responseMessageBelowArrow true
participant "Admin\n(CLI)" as admin
box "Central Server" #f5f5f5
participant "Manager API\nport 5029" as mgr
participant "Server API\nport 60024" as sapi
end box
participant "Remote Sensor\n(behind NAT)" as sensor
The central server forwards the command to the specified remote sensor over its secure channel.
== Troubleshooting ==
== Troubleshooting ==
=== Audio Recording Despite savertp=header ===
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.
'''Cause:''' Capture rules with RTP=ON override global settings.
=== Step 1: Test Manager API Connectivity ===
'''Solution:'''
# Check GUI > Control Panel > Capture Rules for rules with '''recordRTP = ON'''
# Set to '''OFF''' or '''GLOBAL''' to inherit from config
# Click '''reload sniffer'''
Before attempting a reload, verify that the GUI can reach the sensor's Manager API port.
=== Rules Not Applied ===
'''Step 1: Test connectivity'''
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Replace SENSOR_IP with your sensor's actual IP address
echo 'getversion' | nc SENSOR_IP 5029
echo 'getversion' | nc SENSOR_IP 5029
</syntaxhighlight>
</syntaxhighlight>
Line 398:
Line 293:
{| class="wikitable"
{| class="wikitable"
|-
|-
! Result !! Meaning !! Action
! Result !! Action
|-
|-
| Version string (e.g., <code>voipmonitor 8.0.0-SVN.10</code>) || Connectivity OK || Proceed to reload
| Version string || Proceed with reload
|-
|-
| No output / connection times out || Network problem || Check firewall and routing
| Timeout || Check firewall for port 5029/TCP
|-
|-
| Connection refused || Manager API not running || Check sensor service status
| Connection refused || Check sensor service: <code>systemctl status voipmonitor</code>
|}
|}
==== Common Connectivity Issues ====
'''Step 2: Workaround if reload fails'''
{| class="wikitable"
|-
! 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)
Look for messages like <code>Rules reloaded</code> or <code>capture rules re-read</code>.
{{Note|1=The <code>crules_print</code> command prints capture rules as loaded by the sensor. Rules update automatically 1 minute after the last change or via the '''reload sniffer''' button, but the listing may only update after the first SIP packet arrives.}}
'''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
<syntaxhighlight lang="bash">
# Alternative: direct Manager API command (requires encrypted connection disabled OR Unix socket)
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.
=== Filter Directive (BPF) ===
=== Using the <code>filter</code> 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 <code>filter</code> directive in the sensor's configuration file (<code>/etc/voipmonitor.conf</code>).
'''When to use <code>filter</code> 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:'''
Use <code>filter</code> in <code>voipmonitor.conf</code> when:
* IP only appears in RTP packets (not SIP signalling)
* You need IP pair combinations with AND logic
* Skip option affects unintended calls
<syntaxhighlight lang="ini">
<syntaxhighlight lang="ini">
# Exclude all packets from a specific IP address (recommended for single IPs)
# Exclude specific IP
filter = not host 187.60.50.46
filter = not host 187.60.50.46
# Exclude multiple specific IPs
# Exclude subnet
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
filter = not net 10.0.0.0/8
# Capture traffic only between specific IP pairs (AND logic)
# Capture only traffic between specific IP pair (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
filter = host 192.168.1.10 and host 10.0.0.5
# Capture traffic between multiple IP pairs using OR combinations
# Multiple pairs with OR
# 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)
filter = (host 192.168.1.10 and host 10.0.0.5) or (host 192.168.1.10 and host 10.0.0.6)
</syntaxhighlight>
</syntaxhighlight>
'''Important Considerations:'''
{{Warning|1=<code>filter</code> uses BPF which adds CPU load. Requires service restart. For best performance, filter at network level (router/firewall).}}
See [[Sniffer_configuration#filter|Sniffer Configuration - filter]].
== See Also ==
* [[Sniffer_configuration]] - Full configuration reference
* [[Data_Cleaning]] - Storage and retention management
* '''CPU Impact:''' The <code>filter</code> 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 <code>filter</code> require a full service restart (<code>systemctl restart voipmonitor</code>) 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 <code>filter</code> directive and its BPF syntax, see [[Sniffer_configuration#filter|= filter]] in the sniffer configuration reference.
== AI Summary for RAG ==
== 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. A critical section on '''Capture Rule Limitations''' documents what is NOT supported: SIP header-based filtering is NOT supported (capture rules cannot match based on the presence or value of SIP headers like X-Custom-Header), Source AND Destination IP combinations are NOT supported (capture rules use OR logic, e.g., listing two IPs matches traffic involving either one - you cannot create "IP1 AND IP2" rules), only simple direction matching (source/destination) is supported for IPs and phone numbers. For scenarios requiring SIP header filtering or complex IP pair combinations, use the <code>filter</code> directive in <code>/etc/voipmonitor.conf</code> with Berkeley Packet Filter (BPF) syntax instead. A critical section on Selective OPTIONS Recording documents how capture rules support selective recording of SIP OPTIONS (qualify pings), SUBSCRIBE, and NOTIFY messages for specific IP addresses. When the global setting '''save-sip-options = no''' is set, you can still enable saving OPTIONS packets for specific endpoints by creating an IP-based capture rule and enabling the '''Record OPTIONS''' option. This satisfies requirements like "save OPTIONS packets for specific IPs without saving them for all traffic." The workflow involves setting '''save-sip-options = no''' globally in voipmonitor.conf, creating a capture rule for the specific IP with Record OPTIONS enabled, and applying the rule. 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 <code>filter</code> directive in voipmonitor.conf instead). A critical section on PCI DSS Compliance Use Case: Selective DTMF Recording explains how to use capture rules with the "record DTMF" option to enable troubleshooting for specific traffic while maintaining compliance by setting dtmf2db=no globally. The workflow involves disabling DTMF globally in voipmonitor.conf, creating a capture rule for specific IP/phone/domain with record DTMF = ON, and using Auto remove at to delete the rule automatically after the troubleshooting period. A critical section on Compliance and Auditability Limitations documents what is and is NOT supported: automatic rule expiration IS supported (Auto remove at option + autoexpire timeout in user settings), but tracking which user created/modified rules is PARTIALLY supported (Audit Log shows timestamp and IP but not user or specific changes), temporary deactivation of rules is NOT supported (only deletion), and auto-removal is NOT logged to the Audit Log. A critical new section on Inspection Methods for DTMF Recording provides three workarounds to check which rules currently have DTMF enabled: 1) Audit Log for modification timestamps and IP addresses (does not show specific changes), 2) Direct database queries to filter_ip/filter_telnum tables (e.g., SELECT ... WHERE dtmf=1), and 3) Manager API crules_print command (echo 'crules_print' | nc SENSOR_IP 5029). These methods show CURRENT state only, not historical audit trails - for historical trails implement custom DB triggers or scripts. The advanced section explains how to programmatically manage rules by directly inserting into the <code>filter_ip</code> and <code>filter_telnum</code> MySQL tables, with detailed column explanations and SQL examples using <code>INET_ATON()</code> for IP conversion. Three reload methods are documented: GUI button (recommended), CLI via Manager API (<code>echo 'reload' | nc</code>), and Server API for client/server deployments using <code>list_active_clients</code> and JSON commands. The troubleshooting section explains how to diagnose connectivity issues using the <code>getversion</code> command, common problems (firewall, wrong IP, NAT), and verification steps. The "Alternatives to Capture Rules" section documents the <code>filter</code> directive in voipmonitor.conf as a solution for excluding IPs from merged CDRs, RTP-only traffic, and capturing traffic only between specific IP pairs (AND logic). Enhanced syntax examples now include <code>filter = host 192.168.1.10 and host 10.0.0.5</code> for capturing only traffic between two specific hosts, and <code>filter = (host 192.168.1.10 and host 10.0.0.5) or (host 192.168.1.10 and host 10.0.0.6)</code> for capturing traffic between multiple IP pairs. The section also covers important considerations about CPU impact and the recommendation to use router/firewall filtering for better performance. A critical new section on '''Store pcaps to second spooldir''' explains how capture rules can route PCAP files for specific traffic to a secondary storage directory (<code>spooldir_2</code>) with separate retention policies (e.g., <code>maxpoolsize_2</code>, <code>maxpooldays_2</code>). Use cases include legal holds/compliance, VIP customers, and regulatory requirements for long-term retention of specific traffic. The workflow involves configuring <code>spooldir_2</code> in voipmonitor.conf, creating a capture rule enabling the "Store pcaps to second spooldir" option, and reloading the sniffer. '''Critical note:''' <code>spooldir_2</code> is NOT an automatic overflow directory - when the primary <code>spooldir</code> becomes full, cleanspool deletes the oldest files from the primary directory rather than writing to spooldir_2.
'''Summary:''' VoIPmonitor capture rules enable selective call recording based on IP addresses or phone numbers. Key features: 3-state options (GLOBAL/ON/OFF), RTP 4-state (adds HEADER for metadata-only), Skip (ignore calls), Auto remove at (time-limited rules). '''Critical limitations:''' SIP header filtering NOT supported, IP combinations use OR logic only (no AND). For complex filtering, use <code>filter</code> directive with BPF. Storage options: <code>spooldir_2</code> for separate retention (legal holds), <code>spooldir_rtp</code> for on-demand GUI audio. Rules stored in <code>filter_ip</code>/<code>filter_telnum</code> tables. Reload via GUI button, Manager API (<code>echo 'reload' | nc IP 5029</code>), or Server API for client/server mode. '''Common issue:''' Audio recording despite <code>savertp=header</code> caused by capture rules with RTP=ON overriding global settings. Compliance: auto-expiration supported, but Audit Log shows only timestamp/IP (not user or specific changes), auto-removal not logged.
'''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, compliance, auditability, PCI DSS, audit log, user tracking, autoexpire timeout, rule deletion, rule modifications, compliance limitations, DTMF, dtmf2db, PCI DSS compliance, selective DTMF recording, record DTMF option, DTMF troubleshooting, inspection methods, crules_print, dtmf=1 query, database query, manager API audit, historical audit trail, database triggers, SIP OPTIONS, OPTIONS packets, selective OPTIONS recording, Record OPTIONS option, save-sip-options, SUBSCRIBE, NOTIFY, qualify ping, capture rule limitations, SIP header filtering not supported, IP pair combinations, AND logic, BPF filter, Berkeley Packet Filter, IP pair filtering, source and destination filtering, spooldir_2, second spooldir, store pcaps to second spooldir, legal hold, compliance, VIP customers, retention policies, maxpoolsize_2, maxpooldays_2, overflow directory, autoclean setup
* How can I use capture rules to save SIP OPTIONS packets for specific IP addresses only?
* Can I check which capture rules currently have DTMF recording enabled?
* How do I inspect capture rules using the Manager API crules_print command?
* How can I query the database to find rules with DTMF enabled?
* How do I use the Audit Log to check when a rule was modified?
* Is there an audit trail for DTMF recording enablement in capture rules?
* What inspection methods are available for checking DTMF recording flags?
* How can I use crules_print to check which rules have DTMF enabled?
* What is the Record OPTIONS option in capture rules?
* How do I enable selective OPTIONS recording for specific endpoints?
* What is spooldir_2 used for?
* How do I use spooldir_2 with capture rules?
* What is the "Store pcaps to second spooldir" option?
* Is spooldir_2 an automatic overflow directory?
* How do I configure different retention policies for specific traffic?
* Can I store VIP customer calls in a separate directory?
* How do I use spooldir_2 for legal holds or compliance?
* How do capture rules work in VoIPmonitor?
* How do capture rules work in VoIPmonitor?
* What are the 3-state options (GLOBAL/ON/OFF) for rules?
* What are the limitations of capture rules (SIP headers, IP AND logic)?
* How do I reload rules without restarting the sniffer?
* How do I reload rules without restarting the sniffer?
* Why is audio recorded despite savertp=header?
* What does the Skip option do?
* What does the Skip option do?
* Does Skip work for RTP packets that don't appear in SIP signalling?
* How do I use spooldir_2 for legal holds?
* How can I exclude traffic with IP only in RTP packets?
* How can I use capture rules for PCI DSS compliance with DTMF?
* How can I auto-delete a rule after a certain date?
* How do I inspect which rules have DTMF enabled?
* Can rules trigger external scripts?
* How do I reload rules on a remote sensor behind NAT?
* How can I add capture rules without using the GUI?
* What is the filter directive alternative for complex IP filtering?
* 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?
* Does Auto remove at deactivate or delete the rule?
* Is capture rule creation/modification tracked in the Audit Log?
* Can I track which user created or modified a specific capture rule?
* Is auto-removal of capture rules logged to the Audit Log?
* Can I temporarily deactivate a capture rule without deleting it?
* How can I implement PCI DSS 4.0 compliance with capture rules?
* What is the autoexpire timeout feature in user settings?
* How can I create an audit trail for capture rule changes?
* How can I use capture rules to enable DTMF recording for specific traffic only?
* What are the limitations of VoIPmonitor capture rules?
* Do capture rules support SIP header-based filtering?
* Can I create capture rules based on custom SIP headers?
* Do capture rules support Source AND Destination IP combinations?
* Can I capture traffic only between specific IP pairs using capture rules?
* How do I filter by both Source AND Destination IP addresses?
* What is the difference between AND and OR logic in capture rules?
* How can I capture only traffic between two specific IP addresses?
* How do I use BPF filter for IP pair combinations?
* What is the record DTMF option in capture rules?
* How do I disable DTMF storage while preserving troubleshooting capabilities?
* How can I use capture rules for PCI DSS compliance with selective DTMF recording?
* What is the best alternative to capture rules for excluding a specific IP?
* How do I exclude a single IP address from a merged CDR without affecting other call legs?
* What is the syntax for the filter directive in voipmonitor.conf?
* How does the CPU impact differ between capture rules and the filter directive?
* How can I filter traffic from a specific IP that only appears in RTP packets?
* Why is router/firewall filtering better than using the filter directive?
[[Category:GUI manual]]
[[Category:GUI manual]]
[[Category:Sniffer Configuration]]
[[Category:Sniffer Configuration]]
Latest revision as of 02:11, 10 January 2026
Capture rules enable selective recording of calls based on IP addresses or phone numbers. By default, RTP packets may not be fully saved, but rules can enable full RTP recording, call graphs, or SIP signaling capture for specific calls. Rules can also trigger external shell scripts.
How Capture Rules Work
The sniffer loads capture rules on startup and supports hot-reloading without service restart. Changes in the GUI are not automatically applied - click the green reload sniffer button to apply them.
Limitations
⚠️ Warning: Understand what capture rules do NOT support before planning your recording strategy.
Requirement
Supported
Solution
SIP header-based filtering
NO
Use filter directive in voipmonitor.conf with BPF syntax
Source AND Destination combinations
NO
IP rules use OR logic only. Use filter directive for AND logic
IP direction matching
YES
Rules support source, destination, or both directions
Phone number direction
YES
Rules support caller, called, or both directions
Rule Options
3-State Options
State
Description
Use Case
GLOBAL
Inherits from global sniffer config
Enable SIP REGISTER for specific IPs without overriding RTP settings
ON
Explicitly enables the option
Force recording for matched calls
OFF
Explicitly disables the option
Disable recording for matched calls
RTP Options (4 States)
State
Description
GLOBAL
Inherits from savertp in voipmonitor.conf
ON
Save full RTP audio payload
OFF
Discard RTP entirely
HEADER
Save only RTP headers - captures quality metrics (MOS, jitter) without audio (up to 90% storage reduction)
Example: Set global default to headers, then record full audio for specific IPs:
# voipmonitor.confsavertp=header
Then create a GUI capture rule for needed IP(s) with RTP option set to ON.
Special Options
Option
Description
Skip
Ignores matched calls entirely - no CDR, no files, no analysis. Only works if IP/number appears in SIP signalling (not RTP-only traffic). For RTP-only exclusion, use the filter directive.
Auto remove at
Deletes the rule on specified date. Note: Permanently deletes the rule (not deactivates), and deletion is NOT logged in Audit Log.
Script Integration
Rules can trigger external shell scripts via filtercommand option. See Sniffer Configuration.
Storage Options
Secondary Spooldir (spooldir_2)
Route PCAP files for specific traffic to a secondary storage with separate retention policies.
Use Cases: Legal holds, VIP customers, regulatory requirements.
# Get sensor IDecho'list_active_clients'|ncSERVER_IP5029# Output: {"count":1,"services":[{"ip":"127.0.0.1","port":54137,"sensor_id":114}]}# Send reload via Server API (port 60024)echo'{"type_connection":"gui_command","sensor_id":114,"command":"reload"}'|ncSERVER_IP60024
Troubleshooting
Audio Recording Despite savertp=header
Cause: Capture rules with RTP=ON override global settings.
Solution:
Check GUI > Control Panel > Capture Rules for rules with recordRTP = ON
Set to OFF or GLOBAL to inherit from config
Click reload sniffer
Rules Not Applied
Step 1: Test connectivity
echo'getversion'|ncSENSOR_IP5029
Result
Action
Version string
Proceed with reload
Timeout
Check firewall for port 5029/TCP
Connection refused
Check sensor service: systemctl status voipmonitor
Step 2: Workaround if reload fails
systemctlrestartvoipmonitor
Cleaning Up Old Recordings After Rule Change
New rules only affect future calls. To clean up existing recordings:
Go to Settings > Custom Autocleaning
Create rule with time filter (e.g., "older than 1 day")
# Check logs for reload confirmation
journalctl-uvoipmonitor|grep-ireload
Add send_manager_cmd crules_print command to verify active capture rules
# List active capture rules from sensor's perspective (encrypted connection)
phpphp/run.phpsend_manager_cmd-s<sensor_id>-ccrules_print
ℹ️ Note: The crules_print command prints capture rules as loaded by the sensor. Rules update automatically 1 minute after the last change or via the reload sniffer button, but the listing may only update after the first SIP packet arrives.
# Alternative: direct Manager API command (requires encrypted connection disabled OR Unix socket)echo'crules_print'|nc-U/tmp/vm_manager_socket
Alternatives to Capture Rules
Filter Directive (BPF)
Use filter in voipmonitor.conf when:
IP only appears in RTP packets (not SIP signalling)
You need IP pair combinations with AND logic
Skip option affects unintended calls
# Exclude specific IPfilter=not host 187.60.50.46# Exclude subnetfilter=not net 10.0.0.0/8# Capture only traffic between specific IP pair (AND logic)filter=host 192.168.1.10 and host 10.0.0.5# Multiple pairs with ORfilter=(host 192.168.1.10 and host 10.0.0.5) or (host 192.168.1.10 and host 10.0.0.6)
⚠️ Warning:filter uses BPF which adds CPU load. Requires service restart. For best performance, filter at network level (router/firewall).
Summary: VoIPmonitor capture rules enable selective call recording based on IP addresses or phone numbers. Key features: 3-state options (GLOBAL/ON/OFF), RTP 4-state (adds HEADER for metadata-only), Skip (ignore calls), Auto remove at (time-limited rules). Critical limitations: SIP header filtering NOT supported, IP combinations use OR logic only (no AND). For complex filtering, use filter directive with BPF. Storage options: spooldir_2 for separate retention (legal holds), spooldir_rtp for on-demand GUI audio. 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. Common issue: Audio recording despite savertp=header caused by capture rules with RTP=ON overriding global settings. Compliance: auto-expiration supported, but Audit Log shows only timestamp/IP (not user or specific changes), auto-removal not logged.
