src/modules/registrar/README
31ccf6a2
 registrar Module
 
 Jan Janak
 
    FhG FOKUS
780a37d9
    <jan@iptel.org>
31ccf6a2
 
9fc784c6
 Daniel-Constantin Mierla
 
    <miconda@gmail.com>
 
cbce3372
 Juha Heinanen
 
    <jh@tutpro.com>
 
780a37d9
 Olle E. Johansson
 
    Edvina AB
    <oej@edvina.net>
 
31ccf6a2
 Edited by
 
 Jan Janak
 
780a37d9
    <jan@iptel.org>
 
31ccf6a2
 Bogdan-Andre Iancu
 
9cb2a163
    Copyright © 2003 FhG FOKUS
e45ac57e
      __________________________________________________________________
31ccf6a2
 
    Table of Contents
d77df08a
 
9fc784c6
    1. Admin Guide
31ccf6a2
 
e45ac57e
         1. Overview
 
               1.1. PATH support
fd9fe6e6
               1.2. GRUU Support
e45ac57e
 
         2. Dependencies
 
               2.1. Kamailio Modules
               2.2. External Libraries or Applications
 
ba7961bb
         3. Parameters
e45ac57e
 
               3.1. default_expires (integer)
4480f807
               3.2. default_expires_range (integer)
5961824b
               3.3. expires_range (integer)
               3.4. min_expires (integer)
21904268
               3.5. min_expires_mode (integer)
               3.6. max_expires (integer)
               3.7. default_q (integer)
               3.8. realm_prefix (string)
               3.9. append_branches (integer)
               3.10. aor_avp (str)
               3.11. case_sensitive (integer)
               3.12. received_avp (str)
               3.13. received_param (string)
               3.14. max_contacts (integer)
               3.15. retry_after (integer)
               3.16. sock_flag (integer)
               3.17. sock_hdr_name (string)
b0b2ab6d
               3.18. sock_mode (integer)
28e69c4c
               3.19. method_filtering (integer)
               3.20. use_path (integer)
               3.21. path_mode (integer)
               3.22. path_use_received (integer)
               3.23. path_check_local (integer)
               3.24. reg_callid_avp (string)
               3.25. xavp_cfg (string)
               3.26. xavp_rcd (string)
               3.27. xavp_rcd_mask (int)
               3.28. gruu_enabled (integer)
               3.29. outbound_mode (integer)
               3.30. regid_mode (integer)
               3.31. flow_timer (integer)
               3.32. contact_max_size (integer)
               3.33. event_callback (str)
               3.34. lookup_filter_mode (int)
               3.35. use_expired_contacts (int)
e45ac57e
 
ba7961bb
         4. Functions
e45ac57e
 
3417a42c
               4.1. save(domain, [, flags [, uri]])
               4.2. lookup(domain [, uri])
b52757f8
               4.3. lookup_to_dset(domain [, uri])
               4.4. lookup_branches(domain)
               4.5. registered(domain [, uri [, match_option [,
82ea7fd9
                       match_action]]])
 
b52757f8
               4.6. add_sock_hdr(hdr_name)
               4.7. unregister(domain, uri[, ruid])
               4.8. reg_fetch_contacts(domain, uri, profile)
               4.9. reg_free_contacts(profile)
               4.10. reg_send_reply()
e45ac57e
 
83410304
         5. Event Routes
e45ac57e
 
83410304
               5.1. event_route[usrloc:contact-expired]
e45ac57e
 
83410304
         6. Statistics
e45ac57e
 
83410304
               6.1. max_expires
               6.2. max_contacts
a91b2b68
               6.3. default_expires
83410304
               6.4. accepted_regs
               6.5. rejected_regs
 
         7. Pseudo Variables
 
               7.1. $ulc(profile=>attr)
7a67411c
 
033b5989
    2. Frequently Asked Questions
31ccf6a2
 
    List of Examples
d77df08a
 
    1.1. Set default_expires parameter
4480f807
    1.2. Set default_expires_range parameter
5961824b
    1.3. Set expires_range parameter
    1.4. Set min_expires parameter
21904268
    1.5. Set min_expires_mode parameter
    1.6. Set max_expires parameter
    1.7. Set default_q parameter
    1.8. Set realm_prefix parameter
    1.9. Set append_branches parameter
    1.10. Set case_sensitive parameter
    1.11. Set received_avp parameter
    1.12. Set received_param parameter
    1.13. Set max_contacts parameter
    1.14. Set retry_after parameter
    1.15. Set sock_flag parameter
    1.16. Set sock_hdr_name parameter
b0b2ab6d
    1.17. Set sock_mode parameter
28e69c4c
    1.18. Set method_filtering parameter
    1.19. Set use_path parameter
    1.20. Set path_mode parameter
    1.21. Set path_use_received parameter
    1.22. Set path_check_local parameter
    1.23. Set reg_callid_avp parameter
    1.24. Set xavp_cfg parameter
    1.25. Set xavp_rcd parameter
    1.26. Set xavp_rcd_mask parameter
    1.27. Set gruu_enabled parameter
    1.28. Set outbound_mode parameter
    1.29. Set regid_mode parameter
    1.30. Set flow_timer parameter
    1.31. Set contact_max_size parameter
    1.32. Set event_callback parameter
    1.33. Set xavp_cfg parameter
    1.34. Set use_expired_contacts parameter
    1.35. save usage
    1.36. lookup usage
b52757f8
    1.37. lookup_to_dset usage
    1.38. lookup_branches usage
    1.39. registered usage
    1.40. add_sock_hdr usage
    1.41. unregister usage
    1.42. reg_fetch_contacts usage
    1.43. reg_free_contacts usage
    1.44. reg_send_reply usage
    1.45. event_route[usrloc:contact-expired] usage
    1.46. $ulc(name) usage
31ccf6a2
 
9fc784c6
 Chapter 1. Admin Guide
31ccf6a2
 
e45ac57e
    Table of Contents
 
    1. Overview
 
         1.1. PATH support
fd9fe6e6
         1.2. GRUU Support
e45ac57e
 
    2. Dependencies
 
         2.1. Kamailio Modules
         2.2. External Libraries or Applications
 
ba7961bb
    3. Parameters
e45ac57e
 
         3.1. default_expires (integer)
4480f807
         3.2. default_expires_range (integer)
5961824b
         3.3. expires_range (integer)
         3.4. min_expires (integer)
21904268
         3.5. min_expires_mode (integer)
         3.6. max_expires (integer)
         3.7. default_q (integer)
         3.8. realm_prefix (string)
         3.9. append_branches (integer)
         3.10. aor_avp (str)
         3.11. case_sensitive (integer)
         3.12. received_avp (str)
         3.13. received_param (string)
         3.14. max_contacts (integer)
         3.15. retry_after (integer)
         3.16. sock_flag (integer)
         3.17. sock_hdr_name (string)
b0b2ab6d
         3.18. sock_mode (integer)
