The RTPProxy is a high-performance software proxy for RTP streams that can work together with Sippy B2BUA, Kamailio, OpenSIPS and SER (SIP Express Router).

RTPProxy was originally developed by Maxim Sobolyev in 2003 with a purpose of VoIP calls facilitation to/from SIP User Agents located behind NAT or firewalls. That time, there were a few cases where direct end-to-end communication between users behind the NAT was not possible. RTPProxy, in common with a SIP proxy, overcomes those obstacles by acting as an intermediary point for the RTP streams.

Afterwards, the RTPProxy has become widely used by VoIP service providers that are in a demand for optimizing a traffic flow in their networks.

Later on it became apparent that there are many other possible uses of this software. It can be used in common with a signaling element (SIP Proxy or SIP B2BUA) to build complex VoIP networks, to optimize a traffic flow, to collect voice quality information and so on.

RTPProxy is now actively developed and maintained by the Sippy Software, Inc. and is available on GitHub of Sippy Labs - https://github.com/sippy/rtpproxy.

Over the years, many other individuals and organizations have contributed features and fixes into the code base, including Vonage, SipPulse, Voicenter, RateTel, either directly or by sponsoring respective development efforts (often both).

Originally it was designed for handling of NAT scenarios. It can also act as a generic media relay, as well as a gateway for RTP sessions between IPv4 and IPv6 networks.

It can perform a number of additional functions on RTP streams, including call recording, playing pre-recorded announcements, real-time stream copying and RTP payload re-framing.

The RTPProxy supports some advanced features, such as remote control mode, allowing a building of scalable distributed SIP VoIP networks. The rtpproxy modules of OpenSIPS and Kamailio (both descendants of the SIP Express Router, whose nathelper module originally provided this functionality), as well as the Sippy B2BUA, allow using multiple RTPProxy instances running on remote machines for fault-tolerance and load-balancing purposes.

An advanced high-capacity clustering and a load balancing is available through the use of RTP Cluster middleware.

The software also supports MOH/pre-recorded prompts injection, video relaying and RTP session recording to a local file or remote UDP listener(s).

The RTPProxy package by default provides the following components:

In case you want to use a pre-built RTPProxy package, then use your system's package manager to set this up:

dpkg - for Debian™ based systems (including Ubuntu™), when installing .deb packages.

apt-get / aptitude - for Debian™ based systems (including Ubuntu™), when installing from a repository.

rpm - for RPM based systems, when installing .rpm packages.

pkg - for FreeBSD™ when installing from a repository or packages.

Starting with version 3.2.0, packages for several Debian and Ubuntu releases are attached to each release on the GitHub releases page.

Official Docker images are published to Docker Hub (sippylabs/rtpproxy) and GitHub Container Registry (ghcr.io/sippy/rtpproxy) with every release and every commit to the master branch.

In case you want to compile RTPProxy from sources, use the following section "Compilation from sources".

Configuration of the loadable modules is read from a configuration file in the UCL format, specified with the --config command-line option. See Modules for the available modules and their parameters. An example is provided in doc/rtpproxy.conf.sample.

The way you integrate RTPProxy into your system startup sequence is highly OS-version dependent. If you are using a pre-built RTPProxy package then most likely such method will be provided as part of that package and the best course of actions is to use that facility.

However, if you are a package maintainer or system builder you might need to create such configuration from scratch. In the next sections we would provide some basic guidelines on how to launch RTPProxy in some common cases.

[Unit]
Description=RTPProxy media server
After=network.target
Requires=network.target

[Service]
Type=simple
PIDFile=/var/run/rtpproxy/rtpproxy.pid
Environment='OPTIONS= -f -L 4096 -l 0.0.0.0 -m 10000 -M 20000 -d INFO:LOG_LOCAL5'

Restart=always
RestartSec=5

ExecStartPre=-/bin/mkdir /var/run/rtpproxy
ExecStartPre=-/bin/chown rtpproxy:rtpproxy /var/run/rtpproxy

ExecStart=/usr/local/bin/rtpproxy -p /var/run/rtpproxy/rtpproxy.pid -s unix:/var/run/rtpproxy/rtpproxy.sock \
 -u rtpproxy:rtpproxy -n unix:/var/run/rtpproxy/rtpproxy_timeout.sock $OPTIONS
ExecStop=/usr/bin/pkill -F /var/run/rtpproxy/rtpproxy.pid

ExecStopPost=-/bin/rm -R /var/run/rtpproxy

SyslogIdentifier=rtpproxy
SyslogFacility=local5

TimeoutStartSec=10
TimeoutStopSec=10

[Install]
WantedBy=multi-user.target

