# &adminguide;

## Overview

The B2BUA implementation in OpenSIPS is separated in two layers:

- a lower one(coded in b2b_entities module)- which implements the basic functions of a UAS and UAC
- an upper one - which represents the logic engine of B2BUA, responsible of actually implementing the B2BUA services using the functions offered by the low level.

This module is a B2BUA upper level implementation that can be used with b2b_entities module to have B2BUA that can be configured to provide some PBX services. The B2B services are coded in an XML scenario document. The b2b_logic module examines this document and uses the functions provided by the b2b_entities module to achieve the actions specified in the document and enable the service.

A scenario can be instantiated in two ways:

- from the script - at the receipt of a initial message
- with a extern command (MI) command - the server will connect two end points in a session(Third Party Call Control).

## Dependencies

### &osips; Modules

- b2b_entities, a db module

### External Libraries or Applications

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

- libxml2-dev

## Exported Parameters

### `hash_size` (int)

The size of the hash table that stores the scenario instatiation entities.

Default value is 9 (512 records).

#### Set `server_hsize` parameter

    ...
    modparam("b2b_logic", "hash_size", 10)
    ...

### `script_scenario` (str)

This parameter should be set with the path of a document that contains a scenario that can be instantiated from the script at the receipt of an initial message.

This parameter can be set more than once.

#### Set `script_scenario` parameter

    ...
    modparam("b2b_logic", "script_scenario", "/usr/local/opensips/scripts/b2b_prepaid.xml")
    ...

### `extern_scenario` (str)

This parameter should be set with the path of a document that contains a scenario that can be instantiated with an MI command.

This parameter can be set more than once.

#### Set `script_scenario` parameter

    ...
    modparam("b2b_logic", "extern_scenario", "/usr/local/opensips/scripts/b2b_marketing.xml")
    ...

### `cleanup_period` (int)

The time interval at which to search for an hanged b2b context. A scenario is considered expired if the duration of a session exceeds the lifetime specified in the scenario. At that moment, BYE is sent in all the dialogs from that context and the context is deleted.

Default value is 100.

#### Set `cleanup_period` parameter

    ...
    modparam("b2b_logic", "cleanup_period", 60)
    ...

### `custom_headers_regexp` (str)

Regexp to search SIP header by names that should be passed from the dialog of one side to the other side. There are a number of headers that are passed by default. They are:

- Content-Type
- Supported
- Allow
- Proxy-Require
- Session-Expires
- Min-SE
- Require
- RSeq

If you wish some other headers to be passed also you should define them by setting this parameter.

It can be in forms like "regexp", "/regexp/" and "/regexp/flags".

Meaning of the flags is as follows:

- i - Case insensitive search.

- e - Use extended regexp.

Default value is NULL.

#### Set `` parameter

    ...
    modparam("b2b_logic", "custom_headers_regexp", "/^x-/i")
    ...

### `custom_headers` (str)

A list of SIP header names delimited by ';' that should be passed from the dialog of one side to the other side. There are a number of headers that are passed by default. They are:

- Max-Forwards (it is decreased by 1)
- Content-Type
- Supported
- Allow
- Proxy-Require
- Session-Expires
- Min-SE
- Require
- RSeq

If you wish some other headers to be passed also you should define them by setting this parameter.

Default value is NULL.

#### Set `` parameter

    ...
    modparam("b2b_logic", "custom_headers", "User-Agent;Date")
    ...

### `use_init_sdp` (int)

This parameter modifies the behaviour of the B2BUA when bridging and a provisional media uri is set. For playing media while the callee answers (that is connecting the caller to a media server), the bridging with the callee must start by sending an Invite to it. The correct way is to send an Invite without a body in this case, but it has been observed that not many gateways support this. So, the solution is to use the sdp received in the first Invite from the caller and put it as the body for this invite. By setting this parameter, this behavior is enabled. You can also set use_init_sdp per scenario and overwrite this global value.

Default value is 0.

#### Set `` parameter

    ...
    modparam("b2b_logic", "use_init_sdp", 1)
    ...

### `db_url` (str)

Database URL.

#### Set `db_url` parameter

    ...
    modparam("b2b_logic", "db_url", "mysql://opensips:opensipsrw@127.0.0.1/opensips")
    ...

### `update_period` (int)

The time interval at which to update the info in database.

Default value is 100.

#### Set `update_period` parameter

    ...
    modparam("b2b_logic", "update_period", 60)
    ...

### `max_duration` (int)

The maximum duration of a call.

Default value is 12 * 3600 (12 hours).

If you set it to 0, there will be no limitation.

#### Set `max_duration` parameter

    ...
    modparam("b2b_logic", "max_duration", 7200)
    ...

### `b2bl_from_spec_param` (string)

The name of the pseudo variable for storing the new From header. The PV must be set before calling b2b_init_request.

Default value is NULL (disabled).

#### Set `b2bl_from_spec_param` parameter

    ...
    modparam("b2b_logic", "b2bl_from_spec_param", "$var(b2bl_from)")
    ...
    route{
    	...
    	# setting the From header
    	$var(b2bl_from) = "\"Call ID\" <sip:user@opensips.org>";
    	...
    	b2b_init_request("top hiding");
    	...
    }

### `server_address` (str)

The IP address of the machine that will be used as Contact in the generated messages. This is compulsory only when using external scenarios. For the script scenarios, if it is not set, it is constructed dynamically from the socket where the initiating request was received. This socket will be used to send all the requests, replies for that scenario instantiation.

