# &adminguide;

## Overview

This module implements traffic limiting for SIP requests.

The module defines in an abstract mode the notion of 'pipe', which can be a link to an IP address, to a network or a trunk. The associtiation of traffic to a pipe is done in the config file, therefore, a pipe could represent SIP traffic coming from a user or the flow of specific SIP requests such as INVITE or REGISTER.

Pipelimit started from ratelimit module, adding support for definition of pipes limits in database and dynamic names. Complexity of keeping everything in a module and make it dual mode functional resulted in a new module which is focused on just traffic shaping policies. For description of the algorithms see the README of ratelimit.

## Dependencies

### &kamailio; Modules

The following modules must be loaded before this module:

- database connection module.

### External Libraries or Applications

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

- None.

## Parameters

### `db_url` (string)

URL of the database server to be used.

Default value is &defaultdb;.

#### Set `db_url` parameter

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

### `plp_table_name` (string)

Name of DB table where data definition for pipes is stores.

Default value is pl_pipes.

#### Set `plp_table_name` parameter

    ...
    modparam("pipelimit", "plp_table_name", "mypipes")
    ...

### `plp_pipeid_column` (string)

Name of 'pipeid' column.

Default value is pipeid.

#### Set `plp_pipeid_column` parameter

    ...
    modparam("pipelimit", "plp_pipeid_column", "name")
    ...

### `plp_limit_column` (string)

Name of 'limit' column.

Default value is limit.

#### Set `plp_limit_column` parameter

    ...
    modparam("pipelimit", "plp_limit_column", "name")
    ...

### `plp_algorithm_column` (string)

Name of 'algorithm' column.

Default value is algorithm.

#### Set `plp_algorithm_column` parameter

    ...
    modparam("pipelimit", "plp_algorithm_column", "name")
    ...

### `timer_interval` (integer)

The initial length of a timer interval in seconds. All amounts of messages have to be divided by this timer to get a messages per second value.

IMPORTANT: A too small value may lead to performance penalties due to timer process overloading.

Default value is 10.

#### Set `timer_interval` parameter

    ...
    modparam("pipelimit", "timer_interval", 5)
    ...

### `reply_code` (integer)

The code of the reply sent by &kamailio; while limiting.

Default value is 503.

#### Set `reply_code` parameter

    ...
    modparam("pipelimit", "reply_code", 505)
    ...

This value can be modified at runtime using &sercmd;

#### Set `reply_code` parameter at runtime

    &sercmd; cfg.set_now_int pipelimit reply_code 505

### `reply_reason` (string)

The reason of the reply sent by &kamailio; while limiting.

Default value is "Server Unavailable".

#### Set `reply_reason` parameter

    ...
    modparam("pipelimit", "reply_reason", "Limiting")
    ...

This value can be modified at runtime using &sercmd;

#### Set `reply_reason` parameter at runtime

    &sercmd; cfg.set_now_string pipelimit reply_reason "Limiting"

## Functions

### `pl_check(name)`

Check the current request against the 'name' pipe. The pipe name can be provided via a pseudo variabile.

The method will return:

- -2 if no pipe was found

- -1 if pipe limit was reached

- 1 if pipe limit was NOT reached

- 2 if pipe has NOP algorithm

Meaning of the parameters is as follows:

- name - the pseudovariable holding the pipe name.

This function can be used from REQUEST_ROUTE.

#### `rl_check` usage

    ...
    	# perform pipe match for current method
    	if (!pl_check("one")) {
    		pl_drop();
    		exit;
    	}
    ...
    	# use pipe 'one' for the current method via PV
    	$var(p) = "one";
    	$var(check_result) = pl_check("$var(p)");
    	switch($var(check_result)) {
    	case -2:
    		xlog("L_ALERT","pl_check(\"$var(p)\") drop -pipe NOT found\n");
    		pl_drop();
    		exit;
    		break;
    	case -1:
    		xlog("L_ALERT","pl_check(\"$var(p)\") drop\n");
    		pl_drop();
    		exit;
    		break;
    	case 1:
    		xlog("L_INFO", "pl_check(\"$var(p)\") pass\n");
    		break;
    	case 2:
    		xlog("L_ALERT","pl_check(\"$var(p)\") pass -NOP algorithm\n");
    		break;
    	default:
    		xlog("L_ERR","pl_check(\"$var(p)\") dropping \
    with unexpected retcode=$var(check_result)\n");
    		pl_drop();
    		exit;
    	}
    ...

