-
Notifications
You must be signed in to change notification settings - Fork 564
/
README
341 lines (256 loc) · 11.7 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
RTP Relay Module
__________________________________________________________
Table of Contents
1. Admin Guide
1.1. Overview
1.2. Multiple Branches
1.3. Dependencies
1.3.1. OpenSIPS Modules
1.3.2. External Libraries or Applications
1.4. Exported Functions
1.4.1. rtp_relay_engage(engine, [set])
1.5. Exported MI Functions
1.5.1. rtp_relay_list
1.5.2. rtp_relay_update
1.5.3. rtp_relay_update_callid
1.6. Exported Pseudo-Variables
1.6.1. $rtp_relay
1.6.2. $rtp_relay_peer
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. rtp_relay_engage usage
1.2. rtp_relay_list usage
1.3. rtp_relay_update usage
1.4. rtp_relay_update_callid usage
Chapter 1. Admin Guide
1.1. Overview
The purpose of this module is to simplify the usage of
different RTP Relays Servers (such as RTPProxy, RTPEngine,
Media Proxy) in OpenSIPS scripting, as well as to provide
various complex features that rely on the usage of RTP relays
(such as media re-anchoring).
The module provides the logic to engage a specific RTP relay in
a call during initial INVITE, and then it will handle the
entire communication with the RTP relay, until the call
terminates.
Moreover, one can specify various flags that modify the way RTP
engines use each user agent's SDP - these flags are persistent
throughout the entire RTP session, and are being used for
further in-dialog requests. These flags can be specified
through the $rtp_relay and/or $rtp_relay_peer variables at
initial INVITE, and are then passed along with the RTP relay
context until the end of the call. They can also be modified
during sequential in-dialog requests.
This is not a stand-alone module that communicates directly
with RTP relays, but rather a generic interface that is able to
interact with the modules that interact with each specific RTP
Relay (such as rtpproxy or rtpengine) and implement their
specific communication protocol.
1.2. Multiple Branches
The module is able to handle RTP relay for multiple branches,
with different flags flavors. Each branch can have its flags
tuned through the $rtp_relay variable - if the variable is
provisioned in the main route, then the flags are inherited by
all further branches, unless specifically modified per branch.
To modify a specific branch, one needs to specify the desired
branch index as variable index (i.e. $(rtp_relay[1]) = "cor").
When provisioned in a branch route, the flags are only changed
for that specific branch.
The multiple branches behavior is handled differently by the
back-end engine, depending on its capabilities. For example,
rtpengine is able to natively support calls with multiple
branches, whereas for rtpproxy, each branch is emulated in a
different session with a different call-id.
When the call gets answered and a single branch remains active,
all the other branches are destroyed and only the established
branches remain active throughout the call.
1.3. Dependencies
1.3.1. OpenSIPS Modules
The following modules must be loaded before this module:
* Dialog module - used to keep track of in-dialog requests.
* RTP Relay module(s) - such rtpproxy, or rtpengine, or any
module that implements the rtp_relay interface.
1.3.2. External Libraries or Applications
The following libraries or applications must be installed
before running OpenSIPS with this module loaded:
* None.
1.4. Exported Functions
1.4.1. rtp_relay_engage(engine, [set])
Engages the RTP Relay engine for the current initial INVITE.
After calling this function, the entire RTP relay communication
will be handled by the module itself, without having to
intervene for any further in-dialog requests/replies (unless
you specifically want to).
The function is not performing the media requests on the spot,
but rather registers the hooks to automatically handle any
further media requests.
The RTP session modifiers used are the ones provisioned through
the $rtp_relay and/or $rtp_relay_peer variables.
The function can be called from the main request route - in
this case the RTP relay will be engaged for any further
branches created, or from the branch route - in this case the
RTP relay will only be engaged for the branch where it was
called, or that has an associated rtp_relay provisioned.
Meaning of the parameters is as follows:
* engine(string) - the RTP relay engine to be used for the
call (i.e. rtpproxy.
* set(int, optional) - the set used for this call.
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
BRANCH_ROUTE.
Example 1.1. rtp_relay_engage usage
...
if (is_method("INVITE") && !has_totag()) {
xlog("SCRIPT: engaging RTPProxy relay for all branches\n");
$rtp_relay = "co";
$rtp_relay_peer = "co";
rtp_relay_engage("rtpproxy");
}
...
1.5. Exported MI Functions
1.5.1. rtp_relay_list
Lists all the RTP Relay sessions engaged.
Parameters:
* engine - (optional) the RTP relay engine (i.e. rtpproxy or
rtpengine).
* set - (optional) the RTP relay set. When used, the engine
parameter must also be specified.
* node - (optional) the RTP relay node. When used, the engine
parameter must also be specified.
Example 1.2. rtp_relay_list usage
...
## list all sessions
$ opensips-cli -x mi rtp_relay_list
## list all sessions going through a specific RTP node
$ opensips-cli -x mi rtp_relay_list rtpproxy udp:127.0.0.1:2222
...
1.5.2. rtp_relay_update
Updates/Re-engages the RTP relays in all ongoing RTP relay
sessions.
This function can be used to trigger dialog in-dialog updates
for certain ongoing RTP sessions. For all matched sessions, it
re-engages an RTP Relay offer/answer session, then sends
re-INVITEs to call's participants to with the updated SDP.
Note:Running the command without a filter (such as engine or
set) will cause all RTP relay sessions to be re-engaged.
Note:When enforcing a new node, it is not guaranteed to be used
- if the node is not avaialble, but a different one is, the
active one will be chosen.
Note:If the node is being changed, the module tries to unforce
the previous RTP relay session, even though it might not work.
Parameters:
* engine - (optional) the RTP relay engine (i.e. rtpproxy or
rtpengine) to be used as filter.
* set - (optional) the RTP relay set to be used as filter. If
missing, the same set will be used as it was initially
engaged for.
* node - (optional) the RTP relay node to be used as filter.
* new_set - (optional) a new RTP Relay set to be used for the
call.
* new_node - (optional) a new RTP node to be used for the
call. If new_set is missing, the same set will be used.
Example 1.3. rtp_relay_update usage
...
## update all sessions that are using rtpproxy
$ opensips-cli -x mi rtp_relay_update rtpproxy
...
1.5.3. rtp_relay_update_callid
Updates/Re-engages the RTP relays in all ongoing RTP relay
sessions.
The function basically works in the same manner as
rtp_relay_update, but is to be used to update a specific
callid. In addition, one can also update the engine and flags
used for the particular session.
Parameters:
* callid - the callid used to match the dialog to be updated.
* engine - (optional) the new RTP relay engine (i.e. rtpproxy
or rtpengine) to be used. If missing, the same initial
engine is used.
* set - (optional) the new RTP relay set to be used. If
missing, the default same set will be used as it was
initially engaged for.
* node - (optional) the RTP relay node to be used. If not
specified, the first available node is used.
* flags - (optional) a JSON contining the caller and/or
callee nodes, which contain new flags that should be used
for the session. Only explicitely specified flags will be
overwritten.
Example 1.4. rtp_relay_update_callid usage
...
## update a call with a working RTPproxy node
$ opensips-cli -x mi rtp_relay_update_callid 1-3758963@127.0.0.1 rtpprox
y
## update a call to use RTPEngine with a SRTP SDP for caller
$ opensips-cli -x mi rtp_relay_update_callid callid=1-3758963@127.0.0.1
\
flags='{ "caller":{"type":"SRTP", "flags":"replace-origin"},
"callee":{"type":"RTP", "flags"="replace-origin"}}'
...
1.6. Exported Pseudo-Variables
1.6.1. $rtp_relay
Is used to provision the RTP back-end flags for the current
peer - if used in the initial INVITE REQUEST/BRANCH route, it
provisions the flags of the caller, whereas if used in the
initial INVITE REPLY, it provisions the callee's flags.
For a sequential request, the variable represents the flags
used for the UAC that generated the request. When used in a
reply, the other UAC's flags are provisioned.
In an initial INVITE scope, the variable can be provisioned per
branch, by using the variable's index.
For each UAC/peer, there are several flags that can be
configured:
* flags (default, when variable is used without a name) - are
the flags associated with the current UAC - they are passed
along with the offer command
* peer - these flags are passed along in the offer command,
but they are flags associated with the other UAC/peer
* ip - the IP that should be advertised in the resulted SDP
(currently only used by rtpproxy)
* type - the RTP type used by the current UAC (currently only
used by rtpengine)
* iface - the interface used for the traffic coming from this
UAC.
* disabled - provisioned as an integer, it is used to disable
RTP relay for this UAC.
1.6.2. $rtp_relay_peer
This variable has the same meaning and parameters as the
$rtp_relay variable, except that it is used to provision the
other UAC's flags, except the current one. All other fields are
similar.
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) 68 36 3087 308
(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) Apr 2021 - Aug 2022
(1) including any documentation-related commits, excluding
merge commits
Chapter 3. Documentation
3.1. Contributors
Last edited by: Razvan Crainea (@razvancrainea).
Documentation Copyrights:
Copyright © 2021 OpenSIPS Solutions