28e69c4c
         3.19. method_filtering (integer)
         3.20. use_path (integer)
         3.21. path_mode (integer)
         3.22. path_use_received (integer)
         3.23. path_check_local (integer)
         3.24. reg_callid_avp (string)
         3.25. xavp_cfg (string)
         3.26. xavp_rcd (string)
         3.27. xavp_rcd_mask (int)
         3.28. gruu_enabled (integer)
         3.29. outbound_mode (integer)
         3.30. regid_mode (integer)
         3.31. flow_timer (integer)
         3.32. contact_max_size (integer)
         3.33. event_callback (str)
         3.34. lookup_filter_mode (int)
         3.35. use_expired_contacts (int)
e45ac57e
 
ba7961bb
    4. Functions
e45ac57e
 
3417a42c
         4.1. save(domain, [, flags [, uri]])
         4.2. lookup(domain [, uri])
b52757f8
         4.3. lookup_to_dset(domain [, uri])
         4.4. lookup_branches(domain)
         4.5. registered(domain [, uri [, match_option [, match_action]]])
         4.6. add_sock_hdr(hdr_name)
         4.7. unregister(domain, uri[, ruid])
         4.8. reg_fetch_contacts(domain, uri, profile)
         4.9. reg_free_contacts(profile)
         4.10. reg_send_reply()
e45ac57e
 
83410304
    5. Event Routes
 
         5.1. event_route[usrloc:contact-expired]
e45ac57e
 
83410304
    6. Statistics
e45ac57e
 
83410304
         6.1. max_expires
         6.2. max_contacts
a91b2b68
         6.3. default_expires
83410304
         6.4. accepted_regs
         6.5. rejected_regs
e45ac57e
 
83410304
    7. Pseudo Variables
 
         7.1. $ulc(profile=>attr)
e45ac57e
 
 1. Overview
 
    1.1. PATH support
fd9fe6e6
    1.2. GRUU Support
31ccf6a2
 
114d674d
    The module contains REGISTER processing logic. The actual location
    database is managed by the USRLOC module.
31ccf6a2
 
e45ac57e
 1.1. PATH support
bff5fbbc
 
114d674d
    The Register module includes Path support (according to RFC 3327) for
    usage in registrars and home-proxies.
bff5fbbc
 
114d674d
    If path support is enabled in the registrar module, a call to save(...)
    stores the values of the Path Header(s) along with the contact into
    usrloc. There are three modes regarding the reply to a REGISTER
56a25750
    including one or more Path header fields:
e45ac57e
      * off - stores the value of the Path headers into usrloc without
        passing it back to the UAC in the reply.
      * lazy - stores the Path header and passes it back to the UAC if
56a25750
        Path-support is indicated by the “path” param in the Supported
        header field.
9cb2a163
      * strict - rejects the registration with “420 Bad Extension” if
e45ac57e
        there's a Path header but no support for it is indicated by the
        UAC. Otherwise it's stored and passed back to the UAC.
 
    A call to lookup(...) always uses the path header if found, and inserts
56a25750
    it as Route header field either in front of the first Route header
    field, or after the last Via header field if no Route is present. It
    also sets the destination uri to the first Path uri, thus overwriting
    the received-uri, because NAT has to be handled at the outbound-proxy
    of the UAC (the first hop after client's NAT).
e45ac57e
 
    The whole process is transparent to the user, so no config changes are
9cb2a163
    required beside setting the registrar-parameters “use_path” and
    “path_mode”.
e45ac57e
 
fd9fe6e6
 1.2. GRUU Support
 
    GRUU (RFC5627) is supported with both public and temporary addresses.
 
b5c5090c
    The public GRUU is build based on the '+sip.instance' UUID parameter as
fd9fe6e6
    recommended by RFC.
 
    The temporary GRUU is built based on internal SRUID (unique id
    generator) and it is kept the same for the duration of contact
    validity.
 
e45ac57e
 2. Dependencies
 
    2.1. Kamailio Modules
    2.2. External Libraries or Applications
 
 2.1. Kamailio Modules
31ccf6a2
 
    The following modules must be loaded before this module:
      * usrloc - User Location Module.
      * sl - Stateless Replies.
 
e45ac57e
 2.2. External Libraries or Applications
31ccf6a2
 
e45ac57e
    The following libraries or applications must be installed before
    running Kamailio with this module loaded:
31ccf6a2
      * None.
 
ba7961bb
 3. Parameters
e45ac57e
 
    3.1. default_expires (integer)
4480f807
    3.2. default_expires_range (integer)
5961824b
    3.3. expires_range (integer)
    3.4. min_expires (integer)
21904268
    3.5. min_expires_mode (integer)
    3.6. max_expires (integer)
    3.7. default_q (integer)
    3.8. realm_prefix (string)
    3.9. append_branches (integer)
    3.10. aor_avp (str)
    3.11. case_sensitive (integer)
    3.12. received_avp (str)
    3.13. received_param (string)
    3.14. max_contacts (integer)
    3.15. retry_after (integer)
    3.16. sock_flag (integer)
    3.17. sock_hdr_name (string)
b0b2ab6d
    3.18. sock_mode (integer)
28e69c4c
    3.19. method_filtering (integer)
    3.20. use_path (integer)
    3.21. path_mode (integer)
    3.22. path_use_received (integer)
    3.23. path_check_local (integer)
    3.24. reg_callid_avp (string)
    3.25. xavp_cfg (string)
    3.26. xavp_rcd (string)
    3.27. xavp_rcd_mask (int)
    3.28. gruu_enabled (integer)
    3.29. outbound_mode (integer)
    3.30. regid_mode (integer)
    3.31. flow_timer (integer)
    3.32. contact_max_size (integer)
    3.33. event_callback (str)
    3.34. lookup_filter_mode (int)
    3.35. use_expired_contacts (int)
e45ac57e
 
 3.1. default_expires (integer)
 
56a25750
    If the processed message contains neither Expires header fields nor
    expires contact parameters, this value will be used for newly created
    usrloc records. The parameter contains number of second to expire (for
    example use 3600 for one hour). If it is set to a lower value than the
9cb2a163
    “min_expires” parameter then it will be ignored. This parameter can be
4480f807
    modified via ser config framework. A random value in a specific
    interval can be selected by using the default_expires_range parameter
31ccf6a2
 
989206bd
    Default value is 3600.
31ccf6a2
 
d77df08a
    Example 1.1. Set default_expires parameter
31ccf6a2
 ...
 modparam("registrar", "default_expires", 1800)
 ...
 
4480f807
 3.2. default_expires_range (integer)
 
    This parameter specifies that the expiry used for newly created usrloc
b5c5090c
    records are not fixed, but a random value in the interval
9cb2a163
    “[default_expires-default_expires_range%, default_expires]”. The value
8868e624
    is between 0 and 100 and represent the maximum percentage from expires
    that will be subtracted when computing the value. Default is 0, meaning
    default_expires is left unmodified. This parameter can be modified via
    the Kamailio config framework.
4480f807
 
    Default value is 0.
 
    Example 1.2. Set default_expires_range parameter
 ...
d926b2f9
 modparam("registrar", "default_expires_range", 30) # +- 30% from default_expires
4480f807
 ...
 
5961824b
 3.3. expires_range (integer)
 
    Similar to default_expires_range, but it applies to the incoming
b5c5090c
    expires value. Default in 0, meaning the expires is left unmodified.
    This parameter can be modified via the Kamailio config framework.
5961824b
 
    Default value is 0.
 
    Example 1.3. Set expires_range parameter
 ...
 modparam("registrar", "expires_range", 30) # expires within [0.7*expires .. expi
 res]
 ...
 
 3.4. min_expires (integer)