### `pl_drop([ [min ], max ])`

For the current request, a "503 - Server Unavailable" reply is sent back. The reply may or may not have a "Retry-After" header. If no parameter is given, there will be no "Retry-After" header. If only the max parameter is given, the reply will contain a "Retry-After: max" header. If both min and max params are given, the reply will contain a "Retry-After: random" header with random being a random value between the given min and max.

Meaning of the parameters is as follows:

- min - the minimum value of "Retry-After" header.

- max - the maximum value of "Retry-After" header.

This function can be used from REQUEST_ROUTE.

#### `pl_drop` usage

    ...
    	if (!pl_check("one")) {
    		# send back a "503 - Server Unavailable"
    		# with a "Retry-After: 5"
    		pl_drop("5");
    		exit;
    	}
    ...

## MI Commands

### `pl_stats`

Lists the parameters and variables in the pipelimit module.

Name: pl_stats

Parameters: none

MI FIFO Command Format:

    		:pl_stats:_reply_fifo_file_
    		_empty_line_

### `pl_set_pipe`

Sets the pipe parameters for the given pipe id.

Name: pl_set_pipe

Parameters:

- pipe_id - pipe id.

- pipe_algorithm - the algorithm assigned to the given pipe id.

- pipe_limit - the limit assigned to the given pipe id.

MI FIFO Command Format:

    		:pl_set_pipe:_reply_fifo_file_
    		2
    		RED
    		10
    		_empty_line_

### `pl_get_pipes`

Gets the list of in use pipes.

Name: pl_get_pipes

Parameters: none

MI FIFO Command Format:

    		:pl_get_pipes:_reply_fifo_file_
    		_empty_line_

### `pl_set_pid`

Sets the PID Controller parameters for the Feedback Algorithm.

Name: pl_set_pid

Parameters:

- ki - the integral parameter.

- kp - the proportional parameter.

- kd - the derivative parameter.

MI FIFO Command Format:

    		:pl_set_pid:_reply_fifo_file_
    		0.5
    		0.5
    		0.5
    		_empty_line_

### `pl_get_pid`

Gets the list of in use PID Controller parameters.

Name: pl_get_pid

Parameters: none

MI FIFO Command Format:

    		:pl_get_pid:_reply_fifo_file_
    		_empty_line_

### `pl_push_load`

Force the value of the load parameter. This command is useful for testing the Feedback algorithm.

Name: pl_push_load

Parameters:

- load - the forced value of load (it must be greater then 0.0 and smaller then 1.0).

MI FIFO Command Format:

    		:pl_push_load:_reply_fifo_file_
    		0.85
    		_empty_line_

## RPC Commands

### `pl.stats`

Lists the parameters and variabiles in the pipelimit module: pipe id, pipe load and pipe couter.

Name: pl.stats

Parameters: none

RPC Command Format:

    	kamcmd pl.stats

### `pl.set_pipe`

Sets the pipe parameters for the given pipe id.

Name: pl.set_pipe

Parameters:

- pipe_id - pipe id.

- pipe_algorithm - the algorithm assigned to the given pipe id.

- pipe_limit - the limit assigned to the given pipe id.

RPC Command Format:

    	kamcmd pl.set_pipe 2 RED 10

### `pl.get_pipes`

Gets the list of in use pipes.

Name: pl.get_pipes

Parameters: none

RPC Command Format:

    	kamcmd pl.get_pipes

### `pl.set_pid`

Sets the PID Controller parameters for the Feedback Algorithm.

Name: pl.set_pid

Parameters:

- ki - the integral parameter.

- kp - the proportional parameter.

- kd - the derivative parameter.

RPC Command Format:

    	kamcmd pl.set_pid 0.5 0.5 0.5

### `pl.get_pid`

Gets the list of in use PID Controller parameters.

Name: pl.get_pid

Parameters: none

RPC Command Format:

    	kamcmd pl.get_pid

### `pl.push_load`

Force the value of the load parameter. This command is useful for testing the Feedback algorithm.

Name: pl.push_load

Parameters:

- load - the forced value of load (it must be greater then 0.0 and smaller then 1.0).

RPC Command Format:

    	kamcmd pl.push_load 0.85