Logging is a very important aspect of the RTPProxy operation that should not be overlooked. In our experience, properly configured and tested RTPProxy instance can keep running unattended literally for many years non-stop. Yet, various issues with a particular session and/or endpoint would inevitably pop-up over time, so it's of utter importance to setup logging and log management in a manner that is durable and forward-looking. Allowing someone to perform a post-mortem investigation of particular issue that happened days, if not weeks, ago with a relative ease.

Some of the considerations one should have in mind while configuring logging is:

As it was said earlier, keeping of the control socket using systemd, is a good reason to start using systemd.

A configuration process is pretty simple, there are just a few steps you need to implement to start using of it.

1. Firstly, you need to install package requirements: libsystemd-dev

2. Secondly, you need to compile rtpproxy with a systemd flag (a usual compilation process, just add an option to a configure execution):

./configure --enable-systemd

3. A third step, you need to create rtpproxy.socket systemd unit file, that will be responsible for keeping your control socket:

An example:

/etc/systemd/system/rtpproxy.socket (enabling it with systemctl enable creates the link in sockets.target.wants)

[Socket]
ListenStream=/var/run/rtpproxy/rtpproxy.sock
SocketUser=rtpproxy
SocketGroup=rtpproxy
SocketMode=0660
ExecStartPost=-/bin/chown rtpproxy:rtpproxy /var/run/rtpproxy

[Install]
WantedBy=sockets.target

The SIP proxy has to be able to write to the socket, so make sure it runs as a member of the rtpproxy group.

