Capture rules - reload

This is an advanced guide for administrators and developers who need to programmatically add and manage VoIPmonitor's capture rules directly in the database and reload them without using the web interface. This method is ideal for automation, bulk rule creation, or managing remote sensors.

Overview

VoIPmonitor's capture rules allow for fine-grained control over which calls are recorded. While these are typically managed in the GUI, you can also manipulate them directly in the MySQL database. After adding or changing rules in the database, you must signal the running sniffer to reload them.

This guide covers two main parts:

1. Creating Rules: How to manually insert IP-based and telephone number-based rules into the database.
2. Reloading Rules: How to force a running sniffer to apply the new rules using its API.

Part 1: Adding Capture Rules to the Database

Capture rules are stored in the `filter_ip` and `filter_telnum` tables in the `voipmonitor` database. You can add new rules using standard SQL `INSERT` statements.

A. Adding IP-Based Rules

Rules in the `filter_ip` table are based on source or destination IP addresses or subnets.

Key Columns

• ip: The IP address, which must be converted to an integer using the INET_ATON() function.
• mask: The subnet mask in CIDR notation (e.g., 24 for a /24 network).
• direction: 1 for source, 2 for destination, or 0 for both.
• rtp: The action for RTP (audio) streams. 1 means SAVE, 2 means DISCARD, 3 means save only the header.

Example

This SQL statement adds a rule to force-save RTP for all calls from or to the `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);

B. Adding Telephone Number-Based Rules

Rules in the `filter_telnum` table are based on the caller or called number prefix.

Key Columns

• prefix: The telephone number prefix to match (e.g., 4420).
• direction: 1 for source (caller), 2 for destination (called), or 0 for both.
• rtp: The action for RTP streams (1 = SAVE, 2 = DISCARD, etc.).

Example 1

Match any direction

This rule forces RTP saving for any call where the caller or called number starts with `12345`.

INSERT INTO `voipmonitor`.`filter_telnum` 
(`prefix`, `fixed_len`, `direction`, `rtp`) 
VALUES 
('12345', 0, 0, 1);

Example 2

Match only destination

This rule forces RTP saving only when the called number starts with `98765`.

INSERT INTO `voipmonitor`.`filter_telnum` 
(`prefix`, `fixed_len`, `direction`, `rtp`) 
VALUES 
('98765', 0, 2, 1);

Part 2: Reloading Rules on a Running Sniffer

After inserting rules into the database, they will not take effect until the sniffer process reloads its configuration. You can trigger this remotely without restarting the service.

Method 1: Using the Manager API (for directly accessible sensors)

If the sensor's manager port (default `5029`) is accessible from your location, you can send a simple `reload` command.

Example

# Replace 192.168.88.234 with your sensor's IP address
echo 'reload' | nc 192.168.88.234 5029

Method 2: Using the Server API (for sensors in a client/server cluster)

If your sensors are configured in the modern client/server mode, their manager ports may not be directly accessible. In this case, you can send the reload command via the central "server" instance.

Step 1

Get the ID of the remote sensor

First, query the central server's manager API to get a list of connected clients and their unique `sensor_id`.

# Connect to the central server's manager port (e.g., 127.0.0.1:5029)
echo 'list_active_clients' | nc 127.0.0.1 5029

The output will be a JSON object listing connected clients. Look for the `sensor_id` you want to reload.

{"count":1,"services":[{"ip":"127.0.0.1","port":54137,"sensor_id":114}]}

Step 2

Send the reload command via the Server API

Now, send a specially formatted JSON command to the central server's server port (default `60024`), specifying the target `sensor_id`.

# Connect to the central server's SERVER port (e.g., 127.0.0.1:60024)
echo '{"type_connection":"gui_command","sensor_id":114,"command":"reload"}' | nc 127.0.0.1 60024

The central server will forward the `reload` command to the specified remote sensor over its secure channel.

AI Summary for RAG

Summary: This guide provides an advanced tutorial on how to programmatically manage VoIPmonitor's capture rules by directly manipulating the database and using the sniffer's API. It is intended for automation and bulk operations. The first part explains how to add new rules by inserting rows into the `filter_ip` and `filter_telnum` MySQL tables, providing annotated SQL `INSERT` examples for both types. It highlights key columns like `direction` and the use of the `INET_ATON()` function for IP addresses. The second part details two distinct methods for forcing a running sniffer to apply the new rules without a restart. Method 1 describes using the standard Manager API (`echo 'reload' | nc ...`), suitable for directly accessible sensors. Method 2 explains the process for sensors in a client/server architecture, which involves a two-step process: first, querying the central server's Manager API with `list_active_clients` to find a remote sensor's ID, and second, sending a JSON-formatted command to the central server's Server API port (e.g., 60024) to relay the `reload` command to the target remote sensor. Keywords: capture rules, filter, automation, script, database, sql, insert, `filter_ip`, `filter_telnum`, reload, manager api, server api, `list_active_clients`, cli, command line Key Questions:

• How can I add capture rules without using the GUI?
• How to add IP or telephone number based filters directly to the database?
• How can I force a running sniffer to reload its capture rules?
• What is the difference between the Manager API and the Server API for reloading rules?
• How do I reload rules on a remote sensor that is behind NAT in a client/server setup?
• What do the `direction` and `rtp` columns mean in the `filter_ip` table?
• How to use the `INET_ATON()` function for capture rules?