31ccf6a2
 
9cb2a163
    The minimum expires value of a “Contact”. Values lower than this
21904268
    minimum will be either set to the minimum or 423 response is sent back.
    Value 0 disables the checking. This parameter can be modified via the
    Kamailio config framework.
31ccf6a2
 
989206bd
    Default value is 60.
31ccf6a2
 
5961824b
    Example 1.4. Set min_expires parameter
31ccf6a2
 ...
 modparam("registrar", "min_expires", 60)
 ...
 
21904268
 3.5. min_expires_mode (integer)
 
    Control what to do when expires value in REGISTER request is lower than
    min_expires parameter. If set to 0, expires is set to min_expires. If
    set to 1, then 423 Interval Too Brief is sent back.
 
    Default value is 0.
 
    Example 1.5. Set min_expires_mode parameter
 ...
 modparam("registrar", "min_expires_mode", 1)
 ...
 
 3.6. max_expires (integer)
31ccf6a2
 
9cb2a163
    The maximum accepted expires value of a “Contact”, values higher than
b5c5090c
    this maximum will be automatically set to the maximum. Value 0 disables
    the checking. This parameter can be modified via the Kamailio config
    framework.
31ccf6a2
 
989206bd
    Default value is 0.
31ccf6a2
 
21904268
    Example 1.6. Set max_expires parameter
31ccf6a2
 ...
 modparam("registrar", "max_expires", 120)
 ...
 
21904268
 3.7. default_q (integer)
31ccf6a2
 
9cb2a163
    The parameter represents default “q” value for new contacts. Because
e45ac57e
    Kamailio doesn't support float parameter types, the value in the
    parameter is divided by 1000 and stored as float. For example, if you
8b2457cf
    want default_q to be 0.38, use value 380 here. This parameter can be
b5c5090c
    modified via the Kamailio config framework.
31ccf6a2
 
989206bd
    Default value is 0.
31ccf6a2
 
21904268
    Example 1.7. Set default_q parameter
31ccf6a2
 ...
7baba426
 modparam("registrar", "default_q", 1000)
31ccf6a2
 ...
 
21904268
 3.8. realm_prefix (string)
624ef7e8
 
114d674d
    Prefix to be automatically stripped from realm. As an alternative to
    SRV records (not all SIP clients support SRV lookup), a subdomain of
    the master domain can be defined for SIP purposes (like
    sip.mydomain.net pointing to same IP address as the SRV record for
    mydomain.net). By ignoring the realm_prefix "sip.", at registration,
b5c5090c
    sip.mydomain.net will be equivalent to mydomain.net. This parameter can
114d674d
    be modified via the Kamailio config framework.
624ef7e8
 
989206bd
    Default value is NULL (none).
624ef7e8
 
21904268
    Example 1.8. Set realm_prefix parameter
624ef7e8
 ...
 modparam("registrar", "realm_prefix", "sip.")
 ...
 
21904268
 3.9. append_branches (integer)
31ccf6a2
 
e45ac57e
    The parameter controls how lookup function processes multiple contacts.
    If there are multiple contacts for the given username in usrloc and
    this parameter is set to 1, Request-URI will be overwritten with the
    highest-q rated contact and the rest will be appended to sip_msg
    structure and can be later used by tm for forking. If the parameter is
    set to 0, only Request-URI will be overwritten with the highest-q rated
8b2457cf
    contact and the rest will be left unprocessed. This parameter can be
114d674d
    modified via Kamailio config framework.
31ccf6a2
 
989206bd
    Default value is 1.
31ccf6a2
 
21904268
    Example 1.9. Set append_branches parameter
31ccf6a2
 ...
 modparam("registrar", "append_branches", 0)
 ...
 
21904268
 3.10. aor_avp (str)
982b9d7a
 
3417a42c
    This module parameter has been removed. Use the 'uri' parameter from
    functions (e.g., save, lookup, registered).
982b9d7a
 
21904268
 3.11. case_sensitive (integer)
31ccf6a2
 
b0c6ef43
    If set to 1 then AOR comparison and also storing will be case
    sensitive, if set to 0 then AOR comparison and storing will be case
b5c5090c
    insensitive. This is recommended. This parameter can be modified via
114d674d
    Kamailio config framework.
31ccf6a2
 
989206bd
    Default value is 0.
31ccf6a2
 
21904268
    Example 1.10. Set case_sensitive parameter
31ccf6a2
 ...
 modparam("registrar", "case_sensitive", 1)
 ...
 
21904268
 3.12. received_avp (str)
31ccf6a2
 
e45ac57e
    Registrar will store the value of the AVP configured by this parameter
    in the received column in the user location database. It will leave the
    column empty if the AVP is empty. The AVP should contain a SIP URI
b5c5090c
    consisting of the source IP, port, and transport protocol of the
    REGISTER message being processed.
31ccf6a2
 
d77df08a
 Note
31ccf6a2
 
d77df08a
    The value of this parameter should be the same as the value of
    corresponding parameter of nathelper module.
31ccf6a2
 
989206bd
    Default value is "NULL" (disabled).
31ccf6a2
 
21904268
    Example 1.11. Set received_avp parameter
31ccf6a2
 ...
8d9d76ed
 modparam("registrar", "received_avp", "$avp(s:rcv)")
31ccf6a2
 ...
 
21904268
 3.13. received_param (string)
31ccf6a2
 
b5c5090c
    The name of the parameter that will be appended to Contact URI's of 200
9cb2a163
    OK when the received URI was set by the “nathelper” module. If the
b5c5090c
    value is an empty string, then the parameter is not appended anymore.
31ccf6a2
 
989206bd
    Default value is "received".
31ccf6a2
 
21904268
    Example 1.12. Set received_param parameter
31ccf6a2
 ...
 modparam("registrar", "received_param", "rcv")
 ...
 
21904268
 3.14. max_contacts (integer)
31ccf6a2
 
e45ac57e
    The parameter can be used to limit the number of contacts per AOR
7b883f58
    (Address of Record) in the user location database. If the maximum
    number of contacts is exceeded, Kamailio will not accept the
    registration and send an error response. Value 0 disables the check.
    This parameter can be modified via the Kamailio config framework.
    (Please also check the flag for save() if you only want only one active
    registration).
31ccf6a2
 
989206bd
    Default value is 0.
31ccf6a2
 
21904268
    Example 1.13. Set max_contacts parameter
31ccf6a2
 ...
 # Allow no more than 10 contacts per AOR
 modparam("registrar", "max_contacts", 10)
 ...
 
