RTPengine media relay (rtpengine)
Optional RTP relay driven by Kamailio: media anchoring, difficult NAT and media interconnection with carriers. Userspace forwarding, ng control protocol on the admin address, Prometheus metrics on demand.
Generated from catalog/services/rtpengine.yaml: do not edit by hand.
Summary
| Version | 11.5.1.18 |
| Use | install and configure |
| Layer | infrastructure (shown apart) |
| Category | Network |
| Installation methods | package |
| External connection | no |
| Sandbox only | no |
Licence
| SPDX identifier | GPL-3.0-or-later |
| Licence policy | licence exception |
| Licence exception | LEX-026 (pending, awaiting the client) |
| Licence note | GPL-3.0-or-later with the OpenSSL linking exception of Sipwise (debian/copyright of the project; SPDX lists no identifier for this exception): a separate daemon controlled over its ng network protocol; no RTPengine code is linked into Navin. The offline bundle redistributes the distribution packages with their notices and sources. |
| Platform component | rtpengine |
Packages and artifacts
A package the project of the service publishes (its image, its binary archive, its Python or OS package) carries the licence of the service; a third-party package carries the licence written on its row, read from the official upstream metadata.
| Kind | Package | Version | Licence | Details |
|---|---|---|---|---|
| OS package | rtpengine-daemon | version of the configured repository | GPL-3.0-or-later | Debian family (apt) |
| OS package | rtpengine-utils | version of the configured repository | GPL-3.0-or-later | Debian family (apt) |
Supported systems and architectures
| Method | Operating systems | Architectures |
|---|---|---|
package | Debian family (apt) | x86_64, aarch64 (not restricted by the descriptor) |
- No
packagemethod on the RHEL family (dnf): No RTPengine package exists in RHEL nor in EPEL 9 and 10 (the Sipwise project publishes Debian packages only). Place the media relay on Ubuntu 24.04 (universe: rtpengine-daemon 11.5.1.18) or Debian 13 (rtpengine-daemon 12.5.1.31). - Method
packageon the Debian family (apt) limited to Ubuntu 24.04, Debian 13: The rendered configuration is validated against the RTPengine of Ubuntu 24.04 (11.5.1.18) and Debian 13 (12.5.1.31) only; the older releases of Debian 12 and Ubuntu 22.04 are not part of the offline mirror of the telephony.
Units of the distribution masked by the method package: rtpengine-daemon.service. The postinst of the packages starts them with the stock configuration: right after the install the agent stops, disables and masks them (task systemd.mask, only when their unit file belongs to an installed package), and the component runs from its own unit navin-<service>-<component>.service. The uninstall only unmasks them.
Certified host systems: RHEL 8/9/10, Rocky Linux 8/9/10, AlmaLinux 8/9/10, Oracle Linux 8/9, CentOS Stream 9/10, Ubuntu 22.04/24.04, Debian 12, Arch Linux (rolling). The host preflight accepts these systems (other releases of a known family give a warning, end of life releases are refused) and the x86_64 and aarch64 architectures.
Prerequisites
Host
The descriptor declares no host preflight check.
Programs the commands and checks of the service start on the host, outside the managed roots: add them to allowed_commands of the agent (see Security of the Navin agent), else the agent refuses them with command_not_allowed: /usr/bin/rtpengine-ctl.
Network and ports
| Component | Port name | Port | Opened in the host firewall |
|---|---|---|---|
rtpengine | ng | 2223/udp | yes |
rtpengine | media | 30000-39999/udp | yes |
rtpengine | metrics | 2224/tcp | yes |
rtpengine | cli | 9900/tcp | no |
Services and connections needed
This service has no dependency.
Installation methods and modes
| Method | Default | What the method uses |
|---|---|---|
package | yes | the OS packages of the descriptor, installed by the package manager of the host |
Components
| Component | Kind | Installation methods | Ports |
|---|---|---|---|
RTPengine (rtpengine) | master | package | 2223/udp, 30000-39999/udp, 2224/tcp, 9900/tcp |
Single (single) (default)
One media relay.
What the mode deploys:
| Component | Placement |
|---|---|
rtpengine | min 1, max 1 |
Redundant (redundant)
Two or more independent relays used in turn by Kamailio; a lost relay drops the media of its calls.
What the mode deploys:
| Component | Placement |
|---|---|
rtpengine | min 2, recommended 2 |
Install this service
The install wizard of the Navin Manager plans, validates and runs the installation; you need the services:install permission on the cluster.
-
Open the wizard. In Clusters, choose the row action Install services of the target cluster. The wizard opens on its first step, Service.
-
Choose the service. On the Service step, select RTPengine media relay. The card shows the licence
GPL-3.0-or-later. -
Choose the hosts and the mode. On the Hosts step, tick the hosts, then choose the Mode:
single(default),redundant. Each mode deploys the components listed in Installation methods and modes. -
Bindings. This service has no dependency: the Bindings step has nothing to bind.
-
Configure. On the Configure step, review the parameters (see Configuration parameters). Passwords left empty with a generated default are generated and sealed by the Manager.
-
Review and install. On the Install step the Manager validates the plan and shows the installation order; when it says "The plan is valid. Ready to install.", choose Install. A highly available mode is installed only when its HA checks pass.
-
Verify. The operation ends when the health checks of every instance pass (see Health checks); the service then shows as running in Services.
High availability
| Cluster | none (none) |
| High availability | redundancy (redundancy) |
| Failover | client side (client) |
| Replication | none (none) |
| Quorum | none (none) |
| Discovery | static (static) |
| Entry point | client discovery (client-discovery) |
| Official documentation | https://rtpengine.readthedocs.io/en/latest/overview.html |
| References | https://www.kamailio.org/docs/modules/5.7.x/modules/rtpengine.html |
Topology per mode
| Modes | Highest catalog level | Distribution | Quorum component | Fault domains | Description |
|---|---|---|---|---|---|
single | standalone (standalone) | single (single) | - | 1 | One relay: its loss drops the media of the calls it anchors. |
redundant | ha (ha) | active-active (active-active) | - | 2 | Independent relays; Kamailio sends each new call to an available one. |
Notes
- When it is justified: RTP anchoring on the SIP edge (lawful or topology hiding requirements), phones or carriers behind a NAT that Asterisk cannot traverse, media interconnection between networks that do not route to each other. When it is not: Asterisk anchors the media of the PBX calls itself and LiveKit SIP the media of the AI calls; the WebRTC softphones talk DTLS-SRTP with Asterisk, never through RTPengine.
- The relays share no state (no Redis configured): the calls of a lost relay lose their media; new calls go to the others.
Configuration parameters
Network
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|---|---|---|---|---|---|---|
ng port (ng_port) | port | 2223 | - | no | no | yes | UDP control port of the ng protocol on the admin address. ng has no authentication: keep the admin address on a network reached by the Kamailio hosts only. |
Admin address (admin_address) | string | (empty) | - | no | no | yes | Address of the ng and HTTP listeners; empty: the address of the host. (scope host) |
HTTP metrics (metrics_enabled) | bool | false | - | no | no | yes | Opens the HTTP listener: Prometheus /metrics, but also the command interface under /cli, without authentication; restricted to the hosts of the cluster by the host firewall. |
HTTP port (http_port) | port | 2224 | - | no | no | yes | Port of /metrics on the admin address, while HTTP metrics are on. |
CLI port (cli_port) | port | 9900 | - | no | no | yes | Loopback port of rtpengine-ctl (commands of the Manager). |
Media
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|---|---|---|---|---|---|---|
Media address (media_address) | string | (empty) | - | no | no | yes | Local address the RTP ports bind to; empty: the address of the host. (scope host) |
Advertised address (advertised_address) | string | (empty) | - | no | no | yes | Public address written in the SDP when the host is behind a 1:1 NAT; empty: the media address. (scope host) |
First RTP port (port_min) | port | 30000 | min 1024, max 39000 | no | no | yes | First UDP port of the media range, which ends at 39999 (public, two ports per relayed leg). |
RTP timeout (rtp_timeout_s) | int | 60 | min 10, max 3600 | no | no | no | Seconds without media before a call is closed. |
On hold timeout (silent_timeout_s) | int | 3600 | min 60, max 86400 | no | no | no | Seconds without media for a call on hold (sendonly) before it is closed. |
Maximum call duration (max_call_duration_s) | int | 14400 | min 60, max 86400 | no | no | no | Seconds after which a call is closed whatever its media. |
Tuning
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|---|---|---|---|---|---|---|
Threads (threads) | int | 4 | min 1, max 64 | no | no | yes | Worker threads relaying the media. (recommended max(2, min(32, host.cpu_count))) |
Log level (log_level) | int | 5 | min 1, max 7 | no | no | no | Syslog level: 3 errors, 5 notices, 6 info, 7 debug. |
Endpoints
| Endpoint | Scheme | Component | Port | Path | TLS parameter | Binding parameters | Binding secrets | Provisioning command |
|---|---|---|---|---|---|---|---|---|
ng | ng | rtpengine | 2223 (ng_port) | - | - | - | - | - |
Commands
| Command | Component | Target | Description |
|---|---|---|---|
Sessions (sessions) | rtpengine | every host | Number of relayed sessions on every relay. |
Statistics (totals) | rtpengine | every host | Totals since start: sessions, packets, errors, timeouts. |
Health checks
Liveness (per instance)
| Component | Check | Details |
|---|---|---|
rtpengine | TCP 127.0.0.1:{{ config.cli_port }} | 20 retries; interval 1 s; timeout 3 s |
Readiness (service check)
| Check | Details |
|---|---|
/usr/bin/rtpengine-ctl -ip 127.0.0.1 -port {{ config.cli_port }} list numsessions | Expected Current sessions; 10 retries; interval 3 s; timeout 10 s |
Preflight checks
| Check | Type | Meaning | Severity | Components |
|---|---|---|---|---|
ng_port_free | port_free {"param": "ng_port"} | port 2223 free on the host | blocking | every component |
Uninstall
Paths removed when the data is purged: {{ paths.log }}.
Upstream documentation
- Homepage: https://rtpengine.readthedocs.io
- Source: https://github.com/sipwise/rtpengine
- High availability: https://rtpengine.readthedocs.io/en/latest/overview.html
- High availability: https://www.kamailio.org/docs/modules/5.7.x/modules/rtpengine.html