-
Notifications
You must be signed in to change notification settings - Fork 564
/
README
513 lines (386 loc) · 15.8 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
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
B2B_ENTITIES
__________________________________________________________
Table of Contents
1. Admin Guide
1.1. Overview
1.2. Dependencies
1.2.1. OpenSIPS Modules
1.2.2. External Libraries or Applications
1.3. Exported Parameters
1.3.1. server_hsize (int)
1.3.2. client_hsize (int)
1.3.3. script_req_route (str)
1.3.4. script_reply_route (str)
1.3.5. db_url (str)
1.3.6. update_period (int)
1.3.7. b2b_key_prefix (string)
1.3.8. db_mode (int)
1.3.9. db_table (str)
1.3.10. cluster_id (int)
1.4. Exported Functions
1.5. Exported MI Functions
1.5.1. b2be_list
2. Developer Guide
2.1. b2b_load_api(b2b_api_t* api)
2.2. server_new
2.3. client_new
2.4. send_request
2.5. send_reply
2.6. entity_delete
2.7. restore_logic_info
2.8. update_b2bl_param
3. Contributors
3.1. By Commit Statistics
3.2. By Commit Activity
4. Documentation
4.1. Contributors
List of Tables
3.1. Top contributors by DevScore^(1), authored commits^(2) and
lines added/removed^(3)
3.2. Most recently active contributors^(1) to this module
List of Examples
1.1. Set server_hsize parameter
1.2. Set client_hsize parameter
1.3. Set script_req_route parameter
1.4. Set script_repl_route parameter
1.5. Set db_url parameter
1.6. Set update_period parameter
1.7. Set b2b_key_prefix parameter
1.8. Set db_mode parameter
1.9. Set db_table parameter
1.10. Set cluster_id parameter
2.1. b2b_api_t structure
Chapter 1. Admin Guide
1.1. Overview
The B2BUA implementation in OpenSIPS is separated in two
layers:
* a lower one(coded in this module)- which implements the
basic functions of a UAS and UAC
* a upper one - which represents the logic engine of B2BUA,
responsible of actually implementing the B2BUA services
using the functions offered by the low level.
This module stores records corresponding to the dialogs in
which the B2BUA is involved. It exports an API to be called
from other modules which offers functions for creating a new
dialog record, for sending requests or replies in one dialog
and will also notify the upper level module when a request or
reply is received inside one stored dialog. The records are
separated in two types: b2b server entities and b2b client
entities depending on the mode they are created. An entity
created for a received initial message will be a server entity,
while a entity that will send an initial request(create a new
dialog) will be a b2b client entity. The name corresponds to
the behavior in the first transaction - if UAS - server entity
and if UAC - client entity. This module does not implement a
B2BUA alone, but needs a B2B logic implementing module.
The module is able to respond to authentication challanges if
the uac_auth module is loaded first. The list of credentials
for b2b authentication is also provided by the uac_auth module.
1.2. Dependencies
1.2.1. OpenSIPS Modules
* tm
* a db module
* uac_auth (mandatory if authentication is required)
1.2.2. External Libraries or Applications
The following libraries or applications must be installed
before running OpenSIPS with this module loaded:
* none
1.3. Exported Parameters
1.3.1. server_hsize (int)
The size of the hash table that stores the b2b server entities.
It is the 2 logarithmic value of the real size.
Default value is “9” (512 records).
Example 1.1. Set server_hsize parameter
...
modparam("b2b_entities", "server_hsize", 10)
...
1.3.2. client_hsize (int)
The size of the hash table that stores the b2b client entities.
It is the 2 logarithmic value of the real size.
Default value is “9” (512 records).
Example 1.2. Set client_hsize parameter
...
modparam("b2b_entities", "client_hsize", 10)
...
1.3.3. script_req_route (str)
The name of the b2b script route that will be called when B2B
requests are received.
Example 1.3. Set script_req_route parameter
...
modparam("b2b_entities", "script_req_route", "b2b_request")
...
1.3.4. script_reply_route (str)
The name of the b2b script route that will be called when B2B
replies are received.
Example 1.4. Set script_repl_route parameter
...
modparam("b2b_entities", "script_reply_route", "b2b_reply")
...
1.3.5. db_url (str)
Database URL. It is not compulsory, if not set data is not
stored in database.
Example 1.5. Set db_url parameter
...
modparam("b2b_entities", "db_url", "mysql://opensips:opensipsrw@127.0.0.
1/opensips")
...
1.3.6. update_period (int)
The time interval at which to update the info in database.
Default value is “100”.
Example 1.6. Set update_period parameter
...
modparam("b2b_entities", "update_period", 60)
...
1.3.7. b2b_key_prefix (string)
The string to use when generating the key ( it is inserted in
the SIP messages as callid or to tag. It is useful to set this
prefix if you use more instances of opensips B2BUA cascaded in
the same architecture. Sometimes opensips B2BUA looks at the
callid or totag to see if it has the format it uses to
determine if the request was sent by it.
Default value is “B2B”.
Example 1.7. Set b2b_key_prefix parameter
...
modparam("b2b_entities", "b2b_key_prefix", "B2B1")
...
1.3.8. db_mode (int)
The B2B modules have support for the 3 type of database storage
* NO DB STORAGE - set this parameter to 0
* WRITE THROUGH (synchronous write in database) - set this
parameter to 1
* WRITE BACK (update in db from time to time) - set this
parameter to 2
Default value is “2” (WRITE BACK).
Example 1.8. Set db_mode parameter
...
modparam("b2b_entities", "db_mode", 1)
...
1.3.9. db_table (str)
The name of the table that will be used for storing B2B
entities
Default value is “b2b_entities”
Example 1.9. Set db_table parameter
...
modparam("b2b_entities", "db_table", "some table name")
...
1.3.10. cluster_id (int)
The ID of the cluster this instance belongs to. Setting this
parameter enables clustering support for the OpenSIPS B2BUA by
replicating the B2B entities (B2B dialogs) between instances.
This also ensures restart persistency through the clusterer
module's data "sync" mechanism.
Default value is “0” (clustering disabled)
Example 1.10. Set cluster_id parameter
...
modparam("b2b_entities", "cluster_id", 10)
...
1.4. Exported Functions
The module does not export functions to be used in
configuration script.
1.5. Exported MI Functions
1.5.1. b2be_list
This command can be used to list the internals of the b2b
entities.
Name: b2be_list
Parameters: none
MI FIFO Command Format:
opensips-cli -x mi b2be_list
Chapter 2. Developer Guide
The module provides an API that can be used from other OpenSIPS
modules. The API offers the functions for creating and handing
dialogs. A dialog can be created on a receipt initial message,
and this will correspond to a b2b server entity, or initiated
by the server and in this case a client entity will be created
in b2b_entities module.
2.1. b2b_load_api(b2b_api_t* api)
This function binds the b2b_entities modules and fills the
structure the exported functions that will be described in
detail.
Example 2.1. b2b_api_t structure
...
typedef struct b2b_api {
b2b_server_new_t server_new;
b2b_client_new_t client_new;
b2b_send_request_t send_request;
b2b_send_reply_t send_reply;
b2b_entity_delete_t entity_delete;
b2b_restore_linfo_t restore_logic_info;
b2b_update_b2bl_param_t update_b2bl_param;
}b2b_api_t;
...
2.2. server_new
Field type:
...
typedef str* (*b2b_server_new_t) (struct sip_msg* ,b2b_notify_t , void*
param);
...
This function asks the b2b_entities modules to create a new
server entity record. The internal processing actually extracts
the dialog information from the message and constructs a record
that will be stored in a hash table. The second parameters is a
pointer to a function that the b2b_entities module will call
when a event will come for that dialog (a request or reply).
The third parameter is a pointer to a value that will be stored
and given as a parameter when the notify function will be
called(it has to be allocated in shared memory).
The return value is an identifier for the record that will be
mentioned when calling other functions that represent actions
in the dialog(send request, send reply).
The notify function has the following prototype:
...
typedef int (*b2b_notify_t)(struct sip_msg* msg, str* id, int type, void
* param);
...
This function is called when a request or reply is received for
a dialog handled by b2b_entities. The first parameter is the
message, the second is the identifier for the dialog, the third
is a flag that says which is the type of the message(it has two
possible values - B2B_REQUEST and B2B_REPLY). The last
parameter is the parameter by the upper module when the entity
was created.
2.3. client_new
Field type:
...
typedef str* (*b2b_client_new_t) (client_info_t* , b2b_notify_t b2b_cbac
k,
b2b_add_dlginfo_t add_dlginfo_f, str* param);
...
This function asks the b2b_entities modules to create a new
client entity record and also create a new dialog by sending an
initial message. The parameters are all the values needed for
the initial request to which the notify function and parameter
are added. The b2b_cback parameter is a pointer to the callback
that must be called when an event happens(receiving a reply or
request) in the dialog created with this function. The
add_dlginfo_f parameter is also a function pointer to a
callback that will be called when a final success response will
be received for the created dialog. The callback will receive
as parameter the complete dialog information for the record. It
should be stored and used when calling send_request or
send_reply functions.
The return value is an identifier for the record that will be
mentioned when calling other functions that represent actions
in the dialog(send request, send reply).
2.4. send_request
Field type:
...
typedef int (*b2b_send_request_t)(enum b2b_entity_type ,str* b2b_key, st
r* method,
str* extra_headers, str* body, b2b_dlginfo_t*);
...
This function asks the b2b_entities modules to send a request
inside a b2b dialog identified by b2b_key. The first parameter
is the entity type and can have two values: B2B_SERVER and
B2B_CLIENT. The second is the identifier returned by the create
function(server_new or client_new) and the next are the
informations needed for the new request: method, extra_headers,
body. The last parameter contains the dialog information -
callid, to tag, from tag. These are needed to make a perfect
match to of b2b_entities record for which a new request must be
sent.
The return value is 0 for success and a negative value for
error.
2.5. send_reply
Field type:
...
typedef int (*b2b_send_reply_t)(enum b2b_entity_type et, str* b2b_key, i
nt code, str* text,
str* body, str* extra_headers, b2b_dlginfo_t* dlginfo);
...
This function asks the b2b_entities modules to send a reply
inside a b2b dialog identified by b2b_key. The first parameter
is the entity type and can have two values: B2B_SERVER and
B2B_CLIENT. The second is the identifier returned by the create
function(server_new or client_new) and the next are the
informations needed for the new reply: code, text, body,
extra_headers. The last parameter contains the dialog
information used for matching the right record.
The return value is 0 for success and a negative value for
error.
2.6. entity_delete
Field type:
...
typedef void (*b2b_entity_delete_t)(enum b2b_entity_type et, str* b2b_ke
y,
b2b_dlginfo_t* dlginfo);
...
This function must be called by the upper level function to
delete the records in b2b_entities. The records are not cleaned
up by the b2b_entities module and the upper level module must
take care to delete them.
2.7. restore_logic_info
Field type:
...
typedef int (*b2b_restore_linfo_t)(enum b2b_entity_type type, str* key,
b2b_notify_t cback);
...
This function is used at startup when loading the data from the
database to restore the pointer to the callback function.
2.8. update_b2bl_param
Field type:
...
typedef int (*b2b_update_b2bl_param_t)(enum b2b_entity_type type, str* k
ey,
str* param, int replicate);
...
This function can be used to change the logic param stored for
an entity ( useful in case an entity is moved between logic
records).
Chapter 3. Contributors
3.1. By Commit Statistics
Table 3.1. Top contributors by DevScore^(1), authored
commits^(2) and lines added/removed^(3)
Name DevScore Commits Lines ++ Lines --
1. Anca Vamanu 181 94 6839 1860
2. Vlad Patrascu (@rvlad-patrascu) 70 40 2205 706
3. Ovidiu Sas (@ovidiusas) 51 39 853 291
4. Bogdan-Andrei Iancu (@bogdan-iancu) 50 43 410 144
5. Razvan Crainea (@razvancrainea) 45 41 236 121
6. Liviu Chircu (@liviuchircu) 17 13 87 126
7. Vlad Paiu (@vladpaiu) 6 4 74 47
8. Nick Altmann (@nikbyte) 5 2 158 27
9. Maksym Sobolyev (@sobomax) 4 2 20 13
10. Stanislaw Pitucha 4 2 6 6
All remaining contributors: Peter Lemenkov (@lemenkov), Ionut
Ionita (@ionutrazvanionita), @DMOsipov, Stéphane Alnet
(@shimaore), Henk Hesselink, Ryan Bullock (@rrb3942), Walter
Doekes (@wdoekes).
(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
3.2. By Commit Activity
Table 3.2. Most recently active contributors^(1) to this module
Name Commit Activity
1. Razvan Crainea (@razvancrainea) Dec 2010 - Nov 2021
2. Vlad Patrascu (@rvlad-patrascu) May 2017 - Sep 2021
3. Nick Altmann (@nikbyte) Jan 2013 - May 2021
4. Bogdan-Andrei Iancu (@bogdan-iancu) Aug 2009 - Apr 2021
5. Maksym Sobolyev (@sobomax) Jan 2021 - Mar 2021
6. Liviu Chircu (@liviuchircu) Mar 2014 - Nov 2020
7. Peter Lemenkov (@lemenkov) Jun 2018 - Feb 2020
8. @DMOsipov Mar 2016 - Mar 2016
9. Ovidiu Sas (@ovidiusas) Nov 2010 - Mar 2016
10. Ionut Ionita (@ionutrazvanionita) Feb 2015 - Feb 2015
All remaining contributors: Walter Doekes (@wdoekes), Vlad Paiu
(@vladpaiu), Ryan Bullock (@rrb3942), Stéphane Alnet
(@shimaore), Anca Vamanu, Henk Hesselink, Stanislaw Pitucha.
(1) including any documentation-related commits, excluding
merge commits
Chapter 4. Documentation
4.1. Contributors
Last edited by: Vlad Patrascu (@rvlad-patrascu), Razvan Crainea
(@razvancrainea), Peter Lemenkov (@lemenkov), Liviu Chircu
(@liviuchircu), Bogdan-Andrei Iancu (@bogdan-iancu), Vlad Paiu
(@vladpaiu), Ovidiu Sas (@ovidiusas), Anca Vamanu.
Documentation Copyrights:
Copyright © 2009 Anca-Maria Vamanu