21904268
 3.15. retry_after (integer)
31ccf6a2
 
b5c5090c
    The registrar can generate a 5xx reply to REGISTER requests in various
    situations. It can, for example, happen when the max_contacts parameter
    is set and the processing of REGISTER request would exceed the limit.
    In this case the registrar would generate "503 Service Unavailable"
    response. This parameter can be modified via the Kamailio config
    framework.
31ccf6a2
 
e45ac57e
    If you want to add the Retry-After header field in 5xx replies, set
    this parameter to a value grater than zero (0 means do not add the
    header field). See section 20.33 of RFC3261 for more details.
31ccf6a2
 
989206bd
    Default value is 0 (disabled).
31ccf6a2
 
21904268
    Example 1.14. Set retry_after parameter
31ccf6a2
 ...
 modparam("registrar", "retry_after", 30)
 ...
 
21904268
 3.16. sock_flag (integer)
31ccf6a2
 
b5c5090c
    Message flag to signal to the registrar module to look into REGISTER
    request for a header which contains a socket description (IP:port).
    This socket info will be stored by registrar instead of the received
    socket info.
31ccf6a2
 
114d674d
    This makes sense only in multiple replicated servers scenarios.
31ccf6a2
 
989206bd
    Default value is -1 (no flag).
31ccf6a2
 
21904268
    Example 1.15. Set sock_flag parameter
31ccf6a2
 ...
 modparam("registrar", "sock_flag", 18)
 ...
 
21904268
 3.17. sock_hdr_name (string)
31ccf6a2
 
e45ac57e
    Header which contains a socket description (proto:IP:port) to override
    the received socket info. The header will be read only if the flag
    sock_flag is set.
31ccf6a2
 
114d674d
    This makes sense only in multiple replicated servers scenarios.
31ccf6a2
 
989206bd
    Default value is NULL.
31ccf6a2
 
21904268
    Example 1.16. Set sock_hdr_name parameter
31ccf6a2
 ...
 modparam("registrar", "sock_hdr_name", "Sock-Info")
 ...
 
b0b2ab6d
 3.18. sock_mode (integer)
28e69c4c
 
b0b2ab6d
    If set to 1, the server stores the advertised address in socket field,
    instead of bind address.
28e69c4c
 
    This could be useful when kamailio is installed behind NAT and it is
    necessary to store its public IP instead socket on which the register
    request was received.
 
b0b2ab6d
    Default value is 0 (store bind address).
28e69c4c
 
b0b2ab6d
    Example 1.17. Set sock_mode parameter
28e69c4c
 ...
b0b2ab6d
 modparam("registrar", "sock_mode", 1)
28e69c4c
 ...
 
 3.19. method_filtering (integer)
76af1362
 
e45ac57e
    Tells if the contact filtering based on supported methods should be
ac2572b8
    performed during lookup on initial requests without to-tag. It's
    enabled only if it has a non zero value. Supported methods are listed
    in the “Allow:” header in the REGISTER message and stored in the
    location database.
76af1362
 
989206bd
    Default value is 0 (disabled).
76af1362
 
28e69c4c
    Example 1.18. Set method_filtering parameter
76af1362
 ...
 modparam("registrar", "method_filtering", 1)
 ...
 
28e69c4c
 3.20. use_path (integer)
79bf803d
 
9cb2a163
    If set to 1, the “Path:” header is handled according to the parameter
b5c5090c
    This parameter can be modified via Kamailio config framework.
9cb2a163
    “path_mode”.
79bf803d
 
989206bd
    Default value is 0 (disabled).
79bf803d
 
28e69c4c
    Example 1.19. Set use_path parameter
79bf803d
 ...
 modparam("registrar", "use_path", 1)
 ...
 
28e69c4c
 3.21. path_mode (integer)
e45ac57e
 
    The registrar module implements three different modes regarding the
    response to a registration which includes one or more Path headers:
      * 0 - The Path header is saved into usrloc, but is not included in
        the reply.
      * 1 - The Path header is saved into usrloc, but is only included in
        the reply if path support is indicated in the registration request
9cb2a163
        by the “path” option in the “Supported:” header.
e45ac57e
      * 2 - The path header is only saved into usrloc, if path support is
9cb2a163
        indicated in the registration request by the “path” option of the
        “Supported” header. If no path support is indicated, the request is
        rejected with “420 - Bad Extension” and the header “Unsupported:
        path” is included in the reply along with the received “Path”
e45ac57e
        header. This mode is the one recommended by RFC-3327.
79bf803d
 
989206bd
    Default value is 2.
79bf803d
 
28e69c4c
    Example 1.20. Set path_mode parameter
79bf803d
 ...
 modparam("registrar", "path_mode", 0)
 ...
 
28e69c4c
 3.22. path_use_received (integer)
932053d7
 
9cb2a163
    If set to 1, the “received” parameter of the first Path URI of a
e45ac57e
    registration is set as received-uri and the NAT branch flag is set for
    this contact. This is useful if the registrar is placed behind a SIP
9cb2a163
    loadbalancer, which passes the nat'ed UAC address as “received”
e45ac57e
    parameter in it's Path uri.
932053d7
 
989206bd
    Default value is 0 (disabled).
932053d7
 
28e69c4c
    Example 1.21. Set path_use_received parameter
932053d7
 ...
 modparam("registrar", "path_use_received", 1)
 ...
 
28e69c4c
 3.23. path_check_local (integer)
fe95e1ee
 
    If set to 1, when performing a lookup the Path (if present) is
9cb2a163
    evaluated and if the first hop is local (according to “myself” test),
fe95e1ee
    we skip it to avoid unnecessary looping.
 
    This is useful if multiple servers are sharing a common location
    database, each saving contacts with their local address as the Path.
 
    Default value is 0 (disabled).
 
28e69c4c
    Example 1.22. Set path_check_local parameter
fe95e1ee
 ...
 modparam("registrar", "path_check_local", 1)
 ...
 
28e69c4c
 3.24. reg_callid_avp (string)
f0ed82ce
 
82ea7fd9
    obsolete. use match_option in registered function
 
b5c5090c
    If reg_callid_avp is defined and populated when the registered() is
e45ac57e
    invoked, the result is TRUE only if an active registration with the
    specified callID is found.
f0ed82ce
 
    Default value is NULL (disabled).
 
28e69c4c
    Example 1.23. Set reg_callid_avp parameter
f0ed82ce
 ...
 modparam("registrar", "reg_callid_avp", "$avp(s:avp)")
 ...
 
28e69c4c
 3.25. xavp_cfg (string)
71348e9c
 
    Defines the name of XAVP class to store runtime module config values.
    The values are stored as inner XAVPs, like $xavp(class=>attribute).
    Valid inner XAVP names:
8e54f027
      * expires - the number of maximum contacts to be stored for the
        current registration AoR. It overwrites the 'max_contacts' module
        parameter value.
      * q - the expires value, to overwrite the value from SIP headers.
b5c5090c
      * max_contacts - the number of maximum contacts to be stored for the
