# &adminguide;

## Overview

This module contains REGISTER processing logic for the S-CSCF. The 'storage engine' of this module is provided by the ims_usrloc_scscf module:

## Dependencies

### &kamailio; Modules

The following modules must be loaded before this module:

- CDP

- CDP_AVP

- TM

- ims_usrloc_scscf

### External Libraries or Applications

The following libraries or applications must be installed before running &kamailio; with this module loaded:

- LibXML2 - used for parsing the XML Subscription information obtained from the HSS (Home Subscriber Server)

## Parameters

### default_expires (int)

If the processed message contains neither Expires HFs nor expires contact parameters, this value will be used for newly created S-CSCF 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 min_expires parameter then it will be ignored. This parameter can be modified via ser config framework. A random value in a specific interval can be selected by using the default_expires_range parameter

Default value is 3600.

#### Set `default_expires` parameter

    ...
            modparam("ims_registrar_scscf", "default_expires", 3600)
    ...

### default_expires_range (int)

This parameter specifies that the expiry used for newly created S-CSCF usrloc records are not fixed(when default_expires applies), but a random value in the intervalrdq [default_expires-default_expires_range%, default_expires+default_expires_range%]. The value is between 0 and 100 and represent the maximum percentage from default_expires that will be subtracted or added when computing the value. Default in 0, meaning default_expires is left unmodified. This parameter can be modified via ser config framework.

Default value is 0.

#### Set `default_expires_range` parameter

    ...
            modparam("ims_registrar_scscf", "default_expires_range", 30) # +- 30% from default_expires
    ...

### min_expires (int)

The minimum expires value of a Contact, values lower than this minimum will be automatically set to the minimum. Value 0 disables the checking. This parameter can be modified via ser config framework.

Default value is 60.

#### Set `min_expires`parameter

    ...
            modparam("ims_registrar_scscf", "min_expires", 1800)
    ...

### max_expires (int)

The maximum expires value of a Contact, values higher than this maximum will be automatically set to the maximum. Value 0 disables the checking. This parameter can be modified via ser config framework.

Default value is 0.

#### Set `max_expires`parameter

    ...
            modparam("ims_registrar_scscf", "max_expires", 3600)
    ...

### subscription_default_expires (int)

If the processed message contains neither Expires HFs nor expires contact parameters, this value will be used for newly created subscriptions. 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 subscription_min_expires parameter then it will be ignored. A random value in a specific interval can be selected by using the subscription_expires_range parameter

Default value is 3600.

#### Set `subscription_default_expires` parameter

    ...
            modparam("ims_registrar_scscf", "subscription_default_expires", 3600)
    ...

### subscription_expires_range (int)

This parameter specifies that the expiry used for newly created subscriptions are not fixed(when subscription_default_expires applies), but a random value in the interval [subscription_default_expires-subscription_expires_range%, subscription_default_expires+subscription_expires_range%]. The value is between 0 and 100 and represent the maximum percentage from subscription_default_expires that will be subtracted or added when computing the value. Default in 0, meaning subscription_default_expires is left unmodified.

Default value is 0.

#### Set `subscription_expires_range` parameter

    ...
            modparam("ims_registrar_scscf", "subscription_expires_range", 30) # +- 30% from subscription_expires_range
    ...

### subscription_min_expires (int)

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

Default value is 10.

#### Set `subscription_min_expires`parameter

    ...
            modparam("subscription_min_expires", "min_expires", 1800)
    ...

### subscription_max_expires (int)

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

Default value is 1000000.

#### Set `subscription_max_expires`parameter

    ...
            modparam("ims_registrar_scscf", "subscription_max_expires", 3600)
    ...

### ue_unsubscribe_on_dereg (int)

Many UEs do not unsubscribe on de-register, therefor if the parameter is set to 0, the default, any subscription of that subscriber will be removed and NOTIFY will be not sent. To disable this behaviour set this parameter to 1.

Default value is 0 (disabled)

#### Set `user_data_dtd`parameter

    ...
            modparam("ims_registrar_scscf", "ue_unsubscribe_on_dereg", 1)
    ...

### user_data_dtd (string)

DTD to check the user data received in SAA (Server Assignment Answer).

Default value is NULL (none).

#### Set `user_data_dtd`parameter

    ...
            modparam("ims_registrar_scscf", "user_data_dtd", "/usr/local/etc/kamailio/CxDataType_Rel7.dtd")
    ...

### user_data_xsd (string)

XSD to check the user data received in SAA (Server Assignment Answer).

Default value is NULL (none).

#### Set `user_data_xsd`parameter

    ...
            modparam("ims_registrar_scscf", "user_data_xsd", "/usr/local/etc/kamailio/CxDataType_Rel7.xsd")
    ...

### support_wildcardPSI (int)

indicate support for wildcard PSI is subscription profile (SAA)

Default value is 0.

#### Set `support_wildcardPSI`parameter

    ...
            modparam("ims_registrar_scscf", "support_wildcardPSI", 1)
    ...

### scscf_name (string)