4. Set a parameter in startup row of rtpproxy.service unit (you don't need to provide a path to socket file):

-s systemd:

an example:

ExecStart=/usr/local/bin/rtpproxy -p /var/run/rtpproxy/rtpproxy.pid -s systemd: -u rtpproxy:rtpproxy -n unix:/var/run/rtpproxy/rtpproxy_timeout.sock -f -l 0.0.0.0 -m 10000 -M 20000 -d INFO:LOG_DAEMON

When you're done with all above, do not forget to reload systemd configuration and enable socket unit:

bash> sudo systemctl daemon-reload

bash> sudo systemctl enable rtpproxy.socket

(btw here is a nice article of how to configure systemd socket unit files - http://0pointer.de/blog/projects/socket-activation.html)

Now start rtpproxy.socket and rtpproxy.service just after that:

bash> sudo systemctl start rtpproxy.socket

bash> sudo systemctl start rtpproxy.service

At this stage, your rtpproxy.service should catch up a socket created by systemd and start working properly. If you see some kind of errors, then you're missing one of the steps defined above.

Each module is configured in its own block of the modules section of the configuration file. The name of the block is the name of the module. Unless the load parameter specifies the path to the module's shared object, the module is loaded from libdir/rtpproxy/rtpp_name.so (rtpp_name_debug.so for the debug build). Modules that take no parameters can have an empty block:

modules {
    acct_rtcp_hep {
        capt_host = 192.0.2.10
    }

    catch_dtmf {
    }
}

The same module can be loaded more than once, each loaded copy being a separate instance, numbered from 1 in the order of loading.

Modules that are controlled on a per-session basis accept sub-commands appended to the U or L command after &&, in the form Mmodule_id:instance arguments. The module IDs are listed below, and instance is 1 unless the module is loaded more than once. For example, the following command sends S to the first instance of the dtls_gw module:

U call-id 192.0.2.1 12345 from-tag && M4:1 S

Several sub-commands can be chained in the same command, each with its own &&. The output of each of them follows the reply to the main command, separated by && too. A failed sub-command is reported as a negative number, while one with no output is reported as 0, or omitted when no sub-command after it has any output.

Writes one record with the session's statistics into a CSV file for each session, when the session ends. A header line with the column names is written when the file is created. The columns include the Call-ID, the from-tag, the session setup and teardown times, and the packet, loss, jitter and SSRC statistics for each direction. The file is re-opened if it is moved or removed, e.g. by log rotation.

The module takes no sub-commands. The parameters are:

Since the parameter is optional, the module can also be loaded with the --dso command-line option.

modules {
    acct_csv {
        logfile = /var/log/rtpproxy/rtpproxy_acct.csv
    }
}

Reports every RTCP packet received, converted to JSON, to a HEP (Homer) collector, using HEPv3.

The module takes no sub-commands. The parameters are:

modules {
    acct_rtcp_hep {
        capt_host = 192.0.2.10
        capt_port = 9060
        capt_ptype = udp
        capt_id = 101
    }
}

Detects RFC 2833 (RFC 4733) telephone events in the stream and notifies the call controller of each DTMF digit received. Developed in collaboration with the OpenSIPS project. The module takes no parameters.

Detection is enabled per stream with the sub-command:

M3:1 tag [payload_type [h]]

Notifications are sent the same way as the session timeout notifications, so notifications have to be enabled for the session: the U/L command has to specify the notification socket (permitted with the -n command-line option) and the notification tag. For each digit, when its last packet is received, the following line is sent:

tag digit volume duration side

where duration is in RTP timestamp units, and side is 0 for the caller and 1 for the callee. For example:

U call-id 192.0.2.1 12345 from-tag tcp:192.0.2.100:2222 ntag && M3:1 caller%20dtmf 101

would result in notifications like:

caller dtmf 1 0 960 0

Gateways between plain RTP (RTP/AVP) and DTLS-SRTP (UDP/TLS/RTP/SAVP) streams, taking care of certificate validation, key negotiation and SRTP encryption/decryption. It can also re-encrypt already encrypted streams back to back, e.g. for recording. Requires the RTPProxy to be built with libsrtp2 (or libsrtp) and OpenSSL. A self-signed certificate is generated when the module starts. The module takes no parameters.

The sub-commands are:

For example, an incoming INVITE with plain RTP answered with DTLS-SRTP by a passive party:

U call-id 192.0.2.1 12345 from-tag && M4:1 S
35000 && actpass SHA-256 4A:AD:B9:...

L call-id 192.0.2.2 23456 from-tag to-tag && M4:1 P SHA-256 2C:7F:01:...
35002

See modules/dtls_gw/README.md for more scenarios.

Implements the lite variant of ICE (RFC 5245), allowing ICE-enabled user agents to establish media sessions through the RTPProxy, and RTCP multiplexing and de-multiplexing. Together with dtls_gw, it allows the RTPProxy to act as a WebRTC endpoint. Requires the same libraries as dtls_gw. The module takes no parameters.

The sub-commands are:

For example, an incoming INVITE with an ICE offer:

U call-id 192.0.2.1 12345 from-tag && M5:1 A ufrag pwd && M5:1 C 1 1 UDP 2130706431 192.0.2.1 12345 typ host

See modules/ice_lite/README.md for more scenarios.

The whole RTPProxy engine is also available as a library, librtpproxy, which allows running it inside another process, e.g. a test harness, a fuzzer or an application that needs a media relay of its own without managing a separate daemon.

./configure --enable-librtpproxy
make
make install

#include <librtpproxy.h>

struct rtpp_cfg *rtpp_main(int argc, const char * const *argv);
void rtpp_shutdown(struct rtpp_cfg *);

#include <sys/socket.h>
#include <stdio.h>
#include <string.h>
#include <unistd.h>

#include <librtpproxy.h>

int
main(void)
{
    int fds[2];
    char fdarg[16], buf[256];
    struct rtpp_cfg *cfsp;
    ssize_t len;

    if (socketpair(AF_UNIX, SOCK_STREAM, 0, fds) != 0)
        return (1);
    snprintf(fdarg, sizeof(fdarg), "fd:%d", fds[1]);
    const char *argv[] = {"rtpproxy", "-s", fdarg, "-l", "127.0.0.1",
      "-d", "info"};
    cfsp = rtpp_main(sizeof(argv) / sizeof(argv[0]), argv);
    if (cfsp == NULL)
        return (1);

    const char *cmd = "U call1 127.0.0.1 12000 ftag1\n";
    write(fds[0], cmd, strlen(cmd));
    len = read(fds[0], buf, sizeof(buf) - 1);
    if (len > 0) {
        buf[len] = '\0';
        printf("allocated: %s", buf);
    }

    rtpp_shutdown(cfsp);
    close(fds[0]);
    return (0);
}

The RTPProxy comes with an extensive suite of integration tests, located in the tests directory. Each test starts one or more rtpproxy instances, drives them via their control sockets, generates and captures media, and compares the results with the reference ones. The tests are also run by the CI on every change, across several operating systems, compilers and architectures.

make check

cd tests
make -j4 check TESTS="forwarding/forwarding1 playback/playback1"

# Expects RTPPROXY_BIN to be defined
.eval: 0 -> RES_OK
.eval: E50 -> SESS_NOTFOUND
socket r: stdio: -d info -p /dev/null -> example.rout

r: U call1 127.0.0.1 12000 ftag1 -> validate_port(PORT_O)
r: L call1 127.0.0.1 12002 ftag1 ttag1 -> validate_port(PORT_A)
.echo: allocated ports %%PORT_O%% and %%PORT_A%%
r: D call1 ftag1 -> str_compare(RES_OK)
r: D call1 ftag1 -> str_compare(SESS_NOTFOUND)

.close: r

#!/bin/sh

BASEDIR="`dirname "${0}"`/.."
. "${BASEDIR}/functions"

${RPTL_INT} -s "${BASEDIR}/example/example.rptl" \
 -D RTPPROXY_BIN="${RTPPROXY}"
report "running example.rptl"

${DIFF} "${BASEDIR}/example/example.output" example.rout
report "checking rtpproxy replies"