The [[https://tools.ietf.org/html/rfc7865|SIPREC]] protocol consists of a set of metadata information about the participants of the call. By default, OpenSIPS takes those participants from the @@From@@ and @@To@@ headers. However, if the received message contains a DID, or an alias of the User, you do not want to forward that information, but the actual account. You can tune this information in the 3rd and 4th parameters of the @@siprec_start_recording()@@ function. The format of these parameters is a @@name-addr@@ as specified by the [[https://tools.ietf.org/html/rfc3261|SIP RFC]], followed by the @@\r\n@@ header termination. Here is an example:

[@
$var(caller) = "\"John Doe\" <sip:john@opensips.org>\r\n";
$var(callee) = "\"Jane Doe\" <sip:jane@opensips.org>\r\n";
siprec_start_recording("sip:127.0.0.1:5060;transport=tcp",, "$var(caller)", "$var(callee)");
@]

One can also group the calls recorded based on a tag (group as specified in the [[https://tools.ietf.org/html/rfc7865|SIPREC RFC]]). This is done by the second parameter of the @@siprec_start_recording()@@ function:

[@
siprec_start_recording("sip:127.0.0.1:5060;transport=tcp", "regular", "$var(caller)", "$var(callee)");
@]

!!!! SRS Fail-over

There might be cases when a SRS might be down, or cannot be reachable, and you want to fail-over to a different server. This can be achieved by enlisting all the servers in the first parameter of the @@siprec_start_recording()@@ function, separated by comma. The following example tries to connect to the SRS over TCP, and if that fails, it tries to reach it over UDP:

[@
siprec_start_recording("sip:127.0.0.1:5060;transport=tcp, sip:127.0.0.1:5060");
@]

By default, fail-over is driven by a negative response from the SRS, or by an auto-generated 408 if the SRS does not respond. However, not all responses mean the service is unavailable, some of them might simply indicate that the call should not recorded. In this case, you might want to ignore some response codes from the fail-over algorithm. This is done using the [[http://www.opensips.org/html/docs/modules/2.4.x/siprec#skip_failover_codes|skip_failover_codes]] parameter. The following example prevents fail-over for any class 3 and 4 response codes - thus it only fails-over 5xx and 6xx classes:

[@
modparam("siprec", "skip_failover_codes", "[34][0-9][0-9]")
@]

The work for the [[ http://www.opensips.org/html/docs/modules/2.4.x/siprec.html | SIPREC ]] module has been sponsored by the [[http://www.orecx.com/|OrecX Company]].

!!! Basic Configuration

!!! Advanced Configuration

After these changes you can reliably communicate with your SRS Recorder over TCP.

In real scenarios, you might want to put the communication with SRS on a separate/dedicated IP in a local LAN. In order to do this, you need to also specify the desired interface to OpenSIPS, by forcing the communication socket before engaging siprec:
[@
force_send_socket(tcp:127.0.0.1:5060);
siprec_start_recording("sip:127.0.0.1:5060;transport=tcp");
force_send_socket(udp:127.0.0.1:5060); # restore the initial interface
@]

"""Note""" that after forcing the SRS interface, you need to restore the initial interface, otherwise OpenSIPS will try to reach the callee using the dedicated interface.

In the initial scenario we used the @@rtpproxy_engage@@ function, which blindly handles the RTPProxy media proxy. However, in practice, you need to make some fine tuning to the flags passed to the RTPProxy server, such as whether it should trust the IP in the SDP, whether it should act as an asymmetric proxy, etc. This means that you will probably need to use the @@rtpproxy_offer@@/@@rtpproxy_answer@@ combination. This will work perfectly fine and there are no restrictions regarding the order of the @@rtpproxy_offer@@ and @@siprec_start_recording@@ calls.

However, if you configuration runs in a more advanced setup, where you are using RTPProxy sets, you need to make sure that you are providing the same set to SIPREC as well, otherwise recording will fail. So for example if you are using set """5""" for a specific group of users, you will also have to specify it in the 5th parameter of @@siprec_start_recording@@. A configration example is below:

[@
rtpproxy_offer(,,"5");
siprec_start_recording("sip:127.0.0.1:5060;transport=tcp",,,,"5");
@]

!!!! Communicate with SRS over TCP

Although UDP communication is lightweight and the base protocol for SIP, in practice it has a big limitation: it cannot always carry large packets of data. This is SIPREC's case: when adding large SDP payloads, combined with large XML data, to a SIP overhead, you will definitely exceed the MTU (which is usually 1500 bytes), and you end up fragmenting the package. Unfortunately IP fragmentation makes a lot of routers unhappy, thus we might want to use a different method to communicate with the SRS. Luckily, we can achieve this by using TCP.

To do so, we need to make three extra changes to our previous script:

* import the '''proto_tcp''' module, that handles the communication to a TCP endpoint
[@loadmodule "proto_tcp.so"@]

* add a TCP listener - an interface which OpenSIPS will use to communicate to the SRS over TCP
[@listen = tcp:127.0.0.1:5060@]

* change the SRS URI, adding the @@;transport=tcp@@ parameter
[@siprec_start_recording("sip:127.0.0.1:5090;transport=tcp");@]

After these changes you can reliably communicate with your SRS Recorder.

!!!! Use a specific interface to communicate with SRC

!!!! Advanced RTPProxy configuration

!!!! Changing Call Participants Metadata

!!!! SRS Failover

* instruct the SIPREC module that this call is intended to be recorded - we need to provision the SIP URI of the SRS - in this simple scenario, we will consider the SRS is located on the same machine as '''OpenSIPS''', but it is listening on port 5090.

siprec_start_recording("sip:127.0.0.1:5090");

You can find here the final [[http://opensips.org/pub/opensips-scripts/2017/opensips-siprec.cfg |configuration]] example.

!!! Configuration

We will start from an existing working setup for OpenSIPS and gradually add the necessary parts to it until we end up with a working Call Recording script. We will use '''OpenSIPS 2.4''' [[ https://github.com/OpenSIPS/opensips/blob/master/etc/opensips.cfg | default script ]], which provides basic call routing for clients.

The first thing we need to do is load the necessary modules involved:

* '''dialog''': used to keep track of the call status and close the recording when the call ends. It is also needed to handle sequential messages.
* '''b2b_entities''': automatically manages the SIPREC session to the SRS
* '''siprec''': provides the call recording logic
* '''rtpproxy''': used to proxy media and fork RTP traffic to the SRS

So at the beginning section of our script, we need to add the following lines:

[@
loadmodule "dialog.so"
loadmodule "b2b_entities.so"
loadmodule "siprec.so"
loadmodule "rtpproxy.so"
@]

We also need to specify the connector to the RTPProxy server:

[@
modparam("rtpproxy", "rtpproxy_sock", "udp:127.0.0.1:7899")
@]

Now we need to "identify" the calls we want to do call recording for. This can be done using whatever logic you want in your script, but for simplicity in this example, we will engage call recording for all users. To do this, we need to find in our script the code's section that handles the initial INVITEs. In the default script, this is done in the following snippet:

[@
# account only INVITEs
if (is_method("INVITE")) {

do_accounting("log");
}
@]

In this code section, we need to do 3 things:

* create the dialog, to manage the call - you can use any flags to modify the behavior - for simplicity we will use the default behavior.
* engage RTPProxy in the call - again, for simplicity, we will use the auto-mode @@rtpproxy_engage@@ provides.
* instruct the SIPREC module that this call is intended to be recorded - we need to provision the SIP URI of the SRS - in this simple scenario, we will consider the SRS is located on the same machine with '''OpenSIPS'''

After all these changes, the previous snippet will look like this:

[@
# account only INVITEs
if (is_method("INVITE")) {
create_dialog();
rtpproxy_engage();
siprec_start_recording("sip:127.0.0.1");
do_accounting("log");
}
@]

And that's all! All you need to do is start '''OpenSIPS''' with the new script and make a call test.

You can find here the final [[TODO |configuration]] example.

!!! Advanced Topics

* changing metadata
* different rtpproxy set, offer/answer
* force send socket over TCP
* failover

!!! Configuration

We will use as an example the '''OpenSIPS 2.4''' default script, and gradually add components to it until we end up with a working example.

The purpose of this article is to show how one can record a call between two clients, let's call them '''Alice''' and '''Bob'''. In order to do that, we need the following components:

* '''Oreka''' - will act as a SRS, doing the actual recording of the call

The following diagram shows the setup and how each component interact to each other:

http://opensips.org/pub/images/siprec-architecture.png

According to the diagram, '''Alice''' and '''Bob''' do not need to have any recording capabilities (although the SIPREC protocol also supports this model, but it is not part of this article). They will simply behave as a regular SIP client, sending SIP traffic to the '''OpenSIPS''' proxy and the RTP media to a Media Server, in our case, '''RTPProxy'''. However, when a new call is started, '''OpenSIPS''' needs to start a SIPREC session to the SRS, providing it metadata description of '''Alice''' and '''Bob''', as well as media description in the SDP. At this point, the SRS decides whether the call is indeed intended to be recorded - if it is not, it simply rejects the call, otherwise, it sends a 200 OK, containing the SDP where to fork the media. Upon receiving this information, '''OpenSIPS''' instructs '''RTPProxy''' to start forking the clients' RTP traffic to the SRS. When the call is ended, '''OpenSIPS''' needs to also close the SIPREC session with the SRS.

In this article we will only discuss about how '''OpenSIPS''' can be used to record calls using the SIPREC protocol. We will not address the SRS and RTPProxy configuration, but these should already work with the basic/default config.

!!! Configuration

This document describes the steps to configure '''OpenSIPS''' to engage one (or more) SRS recorder(s) in an ongoing call.

!!! Architecture

In order to setup call recording using SIPREC, we need three components:

* '''OpenSIPS''' - will act as a SRC, providing metadata about the call to the SRS
* '''Oreka'''- will act as a SRS, doing the actual recording of the call
* '''RTPProxy''' - will fork the RTP traffic to the SRS

Here is a small diagram of the call flows:

http://opensips.org/pub/images/siprec-architecture.png

!!!!! Documentation -> [[Documentation.Tutorials | Tutorials ]] -> [[ http://www.opensips.org/html/docs/modules/2.4.x/siprec.html | {+Call Recording+} ]] using OpenSIPS and SIPREC
This page has been visited {$PageCount} times.
(:toc-float Table of Content:)
----

!!! Tutorial Overview

[[https://tools.ietf.org/html/rfc7866|SIPREC]] is a standard that specifies how to do call recording in a non-intrusive way, using an external recorder. Using this protocol you can move the call recording features out of your media server to one (or many) other recorder(s), without interfering with the actual RTP flow.
According to the [[https://tools.ietf.org/html/rfc7245|SIPREC architecture]], in order to record a call, you need two components:

* SRC (Session Recording Client) - this is the SIP component in the call's path which triggers the call recording - this is where '''OpenSIPS''' gets involved.
* SRS (Session Recording Server) - this is the actual recorder, the SIP component that only receives the traffic forked by the SRC and dumps it in a file - an example of a SRS is [[http://oreka.sourceforge.net/|Oreka]], an Open Source Enterprise Telephony Recording provided by [[http://www.orecx.com/|OrecX]].

This document describes the steps to configure '''OpenSIPS''' to engage one (or more) SRS recorder(s) in an ongoing call.