Capture rules: Difference between revisions

From VoIPmonitor.org
(Add link to troubleshooting guide)
(Merge Capture_rules_troubleshooting into main page, improve formatting with tables and diagram, fix structure)
Line 1: Line 1:
== Capture Rules ==
{{DISPLAYTITLE:Capture Rules}}
__TOC__


Capture rules allow selective recording of calls to disk based on IP addresses or phone numbers. Typically, RTP packets are not fully saved (or only headers are), but rules can enable full RTP, graphs, or SIP signaling capture. Rules can also trigger shell scripts (see [[Sniffer_configuration#filtercommand]]).
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.


The sniffer loads rules on startup and supports reloading without restart. Changes are not auto-reloaded; click the green "reload sniffer" button in the control panel to apply them. Failed reloads display an error.
== How Capture Rules Work ==


=== Rule Options ===
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.


Some options use a 3-state combo:
<kroki lang="plantuml">
@startuml
skinparam shadowing false
skinparam defaultFontName Arial


* '''GLOBAL''': Inherits from global sniffer configuration (e.g., enable SIP REGISTER for specific IPs without overriding RTP settings).
rectangle "GUI" as gui
* '''ON''': Enables the option (e.g., RTP recording).
rectangle "Sensor\n(Manager API\nport 5029)" as sensor
* '''OFF''': Disables the option (e.g., no RTP recording).
database "voipmonitor.conf\n& capture rules" as config


* '''Skip''': Ignores calls entirely (no files, RTP analysis, or CDR).
gui -> sensor : reload command
* '''Auto remove at''': Deletes the rule on a specified date (e.g., auto-delete after 3 days for temporary REGISTER saving).
sensor -> config : re-read rules
sensor -> gui : success/error
@enduml
</kroki>


[[File:capturerules-ip.png]]
== Rule Options ==


[[File:capturerules-tel.png]]
Capture rules support the following configuration options:


=== GUI Usage ===
=== 3-State Options ===


Access via GUI control panel to create, edit, or reload rules. Use IP or TEL number filters for targeted capture.
Some options use a 3-state selector:


=== AI Summary for RAG ===
{| class="wikitable"
|-
! State !! Description !! Use Case
|-
| '''GLOBAL''' || Inherits from global sniffer configuration || Enable SIP REGISTER for specific IPs without overriding RTP settings
|-
| '''ON''' || Explicitly enables the option || Force RTP recording for matched calls
|-
| '''OFF''' || Explicitly disables the option || Disable recording for matched calls
|}


'''Summary:''' This article explains VoIPmonitor's capture rules for selective call recording based on IP or numbers. It covers rule loading/reloading, 3-state options (GLOBAL/ON/OFF), skip/auto-remove features, and script integration.
=== Special Options ===


'''Keywords:''' capture rules, selective recording, RTP packets, SIP signaling, sniffer reload, GLOBAL option, skip calls, auto-remove, filtercommand
{| class="wikitable"
|-
! Option !! Description
|-
| '''Skip''' || Ignores matched calls entirely - no files are created, no RTP analysis is performed, and no CDR is generated
|-
| '''Auto remove at''' || Automatically deletes the rule on a specified date (useful for temporary debugging rules)
|}
 
=== 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.
 
== GUI Usage ==
 
Access capture rules via the GUI control panel:
 
# Navigate to '''Control Panel''' (Dashboard)
# Click on '''Capture Rules''' section
# Create rules using '''IP''' or '''TEL number''' filters
# Click the green '''reload sniffer''' button to apply changes
 
[[File:capturerules-ip.png|frame|IP-based capture rule configuration]]
 
[[File:capturerules-tel.png|frame|Telephone number-based capture rule configuration]]
 
== Troubleshooting ==
 
If changes made to capture rules in the GUI are not being applied, the most common cause is that the reload signal never reached the sensor due to network connectivity issues.
 
=== Step 1: Test Manager API Connectivity ===
 
Before attempting a reload, verify that the GUI can reach the sensor's Manager API port (default 5029).
 
Test connectivity from the GUI server:
<syntaxhighlight lang="bash">
# Replace PROBE_IP with your sensor's actual IP address
echo 'getversion' | nc PROBE_IP 5029
</syntaxhighlight>
 
{| class="wikitable"
|-
! Result !! Meaning !! Action
|-
| Version string (e.g., <code>voipmonitor 8.0.0-SVN.10</code>) || Connectivity OK || Proceed to Step 2
|-
| No output / connection times out || Network problem || Check firewall and routing
|-
| Connection refused || Manager API not running || Check sensor service status
|}
 
==== Common Connectivity Issues ====
 
* '''Firewall blocking port 5029''' - Ensure port 5029/TCP is open on the sensor's firewall
* '''Wrong IP address in Settings > Sensors''' - Verify the Manager IP matches the sensor's actual IP
* '''NAT/Routing issue''' - For sensors behind NAT, use the Server API method (see below)
 
=== Step 2: Reload Methods ===
 
If connectivity test succeeds, use one of these reload methods:
 
==== Method 1: Web GUI Reload Button (Recommended) ====
 
# Log in to the VoIPmonitor GUI
# Navigate to '''Control Panel''' (Dashboard)
# Click the green '''reload sniffer''' button
# Check for error messages if reload fails
 
==== Method 2: CLI Manager API ====
 
<syntaxhighlight lang="bash">
echo 'reload' | nc PROBE_IP 5029
</syntaxhighlight>
 
Use this method if you cannot access the GUI or need automation.
 
==== Method 3: Server API (for Client/Server Mode) ====
 
If sensors are in client/server mode and manager ports aren't directly accessible:
 
<syntaxhighlight lang="bash">
# Step 1: List connected sensors and get sensor_id
echo 'list_active_clients' | nc SERVER_IP 5029
 
# Step 2: Send reload command via Server API port (default 60024)
echo '{"type_connection":"gui_command","sensor_id":SENSOR_ID,"command":"reload"}' | nc SERVER_IP 60024
</syntaxhighlight>
 
Replace <code>SENSOR_ID</code> with the ID from Step 1 and <code>SERVER_IP</code> with the central server's IP.
 
=== Step 3: Immediate Workaround - Restart Sniffer ===
 
If the reload fails and you cannot resolve the connectivity issue immediately, restart the sniffer service on the sensor:
 
<syntaxhighlight lang="bash">
# SSH to the sensor
ssh root@SENSOR_IP
 
# Check current status
systemctl status voipmonitor
 
# Restart the service (this forces a full reload of all rules)
systemctl restart voipmonitor
</syntaxhighlight>
 
=== Verifying Rules Are Active ===
 
After reloading rules, verify they are active:
 
'''1. Check logs for reload confirmation:'''
<syntaxhighlight lang="bash">
# Debian/Ubuntu
tail -f /var/log/syslog | grep voipmonitor
 
# CentOS/RHEL/AlmaLinux
tail -f /var/log/messages | grep voipmonitor
</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 for reliable rule management
* '''Use monitoring tools''' to detect network connectivity issues early
* Consider '''client/server mode''' if sensors are in different networks - the Server API uses persistent connections that are more reliable
 
== AI Summary for RAG ==
 
'''Summary:''' This article explains VoIPmonitor's capture rules for selective call recording based on IP addresses or phone numbers. It covers rule configuration options (3-state GLOBAL/ON/OFF, Skip, Auto remove), GUI usage, and script integration via filtercommand. The troubleshooting section explains how to diagnose and fix issues when rule changes are not applied, including testing Manager API connectivity with the <code>getversion</code> command, three reload methods (GUI button, CLI, Server API), and verification steps.
 
'''Keywords:''' capture rules, selective recording, RTP packets, SIP signaling, sniffer reload, GLOBAL option, skip calls, auto-remove, filtercommand, manager api, getversion, port 5029, troubleshooting, reload not working


'''Key Questions:'''
'''Key Questions:'''
* How do capture rules work in VoIPmonitor?
* How do capture rules work in VoIPmonitor?
* What are the 3-state options for rules?
* What are the 3-state options (GLOBAL/ON/OFF) for rules?
* How do I reload rules without restarting the sniffer?
* How do I reload rules without restarting the sniffer?
* What does the 'Skip' option do?
* What does the Skip option do?
* How can I auto-delete a rule after a certain date?
* How can I auto-delete a rule after a certain date?
* Can rules trigger external scripts?
* Can rules trigger external scripts?
=== Troubleshooting ===
* 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?
If changes made to capture rules in the GUI are not being applied, see the [[Capture_rules_troubleshooting|Capture Rules Troubleshooting]] guide. It covers:
* How can I reload capture rules if the sensor is behind NAT?
* How do I verify that capture rules have been reloaded?


* Testing Manager API connectivity with <code>getversion</code>
[[Category:GUI manual]]
* Resolving network/firewall issues preventing reload
[[Category:Sniffer Configuration]]
* Alternative reload methods (GUI button, CLI, Server API)
* Immediate workaround by restarting the sniffer service
* Verifying that rules are active

Revision as of 18:54, 4 January 2026

Capture rules allow selective recording of calls to disk based on IP addresses or phone numbers. By default, RTP packets may not be fully saved (or only headers are stored), but rules can enable full RTP recording, call graphs, or SIP signaling capture for specific calls. Rules can also trigger external shell scripts for custom processing.

How Capture Rules Work

The sniffer loads capture rules on startup and supports hot-reloading without service restart. Changes made in the GUI are not automatically applied to the running sniffer - you must click the green "reload sniffer" button in the control panel to apply them.

Rule Options

Capture rules support the following configuration options:

3-State Options

Some options use a 3-state selector:

State Description Use Case
GLOBAL Inherits from global sniffer configuration Enable SIP REGISTER for specific IPs without overriding RTP settings
ON Explicitly enables the option Force RTP recording for matched calls
OFF Explicitly disables the option Disable recording for matched calls

Special Options

Option Description
Skip Ignores matched calls entirely - no files are created, no RTP analysis is performed, and no CDR is generated
Auto remove at Automatically deletes the rule on a specified date (useful for temporary debugging rules)

Script Integration

Rules can trigger external shell scripts when calls match. Configure this via the filtercommand option in voipmonitor.conf. See Sniffer_configuration#filtercommand for details.

GUI Usage

Access capture rules via the GUI control panel:

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

Troubleshooting

If changes made to capture rules in the GUI are not being applied, the most common cause is that the reload signal never reached the sensor due to network connectivity issues.

Step 1: Test Manager API Connectivity

Before attempting a reload, verify that the GUI can reach the sensor's Manager API port (default 5029).

Test connectivity from the GUI server: 

# Replace PROBE_IP with your sensor's actual IP address
echo 'getversion' | nc PROBE_IP 5029
Result Meaning Action
Version string (e.g., voipmonitor 8.0.0-SVN.10) Connectivity OK Proceed to Step 2
No output / connection times out Network problem Check firewall and routing
Connection refused Manager API not running Check sensor service status

Common Connectivity Issues

  • Firewall blocking port 5029 - Ensure port 5029/TCP is open on the sensor's firewall
  • Wrong IP address in Settings > Sensors - Verify the Manager IP matches the sensor's actual IP
  • NAT/Routing issue - For sensors behind NAT, use the Server API method (see below)

Step 2: Reload Methods

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

Method 1: Web GUI Reload Button (Recommended)

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

Method 2: CLI Manager API

echo 'reload' | nc PROBE_IP 5029

Use this method if you cannot access the GUI or need automation.

Method 3: Server API (for Client/Server Mode)

If sensors are in client/server mode and manager ports aren't directly accessible: 

# Step 1: List connected sensors and get sensor_id
echo 'list_active_clients' | nc SERVER_IP 5029

# Step 2: Send reload command via Server API port (default 60024)
echo '{"type_connection":"gui_command","sensor_id":SENSOR_ID,"command":"reload"}' | nc SERVER_IP 60024

Replace SENSOR_ID with the ID from Step 1 and SERVER_IP with the central server's IP.

Step 3: Immediate Workaround - Restart Sniffer

If the reload fails and you cannot resolve the connectivity issue immediately, restart the sniffer service on the sensor: 

# SSH to the sensor
ssh root@SENSOR_IP

# Check current status
systemctl status voipmonitor

# Restart the service (this forces a full reload of all rules)
systemctl restart voipmonitor

Verifying Rules Are Active

After reloading rules, verify they are active:

1. Check logs for reload confirmation: 

# Debian/Ubuntu
tail -f /var/log/syslog | grep voipmonitor

# CentOS/RHEL/AlmaLinux
tail -f /var/log/messages | grep voipmonitor

Look for messages like Rules reloaded or capture rules re-read.

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

3. Monitor CDR view to confirm captured/skipped calls match your rule configuration.

Preventing Future Issues

  • Ensure stable network connectivity between GUI and sensors for reliable rule management
  • Use monitoring tools to detect network connectivity issues early
  • Consider client/server mode if sensors are in different networks - the Server API uses persistent connections that are more reliable

AI Summary for RAG

Summary: This article explains VoIPmonitor's capture rules for selective call recording based on IP addresses or phone numbers. It covers rule configuration options (3-state GLOBAL/ON/OFF, Skip, Auto remove), GUI usage, and script integration via filtercommand. The troubleshooting section explains how to diagnose and fix issues when rule changes are not applied, including testing Manager API connectivity with the getversion command, three reload methods (GUI button, CLI, Server API), and verification steps.

Keywords: capture rules, selective recording, RTP packets, SIP signaling, sniffer reload, GLOBAL option, skip calls, auto-remove, filtercommand, manager api, getversion, port 5029, troubleshooting, reload not working

Key Questions:

  • How do capture rules work in VoIPmonitor?
  • What are the 3-state options (GLOBAL/ON/OFF) for rules?
  • How do I reload rules without restarting the sniffer?
  • What does the Skip option do?
  • How can I auto-delete a rule after a certain date?
  • Can rules trigger external scripts?
  • 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 verify that capture rules have been reloaded?
Retrieved from "https://www.voipmonitor.org/doc/index.php?title=Capture_rules&oldid=6553"