RTP Relay Module


Table of Contents

1. Admin Guide
1.1. Overview
1.2. Multiple Branches
1.3. Dependencies
1.3.1. OpenSIPS Modules
1.3.2. External Libraries or Applications
1.4. Exported Functions
1.4.1. rtp_relay_engage(engine, [set])
1.5. Exported MI Functions
1.5.1. rtp_relay_list
1.5.2. rtp_relay_update
1.5.3. rtp_relay_update_callid
1.6. Exported Pseudo-Variables
1.6.1. $rtp_relay
1.6.2. $rtp_relay_peer
2. Contributors
2.1. By Commit Statistics
2.2. By Commit Activity
3. Documentation
3.1. Contributors

List of Tables

2.1. Top contributors by DevScore(1), authored commits(2) and lines added/removed(3)
2.2. Most recently active contributors(1) to this module

List of Examples

1.1. rtp_relay_engage usage
1.2. rtp_relay_list usage
1.3. rtp_relay_update usage
1.4. rtp_relay_update_callid usage

Chapter1.Admin Guide

1.1.Overview

The purpose of this module is to simplify the usage of different RTP Relays Servers (such as RTPProxy, RTPEngine, Media Proxy) in OpenSIPS scripting, as well as to provide various complex features that rely on the usage of RTP relays (such as media re-anchoring).

The module provides the logic to engage a specific RTP relay in a call during initial INVITE, and then it will handle the entire communication with the RTP relay, until the call terminates.

Moreover, one can specify various flags that modify the way RTP engines use each user agent's SDP - these flags are persistent throughout the entire RTP session, and are being used for further in-dialog requests. These flags can be specified through the $rtp_relay and/or $rtp_relay_peer variables at initial INVITE, and are then passed along with the RTP relay context until the end of the call. They can also be modified during sequential in-dialog requests.

This is not a stand-alone module that communicates directly with RTP relays, but rather a generic interface that is able to interact with the modules that interact with each specific RTP Relay (such as rtpproxy or rtpengine) and implement their specific communication protocol.

1.2.Multiple Branches

The module is able to handle RTP relay for multiple branches, with different flags flavors. Each branch can have its flags tuned through the $rtp_relay variable - if the variable is provisioned in the main route, then the flags are inherited by all further branches, unless specifically modified per branch. To modify a specific branch, one needs to specify the desired branch index as variable index (i.e. $(rtp_relay[1]) = "cor"). When provisioned in a branch route, the flags are only changed for that specific branch.

The multiple branches behavior is handled differently by the back-end engine, depending on its capabilities. For example, rtpengine is able to natively support calls with multiple branches, whereas for rtpproxy, each branch is emulated in a different session with a different call-id.

When the call gets answered and a single branch remains active, all the other branches are destroyed and only the established branches remain active throughout the call.

1.3.Dependencies

1.3.1.OpenSIPS Modules

The following modules must be loaded before this module:

  • Dialog module - used to keep track of in-dialog requests.

  • RTP Relay module(s) - such rtpproxy, or rtpengine, or any module that implements the rtp_relay interface.

1.3.2.External Libraries or Applications

The following libraries or applications must be installed before running OpenSIPS with this module loaded:

  • None.

1.4.Exported Functions

1.4.1. rtp_relay_engage(engine, [set])

Engages the RTP Relay engine for the current initial INVITE. After calling this function, the entire RTP relay communication will be handled by the module itself, without having to intervene for any further in-dialog requests/replies (unless you specifically want to).

The function is not performing the media requests on the spot, but rather registers the hooks to automatically handle any further media requests.

The RTP session modifiers used are the ones provisioned through the $rtp_relay and/or $rtp_relay_peer variables.

The function can be called from the main request route - in this case the RTP relay will be engaged for any further branches created, or from the branch route - in this case the RTP relay will only be engaged for the branch where it was called, or that has an associated rtp_relay provisioned.