71348e9c
        current registration AoR. It overwrites the 'max_contacts' module
        parameter value.
d19c9fc4
      * socket - the string representing the socket on which the register
8868e624
        request was received, as alternative to using the sock_hdr.
71348e9c
 
    For example. if this parameter is set to 'reg', then the number of
    maximum contacts can be set in $xavp(reg=>max_contacts).
 
    Default value is NULL (disabled).
 
28e69c4c
    Example 1.24. Set xavp_cfg parameter
71348e9c
 ...
 modparam("registrar", "xavp_cfg", "reg")
 ...
770c3972
 request_route {
     ...
     $xavp(reg=>max_contacts) = 4;
8e54f027
     $xavp(reg[0]=>expires) = 600;
770c3972
     save("location");
     ...
 }
 ...
71348e9c
 
28e69c4c
 3.26. xavp_rcd (string)
2e1a9d55
 
    Defines the name of XAVP class to store details from the location
    records. The values are stored as inner XAVPs, like
bd08a9b3
    $xavp(class[0]=>attribute). Valid inner XAVP names:
2e1a9d55
      * ruid - the record's internal unique id.
bd08a9b3
      * contact - the record's contact value.
780a37d9
      * expires - the record's expires value.
bd08a9b3
      * received - the record's received value.
fc793348
      * path - the record's path value.
2e1a9d55
 
bd08a9b3
    For example. if this parameter is set to 'ulrcd', then values are set
    in:
      * $xavp(ulrcd[0]=>ruid)
      * $xavp(ulrcd[0]=>contact)
      * $xavp(ulrcd[0]=>received)
fc793348
      * $xavp(ulrcd[0]=>path)
2e1a9d55
 
    Default value is NULL (disabled).
 
28e69c4c
    Example 1.25. Set xavp_rcd parameter
2e1a9d55
 ...
407608df
 modparam("registrar", "xavp_rcd", "ulrcd")
2e1a9d55
 ...
 
28e69c4c
 3.27. xavp_rcd_mask (int)
4b7a2d5b
 
    Defines what values to skip when xavp_rcd is stored.
      * 1 - ruid
      * 2 - contact
      * 4 - expires
      * 8 - received
      * 16 - path
 
    Default value is 0 (none).
 
28e69c4c
    Example 1.26. Set xavp_rcd_mask parameter
4b7a2d5b
 ...
 # skip path value
 modparam("registrar", "xavp_rcd_mask", 16)
 ...
 # skip path and expires values
 modparam("registrar", "xavp_rcd_mask", 20)
 ...
 
28e69c4c
 3.28. gruu_enabled (integer)
21f1a378
 
9cb2a163
    If set to 1 and the “+sip.instance” parameter to Contact header of
21f1a378
    REGISTER is present, then the value of the parameter is saved to
    location and pub-gruu and temp-gruu addresses are generated.
 
    Set it to 0 if you want to ignore GRUU extensions in REGISTER.
 
    Default value is 1 (enabled).
 
28e69c4c
    Example 1.27. Set gruu_enabled parameter
21f1a378
 ...
 modparam("registrar", "gruu_enabled", 0)
 ...
 
28e69c4c
 3.29. outbound_mode (integer)
4cb23b43
 
6b4d87a4
    If set to 0 this module will accept REGISTER requests that do not
9cb2a163
    contain a “Supported:” header with the outbound options-tag. The 200 OK
4cb23b43
    response to REGISTER requests that this module generates will not
9cb2a163
    contain “Require:” or “Supported:” headers with the outbound
    options-tag. If the client has a “Require:” header with the outbound
    options tag the REGISTER will be rejected with a “420 Bad Extension”
b5c5090c
    response.
4cb23b43
 
6b4d87a4
    If set to 1 this module will accept REGISTER requests that do not
9cb2a163
    contain a “Supported:” header with the outbound options-tag and
b5c5090c
    REGISTER requests that do contain a Supported: or Requires: header with
    the outbound options-tag. When the client supports outbound the
    appropriate RFC5626 procedures will be followed.
4cb23b43
 
6b4d87a4
    If set to 2 this module will reject REGISTER requests that do not
9cb2a163
    contain a “Supported:” header with the outbound options-tag. When the
6b4d87a4
    client supports outbound the appropriate RFC5626 procedures will be
    followed.
4cb23b43
 
    Default value is 0.
 
28e69c4c
    Example 1.28. Set outbound_mode parameter
4cb23b43
 ...
 modparam("registrar", "outbound_mode", 2)
 ...
 
28e69c4c
 3.30. regid_mode (integer)
50e9baf2
 
9cb2a163
    If set to 0 this module will ignore the “regid” contact param when
b5c5090c
    saving REGISTER request if the request does not indicate support for
50e9baf2
    outbound.
 
9cb2a163
    If set to 1 this module will use “regid” contact param (if present)
b5c5090c
    when saving REGISTER request even if REGISTER request does not indicate
50e9baf2
    support for outbound.
 
    Default value is 0.
 
28e69c4c
    Example 1.29. Set regid_mode parameter
50e9baf2
 ...
 modparam("registrar", "regid_mode", 1)
 ...
 
28e69c4c
 3.31. flow_timer (integer)
9a10ed33
 
9cb2a163
    If set to 0 then this module will not add a “Flow-Timer:” header to 200
9a10ed33
    OK responses to REGISTER requests.
 
9cb2a163
    If set to > 0 then this module will add a “Flow-Timer:” header
b5c5090c
    containing this value to 200 OK responses to REGISTER requests. This
    parameter may only be set to a value > 0 when outbound_mode is set to 1
    or 2.
 
    When set to a value greater than 0 this parameter should be set to
    slightly less than the connection timeout value between the UAC and the
    network (this corresponds to the core tcp_connection_lifetime option
    and websocket keepalive_timeout modparam). This parameter is most
    useful when you have a single edge proxy/registrar or if you have an
    edge proxy that cannot modify responses. If you are using a separate
    edge proxy you should consider leaving this parameter set to 0 and
9cb2a163
    adding the “Flow-Timer:” header on the edge proxy as this allows you to
b5c5090c
    keep all of the timer values for a specific flow in one configuration.
9a10ed33
 
    Default value is 0.
 
28e69c4c
    Example 1.30. Set flow_timer parameter
9a10ed33
 ...
 modparam("registrar", "flow_timer", 25)
 ...
 
28e69c4c
 3.32. contact_max_size (integer)
6ed325ea
 
    Max size of URIs in “Contact:” header.
 
    The size of URIs in “Contact:” headers are checked to be lower or equal
    to this value. A warning is logged and a 400 Bad Request is sent in
    response to REGISTER requests with contact URIs that are longer than
    this value.
 
    If a database is used then you must make sure that your database model
    supports strings of the configured size in the column “contact” of the
    table specified in “save()” function.
 
18c512e3
    Default value is 512.
6ed325ea
 
28e69c4c
    Example 1.31. Set contact_max_size parameter
6ed325ea
 ...
