# &adminguide;

## Overview

The module contains record routing logic.

## Dialog support

&kamailio; is basically only a transaction stateful proxy, without any dialog support build in. There are many features/services which actually require a dialog awareness, like storing the information in the dialog creation stage, information which will be used during the whole dialog existence.

The most urging example is NAT traversal, in dealing with the within the dialog INVITEs (re-INVITEs). When processing the initial INVITE, the proxy detects if the caller or callee is behind some NAT and fixes the signalling and media parts - since not all the detection mechanism are available for within the dialog requests (like usrloc), to be able to fix correspondingly the sequential requests, the proxy must remember that the original request was NAT processed. There are many other cases where dialog awareness fixes or helps.

The solution is to store additional dialog-related information in the routing set (Record-Route/Route headers), headers which show up in all sequential requests. So any information added to the Record-Route header will be found (with no direction dependencies) in Route header (corresponding to the proxy address).

As storage container, the parameters of the Record-Route / Route header will be used - Record-Route parameters mirroring are reinforced by RFC 3261 (see 12.1.1 UAS behavior).

For this purpose, the module offers the following functions:

- add_rr_param() - see rr.f.add_rr_param

- check_route_param() - see rr.f.check_route_param

### Dialog support in RR module

    ...
    UAC                       &kamailio; PROXY                          UAS

    ---- INVITE ------>       record_route()          ----- INVITE ---->
                         add_rr_param(";foo=true")

    --- reINVITE ----->        loose_route()          ---- reINVITE --->
                        check_route_param(";foo=true")

    <-- reINVITE ------        loose_route()          <--- reINVITE ----
                        check_route_param(";foo=true")

    <------ BYE -------        loose_route()          <----- BYE -------
                        check_route_param(";foo=true")
    ...

## Dependencies

### &kamailio; Modules

The following modules must be loaded before this module:

- (optional) The "outbound" module is needed for outbound routing as per RFC 5626.

### External Libraries or Applications

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

- None.

## Parameters

### `enable_full_lr` (integer)

If set to 1 then ;lr=on instead of just ;lr will be used. This is to overcome problems with broken &ua;s which strip ;lr parameter when generating Route header fields from Record-Route (;lr=on seems to help).

Default value is 0 (no).

#### Set `enable_full_lr` parameter

    ...
    modparam("rr", "enable_full_lr", 1)
    ...

### `append_fromtag` (integer)

If turned on, request's from-tag is appended to record-route; that's useful for understanding whether subsequent requests (such as BYE) come from caller (route's from-tag==BYE's from-tag) or callee (route's from-tag==BYE's to-tag)

Default value is 1 (yes).

#### Set `append_fromtag` parameter

    ...
    modparam("rr", "append_fromtag", 0)
    ...

### `enable_double_rr` (integer)

There are some situations when the server needs to insert two Record-Route header fields instead of one. For example when using two disconnected networks or doing cross-protocol forwarding from UDP->TCP. This parameter enables inserting of 2 Record-Routes. The server will later remove both of them.

Double record-routing does not occur when outbound is used for a request.

Default value is 1 (yes).

#### Set `enable_double_rr` parameter

    ...
    modparam("rr", "enable_double_rr", 0)
    ...

Some useragents (e. g. Linphone) incorrectly use UDP transport for subsequent requests in dialog, despite being configured to use another SIP transport protocol. This can be worked around by setting Record-Route header with explicit transport attribute. But enable_double_rr enabled in default mode omits transport attribute from being added to header if it detects that both sender and receiver use same protocol (e. g. TCP or TLS), and this results in UDP being used by such broken clients. Set enable_double_rr to value 2 to always have two RR headers with transport attributes explicitly set.

#### Set `enable_double_rr` to 2 to always have two explicit RR headers

    ...
    modparam("rr", "enable_double_rr", 2)
    ...

### `add_username` (integer)

If set to a non 0 value (which means yes), the username part will be also added in the Record-Route URI.

This option cannot be set when the outbound module is loaded before this module as outbound uses the username part of Record-Route URIs to store flow-tokens.

Default value is 0 (no).

#### Set `add_username` parameter

    ...
    modparam("rr", "add_username", 1)
    ...

### `enable_socket_mismatch_warning` (integer)

When a preset record-route header is forced in &kamailio; config and the host from the record-route header is not the same as the host server, a warning will be printed out in the logs. The 'enable_socket_mismatch_warning' parameter enables or disables the warning. When &kamailio; is behind a NATed firewall, we don't want this warning to be printed for every bridged call.

Default value is 1 (yes).

#### `enable_socket_mismatch_warning` usage

    ...
    modparam("rr", "enable_socket_mismatch_warning", 0)
    ...

