# &adminguide;

## Overview

The module contains record routing logic

## Dialog support

&osips; is basically only a transaction statefull proxy, without any dialog support build in. There are many features/services which actually require 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 modules offers the following functions:

- add_rr_param() - see add-rr-param-id

- check_route_param() - see check-route-param-id

### Dialog support in RR module

    UAC                       OpenSIPS 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

### &osips; Modules

The following modules must be loaded before this module:

- No dependencies on other &osips; modules.

### External Libraries or Applications

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

- None.

## Exported Parameters

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

Default value is 1 (yes).

#### Set `enable_double_rr` parameter

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

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

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 &osips; 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 &osips; 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)
    ...

## Exported 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 exclusivly via RURI. If a Route header is found, the function returns TRUE and behaves as described in section 16.12 of RFC 3261. The only exception is for requests with preload Route headers (intial requests, carrying a Route header): if there is only one Route header indicating the local proxy, then the Route header is removed and the function returns FALSE.

If there is a Route header but other parsing errors occur ( like parsing the TO header to get the TAG ), the function also returns FALSE.

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

This function can be used from REQUEST_ROUTE.

#### `loose_route` usage

    ...
    loose_route();
    ...

### `record_route()` and `record_route(string)`

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.

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

#### `record_route` usage

    ...
    record_route();
    ...

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

This function will put the string into Record-Route, don't use 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.

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

### `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() call (see record-route-id).

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 call after loose_route() (see loose-route-id).

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 the request. As for checking it's used the ftag Route header parameter, the append_fromtag (see append-fromtag-id module parameter must be enabled. Also this must be called only after loose_route() (see loose-route-id).

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

The downstream (UAC to UAS) direction is relative to 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 UAS to UAC) or downstream (UAC to UAS).

This function can be used from REQUEST_ROUTE.

#### `is_direction` usage

    ...
    if (is_direction("upstream")) {
        xdbg("upstream request ($rm)\n");
    }
    ...

### Exported pseudo-variables

Exported pseudo-variables are listed in the next sections.

#### $rr_params

$rr_params - the whole string of the Route parameters - this is available only after calling loose_route()