18c512e3
 modparam("registrar", "contact_max_size", 1024)
6ed325ea
 ...
 
28e69c4c
 3.33. event_callback (str)
9811a92e
 
    The name of the function in the KEMI configuration file (embedded
    scripting language such as Lua, Python, ...) to be executed instead of
    event_route[...] blocks.
 
    The function receives a string parameter with the name of the event.
    The only possible value currently is 'usrloc:contact-expired'.
 
    Default value is 'empty' (no function is executed for events).
 
28e69c4c
    Example 1.32. Set event_callback parameter
9811a92e
 ...
 modparam("registrar", "event_callback", "ksr_registrar_event")
 ...
 -- event callback function implemented in Lua
 function ksr_registrar_event(evname)
     KSR.info( "Expired contact for " .. KSR.pv.getw("$ulc(exp=>aor)") .. "\n");
         return 1;
 end
 ...
 
28e69c4c
 3.34. lookup_filter_mode (int)
770c3972
 
    Control what filters should be applied to lookup(...) operations. It
    can be a combination (sum) of the next values:
      * 1 - apply the branch flags filter - return only contact records
        with branch flags matching at least one set inside xavp specified
        by xavp_cfg parameter with inner name rlf_bflags - e.g.,
        $xavp(reg=>rlf_bflags).
7d41d020
      * 2 - apply the active tcp connection filter - return only contact
        records that have the associated TCP/TLS/WSS connection active. UDP
        and SCTP contacts are not filtered, all are returned.
770c3972
 
    Default value is NULL (disabled).
 
28e69c4c
    Example 1.33. Set xavp_cfg parameter
770c3972
 ...
 modparam("registrar", "xavp_cfg", "reg")
 modparam("registrar", "lookup_filter_mode", 1)
 ...
 request_route {
     ...
     $xavp(reg=>rlf_bflags) = 8;
     if(lookup("location")) { ... }
     ...
 }
 ...
 
28e69c4c
 3.35. use_expired_contacts (int)
957fde95
 
    Allow/Disallow the usage of the expired contacts.
      * 0 Disallow the usage of the expired contacts.
      * 1 Allow the usage of the expired contacts.
 
    Default value is 0 (Disallow).
 
28e69c4c
    Example 1.34. Set use_expired_contacts parameter
957fde95
 ...
 modparam("registrar", "use_expired_contacts", 1)
 ...
 
 kamcmd cfg.set_now_int registrar use_expired_contacts 1
 kamcmd cfg.set_now_int registrar use_expired_contacts 0
 
ba7961bb
 4. Functions
31ccf6a2
 
3417a42c
    4.1. save(domain, [, flags [, uri]])
    4.2. lookup(domain [, uri])
b52757f8
    4.3. lookup_to_dset(domain [, uri])
    4.4. lookup_branches(domain)
    4.5. registered(domain [, uri [, match_option [, match_action]]])
    4.6. add_sock_hdr(hdr_name)
    4.7. unregister(domain, uri[, ruid])
    4.8. reg_fetch_contacts(domain, uri, profile)
    4.9. reg_free_contacts(profile)
    4.10. reg_send_reply()
31ccf6a2
 
9cb2a163
 4.1.  save(domain, [, flags [, uri]])
e45ac57e
 
    The function processes a REGISTER message. It can add, remove or modify
56a25750
    location records (in usrloc) depending on Contact and Expires header
    fields in the REGISTER message. On success and when called from the
9cb2a163
    REQUEST_ROUTE, “200 OK” will be returned listing all contacts that are
658cb496
    currently in the location database. As a side effect, also branch flags
    are stored in usrloc. On an error, an error message will be sent with a
    short description in reason phrase.
31ccf6a2
 
    Meaning of the parameters is as follows:
b5c5090c
      * domain - Logical domain within the registrar. If a database is used
        then this must be name of the table which stores the contacts.
3417a42c
      * flags (optional) - the value may be a bitwise OR of the following
        flags:
56a25750
           + 0x01 - save the contacts only in memory cache with no DB
e45ac57e
             operation;
           + 0x02 - do not generate a SIP reply to the current REGISTER
             request. When used in ONREPLY_ROUTE, this parameter is
             obsolete.
           + 0x04 - store and maintain one contact per AoR. If there are
             other contact addresses for AoR not matching current
             registration, remove them. This mode ensures one contact per
             AoR (user).
55975adc
           + 0x08 - Do not apply expires_range or default_expires_range to
             this registration.
8868e624
        The flags may be given in decimal or hexadecimal format.
3417a42c
      * uri (optional - flags param has to be set and can be 0 for default
        behavior) - SIP URI to do be used instead of To header URI. It can
        be a dynamic string with pseudo-variables.
31ccf6a2
 
3417a42c
    Return codes:
f6443567
      * -2 - error, too many contacts for AOR.
        -1 - error.
3417a42c
        1 - contacts inserted.
        2 - contacts updated.
        3 - contacts deleted.
        4 - contacts returned.
bfcbd22f
 
664b2f30
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE and
    REPLY_ROUTE.
3417a42c
 
28e69c4c
    Example 1.35. save usage
624ef7e8
 ...
3417a42c
 save("location");
 save("location", "0x01");
 save("location", "0x00", "sip:test@kamailio.org");
624ef7e8
 ...
 
9cb2a163
 4.2.  lookup(domain [, uri])
31ccf6a2
 
b5c5090c
    The lookup function extracts username and/or domain from Request-URI
    and tries to find all contacts for the username in usrloc. If there are
    no such contacts, -1 will be returned. If there are such contacts,
    Request-URI will be overwritten with the contact that has the highest q
    value and optionally the rest will be appended to the message
658cb496
    (depending on append_branches parameter value). As a side effect, also
    branch flags are restored from usrloc.
31ccf6a2
 
ac2572b8
    If the method_filtering option is enabled and request is initial
    request without to-tag, the lookup function will return only the
    contacts that support the method of the processed request.
76af1362
 
31ccf6a2
    Meaning of the parameters is as follows:
      * domain - Name of table that should be used for the lookup.
3417a42c
      * uri (optional) - SIP URI to do be used instead of R-URI. It can be
        a dynamic string with pseudo-variables.
31ccf6a2
 
76af1362
    Return codes:
      * 1 - contacts found and returned.
        -1 - no contact found.
        -2 - contacts found, but method not supported.
56853adf
        -3 - internal error during processing.
76af1362
 
bfcbd22f
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
 
28e69c4c
    Example 1.36. lookup usage
31ccf6a2
 ...
 lookup("location");
b52757f8
                         switch ($retcode) {:1
 
76af1362
     case -1:
     case -3:
         sl_send_reply("404", "Not Found");
         exit;
     case -2:
         sl_send_reply("405", "Not Found");
         exit;
 };
31ccf6a2
 ...
 
b52757f8
 4.3.  lookup_to_dset(domain [, uri])
 
    Similar to lookup(...), but push the location contacts to destination
    set, without changing the R-URI (first branch not changed, it creates
    additional branches). For the meaning of the parameters and the return
    codes, see the documentation for lookup(...) function.
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
 
    Example 1.37. lookup_to_dset usage
 ...
 lookup_to_dset("location");
 ...
 
 4.4.  lookup_branches(domain)