### `custom_user_avp` (avp string)

When add_username is enabled, a call to record_route will add the username of the RequestURI to the Record-Route URI. This parameter allows you to set up an AVP with which you can customise the username to be added in the Record-Route URI.

Default value: if not set, the std add_username behaviour is used - i.e. Request URI username.

#### `custom_user_avp` usage

    ...
    modparam("rr", "custom_user_avp", "$avp(RR_CUSTOMER_USER_AVP)")

    #usage in cfg file
    $avp(RR_CUSTOM_USER_AVP)="mo";
    record_route();
    ...

### `force_send_socket` (int)

If set to 1, local socket is forced even for single Record-Route, otherwise is done on double Record-Route (should that be enabled).

When use of outbound is enabled, the socket is not forced.

Default value is 0.

#### Set `force_send_socket` parameter

    ...
    modparam("rr", "force_send_socket", 1)
    ...

### `ignore_sips` (int)

If set to 1, the Record-Route header are build with 'sip' schema always, ignoring the presence of 'sips' schema in request URI.

Default value is 0 (use 'sips' if present in R-URI).

#### Set `ignore_sips` parameter

    ...
    modparam("rr", "ignore_sips", 1)
    ...

### `sockname_mode` (int)

If set to 1, the Record-Route URI is built to contain socket name in 'sn' parameter and then it is used to lookup the local socket for Route header processing.

Default value is 0.

#### Set `sockname_mode` parameter

    ...
    modparam("rr", "sockname_mode", 1)
    ...

### `loose_route_mode` (int)

Controls the behaviour of loose_route() in the same manner as the value of the parameter for for function loose_route_mode(val), in a global manner.

Default value is 0.

#### Set `loose_route_mode` parameter

    ...
    modparam("rr", "loose_route_mode", 1)
    ...

## Functions

### `loose_route()`

The function performs routing of SIP requests which contain a route set. The name is a little bit confusing, as this function also routes requests which are in the strict router format.

This function is usually used to route in-dialog requests (like ACK, BYE, reINVITE). Nevertheless also out-of-dialog requests can have a pre-loaded route set and my be routed with loose_route. It also takes care of translating between strict-routers and loose-router.

The loose_route function analyzes the Route: headers in the requests. If there is no Route: header, the function returns FALSE and routing should be done with normal lookup functions. If a Route: header is found, the function returns 1 and behaves as described in section 16.12 of RFC 3261. There is only one exception: If the request is out-of-dialog (no to-tag) and there is only one Route: header indicating the local proxy, then the Route: header is removed and the function returns FALSE.

When the outbound module was loaded before this module and the Route: header contains a username part this function will attempt to use the username part as a flow-token for routing. If route calculation based on flow-token succeeds, function returns TRUE even if there is only one Route: header indicating the local proxy.

Make sure your loose_routing function can't be used by attackers to bypass proxy authorization.

The loose_routing topic is very complex. See the RFC3261 for more details (grep for route set is a good starting point in this comprehensive RFC).

Return codes:

- 1 - route calculation has been successful

- 2 - route calculation based on flow-token has been successful

- -1 - route calculation has been unsuccessful

- -2 - outbound flow-token shows evidence of tampering

- -3 - next hop is taken from a preloaded route set

This function can be used from REQUEST_ROUTE.

#### `loose_route` usage

    ...
    loose_route();
    ...

### `loose_route_preloaded()`

The function is similar to `loose_route()`, but it returns 1 (true) when the Route header is preloaded (is in an initial request) and -1 (false) if processing of the Route header failed or it is for requests within dialog.

It is a convenient function to use for routing initial requests on an edge proxy that adds Path header to REGISTER requests.

This function can be used from REQUEST_ROUTE.

#### `loose_route_preloaded` usage

    ...
    if(!loose_route_preloaded()) {
       sl_send_reply("404" "Preloaded route expected");
       exit;
    }
    ...

### `loose_route_mode(vmode)`

The function is similar to `loose_route()`, but it accepts route mode bitmask as vmode parameter.

If bit one is set, then do only loose routing processing, skipping the testing of r-uri==myself for performing strict routing. If not, behave like loose_route(). If bit two is set, then skip flow tokens processing.

First bit is convenient to use with application servers that set the Contact URI to SIP server address.

This function can be used from REQUEST_ROUTE.

#### `loose_route_mode` usage

    ...
    if(has_totag() and uri==myself) {
        if(loose_route_mode("1")) {
            rewritehostport("my.app.server:5090");
            t_relay();
            exit;
        }
    }
    ...

### `record_route([sparams])`

The function adds a new Record-Route header field. The header field will be inserted in the message before any other Record-Route header fields.

