registrar Module
     __________________________________________________________

   Table of Contents

   1. Admin Guide

        1.1. Overview

              1.1.1. Path Support (RFC 3327)
              1.1.2. GRUU Support (RFC 5627)
              1.1.3. SIP Push Notification Support (RFC 8599)

        1.2. Dependencies

              1.2.1. OpenSIPS Modules
              1.2.2. External Libraries or Applications

        1.3. Exported Parameters

              1.3.1. default_expires (integer)
              1.3.2. min_expires (integer)
              1.3.3. max_expires (integer)
              1.3.4. default_q (integer)
              1.3.5. tcp_persistent_flag (string)
              1.3.6. realm_prefix (string)
              1.3.7. case_sensitive (integer)
              1.3.8. received_avp (str)
              1.3.9. received_param (string)
              1.3.10. max_contacts (integer)
              1.3.11. max_username_len (integer)
              1.3.12. max_domain_len (integer)
              1.3.13. max_aor_len (integer)
              1.3.14. max_contact_len (integer)
              1.3.15. retry_after (integer)
              1.3.16. sock_hdr_name (string)
              1.3.17. mcontact_avp (string)
              1.3.18. attr_avp (string)
              1.3.19. gruu_secret (string)
              1.3.20. disable_gruu (int)
              1.3.21. pn_enable (boolean)
              1.3.22. pn_providers (string)
              1.3.23. pn_ct_match_params (string)
              1.3.24. pn_pnsreg_interval (integer)
              1.3.25. pn_trigger_interval (integer)
              1.3.26. pn_skip_pn_interval (integer)
              1.3.27. pn_refresh_timeout (integer)
              1.3.28. pn_enable_purr (boolean)

        1.4. Exported Functions

              1.4.1. save(domain[, flags[, aor[, ownership_tag]]])

              1.4.2. remove(domain, AOR[, [contact][, [next_hop][,
                      [sip_instance]]]])

              1.4.3. lookup(domain [, flags [, aor]])
              1.4.4. is_registered(domain ,[AOR])
              1.4.5. is_contact_registered(domain
                      ,[AOR],[contact],[callid])

              1.4.6. is_ip_registered(domain ,[AOR],IPvar)
              1.4.7. add_sock_hdr(hdr_name)

        1.5. Exported Asynchronous Functions

              1.5.1. pn_process_purr(domain)

        1.6. Exported Statistics

              1.6.1. max_expires
              1.6.2. max_contacts
              1.6.3. defaults_expires
              1.6.4. accepted_regs
              1.6.5. rejected_regs

   2. Frequently Asked Questions
   3. Contributors

        3.1. By Commit Statistics
        3.2. By Commit Activity

   4. Documentation

        4.1. Contributors

   List of Tables

   3.1. Top contributors by DevScore^(1), authored commits^(2) and
          lines added/removed^(3)

   3.2. Most recently active contributors^(1) to this module

   List of Examples

   1.1. Set default_expires parameter
   1.2. Set min_expires parameter
   1.3. Set max_expires parameter
   1.4. Set default_q parameter
   1.5. Set tcp_persistent_flag parameter
   1.6. Set realm_prefix parameter
   1.7. Set case_sensitive parameter
   1.8. Set received_avp parameter
   1.9. Set received_param parameter
   1.10. Set max_contacts parameter
   1.11. Setting the max_username_len module parameter
   1.12. Setting the max_domain_len module parameter
   1.13. Setting the max_aor_len module parameter
   1.14. Setting the max_contact_len module parameter
   1.15. Set retry_after parameter
   1.16. Set sock_hdr_namer parameter
   1.17. Set mcontact_avp parameter
   1.18. Set attr_avp parameter
   1.19. Set gruu_secret parameter
   1.20. Set gruu_secret parameter
   1.21. Setting the pn_enable parameter
   1.22. Setting the pn_providers parameter
   1.23. Setting the pn_ct_match_params parameter
   1.24. Setting the pn_pnsreg_interval parameter
   1.25. Setting the pn_trigger_interval parameter
   1.26. Setting the pn_skip_pn_interval parameter
   1.27. Setting the pn_refresh_timeout parameter
   1.28. Setting the pn_enable_purr parameter
   1.29. save usage
   1.30. remove usage
   1.31. lookup usage
   1.32. is_registered usage
   1.33. is_contact_registered usage
   1.34. is_ip_registered usage
   1.35. add_sock_hdr usage
   1.36. async pn_process_purr() usage

Chapter 1. Admin Guide

1.1. Overview

   The module contains SIP REGISTER request processing logic, per
   RFC 3261. On top of this support, several extensions are
   available:

