Capture rules: Difference between revisions

From VoIPmonitor.org
(Add documentation for on-demand audio generation via GUI using spooldir_rtp and recordRTP option)
(Add crules_print command to verify active capture rules loaded by sensor)
 
(5 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 ===
Most 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
Line 74: Line 66:


=== RTP Options (4 States) ===
=== RTP Options (4 States) ===
The RTP capture option has an additional fourth state:


{| class="wikitable"
{| class="wikitable"
|-
|-
! State !! Description !! Use Case
! State !! Description
|-
|-
| '''GLOBAL''' || Inherits from <code>savertp</code> configuration from <code>voipmonitor.conf</code> || Use global setting (usually <code>savertp = yes</code> or <code>savertp = header</code>)
| '''GLOBAL''' || Inherits from <code>savertp</code> in <code>voipmonitor.conf</code>
|-
|-
| '''ON''' || Save full RTP audio payload || Override global to record complete audio for matched calls
| '''ON''' || Save full RTP audio payload
|-
|-
| '''OFF''' || Discard RTP entirely || Disable RTP recording for matched calls
| '''OFF''' || Discard RTP entirely
|-
|-
| '''HEADER''' || Save only RTP headers (no audio payload) || Capture quality metrics (MOS, jitter, packet loss) without storing audio
| '''HEADER''' || Save only RTP headers - captures quality metrics (MOS, jitter) without audio (up to 90% storage reduction)
|}
|}


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


In <code>voipmonitor.conf</code>:
<syntaxhighlight lang="ini">
<syntaxhighlight lang="ini">
# voipmonitor.conf
savertp = header
savertp = header
</syntaxhighlight>
</syntaxhighlight>


Then create a GUI capture rule for the IP(s) that need full audio, and set the RTP option to '''ON'''.
Then create a GUI capture rule for needed IP(s) with RTP option set to '''ON'''.
 
For more details on <code>savertp = header</code> configuration, see [[Data_Cleaning#Save_Only_RTP_Headers_.28Major_Space_Saver.29|Data Cleaning - Save Only RTP Headers]].


=== Special Options ===
=== Special Options ===
Line 107: 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. 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.
| '''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 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.
| '''Auto remove at''' || Deletes the rule on specified date. '''Note:''' Permanently deletes the rule (not deactivates), and deletion is NOT logged in 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:'''
<syntaxhighlight lang="ini">
dtmf2db = no
</syntaxhighlight>
'''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 [[Settings|User Management]])
=== Compliance and Auditability Limitations ===
Capture rules have specific limitations for compliance scenarios requiring strict audit trails:
{| class="wikitable"
|-
! 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|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
|-
| '''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 <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 ===
== Storage Options ==


Capture rules can route PCAP files for specific traffic to a secondary storage directory (<code>spooldir_2</code>) with separate retention policies.
=== Secondary Spooldir (spooldir_2) ===


'''Use Cases:'''
Route PCAP files for specific traffic to a secondary storage with separate retention policies.


* '''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).
'''Use Cases:''' Legal holds, VIP customers, regulatory requirements.
* '''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:'''
<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:'''
 
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:'''
 
* <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>.
* 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>.
* 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.
 
=== 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:'''
{{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.}}


* '''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 (spooldir_rtp) ===
* '''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:'''
Store RTP packets separately for on-demand GUI audio playback:


'''1. Configure spooldir_rtp in voipmonitor.conf:'''
<syntaxhighlight lang="ini">
<syntaxhighlight lang="ini">
# Set custom directory for RTP packets (for on-demand GUI playback)
# voipmonitor.conf
spooldir_rtp = /path/to/your/storage
spooldir_rtp = /path/to/fast/storage
</syntaxhighlight>
 
This directory will store RTP packets for calls matching capture rules with `recordRTP=ON` enabled.
 
'''2. Restart the voipmonitor service:'''
<syntaxhighlight lang="bash">
systemctl restart voipmonitor
</syntaxhighlight>
</syntaxhighlight>


'''3. Create a capture rule to enable RTP recording:'''
Create a capture rule with RTP option set to '''ON''' to save to this location.
 
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 [[Sniffer_configuration#Storage_.26_File_Management_.28Spooldir.29|Storage & File Management]] in the sniffer configuration reference.


== 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|500px|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|500px|Telephone number-based capture rule configuration]]


=== Saving Only RTP Headers ===
=== Selective OPTIONS Recording ===


To capture only RTP headers (without audio payload) while reducing storage overhead by up to 90%:
Save SIP OPTIONS packets for specific IPs only:


'''Option A: Apply to all calls globally using voipmonitor.conf'''
In <code>/etc/voipmonitor.conf</code>, set:
<syntaxhighlight lang="ini">
<syntaxhighlight lang="ini">
savertp = header
# voipmonitor.conf - disable global OPTIONS saving
save-sip-options = no
</syntaxhighlight>
</syntaxhighlight>


This applies to all calls captured by the sensor. Restart the sniffer to apply changes.
Then create an IP-based capture rule with '''Record OPTIONS''' enabled. See [[SIP_OPTIONS/SUBSCRIBE/NOTIFY]] for details.


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


Access capture rules via the GUI control panel:
=== PCI DSS: Selective DTMF Recording ===


# Navigate to '''Control Panel''' (Dashboard)
Disable DTMF globally but enable for troubleshooting specific traffic:
# 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:
<syntaxhighlight lang="ini">
<syntaxhighlight lang="ini">
save-sip-options = no
# voipmonitor.conf
dtmf2db = no
</syntaxhighlight>
</syntaxhighlight>


# In the GUI Capture Rules interface, create an IP-based rule for the specific endpoint
Create a capture rule for specific IP/number with '''record DTMF''' set to '''ON'''.
# 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."
{{Tip|1=Use '''Auto remove at''' to limit rule lifetime. Keep scope narrow (specific IP/number) to minimize data retention.}}


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).
=== Compliance Audit Limitations ===


For more information on SIP OPTIONS configuration and storage settings, see [[SIP_OPTIONS/SUBSCRIBE/NOTIFY]].
{| 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
|}


<br clear="all"/>
'''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>


== Advanced: Managing Rules via Database ==
== Database Management ==


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


* Automated provisioning systems
=== Tables ===
* 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 <code>voipmonitor</code> database:


{| class="wikitable"
{| class="wikitable"
Line 347: Line 199:
! Table !! Purpose
! Table !! Purpose
|-
|-
| <code>filter_ip</code> || IP address and subnet-based rules
| <code>filter_ip</code> || IP address/subnet rules
|-
|-
| <code>filter_telnum</code> || Telephone number prefix-based rules
| <code>filter_telnum</code> || Telephone number prefix rules
|}
|}


=== Adding IP-Based Rules ===
=== IP-Based Rule Example ===
 
Rules in the <code>filter_ip</code> table match source or destination IP addresses or subnets.
 
'''Key Columns:'''


{| class="wikitable"
{| class="wikitable"
Line 362: Line 210:
! Column !! Type !! Description
! Column !! Type !! Description
|-
|-
| <code>ip</code> || INT UNSIGNED || IP address converted using <code>INET_ATON()</code>
| <code>ip</code> || INT UNSIGNED || IP via <code>INET_ATON()</code>
|-
|-
| <code>mask</code> || TINYINT || Subnet mask in CIDR notation (e.g., <code>24</code> for /24)
| <code>mask</code> || TINYINT || CIDR notation (e.g., <code>24</code>)
|-
|-
| <code>direction</code> || TINYINT || <code>0</code> = both, <code>1</code> = source, <code>2</code> = destination
| <code>direction</code> || TINYINT || 0=both, 1=source, 2=destination
|-
|-
| <code>rtp</code> || TINYINT || <code>1</code> = SAVE, <code>2</code> = DISCARD, <code>3</code> = header only
| <code>rtp</code> || TINYINT || 1=SAVE, 2=DISCARD, 3=header only
|}
|}
'''Example:''' Force-save RTP for all calls from or to the <code>1.2.3.0/24</code> network:


<syntaxhighlight lang="sql">
<syntaxhighlight lang="sql">
INSERT INTO voipmonitor.filter_ip
-- Force RTP for 1.2.3.0/24 network
    (ip, mask, direction, rtp)
INSERT INTO voipmonitor.filter_ip (ip, mask, direction, rtp)
VALUES
VALUES (INET_ATON('1.2.3.0'), 24, 0, 1);
    (INET_ATON('1.2.3.0'), 24, 0, 1);
</syntaxhighlight>
</syntaxhighlight>


=== Adding Telephone Number-Based Rules ===
=== Telephone Number Rule Example ===
 
Rules in the <code>filter_telnum</code> table match caller or called number prefixes.
 
'''Key Columns:'''


{| class="wikitable"
{| class="wikitable"
Line 390: Line 231:
! Column !! Type !! Description
! Column !! Type !! Description
|-
|-
| <code>prefix</code> || VARCHAR || Telephone number prefix to match (e.g., <code>4420</code>)
| <code>prefix</code> || VARCHAR || Number prefix to match
|-
|-
| <code>fixed_len</code> || TINYINT || Fixed length matching (0 = prefix match)
| <code>fixed_len</code> || TINYINT || 0=prefix match
|-
|-
| <code>direction</code> || TINYINT || <code>0</code> = both, <code>1</code> = caller, <code>2</code> = called
| <code>direction</code> || TINYINT || 0=both, 1=caller, 2=called
|-
|-
| <code>rtp</code> || TINYINT || <code>1</code> = SAVE, <code>2</code> = DISCARD, <code>3</code> = header only
| <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) ===
=== Method 1: GUI (Recommended) ===


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


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


<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
 
== Step 1: Get sensor ID ==
admin -> mgr : list_active_clients
mgr --> admin : {"sensor_id": 114, ...}
 
== Step 2: Send reload via Server API ==
admin -> sapi : {"type_connection":"gui_command",\n"sensor_id":114, "command":"reload"}
sapi -> sensor : forward reload command
sensor --> sapi : OK
sapi --> admin : success
@enduml
</kroki>
 
'''Step 1:''' Get list of connected sensors and their IDs:


<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Get sensor ID
echo 'list_active_clients' | nc SERVER_IP 5029
echo 'list_active_clients' | nc SERVER_IP 5029
</syntaxhighlight>
# Output: {"count":1,"services":[{"ip":"127.0.0.1","port":54137,"sensor_id":114}]}


Example output:
# Send reload via Server API (port 60024)
<syntaxhighlight lang="json">
{"count":1,"services":[{"ip":"127.0.0.1","port":54137,"sensor_id":114}]}
</syntaxhighlight>
 
'''Step 2:''' Send reload command via Server API port (default 60024):
 
<syntaxhighlight lang="bash">
echo '{"type_connection":"gui_command","sensor_id":114,"command":"reload"}' | nc SERVER_IP 60024
echo '{"type_connection":"gui_command","sensor_id":114,"command":"reload"}' | nc SERVER_IP 60024
</syntaxhighlight>
</syntaxhighlight>
The central server forwards the command to the specified remote sensor over its secure channel.


== Troubleshooting ==
== Troubleshooting ==


=== Audio Recording Despite savertp=header or saveaudio=no ===
=== Audio Recording Despite savertp=header ===


If audio is being captured even though your local <code>/etc/voipmonitor.conf</code> has <code>savertp = header</code> or <code>saveaudio = no</code>, the most likely cause is that **capture rules are overriding your global settings**.
'''Cause:''' Capture rules with RTP=ON override 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 <code>savertp</code> or <code>saveaudio</code> configuration. This is by design - capture rules provide granular control to override global settings for specific IPs, phone numbers, or subnets.
'''Solution:'''
# Check GUI > Control Panel > Capture Rules for rules with '''recordRTP = ON'''
# Set to '''OFF''' or '''GLOBAL''' to inherit from config
# Click '''reload sniffer'''


'''Troubleshooting Steps:'''
=== Rules Not Applied ===
 
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 [[Sniffer_configuration#mysqlloadconfig|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.


'''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 536: 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)
|}
 
=== Step 2: Immediate Workaround - Restart Sniffer ===
 
If reload fails and connectivity cannot be resolved immediately, restart the sniffer service:
 
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# SSH to the sensor
ssh root@SENSOR_IP
# Check current status
systemctl status voipmonitor
# Restart (forces full reload of all rules)
systemctl restart voipmonitor
systemctl restart voipmonitor
</syntaxhighlight>
</syntaxhighlight>


Note: Restarting causes a brief interruption in call monitoring.
=== Cleaning Up Old Recordings After Rule Change ===


=== Verifying Rules Are Active ===
New rules only affect future calls. To clean up existing recordings:


After reloading rules, verify they are applied:
# 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


'''1. Check logs for reload confirmation:'''
See [[Data_Cleaning#Custom_Autocleaning:_One-Time_Cleanup_with_Filters|Data Cleaning - Custom Autocleaning]].
 
=== Verify Rules Are Active ===


<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>
# CentOS/RHEL/AlmaLinux
Add send_manager_cmd crules_print command to verify active capture rules
tail -f /var/log/messages | grep voipmonitor
<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>
</syntaxhighlight>


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)
echo 'crules_print' | nc -U /tmp/vm_manager_socket
</syntaxhighlight>
== Alternatives to Capture Rules ==
== 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.
=== Filter Directive (BPF) ===


=== Using the <code>filter</code> Directive in voipmonitor.conf ===
Use <code>filter</code> in <code>voipmonitor.conf</code> when:
 
* IP only appears in RTP packets (not SIP signalling)
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>).
* You need IP pair combinations with AND logic
 
* Skip option affects unintended calls
'''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:'''


<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
* [[SIP_OPTIONS/SUBSCRIBE/NOTIFY]] - OPTIONS recording details
* [[Sniffer_distributed_architecture]] - Client/server mode


* '''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 covers two critical scenarios: 1) '''Audio Recording Despite savertp=header or saveaudio=no''' - explains that capture rules with RTP option set to ON or SAVE can override global savertp/saveaudio settings. The workflow confirms audio is being saved via WAV file creation in the GUI, checks for active capture rules with recordRTP=ON in the Control Panel, disables or removes conflicting rules, reloads the sniffer, and verifies the fix with test calls. If audio recording persists after removing capture rules, check for database-based configuration overrides (see mysqlloadconfig in Sniffer_configuration). 2) '''Connectivity issues''' - 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. A critical new section on '''On-Demand Audio Generation via GUI''' explains how to configure VoIPmonitor to save RTP packets to a custom directory (spooldir_rtp) specifically for on-demand audio generation and playback through the GUI. Use cases include separate storage for audio playback (keeping RTP files on fast SSD/NVMe while other data goes to HDD), on-demand audio generation for GUI playback, and selective audio archiving. The workflow involves setting spooldir_rtp in voipmonitor.conf (e.g., spooldir_rtp = /path/to/custom/storage), restarting the voipmonitor service, creating a capture rule with the RTP option set to ON (recordRTP=ON), and reloading the sniffer. After this setup, RTP packets from calls matching the capture rule are saved to the specified spooldir_rtp directory and audio files can be generated and played back through the GUI. '''Critical note:''' 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 spooldir_rtp directory must exist and be writable by the voipmonitor user.
'''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, audio recording troubleshooting, savertp override, saveaudio override, audio despite savertp header, audio despite saveaudio no, WAV file creation, recordRTP option, capture rules override global settings, mysqlloadconfig, database configuration overrides, sensor_config table, database priority vs file config, spooldir_rtp, on-demand audio generation, GUI audio playback, RTP packet storage, custom RTP directory, RTP storage location, audio generation via GUI, selective RTP storage, RTP files directory, generate audio from RTP, play audio through GUI
'''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 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?
* Why is audio being recorded even though I set savertp=header and saveaudio=no?
* How do I use spooldir_2 for legal holds?
* Can capture rules override global savertp and saveaudio settings?
* How can I use capture rules for PCI DSS compliance with DTMF?
* How do I check if capture rules are forcing audio recording?
* How do I inspect which rules have DTMF enabled?
* What should I do if audio is being saved despite my voipmonitor.conf settings?
* How do I reload rules on a remote sensor behind NAT?
* How do I disable capture rules that are overriding my global recording settings?
* What is the filter directive alternative for complex IP filtering?
* Does Skip work for RTP packets that don't appear in SIP signalling?
* How can I exclude traffic with IP only in RTP packets?
* How can I auto-delete a rule after a certain date?
* Can rules trigger external scripts?
* How can I add capture rules without using the GUI?
* How to add IP or telephone number based filters directly to the database?
* What do the direction and rtp columns mean in the filter_ip table?
* Why are capture rules not being applied after I change them in the GUI?
* How do I test if the GUI can reach the sensor's Manager API?
* How can I reload capture rules if the sensor is behind NAT?
* How do I reload rules on a remote sensor in client/server mode?
* How do I verify that capture rules have been reloaded?
* 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?
* What is spooldir_rtp used for?
* How do I configure on-demand audio generation via GUI?
* How do I save RTP packets to a custom directory?
* What is the recordRTP option in capture rules?
* How do I use spooldir_rtp with capture rules?
* Can I generate and play audio files through the GUI?
* How do I store RTP files separately from the main spooldir?
* What is the workflow for on-demand audio generation?
* How do I save RTP packets for GUI playback?
* Does spooldir_rtp require a capture rule with RTP option set to ON?
* How do I create a capture rule for on-demand audio generation?
* What is the difference between spooldir and spooldir_rtp?
* Can I use spooldir_rtp without creating a capture rule?


[[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"