bb7bc779
 
    The function performs lookup(domain) on r-uri and additional branches
    (only branches that have no other attributes set than uri).
 
    Meaning of the parameters is as follows:
      * domain - Name of table that should be used for the lookup.
 
b5c5090c
    Return codes are propagated from the lookup(domain) function.
bb7bc779
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
 
b52757f8
    Example 1.38. lookup_branches usage
bb7bc779
 ...
 lookup_branches("location");
 ...
 
b52757f8
 4.5.  registered(domain [, uri [, match_option [, match_action]]])
31ccf6a2
 
b0a776b3
    The function returns true if the AOR in the URI is registered, false
    otherwise. The function does not modify the message being process, it
    neither rewrites the Request-URI if a contact is found nor append
    branches. If uri parameter is not provided, then it considered to be
    the Request-URI for SIP requests and To-URI for SIP replies.
31ccf6a2
 
    Meaning of the parameters is as follows:
      * domain - Name of table that should be used for the lookup.
b0a776b3
      * uri (optional) - SIP URI to do be used instead of Request/To-URI.
        It can be a dynamic string with pseudo-variables.
82ea7fd9
      * match_option (optional) - flag parameter to restrict contact
        search. use reg_xavp_cfg to set the values to compare to.
        flag values is as follows:
           + 1 - match_callid
           + 2 - match_received
           + 4 - match_contact
      * match_action (optional) - actions to perform when match is
        positive.
        flag values is as follows:
de5fdc07
           + 1 - restore the xavps associated with the matched contact
           + 2 - skip adding the matched location record attributes to
             xavp_rcd (e.g., the ruid, contact, received, ...)
31ccf6a2
 
b0a776b3
    This function can be used from ANY_ROUTE.
bfcbd22f
 
b52757f8
    Example 1.39. registered usage
31ccf6a2
 ...
 if (registered("location")) {
         sl_send_reply("100", "Trying");
         ...
 };
 ...
82ea7fd9
 $xavp(regcfg=>match_received) = $su;
 if (registered("location","$rz:$Au", 2)) {
         sl_send_reply("100", "Trying");
         ...
 };
 ...
31ccf6a2
 
b52757f8
 4.6.  add_sock_hdr(hdr_name)
31ccf6a2
 
9cb2a163
    Adds a new header to the current REGISTER request with “hdr_name” which
e45ac57e
    contains the description of the received socket (proto:ip:port)
31ccf6a2
 
b5c5090c
    This makes sense only in multiple replicated servers scenarios.
31ccf6a2
 
    Meaning of the parameters is as follows:
e45e3b53
      * hdr_name - header name to be used, it can be a static string or
        contain variables.
31ccf6a2
 
bfcbd22f
    This function can be used from REQUEST_ROUTE.
 
b52757f8
    Example 1.40. add_sock_hdr usage
31ccf6a2
 ...
 add_sock_hdr("Sock-Info");
 ...
1061d103
 
b52757f8
 4.7.  unregister(domain, uri[, ruid])
b235af63
 
b5c5090c
    The function removes contacts associated with 'uri' from the location
    database. If 'ruid' is provided a specific contact is removed, if
    'ruid' is not provided all the current contacts are removed. If 'ruid'
9cb2a163
    is provided and the “usrloc” module is using “db_mode=3”, 'uri' does
b5c5090c
    not need to be given and can be empty string.
b235af63
 
    Meaning of the parameters is as follows:
e45ac57e
      * domain - Name of table that should be used for the lookup or
        contact addresses.
      * uri - The SIP URI address of the user which to remove the contact
        addresses for. It can contain pseudo-variables that are evaluated
        at runtime.
71c197df
      * ruid - The record unique ID for a a specific contact to be removed.
        It can contain pseudo-variables that are evaluated at runtime.
b235af63
 
8546983d
    This function can be used from ANY_ROUTE.
b235af63
 
51f07e7b
    Return values:
      * 0 - Successfully deleted contact(s)
      * -1 - Failed to extract or parse address of record from argument
      * -2 - Error in unregistering user
      * -3 - Contacts for AOR not found
 
b52757f8
    Example 1.41. unregister usage
b235af63
 ...
 unregister("location", "$ru");
 unregister("location", "sip:user@kamailio.org");
71c197df
 unregister("location", "$ru", "$ulc(caller=>ruid)");
6c385398
 unregister("location", "", "$ruid");
b235af63
 ...
 
b52757f8
 4.8.  reg_fetch_contacts(domain, uri, profile)
7a67411c
 
e45ac57e
    The function fetches the contacts for 'uri' from table 'domain' to
    pseudo-variable $ulc(profile).
7a67411c
 
    Meaning of the parameters is as follows:
e45ac57e
      * domain - Name of table that should be used for the lookup of
        contact addresses.
      * uri - The SIP URI address of the user which to fetch the contact
        addresses for. It can contain pseudo-variables that are evaluated
        at runtime.
      * profile - Name of $ulc pseudo-variable profile that will store the
        fetched contacts. It is a static string.
7a67411c
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
 
b52757f8
    Example 1.42. reg_fetch_contacts usage
7a67411c
 ...
 reg_fetch_contacts("location", "$ru", "callee");
 reg_fetch_contacts("location", "sip:user@kamailio.org", "caller");
 ...
 
b52757f8
 4.9.  reg_free_contacts(profile)
7a67411c
 
e45ac57e
    The function frees the contacts from pseudo-variable $ulc(profile).
    Should be called to release the content of a profile. Anyhow, fetching
    a new contact addresses set over a profile will release any existing
    data in that profile.
7a67411c
 
    Meaning of the parameters is as follows:
e45ac57e
      * profile - Name of $ulc pseudo-variable profile that stores fetched
        contacts. It is a static string.
7a67411c
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
 
b52757f8
    Example 1.43. reg_free_contacts usage
7a67411c
 ...
 reg_free_contacts("callee");
 ...
 
b52757f8
 4.10.  reg_send_reply()
5bd5df36
 
    The function sends the SIP reply that is normally sent by save(...),
    but that was skipped due to flag 0x2. It must be used after save(...,
    "0x2"). Practically it allows saving registration to location table, do
    other operations and then send the reply.
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
 
b52757f8
    Example 1.44. reg_send_reply usage
5bd5df36
 ...
 save("location", "0x2");
 ...
 reg_send_reply();
 ...
 
83410304
 5. Event Routes
 
    5.1. event_route[usrloc:contact-expired]
 
 5.1. event_route[usrloc:contact-expired]
 
    Executed when a contact in location table has expired. The variable
    $ulc(exp=>...) is filled with the attributes of the expired contact.
 
b52757f8
    Example 1.45. event_route[usrloc:contact-expired] usage
83410304
 ...
 event_route[usrloc:contact-expired] {
84457e88
     xlog("expired contact for $ulc(exp=>aor)\n");
83410304
 }
 ...
 
 6. Statistics
e45ac57e
 
83410304
    6.1. max_expires
    6.2. max_contacts
a91b2b68
    6.3. default_expires
83410304
    6.4. accepted_regs
    6.5. rejected_regs
1061d103
 
83410304
 6.1. max_expires
1061d103
 
    Value of max_expires parameter.
 
83410304
 6.2. max_contacts
1061d103
 
    The value of max_contacts parameter.
 
a91b2b68
 6.3. default_expires
1061d103
 
    The value of default_expires parameter.
 
83410304
 6.4. accepted_regs
1061d103
 
    Number of accepted registrations.
 
83410304
 6.5. rejected_regs
1061d103
 
    Number of rejected registrations.
31ccf6a2
 
83410304
 7. Pseudo Variables
7a67411c
 
83410304
    7.1. $ulc(profile=>attr)
7a67411c
 
83410304
 7.1. $ulc(profile=>attr)
e45ac57e
 
    Access the attributes of contact addresses stored in 'profile'. It must
9cb2a163
    be used after a call of “reg_fetch_contacts()”.
7a67411c
 
9cb2a163
    The “profile” has to be one of the values used with
    “reg_fetch_contacts()”.
7a67411c
 
9cb2a163
    The “attr” can be:
7a67411c
      * aor - address of record
49c198a4
      * domain - used location domain/table name
7a67411c
      * aorhash - hash id for the record
      * addr - contact address
      * path - path vector
      * received - received address
      * expires - expires value
      * callid - call-id header value
      * q - the q value
71c197df
      * cseq - the cseq value
7a67411c
      * flags - flags value
      * cflags - cflags value
      * user_agent - user agent
      * socket - local socket
      * modified - last modified time
      * methods - methods value
71c197df
      * count - number of contacts
      * ruid - record unique ID
b420f856
      * regid - reg-id value
71c197df
      * instance - instance value
824c31c2
      * conid - TCP socket internal connection ID ($null if UDP)
dda77dd0
      * server_id - server_id value
7a67411c
 
e45ac57e
    The pseudo-variable accepts positive index value to access a specific
    contact record.
7a67411c
 
b52757f8
    Example 1.46. $ulc(name) usage
7a67411c
 ...
 if(reg_fetch_contacts("location", "$fu", "caller"))
 {
740c1bbd
   xlog("caller=>aor: $(ulc(caller=>aor))\n");
   xlog("caller=>domain: $(ulc(caller=>domain))\n");
   xlog("caller=>aorhash $(ulc(caller=>aorhash))\n");
   xlog("caller=>count $(ulc(caller=>count))\n");
   $var(i) = 0;
   while($var(i) < $(ulc(caller=>count)))
   {
     xlog("--- contact [$var(i)]\n");
     xlog("caller=>addr:       $(ulc(caller=>addr)[$var(i)])\n");
     xlog("caller=>path:       $(ulc(caller=>path)[$var(i)])\n");
     xlog("caller=>received:   $(ulc(caller=>received)[$var(i)])\n");
     xlog("caller=>expires:    $(ulc(caller=>expires)[$var(i)])\n");
     xlog("caller=>callid:     $(ulc(caller=>callid)[$var(i)])\n");
b420f856
     xlog("caller=>regid:      $(ulc(caller=>regid)[$var(i)])\n");
740c1bbd
     xlog("caller=>q:          $(ulc(caller=>q)[$var(i)])\n");
     xlog("caller=>cseq:       $(ulc(caller=>cseq)[$var(i)])\n");
     xlog("caller=>flags:      $(ulc(caller=>flags)[$var(i)])\n");
     xlog("caller=>cflags:     $(ulc(caller=>cflags)[$var(i)])\n");
     xlog("caller=>user_agent: $(ulc(caller=>user_agent)[$var(i)])\n");
     xlog("caller=>socket:     $(ulc(caller=>socket)[$var(i)])\n");
     xlog("caller=>modified:   $(ulc(caller=>modified)[$var(i)])\n");
     xlog("caller=>methods:    $(ulc(caller=>methods)[$var(i)])\n");
     $var(i) = $var(i) + 1;
   }
7a67411c
 }
 ...
 
033b5989
 Chapter 2. Frequently Asked Questions
31ccf6a2
 
abddba32
    2.1. What happened with the old “nat_flag” module parameter?
    2.2. What happened with the old “use_domain” module parameter?
9cb2a163
    2.3. What happened with the old “save_noreply” and “save_memory”
e45ac57e
           functions?
 
    2.4. Where can I find more about Kamailio?
    2.5. Where can I post a question about this module?
    2.6. How can I report a bug?
    2.7. What happened to the desc_time_order parameter?
 
d77df08a
    2.1.
 
abddba32
    What happened with the old “nat_flag” module parameter?
f565de5a
 
b420f856
    In was removed, as the module internally loads this value from the
9cb2a163
    “USRLOC” module (see the “nat_bflag” USRLOC parameter).
d77df08a
 
    2.2.
 
abddba32
    What happened with the old “use_domain” module parameter?
f565de5a
 
b420f856
    In was removed, as the module internally loads this option from the
9cb2a163
    “USRLOC” module. This was done in order to simplify the configuration.
bf3705d3
 
d77df08a
    2.3.
4c5fb67e
 
9cb2a163
    What happened with the old “save_noreply” and “save_memory” functions?
f565de5a
 
9cb2a163
    There functions were merged into the new “save(domain,flags)”
b420f856
    functions. If a reply should be sent or if the DB should be updated
    also is controlled via the flags.
bf3705d3
 
d77df08a
    2.4.
bf3705d3
 
b420f856
    Where can I find more about Kamailio?
f565de5a
 
ff1bcdb4
    Take a look at https://www.kamailio.org/.
31ccf6a2
 
d77df08a
    2.5.
31ccf6a2
 
b420f856
    Where can I post a question about this module?
f565de5a
 
b420f856
    First at all check if your question was already answered on one of our
    mailing lists:
      * User Mailing List -
ff1bcdb4
        https://lists.kamailio.org/cgi-bin/mailman/listinfo/sr-users
b420f856
      * Developer Mailing List -
ff1bcdb4
        https://lists.kamailio.org/cgi-bin/mailman/listinfo/sr-dev
31ccf6a2
 
b420f856
    E-mails regarding any stable Kamailio release should be sent to
ff1bcdb4
    <sr-users@lists.kamailio.org> and e-mails regarding development
    versions should be sent to <sr-dev@lists.kamailio.org>.
989206bd
 
d77df08a
    2.6.
31ccf6a2
 
b420f856
    How can I report a bug?
f565de5a
 
b420f856
    Please follow the guidelines provided at:
8acdb08d
    https://github.com/kamailio/kamailio/issues.
31ccf6a2
 
d77df08a
    2.7.
1c8ce5f4
 
b420f856
    What happened to the desc_time_order parameter?
1c8ce5f4
 
b420f856
    It was removed, as its functionality was migrated into usrloc module,
    were there is a parameter with the same name.