1.1.1. Path Support (RFC 3327)

   The registrar module includes SIP Path header field support
   according to RFC 3327, for usage in registrars and
   home-proxies.

   A call to save() stores, if path support is enabled in the
   registrar module, the values of the Path Header(s) along with
   the Contact information into usrloc. There are three modes for
   building the reply to a REGISTER message which includes one or
   more Path header fields:
     * off - stores the value of the Path headers into usrloc
       without passing it back to the UAC in the reply.
     * lazy - stores the Path header and passes it back to the UAC
       if Path-support is indicated by the “path” param in the
       Supported HF.
     * strict - rejects the registration with “420 Bad Extension”
       if there's a Path header but no support for it is indicated
       by the UAC. Otherwise it's stored and passed back to the
       UAC.

   A call to lookup() always uses the Path header if found, and
   inserts it as Route HF either in front of the first Route HF,
   or after the last Via HF if no Route is present. It also sets
   the destination URI to the first Path URI, thus overwriting the
   received-URI, because NAT has to be handled at the
   outbound-proxy of the UAC (the first hop after client's NAT).

   The whole process is transparent to the user, so no config
   changes are required besides enabling one of the "p0" / "p1" /
   "p2" flags when calling save().

1.1.2. GRUU Support (RFC 5627)

   The registrar module includes support for Globally Routable
   User Agent URIs according to RFC 5627.

   A call to save() stores, if the phone supports GRUU, the values
   of the SIP Instance along with the contact into usrloc. The
   module will generate two types of GRUUs:
     * public - exposes the underlying AOR, constructed just by
       attaching the SIP Instance as the ;gr parameter value.
       These are persistent, valid as long as the contact
       registration is valid.
     * temporary - hides the underlying AOR Each new Register
       request leads to the construction of a new temporary GRUU,
       while Register requests with a different Call-ID lead to
       the invalidation of all the previous generated temporary
       GRUUs.

   A call to lookup() will try to detect if the R-URI contains a
   GRUU. If it does, it will route the request just for the
   Contact that the specific AOR belongs to, without appending any
   other branches.

   Even if the the GRUU handling during the registration process
   is transparent to the user, so no config changes are required,
   you need to take care of the GRUU specifics when handling
   mid-dialog requests.

   As the GRUU will be present in the contact header of the
   initial requests generated byt GRUU enabled devices, you will
   have to also do a lookup() when receiving a mid-dialog request
   with the GRUU indication in the RURI.

1.1.3. SIP Push Notification Support (RFC 8599)

   The registrar module includes support for standards-based SIP
   Push Notifications, per RFC 8599. Support for the basic version
   of the draft can be enabled by switching pn_enable to true. The
   module also includes optional support for sending Push
   Notifications during long-lived dialogs (see RFC section 6),
   through the pn_enable_purr switch.

   Essential mechanics behind the Push Notification (PN) support:
     * the PN support is fully compatible with the existing logic
       and enabling it does not impose any limitations, as the
       registrar can simultaneously handle both SIP PN compliant
       and standard SIP User Agents
     * OpenSIPS will raise a E_UL_CONTACT_REFRESH event any time a
       Push Notification needs to be sent to a PN-enabled contact.
       The event includes the PN coordinates of the contact --
       they may be found in the Contact URI ('uri' event
       parameter) and may be extracted using the {uri.param,name}
       transformation. From here onwards, it is up to the script
       developer to trigger the Push Notification, thus forcing a
       re-registration from the device (e.g. possibly by sending
       an HTTP POST with the rest_client module)
     * REGISTER processing is unchanged -- PN-enabled UAs are
       saved just as regular UAs, with the former ones
       additionally having the 4 bitflag set in the "Flags" field
       of any MI listing of contacts, for differentiation purposes
     * initial INVITE processing is barely changed, with the
       lookup() function now additionally returning a value of 2
       if the only found contacts were PN-enabled contacts, all
       which required a Push Notification. This means that PNs
       have been triggered for each of them and t_relay() is not
       required, since they are not reachable until they
       re-register!
       Using the event_routing module, OpenSIPS will transparently
       fork a new branch from the current INVITE on each
       re-registration from these contacts within the accepted
       pn_refresh_timeout
     * mid-dialog requests: In some cases (e.g. long-lived
       dialogs), a PN may be required before being able to route a
       mid-dialog request to a SIP UA. The pn_process_purr() async
       function will take care of triggering the PN event and
       resuming the script as soon as a re-registration from the
       concerned contact is received.

   For more information or examples, refer to the documentation of
   the "pn_xxx" module parameters or the OpenSIPS blog posts
   around the "SIP Push Notification" topic.

1.2. Dependencies

1.2.1. OpenSIPS Modules

   The following modules must be loaded before this module:
     * usrloc - User Location Module.
     * signaling - Signaling module.

1.2.2. External Libraries or Applications

   The following libraries or applications must be installed
   before running OpenSIPS with this module loaded:
     * None.

1.3. Exported Parameters

1.3.1. default_expires (integer)

   If the processed message contains neither Expires HFs nor
   expires contact parameters, this value will be used for newly
   created usrloc records. The parameter contains number of second
   to expire (for example use 3600 for one hour).

   Default value is 3600.

   Example 1.1. Set default_expires parameter
...
modparam("registrar", "default_expires", 1800)
...

1.3.2. min_expires (integer)

   The minimum expires value of a Contact, values lower than this
   minimum will be automatically set to the minimum. Value 0
   disables the checking.

   Default value is 60.

   Example 1.2. Set min_expires parameter
...
modparam("registrar", "min_expires", 60)
...

1.3.3. max_expires (integer)

   The maximum expires value of a Contact, values higher than this
   maximum will be automatically set to the maximum. Value 0
   disables the checking.

   Default value is 0.

   Example 1.3. Set max_expires parameter
...
modparam("registrar", "max_expires", 120)
...

1.3.4. default_q (integer)

   The parameter represents default q value for new contacts.
   Because OpenSIPS doesn't support float parameter types, the
   value in the parameter is divided by 1000 and stored as float.
   For example, if you want default_q to be 0.38, use value 380
   here.

   Default value is 0.

   Example 1.4. Set default_q parameter
...
modparam("registrar", "default_q", 1000)
...

1.3.5. tcp_persistent_flag (string)

   The parameter specifies the message flag to be used to control
   the module behaviour regarding TCP connections. If the flag is
   set for a REGISTER via TCP containing a TCP contact, the
   module, via the “save()” function, will set the lifetime of the
   TCP connection to the contact expire value. By doing this, the
   TCP connection will stay on as long as the contact is valid.

   Default value is -1 (disabled).

   Example 1.5. Set tcp_persistent_flag parameter
...
modparam("registrar", "tcp_persistent_flag", "TCP_PERSIST_DURATION")
...

1.3.6. realm_prefix (string)

   Prefix to be automatically strip from realm. As an alternative
   to SRV records (not all SIP clients support SRV lookup), a
   subdomain of the master domain can be defined for SIP purposes
   (like sip.mydomain.net pointing to same IP address as the SRV
   record for mydomain.net). By ignoring the realm_prefix "sip.",
   at registration, sip.mydomain.net will be equivalent to
   mydomain.net .

   Default value is NULL (none).

   Example 1.6. Set realm_prefix parameter
...
modparam("registrar", "realm_prefix", "sip.")
...

1.3.7. case_sensitive (integer)

   If set to 1 then AOR comparison will be case sensitive (as
   RFC3261 instructs), if set to 0 then AOR comparison will be
   case insensitive.

   Default value is 1.

   Example 1.7. Set case_sensitive parameter
...
modparam("registrar", "case_sensitive", 0)
...

1.3.8. received_avp (str)

   Registrar will store the value of the AVP configured by this
   parameter in the received column in the user location database.
   It will leave the column empty if the AVP is empty. The AVP
   should contain a SIP URI consisting of the source IP, port, and
   protocol of the REGISTER message being processed.

Note

   The value of this parameter should be the same as the value of
   corresponding parameter of nathelper module.

   Default value is "NULL" (disabled).

   Example 1.8. Set received_avp parameter
...
modparam("registrar", "received_avp", "$avp(rcv)")
...

1.3.9. received_param (string)

   The name of the parameter that will be appended to Contacts of
   200 OK when the received URI was set by nathelper module.

   Default value is "received".

   Example 1.9. Set received_param parameter
...
modparam("registrar", "received_param", "rcv")
...

1.3.10. max_contacts (integer)

   The parameter can be used to limit the number of contacts per
   AOR (Address of Record) in the user location database. Value 0
   disables the check.

   This is the default value and will be used only if no other
   value (for max_contacts) is passed as parameter to the save()
   function. That's it - the function parameter overwride this
   global parameter.

   Default value is 0.

   Example 1.10. Set max_contacts parameter
...
# Allow no more than 10 contacts per AOR
modparam("registrar", "max_contacts", 10)
...

1.3.11. max_username_len (integer)

   The maximum length of the "username" part of an
   Address-of-Record SIP URI.

   Default value is 64.

   Example 1.11. Setting the max_username_len module parameter
modparam("registrar", "max_username_len", 128)

1.3.12. max_domain_len (integer)

   The maximum length of the "domain" part of an Address-of-Record
   SIP URI.

   Default value is 64.

   Example 1.12. Setting the max_domain_len module parameter
modparam("registrar", "max_domain_len", 128)

1.3.13. max_aor_len (integer)

   The maximum length of an Address-of-Record SIP URI.

   Default value is 256.

   Example 1.13. Setting the max_aor_len module parameter
modparam("registrar", "max_aor_len", 512)

1.3.14. max_contact_len (integer)

   The maximum length of a Contact header field SIP URI.

   Default value is 255.

   Example 1.14. Setting the max_contact_len module parameter
modparam("registrar", "max_contact_len", 512)

1.3.15. retry_after (integer)

   The registrar can generate 5xx reply to REGISTER in various
   situations. It can, for example, happen when the max_contacts
   parameter is set and the processing of REGISTER request would
   exceed the limit. In this case the registrar would generate
   "503 Service Unavailable" response.

   If you want to add the Retry-After header field in 5xx replies,
   set this parameter to a value grater than zero (0 means do not
   add the header field). See section 20.33 of RFC3261 for more
   details.

   Default value is 0 (disabled).

   Example 1.15. Set retry_after parameter
...
modparam("registrar", "retry_after", 30)
...

1.3.16. sock_hdr_name (string)

   Header which contains a socket description (proto:IP:port) to
   override the received socket info. The header will be search
   and used only if the flag 's' (Socket header) is set at
   "save()" time.

   This makes sense only in multiple replicated servers scenarios.

   Default value is NULL.

   Example 1.16. Set sock_hdr_namer parameter
...
modparam("registrar", "sock_hdr_name", "Sock-Info")
...

1.3.17. mcontact_avp (string)

   AVP to store the modified binding/contact that is set during
   cached registrations scenario (when REGISTER is forwarded to
   another registrar). The AVP will be used to extract the
   "expires" value returned in the 200 OK by the main registrar.

   This makes sense only in cached registrations scenario, where
   your OpenSIPS is caching registrations before forwarding them
   to the main registrar.

   Default value is NULL.

   Example 1.17. Set mcontact_avp parameter
...
modparam("registrar", "mcontact_avp", "$avp(orig_ct)")
...
route {
   ...
   # before forwarding the REGISTER request, save the outgoing contact.
   # Be SURE to do it after all the possible changes over the contact,
   # like fix_nated_contact()
   $avp(orig_ct) = $ct.fields(uri);
   t_on_reply("do_save");
   t_relay("udp:ip:port");
   ...
}
...
onreply_route[do_save] {
        if ($rs=="200")
                save("location");
}
...

1.3.18. attr_avp (string)

   AVP to store specific additional information for each
   registration. This information is read from the AVP and stored
   (in memory, db or both) at every registrar 'save'. When a
   registrar 'lookup' or 'is_registered' function is called, the
   attr_avp is populated with the value saved at [re]registration.

   When doing call forking, the avp will hold multiple values. The
   position of the corresponding attribute information in attr_avp
   is equal to the branch index. An example scenario is given
   below.

   Default value is NULL.

   Example 1.18. Set attr_avp parameter
# reading attributes from the attr_pvar when doing parallel forking
...
modparam("registrar", "attr_avp", "$avp(attr)")

...
if (is_method("REGISTER")) {
        $avp(attr) = "contact_info";
        save("location");
        exit;
}
...
lookup("location");
t_on_branch("parallel_fork");
...
branch_route [parallel_fork] {
        xlog("Attributes for branch $T_branch_idx: $(avp(attr)[$T_branch
_idx])\n");
}


