-
Notifications
You must be signed in to change notification settings - Fork 564
/
README
1464 lines (1166 loc) · 52.6 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
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
registrar Module
__________________________________________________________
Table of Contents
1. Admin Guide
1.1. Overview
1.1.1. Path Support (RFC 3327)
1.1.2. GRUU Support (RFC 5627)
1.1.3. SIP Push Notification Support (RFC 8599)
1.2. Dependencies
1.2.1. OpenSIPS Modules
1.2.2. External Libraries or Applications
1.3. Exported Parameters
1.3.1. default_expires (integer)
1.3.2. min_expires (integer)
1.3.3. max_expires (integer)
1.3.4. default_q (integer)
1.3.5. tcp_persistent_flag (string)
1.3.6. realm_prefix (string)
1.3.7. case_sensitive (integer)
1.3.8. received_avp (str)
1.3.9. received_param (string)
1.3.10. max_contacts (integer)
1.3.11. max_username_len (integer)
1.3.12. max_domain_len (integer)
1.3.13. max_aor_len (integer)
1.3.14. max_contact_len (integer)
1.3.15. retry_after (integer)
1.3.16. sock_hdr_name (string)
1.3.17. mcontact_avp (string)
1.3.18. attr_avp (string)
1.3.19. gruu_secret (string)
1.3.20. disable_gruu (int)
1.3.21. pn_enable (boolean)
1.3.22. pn_providers (string)
1.3.23. pn_ct_match_params (string)
1.3.24. pn_pnsreg_interval (integer)
1.3.25. pn_trigger_interval (integer)
1.3.26. pn_skip_pn_interval (integer)
1.3.27. pn_refresh_timeout (integer)
1.3.28. pn_enable_purr (boolean)
1.4. Exported Functions
1.4.1. save(domain[, flags[, aor[, ownership_tag]]])
1.4.2. remove(domain, AOR[, [contact][, [next_hop][,
[sip_instance]]]])
1.4.3. lookup(domain [, flags [, aor]])
1.4.4. is_registered(domain ,[AOR])
1.4.5. is_contact_registered(domain
,[AOR],[contact],[callid])
1.4.6. is_ip_registered(domain ,[AOR],IPvar)
1.4.7. add_sock_hdr(hdr_name)
1.5. Exported Asynchronous Functions
1.5.1. pn_process_purr(domain)
1.6. Exported Statistics
1.6.1. max_expires
1.6.2. max_contacts
1.6.3. defaults_expires
1.6.4. accepted_regs
1.6.5. rejected_regs
2. Frequently Asked Questions
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 default_expires parameter
1.2. Set min_expires parameter
1.3. Set max_expires parameter
1.4. Set default_q parameter
1.5. Set tcp_persistent_flag parameter
1.6. Set realm_prefix parameter
1.7. Set case_sensitive parameter
1.8. Set received_avp parameter
1.9. Set received_param parameter
1.10. Set max_contacts parameter
1.11. Setting the max_username_len module parameter
1.12. Setting the max_domain_len module parameter
1.13. Setting the max_aor_len module parameter
1.14. Setting the max_contact_len module parameter
1.15. Set retry_after parameter
1.16. Set sock_hdr_namer parameter
1.17. Set mcontact_avp parameter
1.18. Set attr_avp parameter
1.19. Set gruu_secret parameter
1.20. Set gruu_secret parameter
1.21. Setting the pn_enable parameter
1.22. Setting the pn_providers parameter
1.23. Setting the pn_ct_match_params parameter
1.24. Setting the pn_pnsreg_interval parameter
1.25. Setting the pn_trigger_interval parameter
1.26. Setting the pn_skip_pn_interval parameter
1.27. Setting the pn_refresh_timeout parameter
1.28. Setting the pn_enable_purr parameter
1.29. save usage
1.30. remove usage
1.31. lookup usage
1.32. is_registered usage
1.33. is_contact_registered usage
1.34. is_ip_registered usage
1.35. add_sock_hdr usage
1.36. async pn_process_purr() usage
Chapter 1. Admin Guide
1.1. Overview
The module contains SIP REGISTER request processing logic, per
RFC 3261. On top of this support, several extensions are
available:
1.1.1. Path Support (RFC 3327)
The registrar module includes SIP Path header field support
according to RFC 3327, for usage in registrars and
home-proxies.
A call to save() stores, if path support is enabled in the
registrar module, the values of the Path Header(s) along with
the Contact information into usrloc. There are three modes for
building the reply to a REGISTER message which includes one or
more Path header fields:
* off - stores the value of the Path headers into usrloc
without passing it back to the UAC in the reply.
* lazy - stores the Path header and passes it back to the UAC
if Path-support is indicated by the “path” param in the
Supported HF.
* strict - rejects the registration with “420 Bad Extension”
if there's a Path header but no support for it is indicated
by the UAC. Otherwise it's stored and passed back to the
UAC.
A call to lookup() always uses the Path header if found, and
inserts it as Route HF either in front of the first Route HF,
or after the last Via HF if no Route is present. It also sets
the destination URI to the first Path URI, thus overwriting the
received-URI, because NAT has to be handled at the
outbound-proxy of the UAC (the first hop after client's NAT).
The whole process is transparent to the user, so no config
changes are required besides enabling one of the "p0" / "p1" /
"p2" flags when calling save().
1.1.2. GRUU Support (RFC 5627)
The registrar module includes support for Globally Routable
User Agent URIs according to RFC 5627.
A call to save() stores, if the phone supports GRUU, the values
of the SIP Instance along with the contact into usrloc. The
module will generate two types of GRUUs:
* public - exposes the underlying AOR, constructed just by
attaching the SIP Instance as the ;gr parameter value.
These are persistent, valid as long as the contact
registration is valid.
* temporary - hides the underlying AOR Each new Register
request leads to the construction of a new temporary GRUU,
while Register requests with a different Call-ID lead to
the invalidation of all the previous generated temporary
GRUUs.
A call to lookup() will try to detect if the R-URI contains a
GRUU. If it does, it will route the request just for the
Contact that the specific AOR belongs to, without appending any
other branches.
Even if the the GRUU handling during the registration process
is transparent to the user, so no config changes are required,
you need to take care of the GRUU specifics when handling
mid-dialog requests.
As the GRUU will be present in the contact header of the
initial requests generated byt GRUU enabled devices, you will
have to also do a lookup() when receiving a mid-dialog request
with the GRUU indication in the RURI.
1.1.3. SIP Push Notification Support (RFC 8599)
The registrar module includes support for standards-based SIP
Push Notifications, per RFC 8599. Support for the basic version
of the draft can be enabled by switching pn_enable to true. The
module also includes optional support for sending Push
Notifications during long-lived dialogs (see RFC section 6),
through the pn_enable_purr switch.
Essential mechanics behind the Push Notification (PN) support:
* the PN support is fully compatible with the existing logic
and enabling it does not impose any limitations, as the
registrar can simultaneously handle both SIP PN compliant
and standard SIP User Agents
* OpenSIPS will raise a E_UL_CONTACT_REFRESH event any time a
Push Notification needs to be sent to a PN-enabled contact.
The event includes the PN coordinates of the contact --
they may be found in the Contact URI ('uri' event
parameter) and may be extracted using the {uri.param,name}
transformation. From here onwards, it is up to the script
developer to trigger the Push Notification, thus forcing a
re-registration from the device (e.g. possibly by sending
an HTTP POST with the rest_client module)
* REGISTER processing is unchanged -- PN-enabled UAs are
saved just as regular UAs, with the former ones
additionally having the 4 bitflag set in the "Flags" field
of any MI listing of contacts, for differentiation purposes
* initial INVITE processing is barely changed, with the
lookup() function now additionally returning a value of 2
if the only found contacts were PN-enabled contacts, all
which required a Push Notification. This means that PNs
have been triggered for each of them and t_relay() is not
required, since they are not reachable until they
re-register!
Using the event_routing module, OpenSIPS will transparently
fork a new branch from the current INVITE on each
re-registration from these contacts within the accepted
pn_refresh_timeout
* mid-dialog requests: In some cases (e.g. long-lived
dialogs), a PN may be required before being able to route a
mid-dialog request to a SIP UA. The pn_process_purr() async
function will take care of triggering the PN event and
resuming the script as soon as a re-registration from the
concerned contact is received.
For more information or examples, refer to the documentation of
the "pn_xxx" module parameters or the OpenSIPS blog posts
around the "SIP Push Notification" topic.
1.2. Dependencies
1.2.1. OpenSIPS Modules
The following modules must be loaded before this module:
* usrloc - User Location Module.
* signaling - Signaling module.
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. default_expires (integer)
If the processed message contains neither Expires HFs nor
expires contact parameters, this value will be used for newly
created usrloc records. The parameter contains number of second
to expire (for example use 3600 for one hour).
Default value is 3600.
Example 1.1. Set default_expires parameter
...
modparam("registrar", "default_expires", 1800)
...
1.3.2. min_expires (integer)
The minimum expires value of a Contact, values lower than this
minimum will be automatically set to the minimum. Value 0
disables the checking.
Default value is 60.
Example 1.2. Set min_expires parameter
...
modparam("registrar", "min_expires", 60)
...
1.3.3. max_expires (integer)
The maximum expires value of a Contact, values higher than this
maximum will be automatically set to the maximum. Value 0
disables the checking.
Default value is 0.
Example 1.3. Set max_expires parameter
...
modparam("registrar", "max_expires", 120)
...
1.3.4. default_q (integer)
The parameter represents default q value for new contacts.
Because OpenSIPS doesn't support float parameter types, the
value in the parameter is divided by 1000 and stored as float.
For example, if you want default_q to be 0.38, use value 380
here.
Default value is 0.
Example 1.4. Set default_q parameter
...
modparam("registrar", "default_q", 1000)
...
1.3.5. tcp_persistent_flag (string)
The parameter specifies the message flag to be used to control
the module behaviour regarding TCP connections. If the flag is
set for a REGISTER via TCP containing a TCP contact, the
module, via the “save()” function, will set the lifetime of the
TCP connection to the contact expire value. By doing this, the
TCP connection will stay on as long as the contact is valid.
Default value is -1 (disabled).
Example 1.5. Set tcp_persistent_flag parameter
...
modparam("registrar", "tcp_persistent_flag", "TCP_PERSIST_DURATION")
...
1.3.6. realm_prefix (string)
Prefix to be automatically strip from realm. As an alternative
to SRV records (not all SIP clients support SRV lookup), a
subdomain of the master domain can be defined for SIP purposes
(like sip.mydomain.net pointing to same IP address as the SRV
record for mydomain.net). By ignoring the realm_prefix "sip.",
at registration, sip.mydomain.net will be equivalent to
mydomain.net .
Default value is NULL (none).
Example 1.6. Set realm_prefix parameter
...
modparam("registrar", "realm_prefix", "sip.")
...
1.3.7. case_sensitive (integer)
If set to 1 then AOR comparison will be case sensitive (as
RFC3261 instructs), if set to 0 then AOR comparison will be
case insensitive.
Default value is 1.
Example 1.7. Set case_sensitive parameter
...
modparam("registrar", "case_sensitive", 0)
...
1.3.8. received_avp (str)
Registrar will store the value of the AVP configured by this
parameter in the received column in the user location database.
It will leave the column empty if the AVP is empty. The AVP
should contain a SIP URI consisting of the source IP, port, and
protocol of the REGISTER message being processed.
Note
The value of this parameter should be the same as the value of
corresponding parameter of nathelper module.
Default value is "NULL" (disabled).
Example 1.8. Set received_avp parameter
...
modparam("registrar", "received_avp", "$avp(rcv)")
...
1.3.9. received_param (string)
The name of the parameter that will be appended to Contacts of
200 OK when the received URI was set by nathelper module.
Default value is "received".
Example 1.9. Set received_param parameter
...
modparam("registrar", "received_param", "rcv")
...
1.3.10. max_contacts (integer)
The parameter can be used to limit the number of contacts per
AOR (Address of Record) in the user location database. Value 0
disables the check.
This is the default value and will be used only if no other
value (for max_contacts) is passed as parameter to the save()
function. That's it - the function parameter overwride this
global parameter.
Default value is 0.
Example 1.10. Set max_contacts parameter
...
# Allow no more than 10 contacts per AOR
modparam("registrar", "max_contacts", 10)
...
1.3.11. max_username_len (integer)
The maximum length of the "username" part of an
Address-of-Record SIP URI.
Default value is 64.
Example 1.11. Setting the max_username_len module parameter
modparam("registrar", "max_username_len", 128)
1.3.12. max_domain_len (integer)
The maximum length of the "domain" part of an Address-of-Record
SIP URI.
Default value is 64.
Example 1.12. Setting the max_domain_len module parameter
modparam("registrar", "max_domain_len", 128)
1.3.13. max_aor_len (integer)
The maximum length of an Address-of-Record SIP URI.
Default value is 256.
Example 1.13. Setting the max_aor_len module parameter
modparam("registrar", "max_aor_len", 512)
1.3.14. max_contact_len (integer)
The maximum length of a Contact header field SIP URI.
Default value is 255.
Example 1.14. Setting the max_contact_len module parameter
modparam("registrar", "max_contact_len", 512)
1.3.15. retry_after (integer)
The registrar can generate 5xx reply to REGISTER in various
situations. It can, for example, happen when the max_contacts
parameter is set and the processing of REGISTER request would
exceed the limit. In this case the registrar would generate
"503 Service Unavailable" response.
If you want to add the Retry-After header field in 5xx replies,
set this parameter to a value grater than zero (0 means do not
add the header field). See section 20.33 of RFC3261 for more
details.
Default value is 0 (disabled).
Example 1.15. Set retry_after parameter
...
modparam("registrar", "retry_after", 30)
...
1.3.16. sock_hdr_name (string)
Header which contains a socket description (proto:IP:port) to
override the received socket info. The header will be search
and used only if the flag 's' (Socket header) is set at
"save()" time.
This makes sense only in multiple replicated servers scenarios.
Default value is NULL.
Example 1.16. Set sock_hdr_namer parameter
...
modparam("registrar", "sock_hdr_name", "Sock-Info")
...
1.3.17. mcontact_avp (string)
AVP to store the modified binding/contact that is set during
cached registrations scenario (when REGISTER is forwarded to
another registrar). The AVP will be used to extract the
"expires" value returned in the 200 OK by the main registrar.
This makes sense only in cached registrations scenario, where
your OpenSIPS is caching registrations before forwarding them
to the main registrar.
Default value is NULL.
Example 1.17. Set mcontact_avp parameter
...
modparam("registrar", "mcontact_avp", "$avp(orig_ct)")
...
route {
...
# before forwarding the REGISTER request, save the outgoing contact.
# Be SURE to do it after all the possible changes over the contact,
# like fix_nated_contact()
$avp(orig_ct) = $ct.fields(uri);
t_on_reply("do_save");
t_relay("udp:ip:port");
...
}
...
onreply_route[do_save] {
if ($rs=="200")
save("location");
}
...
1.3.18. attr_avp (string)
AVP to store specific additional information for each
registration. This information is read from the AVP and stored
(in memory, db or both) at every registrar 'save'. When a
registrar 'lookup' or 'is_registered' function is called, the
attr_avp is populated with the value saved at [re]registration.
When doing call forking, the avp will hold multiple values. The
position of the corresponding attribute information in attr_avp
is equal to the branch index. An example scenario is given
below.
Default value is NULL.
Example 1.18. Set attr_avp parameter
# reading attributes from the attr_pvar when doing parallel forking
...
modparam("registrar", "attr_avp", "$avp(attr)")
...
if (is_method("REGISTER")) {
$avp(attr) = "contact_info";
save("location");
exit;
}
...
lookup("location");
t_on_branch("parallel_fork");
...
branch_route [parallel_fork] {
xlog("Attributes for branch $T_branch_idx: $(avp(attr)[$T_branch
_idx])\n");
}
1.3.19. gruu_secret (string)
The string that will be used in XORing when generating
temporary GRUUs.
If not set, 'OpenSIPS' is the default secret.
Example 1.19. Set gruu_secret parameter
...
modparam("registrar", "gruu_secret", "top_secret")
...
1.3.20. disable_gruu (int)
Globally disable GRUU handling
Default value is 1 ( GRUU will not be handled ).
Example 1.20. Set gruu_secret parameter
...
modparam("registrar", "disable_gruu", 0)
...
1.3.21. pn_enable (boolean)
Enable SIP Push Notification support (RFC 8599). If enabled,
Contact header field URIs which include all pn_ct_match_params
will be matched against existing bindings using only these
parameters. Otherwise, the module will attempt to match them as
usual, using the current usrloc matching_mode.
Default value is false.
Example 1.21. Setting the pn_enable parameter
...
modparam("registrar", "pn_enable", true)
...
1.3.22. pn_providers (string)
A list of supported Push Notification providers. While only
three possible values are defined by RFC 8599 ("apns", "fcm"
and "webpush"), non-standard values may be specified as well.
Default value is NULL (not set).
Example 1.22. Setting the pn_providers parameter
...
modparam("registrar", "pn_providers", "apns, fcm, webpush")
...
1.3.23. pn_ct_match_params (string)
The minimally required list of RFC 8599 parameters (custom ones
are accepted as well) which must be present in a Contact URI
and identically match an existing binding in order for the
binding to be refreshed. If at least one such parameter is
missing from a Contact header field URI, the module will fall
back to performing regular contact matching.
Note that if all above PN Contact URI parameters match an
existing binding, the match is considered to be successful
regardless if other parts of the SIP URI do not match (e.g.
hostname, port, other URI parameters, etc.).
After calling lookup() or pn_process_purr(), the above
PN-related parameters will be automatically stripped from the
resulting Request and Contact URI event parameter,
respectively.
Default value is "pn-provider, pn-prid, pn-param".
Example 1.23. Setting the pn_ct_match_params parameter
...
modparam("registrar", "pn_ct_match_params", "pn-provider, pn-prid")
...
1.3.24. pn_pnsreg_interval (integer)
For devices capable of waking up and refreshing their binding
on their own (signified by the ";+sip.pnsreg" Contact header
field parameter), this setting denotes the prior-to-expiration
interval advertised by the server at which the device should
issue its binding refresh request.
Default value is 130 (seconds before expiry).
Example 1.24. Setting the pn_pnsreg_interval parameter
...
modparam("registrar", "pn_pnsreg_interval", 140)
...
1.3.25. pn_trigger_interval (integer)
If a binding refresh REGISTER request from a given SIP endpoint
does not arrive within at least pn_trigger_interval seconds
prior to expiration (e.g. because the device does not support
";+sip.pnsreg" or because of other error conditions), the
E_UL_CONTACT_REFRESH usrloc event will be triggered.
Once E_UL_CONTACT_REFRESH is triggered, the script writer
should use the RFC 8599 parameters from the Contact URI in
order to generate a Push Notification request to the PN
provider of the device, in order to cause the device to wake up
and re-register.
Default value is 120 (seconds before expiry).
Example 1.25. Setting the pn_trigger_interval parameter
...
modparam("registrar", "pn_trigger_interval", 130)
...
1.3.26. pn_skip_pn_interval (integer)
Following a successful (re)registration of a contact, this
setting denotes a time interval, in seconds, during which the
contact is assumed to be reachable, so any Push Notifications
will be skipped.
Default value is 0 seconds (always generate Push
Notifications).
Example 1.26. Setting the pn_skip_pn_interval parameter
...
modparam("registrar", "pn_skip_pn_interval", 10)
...
1.3.27. pn_refresh_timeout (integer)
This timeout starts counting following a lookup() or a
pn_process_purr() which triggers a Push Notification. The value
represents the maximum allowed sum of the duration required for
the Push Notification to be sent and the duration required for
the corresponding re-registration from the device to arrive.
Once this timeout is exceeded for an initial or a mid-dialog
request, any further re-registrations which match the pending
Push Notification will no longer cause the desired effects. For
example:
* pending initial INVITE transactions will complete and will
no longer auto-fork an additional branch for each REGISTER
sent by the callee side
* pending BYE messages will time out and OpenSIPS will
attempt to route them despite not having received a
confirmation that the target device is actually reachable
Default value is 6 seconds.
Example 1.27. Setting the pn_refresh_timeout parameter
...
modparam("registrar", "pn_refresh_timeout", 10)
...
1.3.28. pn_enable_purr (boolean)
Enable the SIP Push Notification mechanism for long-lived
dialogs. If enabled, the registrar will include a
"+sip.pnspurr" Feature-Caps header field tag in 200 OK replies
to REGISTER requests. This tag represents a unique identifier
for the registration (PURR - Proxy Unique Registration
Reference).
For each initial request for dialog, the UA may include the
PURR received from the registrar in its Contact header (using
the ";pn-purr" URI parameter) if it expects to be first awoken
by a Push Notification before being able to receive mid-dialog
request sent by the callee side.
When enabling this parameter, make sure to also add logic for
pn_process_purr().
Default value is false.
Example 1.28. Setting the pn_enable_purr parameter
...
modparam("registrar", "pn_enable_purr", true)
...
1.4. Exported Functions
1.4.1. save(domain[, flags[, aor[, ownership_tag]]])
The function processes a REGISTER message. It can add, remove
or modify usrloc records depending on Contact and Expires HFs
in the REGISTER message. On success, 200 OK will be returned
listing all contacts that are currently in usrloc. On an error,
error message will be send with a short description in reason
phrase.
Meaning of the parameters is as follows:
* domain (static string) - Logical domain within registrar.
If database is used then this must be name of the table
which stores the contacts.
* flags (string, optional) - string of the following flags:
+ 'm' (Memory only) - save the contacts only in memory
cache without no DB operation;
+ 'r' (no Reply) - do not generate a SIP reply to the
current REGISTER request.
+ 's' (Socket header) - look into REGISTER request for a
header which contains a socket description
(proto:IP:port). This socket info will be stored by
register instead of the received socket info.
+ 'cnn' (max Contacts) - this flag can be used to limit
the number of contacts for this AOR (Address of
Record) in the user location database. Value 0
disables the check. This parameter overrides the
global "max_contacts" module parameter.
+ 'e(int)' (minimum expires) - this flag can be used to
set minimum register expiration time. Values lower
than this minimum will be automatically set to the
minimum. Value 0 disables the checking. This parameter
overrides the global min_expires module parameter.
+ 'E(int)' (maximum expires) - this flag can be used to
set maximum register expiration time. Values higher
than this maximum will be automatically set to the
maximum. Value 0 disables the checking. This parameter
overrides the global max_expires module parameter.
+ 'f' (force registration) - this flag can be used to
force the registration of NEW contacts even if the
maximum number of contacts is reached. In such a case,
older contacts will be removed to make space to the
new ones, without exceeding the maximum allowed
number. This flag makes sense only if "cxx" is used.
+ 'o' (Only request contacts) - Only include the
REGISTER request's Contacts in the 200 OK reply, in
case the registration is successful. While this is
against RFC 3261, it may be useful in certain
scenarios.
+ 'Mxx' (contact Matching mode) - How the matching
should be performed between the uploaded contacts (by
the currently handled REGISTER) and the already know
contacts (in memory or DB). This options will be used
only for the current operation and can be:
o 'M0' - contact URI matching only
o 'M1' - contact URI and SIP Call-ID matching
o 'M<param_name>' - only the value of the given URI
param will be used for matching (for example
M<rinstance>)
+ 'p0' (Path support - 'off' mode) The Path header is
saved into usrloc, but is never included in the reply.
+ 'p1' (Path support - lazy mode) The Path header is
saved into usrloc, but is only included in the reply
if path support is indicated in the registration
request by the “path” option of the “Supported”
header.
+ 'p2' (Path support - strict mode) The path header is
only saved into usrloc, if path support is indicated
in the registration request by the “path” option of
the “Supported” header. If no path support is
indicated, the request is rejected with “420 - Bad
Extension” and the header “Unsupported: path” is
included in the reply along with the received “Path”
header. This mode is the one recommended by RFC-3327.
+ 'v' (path receiVed) if set, the “received” parameter
of the first Path URI of a registration is set as
received-uri and the NAT branch flag is set for this
contact. This is useful if the registrar is placed
behind a SIP loadbalancer, which passes the nat'ed UAC
address as “received” parameter in it's Path uri.
This parameter is a string composed of a set of flags.
* aor (string, optional) - a custom AOR; if missing, the AOR
will be taken from the default place - the TO header URI.
* ownership_tag (string, optional) - a cluster-shared tag
(see the clusterer module documentation for more details)
which will be attached to each contact saved from the
current request. This tag is only relevant in clustered
user location scenarios and helps determine the current
logical owner node of a contact. This, in turn, is useful
in order to restrict nodes which are not currently
responsible for this contact from performing certain
actions (for example: incorrectly originating pings from a
non-owned virtual IP address in highly-available setups).
This function can be used from REQUEST_ROUTE and ONREPLY_ROUTE.
If you plan to use the “save()” function in reply route, please
refer to mcontact_avp module parameter.
Example 1.29. save usage
...
# save into 'location', no flags, use default AOR (TO URI)
save("location");
...
# save into 'location', do not update DB, max 5 contacts per AOR,
# use default AOR (TO URI)
save("location","mc5");
...
# save into 'location', no flags, use as AOR the FROM URI
save("location","",$fu);
...
# save into 'location', no DB update, force registration, take AOR from
AVP
save("location","mr", $avp(aor));
...
# save into 'location', mark the contacts with the "vip" ownership tag a
nd
# replicate these contacts to the backup node, which does not currently
own "vip"
save("location", , , "vip");
...
1.4.2. remove(domain, AOR[, [contact][, [next_hop][,
[sip_instance]]]])
Explicitly remove contacts behind a given address-of-record.
Meaning of the parameters is as follows:
* domain (static string - Logical domain within the
registrar. If a database is used, then this must be name of
the table which stores the contacts.
* AOR (string) - address-of-record to be searched (SIP URI)
* contact (string, optional) - SIP URI filter for the contact
to be removed. This must be the full SIP URI as used during
registered.
* next_hop (string, optional) - the next SIP IP
address/hostname on the way back to this contact. See the
section below for details on how the next hop is computed.
Hostnames are resolved before matching.
* sip_instance (string, optional) - a "+sip.instance" value
to be used for filtering purposes.
IMPORTANT: the IP address of each contact (for matching
purposes) is computed as follows:
* a. if a Path header is present, the hostname part of the
Path URI will be resolved as the contact's IP address.
* b. otherwise, if by using nathelper, the "Received" value
(source IP of the next hop) is set for a contact, this
becomes the chosen hostname to be resolved as the contact's
IP address.
* c. otherwise, the "hostname" part of the Contact header
field URI is chosen to be resolved as the contact's IP
address.
This function can be used from REQUEST_ROUTE and ONREPLY_ROUTE.
Example 1.30. remove usage
...
# remove all contacts belonging to the "bob" AOR
remove("location", "sip:bob@atlanta.com");
...
# remove only bob's home phone contact
remove("location", "sip:bob@atlanta.com", "sip:bob@46.50.64.78");
...
# remove all bob's phones which are behind "50.60.50.60"
# note that "contact" parameter has to be specified with NULL value even
though not used
$var(next_hop) = "50.60.50.60"
remove("location", "sip:bob@atlanta.com", , $var(next_hop));
...
# remove bob's phone with contact "sip:bob@46.50.64.78" that is behind "
50.60.50.60"
remove("location", "sip:bob@atlanta.com", "sip:bob@46.50.64.78", "50.60.
50.60");
...
# remove all contacts behind bob's mobile device X
remove("location", "sip:bob@atlanta.com", , , "<urn:uuid:e5e68d40-f08a-4
600-b82e-ff4d5d8c1a8f>")
1.4.3. lookup(domain [, flags [, aor]])
The functions extracts username from Request-URI and tries to
find all contacts for the username in usrloc. If there are no
such contacts, -1 will be returned. If there are such contacts,
Request-URI will be overwritten with the contact that has the
highest q value and optionally the rest will be appended to the
message (depending on append_branches parameter value).
If the method_filtering option is enabled, the lookup function
will return only the contacts that support the method of the
processed request.
Meaning of the parameters is as follows:
* domain (static string) - Name of table that should be used
for the lookup.
* flags (string, optional)
+ 'b' (no Branches) - this flag controls how the
lookup() function processes multiple contacts. If
there are multiple contacts for the given username in
usrloc and this flag is not set, Request-URI will be
overwritten with the highest-q rated contact and the
rest will be appended to sip_msg structure and can be
later used by tm for forking. If the flag is set, only
Request-URI will be overwritten with the highest-q
rated contact and the rest will be left unprocessed.
+ 'B' (to Branches only) - this flags forces all found
contacts to be uploaded only as branches (in the
destination set) and not at all in the R-URI of the
current message. Using this option allows the lookup()
function to also be used in the context of a SIP
reply.
+ 'r' (bRanch lookup) - this flag enables searching
through existing branches for aor's and expanding them
to contacts. For example, you have got AOR A in your
ruri but you also want to forward your calls to AOR B.
In order to do this, you must put AOR B in a branch,
and if this flag enabled, the function will also
expand AOR B to contacts, which will be put back into
the branches. The AOR's that were in branches before
the function call shall be removed.
WARNING: if you want this flag activated, the 'b' (no
Branches) flag must not be set, because by setting
that flag you won't allow lookup() to write in a
branch.
+ 'm' (Method filtering) - setting this flag will enable
contact filtering based on the supported methods
listed in the "Allow" header field during
registration. Contacts which did not present an
"Allow" header field during registration are assumed
to support all standard SIP methods.
+ 'u' (User-Agent filtering) - this flag enables regexp
filtering by user-agent. It's useful with enabled
append_branches parameter. Regexp must follow the 'u'
flag and must use format like 'u/regexp/'.
+ 'i' (Case insensitive search) - this flag enables case
insensitive filtering for the 'u' flag.
+ 'e' (Use extended regexp) - this flag enables using of
extended regexp format for the 'u' flag.
+ 'g' (Global lookup) - this flag is only relevant with
federated user location clustering. If set, the
lookup() function will not only perform the classic
in-memory "search-AoR-and-push-branches" operation,
but will also perform a metadata lookup and append an
additional branch for each returned result. The
"in-memory branches" correspond to local contacts
(current location), while the "metadata branches"
correspond to contacts available on one or more of the
remaining locations of the platform.
The AoR metadata consists of the minimally required
information in order for one of the VoIP platform's
locations (data centers) to advertise the presence of
a locally registered AoR for the global platform.
Specifically, this consists of two pieces of
information: