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