Capture rules: Difference between revisions

From VoIPmonitor.org
(Add section about cleaning up existing recordings after capture rule changes)
(Rewrite: konsolidace a vylepšení struktury - removed redundancy, better organization, more compact)
 
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 <code>recordRTP=ON</code> 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 <code>recordRTP=ON</code> 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 <code>spooldir_rtp</code> 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 <code>spooldir</code>
 
'''Important Notes:'''
 
* <code>spooldir_rtp</code> only affects calls captured by rules with the RTP option set to ON. Without an active capture rule with <code>recordRTP=ON</code>, RTP packets will not be saved to this directory.
* The directory specified in <code>spooldir_rtp</code> must exist and be writable by the <code>voipmonitor</code> user before starting the service.
* This configuration is separate from the main <code>spooldir</code> and <code>spooldir_2</code> - it exists specifically for RTP packet storage.
 
For more details on <code>spooldir_rtp</code> 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 ==


=== Cleaning Up Existing Recordings After Changing Capture Rules ===
=== Audio Recording Despite savertp=header ===
 
When you add or modify capture rules to stop recording specific traffic (for example, setting RTP to OFF for a specific IP address), the new rule only affects '''future calls'''. Existing recordings for that traffic will remain on disk.
 
To clean up old recordings that match the same criteria (IP address, phone number, etc.), use the '''Custom Autocleaning''' feature in the GUI:
 
1. Navigate to '''Settings > Custom Autocleaning'''
2. Create a new autocleaning rule:
  * Set criteria to delete RTP/SIP files older than X days (e.g., "older than 1 day")
  * In the '''Common Filter''' section, specify the same IP address or phone number as your capture rule
3. Save and run the rule
4. Once cleanup is complete, you can remove the autocleaning rule
 
This performs a one-time cleanup of existing files matching your criteria. After the capture rule is in place, new calls will not be recorded, so the autocleaning rule is only needed once.
 