The name of the S-CSCF

Default value is sip:scscf.ims.smilecoms.com:6060.

#### Set `scscf_name`parameter

    ...
            modparam("ims_registrar_scscf", "scscf_name", "sip:scscf2.ims.smilecoms.com:6060")
    ...

### store_profile_dereg (int)

Should the subscription profile be stored on de-registration

Default value 0.

#### Set `store_profile_dereg`parameter

    ...
            modparam("ims_registrar_scscf", "store_profile_dereg", 1)
    ...

### cxdx_dest_realm (string)

Destination realm to be used in Diameter messages

Default value "ims.smilecoms.com"

#### Set `cxdx_dest_realm`parameter

    ...
            modparam("ims_registrar_scscf", "cxdx_dest_realm", "my.domain,org")
    ...

### cxdx_forced_peer (string)

FQDN of Diameter Peer (HSS) to use for communication (SAR). If you use this, the routing defined in your diameter xml configuration file (CDP) will be ignored and as a result you will lose the benefits of load balancing and failover.

Default value NULL (none)

#### Set `cxdx_forced_peer`parameter

    ...
            modparam("ims_registrar_scscf", "cxdx_forced_peer", "hss.ims.smilecoms.com")
    ...

### append_branches (integer)

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 contact and the rest will be left unprocessed. This parameter can be modified via Kamailio config framework.

Default value is 0 (disabled)

#### Set `cxdx_forced_peer`parameter

    ...
            modparam("ims_registrar_scscf", "append_branches", 1)
    ...

### method_filtering (integer)

Tells if the contact filtering based on supported methods should be performed during lookup. It's enabled only if it has a non zero value.

Default value is 0 (disabled)

#### Set `cxdx_forced_peer`parameter

    ...
            modparam("ims_registrar_scscf", "method_filtering", 1)
    ...

### user_data_always (integer)

If specified this will make the S-CSCF always request user data from HSS.

Default value is 0 (disabled)

#### Set `user_data_always`parameter

    ...
            modparam("ims_registrar_scscf", "user_data_always", 1)
    ...

### error_reply_code (int)

In certain error conditions, the S-CSCF may not be able to process the request (e.g. in case of database failures). Per default and according to the Specs, the S-CSCF would return a 500 error in this case. However, according to the SIP-Specs for DNS-SRV, this won't trigger a failover, which may be desired.

This parameter let's you override the default 500 with another return-code (e.g. 503) in order to get the desired behaviour.

Default value is 500.

#### Set `error_reply_code` parameter

    ...
            modparam("ims_registrar_scscf", "error_reply_code", 503)
    ...

### skip_multiple_bindings_on_reg_resp (int)

If set to 1 - on Re-Registration registrar sends in 200 OK reply only current contact in case of multiple bindings. If set to 0 - on Re-Registration registrar sends in 200 OK reply all contacts in case of multiple bindings according to RFC3261.

Default value is 0.

#### Set `skip_multiple_bindings_on_reg_resp` parameter

    ...
            modparam("ims_registrar_scscf", "skip_multiple_bindings_on_reg_resp", 1)
    ...

## Functions

### `save(async_reply_route, domain, mode, flags)`

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 and when called from the REQUEST_ROUTE, 200 OK will be returned listing all contacts that are currently in usrloc. On an error, error message will be sent with a short description in reason phrase. In case of internal errors the function will return FALSE, otherwise a force to exit the cfg is file is actioned by returning 0 (asynchronous processing)

Meaning of the parameters is as follows:

- async_reply_route- the route to execute after the save has completed. This is required because the save function is executed asynchronously (Diameter).

- domain- Logical domain within registrar.

- mode- Optional and unused legacy parameter.

- flags- Optional parameter. Valid values: 0x01 - Realm is not used when extracting Private Identity from the Authorization header.

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE

#### `save` usage

    ...
    if (!impu_registered("location")) {
       save("PRE_REG_SAR_REPLY","location");
    }
    ...

### `lookup(domain)`

This function extract the IMPU from the Request-URI and tries to find all registered contacts in usrloc. If there are no such contacts, -1 is returned. If there are, Request-URI will be rewritten with the contact that has the highest q value. The rest of the contacts will be appended to the sip msg structure (if append_branches is set) and can be later used by TM module for forking for example...

If the method filtering option is enabled, the lookup function will only return contacts that support the method of the request being processed (see allows header)

Meaning of the parameters is as follows:

- domain - Logical domain within registrar.

Return codes:

- -1 - Not found

- -2 - Found, but method not allowed (check Allows header for INVITE, MESSAGE, etc).

- -3 - Error occurred internally during processing

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE

#### `lookup` usage

    ...
    lookup("location");
    switch ($retcode) {
        case -1:
        case -3:
            sl_send_reply("404", "Not Found");
            exit;
        case -2:
            sl_send_reply("405", "Not Found");
            exit;
    };
    ...

### `lookup_path_to_contact(uri)`

This function take a URI and tries to find the contact in usrloc. If the contact is found and has a path set, then a path header is added to the SIP message so it can be loose routed.

Meaning of the parameters is as follows:

- uri - URI of contact to lookup

Return codes:

- 1 - Success

- -1 - Failure

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE

#### `lookup` usage

    ...
    lookup_path_to_contact($ruri);
    ...

### `unregister(domain)`

This function will remove all bindings for the IMPU found in the Request-URI.

Meaning of the parameters is as follows:

- Domain- Logical domain within registrar.

This function can be used in REQUEST_ROUTE, FAILURE_ROUTE

#### `unregister` usage

    ...
    unregister("location");
    ...

### `assign_server_unreg(aysnc_reply_route, domain, direction)`

TBD

used in REQUEST_ROUTE

### `impu_registered(domain)`

This function checks if the IMPU in the To header is registered in usrloc.

Meaning of the parameters is as follows:

- domain- Logical domain within registrar.

Return codes:

- 1 - True, IMPU exists in registered state in usrloc

- -1 - False, IMPU not registered

This function can be used in REQUEST_ROUTE, FAILURE_ROUTE

#### `impu_registered` usage

    ...
    impu_registered("location");
    switch ($retcode) {
        case -1:
            sl_send_reply("404", "Not Found");
            exit;
        case 1:
            #true, continue with normal processing
    };
    ...

### `term_impu_registered(domain)`

This function checks if the IMPU in the Request-URI is registered in usrloc.

Meaning of the parameters is as follows:

- domain- Logical domain within registrar.

Return codes:

- 1 - True, IMPU exists in registered state in usrloc

- -1 - False, IMPU not registered

This function can be used in REQUEST_ROUTE, FAILURE_ROUTE

#### `term_impu_registered` usage

    ...
    term_impu_registered("location");
    switch ($retcode) {
         case -1:
              sl_send_reply("404", "Not Found");
              exit;
         case 1:
              #true, continue with normal processing
    };
    ...

### `reg_fetch_contacts(domain, uri, profile)`

The function fetches the contacts for 'uri' from table 'domain' to pseudo-variable $ulc(profile) [ulc = ims scscf ulc].

Meaning of the parameters is as follows:

- 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.

This function can be used in REQUEST_ROUTE, FAILURE_ROUTE

#### `reg_fetch_contacts` usage

    ...
    reg_fetch_contacts("location", "$ru", "callee");
    reg_fetch_contacts("location", "sip:user@kamailio.org", "caller");
    ...

### `reg_free_contacts(profile)`

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.

Meaning of the parameters is as follows:

- profile - Name of $ulc pseudo-variable profile that stores the contacts. It is a static string.

This function can be used in REQUEST_ROUTE, FAILURE_ROUTE

#### `reg_free_contacts` usage

    ...
    reg_free_contacts("callee");
    ...

### `can_subscribe_to_reg(domain)`

This function checks to see that a SUBSCRIBE request is authorised to subscribe to the particular identity. Only 3 entities can subscribe:

- The user agent to its own state

- The P-CSCF specified in the path header for that user

- Application Server (AS) not yet implemented

Meaning of the parameters is as follows:

- domain - Logical domain within registrar.

This function can be used in REQUEST_ROUTE

#### `can_subscribe_to_reg` usage

    ...
    if (can_subscribe_to_reg("location")){
         $var(ret)= subscribe_to_reg("location");
    }
    ...

### `subscribe_to_reg(domain)`

Save the subscription to the REG event for the UAC or the appropriate P-CSCF (in the path to the UAC).

Meaning of the parameters is as follows:

- domain - Logical domain within registrar.

This function can be used in REQUEST_ROUTE

#### `subscribe_to_reg` usage

    ...
    if (can_subscribe_to_reg("location")){
         $var(ret)= subscribe_to_reg("location");
    }
    ...

### `can_publish_reg(domain)`

This function checks to see that a PUBLISH request is authorised to publish for a particular identity. Only 3 entities can publish:

- The user agent to its own state

- The P-CSCF specified in the path header for that user

- Application Server (AS) not yet implemented

Meaning of the parameters is as follows:

- domain - Logical domain within registrar.

This function can be used in REQUEST_ROUTE

#### `can_publish_reg` usage

    ...
    if (can_publish_reg("location")){
        $var(ret)= publish_reg("location");
    }
    ...

### `publish_reg(domain)`

Save the publish to the REG event for the UAC or the appropriate P-CSCF (in the path to the UAC).

Meaning of the parameters is as follows:

- domain - Logical domain within registrar.

This function can be used in REQUEST_ROUTE

#### `publish_reg` usage

    ...
    if (can_publish_reg("location")){
        $var(ret)= publish_reg("location");
    }
    ...

## RPC Commands

exported RPC commands.

### regscscf.dereg_impu

Initiate network de-register of IMPU

## Statistics

Exported statistics are listed in the next sections.

### registered contacts

Number of AOR contacts in registered state - cannot be reset.

### impus

Number of IMPUs - cannot be reset.

### expired contacts

Number of expired contacts - can be reset.