Media Engines Module Documentation

Table of Contents

1. Module Overview (Technical)
2. Module Overview (Commercial/Business)
3. Module Overview (End User/Administrator)
4. Configuration Categories
5. Common Settings Reference
6. Common Scenarios & Examples
7. Limitations & Important Notes
8. Troubleshooting Tips
9. Glossary
10. Lua Script Status ℹ️

1. Module Overview (Technical)

What Are Media Engines?

Media Engines is a Kamailio / RTPEngine configuration module that defines and manages external RTPEngine server pools. By maintaining node records in the database, the SBC backend can dynamically write the Kamailio configuration files required to balance active audio/video media streams across a network of distributed nodes.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                  Media Engines Architecture                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  SBC Admin UI (React)                                           │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        Media Engines Page                                │   │
│  │  Define nodes: host, port, weight, active status.        │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼ REST API (Fastify)                                      │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        Database: public.rtpengine_nodes                  │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼ Write / Generate config (Apply)                          │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        /etc/kamailio/sbc-rtpengines.cfg                  │   │
│  │  modparam("rtpengine", "rtpengine_sock", "udp:...")     │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼ Kamailio reads configuration                            │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        Kamailio mod_rtpengine                            │   │
│  │  Splits traffic among active sockets using weights.     │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Background Health Check

The SBC backend implements an autonomous background service (initRtpEngineHealthCheck) that runs every 30 seconds:

• Sends a UDP ping packet formatted with the RTPEngine ng protocol (d7:command4:pinge) to each active node.
• Measures network latency in milliseconds.
• Updates node state (online / offline) and the measured latency directly in the database.
• Runs an initial quick verification check 5 seconds after backend startup.

Key Tables

Key Files

2. Module Overview (Commercial/Business)

Business Value

Managing external media handlers separates signaling (handled by the SBC/Kamailio) from RTP processing (handled by RTPEngine). This provides distinct benefits:

Use Cases

1. High Call Density Environments

1. Geographical Latency Optimization

1. No-Downtime Maintenance

3. Module Overview (End User/Administrator)

What Can You Do?

• View Active Pool: Monitor a unified grid showing host addresses, port numbers, weights, statuses, real-time latencies, and last probed timestamps.
• Add/Edit Node Dialog: Define Name, IP/Hostname, UDP control port, load balancer Weight, and Active flag.
• Manual Ping: Trigger an instantaneous UDP diagnostics test to check server availability.
• Apply Pool Configuration: Rebuild the Kamailio includes with active sockets.

4. Configuration Categories

When registering or editing an RTPEngine node, the following properties are defined:

• Name

- Tooltip: Unique name to identify this RTPEngine node.

• IP / Hostname

- Tooltip: IP address or DNS hostname of the external RTPEngine server.

• Port (UDP)

- Tooltip: UDP control port where RTPEngine listens (default is 2223).

• Weight

- Tooltip: Priority weight for load balancing. Higher values receive more traffic.

• Active Node

- Tooltip: Whether this node should be included in the active pool for Kamailio.

• Description

- Tooltip: Optional notes about this node (e.g. location, provider).

5. Common Settings Reference

6. Common Scenarios & Examples

Scenario 1: Registering a Secondary RTPEngine Node

1. Access the Media Engines section.
2. Click Add Engine Node in the top right.
3. Provide the details:

- IP / Hostname: 192.168.10.15

- Port: 2223

- Weight: 2 (Gives this node double the traffic share relative to weight 1 nodes)

- Active: Enabled (Toggle set to Yes)

1. Click Save. The background service will run a ping test and list the node.

Scenario 2: Node Maintenance and Deactivation

1. Prior to shutting down an RTPEngine node for OS updates:
2. Open the edit dialog by clicking the Edit pencil icon next to the target node.
3. Change the Active Node toggle to No.
4. Click Save.
5. Click Apply Config to rebuild /etc/kamailio/sbc-rtpengines.cfg (excluding this socket).
6. Reload/Restart Kamailio. Calls will gracefully shift to the remaining active nodes.

7. Limitations & Important Notes

8. Troubleshooting Tips

Node Status Shows "Offline"

• Check Firewall: Ensure the SBC can communicate on the UDP control port (default 2223) of the target server.
• Process Verification: Log into the target node and verify the RTPEngine daemon is active:

  systemctl status rtpengine
  

• Control Interface: Ensure rtpengine is started with the correct --listen-ng interface mapping corresponding to the IP defined in the dashboard.

Manual Diagnostics Ping Failures

If you trigger a manual ping and receive a timeout:

1. Verify the route between SBC and node IP is open.
2. Test connection with nc or tcpdump on the node:

   tcpdump -i any udp port 2223
   

1. Look for incoming ping commands (ping_... d7:command4:pinge) from the SBC.

9. Glossary

Lua Script Status ℹ️

No Lua Handler Required