# &adminguide;

## Overview

This module provides all functionality to build an IMS ICSCF.

## Dependencies

### &kamailio; Modules

The Following modules must be loaded before this module:

- TM - Transaction Manager

- SL - Stateless Reply

- CDP - C Diameter Peer

- CDP_AVP - CDP AVP Applications

### External Libraries or Applications

This module requires the Kamailio internal IMS library.

## Parameters

### `route_lir_user_unknown` (string)

This is the route which is executed if HSS returns "user unknown" in LIR

Default value is ''.

#### `route_lir_user_unknown` parameter usage

    ...
    modparam("ims_icscf","route_lir_user_unknown", "lir_term_user_unknown")
    ...

### `route_uar_user_unknown` (string)

This is the route which is executed if HSS returns "user unknown" in UAR.

Default value is ''.

#### `route_uar_user_unknown` parameter usage

    ...
    modparam("ims_icscf","route_uar_user_unknown", "uar_term_user_unknown")
    ...

### `scscf_entry_expiry` (integer)

This is the time in s after which S-CSCF entries in the I-CSCF's SCSCF list will expire.

Default value is 300.

#### `scscf_entry_expiry` parameter usage

    ...
    modparam("ims_icscf","scscf_entry_expiry", 300)
    ...

### `db_url` (string)

&url; of the database to be used.

If the db_url string is empty, the default database URL will be used.

Default value is &defaultrodb;.

#### Set `db_url` parameter

    ...
    modparam("ims_icscf", "db_url", "&exampledb;")
    ...

### `db_nds_table` (string)

NDS (Network Domain Security) table name in database to be used.

Default value is nds_trusted_domains.

#### Set `db_nds_table` parameter

    ...
    modparam("ims_icscf", "db_nds_table", "nds_trusted_domains")
    ...

### `db_scscf_table` (string)

S-CSCF table name in database to be used.

Default value is s_cscf.

#### Set `db_scscf_table` parameter

    ...
    modparam("ims_icscf", "db_scscf_table", "s_cscf")
    ...

### `db_capabilities_table` (string)

S-CSCF capabilities table name in database to be used.

Default value is s_cscf_capabilities.

#### Set `db_capabilities_table` parameter

    ...
    modparam("ims_icscf", "db_capabilities_table", "s_cscf_capabilities")
    ...

### `cxdx_forced_peer` (string)

FQDN of Diameter Peer (HSS) to use for communication (UAR, LIR). 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 is "".

#### `cxdx_forced_peer` parameter usage

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

### `cxdx_dest_realm` (string)

Destination realm to be used in Diameter messages to HSS

Default value is "ims.smilecoms.com".

#### `cxdx_dest_realm` parameter usage

    ...
    modparam("ims_icscf", "cxdx_dest_realm", "ims.smilecoms.com")
    ...

### `use_preferred_scscf_uri` (int)

Whether or not this ICSCF has a preferred S-CSCF to use when the HSS returns a list of SCSCFs. 0 means this I-CSCF has no preferred SCSCF. 1 means it has a preferred S-CSCF.

Default value is 0.

#### `use_preferred_scscf_uri` parameter usage

    ...
    modparam("ims_icscf", "use_preferred_scscf_uri", 1)
    ...

### `preferred_scscf_uri` (string)

If use_preferred_scscf_uri is set then this is the URI of the preferred SCSCF.

Default value is "".

#### `preferred_scscf_uri` parameter usage

    ...
    modparam("ims_icscf", "preferred_scscf_uri", "sip:scscf.ims.smilecoms.com:6060")
    ...

## Functions

### `I_scscf_select(initial)`

This function is used to retrieve the next unused SCSCF from the list for this request (based on callid).

A positive return code (1) means an SCSCF was found and is armed for routing.

Meaning of the parameters is as follows:

- initial - Signal whether or not this is an original or subsequent.

This function can be used from REQUEST_ROUTE | FAILURE_ROUTE.

#### `I_scscf_select` usage

    ...
    if (I_scscf_select("0")) {
         #there is an S-CSCF list - no need to do a UAR
         t_on_reply("register_reply");
         t_on_failure("register_failure");
         t_relay();
    }
    ...

### `I_scscf_drop()`

Drop the list of SCSCFs for this request (based on callid).

This function can be used from REQUEST_ROUTE | FAILURE_ROUTE | REPLY_ROUTE

#### `I_scscf_drop` usage

    ...
    I_scscf_drop();
    ...

.

### `I_perform_user_authorization_request(route_block, capabalities)`

Perform a UAR on Diameter CXDX interface. This function will build a list of SCSCFs to be used and populate the SCSCF list for the request. On a successful return of this message you can get the next available SCSCF by using the I_scscf_select function in 4.1.

- Route block to resume after async UAR Diameter reply.

- capabilities - whether to request capabilities or not "1" - with capabilities, "0" - no capabilities.

This function can be used from REQUEST_ROUTE.

p.s. this is executed asynchronously. See example on how to retrieve return value

#### I_perform_user_authorization_request usage

    ...
    I_perform_user_authorization_request("REG_UAR_REPLY","0"); #0=REG/DEREG; 1=REG+Capabilities
    exit;
    ...
    route[REG_UAR_REPLY]
    {
        #this is async so to know status we have to check the reply avp
        switch ($avp(s:uaa_return_code)){
                case 1: #success
                        if (I_scscf_select("0")){
                                t_on_failure("register_failure");
                                t_on_reply("register_reply");
                                #now relay to appropriate SCSCF
                                if (!t_relay()) {
                                        t_reply("500", "Error forwarding to SCSCF");
                                }
                        } else {#select failed
                                I_scscf_drop();
                                t_reply("500", "Server error on SCSCF Select (UAR)");
                        }
                        break;
                case -1: #failure
                        xlog("L_ERR", "UAR failure - error response sent from module\n");
                        break;
                case -2: #error
                        xlog("L_ERR", "UAR error - sending error response now\n");
                        t_reply("500", "UAR failed");
                        break;
                default:
                        xlog("L_ERR", "Unknown return code from UAR, value is [$avp(s:uaa_return_code)]\n");
                        t_reply("500", "Unknown response code from UAR");
                        break;
        }
    }
    ...

### `I_perform_location_information_request(route_block)`

Perform a LIR on Diameter CXDX interface.

- Route block to resume after async LIR Diameter reply.

This function can be used from REQUEST_ROUTE.

p.s. this is executed asynchronously. See example on how to retrieve return value

#### I_perform_location_information_request

    ...
    I_perform_location_information_request("SESSION_LIR_REPLY","0");
    exit;
    ...
    route[SESSION_LIR_REPLY]
    {
        if ($avp(lia_return_code) == 1) {
                if (I_scscf_select("0")) {
                        append_branch();
                        t_on_reply("initial_request_reply");
                        t_on_failure("initial_request_failure");
                        if (!t_relay()) {
                                t_reply("500","Error forwarding towards S-CSCF");
                                break;
                        }
                        break;
                } else {
                        xlog("L_DBG", "dropping scscf list on initial request\n");
                        I_scscf_drop();
                        t_reply("500", "Server error on LIR select S-CSCF");
                        break;
                }
        } else {
                t_reply("500", "Server error on LIR");
                break;
        }
        break;
    }
    ...

## Statistics

### Average UAR Response Time (uar_avg_response_time)

The average response time in milliseconds for UAR-UAA transaction.

### UAR Timeouts (uar_timeouts)

The number of UAR timeouts.

### Average LIR Response Time (lir_avg_response_time)

The average response time in milliseconds for LIR-LIA transaction.

### LIR Timeouts (lir_timeouts)

The number of LIR timeouts.