registrar Module

Jan Janak

   FhG FOKUS

Edited by

Jan Janak

Edited by

Bogdan-Andrei Iancu

   Copyright © 2003 FhG FOKUS
   Revision History
   Revision $Revision: 8740 $ $Date$
     __________________________________________________________

   Table of Contents

   1. Admin Guide

        1.1. Overview

              1.1.1. PATH support
              1.1.2. GRUU support

        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 (integer)
              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. retry_after (integer)
              1.3.12. sock_hdr_name (string)
              1.3.13. mcontact_avp (string)
              1.3.14. attr_avp (string)
              1.3.15. gruu_secret (string)
              1.3.16. disable_gruu (int)

        1.4. Exported Functions

              1.4.1. save(domain [,flags ,[aor]])
              1.4.2. remove(domain, AOR[, target])
              1.4.3. lookup(domain [, flags [, aor]])
              1.4.4. registered(domain [,AOR[, callid]])
              1.4.5. is_other_contact(domain , IPs)
              1.4.6. add_sock_hdr(hdr_name)

        1.5. Exported Statistics

              1.5.1. max_expires
              1.5.2. max_contacts
              1.5.3. defaults_expires
              1.5.4. accepted_regs
              1.5.5. rejected_regs

   2. Frequently Asked Questions

   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. Set retry_after parameter
   1.12. Set sock_hdr_namer parameter
   1.13. Set mcontact_avp parameter
   1.14. Set attr_avp parameter
   1.15. Set gruu_secret parameter
   1.16. Set gruu_secret parameter
   1.17. save usage
   1.18. remove usage
   1.19. lookup usage
   1.20. registered usage
   1.21. is_other_contact usage
   1.22. add_sock_hdr usage

Chapter 1. Admin Guide

1.1. Overview

   The module contains REGISTER processing logic.

1.1.1. PATH support

   Register module includes Path 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 into usrloc. There are three modes regarding the
   reply to a REGISTER including one or more Path HFs:
     * 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 beside setting the registrar-parameters
   “use_path” and “path_mode”.

1.1.2. GRUU support

   Register module includes GRUU support (according to RFC 5627)
   for usage in registrars and home-proxies.

   A call to save(...) stores, if the phone supports GRUU, the
   values of the SIP Instance along with the contact into usrloc.
   The registrar 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.

   The whole process is transparent to the user, so no config
   changes are required.

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 (integer)

   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", 7)
...

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 paramter 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. 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.11. Set retry_after parameter
...
modparam("registrar", "retry_after", 30)
...

1.3.12. 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.12. Set sock_hdr_namer parameter
...
modparam("registrar", "sock_hdr_name", "Sock-Info")
...

1.3.13. mcontact_avp (string)

   AVP to store the modified binding that is set during cached
   registrations scenario (when REGISTER is forwarded to another
   registrar). The AVP will be used to extract the imposed expires
   from the 200ok reply.

   This makes sense only in cached registrations scenario.

   Default value is NULL.

   Example 1.13. Set mcontact_avp parameter
...
modparam("registrar", "mcontact_avp", "$avp(register)")
...

1.3.14. 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 '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.14. 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("branch_route_1");
...
branch_route[branch_route_1] {
        xlog("Attributes for branch $T_branch_idx: $(avp(attr)[$T_branch
_idx])\n");
}


1.3.15. 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.15. Set gruu_secret parameter
...
modparam("registrar", "gruu_secret", "top_secret")
...

1.3.16. disable_gruu (int)

   Globally disable GRUU handling

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

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

1.4. Exported Functions

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

   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 - Logical domain within registrar. If database is
       used then this must be name of the table which stores the
       contacts.
     * flags (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.
          + '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 (optional) - Variable contain a custom AOR; if missing,
       the AOR will be taken from the default place - the TO
       header URI.

   This function can be used from REQUEST_ROUTE and ONREPLY_ROUTE.

   Example 1.17. 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, no reply to send, take AOR from AVP
save("location","mr", "$avp(aor)");
...

1.4.2.  remove(domain, AOR[, target])

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

   Meaning of the parameters is as follows:
     * domain - Logical domain within registrar. If database is
       used then this must be name of the table which stores the
       contacts.
     * AOR - address-of-record to be searched (SIP URI)
     * target (optional) - may be specified in two ways:
          + single delete - Specific contact to be deleted (SIP
            URI)
          + multi delete - IP/hostname of the AOR's contacts which
            will be deleted

   This function can be used from REQUEST_ROUTE and ONREPLY_ROUTE.

   Example 1.18. remove usage
...
# remove all contacts belonging to the "bob" AOR
remove("location", "sip:bob@atlanta.com");
...
# remove only bob's home phone
remove("location", "sip:bob@atlanta.com", "sip:bob@46.50.64.78");
...
# remove all bob's phones which are behind "50.60.50.60"
$var(next_hop) = "50.60.50.60"
remove("location", "sip:bob@atlanta.com", "$var(next_hop)");
...

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 - Name of table that should be used for the lookup.
     * flags(optional)
          + 'b' (no Branches) - this flag controls how 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.
          + 'm' (Method filtering) - this flag tells if the
            contact filtering based on supported methods should be
            performed during lookup.
          + '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.
     * AOR (optional)- AOR to lookup for; if missing, the RURI is
       used as AOR; This must be a variable.

   Return codes:
     * 1 - contacts found and returned.
       -1 - no contact found.
       -2 - contacts found, but method not supported.
       -3 - internal error during processing.

   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.

   Example 1.19. lookup usage
...
lookup("location");  # simple lookup
   #or
lookup("location","m"); # lookup with method filtering
   #or
lookup("location","u/phone/i"); # lookup with user-agent filtering
   #or
lookup("location","","$var(aor)"); # simple lookup with AOR from PV
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.  registered(domain [,AOR[, callid]])

   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 - Name of table that should be used for the lookup.
     * AOR (optional)- AOR to lookup for; if missing, the RURI is
       used as AOR; This must be a variable.
     * callid (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.20. registered usage
...
if (registered("location")) {
        sl_send_reply("100", "Trying");
        ...
};
if (registered("location","$fu")) {
        xlog("caller is registered\n");
}
...

1.4.5.  is_other_contact(domain , IPs)

   This function returns true if there are any other contacts
   registered, different from the ones from the IPs avp.

   Meaning of the parameters is as follows:
     * domain - Name of table that should be used for contacts
       lookup.
     * IPs - an AVP containing the IP's that will be compared with
       the contacts from usrloc.

   This function can be used from REQUEST_ROUTE.

   Example 1.21. is_other_contact usage
...

if (is_other_contact("location", "$avp(ips)")) {
        sl_send_reply("403", "Forbidden");
        ...
};
...

1.4.6.  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 - header name to be used.

   This function can be used from REQUEST_ROUTE.

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

1.5. Exported Statistics

1.5.1. max_expires

   Value of max_expires parameter.

1.5.2. max_contacts

   The value of max_contacts parameter.

1.5.3. defaults_expires

   The value of default_expires parameter.

1.5.4. accepted_regs

   Number of accepted registrations.

1.5.5. rejected_regs

   Number of rejected registrations.

Chapter 2. Frequently Asked Questions

   2.1.

        What happend 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 happend 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 happend 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 happend 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 happend 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 happend 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 happend 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 happend 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 http://www.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.
