-
Notifications
You must be signed in to change notification settings - Fork 564
/
README
354 lines (273 loc) · 12.5 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
SIPREC Module
__________________________________________________________
Table of Contents
1. Admin Guide
1.1. Overview
1.2. How it works
1.3. Media Handling
1.4. SRS Failover
1.5. Limitations
1.6. Dependencies
1.6.1. OpenSIPS Modules
1.6.2. External Libraries or Applications
1.7. Exported Parameters
1.7.1. media_port_min (integer)
1.7.2. media_port_max (integer)
1.7.3. skip_failover_codes (string)
1.8. Exported Functions
1.8.1. siprec_start_recording(srs, [group],
[caller], [callee], [rtpproxy_sock],
[media_ip], [headers])
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. Set media_port_min parameter
1.2. Set media_port_max parameter
1.3. Set skip_failover_codes parameter
1.4. Use siprec_start_recording() function with a single SRS
1.5. Use siprec_start_recording() function with multiple SRS
servers
1.6. Use siprec_start_recording() function with custom XML
values for participants
1.7. Use siprec_start_recording() function with custom headers
Chapter 1. Admin Guide
1.1. Overview
This module provides the means to do calls recording using an
external recorder - the entity that records the call is not in
the media path between the caller and callee, but it is
completely separate, thus it can not affect by any means the
quality of the conversation. This is done in a standardized
manner, using the SIPREC Protocol, thus it can be used by any
recorder that implements this protocol.
Since an external server is used to record calls, there are no
constraints regarding the location of the recorder, thus it can
be placed arbitrary. This offers huge flexibility to your
architecture configuration and various means for scaling.
The work for this module has been sponsored by the OrecX
Company. This module is fully integrated with the OrecX Call
Recording products.
1.2. How it works
The full architecture of a SIP Media Recording platform is
documented in RFC 7245. According to this architecture, this
OpenSIPS module implements a SRC (Session Recording Client)
that instructs a SRS (Session Recording Server) when new calls
are started, the participants of the calls and their profiles.
Based on this data, the SRS can decide whether the call should
be recorded or not.
From SIP signalling perspective, the module does not change the
call flow between the caller and callee. The call is
established just as any other calls that are not recorded. But
for each call that has SIPREC engaged, a completely separate
SIP session is started by the SRC (OpenSIPS) towards the SRS,
using the OpenSIPS Back-2-Back module. The INVITE message sent
to the SRS contains a multi-part body consisting of two parts:
* Recording SDP - the SDP of the Media Server that will fork
the RTP to the recorder.
* Participants Metadata - an XML-formatted document that
contains information about the participants. The structure
of the document is detailed in RFC 7865.
The SRS can respond with negative reply, indicating that the
session does not need to be recorded, or with a positive reply
(200 OK), indicating in the SDP body where the media RTP should
be sent/forked. When the call ends, the SRC must send a BYE
message to the SRS, indicating that the recording should be
completed.
Full examples of call flows can be found in RFC 8068.
1.3. Media Handling
Since OpenSIPS is a SIP Proxy, it does not have any Media
Capabilities by itself. Thus we need to rely on a different
Media Server to capture the RTP traffic and fork it to the SRS.
This module currently uses the RTPProxy module in OpenSIPS to
instruct the RTPProxy Media Server to fork the RTP media to the
SRS.
1.4. SRS Failover
The siprec module supports failover between multiple SRS
servers - when calling the siprec_start_recording() function,
one can provision more SRS URIs, separated by comma. In this
case, OpenSIPS will try to use them in the same order
specified, one by one, until either one of them responds with a
positive reply (200 OK), or the response code is one of the
codes matched by the skip_failover_codes regular expression. In
the latter case the call is not recorded at all.
1.5. Limitations
This module only implements the SRC specifications of the
SIPREC RFC. In order to have a full recording solution, you
will also need a SRS solution such as Oreka - an open-source
project provided by OrecX.
Although this module provides all the necessary tools to do
calls recording, it does not fully implement the entire SIPREC
SRC specifications. This list contains some of the module's
limitations:
* There is no Recording Indicator played to the callee -
since OpenSIPS continues to act as a proxy, there is no way
for us to postpone the media between the caller and callee
to play a Recording Indicator message.
* Cannot handle Recording Sessions initiated by SRS - we do
not support the scenario when an SRS suddently decides to
record a call in the middle of the dialog.
* OpenSIPS cannot be “queried” for ongoing recording sessions
- this is scheduled to be implemented in further releases.
1.6. Dependencies
1.6.1. OpenSIPS Modules
The following modules must be loaded before this module:
* TM - Transaction module.
* Dialog - Dialog module for keeping track of the call.
* RTPProxy - RTPProxy module used for controlling the media
forked.
* B2B_ENTITIES - Back-2-Back module used for communicating
with the SRS.
1.6.2. External Libraries or Applications
The following libraries or applications must be installed
before running OpenSIPS with this module loaded:
* None.
1.7. Exported Parameters
1.7.1. media_port_min (integer)
The minimum value of the port used in the SDP sent to the SRS.
This value should correlate to the port-range configured in the
RTPProxy Media Server.
Default value is “35000”.
Example 1.1. Set media_port_min parameter
...
modparam("siprec", "media_port_min", 10000)
...
1.7.2. media_port_max (integer)
The maximum value of the port used in the SDP sent to the SRS.
This value should correlate to the port-range configured in the
RTPProxy Media Server.
Default value is “65000”.
Example 1.2. Set media_port_max parameter
...
modparam("siprec", "media_port_max", 20000)
...
1.7.3. skip_failover_codes (string)
A regular expression used to specify the codes that should
prevent the module from failing over to a new SRS server.
By default any negative reply generates a failover.
Example 1.3. Set skip_failover_codes parameter
...
# do not failover on 408 reply codes
modparam("siprec", "skip_failover_codes", "408")
# do not failover on 408 or 487 reply codes
modparam("siprec", "skip_failover_codes", "408|487")
# do not failover on any 3xx or 4xx reply code
modparam("siprec", "skip_failover_codes", "[34][0-9][0-9]")
...
1.8. Exported Functions
1.8.1. siprec_start_recording(srs, [group], [caller], [callee],
[rtpproxy_sock], [media_ip], [headers])
Calling this function on an initial INVITE engages call
recording to SRS(s) for that call. Note that it does not
necessary mean that the call will be recorded - it just means
that OpenSIPS will query instruct the SRS that a new call has
started, but the SRS might decide that the recording is
disabled for those participants.
Note that the call recording is not started right away, but
only when the call is actually answered - 200 OK is sent by the
callee.
Parameters:
* srs (string) - a comma-separated list of SRS URIs. These
URIs are used in the order specified. See
siprec_srs_failover for more information.
* group (string, optional) - an opaque values used by the
SIPREC protocol to group calls in certain profiles.
* caller (string, optional) - an XML block containing
information about the caller. If absent, the From header is
used to build the value from.
* callee (string, optional) - an XML block containing
information about the callee. If absent, the To header is
used to build the value from.
* rtpproxy_sock (string, optional) - the RTPProxy socket used
for this call. If absent, the rtpproxy module will try to
detect the proxy used for the initial call, based on the
default set provisioned in the rtpproxy module.
* media_ip (string, optional) - the IP that RTPProxy will be
streaming media from. If absent 127.0.0.1 will be used.
* headers (string, optional) - extra headers that are to be
added in the initial request towards the SRS. NOTE: headers
must be separated by \r\n and must end with \r\n.
The function returns false when an internal error is triggered
and the call recording setup fails. Otherwise, if all the
internal mechanisms are activated, it returns true.
This function can be used from REQUEST_ROUTE.
Example 1.4. Use siprec_start_recording() function with a
single SRS
...
if (!has_totag() && is_method("INVITE")) {
$var(srs) = "sip:127.0.0.1";
xlog("Engage SIPREC call recording to $var(srs) for $ci\
n");
siprec_start_recording($var(srs));
}
...
Example 1.5. Use siprec_start_recording() function with
multiple SRS servers
...
if (!has_totag() && is_method("INVITE")) {
$var(srs) = "sip:127.0.0.1, sip:127.0.0.1;transport=TCP"
;
xlog("Engage SIPREC call recording to servers $var(srs)
for $ci in inbound group\n");
siprec_start_recording($var(srs), "inbound");
}
...
Example 1.6. Use siprec_start_recording() function with custom
XML values for participants
...
$xml(caller_xml) = "<nameID></nameID>";
$xml(caller_xml/nameID.attr/aor) = "sip:6024151234@10.0.0.11:509
0";
$xml(caller_xml/nameID) = "<name>test</name>";
siprec_start_recording($var(srs),,$xml(caller_xml/nameID));
...
Example 1.7. Use siprec_start_recording() function with custom
headers
...
siprec_start_recording($var(srs),,,,,,"X-MY-CUSTOM_HDR: 1\r\n");
...
Chapter 2. Contributors
2.1. By Commit Statistics
Table 2.1. Top contributors by DevScore^(1), authored
commits^(2) and lines added/removed^(3)
Name DevScore Commits Lines ++ Lines --
1. Razvan Crainea (@razvancrainea) 92 49 3636 737
2. Vlad Patrascu (@rvlad-patrascu) 14 9 159 138
3. Liviu Chircu (@liviuchircu) 8 6 27 50
4. Norman Brandinger (@NormB) 3 1 4 4
5. Bogdan-Andrei Iancu (@bogdan-iancu) 3 1 2 1
(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
Table 2.2. Most recently active contributors^(1) to this module
Name Commit Activity
1. Razvan Crainea (@razvancrainea) Jun 2017 - Aug 2022
2. Norman Brandinger (@NormB) Aug 2021 - Aug 2021
3. Vlad Patrascu (@rvlad-patrascu) Feb 2018 - Jul 2021
4. Liviu Chircu (@liviuchircu) Apr 2018 - Nov 2019
5. Bogdan-Andrei Iancu (@bogdan-iancu) Apr 2019 - Apr 2019
(1) including any documentation-related commits, excluding
merge commits
Chapter 3. Documentation
3.1. Contributors
Last edited by: Norman Brandinger (@NormB), Razvan Crainea
(@razvancrainea), Vlad Patrascu (@rvlad-patrascu), Liviu Chircu
(@liviuchircu).
Documentation Copyrights:
Copyright © 2017 www.opensips-solutions.com