#### Set `server_address` parameter

    ...
    modparam("b2b_logic", "server_address", "sip:sa@10.10.10.10:5060")
    ...

### `init_callid_hdr` (str)

The module offers the possibility to insert the original callid in a header in the generated Invites. If you want this, set this parameter to the name of the header in which to insert the original callid.

#### Set `init_callid_hdr` parameter

    ...
    modparam("b2b_logic", "init_callid_hdr", "Init-CallID")
    ...

### `db_mode` (int)

The B2B modules have support for the 3 type of database storage

- NO DB STORAGE - set this parameter to 0
- WRITE THROUGH (synchronous write in database) - set this parameter to 1
- WRITE BACK (update in db from time to time) - set this parameter to 2

Default value is 2 (WRITE BACK).

#### Set `db_mode` parameter

    ...
    modparam("b2b_logic", "db_mode", 1)
    ...

### `db_table` (str)

Name of the database table to be used

Default value is b2b_logic

#### Set `db_table` parameter

    ...
    modparam("b2b_logic", "db_table", "some_table_name")
    ...

### `b2bl_th_init_timeout` (int)

Call setup timeout for topology hiding scenario.

Default value is 60

#### Set `b2bl_th_init_timeout` parameter

    ...
    modparam("b2b_logic", "b2bl_th_init_timeout", 60)
    ...

## Exported Functions

### `b2b_init_request`

This is the function that must be called by the script writer on an initial INVITE for which a B2B scenario must be instantiated. It is up to the script writer to decide which are the criteria to decide for which messages certain scenarios must be instantiated.

The first parameter is the identifier for the scenario and possible flags. This is defined in the XML document as an attribute of the root node or "top hiding" for internal topology hiding scenario. It can be passed as "scenario" or "scenario_name/flags".

Meaning of the flags is as follows:

- t[nn] - Call setup timeout for topology hiding scenario. Example: t300.

- a - Transparent authentication. In this mode b2b passes your 401 or 407 authentication request to destination server.

- p - Preserve To: header.

Then it can take at most 4 other parameters that represent the parameters for the xml scenario. The expected number of parameters is also specified as an attribute in the root node of the XML scenario.

If you have a multi interface setup and want to chance the outbound interface, it is mandatory to use the "force_send_socket()" core function before passing control to b2b function. If you do not do it, the requests may be correctly routed, but the SIP pacakge may be invalid (as Contact, Via, etc).

#### `b2b_init_request` usage

    ...
    if(is_method("INVITE") && !has_totag() && prepaid_user())
       b2b_init_request("prepaid", "sip:320@opensips.org:5070",
          "sip:321@opensips.org:5070"));
    ...

### `b2b_bridge_request(b2bl_key,entity_no)`

This function will bridge an initial INVITE with one of the particapnts from an existing b2b dialog.

Parameters:

- b2bl_key - a pseudo-variable that contains the b2b_logic key

- entity_no - a pseudo-variable that holds the entity of the entity/participant to bridge.

#### `b2b_bridge_request` usage

    ...
    modparam("b2b_entities", "script_req_route", "b2b_request")
    ...
    route[b2b_request]
    {
       # incoming requests from the B2B entities
       ...
       if ($ci~="^B2B") { #keep this aligned with b2b_key_prefix
          # request coming from the UAC side;
          # the Call-ID carries the B2B key ID
          if (is_method("BYE") {
             $var(entity) = 1;
             b2b_bridge_request("$ci","$var(entity)");
          }
       }
       ...
    }
    ...

## Exported MI Functions

### `b2b_trigger_scenario`

This command instantiated a B2B scenario.

Name: b2b_trigger_scenario

Parameters:

- senario_id : the id of the scenario to be instantiated.

- scenario parameters - it can take 4 more parameters that are scenario parameters

MI FIFO Command Format:

    	:b2b_trigger_scenario:fifo_reply
    	marketing
    	sip:bob@opensips.org
    	sip:322@opensips.org:5070
    	sip:alice@opensips.org
    	_empty_line_

### `b2b_bridge`

This command can be used by an external application to tell B2BUA to bridge a call party from an on going dialog to another destination. By default the caller is bridged to the new uri and BYE is set to the callee. You can instead bridge the callee if you send 1 as the third parameter. Also, if a fourth parameter is

Name: b2b_bridge

Parameters:

- dialog-id : the id of the dialog. If you set the module parameter dialog-id the server will include the dialogid in the generated Invites as the content of a header with name 'Dialog-ID'.

- new uri - the uri of the new destination

- flag to specify that the callee must be bridged to the new destination. It is optional. If not present the caller will be bridged.

- provisional media uri - the uri of a media server able to play provisional media starting from the beginning of the bridging scenario to the end of it. It is optional. If not present, no other entity will be envolved in the bridging scenario

MI FIFO Command Format:

    	:b2b_bridge:fifo_reply
    	1020.30
    	sip:alice@opensips.org
    	_empty_line_

opensipsctl Command Format:

    	opensipsctl b2b_bridge 1020.30 sip:alice@opensips.org

### `b2b_list`

This command can be used to list the internals of b2b_logic entities.

Name: b2b_list

Parameters: none

MI FIFO Command Format:

    	:b2b_list:_reply_fifo_file_
    	_empty_line_

opensipsctl Command Format:

    	opensipsctl fifo b2b_list