1. Overview

This module provides a MSRP routing engine, a.k.a. MSRP relay.
MSRP (Message Session Relay Protocol) is defined by RFC4975,
and the extensions for an MSRP relay are covered in RFC4976.

A typical use of MSRP is instant messaging sessions initiated
via SIP. Unlike page-mode instant messaging, which is done via the SIP
MESSAGE request, MSRP uses a different communication channel which
is negotiated via INVITE-200 OK-ACK.

However, MSRP is still a text-based protocol. It uses several routing
mechanisms similar to what exists in SIP. Furthermore,
MSRP requires TCP, and recommends TLS for confidentiality and security.
In light of the scalability and performance of Kamailio in handling
TCP/TLS, this module reuses Kamailio's core framework to
offer MSRP routing capabilities. Along with embedded Presence and XCAP
servers, Kamailio now offers a complete solution for SIP beyond VoIP.

One of the main benefits of this module is the ability to reuse
all the other extensions that exist in the SIP server, including
accounting, authentication, authorization to database connectors,
security and DoS attack protections.

Kamailio can handle SIP and MSRP traffic received on the same port;
the appropriate configuration file block being executed based on the
type of message. Therefore, you can use Kamailio as a stand-alone
MSRP relay or you can have an instance handling both SIP and MSRP. Another
option is to configure Kamailio to listen on multiple ports, some
of them for SIP and others for MSRP.

2. Dependencies

2.1. Kamailio Modules

The following modules must be loaded before this module:

None.

The following modules are required to make proper use of this
module:

tls.

2.2. External Libraries or Applications

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

None

3. Parameters

3.1. sipmsg (int)

If set to 1, the module will build a SIP message from MSRP frame headers,
providing it to “event_route[msrp:frame-in]”.
All the config file functions (apart from SIP request relay) that can be used
in a request route block can be used in the MSRP event_route.

Default value is '1'.

Example 1.1. Set sipmsg parameter

...
modparam("msrp", "sipmsg", 1)
...

3.2. cmap_size (int)

The size of connection map table, to be computed as power of 2 (e.g.,
if the value is 4, then the number of slots in map table is 2^4 = 16).

Default value is '0' (no internal map table to be used).

Example 1.2. Set cmap_size parameter

...
modparam("msrp", "cmap_size", 8)
...

3.3. timer_interval (int)

The timer interval in seconds to run the procedure for cleaning
expired connections.

Default value is '60'.

Example 1.3. Set timer_interval parameter

...
modparam("msrp", "timer_interval", 90)
...

3.4. auth_min_expires (int)

The minimum value accepted for the “Expires” header in AUTH requests.

Default value is '60'.

Example 1.4. Set auth_min_expires parameter

...
modparam("msrp", "auth_min_expiresl", 90)
...

3.5. auth_max_expires (int)

The maximum value accepted for “Expires” header in AUTH requests.

Default value is '3600'.

Example 1.5. Set auth_max_expires parameter

...
modparam("msrp", "auth_max_expiresl", 1800)
...

3.6. use_path_addr (str)

The hostname:port to be used when building the Path header.

Default value is NULL (server IP and port are used).

Example 1.6. Set use_path_addr parameter

...
modparam("msrp", "use_path_addr", "msrp.kamailio.org:5061")
...

3.7. event_callback (str)

The name of the function in the kemi configuration file (embedded
scripting language such as Lua, Python, ...) to be executed instead
of event_route[...] blocks.

The function receives a string parameter with the name of the event,
the values can be: 'msrp:frame-in'.

4. Functions

4.1.
msrp_relay()

Relay MSRP frame according to the To-Path. This function has to be
executed for each MSRP request or reply that has to be forwarded. Note
that due to nature of the MSRP transport layer, which is reliable
(TCP/TLS), there is no retransmission of MSRP frames.

5. Pseudo Variables

The module exports a pseudo-variable class, $msrp(key), to access
the MSRP frame (e.g. first line attributes, body, all frame
content).

The module exports a transformations class, 'msrpuri', to allow
access attributes of a MSRP URI.

These are documented in the appropriate Wiki pages hosted on the
project web site.

6. RPC Commands

6.1.
msrp.cmaplist

List active MSRP connections.

Example:

...
kamcmd msrp.cmaplist
...

7. Event Routes

For each MSRP frame received from the network, the module executes
event_route[msrp:frame-in] block in the config file.

8. Usage

When the sipmsg parameter is set to 1 (which is the
default), the module internally builds a SIP request from the MSRP frame
and exposes it to the config file interpreter. This way, all the functions
that are valid for SIP requests can be used safely in event_route[msrp:frame-in].

To build the SIP request, the module takes the first line and the
headers from an MSRP message and appends them to a static buffer. The
next two examples show an MSRP frame and the resulting SIP request.

Note that MSRP does not permit line folding. A "\" in the examples
shows a line continuation due to the limitations of line length of this
document. Neither the backslash nor the extra CRLF is included in
the actual request or response.

As can be observed, the MSRP frame content starts with the body
of the 'MSRP-First-Line:' header. Using static content to get to a
valid SIP request is a perfect trade-off for performance.

Besides the option to access parts of MSRP frame via an
internally-built SIP message, the module exports a new pseudo-variable
class $msrp(key) which returns attributes from the MSRP frame. There is
also a new transformation, {msrpuri.key}, to get access to parts
of an MSRP URI. See the appropriate Wiki pages on the project's
web site for full details about new pseudo-variable and
transformation classes.

Next is an example of configuration file with the routing block
for MSRP frames. In this config, the SIP traffic is rejected.