# &adminguide;

## Overview

The pike module keeps trace of all (or selected ones) incoming request's IP source and blocks the ones that exceed the limit. It works simultaneously for IPv4 and IPv6 addresses.

The module does not implement any actions on blocking - it just simply reports that there is high traffic from an IP; what to do, is the administrator decision (via scripting).

## Dependencies

### &kamailio; Modules

The following modules must be loaded before this module:

- No dependencies on other &kamailio; modules.

### External Libraries or Applications

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

- None.

## Parameters

### `sampling_time_unit` (integer)

Time period in seconds used for sampling (or the sampling accuracy). The smaller the better, but slower. If you want to detect peeks, use a small one. To limit the access (like total number of requests on a long period of time) to a proxy resource (a gateway for example), use a bigger value of this parameter.

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

Default value is 2.

#### Set `sampling_time_unit` parameter

    ...
    modparam("pike", "sampling_time_unit", 10)
    ...

### `reqs_density_per_unit` (integer)

How many requests should be allowed per `sampling_time_unit` before blocking all the incoming request from that IP. Practically, the blocking limit is between ( let's have x=reqs_density_per_unit) x and 3*x for IPv4 addresses and between x and 8*x for IPv6 addresses.

Default value is 30.

#### Set `reqs_density_per_unit` parameter

    ...
    modparam("pike", "reqs_density_per_unit", 30)
    ...

### `remove_latency` (integer)

Specifies for how long the IP address will be kept in memory after the last request from that IP address. It's a sort of timeout value, in seconds. Note that it is not the duration to keep the IP in state 'blocked'. An IP is unblocked next occurrence of 'sampling_time_unit' that does not exceed 'reqs_density_per_unit'. Keeping an IP in memory results in faster reaching of blocked state -- see the notes about the limits of getting to state 'blocked'.

Default value is 120.

#### Set `remove_latency` parameter

    ...
    modparam("pike", "remove_latency", 130)
    ...

### `pike_log_level` (integer)

Syslog log level to be used by module to auto report the blocking (only first time) and unblocking of IPs detected as source of floods.

Default value is 1 (L_WARN).

#### Set `pike_log_level` parameter

    ...
    modparam("pike", "pike_log_level", -1)
    ...

## Functions

### `pike_check_req()`

Process the source IP of the current request and return false if the IP was exceeding the blocking limit.

Return codes:

- 1 (true) - IP is not to be blocked or internal error occurred.

  IMPORTANT: in case of internal error, the function returns true to avoid reporting the current processed IP as blocked.

- -1 (false) - IP is source of flooding, previously detected

- -2 (false) - IP is detected as a new source of flooding - first time detection

This function can be used from REQUEST_ROUTE|ONREPLY_ROUTE.

#### `pike_check_req` usage

    ...
    if (!pike_check_req()) { exit; };
    ...

### `pike_check_ip(ipaddr)`

Process the IP address parameter and return false if it was exceeding the blocking limit. The return codes are the same from pike_check_req().

The parameter can contain variables.

This function can be used from REQUEST_ROUTE|ONREPLY_ROUTE.

#### `pike_check_ip` usage

    ...
    if (!pike_check_ip("1.2.3.4")) { exit; };
    ...
    if (!pike_check_ip("$si")) { exit; };
    ...

## RPC Commands

### `pike.top`

Lists nodes in the pike tree.

Name: pike.top

Parameters: filter (optional) - it can be "ALL", "HOT" or "WARM". If missing, the "HOT" nodes are listed.

RPC Command Example:

    ...
    &kamctl; rpc pike.top
    ...