1.3.19. gruu_secret (string)

   The string that will be used in XORing when generating
   temporary GRUUs.

   If not set, 'OpenSIPS' is the default secret.

   Example 1.19. Set gruu_secret parameter
...
modparam("registrar", "gruu_secret", "top_secret")
...

1.3.20. disable_gruu (int)

   Globally disable GRUU handling

   Default value is 1 ( GRUU will not be handled ).

   Example 1.20. Set gruu_secret parameter
...
modparam("registrar", "disable_gruu", 0)
...

1.3.21. pn_enable (boolean)

   Enable SIP Push Notification support (RFC 8599). If enabled,
   Contact header field URIs which include all pn_ct_match_params
   will be matched against existing bindings using only these
   parameters. Otherwise, the module will attempt to match them as
   usual, using the current usrloc matching_mode.

   Default value is false.

   Example 1.21. Setting the pn_enable parameter
...
modparam("registrar", "pn_enable", true)
...

1.3.22. pn_providers (string)

   A list of supported Push Notification providers. While only
   three possible values are defined by RFC 8599 ("apns", "fcm"
   and "webpush"), non-standard values may be specified as well.

   Default value is NULL (not set).

   Example 1.22. Setting the pn_providers parameter
...
modparam("registrar", "pn_providers", "apns, fcm, webpush")
...

