!!!! [[#opensips.cfg]] Normal SDP negotiation

!!!! [[#opensips-late.cfg]] Late SDP negotiation

[[http://www.opensips.org/pub/docs/tutorials/websockets/opensips-late.cfg | Here ]] you can find a more complex configuration file, that also includes support for late SDP negotiation (SDP is exchanged between 200 OK and ACK).

'''NOTE:''' the default port for WSS (443) is privileged, so if you are running this script, you should start OpenSIPS with super-user rights (as user root).

'''NOTE:''' the default port port for WSS (443) is privileged, so if you are running this script, you should start OpenSIPS with super-user rights (as user root).

!!!! [[#opensips.cfg]] Normal SDP negociation

!!!! [[#opensips-late.cfg]] Late SDP negociation

* [[#opensips.cfg | Normal SDP negociation]]

The [[http://www.opensips.org/pub/docs/tutorials/websockets/opensips.cfg | following ]] configuration file is a minimal working example of a Residential script that can handle clients connections over both UDP and Websocket transports. This example assumes that the SDP offer is present in the INVITE from the UAC and the SDP answer is in the 200 OK from the UAS.

@]

* [[#opensips-late.cfg | Late SDP negociation]]
[[http://www.opensips.org/pub/docs/tutorials/websockets/opensips-late.cfg | Here ]] you can find a more complex configuration file, that also includes support for late SDP negociation (SDP is exchanged between 200 OK and ACK).

./rtpengine -p /var/run/rtpengine.pid -i eth0/1.1.1.1 -n 127.0.0.1:60000 -c 127.0.0.0.1:60001 -m 50000 -M 55000 -E -L 7

* @@-n@@: the listening IP and port that is used by OpenSIPS to communicate with the RTPengine ('''NOTE:''' the rtpengine module only works with the rtpengine NG protocol, so you must use @@-n@@/@@--listen-ng@@; Using @@-u@@/@@--listen-udp@@ or @@-l@@/@@--listen-tcp@@ will not work!)

After installing the kernel module and the additional libraries, the rtpengine daemon has to be configured. This can be done from @@/etc/default/ngcp-rtpengine-daemon@@ if installed from debs, or from the command line if the daemon is started manually. On systemd based OSes, Eric Tamme created some [[https://github.com/etamme/federated-sip/tree/master/scripts|startup scripts]].

Also important to note that as of 2.2, certificate management has been split out into a new module, [[ http://www.opensips.org/html/docs/modules/2.2.x/tls_mgm.html|TLS_MGM]]. Setting appropriate modparams for the tls_mgm module is how we will manage our certificates for both WSS and TLS.

[[http://tools.ietf.org/html/rfc6455|WebSocket]] is a protocol that provides full-duplex communication between web clients and servers over TCP connections. Using the WebSocket protocol, browsers can connect to web servers and exchange data, regardless the type or nature of the application protocol. [[https://tools.ietf.org/html/rfc7118|RFC 7118]] leveraged this protocol in order to allow browsers to make VoIP calls using the SIP protocol. [[ http://www.opensips.org/html/docs/modules/2.2.x/proto_wss.html|WebSocketSecure]] (WSS) overlays TLS onto the Websocket protocol making the connection secure, a requirement for many browsers if you want to do WebRTC.

[[http://tools.ietf.org/html/rfc6455|WebSocket]] is a protocol that provides full-duplex communication between web clients and servers over TCP connections. Using the WebSocket protocol, browsers can connect to web servers and exchange data, regardless the type or nature of the application protocol. [[https://tools.ietf.org/html/rfc7118|RFC 7118]] leveraged this protocol in order to allow browsers to make VoIP calls using the SIP protocol. [[ http://www.opensips.org/html/docs/modules/2.2.x/proto_wss.html |WebSocketSecure} ]] (WSS) overlays TLS onto the Websocket protocol making the connection secure, a requirement for many browsers if you want to do WebRTC.

[[http://tools.ietf.org/html/rfc6455|WebSocket]] is a protocol that provides full-duplex communication between web clients and servers over TCP connections. Using the WebSocket protocol, browsers can connect to web servers and exchange data, regardless the type or nature of the application protocol. [[https://tools.ietf.org/html/rfc7118|RFC 7118]] leveraged this protocol in order to allow browsers to make VoIP calls using the SIP protocol. WebsocketSecure (WSS) overlays TLS onto the Websocket protocol making the connection secure, a requirement for many browsers if you want to do WebRTC.

This document describes how to use '''OpenSIPS''' as the core component of a SIP platform that connects both SIP clients (over UDP, TCP or TLS) as well as browser based clients using SIP over WebSockets and WebSocketsSecure. While OpenSIPS handles the SIP signalling part, media is handled by [[https://github.com/sipwise/rtpengine|RTPengine]], a high performance media proxy that is able to handle both RTP and SRTP media streams, as well as bridging between them.

You must generate certificates to use with TLS and WSS. For this example we are generating certificates using [[https://letsencrypt.org/|LetsEncrypt]]

Also important to note that as of 2.2, certificate management has been split out into a new module, tls_mgm. Setting appropriate modparams for the tls_mgm module is how we will manage our certificates for both WSS and TLS.

In order to use WebSocket and WebSocketSecure in OpenSIPS, one has to load the [[http://www.opensips.org/html/docs/modules/2.2.x/proto_ws|proto_ws]] and [[http://www.opensips.org/html/docs/modules/2.2.x/proto_wss|proto_wss]] into its configuration file and define a listener for the WebSocket and WebSocketSecure protocol. We also must load the [[http://www.opensips.org/html/docs/modules/2.2.x/tls_mgm|tls_mgm]] module in order to manage our certificates.

# set listeners for all protocols

listen=wss:127.0.0.1:443
listen=tls:127.0.0.1:5061
listen=udp:127.0.0.1:5060

# load our certificate management module
loadmodule "tls_mgm.so"

#load all protocol modules
loadmodule "proto_udp.so"
loadmodule "proto_tls.so"
loadmodule "proto_wss.so"

# modparam our certificate information
modparam("tls_mgm", "certificate","/etc/letsencrypt/live/acme.com/cert.pem")
modparam("tls_mgm", "private_key","/etc/letsencrypt/live/acme.com/privkey.pem")

if (proto == WS || proto == WSS)

# Set up listeners
listen=ws:127.0.0.1:8080
listen=wss:127.0.0.1:443
listen=tls:127.0.0.1:5061
listen=udp:127.0.0.1:5060

#### TLS protocol
loadmodule "proto_tls.so"

#### WebSocket and WebSocketSecure protocol
loadmodule "proto_wss.so"

# Certificate management
loadmodule "tls_mgm.so"
modparam("tls_mgm", "certificate","/etc/letsencrypt/live/acme.com/cert.pem")
modparam("tls_mgm", "private_key","/etc/letsencrypt/live/acme.com/privkey.pem")

# check if the clients are using WebSockets or WebSocketSecure
if (proto == WS || proto == WSS)

The following configuration file is a minimal working example of a Residential script that can handle clients connections over both UDP and Websocket transports. This example assumes that the SDP offer is present in the INVITE from the UAC and the SDP answer is in the 200 OK from the UAS.

After installing the kernel module and the additional libraries, the rtpengine daemon has to be configured. This can be done from @@/etc/default/ngcp-rtpengine-daemon@@ if installed from debs, or from the command line if the daemon is started manually. On systemd based OSes, Eric Tamme created some [[https://github.com/etamme/federated-sip/tree/2.2-config/scripts|startup scripts]].

if (is_method("REGISTER")) {

if (is_method("PUBLISH|SUBSCRIBE")) {

if (is_method("REGISTER")) {

!!!!! Documentation -> [[Documentation.Tutorials | Tutorials ]] -> [[ http://www.opensips.org/html/docs/modules/2.2.x/proto_ws.html | {+WebSocket Transport+} ]] using OpenSIPS
This page has been visited {$PageCount} times.
(:toc-float Table of Content:)
----

!!! Tutorial Overview

[[http://tools.ietf.org/html/rfc6455|WebSocket]] is a protocol that provides full-duplex communication between web clients and servers over TCP connections. Using the WebSocket protocol, browsers can connect to web servers and exchange data, regardless the type or nature of the application protocol. [[https://tools.ietf.org/html/rfc7118|RFC 7118]] leveraged this protocol in order to allow browsers to make VoIP calls using the SIP protocol.

This document describes how to use '''OpenSIPS''' as the core component of a SIP platform that connects both SIP clients (over UDP, TCP or TLS) as well as browser based clients (using SIP over WebSockets). While OpenSIPS handles the SIP signalling part, media is handled by [[https://github.com/sipwise/rtpengine|RTPengine]], a high performance media proxy that is able to handle both RTP and SRTP media streams, as well as bridging between them.

This tutorial is inspired from

!!! Setup

!!!! RTPengine

!!!!! Installation

The RTPengine consists of two main components: a kernel module used to efficiently route the RTP packets directly in kernel, and a daemon used to communicate with OpenSIPS. You can find more details [[https://github.com/sipwise/rtpengine#overview|here]]. Both components can be installed from debs (on Debian based systems) or directly from sources. Simply follow the [[https://github.com/sipwise/rtpengine#compiling-and-installing|official documentation]] to install RTPengine.

!!!!! Usage

After installing the kernel module and the additional libraries, the rtpengine daemon has to be configured. This can be done from @@/etc/default/ngcp-rtpengine-daemon@@ if installed from debs, or from the command line if the daemon is started manually. On systemd based OSes, Eric Tamme created some [[https://github.com/etamme/federated-sip/wiki|start scripts]].

The interesting parameters we are using are as follows:

* @@-i@@: the listening interface for RTP/SRTP
* @@-n@@: the listening IP and port that is used by OpenSIPS to communicate with the RTPengine
* @@-c@@: the IP and port of the CLI - this is used to gather statistics for the RTP/SRTP sessions
* @@-m, -M@@: both take an integer as argument and together define the local port range from which rtpengine will allocate UDP ports for media traffic relay. Default to 30000 and 40000 respectively.
* @@-L@@: indicates the debugging level

You can find all the parameters available [[https://github.com/sipwise/rtpengine#userspace-daemon|here]].

Here is an example that runs @@rtpengine@@ from cli that talks with OpenSIPS over localhost and RTP using the 1.1.1.1 IP:

[@
./rtpengine -p /var/run/rtpengine.pid --i eth0/1.1.1.1 -n 127.0.0.1:60000 -c 127.0.0.0.1:60001 -m 50000 -M 55000 -E -L 7
@]

!!!!! Troubleshoot

First make sure the @@rtpengine@@ daemon is started:
[@
ps -ef | grep rtpengine
@]

If the @@rtpengine@@ daemon does not start, make sure the @@xt_RTPENGINE@@ kernel module is loaded:
[@
lsmod | grep xt_RTPENGINE
@]

If the module is not loaded, make sure the @@ip_tables@@ and @@x_tables@@ kernel modules are loaded. Also, check the logs for the last errors of the system
[@
dmesg
@]

!!!! OpenSIPS

In order to use WebSocket in OpenSIPS, one has to load the [[http://www.opensips.org/html/docs/modules/2.2.x/proto_ws|proto_ws]] into its configuration file and define a listener for the WebSocket protocol.
[@
listen=ws:127.0.0.1:8080
...
loadmodule "proto_ws.so"
@]

Next, the [[http://www.opensips.org/html/docs/modules/2.2.x/rtpengine|rtpengine]] module has to be loaded and configured to communicate with the @@rtpengine@@ daemon.
[@
loadmodule "rtpengine.so"
modparam("rtpengine", "rtpengine_sock", "udp:127.0.0.1:60000")
@]

Note that the [[http://www.opensips.org/html/docs/modules/2.2.x/rtpengine#rtpengine.p.rtpengine_sock|rtpengine_sock]] parameter should be the same as the @@-n@@ parameter sent to the @@rtpengine@@ daemon, and OpenSIPS should have IP connectivity to that socket.

Next, the routing logic has to be changed in order to treat different the clients that use DTLS-SRTP, from the ones that use plain RTP and enable bridging if necessary. To do that, one can check if the request message was received over the WebSocket protocol. This can be achieved using the following code:

[@
if (proto == WS)
setflag(SRC_WS);
@]

In case the request is a REGISTER, we want to store this information in the ''location'' table, so that we know then the user is called. To do that, we can set a branch flag before calling the [[http://www.opensips.org/html/docs/modules/2.2.x/registrar.html#id294034|save()]] function. This way, when the [[http://www.opensips.org/html/docs/modules/2.2.x/registrar.html#id294366|lookup()]] method returns, we will be able to determine whether the client uses WebSocket or not.

[@
if (is_method("REGISTER"))
{
if (isflagset(SRC_WS))
setbflag(DST_WS);

fix_nated_register();
if (!save("location"))
sl_reply_error();

exit;
}
@]

When a call is placed, based on the two flags (@@STR_WS@@ and @@DST_WS@@) we can determine what our caller and callee can "speak" (either RTP or DTLS-SRTP) and instruct the @@rtpengine@@ daemon how to handle the call. We can do that by tuning the parameters passed to the [[http://www.opensips.org/html/docs/modules/2.2.x/rtpengine#rtpengine.f.rtpengine_offer|rtpengine_offer()]] function.
[@
if (isflagset(SRC_WS) && isbflagset(DST_WS))
$var(rtpengine_flags) = "ICE=force-relay DTLS=passive";
else if (isflagset(SRC_WS) && !isbflagset(DST_WS))
$var(rtpengine_flags) = "RTP/AVP replace-session-connection replace-origin ICE=remove";
else if (!isflagset(SRC_WS) && isbflagset(DST_WS))
$var(rtpengine_flags) = "UDP/TLS/RTP/SAVPF ICE=force";
else if (!isflagset(SRC_WS) && !isbflagset(DST_WS))
$var(rtpengine_flags) = "RTP/AVP replace-session-connection replace-origin ICE=remove";

rtpengine_offer("$var(rtpengine_flags)");
@]

The [[http://www.opensips.org/html/docs/modules/2.2.x/rtpengine#rtpengine.f.rtpengine_answer|rtpengine_answer()]] function logic should look like this:

[@
if (isflagset(SRC_WS) && isbflagset(DST_WS))
$var(rtpengine_flags) = "ICE=force-relay DTLS=passive";
else if (isflagset(SRC_WS) && !isbflagset(DST_WS))
$var(rtpengine_flags) = "UDP/TLS/RTP/SAVPF ICE=force";
else if (!isflagset(SRC_WS) && isbflagset(DST_WS))
$var(rtpengine_flags) = "RTP/AVP replace-session-connection replace-origin ICE=remove";
else if (!isflagset(SRC_WS) && !isbflagset(DST_WS))
$var(rtpengine_flags) = "RTP/AVP replace-session-connection replace-origin ICE=remove";

rtpengine_answer("$var(rtpengine_flags)");
@]

Now, all we have to do is to close the RTP/SRTP session when the call is ended. To do that, we use the [[http://www.opensips.org/html/docs/modules/2.2.x/rtpengine#rtpengine.f.rtpengine_delete|rtpengine_delete()]] function:

[@
if (is_method("BYE|CANCEL")) {
rtpengine_delete();
@]

Having done all these settings should provide a full setup for interconnecting SIP clients over both UDP, TCP, etc. protocols, as well as browser based SIP clients over WebSocket.

!!! Configuration file

The following configuration file is a minimal working example of a Residential script that can handle clients connections over both UDP and Websocket transports.

[@
#
# OpenSIPS residential configuration script
# by OpenSIPS Solutions <team@opensips-solutions.com>
#
# Please refer to the Core CookBook at:
# http://www.opensips.org/Resources/DocsCookbooks
# for a explanation of possible statements, functions and parameters.
#


####### Global Parameters #########

debug=3
log_stderror=no
log_facility=LOG_LOCAL0

fork=yes
children=4
auto_aliases=no

listen=udp:127.0.0.0:5060 # TODO: update with your local IP and port
listen=ws:127.0.0.0:8080 # TODO: update with your local IP and port

####### Modules Section ########

# set module path
mpath="/usr/local/lib/opensips/modules/"

#### SIGNALING module
loadmodule "signaling.so"

#### StateLess module
loadmodule "sl.so"

#### Transaction Module
loadmodule "tm.so"
modparam("tm", "fr_timeout", 5)
modparam("tm", "fr_inv_timeout", 30)
modparam("tm", "restart_fr_on_each_reply", 0)
modparam("tm", "onreply_avp_mode", 1)

#### Record Route Module
loadmodule "rr.so"
modparam("rr", "append_fromtag", 0)

#### MAX ForWarD module
loadmodule "maxfwd.so"

#### SIP MSG OPerationS module
loadmodule "sipmsgops.so"

#### FIFO Management Interface
loadmodule "mi_fifo.so"
modparam("mi_fifo", "fifo_name", "/tmp/opensips_fifo")
modparam("mi_fifo", "fifo_mode", 0666)

#### URI module
loadmodule "uri.so"
modparam("uri", "use_uri_table", 0)

#### USeR LOCation module
loadmodule "usrloc.so"
modparam("usrloc", "nat_bflag", "NAT")
modparam("usrloc", "db_mode", 0)

#### REGISTRAR module
loadmodule "registrar.so"

#### RTPengine protocol
loadmodule "rtpengine.so"
modparam("rtpengine", "rtpengine_sock", "udp:127.0.0.0:60000")

#### Nathelper protocol
loadmodule "nathelper.so"
modparam("registrar|nathelper", "received_avp", "$avp(rcv)")

#### UDP protocol
loadmodule "proto_udp.so"

#### WebSocket protocol
loadmodule "proto_ws.so"


####### Routing Logic ########

# main request routing logic
route{
if (!mf_process_maxfwd_header("10")) {
sl_send_reply("483","Too Many Hops");
exit;
}

if (has_totag()) {
# sequential requests within a dialog should
# take the path determined by record-routing
if (loose_route()) {

if (is_method("INVITE")) {
# even if in most of the cases is useless, do RR for
# re-INVITEs alos, as some buggy clients do change route set
# during the dialog.
record_route();
}

# route it out to whatever destination was set by loose_route()
# in $du (destination URI).
route(relay);
} else {

if ( is_method("ACK") ) {
if ( t_check_trans() ) {
# non loose-route, but stateful ACK; must be an ACK after
# a 487 or e.g. 404 from upstream server
t_relay();
exit;
} else {
# ACK without matching transaction ->
# ignore and discard
exit;
}
}
sl_send_reply("404","Not here");
}
exit;
}

# CANCEL processing
if (is_method("CANCEL")) {
if (t_check_trans())
t_relay();
exit;
}

t_check_trans();

if (!is_method("REGISTER")) {
if (from_uri!=myself) {
# if caller is not local, then called number must be local
if (!uri==myself) {
send_reply("403","Rely forbidden");
exit;
}
}
}

# preloaded route checking
if (loose_route()) {
xlog("L_ERR",
"Attempt to route with preloaded Route's [$fu/$tu/$ru/$ci]");
if (!is_method("ACK"))
sl_send_reply("403","Preload Route denied");
exit;
}

# record routing
if (!is_method("REGISTER|MESSAGE"))
record_route();

if (!uri==myself) {
append_hf("P-hint: outbound\r\n");
route(relay);
}

# requests for my domain
if (is_method("PUBLISH|SUBSCRIBE"))
{
sl_send_reply("503", "Service Unavailable");
exit;
}

# check if the clients are using WebSockets
if (proto == WS)
setflag(SRC_WS);

# consider the client is behind NAT - always fix the contact
fix_nated_contact();

if (is_method("REGISTER"))
{
# indicate that the client supports DTLS
# so we know when he is called
if (isflagset(SRC_WS))
setbflag(DST_WS);

fix_nated_register();
if (!save("location"))
sl_reply_error();

exit;
}

if ($rU==NULL) {
# request with no Username in RURI
sl_send_reply("484","Address Incomplete");
exit;
}

# do lookup with method filtering
if (!lookup("location","m")) {
t_newtran();
t_reply("404", "Not Found");
exit;
}

route(relay);
}


route[relay] {
# for INVITEs enable some additional helper routes
if (is_method("INVITE")) {
t_on_branch("handle_nat");
t_on_reply("handle_nat");
} else if (is_method("BYE|CANCEL")) {
rtpengine_delete();
}

if (!t_relay()) {
send_reply("500","Internal Error");
};
exit;
}


branch_route[handle_nat] {

if (!is_method("INVITE") || !has_body("application/sdp"))
return;

if (isflagset(SRC_WS) && isbflagset(DST_WS))
$var(rtpengine_flags) = "ICE=force-relay DTLS=passive";
else if (isflagset(SRC_WS) && !isbflagset(DST_WS))
$var(rtpengine_flags) = "RTP/AVP replace-session-connection replace-origin ICE=remove";
else if (!isflagset(SRC_WS) && isbflagset(DST_WS))
$var(rtpengine_flags) = "UDP/TLS/RTP/SAVPF ICE=force";
else if (!isflagset(SRC_WS) && !isbflagset(DST_WS))
$var(rtpengine_flags) = "RTP/AVP replace-session-connection replace-origin ICE=remove";

rtpengine_offer("$var(rtpengine_flags)");
}


onreply_route[handle_nat] {

fix_nated_contact();
if (!has_body("application/sdp"))
return;

if (isflagset(SRC_WS) && isbflagset(DST_WS))
$var(rtpengine_flags) = "ICE=force-relay DTLS=passive";
else if (isflagset(SRC_WS) && !isbflagset(DST_WS))
$var(rtpengine_flags) = "UDP/TLS/RTP/SAVPF ICE=force";
else if (!isflagset(SRC_WS) && isbflagset(DST_WS))
$var(rtpengine_flags) = "RTP/AVP replace-session-connection replace-origin ICE=remove";
else if (!isflagset(SRC_WS) && !isbflagset(DST_WS))
$var(rtpengine_flags) = "RTP/AVP replace-session-connection replace-origin ICE=remove";

rtpengine_answer("$var(rtpengine_flags)");
}
@]