If any string is passed as parameter, it will be appended as URI parameter to the Record-Route header. The string must follow the ;name=value scheme and it may contain pseudo-variables.

When the outbound module was loaded before this module this function will determine whether outbound is required for the request and generate and add a flow-token as the username part of the Record-Route-URI.

Note: if append From-tag is enabled and the function is used for requests within dialog, it must be executed after loose_route() in order to detect properly the direction.

This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and FAILURE_ROUTE.

#### `record_route` usage

    ...
    record_route();
    ...

### `remove_record_route()`

The function removes the internal lumps added by record_route() functions.

Can be used to revert adding Record-Route header(s).

This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.

#### `remove_record_route` usage

    ...
    remove_record_route();
    ...

### `record_route_preset(string [,string2])`

This function will put the string params into Record-Route, avoid to use it unless you know what you are doing.

Meaning of the parameters is as follows:

- string - String to be inserted into the first header field; it may contain pseudo-variables.

- string2 - String to be inserted into the second header field; it may contain pseudo-variables.

Note: If 'string2' is present, then the 'string' param is pointing to the outbound interface and the 'string2' param is pointing to the inbound interface.

Note: The value of parameters must not contain the SIP protocol scheme (sip: or sips:), one is added based on routing requirements. Thus the value has to be like "address:port;parameters", the port and parameters are optional. If the second parameter is provided, do not forget to add the parameter "r2=on" so the proxy processes both corresponding Route headers at once.

When the outbound module was loaded before this module this function will determine whether outbound is required for the request and generate and add a flow-token as the username part of the Record-Route-URI.

This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and FAILURE_ROUTE.

#### `record_route_preset` usage

    ...
    record_route_preset("1.2.3.4:5090");
    ...

### `record_route_advertised_address(address)`

The function adds a new Record-Route header field using the address given. The header field will be inserted in the message before any other Record-Route header fields.

When the outbound module was loaded before this module this function will determine whether outbound is required for the request and generate and add a flow-token as the username part of the Record-Route-URI.

Meaning of the parameter is as follows:

- address - Advertised address to use in the header; it may contain pseudo-variables.

If double record-routing is enabled two Record-Route headers will be inserted with the same given address with different transports if the transport changes.

This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and FAILURE_ROUTE.

#### `record_route_advertised_address` usage

    ...
    record_route_advertised_address("1.2.3.4:5080");
    ...

### `add_rr_param(param)`

Adds a parameter to the Record-Route URI (param must be in ;name=value format. The function may be called also before or after the record_route(), record_route_advertised_address(), and record_route_preset() calls (see rr.f.record_route or rr.f.record_route_adv_addr)).

Meaning of the parameters is as follows:

- param - String containing the URI parameter to be added. It must follow the ;name=value scheme; it may contain pseudo-variables.

This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and FAILURE_ROUTE.

#### `add_rr_param` usage

    ...
    add_rr_param(";nat=yes");
    ...

### `check_route_param(re)`

The function checks if the URI parameters of the local Route header (corresponding to the local server) matches the given regular expression. It must be called after loose_route() (see rr.f.loose_route).

Meaning of the parameters is as follows:

- re - regular expression to check against the Route URI parameters.

This function can be used from REQUEST_ROUTE.

#### `check_route_param` usage

    ...
    if (check_route_param("nat=yes")) {
        setflag(6);
    }
    ...

### `is_direction(dir)`

The function checks the flow direction of in-dialog requests. This function uses the ftag parameter from the Route header, therefore the append_fromtag (see rr.p.append_fromtag module parameter must be enabled. Also this must be called only after loose_route() (see rr.f.loose_route).

The function returns true if the dir is the same with the request's flow direction.

The downstream direction means that the request is in the same direction as the initial request that created the dialog.

Meaning of the parameters is as follows:

- dir - string containing the direction to be checked. It may be upstream (from callee to caller) or downstream (caller to callee).

This function can be used from REQUEST_ROUTE.

#### `is_direction` usage

    ...
    if (is_direction("downstream")) {
        xdbg("in-dialog request from caller to callee (downstream) ($rm)\n");
    } else {
        xdbg("in-dialog request from callee to caller (upstream) ($rm)\n");
    }
    ...

### `rr_next_hop_route()`

The function returns 1 (true) if there is a Route header for the next hop address. It has to be used after loose_route(), when the local Route headers are processed.

This function can be used from ANY_ROUTE.

#### `rr_next_hop_route` usage

    ...
    if(loose_route) {
        if(rr_next_hop_route()) {
            # next hop address is from Route header
        }

    }
    ...

## Exported Pseudo Variables

### `$route_uri`

Returns the URI of the top route-header.

#### $route_uri

    ...
        xdbg("Route-URI is: $route_uri\n");
    ...