1.3.23. pn_ct_match_params (string)

   The minimally required list of RFC 8599 parameters (custom ones
   are accepted as well) which must be present in a Contact URI
   and identically match an existing binding in order for the
   binding to be refreshed. If at least one such parameter is
   missing from a Contact header field URI, the module will fall
   back to performing regular contact matching.

   Note that if all above PN Contact URI parameters match an
   existing binding, the match is considered to be successful
   regardless if other parts of the SIP URI do not match (e.g.
   hostname, port, other URI parameters, etc.).

   After calling lookup() or pn_process_purr(), the above
   PN-related parameters will be automatically stripped from the
   resulting Request and Contact URI event parameter,
   respectively.

   Default value is "pn-provider, pn-prid, pn-param".

   Example 1.23. Setting the pn_ct_match_params parameter
...
modparam("registrar", "pn_ct_match_params", "pn-provider, pn-prid")
...

1.3.24. pn_pnsreg_interval (integer)

   For devices capable of waking up and refreshing their binding
   on their own (signified by the ";+sip.pnsreg" Contact header
   field parameter), this setting denotes the prior-to-expiration
   interval advertised by the server at which the device should
   issue its binding refresh request.

   Default value is 130 (seconds before expiry).

   Example 1.24. Setting the pn_pnsreg_interval parameter
...
modparam("registrar", "pn_pnsreg_interval", 140)
...

1.3.25. pn_trigger_interval (integer)

   If a binding refresh REGISTER request from a given SIP endpoint
   does not arrive within at least pn_trigger_interval seconds
   prior to expiration (e.g. because the device does not support
   ";+sip.pnsreg" or because of other error conditions), the
   E_UL_CONTACT_REFRESH usrloc event will be triggered.

   Once E_UL_CONTACT_REFRESH is triggered, the script writer
   should use the RFC 8599 parameters from the Contact URI in
   order to generate a Push Notification request to the PN
   provider of the device, in order to cause the device to wake up
   and re-register.

   Default value is 120 (seconds before expiry).

   Example 1.25. Setting the pn_trigger_interval parameter
...
modparam("registrar", "pn_trigger_interval", 130)
...

1.3.26. pn_skip_pn_interval (integer)

   Following a successful (re)registration of a contact, this
   setting denotes a time interval, in seconds, during which the
   contact is assumed to be reachable, so any Push Notifications
   will be skipped.

   Default value is 0 seconds (always generate Push
   Notifications).

   Example 1.26. Setting the pn_skip_pn_interval parameter
...
modparam("registrar", "pn_skip_pn_interval", 10)
...

1.3.27. pn_refresh_timeout (integer)

   This timeout starts counting following a lookup() or a
   pn_process_purr() which triggers a Push Notification. The value
   represents the maximum allowed sum of the duration required for
   the Push Notification to be sent and the duration required for
   the corresponding re-registration from the device to arrive.

   Once this timeout is exceeded for an initial or a mid-dialog
   request, any further re-registrations which match the pending
   Push Notification will no longer cause the desired effects. For
   example:
     * pending initial INVITE transactions will complete and will
       no longer auto-fork an additional branch for each REGISTER
       sent by the callee side
     * pending BYE messages will time out and OpenSIPS will
       attempt to route them despite not having received a
       confirmation that the target device is actually reachable

   Default value is 6 seconds.

   Example 1.27. Setting the pn_refresh_timeout parameter
...
modparam("registrar", "pn_refresh_timeout", 10)
...

1.3.28. pn_enable_purr (boolean)

   Enable the SIP Push Notification mechanism for long-lived
   dialogs. If enabled, the registrar will include a
   "+sip.pnspurr" Feature-Caps header field tag in 200 OK replies
   to REGISTER requests. This tag represents a unique identifier
   for the registration (PURR - Proxy Unique Registration
   Reference).

   For each initial request for dialog, the UA may include the
   PURR received from the registrar in its Contact header (using
   the ";pn-purr" URI parameter) if it expects to be first awoken
   by a Push Notification before being able to receive mid-dialog
   request sent by the callee side.

   When enabling this parameter, make sure to also add logic for
   pn_process_purr().

   Default value is false.

   Example 1.28. Setting the pn_enable_purr parameter
...
modparam("registrar", "pn_enable_purr", true)
...

1.4. Exported Functions