Meaning of the parameters is as follows:

  • engine(string) - the RTP relay engine to be used for the call (i.e. rtpproxy.

  • set(int, optional) - the set used for this call.

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

Example1.1.rtp_relay_engage usage

...
if (is_method("INVITE") && !has_totag()) {
	xlog("SCRIPT: engaging RTPProxy relay for all branches\n");
	$rtp_relay = "co";
	$rtp_relay_peer = "co";
	rtp_relay_engage("rtpproxy");
}
...
		

1.5.Exported MI Functions

1.5.1.rtp_relay_list

Lists all the RTP Relay sessions engaged.

Parameters:

  • engine - (optional) the RTP relay engine (i.e. rtpproxy or rtpengine).

  • set - (optional) the RTP relay set. When used, the engine parameter must also be specified.

  • node - (optional) the RTP relay node. When used, the engine parameter must also be specified.

Example1.2. rtp_relay_list usage

...
## list all sessions
$ opensips-cli -x mi rtp_relay_list

## list all sessions going through a specific RTP node
$ opensips-cli -x mi rtp_relay_list rtpproxy udp:127.0.0.1:2222
...
			

1.5.2.rtp_relay_update

Updates/Re-engages the RTP relays in all ongoing RTP relay sessions.

This function can be used to trigger dialog in-dialog updates for certain ongoing RTP sessions. For all matched sessions, it re-engages an RTP Relay offer/answer session, then sends re-INVITEs to call's participants to with the updated SDP.

Note:Running the command without a filter (such as engine or set) will cause all RTP relay sessions to be re-engaged.

Note:When enforcing a new node, it is not guaranteed to be used - if the node is not avaialble, but a different one is, the active one will be chosen.

Note:If the node is being changed, the module tries to unforce the previous RTP relay session, even though it might not work.

Parameters:

  • engine - (optional) the RTP relay engine (i.e. rtpproxy or rtpengine) to be used as filter.

  • set - (optional) the RTP relay set to be used as filter. If missing, the same set will be used as it was initially engaged for.

  • node - (optional) the RTP relay node to be used as filter.

  • new_set - (optional) a new RTP Relay set to be used for the call.

  • new_node - (optional) a new RTP node to be used for the call. If new_set is missing, the same set will be used.

Example1.3. rtp_relay_update usage

...
## update all sessions that are using rtpproxy
$ opensips-cli -x mi rtp_relay_update rtpproxy
...
			

1.5.3.rtp_relay_update_callid

Updates/Re-engages the RTP relays in all ongoing RTP relay sessions.

The function basically works in the same manner as rtp_relay_update, but is to be used to update a specific callid. In addition, one can also update the engine and flags used for the particular session.

Parameters:

  • callid - the callid used to match the dialog to be updated.

  • engine - (optional) the new RTP relay engine (i.e. rtpproxy or rtpengine) to be used. If missing, the same initial engine is used.

  • set - (optional) the new RTP relay set to be used. If missing, the default same set will be used as it was initially engaged for.

  • node - (optional) the RTP relay node to be used. If not specified, the first available node is used.

  • flags - (optional) a JSON contining the caller and/or callee nodes, which contain new flags that should be used for the session. Only explicitely specified flags will be overwritten.

Example1.4. rtp_relay_update_callid usage

...
## update a call with a working RTPproxy node
$ opensips-cli -x mi rtp_relay_update_callid 1-3758963@127.0.0.1 rtpproxy

## update a call to use RTPEngine with a SRTP SDP for caller
$ opensips-cli -x mi rtp_relay_update_callid callid=1-3758963@127.0.0.1 \
	flags='{ "caller":{"type":"SRTP", "flags":"replace-origin"},
		"callee":{"type":"RTP", "flags"="replace-origin"}}'
...
			

1.6.Exported Pseudo-Variables

1.6.1.$rtp_relay

Is used to provision the RTP back-end flags for the current peer - if used in the initial INVITE REQUEST/BRANCH route, it provisions the flags of the caller, whereas if used in the initial INVITE REPLY, it provisions the callee's flags.

For a sequential request, the variable represents the flags used for the UAC that generated the request. When used in a reply, the other UAC's flags are provisioned.

In an initial INVITE scope, the variable can be provisioned per branch, by using the variable's index.

For each UAC/peer, there are several flags that can be configured:

  • flags (default, when variable is used without a name) - are the flags associated with the current UAC - they are passed along with the offer command

  • peer - these flags are passed along in the offer command, but they are flags associated with the other UAC/peer

  • ip - the IP that should be advertised in the resulted SDP (currently only used by rtpproxy)

  • type - the RTP type used by the current UAC (currently only used by rtpengine)

  • iface - the interface used for the traffic coming from this UAC.

  • disabled - provisioned as an integer, it is used to disable RTP relay for this UAC.

1.6.2.$rtp_relay_peer

This variable has the same meaning and parameters as the $rtp_relay variable, except that it is used to provision the other UAC's flags, except the current one. All other fields are similar.

Chapter2.Contributors

2.1.By Commit Statistics

Table2.1.Top contributors by DevScore(1), authored commits(2) and lines added/removed(3)

NameDevScoreCommitsLines ++Lines --
1. Razvan Crainea (@razvancrainea)51213005258

(1) DevScore = author_commits + author_lines_added / (project_lines_added / project_commits) + author_lines_deleted / (project_lines_deleted / project_commits)

(2) including any documentation-related commits, excluding merge commits. Regarding imported patches/code, we do our best to count the work on behalf of the proper owner, as per the "fix_authors" and "mod_renames" arrays in opensips/doc/build-contrib.sh. If you identify any patches/commits which do not get properly attributed to you, please submit a pull request which extends "fix_authors" and/or "mod_renames".

(3) ignoring whitespace edits, renamed files and auto-generated files

2.2.By Commit Activity

Table2.2.Most recently active contributors(1) to this module

NameCommit Activity
1. Razvan Crainea (@razvancrainea)Apr 2021 - May 2021

(1) including any documentation-related commits, excluding merge commits

Chapter3.Documentation

3.1.Contributors

Last edited by: Razvan Crainea (@razvancrainea).

Documentation Copyrights:

Copyright 2021 OpenSIPS Solutions