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