For more details on custom autocleaning, see [[Data_Cleaning#Custom_Autocleaning:_One-Time_Cleanup_with_Filters|Data Cleaning - Custom Autocleaning]].
 
=== Audio Recording Despite savertp=header or saveaudio=no ===
 
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**.
 
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.
 
'''Troubleshooting Steps:'''
 
1. '''Confirm audio is actually being saved:'''
  * Open the VoIPmonitor GUI
  * Navigate to the CDR table and find a recently captured call
  * Click on the call and attempt to create a WAV file
  * If audio is successfully extracted, the issue is confirmed
 
2. '''Check for active capture rules:'''
  * Navigate to '''GUI > Control Panel > Capture Rules'''
  * Look for any rules with the '''recordRTP''' option set to '''ON''' or '''SAVE'''
  * Even a single active rule with recordRTP enabled can trigger audio recording
 
3. '''Disable or remove the conflicting rules:'''
  * Either delete the rules entirely, or
  * Set the '''recordRTP''' option to '''OFF''' or '''GLOBAL''' to inherit from your local configuration
  * Click the green '''reload sniffer''' button to apply changes
  * Alternatively, wait up to one minute for automatic application


4. '''Verify the fix:'''
'''Cause:''' Capture rules with RTP=ON override global settings.
  * 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).
'''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 ===
 
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 553: 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
 
# CentOS/RHEL/AlmaLinux
tail -f /var/log/messages | grep voipmonitor
</syntaxhighlight>
</syntaxhighlight>
Look for messages like <code>Rules reloaded</code> or <code>capture rules re-read</code>.
'''2. Make a test call''' that should trigger your new rule and verify the recording behavior matches expectations.
'''3. Monitor CDR view''' to confirm captured/skipped calls match your rule configuration.
=== Preventing Future Issues ===
* Ensure '''stable network connectivity''' between GUI and sensors
* '''Use monitoring tools''' to detect connectivity issues early
* Consider '''client/server mode''' for sensors in different networks - uses persistent connections that are more reliable than direct Manager API access


== Alternatives to Capture Rules ==
== 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]].


* '''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.
== See Also ==
* '''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.
* [[Sniffer_configuration]] - Full configuration reference
* [[Data_Cleaning]] - Storage and retention management
* [[SIP_OPTIONS/SUBSCRIBE/NOTIFY]] - OPTIONS recording details
* [[Sniffer_distributed_architecture]] - Client/server mode


== AI Summary for RAG ==
== AI Summary for RAG ==


'''Summary:''' VoIPmonitor capture rules enable selective call recording based on IP addresses or phone numbers. Key features include 3-state options (GLOBAL/ON/OFF), RTP 4-state (adds HEADER for metadata-only), Skip (ignore calls entirely), and Auto remove at (time-limited rules). '''Critical limitations:''' SIP header-based filtering NOT supported, IP combinations use OR logic only (no AND). For complex filtering, use the <code>filter</code> directive with BPF syntax. Selective OPTIONS recording allows saving SIP OPTIONS for specific IPs when <code>save-sip-options = no</code> globally. PCI DSS compliance: set <code>dtmf2db = no</code> globally, enable DTMF per-rule for troubleshooting. Compliance limitations: auto-expiration supported, but user tracking partial (Audit Log shows IP/timestamp only), no temporary deactivation, auto-removal not logged. Inspection methods: <code>crules_print</code> via Manager API, database queries (<code>WHERE dtmf=1</code>). 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. '''Troubleshooting:''' Audio recording despite <code>savertp=header</code> usually caused by capture rules with RTP=ON overriding global settings. '''Cleaning up existing recordings:''' When modifying capture rules to stop recording (e.g., setting RTP=OFF for a specific IP), the rule only affects future calls. To clean up old recordings, use Custom Autocleaning (Settings > Custom Autocleaning) with a time filter (e.g., "older than 1 day") and Common Filter matching the same IP/phone number. This performs one-time cleanup; the autocleaning rule can be removed afterward. Storage options: <code>spooldir_2</code> for separate retention (legal holds, VIP), <code>spooldir_rtp</code> for on-demand GUI audio generation - both require active capture rules.
'''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, filter_ip, filter_telnum, INET_ATON, sniffer reload, GLOBAL option, skip calls, auto-remove, filtercommand, manager api, port 5029, client server mode, filter directive, BPF, PCI DSS, DTMF, dtmf2db, crules_print, SIP OPTIONS, Record OPTIONS, save-sip-options, capture rule limitations, SIP header filtering not supported, IP pair combinations, AND logic, spooldir_2, legal hold, retention policies, maxpoolsize_2, savertp override, recordRTP, mysqlloadconfig, spooldir_rtp, on-demand audio generation, GUI audio playback
'''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 and 4-state options for capture rules?
* What are the limitations of capture rules (SIP headers, IP AND logic)?
* 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? Can capture rules override global settings?
* Why is audio recorded despite savertp=header?
* What does the Skip option do? Does it work for RTP-only IPs?
* 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?
* How can I add capture rules directly to the database?
* How can I use capture rules for PCI DSS compliance with DTMF?
* How do I use spooldir_2 for legal holds or VIP retention?
* How do I inspect which rules have DTMF enabled?
* Is spooldir_2 an automatic overflow directory?
* How do I configure on-demand audio generation with spooldir_rtp?
* How can I use capture rules for PCI DSS compliance with selective DTMF?
* How do I inspect which rules have DTMF enabled (crules_print, database query)?
* Is capture rule modification tracked in the Audit Log?
* How do I enable selective OPTIONS recording for specific IPs?
* How do I reload rules on a remote sensor behind NAT?
* How do I reload rules on a remote sensor behind NAT?
* What is the filter directive alternative for complex IP pair filtering?
* What is the filter directive alternative for complex IP filtering?


[[Category:GUI manual]]
[[Category:GUI manual]]
[[Category:Sniffer Configuration]]
[[Category:Sniffer Configuration]]

Latest revision as of 16:50, 8 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

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=10189"