1.4.1.  save(domain[, flags[, aor[, ownership_tag]]])

   The function processes a REGISTER message. It can add, remove
   or modify usrloc records depending on Contact and Expires HFs
   in the REGISTER message. On success, 200 OK will be returned
   listing all contacts that are currently in usrloc. On an error,
   error message will be send with a short description in reason
   phrase.

   Meaning of the parameters is as follows:
     * domain (static string) - Logical domain within registrar.
       If database is used then this must be name of the table
       which stores the contacts.
     * flags (string, optional) - string of the following flags:
          + 'm' (Memory only) - save the contacts only in memory
            cache without no DB operation;
          + 'r' (no Reply) - do not generate a SIP reply to the
            current REGISTER request.
          + 's' (Socket header) - look into REGISTER request for a
            header which contains a socket description
            (proto:IP:port). This socket info will be stored by
            register instead of the received socket info.
          + 'cnn' (max Contacts) - this flag can be used to limit
            the number of contacts for this AOR (Address of
            Record) in the user location database. Value 0
            disables the check. This parameter overrides the
            global "max_contacts" module parameter.
          + 'e(int)' (minimum expires) - this flag can be used to
            set minimum register expiration time. Values lower
            than this minimum will be automatically set to the
            minimum. Value 0 disables the checking. This parameter
            overrides the global min_expires module parameter.
          + 'E(int)' (maximum expires) - this flag can be used to
            set maximum register expiration time. Values higher
            than this maximum will be automatically set to the
            maximum. Value 0 disables the checking. This parameter
            overrides the global max_expires module parameter.
          + 'f' (force registration) - this flag can be used to
            force the registration of NEW contacts even if the
            maximum number of contacts is reached. In such a case,
            older contacts will be removed to make space to the
            new ones, without exceeding the maximum allowed
            number. This flag makes sense only if "cxx" is used.
          + 'o' (Only request contacts) - Only include the
            REGISTER request's Contacts in the 200 OK reply, in
            case the registration is successful. While this is
            against RFC 3261, it may be useful in certain
            scenarios.
          + 'Mxx' (contact Matching mode) - How the matching
            should be performed between the uploaded contacts (by
            the currently handled REGISTER) and the already know
            contacts (in memory or DB). This options will be used
            only for the current operation and can be:
               o 'M0' - contact URI matching only
               o 'M1' - contact URI and SIP Call-ID matching
               o 'M<param_name>' - only the value of the given URI
                 param will be used for matching (for example
                 M<rinstance>)
          + 'p0' (Path support - 'off' mode) The Path header is
            saved into usrloc, but is never included in the reply.
          + 'p1' (Path support - lazy mode) The Path header is
            saved into usrloc, but is only included in the reply
            if path support is indicated in the registration
            request by the “path” option of the “Supported”
            header.
          + 'p2' (Path support - strict mode) The path header is
            only saved into usrloc, if path support is indicated
            in the registration request by the “path” option of
            the “Supported” header. If no path support is
            indicated, the request is rejected with “420 - Bad
            Extension” and the header “Unsupported: path” is
            included in the reply along with the received “Path”
            header. This mode is the one recommended by RFC-3327.
          + 'v' (path receiVed) if set, the “received” parameter
            of the first Path URI of a registration is set as
            received-uri and the NAT branch flag is set for this
            contact. This is useful if the registrar is placed
            behind a SIP loadbalancer, which passes the nat'ed UAC
            address as “received” parameter in it's Path uri.
       This parameter is a string composed of a set of flags.
     * aor (string, optional) - a custom AOR; if missing, the AOR
       will be taken from the default place - the TO header URI.
     * ownership_tag (string, optional) - a cluster-shared tag
       (see the clusterer module documentation for more details)
       which will be attached to each contact saved from the
       current request. This tag is only relevant in clustered
       user location scenarios and helps determine the current
       logical owner node of a contact. This, in turn, is useful
       in order to restrict nodes which are not currently
       responsible for this contact from performing certain
       actions (for example: incorrectly originating pings from a
       non-owned virtual IP address in highly-available setups).

   This function can be used from REQUEST_ROUTE and ONREPLY_ROUTE.

   If you plan to use the “save()” function in reply route, please
   refer to mcontact_avp module parameter.

   Example 1.29. save usage
...
# save into 'location', no flags, use default AOR (TO URI)
save("location");
...
# save into 'location', do not update DB, max 5 contacts per AOR,
# use default AOR (TO URI)
save("location","mc5");
...
# save into 'location', no flags, use as AOR the FROM URI
save("location","",$fu);
...
# save into 'location', no DB update, force registration, take AOR from
AVP
save("location","mr", $avp(aor));
...
# save into 'location', mark the contacts with the "vip" ownership tag a
nd
# replicate these contacts to the backup node, which does not currently
own "vip"
save("location", , , "vip");
...

