Browse code

modules: readme files regenerated - registrar ... [skip ci]

Kamailio Dev authored on 12/05/2022 17:31:15
Showing 1 changed files
... ...
@@ -1 +1,1477 @@
1
+registrar Module
1 2
 
3
+Jan Janak
4
+
5
+   FhG FOKUS
6
+   <jan@iptel.org>
7
+
8
+Daniel-Constantin Mierla
9
+
10
+   <miconda@gmail.com>
11
+
12
+Juha Heinanen
13
+
14
+   <jh@tutpro.com>
15
+
16
+Olle E. Johansson
17
+
18
+   Edvina AB
19
+   <oej@edvina.net>
20
+
21
+Edited by
22
+
23
+Jan Janak
24
+
25
+   <jan@iptel.org>
26
+
27
+Bogdan-Andre Iancu
28
+
29
+   Copyright © 2003 FhG FOKUS
30
+     __________________________________________________________________
31
+
32
+   Table of Contents
33
+
34
+   1. Admin Guide
35
+
36
+        1. Overview
37
+
38
+              1.1. PATH support
39
+              1.2. GRUU Support
40
+
41
+        2. Dependencies
42
+
43
+              2.1. Kamailio Modules
44
+              2.2. External Libraries or Applications
45
+
46
+        3. Parameters
47
+
48
+              3.1. default_expires (integer)
49
+              3.2. default_expires_range (integer)
50
+              3.3. expires_range (integer)
51
+              3.4. min_expires (integer)
52
+              3.5. min_expires_mode (integer)
53
+              3.6. max_expires (integer)
54
+              3.7. default_q (integer)
55
+              3.8. realm_prefix (string)
56
+              3.9. append_branches (integer)
57
+              3.10. aor_avp (str)
58
+              3.11. case_sensitive (integer)
59
+              3.12. received_avp (str)
60
+              3.13. received_param (string)
61
+              3.14. max_contacts (integer)
62
+              3.15. retry_after (integer)
63
+              3.16. sock_flag (integer)
64
+              3.17. sock_hdr_name (string)
65
+              3.18. sock_mode (integer)
66
+              3.19. method_filtering (integer)
67
+              3.20. use_path (integer)
68
+              3.21. path_mode (integer)
69
+              3.22. path_use_received (integer)
70
+              3.23. path_check_local (integer)
71
+              3.24. reg_callid_avp (string)
72
+              3.25. xavp_cfg (string)
73
+              3.26. xavp_rcd (string)
74
+              3.27. xavp_rcd_mask (int)
75
+              3.28. gruu_enabled (integer)
76
+              3.29. outbound_mode (integer)
77
+              3.30. regid_mode (integer)
78
+              3.31. flow_timer (integer)
79
+              3.32. contact_max_size (integer)
80
+              3.33. event_callback (str)
81
+              3.34. lookup_filter_mode (int)
82
+              3.35. use_expired_contacts (int)
83
+
84
+        4. Functions
85
+
86
+              4.1. save(domain, [, flags [, uri]])
87
+              4.2. lookup(domain [, uri])
88
+              4.3. lookup_to_dset(domain [, uri])
89
+              4.4. lookup_branches(domain)
90
+              4.5. lookup_xavp(ultable, uri, rxname, cxname)
91
+              4.6. registered(domain [, uri [, match_option [,
92
+                      match_action]]])
93
+
94
+              4.7. add_sock_hdr(hdr_name)
95
+              4.8. unregister(domain, uri[, ruid])
96
+              4.9. reg_fetch_contacts(domain, uri, profile)
97
+              4.10. reg_free_contacts(profile)
98
+              4.11. reg_send_reply()
99
+
100
+        5. Event Routes
101
+
102
+              5.1. event_route[usrloc:contact-expired]
103
+
104
+        6. Statistics
105
+
106
+              6.1. max_expires
107
+              6.2. max_contacts
108
+              6.3. default_expires
109
+              6.4. accepted_regs
110
+              6.5. rejected_regs
111
+
112
+        7. Pseudo Variables
113
+
114
+              7.1. $ulc(profile=>attr)
115
+
116
+   2. Frequently Asked Questions
117
+
118
+   List of Examples
119
+
120
+   1.1. Set default_expires parameter
121
+   1.2. Set default_expires_range parameter
122
+   1.3. Set expires_range parameter
123
+   1.4. Set min_expires parameter
124
+   1.5. Set min_expires_mode parameter
125
+   1.6. Set max_expires parameter
126
+   1.7. Set default_q parameter
127
+   1.8. Set realm_prefix parameter
128
+   1.9. Set append_branches parameter
129
+   1.10. Set case_sensitive parameter
130
+   1.11. Set received_avp parameter
131
+   1.12. Set received_param parameter
132
+   1.13. Set max_contacts parameter
133
+   1.14. Set retry_after parameter
134
+   1.15. Set sock_flag parameter
135
+   1.16. Set sock_hdr_name parameter
136
+   1.17. Set sock_mode parameter
137
+   1.18. Set method_filtering parameter
138
+   1.19. Set use_path parameter
139
+   1.20. Set path_mode parameter
140
+   1.21. Set path_use_received parameter
141
+   1.22. Set path_check_local parameter
142
+   1.23. Set reg_callid_avp parameter
143
+   1.24. Set xavp_cfg parameter
144
+   1.25. Set xavp_rcd parameter
145
+   1.26. Set xavp_rcd_mask parameter
146
+   1.27. Set gruu_enabled parameter
147
+   1.28. Set outbound_mode parameter
148
+   1.29. Set regid_mode parameter
149
+   1.30. Set flow_timer parameter
150
+   1.31. Set contact_max_size parameter
151
+   1.32. Set event_callback parameter
152
+   1.33. Set xavp_cfg parameter
153
+   1.34. Set use_expired_contacts parameter
154
+   1.35. save usage
155
+   1.36. lookup usage
156
+   1.37. lookup_to_dset usage
157
+   1.38. lookup_branches usage
158
+   1.39. lookup_xavp usage
159
+   1.40. registered usage
160
+   1.41. add_sock_hdr usage
161
+   1.42. unregister usage
162
+   1.43. reg_fetch_contacts usage
163
+   1.44. reg_free_contacts usage
164
+   1.45. reg_send_reply usage
165
+   1.46. event_route[usrloc:contact-expired] usage
166
+   1.47. $ulc(name) usage
167
+
168
+Chapter 1. Admin Guide
169
+
170
+   Table of Contents
171
+
172
+   1. Overview
173
+
174
+        1.1. PATH support
175
+        1.2. GRUU Support
176
+
177
+   2. Dependencies
178
+
179
+        2.1. Kamailio Modules
180
+        2.2. External Libraries or Applications
181
+
182
+   3. Parameters
183
+
184
+        3.1. default_expires (integer)
185
+        3.2. default_expires_range (integer)
186
+        3.3. expires_range (integer)
187
+        3.4. min_expires (integer)
188
+        3.5. min_expires_mode (integer)
189
+        3.6. max_expires (integer)
190
+        3.7. default_q (integer)
191
+        3.8. realm_prefix (string)
192
+        3.9. append_branches (integer)
193
+        3.10. aor_avp (str)
194
+        3.11. case_sensitive (integer)
195
+        3.12. received_avp (str)
196
+        3.13. received_param (string)
197
+        3.14. max_contacts (integer)
198
+        3.15. retry_after (integer)
199
+        3.16. sock_flag (integer)
200
+        3.17. sock_hdr_name (string)
201
+        3.18. sock_mode (integer)
202
+        3.19. method_filtering (integer)
203
+        3.20. use_path (integer)
204
+        3.21. path_mode (integer)
205
+        3.22. path_use_received (integer)
206
+        3.23. path_check_local (integer)
207
+        3.24. reg_callid_avp (string)
208
+        3.25. xavp_cfg (string)
209
+        3.26. xavp_rcd (string)
210
+        3.27. xavp_rcd_mask (int)
211
+        3.28. gruu_enabled (integer)
212
+        3.29. outbound_mode (integer)
213
+        3.30. regid_mode (integer)
214
+        3.31. flow_timer (integer)
215
+        3.32. contact_max_size (integer)
216
+        3.33. event_callback (str)
217
+        3.34. lookup_filter_mode (int)
218
+        3.35. use_expired_contacts (int)
219
+
220
+   4. Functions
221
+
222
+        4.1. save(domain, [, flags [, uri]])
223
+        4.2. lookup(domain [, uri])
224
+        4.3. lookup_to_dset(domain [, uri])
225
+        4.4. lookup_branches(domain)
226
+        4.5. lookup_xavp(ultable, uri, rxname, cxname)
227
+        4.6. registered(domain [, uri [, match_option [, match_action]]])
228
+        4.7. add_sock_hdr(hdr_name)
229
+        4.8. unregister(domain, uri[, ruid])
230
+        4.9. reg_fetch_contacts(domain, uri, profile)
231
+        4.10. reg_free_contacts(profile)
232
+        4.11. reg_send_reply()
233
+
234
+   5. Event Routes
235
+
236
+        5.1. event_route[usrloc:contact-expired]
237
+
238
+   6. Statistics
239
+
240
+        6.1. max_expires
241
+        6.2. max_contacts
242
+        6.3. default_expires
243
+        6.4. accepted_regs
244
+        6.5. rejected_regs
245
+
246
+   7. Pseudo Variables
247
+
248
+        7.1. $ulc(profile=>attr)
249
+
250
+1. Overview
251
+
252
+   1.1. PATH support
253
+   1.2. GRUU Support
254
+
255
+   The module contains REGISTER processing logic. The actual location
256
+   database is managed by the USRLOC module.
257
+
258
+1.1. PATH support
259
+
260
+   The Register module includes Path support (according to RFC 3327) for
261
+   usage in registrars and home-proxies.
262
+
263
+   If path support is enabled in the registrar module, a call to save(...)
264
+   stores the values of the Path Header(s) along with the contact into
265
+   usrloc. There are three modes regarding the reply to a REGISTER
266
+   including one or more Path header fields:
267
+     * off - stores the value of the Path headers into usrloc without
268
+       passing it back to the UAC in the reply.
269
+     * lazy - stores the Path header and passes it back to the UAC if
270
+       Path-support is indicated by the “path” param in the Supported
271
+       header field.
272
+     * strict - rejects the registration with “420 Bad Extension” if
273
+       there's a Path header but no support for it is indicated by the
274
+       UAC. Otherwise it's stored and passed back to the UAC.
275
+
276
+   A call to lookup(...) always uses the path header if found, and inserts
277
+   it as Route header field either in front of the first Route header
278
+   field, or after the last Via header field if no Route is present. It
279
+   also sets the destination uri to the first Path uri, thus overwriting
280
+   the received-uri, because NAT has to be handled at the outbound-proxy
281
+   of the UAC (the first hop after client's NAT).
282
+
283
+   The whole process is transparent to the user, so no config changes are
284
+   required beside setting the registrar-parameters “use_path” and
285
+   “path_mode”.
286
+
287
+1.2. GRUU Support
288
+
289
+   GRUU (RFC5627) is supported with both public and temporary addresses.
290
+
291
+   The public GRUU is build based on the '+sip.instance' UUID parameter as
292
+   recommended by RFC.
293
+
294
+   The temporary GRUU is built based on internal SRUID (unique id
295
+   generator) and it is kept the same for the duration of contact
296
+   validity.
297
+
298
+2. Dependencies
299
+
300
+   2.1. Kamailio Modules
301
+   2.2. External Libraries or Applications
302
+
303
+2.1. Kamailio Modules
304
+
305
+   The following modules must be loaded before this module:
306
+     * usrloc - User Location Module.
307
+     * sl - Stateless Replies.
308
+
309
+2.2. External Libraries or Applications
310
+
311
+   The following libraries or applications must be installed before
312
+   running Kamailio with this module loaded:
313
+     * None.
314
+
315
+3. Parameters
316
+
317
+   3.1. default_expires (integer)
318
+   3.2. default_expires_range (integer)
319
+   3.3. expires_range (integer)
320
+   3.4. min_expires (integer)
321
+   3.5. min_expires_mode (integer)
322
+   3.6. max_expires (integer)
323
+   3.7. default_q (integer)
324
+   3.8. realm_prefix (string)
325
+   3.9. append_branches (integer)
326
+   3.10. aor_avp (str)
327
+   3.11. case_sensitive (integer)
328
+   3.12. received_avp (str)
329
+   3.13. received_param (string)
330
+   3.14. max_contacts (integer)
331
+   3.15. retry_after (integer)
332
+   3.16. sock_flag (integer)
333
+   3.17. sock_hdr_name (string)
334
+   3.18. sock_mode (integer)
335
+   3.19. method_filtering (integer)
336
+   3.20. use_path (integer)
337
+   3.21. path_mode (integer)
338
+   3.22. path_use_received (integer)
339
+   3.23. path_check_local (integer)
340
+   3.24. reg_callid_avp (string)
341
+   3.25. xavp_cfg (string)
342
+   3.26. xavp_rcd (string)
343
+   3.27. xavp_rcd_mask (int)
344
+   3.28. gruu_enabled (integer)
345
+   3.29. outbound_mode (integer)
346
+   3.30. regid_mode (integer)
347
+   3.31. flow_timer (integer)
348
+   3.32. contact_max_size (integer)
349
+   3.33. event_callback (str)
350
+   3.34. lookup_filter_mode (int)
351
+   3.35. use_expired_contacts (int)
352
+
353
+3.1. default_expires (integer)
354
+
355
+   If the processed message contains neither Expires header fields nor
356
+   expires contact parameters, this value will be used for newly created
357
+   usrloc records. The parameter contains number of second to expire (for
358
+   example use 3600 for one hour). If it is set to a lower value than the
359
+   “min_expires” parameter then it will be ignored. This parameter can be
360
+   modified via ser config framework. A random value in a specific
361
+   interval can be selected by using the default_expires_range parameter
362
+
363
+   Default value is 3600.
364
+
365
+   Example 1.1. Set default_expires parameter
366
+...
367
+modparam("registrar", "default_expires", 1800)
368
+...
369
+
370
+3.2. default_expires_range (integer)
371
+
372
+   This parameter specifies that the expiry used for newly created usrloc
373
+   records are not fixed, but a random value in the interval
374
+   “[default_expires-default_expires_range%, default_expires]”. The value
375
+   is between 0 and 100 and represent the maximum percentage from expires
376
+   that will be subtracted when computing the value. Default is 0, meaning
377
+   default_expires is left unmodified. This parameter can be modified via
378
+   the Kamailio config framework.
379
+
380
+   Default value is 0.
381
+
382
+   Example 1.2. Set default_expires_range parameter
383
+...
384
+modparam("registrar", "default_expires_range", 30) # +- 30% from default_expires
385
+...
386
+
387
+3.3. expires_range (integer)
388
+
389
+   Similar to default_expires_range, but it applies to the incoming
390
+   expires value. Default in 0, meaning the expires is left unmodified.
391
+   This parameter can be modified via the Kamailio config framework.
392
+
393
+   Default value is 0.
394
+
395
+   Example 1.3. Set expires_range parameter
396
+...
397
+modparam("registrar", "expires_range", 30) # expires within [0.7*expires .. expi
398
+res]
399
+...
400
+
401
+3.4. min_expires (integer)
402
+
403
+   The minimum expires value of a “Contact”. Values lower than this
404
+   minimum will be either set to the minimum or 423 response is sent back.
405
+   Value 0 disables the checking. This parameter can be modified via the
406
+   Kamailio config framework.
407
+
408
+   Default value is 60.
409
+
410
+   Example 1.4. Set min_expires parameter
411
+...
412
+modparam("registrar", "min_expires", 60)
413
+...
414
+
415
+3.5. min_expires_mode (integer)
416
+
417
+   Control what to do when expires value in REGISTER request is lower than
418
+   min_expires parameter. If set to 0, expires is set to min_expires. If
419
+   set to 1, then 423 Interval Too Brief is sent back.
420
+
421
+   Default value is 0.
422
+
423
+   Example 1.5. Set min_expires_mode parameter
424
+...
425
+modparam("registrar", "min_expires_mode", 1)
426
+...
427
+
428
+3.6. max_expires (integer)
429
+
430
+   The maximum accepted expires value of a “Contact”, values higher than
431
+   this maximum will be automatically set to the maximum. Value 0 disables
432
+   the checking. This parameter can be modified via the Kamailio config
433
+   framework.
434
+
435
+   Default value is 0.
436
+
437
+   Example 1.6. Set max_expires parameter
438
+...
439
+modparam("registrar", "max_expires", 120)
440
+...
441
+
442
+3.7. default_q (integer)
443
+
444
+   The parameter represents default “q” value for new contacts. Because
445
+   Kamailio doesn't support float parameter types, the value in the
446
+   parameter is divided by 1000 and stored as float. For example, if you
447
+   want default_q to be 0.38, use value 380 here. This parameter can be
448
+   modified via the Kamailio config framework.
449
+
450
+   Default value is 0.
451
+
452
+   Example 1.7. Set default_q parameter
453
+...
454
+modparam("registrar", "default_q", 1000)
455
+...
456
+
457
+3.8. realm_prefix (string)
458
+
459
+   Prefix to be automatically stripped from realm. As an alternative to
460
+   SRV records (not all SIP clients support SRV lookup), a subdomain of
461
+   the master domain can be defined for SIP purposes (like
462
+   sip.mydomain.net pointing to same IP address as the SRV record for
463
+   mydomain.net). By ignoring the realm_prefix "sip.", at registration,
464
+   sip.mydomain.net will be equivalent to mydomain.net. This parameter can
465
+   be modified via the Kamailio config framework.
466
+
467
+   Default value is NULL (none).
468
+
469
+   Example 1.8. Set realm_prefix parameter
470
+...
471
+modparam("registrar", "realm_prefix", "sip.")
472
+...
473
+
474
+3.9. append_branches (integer)
475
+
476
+   The parameter controls how lookup function processes multiple contacts.
477
+   If there are multiple contacts for the given username in usrloc and
478
+   this parameter is set to 1, Request-URI will be overwritten with the
479
+   highest-q rated contact and the rest will be appended to sip_msg
480
+   structure and can be later used by tm for forking. If the parameter is
481
+   set to 0, only Request-URI will be overwritten with the highest-q rated
482
+   contact and the rest will be left unprocessed. This parameter can be
483
+   modified via Kamailio config framework.
484
+
485
+   Default value is 1.
486
+
487
+   Example 1.9. Set append_branches parameter
488
+...
489
+modparam("registrar", "append_branches", 0)
490
+...
491
+
492
+3.10. aor_avp (str)
493
+
494
+   This module parameter has been removed. Use the 'uri' parameter from
495
+   functions (e.g., save, lookup, registered).
496
+
497
+3.11. case_sensitive (integer)
498
+
499
+   If set to 1 then AOR comparison and also storing will be case
500
+   sensitive, if set to 0 then AOR comparison and storing will be case
501
+   insensitive. This is recommended. This parameter can be modified via
502
+   Kamailio config framework.
503
+
504
+   Default value is 0.
505
+
506
+   Example 1.10. Set case_sensitive parameter
507
+...
508
+modparam("registrar", "case_sensitive", 1)
509
+...
510
+
511
+3.12. received_avp (str)
512
+
513
+   Registrar will store the value of the AVP configured by this parameter
514
+   in the received column in the user location database. It will leave the
515
+   column empty if the AVP is empty. The AVP should contain a SIP URI
516
+   consisting of the source IP, port, and transport protocol of the
517
+   REGISTER message being processed.
518
+
519
+Note
520
+
521
+   The value of this parameter should be the same as the value of
522
+   corresponding parameter of nathelper module.
523
+
524
+   Default value is "NULL" (disabled).
525
+
526
+   Example 1.11. Set received_avp parameter
527
+...
528
+modparam("registrar", "received_avp", "$avp(s:rcv)")
529
+...
530
+
531
+3.13. received_param (string)
532
+
533
+   The name of the parameter that will be appended to Contact URI's of 200
534
+   OK when the received URI was set by the “nathelper” module. If the
535
+   value is an empty string, then the parameter is not appended anymore.
536
+
537
+   Default value is "received".
538
+
539
+   Example 1.12. Set received_param parameter
540
+...
541
+modparam("registrar", "received_param", "rcv")
542
+...
543
+
544
+3.14. max_contacts (integer)
545
+
546
+   The parameter can be used to limit the number of contacts per AOR
547
+   (Address of Record) in the user location database. If the maximum
548
+   number of contacts is exceeded, Kamailio will not accept the
549
+   registration and send an error response. Value 0 disables the check.
550
+   This parameter can be modified via the Kamailio config framework.
551
+   (Please also check the flag for save() if you only want only one active
552
+   registration).
553
+
554
+   Default value is 0.
555
+
556
+   Example 1.13. Set max_contacts parameter
557
+...
558
+# Allow no more than 10 contacts per AOR
559
+modparam("registrar", "max_contacts", 10)
560
+...
561
+
562
+3.15. retry_after (integer)
563
+
564
+   The registrar can generate a 5xx reply to REGISTER requests in various
565
+   situations. It can, for example, happen when the max_contacts parameter
566
+   is set and the processing of REGISTER request would exceed the limit.
567
+   In this case the registrar would generate "503 Service Unavailable"
568
+   response. This parameter can be modified via the Kamailio config
569
+   framework.
570
+
571
+   If you want to add the Retry-After header field in 5xx replies, set
572
+   this parameter to a value grater than zero (0 means do not add the
573
+   header field). See section 20.33 of RFC3261 for more details.
574
+
575
+   Default value is 0 (disabled).
576
+
577
+   Example 1.14. Set retry_after parameter
578
+...
579
+modparam("registrar", "retry_after", 30)
580
+...
581
+
582
+3.16. sock_flag (integer)
583
+
584
+   Message flag to signal to the registrar module to look into REGISTER
585
+   request for a header which contains a socket description (IP:port).
586
+   This socket info will be stored by registrar instead of the received
587
+   socket info.
588
+
589
+   This makes sense only in multiple replicated servers scenarios.
590
+
591
+   Default value is -1 (no flag).
592
+
593
+   Example 1.15. Set sock_flag parameter
594
+...
595
+modparam("registrar", "sock_flag", 18)
596
+...
597
+
598
+3.17. sock_hdr_name (string)
599
+
600
+   Header which contains a socket description (proto:IP:port) to override
601
+   the received socket info. The header will be read only if the flag
602
+   sock_flag is set.
603
+
604
+   This makes sense only in multiple replicated servers scenarios.
605
+
606
+   Default value is NULL.
607
+
608
+   Example 1.16. Set sock_hdr_name parameter
609
+...
610
+modparam("registrar", "sock_hdr_name", "Sock-Info")
611
+...
612
+
613
+3.18. sock_mode (integer)
614
+
615
+   If set to 1, the server stores the advertised address in socket field,
616
+   instead of bind address.
617
+
618
+   This could be useful when kamailio is installed behind NAT and it is
619
+   necessary to store its public IP instead socket on which the register
620
+   request was received.
621
+
622
+   Default value is 0 (store bind address).
623
+
624
+   Example 1.17. Set sock_mode parameter
625
+...
626
+modparam("registrar", "sock_mode", 1)
627
+...
628
+
629
+3.19. method_filtering (integer)
630
+
631
+   Tells if the contact filtering based on supported methods should be
632
+   performed during lookup on initial requests without to-tag. It's
633
+   enabled only if it has a non zero value. Supported methods are listed
634
+   in the “Allow:” header in the REGISTER message and stored in the
635
+   location database.
636
+
637
+   Default value is 0 (disabled).
638
+
639
+   Example 1.18. Set method_filtering parameter
640
+...
641
+modparam("registrar", "method_filtering", 1)
642
+...
643
+
644
+3.20. use_path (integer)
645
+
646
+   If set to 1, the “Path:” header is handled according to the parameter
647
+   This parameter can be modified via Kamailio config framework.
648
+   “path_mode”.
649
+
650
+   Default value is 0 (disabled).
651
+
652
+   Example 1.19. Set use_path parameter
653
+...
654
+modparam("registrar", "use_path", 1)
655
+...
656
+
657
+3.21. path_mode (integer)
658
+
659
+   The registrar module implements three different modes regarding the
660
+   response to a registration which includes one or more Path headers:
661
+     * 0 - The Path header is saved into usrloc, but is not included in
662
+       the reply.
663
+     * 1 - The Path header is saved into usrloc, but is only included in
664
+       the reply if path support is indicated in the registration request
665
+       by the “path” option in the “Supported:” header.
666
+     * 2 - The path header is only saved into usrloc, if path support is
667
+       indicated in the registration request by the “path” option of the
668
+       “Supported” header. If no path support is indicated, the request is
669
+       rejected with “420 - Bad Extension” and the header “Unsupported:
670
+       path” is included in the reply along with the received “Path”
671
+       header. This mode is the one recommended by RFC-3327.
672
+
673
+   Default value is 2.
674
+
675
+   Example 1.20. Set path_mode parameter
676
+...
677
+modparam("registrar", "path_mode", 0)
678
+...
679
+
680
+3.22. path_use_received (integer)
681
+
682
+   If set to 1, the “received” parameter of the first Path URI of a
683
+   registration is set as received-uri and the NAT branch flag is set for
684
+   this contact. This is useful if the registrar is placed behind a SIP
685
+   loadbalancer, which passes the nat'ed UAC address as “received”
686
+   parameter in it's Path uri.
687
+
688
+   Default value is 0 (disabled).
689
+
690
+   Example 1.21. Set path_use_received parameter
691
+...
692
+modparam("registrar", "path_use_received", 1)
693
+...
694
+
695
+3.23. path_check_local (integer)
696
+
697
+   If set to 1, when performing a lookup the Path (if present) is
698
+   evaluated and if the first hop is local (according to “myself” test),
699
+   we skip it to avoid unnecessary looping.
700
+
701
+   This is useful if multiple servers are sharing a common location
702
+   database, each saving contacts with their local address as the Path.
703
+
704
+   Default value is 0 (disabled).
705
+
706
+   Example 1.22. Set path_check_local parameter
707
+...
708
+modparam("registrar", "path_check_local", 1)
709
+...
710
+
711
+3.24. reg_callid_avp (string)
712
+
713
+   obsolete. use match_option in registered function
714
+
715
+   If reg_callid_avp is defined and populated when the registered() is
716
+   invoked, the result is TRUE only if an active registration with the
717
+   specified callID is found.
718
+
719
+   Default value is NULL (disabled).
720
+
721
+   Example 1.23. Set reg_callid_avp parameter
722
+...
723
+modparam("registrar", "reg_callid_avp", "$avp(s:avp)")
724
+...
725
+
726
+3.25. xavp_cfg (string)
727
+
728
+   Defines the name of XAVP class to store runtime module config values.
729
+   The values are stored as inner XAVPs, like $xavp(class=>attribute).
730
+   Valid inner XAVP names:
731
+     * match_callid - filter contacts by callid. Used in registered().
732
+     * match_contact - filter contacts by contact. Used in registered().
733
+     * match_received - filter contacts by received. Used in registered().
734
+     * rlf_bflags - filter contacts by branch flags. Used in lookup().
735
+     * q - q value of contact (integer 0-1000). It overrides q value given
736
+       in contact header and default_q parameter. Used in save().
737
+     * expires - the expires value, to overwrite the value from SIP
738
+       headers. Used in save().
739
+     * max_contacts - the number of maximum contacts to be stored for the
740
+       current registration AoR. It overwrites the 'max_contacts' module
741
+       parameter value. Used in save().
742
+     * socket - the string representing the socket on which the register
743
+       request was received, as alternative to using the sock_hdr. Used in
744
+       save().
745
+
746
+   For example. if this parameter is set to 'reg', then the number of
747
+   maximum contacts can be set in $xavp(reg=>max_contacts).
748
+
749
+   Default value is NULL (disabled).
750
+
751
+   Example 1.24. Set xavp_cfg parameter
752
+...
753
+modparam("registrar", "xavp_cfg", "reg")
754
+...
755
+request_route {
756
+    ...
757
+    $xavp(reg=>max_contacts) = 4;
758
+    $xavp(reg[0]=>expires) = 600;
759
+    save("location");
760
+    ...
761
+}
762
+...
763
+
764
+3.26. xavp_rcd (string)
765
+
766
+   Defines the name of XAVP class to store details from the location
767
+   records. The values are stored as inner XAVPs, like
768
+   $xavp(class[0]=>attribute). Valid inner XAVP names:
769
+     * ruid - the record's internal unique id.
770
+     * contact - the record's contact value.
771
+     * expires - the record's expires value.
772
+     * received - the record's received value.
773
+     * path - the record's path value.
774
+
775
+   For example. if this parameter is set to 'ulrcd', then values are set
776
+   in:
777
+     * $xavp(ulrcd[0]=>ruid)
778
+     * $xavp(ulrcd[0]=>contact)
779
+     * $xavp(ulrcd[0]=>received)
780
+     * $xavp(ulrcd[0]=>path)
781
+
782
+   Default value is NULL (disabled).
783
+
784
+   Example 1.25. Set xavp_rcd parameter
785
+...
786
+modparam("registrar", "xavp_rcd", "ulrcd")
787
+...
788
+
789
+3.27. xavp_rcd_mask (int)
790
+
791
+   Defines what values to skip when xavp_rcd is stored.
792
+     * 1 - ruid
793
+     * 2 - contact
794
+     * 4 - expires
795
+     * 8 - received
796
+     * 16 - path
797
+
798
+   Default value is 0 (none).
799
+
800
+   Example 1.26. Set xavp_rcd_mask parameter
801
+...
802
+# skip path value
803
+modparam("registrar", "xavp_rcd_mask", 16)
804
+...
805
+# skip path and expires values
806
+modparam("registrar", "xavp_rcd_mask", 20)
807
+...
808
+
809
+3.28. gruu_enabled (integer)
810
+
811
+   If set to 1 and the “+sip.instance” parameter to Contact header of
812
+   REGISTER is present, then the value of the parameter is saved to
813
+   location and pub-gruu and temp-gruu addresses are generated.
814
+
815
+   Set it to 0 if you want to ignore GRUU extensions in REGISTER.
816
+
817
+   Default value is 1 (enabled).
818
+
819
+   Example 1.27. Set gruu_enabled parameter
820
+...
821
+modparam("registrar", "gruu_enabled", 0)
822
+...
823
+
824
+3.29. outbound_mode (integer)
825
+
826
+   If set to 0 this module will accept REGISTER requests that do not
827
+   contain a “Supported:” header with the outbound options-tag. The 200 OK
828
+   response to REGISTER requests that this module generates will not
829
+   contain “Require:” or “Supported:” headers with the outbound
830
+   options-tag. If the client has a “Require:” header with the outbound
831
+   options tag the REGISTER will be rejected with a “420 Bad Extension”
832
+   response.
833
+
834
+   If set to 1 this module will accept REGISTER requests that do not
835
+   contain a “Supported:” header with the outbound options-tag and
836
+   REGISTER requests that do contain a Supported: or Requires: header with
837
+   the outbound options-tag. When the client supports outbound the
838
+   appropriate RFC5626 procedures will be followed.
839
+
840
+   If set to 2 this module will reject REGISTER requests that do not
841
+   contain a “Supported:” header with the outbound options-tag. When the
842
+   client supports outbound the appropriate RFC5626 procedures will be
843
+   followed.
844
+
845
+   Default value is 0.
846
+
847
+   Example 1.28. Set outbound_mode parameter
848
+...
849
+modparam("registrar", "outbound_mode", 2)
850
+...
851
+
852
+3.30. regid_mode (integer)
853
+
854
+   If set to 0 this module will ignore the “regid” contact param when
855
+   saving REGISTER request if the request does not indicate support for
856
+   outbound.
857
+
858
+   If set to 1 this module will use “regid” contact param (if present)
859
+   when saving REGISTER request even if REGISTER request does not indicate
860
+   support for outbound.
861
+
862
+   Default value is 0.
863
+
864
+   Example 1.29. Set regid_mode parameter
865
+...
866
+modparam("registrar", "regid_mode", 1)
867
+...
868
+
869
+3.31. flow_timer (integer)
870
+
871
+   If set to 0 then this module will not add a “Flow-Timer:” header to 200
872
+   OK responses to REGISTER requests.
873
+
874
+   If set to > 0 then this module will add a “Flow-Timer:” header
875
+   containing this value to 200 OK responses to REGISTER requests. This
876
+   parameter may only be set to a value > 0 when outbound_mode is set to 1
877
+   or 2.
878
+
879
+   When set to a value greater than 0 this parameter should be set to
880
+   slightly less than the connection timeout value between the UAC and the
881
+   network (this corresponds to the core tcp_connection_lifetime option
882
+   and websocket keepalive_timeout modparam). This parameter is most
883
+   useful when you have a single edge proxy/registrar or if you have an
884
+   edge proxy that cannot modify responses. If you are using a separate
885
+   edge proxy you should consider leaving this parameter set to 0 and
886
+   adding the “Flow-Timer:” header on the edge proxy as this allows you to
887
+   keep all of the timer values for a specific flow in one configuration.
888
+
889
+   Default value is 0.
890
+
891
+   Example 1.30. Set flow_timer parameter
892
+...
893
+modparam("registrar", "flow_timer", 25)
894
+...
895
+
896
+3.32. contact_max_size (integer)
897
+
898
+   Max size of URIs in “Contact:” header.
899
+
900
+   The size of URIs in “Contact:” headers are checked to be lower or equal
901
+   to this value. A warning is logged and a 400 Bad Request is sent in
902
+   response to REGISTER requests with contact URIs that are longer than
903
+   this value.
904
+
905
+   If a database is used then you must make sure that your database model
906
+   supports strings of the configured size in the column “contact” of the
907
+   table specified in “save()” function.
908
+
909
+   Default value is 512.
910
+
911
+   Example 1.31. Set contact_max_size parameter
912
+...
913
+modparam("registrar", "contact_max_size", 1024)
914
+...
915
+
916
+3.33. event_callback (str)
917
+
918
+   The name of the function in the KEMI configuration file (embedded
919
+   scripting language such as Lua, Python, ...) to be executed instead of
920
+   event_route[...] blocks.
921
+
922
+   The function receives a string parameter with the name of the event.
923
+   The only possible value currently is 'usrloc:contact-expired'.
924
+
925
+   Default value is 'empty' (no function is executed for events).
926
+
927
+   Example 1.32. Set event_callback parameter
928
+...
929
+modparam("registrar", "event_callback", "ksr_registrar_event")
930
+...
931
+-- event callback function implemented in Lua
932
+function ksr_registrar_event(evname)
933
+    KSR.info( "Expired contact for " .. KSR.pv.getw("$ulc(exp=>aor)") .. "\n");
934
+        return 1;
935
+end
936
+...
937
+
938
+3.34. lookup_filter_mode (int)
939
+
940
+   Control what filters should be applied to lookup(...) operations. It
941
+   can be a combination (sum) of the next values:
942
+     * 1 - apply the branch flags filter - return only contact records
943
+       with branch flags matching at least one set inside xavp specified
944
+       by xavp_cfg parameter with inner name rlf_bflags - e.g.,
945
+       $xavp(reg=>rlf_bflags).
946
+     * 2 - apply the active tcp connection filter - return only contact
947
+       records that have the associated TCP/TLS/WSS connection active. UDP
948
+       and SCTP contacts are not filtered, all are returned.
949
+
950
+   Default value is NULL (disabled).
951
+
952
+   Example 1.33. Set xavp_cfg parameter
953
+...
954
+modparam("registrar", "xavp_cfg", "reg")
955
+modparam("registrar", "lookup_filter_mode", 1)
956
+...
957
+request_route {
958
+    ...
959
+    $xavp(reg=>rlf_bflags) = 8;
960
+    if(lookup("location")) { ... }
961
+    ...
962
+}
963
+...
964
+
965
+3.35. use_expired_contacts (int)
966
+
967
+   Allow/Disallow the usage of the expired contacts.
968
+     * 0 Disallow the usage of the expired contacts.
969
+     * 1 Allow the usage of the expired contacts.
970
+
971
+   Default value is 0 (Disallow).
972
+
973
+   Example 1.34. Set use_expired_contacts parameter
974
+...
975
+modparam("registrar", "use_expired_contacts", 1)
976
+...
977
+
978
+kamcmd cfg.set_now_int registrar use_expired_contacts 1
979
+kamcmd cfg.set_now_int registrar use_expired_contacts 0
980
+
981
+4. Functions
982
+
983
+   4.1. save(domain, [, flags [, uri]])
984
+   4.2. lookup(domain [, uri])
985
+   4.3. lookup_to_dset(domain [, uri])
986
+   4.4. lookup_branches(domain)
987
+   4.5. lookup_xavp(ultable, uri, rxname, cxname)
988
+   4.6. registered(domain [, uri [, match_option [, match_action]]])
989
+   4.7. add_sock_hdr(hdr_name)
990
+   4.8. unregister(domain, uri[, ruid])
991
+   4.9. reg_fetch_contacts(domain, uri, profile)
992
+   4.10. reg_free_contacts(profile)
993
+   4.11. reg_send_reply()
994
+
995
+4.1.  save(domain, [, flags [, uri]])
996
+
997
+   The function processes a REGISTER message. It can add, remove or modify
998
+   location records (in usrloc) depending on Contact and Expires header
999
+   fields in the REGISTER message. On success and when called from the
1000
+   REQUEST_ROUTE, “200 OK” will be returned listing all contacts that are
1001
+   currently in the location database. As a side effect, also branch flags
1002
+   are stored in usrloc. On an error, an error message will be sent with a
1003
+   short description in reason phrase.
1004
+
1005
+   Meaning of the parameters is as follows:
1006
+     * domain - Logical domain within the registrar. If a database is used
1007
+       then this must be name of the table which stores the contacts.
1008
+     * flags (optional) - the value may be a bitwise OR of the following
1009
+       flags:
1010
+          + 0x01 - save the contacts only in memory cache with no DB
1011
+            operation;
1012
+          + 0x02 - do not generate a SIP reply to the current REGISTER
1013
+            request. When used in ONREPLY_ROUTE, this parameter is
1014
+            obsolete.
1015
+          + 0x04 - store and maintain one contact per AoR. If there are
1016
+            other contact addresses for AoR not matching current
1017
+            registration, remove them. This mode ensures one contact per
1018
+            AoR (user).
1019
+          + 0x08 - Do not apply expires_range or default_expires_range to
1020
+            this registration.
1021
+          + 0x10 - prepare the headers for reply, used only if flag 0x02
1022
+            is set.
1023
+       The flags may be given in decimal or hexadecimal format.
1024
+     * uri (optional - flags param has to be set and can be 0 for default
1025
+       behavior) - SIP URI to do be used instead of To header URI. It can
1026
+       be a dynamic string with pseudo-variables.
1027
+
1028
+   Return codes:
1029
+     * -2 - error, too many contacts for AOR.
1030
+       -1 - error.
1031
+       1 - contacts inserted.
1032
+       2 - contacts updated.
1033
+       3 - contacts deleted.
1034
+       4 - contacts returned.
1035
+
1036
+   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE and
1037
+   REPLY_ROUTE.
1038
+
1039
+   Example 1.35. save usage
1040
+...
1041
+save("location");
1042
+save("location", "0x01");
1043
+save("location", "0x00", "sip:test@kamailio.org");
1044
+...
1045
+
1046
+4.2.  lookup(domain [, uri])
1047
+
1048
+   The lookup function extracts username and/or domain from Request-URI
1049
+   and tries to find all contacts for the username in usrloc. If there are
1050
+   no such contacts, -1 will be returned. If there are such contacts,
1051
+   Request-URI will be overwritten with the contact that has the highest q
1052
+   value and optionally the rest will be appended to the message
1053
+   (depending on append_branches parameter value). As a side effect, also
1054
+   branch flags are restored from usrloc.
1055
+
1056
+   If the method_filtering option is enabled and request is initial
1057
+   request without to-tag, the lookup function will return only the
1058
+   contacts that support the method of the processed request.
1059
+
1060
+   Meaning of the parameters is as follows:
1061
+     * domain - Name of table that should be used for the lookup.
1062
+     * uri (optional) - SIP URI to do be used instead of R-URI. It can be
1063
+       a dynamic string with pseudo-variables.
1064
+
1065
+   Return codes:
1066
+     * 1 - contacts found and returned.
1067
+       -1 - no contact found.
1068
+       -2 - contacts found, but method not supported.
1069
+       -3 - internal error during processing.
1070
+
1071
+   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1072
+
1073
+   Example 1.36. lookup usage
1074
+...
1075
+lookup("location");
1076
+                        switch ($retcode) {:1
1077
+
1078
+    case -1:
1079
+    case -3:
1080
+        sl_send_reply("404", "Not Found");
1081
+        exit;
1082
+    case -2:
1083
+        sl_send_reply("405", "Not Found");
1084
+        exit;
1085
+};
1086
+...
1087
+
1088
+4.3.  lookup_to_dset(domain [, uri])
1089
+
1090
+   Similar to lookup(...), but push the location contacts to destination
1091
+   set, without changing the R-URI (first branch not changed, it creates
1092
+   additional branches). For the meaning of the parameters and the return
1093
+   codes, see the documentation for lookup(...) function.
1094
+
1095
+   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1096
+
1097
+   Example 1.37. lookup_to_dset usage
1098
+...
1099
+lookup_to_dset("location");
1100
+...
1101
+
1102
+4.4.  lookup_branches(domain)
1103
+
1104
+   The function performs lookup(domain) on r-uri and additional branches
1105
+   (only branches that have no other attributes set than uri).
1106
+
1107
+   Meaning of the parameters is as follows:
1108
+     * domain - Name of table that should be used for the lookup.
1109
+
1110
+   Return codes are propagated from the lookup(domain) function.
1111
+
1112
+   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1113
+
1114
+   Example 1.38. lookup_branches usage
1115
+...
1116
+lookup_branches("location");
1117
+...
1118
+
1119
+4.5.  lookup_xavp(ultable, uri, rxname, cxname)
1120
+
1121
+   Similar to lookup(...), but store the location record attributes in
1122
+   XAVPs. Note that not all contact record fields are stored
1123
+
1124
+   Meaning of the parameters:
1125
+     * ultable - name of the usrloc table that is used for the lookup.
1126
+     * uri - the URI to be searched in location table.
1127
+     * rxname - name of the XAVP to store record attributes. These are:
1128
+          + aor - the address of record.
1129
+     * cxname - name of the XAVP to store content attributes, name mapping
1130
+       is done from the perspective of using them to send out SIP
1131
+       requests. These are:
1132
+          + uri - the contact address.
1133
+          + socket - the socket of the contact record.
1134
+          + dsturi - the destination uri of the contact record (the
1135
+            received field in location contact).
1136
+
1137
+   This function can be used from ANY_ROUTE.
1138
+
1139
+   Example 1.39. lookup_xavp usage
1140
+...
1141
+lookup_xavp("location", "$fu", "rul", "cul");
1142
+xinfo("aor: $xavp(rul=>aor)\n");
1143
+xinfo("number of contacts: $xavp(rul>count)\n");
1144
+xinfo("first contact record - uri: $xavp(cul>uri)\n");
1145
+xinfo("first contact record - socket: $xavp(cul>socket)\n");
1146
+...
1147
+
1148
+4.6.  registered(domain [, uri [, match_option [, match_action]]])
1149
+
1150
+   The function returns true if the AOR in the URI is registered, false
1151
+   otherwise. The function does not modify the message being process, it
1152
+   neither rewrites the Request-URI if a contact is found nor append
1153
+   branches. If uri parameter is not provided, then it considered to be
1154
+   the Request-URI for SIP requests and To-URI for SIP replies.
1155
+
1156
+   Meaning of the parameters is as follows:
1157
+     * domain - Name of table that should be used for the lookup.
1158
+     * uri (optional) - SIP URI to do be used instead of Request/To-URI.
1159
+       It can be a dynamic string with pseudo-variables.
1160
+     * match_option (optional) - flag parameter to restrict contact
1161
+       search. use xavp_cfg to set the values to compare to.
1162
+       flag values is as follows:
1163
+          + 1 - match_callid
1164
+          + 2 - match_received
1165
+          + 4 - match_contact
1166
+     * match_action (optional) - actions to perform when match is
1167
+       positive.
1168
+       flag values is as follows:
1169
+          + 1 - restore the xavps associated with the matched contact
1170
+          + 2 - skip adding the matched location record attributes to
1171
+            xavp_rcd (e.g., the ruid, contact, received, ...)
1172
+
1173
+   This function can be used from ANY_ROUTE.
1174
+
1175
+   Example 1.40. registered usage
1176
+...
1177
+if (registered("location")) {
1178
+        sl_send_reply("100", "Trying");
1179
+        ...
1180
+};
1181
+...
1182
+$xavp(regcfg=>match_received) = $su;
1183
+if (registered("location","$rz:$Au", 2)) {
1184
+        sl_send_reply("100", "Trying");
1185
+        ...
1186
+};
1187
+...
1188
+
1189
+4.7.  add_sock_hdr(hdr_name)
1190
+
1191
+   Adds a new header to the current REGISTER request with “hdr_name” which
1192
+   contains the description of the received socket (proto:ip:port)
1193
+
1194
+   This makes sense only in multiple replicated servers scenarios.
1195
+
1196
+   Meaning of the parameters is as follows:
1197
+     * hdr_name - header name to be used, it can be a static string or
1198
+       contain variables.
1199
+
1200
+   This function can be used from REQUEST_ROUTE.
1201
+
1202
+   Example 1.41. add_sock_hdr usage
1203
+...
1204
+add_sock_hdr("Sock-Info");
1205
+...
1206
+
1207
+4.8.  unregister(domain, uri[, ruid])
1208
+
1209
+   The function removes contacts associated with 'uri' from the location
1210
+   database. If 'ruid' is provided a specific contact is removed, if
1211
+   'ruid' is not provided all the current contacts are removed. If 'ruid'
1212
+   is provided and the “usrloc” module is using “db_mode=3”, 'uri' does
1213
+   not need to be given and can be empty string.
1214
+
1215
+   Meaning of the parameters is as follows:
1216
+     * domain - Name of table that should be used for the lookup or
1217
+       contact addresses.
1218
+     * uri - The SIP URI address of the user which to remove the contact
1219
+       addresses for. It can contain pseudo-variables that are evaluated
1220
+       at runtime.
1221
+     * ruid - The record unique ID for a a specific contact to be removed.
1222
+       It can contain pseudo-variables that are evaluated at runtime.
1223
+
1224
+   This function can be used from ANY_ROUTE.
1225
+
1226
+   Return values:
1227
+     * 0 - Successfully deleted contact(s)
1228
+     * -1 - Failed to extract or parse address of record from argument
1229
+     * -2 - Error in unregistering user
1230
+     * -3 - Contacts for AOR not found
1231
+
1232
+   Example 1.42. unregister usage
1233
+...
1234
+unregister("location", "$ru");
1235
+unregister("location", "sip:user@kamailio.org");
1236
+unregister("location", "$ru", "$ulc(caller=>ruid)");
1237
+unregister("location", "", "$ruid");
1238
+...
1239
+
1240
+4.9.  reg_fetch_contacts(domain, uri, profile)
1241
+
1242
+   The function fetches the contacts for 'uri' from table 'domain' to
1243
+   pseudo-variable $ulc(profile).
1244
+
1245
+   Meaning of the parameters is as follows:
1246
+     * domain - Name of table that should be used for the lookup of
1247
+       contact addresses.
1248
+     * uri - The SIP URI address of the user which to fetch the contact
1249
+       addresses for. It can contain pseudo-variables that are evaluated
1250
+       at runtime.
1251
+     * profile - Name of $ulc pseudo-variable profile that will store the
1252
+       fetched contacts. It is a static string.
1253
+
1254
+   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1255
+
1256
+   Example 1.43. reg_fetch_contacts usage
1257
+...
1258
+reg_fetch_contacts("location", "$ru", "callee");
1259
+reg_fetch_contacts("location", "sip:user@kamailio.org", "caller");
1260
+...
1261
+
1262
+4.10.  reg_free_contacts(profile)
1263
+
1264
+   The function frees the contacts from pseudo-variable $ulc(profile).
1265
+   Should be called to release the content of a profile. Anyhow, fetching
1266
+   a new contact addresses set over a profile will release any existing
1267
+   data in that profile.
1268
+
1269
+   Meaning of the parameters is as follows:
1270
+     * profile - Name of $ulc pseudo-variable profile that stores fetched
1271
+       contacts. It is a static string.
1272
+
1273
+   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1274
+
1275
+   Example 1.44. reg_free_contacts usage
1276
+...
1277
+reg_free_contacts("callee");
1278
+...
1279
+
1280
+4.11.  reg_send_reply()
1281
+
1282
+   The function sends the SIP reply that is normally sent by save(...),
1283
+   but that was skipped due to flag 0x2. It must be used after save(...,
1284
+   "0x2"). Practically it allows saving registration to location table, do
1285
+   other operations and then send the reply.
1286
+
1287
+   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1288
+
1289
+   Example 1.45. reg_send_reply usage
1290
+...
1291
+save("location", "0x2");
1292
+...
1293
+reg_send_reply();
1294
+...
1295
+
1296
+5. Event Routes
1297
+
1298
+   5.1. event_route[usrloc:contact-expired]
1299
+
1300
+5.1. event_route[usrloc:contact-expired]
1301
+
1302
+   Executed when a contact in location table has expired. The variable
1303
+   $ulc(exp=>...) is filled with the attributes of the expired contact.
1304
+
1305
+   Example 1.46. event_route[usrloc:contact-expired] usage
1306
+...
1307
+event_route[usrloc:contact-expired] {
1308
+    xlog("expired contact for $ulc(exp=>aor)\n");
1309
+}
1310
+...
1311
+
1312
+6. Statistics
1313
+
1314
+   6.1. max_expires
1315
+   6.2. max_contacts
1316
+   6.3. default_expires
1317
+   6.4. accepted_regs
1318
+   6.5. rejected_regs
1319
+
1320
+6.1. max_expires
1321
+
1322
+   Value of max_expires parameter.
1323
+
1324
+6.2. max_contacts
1325
+
1326
+   The value of max_contacts parameter.
1327
+
1328
+6.3. default_expires
1329
+
1330
+   The value of default_expires parameter.
1331
+
1332
+6.4. accepted_regs
1333
+
1334
+   Number of accepted registrations.
1335
+
1336
+6.5. rejected_regs
1337
+
1338
+   Number of rejected registrations.
1339
+
1340
+7. Pseudo Variables
1341
+
1342
+   7.1. $ulc(profile=>attr)
1343
+
1344
+7.1. $ulc(profile=>attr)
1345
+
1346
+   Access the attributes of contact addresses stored in 'profile'. It must
1347
+   be used after a call of “reg_fetch_contacts()”.
1348
+
1349
+   The “profile” has to be one of the values used with
1350
+   “reg_fetch_contacts()”.
1351
+
1352
+   The “attr” can be:
1353
+     * aor - address of record
1354
+     * domain - used location domain/table name
1355
+     * aorhash - hash id for the record
1356
+     * addr - contact address
1357
+     * path - path vector
1358
+     * received - received address
1359
+     * expires - expires value
1360
+     * callid - call-id header value
1361
+     * q - the q value
1362
+     * cseq - the cseq value
1363
+     * flags - flags value
1364
+     * cflags - cflags value
1365
+     * user_agent - user agent
1366
+     * socket - local socket
1367
+     * modified - last modified time
1368
+     * methods - methods value
1369
+     * count - number of contacts
1370
+     * ruid - record unique ID
1371
+     * regid - reg-id value
1372
+     * instance - instance value
1373
+     * conid - TCP socket internal connection ID ($null if UDP)
1374
+     * server_id - server_id value
1375
+
1376
+   The pseudo-variable accepts positive index value to access a specific
1377
+   contact record.
1378
+
1379
+   Example 1.47. $ulc(name) usage
1380
+...
1381
+if(reg_fetch_contacts("location", "$fu", "caller"))
1382
+{
1383
+  xlog("caller=>aor: $(ulc(caller=>aor))\n");
1384
+  xlog("caller=>domain: $(ulc(caller=>domain))\n");
1385
+  xlog("caller=>aorhash $(ulc(caller=>aorhash))\n");
1386
+  xlog("caller=>count $(ulc(caller=>count))\n");
1387
+  $var(i) = 0;
1388
+  while($var(i) < $(ulc(caller=>count)))
1389
+  {
1390
+    xlog("--- contact [$var(i)]\n");
1391
+    xlog("caller=>addr:       $(ulc(caller=>addr)[$var(i)])\n");
1392
+    xlog("caller=>path:       $(ulc(caller=>path)[$var(i)])\n");
1393
+    xlog("caller=>received:   $(ulc(caller=>received)[$var(i)])\n");
1394
+    xlog("caller=>expires:    $(ulc(caller=>expires)[$var(i)])\n");
1395
+    xlog("caller=>callid:     $(ulc(caller=>callid)[$var(i)])\n");
1396
+    xlog("caller=>regid:      $(ulc(caller=>regid)[$var(i)])\n");
1397
+    xlog("caller=>q:          $(ulc(caller=>q)[$var(i)])\n");
1398
+    xlog("caller=>cseq:       $(ulc(caller=>cseq)[$var(i)])\n");
1399
+    xlog("caller=>flags:      $(ulc(caller=>flags)[$var(i)])\n");
1400
+    xlog("caller=>cflags:     $(ulc(caller=>cflags)[$var(i)])\n");
1401
+    xlog("caller=>user_agent: $(ulc(caller=>user_agent)[$var(i)])\n");
1402
+    xlog("caller=>socket: