Capture rules: Difference between revisions

From VoIPmonitor.org
(Fix image display - use thumb|none to prevent floating into Troubleshooting section)
(Add crules_print command to verify active capture rules loaded by sensor)
 
(18 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 12: Line 12:
skinparam shadowing false
skinparam shadowing false
skinparam defaultFontName Arial
skinparam defaultFontName Arial
skinparam rectangle {
  BorderColor #4A90E2
  BackgroundColor #FFFFFF
}


rectangle "GUI" as gui
rectangle "GUI\n(Web Interface)" as gui
rectangle "Sensor\n(Manager API\nport 5029)" as sensor
rectangle "Sensor\n(Manager API\nport 5029)" as sensor
database "voipmonitor.conf\n& capture rules" as config
database "MySQL\nfilter_ip\nfilter_telnum" as db


gui -> sensor : reload command
gui -down-> db : 1. Save rules
sensor -> config : re-read rules
gui -right-> sensor : 2. Send reload
sensor -> gui : success/error
sensor -down-> db : 3. Re-read rules
sensor -up-> gui : 4. Success/error
 
note bottom of sensor
  Rules take effect only
  after reload command
end note
@enduml
@enduml
</kroki>
</kroki>
== Limitations ==
{{Warning|1=Understand what capture rules do NOT support before planning your recording strategy.}}
{| class="wikitable"
|-
! Requirement !! Supported !! Solution
|-
| '''SIP header-based filtering''' || '''NO''' || Use <code>filter</code> directive in <code>voipmonitor.conf</code> with BPF syntax
|-
| '''Source AND Destination combinations''' || '''NO''' || IP rules use OR logic only. Use <code>filter</code> 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 ==
== 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 35: 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
|}
|}
=== RTP Options (4 States) ===
{| class="wikitable"
|-
! State !! Description
|-
| '''GLOBAL''' || Inherits from <code>savertp</code> in <code>voipmonitor.conf</code>
|-
| '''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:
<syntaxhighlight lang="ini">
# voipmonitor.conf
savertp = header
</syntaxhighlight>
Then create a GUI capture rule for needed IP(s) with RTP option set to '''ON'''.


=== Special Options ===
=== Special Options ===
Line 48: Line 95:
! Option !! Description
! Option !! Description
|-
|-
| '''Skip''' || Ignores matched calls entirely - no files are created, no RTP analysis is performed, and no CDR is generated
| '''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.
|-
|-
| '''Auto remove at''' || Automatically deletes the rule on a specified date (useful for temporary debugging rules)
| '''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 ===
=== 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]].
 
== 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.
 
<syntaxhighlight lang="ini">
# voipmonitor.conf
spooldir_2 = /var/spool/voipmonitor2
maxpoolsize_2 = 1000G
maxpooldays_2 = 365
</syntaxhighlight>
 
Then create a capture rule and enable '''Store pcaps to second spooldir'''.
 
{{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.}}
 
=== On-Demand Audio (spooldir_rtp) ===
 
Store RTP packets separately for on-demand GUI audio playback:
 
<syntaxhighlight lang="ini">
# voipmonitor.conf
spooldir_rtp = /path/to/fast/storage
</syntaxhighlight>
 
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


[[File:capturerules-ip.png|thumb|none|400px|IP-based capture rule configuration]]
[[File:capturerules-ip.png|thumb|none|500px|IP-based capture rule configuration]]
[[File:capturerules-tel.png|thumb|none|500px|Telephone number-based capture rule configuration]]


[[File:capturerules-tel.png|thumb|none|400px|Telephone number-based capture rule configuration]]
=== Selective OPTIONS Recording ===


<br clear="all"/>
Save SIP OPTIONS packets for specific IPs only:


== Troubleshooting ==
<syntaxhighlight lang="ini">
# voipmonitor.conf - disable global OPTIONS saving
save-sip-options = no
</syntaxhighlight>
 
Then create an IP-based capture rule with '''Record OPTIONS''' enabled. See [[SIP_OPTIONS/SUBSCRIBE/NOTIFY]] for details.


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.
== Use Cases ==


=== Step 1: Test Manager API Connectivity ===
=== PCI DSS: Selective DTMF Recording ===


Before attempting a reload, verify that the GUI can reach the sensor's Manager API port (default 5029).
Disable DTMF globally but enable for troubleshooting specific traffic:


Test connectivity from the GUI server:
<syntaxhighlight lang="ini">
<syntaxhighlight lang="bash">
# voipmonitor.conf
# Replace PROBE_IP with your sensor's actual IP address
dtmf2db = no
echo 'getversion' | nc PROBE_IP 5029
</syntaxhighlight>
</syntaxhighlight>
Create a capture rule for specific IP/number with '''record DTMF''' set to '''ON'''.
{{Tip|1=Use '''Auto remove at''' to limit rule lifetime. Keep scope narrow (specific IP/number) to minimize data retention.}}
=== Compliance Audit Limitations ===


{| class="wikitable"
{| class="wikitable"
|-
|-
! Result !! Meaning !! Action
! Requirement !! Status !! Notes
|-
|-
| Version string (e.g., <code>voipmonitor 8.0.0-SVN.10</code>) || Connectivity OK || Proceed to Step 2
| Automatic rule expiration || Supported || '''Auto remove at''' option; also '''autoexpire timeout''' in user settings
|-
|-
| No output / connection times out || Network problem || Check firewall and routing
| Track who modified rules || Partial || Audit Log shows timestamp/IP only, NOT user or specific changes
|-
|-
| Connection refused || Manager API not running || Check sensor service status
| Temporary deactivation || NOT Supported || Rules can only be active or deleted
|-
| Log auto-removal || NOT Supported || Expiration deletions not logged
|}
|}


==== Common Connectivity Issues ====
'''Inspection methods for DTMF-enabled rules:'''
* '''Database:''' <code>SELECT ip, INET_NTOA(ip), direction FROM filter_ip WHERE dtmf=1;</code>
* '''Manager API:''' <code>echo 'crules_print' | nc SENSOR_IP 5029</code>


* '''Firewall blocking port 5029''' - Ensure port 5029/TCP is open on the sensor's firewall
== Database Management ==
* '''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 ===
For automation or bulk operations, manipulate rules directly in MySQL.


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


==== Method 1: Web GUI Reload Button (Recommended) ====
{| class="wikitable"
|-
! Table !! Purpose
|-
| <code>filter_ip</code> || IP address/subnet rules
|-
| <code>filter_telnum</code> || Telephone number prefix rules
|}


# Log in to the VoIPmonitor GUI
=== IP-Based Rule Example ===
# Navigate to '''Control Panel''' (Dashboard)
 
# Click the green '''reload sniffer''' button
{| class="wikitable"
# Check for error messages if reload fails
|-
! Column !! Type !! Description
|-
| <code>ip</code> || INT UNSIGNED || IP via <code>INET_ATON()</code>
|-
| <code>mask</code> || TINYINT || CIDR notation (e.g., <code>24</code>)
|-
| <code>direction</code> || TINYINT || 0=both, 1=source, 2=destination
|-
| <code>rtp</code> || TINYINT || 1=SAVE, 2=DISCARD, 3=header only
|}
 
<syntaxhighlight lang="sql">
-- Force RTP for 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);
</syntaxhighlight>
 
=== Telephone Number Rule Example ===
 
{| class="wikitable"
|-
! Column !! Type !! Description
|-
| <code>prefix</code> || VARCHAR || Number prefix to match
|-
| <code>fixed_len</code> || TINYINT || 0=prefix match
|-
| <code>direction</code> || TINYINT || 0=both, 1=caller, 2=called
|-
| <code>rtp</code> || TINYINT || 1=SAVE, 2=DISCARD, 3=header only
|}
 
<syntaxhighlight lang="sql">
-- Force RTP when called number starts with 98765
INSERT INTO voipmonitor.filter_telnum (prefix, fixed_len, direction, rtp)
VALUES ('98765', 0, 2, 1);
</syntaxhighlight>
 
== Reloading Rules ==
 
Rules do NOT take effect until reloaded.
 
=== Method 1: GUI (Recommended) ===
 
Click green '''reload sniffer''' button in Control Panel.


==== Method 2: CLI Manager API ====
=== Method 2: Manager API ===


<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
echo 'reload' | nc PROBE_IP 5029
echo 'reload' | nc SENSOR_IP 5029
</syntaxhighlight>
</syntaxhighlight>


Use this method if you cannot access the GUI or need automation.
=== Method 3: Server API (Client/Server Mode) ===


==== Method 3: Server API (for Client/Server Mode) ====
For sensors behind NAT using [[Sniffer_distributed_architecture|distributed architecture]]:
 
If sensors are in client/server mode and manager ports aren't directly accessible:


<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Step 1: List connected sensors and get sensor_id
# Get sensor ID
echo 'list_active_clients' | nc SERVER_IP 5029
echo 'list_active_clients' | nc SERVER_IP 5029
# 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)
# Send reload via Server API (port 60024)
echo '{"type_connection":"gui_command","sensor_id":SENSOR_ID,"command":"reload"}' | nc SERVER_IP 60024
echo '{"type_connection":"gui_command","sensor_id":114,"command":"reload"}' | nc SERVER_IP 60024
</syntaxhighlight>
</syntaxhighlight>


Replace <code>SENSOR_ID</code> with the ID from Step 1 and <code>SERVER_IP</code> with the central server's IP.
== Troubleshooting ==


=== Step 3: Immediate Workaround - Restart Sniffer ===
=== Audio Recording Despite savertp=header ===


If the reload fails and you cannot resolve the connectivity issue immediately, restart the sniffer service on the sensor:
'''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'''
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# SSH to the sensor
echo 'getversion' | nc SENSOR_IP 5029
ssh root@SENSOR_IP
</syntaxhighlight>


# Check current status
{| class="wikitable"
systemctl status voipmonitor
|-
! Result !! Action
|-
| Version string || Proceed with reload
|-
| Timeout || Check firewall for port 5029/TCP
|-
| Connection refused || Check sensor service: <code>systemctl status voipmonitor</code>
|}


# Restart the service (this forces a full reload of all rules)
'''Step 2: Workaround if reload fails'''
<syntaxhighlight lang="bash">
systemctl restart voipmonitor
systemctl restart voipmonitor
</syntaxhighlight>
</syntaxhighlight>


=== Verifying Rules Are Active ===
=== 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")
# Set '''Common Filter''' matching same IP/phone number
# Run once, then remove the autocleaning rule
 
See [[Data_Cleaning#Custom_Autocleaning:_One-Time_Cleanup_with_Filters|Data Cleaning - Custom Autocleaning]].


After reloading rules, verify they are active:
=== Verify Rules Are Active ===


'''1. Check logs for reload confirmation:'''
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Debian/Ubuntu
# Check logs for reload confirmation
tail -f /var/log/syslog | grep voipmonitor
journalctl -u voipmonitor | grep -i reload
</syntaxhighlight>
Add send_manager_cmd crules_print command to verify active capture rules
<syntaxhighlight lang="bash">
# List active capture rules from sensor's perspective (encrypted connection)
php php/run.php send_manager_cmd -s &lt;sensor_id&gt; -c crules_print
</syntaxhighlight>


# CentOS/RHEL/AlmaLinux
{{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.}}
tail -f /var/log/messages | grep voipmonitor
 
<syntaxhighlight lang="bash">
# Alternative: direct Manager API command (requires encrypted connection disabled OR Unix socket)
echo 'crules_print' | nc -U /tmp/vm_manager_socket
</syntaxhighlight>
</syntaxhighlight>
== Alternatives to Capture Rules ==
=== Filter Directive (BPF) ===
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">
# Exclude specific IP
filter = not host 187.60.50.46
# Exclude subnet
filter = 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 OR
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>
{{Warning|1=<code>filter</code> uses BPF which adds CPU load. Requires service restart. For best performance, filter at network level (router/firewall).}}


Look for messages like <code>Rules reloaded</code> or <code>capture rules re-read</code>.
See [[Sniffer_configuration#filter|Sniffer Configuration - filter]].


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


'''3. Monitor CDR view''' to confirm captured/skipped calls match your rule configuration.
* [[Sniffer_configuration]] - Full configuration reference
* [[Data_Cleaning]] - Storage and retention management
* [[SIP_OPTIONS/SUBSCRIBE/NOTIFY]] - OPTIONS recording details
* [[Sniffer_distributed_architecture]] - Client/server mode


=== 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 ==
== 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 <code>getversion</code> command, three reload methods (GUI button, CLI, Server API), and verification steps.
'''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, sniffer reload, GLOBAL option, skip calls, auto-remove, filtercommand, manager api, getversion, port 5029, troubleshooting, reload not working
'''Keywords:''' capture rules, selective recording, RTP packets, filter_ip, filter_telnum, INET_ATON, sniffer reload, skip calls, auto-remove, manager api, port 5029, filter directive, BPF, PCI DSS, DTMF, dtmf2db, crules_print, SIP OPTIONS, spooldir_2, legal hold, savertp override, spooldir_rtp


'''Key Questions:'''
'''Key Questions:'''
* 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?
* How can I auto-delete a rule after a certain date?
* How do I use spooldir_2 for legal holds?
* Can rules trigger external scripts?
* How can I use capture rules for PCI DSS compliance with DTMF?
* Why are capture rules not being applied after I change them in the GUI?
* How do I inspect which rules have DTMF enabled?
* How do I test if the GUI can reach the sensor's Manager API?
* How do I reload rules on a remote sensor behind NAT?
* How can I reload capture rules if the sensor is behind NAT?
* What is the filter directive alternative for complex IP filtering?
* How do I verify that capture rules have been reloaded?


[[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.conf
savertp = 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. 

# voipmonitor.conf
spooldir_2 = /var/spool/voipmonitor2
maxpoolsize_2 = 1000G
maxpooldays_2 = 365

Then create a capture rule and enable Store pcaps to second spooldir.

ℹ️ Note: spooldir_2 is NOT automatic overflow. When primary fills up, cleanspool deletes oldest files - it does NOT write to spooldir_2.

On-Demand Audio (spooldir_rtp)

Store RTP packets separately for on-demand GUI audio playback: 

# voipmonitor.conf
spooldir_rtp = /path/to/fast/storage

Create a capture rule with RTP option set to ON to save to this location.

GUI Usage

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

Selective OPTIONS Recording

Save SIP OPTIONS packets for specific IPs only: 

# voipmonitor.conf - disable global OPTIONS saving
save-sip-options = no

Then create an IP-based capture rule with Record OPTIONS enabled. See SIP_OPTIONS/SUBSCRIBE/NOTIFY for details.

Use Cases

PCI DSS: Selective DTMF Recording

Disable DTMF globally but enable for troubleshooting specific traffic: 

# voipmonitor.conf
dtmf2db = no

Create a capture rule for specific IP/number with record DTMF set to ON.

💡 Tip: Use Auto remove at to limit rule lifetime. Keep scope narrow (specific IP/number) to minimize data retention.

Compliance Audit Limitations

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

Inspection methods for DTMF-enabled rules:

  • Database: SELECT ip, INET_NTOA(ip), direction FROM filter_ip WHERE dtmf=1;
  • Manager API: echo 'crules_print' | nc SENSOR_IP 5029

Database Management

For automation or bulk operations, manipulate rules directly in MySQL.

Tables

Table Purpose
filter_ip IP address/subnet rules
filter_telnum Telephone number prefix rules

IP-Based Rule Example

Column Type Description
ip INT UNSIGNED IP via INET_ATON()
mask TINYINT CIDR notation (e.g., 24)
direction TINYINT 0=both, 1=source, 2=destination
rtp TINYINT 1=SAVE, 2=DISCARD, 3=header only 
-- Force RTP for 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);

Telephone Number Rule Example

Column Type Description
prefix VARCHAR Number prefix to match
fixed_len TINYINT 0=prefix match
direction TINYINT 0=both, 1=caller, 2=called
rtp TINYINT 1=SAVE, 2=DISCARD, 3=header only 
-- Force RTP when called number starts with 98765
INSERT INTO voipmonitor.filter_telnum (prefix, fixed_len, direction, rtp)
VALUES ('98765', 0, 2, 1);

Reloading Rules

Rules do NOT take effect until reloaded.

Method 1: GUI (Recommended)

Click green reload sniffer button in Control Panel.

Method 2: Manager API

echo 'reload' | nc SENSOR_IP 5029

Method 3: Server API (Client/Server Mode)

For sensors behind NAT using distributed architecture: 

# Get sensor ID
echo 'list_active_clients' | nc SERVER_IP 5029
# 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"}' | nc SERVER_IP 60024

Troubleshooting

Audio Recording Despite savertp=header

Cause: Capture rules with RTP=ON override global settings.

Solution:

  1. Check GUI > Control Panel > Capture Rules for rules with recordRTP = ON
  2. Set to OFF or GLOBAL to inherit from config
  3. Click reload sniffer

Rules Not Applied

Step 1: Test connectivity 

echo 'getversion' | nc SENSOR_IP 5029
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 

systemctl restart voipmonitor

Cleaning Up Old Recordings After Rule Change

New rules only affect future calls. To clean up existing recordings:

  1. Go to Settings > Custom Autocleaning
  2. Create rule with time filter (e.g., "older than 1 day")
  3. Set Common Filter matching same IP/phone number
  4. Run once, then remove the autocleaning rule

See Data Cleaning - Custom Autocleaning.

Verify Rules Are Active

# Check logs for reload confirmation
journalctl -u voipmonitor | grep -i reload

Add send_manager_cmd crules_print command to verify active capture rules 

# List active capture rules from sensor's perspective (encrypted connection)
php php/run.php send_manager_cmd -s &lt;sensor_id&gt; -c crules_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 IP
filter = not host 187.60.50.46

# Exclude subnet
filter = 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 OR
filter = (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).

See Sniffer Configuration - filter.

See Also


AI Summary for RAG

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.

Keywords: capture rules, selective recording, RTP packets, filter_ip, filter_telnum, INET_ATON, sniffer reload, skip calls, auto-remove, manager api, port 5029, filter directive, BPF, PCI DSS, DTMF, dtmf2db, crules_print, SIP OPTIONS, spooldir_2, legal hold, savertp override, spooldir_rtp

Key Questions:

  • How do capture rules work in VoIPmonitor?
  • 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?
  • What does the Skip option do?
  • How do I use spooldir_2 for legal holds?
  • How can I use capture rules for PCI DSS compliance with DTMF?
  • How do I inspect which rules have DTMF enabled?
  • How do I reload rules on a remote sensor behind NAT?
  • What is the filter directive alternative for complex IP filtering?
Retrieved from "https://www.voipmonitor.org/doc/index.php?title=Capture_rules&oldid=10543"