1.4.2.  remove(domain, AOR[, [contact][, [next_hop][,
[sip_instance]]]])

   Explicitly remove contacts behind a given address-of-record.

   Meaning of the parameters is as follows:
     * domain (static string - Logical domain within the
       registrar. If a database is used, then this must be name of
       the table which stores the contacts.
     * AOR (string) - address-of-record to be searched (SIP URI)
     * contact (string, optional) - SIP URI filter for the contact
       to be removed. This must be the full SIP URI as used during
       registered.
     * next_hop (string, optional) - the next SIP IP
       address/hostname on the way back to this contact. See the
       section below for details on how the next hop is computed.
       Hostnames are resolved before matching.
     * sip_instance (string, optional) - a "+sip.instance" value
       to be used for filtering purposes.

   IMPORTANT: the IP address of each contact (for matching
   purposes) is computed as follows:
     * a. if a Path header is present, the hostname part of the
       Path URI will be resolved as the contact's IP address.
     * b. otherwise, if by using nathelper, the "Received" value
       (source IP of the next hop) is set for a contact, this
       becomes the chosen hostname to be resolved as the contact's
       IP address.
     * c. otherwise, the "hostname" part of the Contact header
       field URI is chosen to be resolved as the contact's IP
       address.

   This function can be used from REQUEST_ROUTE and ONREPLY_ROUTE.

   Example 1.30. remove usage
...
# remove all contacts belonging to the "bob" AOR
remove("location", "sip:bob@atlanta.com");
...
# remove only bob's home phone contact
remove("location", "sip:bob@atlanta.com", "sip:bob@46.50.64.78");
...
# remove all bob's phones which are behind "50.60.50.60"
# note that "contact" parameter has to be specified with NULL value even
 though not used
$var(next_hop) = "50.60.50.60"
remove("location", "sip:bob@atlanta.com", , $var(next_hop));
...
# remove bob's phone with contact "sip:bob@46.50.64.78" that is behind "
50.60.50.60"
remove("location", "sip:bob@atlanta.com", "sip:bob@46.50.64.78", "50.60.
50.60");
...
# remove all contacts behind bob's mobile device X
remove("location", "sip:bob@atlanta.com", , , "<urn:uuid:e5e68d40-f08a-4
600-b82e-ff4d5d8c1a8f>")

1.4.3.  lookup(domain [, flags [, aor]])

   The functions extracts username from Request-URI and tries to
   find all contacts for the username in usrloc. If there are no
   such contacts, -1 will be returned. If there are such contacts,
   Request-URI will be overwritten with the contact that has the
   highest q value and optionally the rest will be appended to the
   message (depending on append_branches parameter value).

   If the method_filtering option is enabled, the lookup function
   will return only the contacts that support the method of the
   processed request.

   Meaning of the parameters is as follows:
     * domain (static string) - Name of table that should be used
       for the lookup.
     * flags (string, optional)
          + 'b' (no Branches) - this flag controls how the
            lookup() function processes multiple contacts. If
            there are multiple contacts for the given username in
            usrloc and this flag is not set, Request-URI will be
            overwritten with the highest-q rated contact and the
            rest will be appended to sip_msg structure and can be
            later used by tm for forking. If the flag is set, only
            Request-URI will be overwritten with the highest-q
            rated contact and the rest will be left unprocessed.
          + 'B' (to Branches only) - this flags forces all found
            contacts to be uploaded only as branches (in the
            destination set) and not at all in the R-URI of the
            current message. Using this option allows the lookup()
            function to also be used in the context of a SIP
            reply.
          + 'r' (bRanch lookup) - this flag enables searching
            through existing branches for aor's and expanding them
            to contacts. For example, you have got AOR A in your
            ruri but you also want to forward your calls to AOR B.
            In order to do this, you must put AOR B in a branch,
            and if this flag enabled, the function will also
            expand AOR B to contacts, which will be put back into
            the branches. The AOR's that were in branches before
            the function call shall be removed.
            WARNING: if you want this flag activated, the 'b' (no
            Branches) flag must not be set, because by setting
            that flag you won't allow lookup() to write in a
            branch.
          + 'm' (Method filtering) - setting this flag will enable
            contact filtering based on the supported methods
            listed in the "Allow" header field during
            registration. Contacts which did not present an
            "Allow" header field during registration are assumed
            to support all standard SIP methods.
          + 'u' (User-Agent filtering) - this flag enables regexp
            filtering by user-agent. It's useful with enabled
            append_branches parameter. Regexp must follow the 'u'
            flag and must use format like 'u/regexp/'.
          + 'i' (Case insensitive search) - this flag enables case
            insensitive filtering for the 'u' flag.
          + 'e' (Use extended regexp) - this flag enables using of
            extended regexp format for the 'u' flag.
          + 'g' (Global lookup) - this flag is only relevant with
            federated user location clustering. If set, the
            lookup() function will not only perform the classic
            in-memory "search-AoR-and-push-branches" operation,
            but will also perform a metadata lookup and append an
            additional branch for each returned result. The
            "in-memory branches" correspond to local contacts
            (current location), while the "metadata branches"
            correspond to contacts available on one or more of the
            remaining locations of the platform.
            The AoR metadata consists of the minimally required
            information in order for one of the VoIP platform's
            locations (data centers) to advertise the presence of
            a locally registered AoR for the global platform.
            Specifically, this consists of two pieces of
            information:
               o the AoR (e.g. "vladimir@federation-cluster")
               o the home IP (e.g. "10.0.0.223")
          + 'yXXXXX' (Max pinging latency) - maximally accepted
            contact pinging latency (microseconds). Contacts of an
            AoR with a higher latency will be discarded during
            lookup().
          + 'Y' (Sort by pinging latency) - contacts will be
            picked in ascending order of their last successful
            pinging latency (fastest ping -> slowest ping). This
            flag may work together with the "y" flag.
     * AOR (string, optional) - AOR to lookup for; if missing, the
       RURI is used as AOR;

   Return codes:
     * 1 - contacts found and successfully pushed as branches.
       Contacts which required awakening prior to being reachable
       are being notified via async Push Notifications.
     * 2 - successfully started at least one async Push
       Notification for the found contacts, however no extra
       branches were populated (i.e. there is no need to call
       t_relay()).
     * -1 - no contact found.
     * -2 - contacts found, but neither of them supports the
       current SIP method.
     * -3 - internal error during processing.

   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.

   Example 1.31. lookup usage
...
lookup("location");  # simple lookup
   #or
lookup("location","m"); # lookup with method filtering
   #or
lookup("location","r"); #lookup with aor branch search;
                                                #all contacts except the
 first one shall be put
                                                #in the branches
   #or
lookup("location","u/phone/i"); # lookup with user-agent filtering
   #or
lookup("location","",$var(aor)); # simple lookup with AOR from var
switch ($retcode) {
    case -1:
    case -3:
        sl_send_reply(404, "Not Found");
        exit;
    case -2:
        sl_send_reply(405, "Not Found");
        exit;
};
...

1.4.4.  is_registered(domain ,[AOR])

   The function returns true if an AOR is registered, false
   otherwise. The function does not modify the message being
   process.

   NOTE: if called for a reply (from onreply_route), you must pass
   an AOR (as parameter), otherwise the function will fail.

   Meaning of the parameters is as follows:
     * domain (static string) - Name of table that should be used
       for the lookup.
     * AOR (string, optional) - AOR to lookup for; if missing, the
       source if the AOR is the "To" header for REGISTER request,
       "From" header for any other sip request.

   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
   BRANCH_ROUTE, ONREPLY_ROUTE, LOCAL_ROUTE.

   Example 1.32. is_registered usage
...
/**/
if (is_method("REGISTER")) {
        /* automatically uses the URI from the To header */
        if (is_registered("location")) {
                xlog("this AOR is registered\n")
                ...
        }
};
/* check the From uri whether this aor is registered or not */
if (is_registered("location",$fu)) {
        xlog("caller is registered\n");
}
...

1.4.5.  is_contact_registered(domain ,[AOR],[contact],[callid])

   The function returns true if a contact and/or a callid from a
   certain AOR is registered, false otherwise. The function does
   not modify the message being process.

   Meaning of the parameters is as follows:
     * domain (static string) - Name of table that should be used
       for the lookup.
     * AOR (string, optional) - AOR to lookup for; if missing, the
       source if the AOR is the "To" header for REGISTER request,
       "From" header for any other sip request.
     * contact (contact, optional) (optional)- SIP URI to check if
       there is a registration with this URI as cotact (this may
       help you to make distinction between multiple registrations
       for the same user/AOR).
     * callid (string, optional) - callid to check if a contact if
       registered with this callid (this may help you to make
       distinction between newly registered contact (callid not
       registered so far) and re-registration (callid already
       registered).

   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
   BRANCH_ROUTE, ONREPLY_ROUTE, LOCAL_ROUTE.

   Example 1.33. is_contact_registered usage
...
/*let's say you want to block users that are not registered*/
if (is_method("INVITE")) {
        if (!is_contact_registered("location")) {
                sl_send_reply(401, "Unauthorized");
        ...
        }
}
/* you want to check the second contact from the message whether it is
registered or not */
if(is_method("INVITE")) {
        if (is_contact_registered("location",$fu,$(ct[1]),))
                xlog("caller is registered\n");
}
...

1.4.6.  is_ip_registered(domain ,[AOR],IPvar)

   The function returns true if there is at least one contact that
   has been registered from the IP in the IPvar variable. The IP
   is matched against the received host, if it exists, or the
   contact host otherwise. This function does not modify the
   message being process. This function replaces the old
   "is_other_contact" function.

   Meaning of the parameters is as follows:
     * domain (static string) - Name of table that should be used
       for the lookup.
     * AOR (string, optional) - AOR to lookup for; if missing, the
       source if the AOR is the "To" header for REGISTER request,
       "From" header for any other sip request.
     * IPvar (var) - the variable containing the IP matched
       against the contact host or the received host (see above).
       If the IPvar is an AVP containing multiple values/IPs, then
       all the values are checked.

   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
   BRANCH_ROUTE, ONREPLY_ROUTE, LOCAL_ROUTE.

   Example 1.34. is_ip_registered usage
...
/* check the source ip  whether it is already registered */
if (is_method("REGISTER")) {
        if (is_ip_registered("location",$tu,$si)) {
                xlog("already registered from this ip\n");
                ...
        }
};
...

1.4.7.  add_sock_hdr(hdr_name)

   Adds to the current REGISTER request a new header with
   “hdr_name” which contains the description of the received
   socket (proto:ip:port)

   This makes sense only in multiple replicated servers scenarios.

   Meaning of the parameters is as follows:
     * hdr_name (string) - header name to be used.

   This function can be used from REQUEST_ROUTE.

   Example 1.35. add_sock_hdr usage
...
add_sock_hdr("Sock-Info");
...

1.5. Exported Asynchronous Functions

1.5.1.  pn_process_purr(domain)

   Perform mid-dialog request processing, according to RFC 8599.
   For such requests, search the R-URI and topmost Route header
   field URI for a ";pn-purr" parameter value that both matches
   the OpenSIPS PURR format and corresponds to an usrloc
   registration. Once a usrloc contact is located, trigger an
   E_UL_CONTACT_REFRESH event and place the request on async hold
   for at most pn_refresh_timeout seconds, until a matching Push
   Notification arrives.

   If processing ends before triggering the Push Notification, the
   request will no longer block and the resume route will be
   immediately called.

   Meaning of the parameters is as follows:
     * domain (static string) - Logical domain within registrar.
       If a database is used, then this must be name of the table
       which stores the contacts.

   Return Codes
     * 1 - Success, PN was launched.
     * 2 - Success, but PN was not launched (due to missing PURR,
       foreign PURR or offline contact)
     * -1 - Internal Error

   Example 1.36. async pn_process_purr() usage
route {
        ...
        if (has_totag()) {
                if (is_method("ACK") && t_check_trans()) {
                        t_relay();
                        exit;
                }

                if (!loose_route()) {
                        send_reply(404, "Not Found");
                        exit;
                }

                if (!is_method("ACK"))
                        async (pn_process_purr("location"), resume_route
);

                route(relay);
                exit;
        }
}

route [resume_route] {
        $var(rc) = $rc;
        xlog("pn_process_purr() finished with $var(rc)\n");

        ...
}

1.6. Exported Statistics

1.6.1. max_expires

   Value of max_expires parameter.

1.6.2. max_contacts

   The value of max_contacts parameter.

1.6.3. defaults_expires

   The value of default_expires parameter.

1.6.4. accepted_regs

   Number of accepted registrations.

1.6.5. rejected_regs

   Number of rejected registrations.

Chapter 2. Frequently Asked Questions

   2.1.

   What happened with the old “append_branch” module parameter?

   It was removed as global option, as the “lookup” function takes
   this option via the flag "b" (append Branches) See the
   documentation of the “lookup” function.

   2.2.

   What happened with the old “method_filtering” module parameter?

   It was removed as global option, as the “lookup” function takes
   this option via the flag "m" (Method filtering) See the
   documentation of the “lookup” function.

   2.3.

   What happened with the old “sock_flag” module parameter?

   It was removed as global option, as the “save” function takes
   this option via the flag "s" (Socket header) See the
   documentation of the “save” function.

   2.4.

   What happened with the old “use_path” and “path_mode” module
   parameters?

   They were removed as global option, as the “save” function
   takes these options via the flag "px" (path support) See the
   documentation of the “save” function.

   2.5.

   What happened with the old “path_use_received” module
   parameter?

   It was removed as global option, as the “save” function takes
   this option via the flag "v" (path receiVed) See the
   documentation of the “save” function.

   2.6.

   What happened with the old “nat_flag” module parameter?

   It was removed, as the module internally loads this value from
   the “USRLOC” module (see the “nat_bflag” USRLOC parameter).

   2.7.

   What happened with the old “use_domain” module parameter?

   It was removed, as the module internally loads this option from
   the “USRLOC” module. This was done in order to simplify the
   configuration.

   2.8.

   What happened with the old “save_noreply” and “save_memory”
   functions?

   There functions were merged into the new “save(domain,flags)”
   functions. If a reply should be sent or if the DB should be
   updated also is controlled via the flags.

   2.9.

   Where can I find more about OpenSIPS?

   Take a look at https://opensips.org/.

   2.10.

   Where can I post a question about this module?

   First at all check if your question was already answered on one
   of our mailing lists:
     * User Mailing List -
       http://lists.opensips.org/cgi-bin/mailman/listinfo/users
     * Developer Mailing List -
       http://lists.opensips.org/cgi-bin/mailman/listinfo/devel

   E-mails regarding any stable OpenSIPS release should be sent to
   <users@lists.opensips.org> and e-mails regarding development
   versions should be sent to <devel@lists.opensips.org>.

   If you want to keep the mail private, send it to
   <users@lists.opensips.org>.

   2.11.

   How can I report a bug?

   Please follow the guidelines provided at:
   https://github.com/OpenSIPS/opensips/issues.

   2.12.

   What happened to the desc_time_order parameter?

   It was removed, as its functionality was mmigrate into usrloc
   module, were there is a parameter with the same name.

Chapter 3. Contributors

3.1. By Commit Statistics

   Table 3.1. Top contributors by DevScore^(1), authored
   commits^(2) and lines added/removed^(3)
     Name DevScore Commits Lines ++ Lines --
   1. Liviu Chircu (@liviuchircu) 176 104 2752 2982
   2. Bogdan-Andrei Iancu (@bogdan-iancu) 166 112 2380 2031
   3. Jan Janak (@janakj) 120 73 3465 1102
   4. Daniel-Constantin Mierla (@miconda) 23 19 160 105
   5. Razvan Crainea (@razvancrainea) 19 14 265 73
   6. Vlad Paiu (@vladpaiu) 16 10 489 81
   7. Ionut Ionita (@ionutrazvanionita) 16 4 763 248
   8. Jiri Kuthan (@jiriatipteldotorg) 15 9 538 45
   9. Andreas Granig 13 7 527 36
   10. Vlad Patrascu (@rvlad-patrascu) 13 4 163 373

   All remaining contributors: Henning Westerholt (@henningw),
   Andrei Pelinescu-Onciul, Ovidiu Sas (@ovidiusas), Juha Heinanen
   (@juha-h), Nick Altmann (@nikbyte), Ancuta Onofrei,
   Elena-Ramona Modroiu, Maksym Sobolyev (@sobomax), Peter
   Lemenkov (@lemenkov), Dan Pascu (@danpascu), Sergio Gutierrez,
   Carsten Bock, Jeffrey Magder, Kobi Eshun (@ekobi), Marcus
   Hunger, Julián Moreno Patiño, Phil D'Amore, Klaus Darilion,
   Irina-Maria Stanescu, Dmitry Semyonov, Konstantin Bokarius,
   Jesus Rodrigues, Dusan Klinec, Ruslan Bukin, Saúl Ibarra
   Corretgé (@saghul), @jalung, Tolga Tarhan, Edson Gellert
   Schubert.

   (1) DevScore = author_commits + author_lines_added /
   (project_lines_added / project_commits) + author_lines_deleted
   / (project_lines_deleted / project_commits)

   (2) including any documentation-related commits, excluding
   merge commits. Regarding imported patches/code, we do our best
   to count the work on behalf of the proper owner, as per the
   "fix_authors" and "mod_renames" arrays in
   opensips/doc/build-contrib.sh. If you identify any
   patches/commits which do not get properly attributed to you,
   please submit a pull request which extends "fix_authors" and/or
   "mod_renames".

   (3) ignoring whitespace edits, renamed files and auto-generated
   files

3.2. By Commit Activity

   Table 3.2. Most recently active contributors^(1) to this module
                      Name                   Commit Activity
   1.  Liviu Chircu (@liviuchircu)         Mar 2013 - Jul 2020
   2.  Peter Lemenkov (@lemenkov)          Jun 2018 - Feb 2020
   3.  Bogdan-Andrei Iancu (@bogdan-iancu) Sep 2003 - Nov 2019
   4.  Razvan Crainea (@razvancrainea)     Apr 2011 - Sep 2019
   5.  Vlad Patrascu (@rvlad-patrascu)     May 2017 - Apr 2019
   6.  @jalung                             Aug 2017 - Aug 2017
   7.  Ovidiu Sas (@ovidiusas)             May 2011 - Mar 2017
   8.  Ionut Ionita (@ionutrazvanionita)   Jul 2015 - Feb 2017
   9.  Julián Moreno Patiño                Feb 2016 - Feb 2016
   10. Dusan Klinec                        Dec 2015 - Dec 2015

   All remaining contributors: Nick Altmann (@nikbyte), Vlad Paiu
   (@vladpaiu), Tolga Tarhan, Saúl Ibarra Corretgé (@saghul),
   Ruslan Bukin, Irina-Maria Stanescu, Kobi Eshun (@ekobi), Phil
   D'Amore, Sergio Gutierrez, Klaus Darilion, Henning Westerholt
   (@henningw), Daniel-Constantin Mierla (@miconda), Konstantin
   Bokarius, Edson Gellert Schubert, Jesus Rodrigues, Dan Pascu
   (@danpascu), Ancuta Onofrei, Marcus Hunger, Juha Heinanen
   (@juha-h), Elena-Ramona Modroiu, Jeffrey Magder, Carsten Bock,
   Andreas Granig, Dmitry Semyonov, Maksym Sobolyev (@sobomax),
   Jan Janak (@janakj), Andrei Pelinescu-Onciul, Jiri Kuthan
   (@jiriatipteldotorg).

   (1) including any documentation-related commits, excluding
   merge commits

Chapter 4. Documentation

4.1. Contributors

   Last edited by: Liviu Chircu (@liviuchircu), Bogdan-Andrei
   Iancu (@bogdan-iancu), Vlad Patrascu (@rvlad-patrascu), Peter
   Lemenkov (@lemenkov), Razvan Crainea (@razvancrainea), Ionut
   Ionita (@ionutrazvanionita), Julián Moreno Patiño, Nick Altmann
   (@nikbyte), Vlad Paiu (@vladpaiu), Ovidiu Sas (@ovidiusas),
   Irina-Maria Stanescu, Kobi Eshun (@ekobi), Sergio Gutierrez,
   Klaus Darilion, Daniel-Constantin Mierla (@miconda), Konstantin
   Bokarius, Edson Gellert Schubert, Jesus Rodrigues, Marcus
   Hunger, Juha Heinanen (@juha-h), Elena-Ramona Modroiu, Carsten
   Bock, Andreas Granig, Jan Janak (@janakj).

   Documentation Copyrights:

   Copyright © 2003 FhG FOKUS

   Copyright © 2020 OpenSIPS Solutions
