# &adminguide;

## Overview

This module performs destinations monitoring either for itself, or on the behalf of other modules. The monitoring is done by sending SIP OPTIONS requests, more or less in the same fashion as the dispatcher module (which was the initial source for this module).

As an example of usage by other modules, see drouting, which was enhanced to use this module to monitor its gateways.

## Dependencies

### &kamailio; Modules

The following modules must be loaded before this module:

- tm - Transaction module

### External Libraries or Applications

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

- none

### Parameters

#### `ping_interval` (integer)

Define the interval (in seconds) ping requests are sent to destinations

Default value is 30 seconds.

##### Set `ping_interval` parameter

    ...
    modparam("keepalive", "ping_interval", 10)
    ...

#### `destination` (string)

Allows to statically define destinations you want to monitor

##### Set `destination` parameter

    ...
    modparam("keepalive", "destination", "192.168.10.20")
    modparam("keepalive", "destination", "sip.provider.com")
    ...

#### `delete_counter`(int)

Unsuccessful attempts increase delete_counter. After passing it, keepalive module doesn't try to send options requests. Ignored if it's set to 0.

Default value is 5 .

##### Set `delete_counter` parameter

    ...
    modparam("keepalive", "delete_counter", "5")
    ...

#### `ping_from`(string)

Sets from header's uri.

Default value is "sip:keepalive@kamailio.org" .

##### Set `ping_from` parameter

    ...
    modparam("keepalive", "ping_from", "sip:keepalive@kamailio.org")
    ...

### Functions

#### `ka_is_alive(destination)`

Get destination status.

The parameter destination is destination you want to check status

Returned value:

- 1 if destination is up
- 2 if destination is down
- -1 on error

This function can be used from ANY_ROUTE.

##### `ka_is_alive()` usage

    ...
    if(ka_is_alive("192.168.10.20") == 1) {
      // do stuff
    };
    ...

#### `ka_add_destination(sip_uri, owner)`

Adds SIP URI in the memory destinations list to perform keep alive to it.

Meaning of the parameters:

- sip_uri (string) - address of destination to monitor. Valid format is [protoschema:]ip[:port], with: 'protoschema' being one of 'sip' or 'sips' (SIP over TLS) - if omitted, 'sip' is used by default; 'port' is optional (using default standard port 5060 for sip and 5061 for sips)
- owner (string) - module name owning the destination (for informational purpose)

Returned value:

- 1 - successful
- -1 - on error

This function can be used from REQUEST_ROUTE,BRANCH_ROUTE,ONREPLY_ROUTE.

##### `ka_add_destination(sip_uri, ownder)` usage

    ...
    $avp(duri1)="sip:192.168.1.10:5060;transport=tcp";
    $avp(duri2)="sip:192.168.1.11:5061";
    $avp(duri3)="sip:192.168.1.12"
    ka_add_destination("$avp(duri3)", "config");
    ka_add_destination("sip:192.168.1.10:5060;transport=tcp", "config");
    ...

#### `ka_del_destination(sip_uri, owner)`

Deletes the SIP URI from the memory destinations list used for monitoring.

Meaning of the parameters:

- sip_uri (string) - address of monitored destination. Valid format is [protoschema:]ip[:port], with: 'protoschema' being one of 'sip' or 'sips' (SIP over TLS) - if omitted, 'sip' is used by default; 'port' is optional (using default standard port 5060 for sip and 5061 for sips)
- owner (string) - module name owning the destination (for informational purpose)

Returned value:

- 1 - successful
- -1 - on error

This function can be used from ANY_ROUTE.

##### `ka_del_destination(sip_uri, owner)` usage

    ...
    $avp(duri1)="sip:192.168.1.10:5060;transport=tcp";
    $avp(duri2)="sip:192.168.1.11:5061";
    $avp(duri3)="sip:192.168.1.12"
    ka_del_destination("$avp(duri3)", "config");
    ka_del_destination("sip:192.168.1.10:5060;transport=tcp", "config");
    ...

### RPC Commands

#### `keepalive.list`

Lists destinations in memory.

Name: keepalive.list

Parameters: none

##### `keepalive.list` RPC example

    			 keepalive.list

#### `keepalive.add`

Adds destination in memory.

Name: keepalive.add

Parameters: sip_uri listname

##### `keepalive.add` RPC example

    			 keepalive.add sip:username@domain listname

#### `keepalive.del`

Deletes destination in memory.

Name: keepalive.del

Parameters: sip_uri listname

##### `keepalive.del` RPC example

    			 keepalive.del sip:username@domain listname

#### `keepalive.get`

Gets destination in memory.

Name: keepalive.get

Parameters: sip_uri listname

##### `keepalive.get` RPC example

    			 keepalive.get sip:username@domain listname

#### `keepalive.flush`

Deletes all destinations in memory.

Name: keepalive.flush

Parameters:

##### `keepalive.flush` RPC example

    			 keepalive.flush