|
|
@@ -10,7 +10,13 @@ Daniel-Constantin Mierla
|
|
|
|
|
|
<[email protected]>
|
|
|
|
|
|
- Copyright © 2012 asipto.com
|
|
|
+Edited by
|
|
|
+
|
|
|
+Alex Balashov
|
|
|
+
|
|
|
+ <[email protected]>
|
|
|
+
|
|
|
+ Copyright © 2012 asipto.com
|
|
|
__________________________________________________________________
|
|
|
|
|
|
Table of Contents
|
|
|
@@ -84,33 +90,33 @@ Chapter 1. Admin Guide
|
|
|
1. Overview
|
|
|
|
|
|
This module provides a MSRP routing engine, a.k.a. MSRP relay. MSRP
|
|
|
- (Message Session Relay Protocol) is defined by RFC4975, the extensions
|
|
|
- for a MSRP Relay being covered in RFC4976.
|
|
|
-
|
|
|
- A typical use of MSRP is to do Instant Messaging sessions initiated via
|
|
|
- SIP. Unlike page-mode instant messaging, which is done via SIP request
|
|
|
- MESSAGE, MSRP uses a different communication channel, which is
|
|
|
- negotiated via INVITE-200OK-ACK.
|
|
|
-
|
|
|
- However, MSRP is still a text based protocol, using several routing
|
|
|
- mechanisms which are similar with what exists in SIP. Furthermore, MSRP
|
|
|
- requres TCP (and recommends TLS for confidentiality and security).
|
|
|
- Considering scalability and perormances of Kamailio for handling
|
|
|
- TCP/TLS, this module reuses Kamailio's core framework to offer MSRP
|
|
|
- routing capabilities. Along with embedded Presence and XCAP servers,
|
|
|
- Kamailio offers now a complete solution for SIP beyond VoIP.
|
|
|
-
|
|
|
- One of the main benefits with the new module, is the ability to reuse
|
|
|
- all the other extensions that exist in the SIP server, from accounting,
|
|
|
+ (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 requres
|
|
|
+ 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
|
|
|
+ offers now 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
|
|
|
- attacks protections.
|
|
|
+ attack protections.
|
|
|
|
|
|
- Kamailio can handle SIP and MSRP traffic received on the same port, the
|
|
|
+ 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 have an instance handling both SIP and MSRP. Another option is to
|
|
|
- configure Kamailio to listen on multiple ports, some of them being used
|
|
|
- for SIP and others for MSRP.
|
|
|
+ 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
|
|
|
|
|
|
@@ -135,8 +141,8 @@ Chapter 1. Admin Guide
|
|
|
3.1. sipmsg (int)
|
|
|
|
|
|
If 1, the module will build a SIP message from MSRP frame headers,
|
|
|
- providing it to event_route[msrp:frame-in]. The all the config file
|
|
|
- functions (apart of SIP request relaying) that can be used in a request
|
|
|
+ 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 msrp event_route.
|
|
|
|
|
|
Default value is '1'.
|
|
|
@@ -156,12 +162,12 @@ modparam("msrp", "sipmsg", 1)
|
|
|
4.6. msrp_relay_flags(flags)
|
|
|
4.7. msrp_reply_flags(flags)
|
|
|
|
|
|
-4.1. msrp_relay()
|
|
|
+4.1. msrp_relay()
|
|
|
|
|
|
- Relay MSRP frame according to To-Path. It has to be executed for each
|
|
|
- MSRP request or reply that has to be forwarded. Note that due to nature
|
|
|
- of MSRP transport layer which is reliable (TCP/TLS), there is no
|
|
|
- retransmission of MSRP frames.
|
|
|
+ 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 MSRP transport layer, which is reliable
|
|
|
+ (TCP/TLS), there is no retransmission of MSRP frames.
|
|
|
|
|
|
This function can be used in ANY_ROUTE.
|
|
|
|
|
|
@@ -172,11 +178,11 @@ event_route[msrp:frame-in] {
|
|
|
}
|
|
|
...
|
|
|
|
|
|
-4.2. msrp_reply(code, text [, hdrs])
|
|
|
+4.2. msrp_reply(code, text [, hdrs])
|
|
|
|
|
|
- Send a reply for current MSRP request, adding optional headers.
|
|
|
+ Send a reply for the current MSRP request, adding optional headers.
|
|
|
|
|
|
- The parameter can be pseudo-variable.
|
|
|
+ The parameter can be a pseudo-variable.
|
|
|
|
|
|
This function can be used in ANY_ROUTE.
|
|
|
|
|
|
@@ -187,7 +193,7 @@ event_route[msrp:frame-in] {
|
|
|
}
|
|
|
...
|
|
|
|
|
|
-4.3. msrp_is_request()
|
|
|
+4.3. msrp_is_request()
|
|
|
|
|
|
Return true if the MSRP frame is a request.
|
|
|
|
|
|
@@ -204,7 +210,7 @@ event_route[msrp:frame-in] {
|
|
|
}
|
|
|
...
|
|
|
|
|
|
-4.4. msrp_is_reply()
|
|
|
+4.4. msrp_is_reply()
|
|
|
|
|
|
Return true if the MSRP frame is a reply.
|
|
|
|
|
|
@@ -221,12 +227,12 @@ event_route[msrp:frame-in] {
|
|
|
}
|
|
|
...
|
|
|
|
|
|
-4.5. msrp_set_dst(addr, sock)
|
|
|
+4.5. msrp_set_dst(addr, sock)
|
|
|
|
|
|
Set destination attributes: addr - target address as MSRP URI; sock -
|
|
|
local socket to be used (format 'proto:ip:port').
|
|
|
|
|
|
- The parameter can be pseudo-variable.
|
|
|
+ The parameter can be a pseudo-variable.
|
|
|
|
|
|
This function can be used in ANY_ROUTE.
|
|
|
|
|
|
@@ -239,13 +245,13 @@ event_route[msrp:frame-in] {
|
|
|
}
|
|
|
...
|
|
|
|
|
|
-4.6. msrp_relay_flags(flags)
|
|
|
+4.6. msrp_relay_flags(flags)
|
|
|
|
|
|
Set transport layer sending flags for forwarding current MSRP frame;
|
|
|
flags - a bitmask of flags - 1 (don't create a new connection), 2
|
|
|
(close connection after send).
|
|
|
|
|
|
- The parameter can be pseudo-variable.
|
|
|
+ The parameter can be a pseudo-variable.
|
|
|
|
|
|
This function can be used in ANY_ROUTE.
|
|
|
|
|
|
@@ -258,13 +264,13 @@ event_route[msrp:frame-in] {
|
|
|
}
|
|
|
...
|
|
|
|
|
|
-4.7. msrp_reply_flags(flags)
|
|
|
+4.7. msrp_reply_flags(flags)
|
|
|
|
|
|
- Set transport layer sending flags for replies to current MSRP frame;
|
|
|
- flags - a bitmask of flags - 1 (don't create a new connection), 2
|
|
|
- (close connection after send).
|
|
|
+ Set transport layer sending flags for replies to the current MSRP
|
|
|
+ frame; flags - a bitmask of flags - 1 (don't create a new connection),
|
|
|
+ 2 (close connection after send).
|
|
|
|
|
|
- The parameter can be pseudo-variable.
|
|
|
+ The parameter can be a pseudo-variable.
|
|
|
|
|
|
This function can be used in ANY_ROUTE.
|
|
|
|
|
|
@@ -279,14 +285,14 @@ event_route[msrp:frame-in] {
|
|
|
|
|
|
5. Pseudo Variables
|
|
|
|
|
|
- The module exports a pseudo-variables class $msrp(key) to access the
|
|
|
- MSRP frame (e.g., first line attributes, body, all frame content).
|
|
|
+ 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 be able to
|
|
|
- access attributes of a MSRP URI.
|
|
|
+ The module exports a transformations class, 'msrpuri', to allow access
|
|
|
+ attributes of a MSRP URI.
|
|
|
|
|
|
- These are documented in the appropriate Wiki pages hosted by the
|
|
|
- project's web site.
|
|
|
+ These are documented in the appropriate Wiki pages hosted on the
|
|
|
+ project web site.
|
|
|
|
|
|
6. Event Routes
|
|
|
|
|
|
@@ -296,13 +302,13 @@ event_route[msrp:frame-in] {
|
|
|
7. Usage
|
|
|
|
|
|
When 'sipmsg' parameter is set to 1 (which is default), the module
|
|
|
- builds internally a SIP request from the MSRP frame and gives it to the
|
|
|
- config file interpreter, in this way all the functions that are valid
|
|
|
- for SIP requests can be used safe in event_route[msrp:frame-in].
|
|
|
+ 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, msrp module takes the first line and the
|
|
|
- headers from a MSRP message and appends to a static buffer. Next two
|
|
|
- examples show a MSRP frame and the resulted SIP request.
|
|
|
+ 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.
|
|
|
...
|
|
|
MSRP 6aef SEND
|
|
|
To-Path: msrps://a.example.org:9000/kjfjan;tcp \
|
|
|
@@ -338,20 +344,20 @@ Content-Type: text/plain
|
|
|
...
|
|
|
|
|
|
Note that MSRP does not permit line folding. A "\" in the examples
|
|
|
- shows a line continuation due to limitations in line length of this
|
|
|
+ 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 it can be observed, the MSRP frame content starts with the body of
|
|
|
- header 'MSRP-First-Line:'. Using a static content to get to a valid SIP
|
|
|
- request is a perfect trade off for performances.
|
|
|
+ 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 internally build
|
|
|
- SIP message, msrp 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 a MSRP URI.
|
|
|
- See the appropriate Wiki pages on the project's web site for full
|
|
|
- details about new pseudo-variable and transformation classes.
|
|
|
+ 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.
|
Alex Balashov - Diminuendo-2