pike(k): more notes about remove_latency

- clarification about the meaning of this parameter upon report by
  Miguel Baptista

modules_k/pike/README

@@ -8,36 +8,35 @@ Edited by
 
 Bogdan-Andrei Iancu
 
-   Copyright © 2003 FhG FOKUS
+   Copyright © 2003 FhG FOKUS
    Revision History
-   Revision $Revision$ $Date: 2008-08-06 12:08:33 +0200
-                              (Mi, 06 Aug 2008) $
-     __________________________________________________________
+   Revision $Revision$ $Date$
+     __________________________________________________________________
 
    Table of Contents
 
    1. Admin Guide
 
-        1.1. Overview
-        1.2. Dependencies
+        1. Overview
+        2. Dependencies
 
-              1.2.1. Kamailio Modules
-              1.2.2. External Libraries or Applications
+              2.1. Kamailio Modules
+              2.2. External Libraries or Applications
 
-        1.3. Exported Parameters
+        3. Exported Parameters
 
-              1.3.1. sampling_time_unit (integer)
-              1.3.2. reqs_density_per_unit (integer)
-              1.3.3. remove_latency (integer)
-              1.3.4. pike_log_level (integer)
+              3.1. sampling_time_unit (integer)
+              3.2. reqs_density_per_unit (integer)
+              3.3. remove_latency (integer)
+              3.4. pike_log_level (integer)
 
-        1.4. Exported Functions
+        4. Exported Functions
 
-              1.4.1. pike_check_req()
+              4.1. pike_check_req()
 
-        1.5. Exported MI Functions
+        5. Exported MI Functions
 
-              1.5.1. pike_list
+              5.1. pike_list
 
    2. Developer Guide
 
@@ -52,41 +51,72 @@ Bogdan-Andrei Iancu
 
 Chapter 1. Admin Guide
 
-1.1. Overview
+   Table of Contents
+
+   1. Overview
+   2. Dependencies
+
+        2.1. Kamailio Modules
+        2.2. External Libraries or Applications
+
+   3. Exported Parameters
+
+        3.1. sampling_time_unit (integer)
+        3.2. reqs_density_per_unit (integer)
+        3.3. remove_latency (integer)
+        3.4. pike_log_level (integer)
+
+   4. Exported Functions
+
+        4.1. pike_check_req()
 
-   The module keeps trace of all (or selected ones) incoming
-   request's IP source and blocks the ones that exceeded some
-   limit. Works simultaneous for IPv4 and IPv6 addresses.
+   5. Exported MI Functions
 
-   The module does not implement any actions on blocking - it just
-   simply reports that there is a high traffic from an IP; what to
-   do, is the administator decision (via scripting).
+        5.1. pike_list
 
-1.2. Dependencies
+1. Overview
 
-1.2.1. Kamailio Modules
+   The module keeps trace of all (or selected ones) incoming request's IP
+   source and blocks the ones that exceeded some limit. Works simultaneous
+   for IPv4 and IPv6 addresses.
+
+   The module does not implement any actions on blocking - it just simply
+   reports that there is a high traffic from an IP; what to do, is the
+   administator decision (via scripting).
+
+2. Dependencies
+
+   2.1. Kamailio Modules
+   2.2. External Libraries or Applications
+
+2.1. Kamailio Modules
 
    The following modules must be loaded before this module:
      * No dependencies on other Kamailio modules.
 
-1.2.2. External Libraries or Applications
+2.2. External Libraries or Applications
 
-   The following libraries or applications must be installed
-   before running Kamailio with this module loaded:
+   The following libraries or applications must be installed before
+   running Kamailio with this module loaded:
      * None.
 
-1.3. Exported Parameters
+3. Exported Parameters
 
-1.3.1. sampling_time_unit (integer)
+   3.1. sampling_time_unit (integer)
+   3.2. reqs_density_per_unit (integer)
+   3.3. remove_latency (integer)
+   3.4. pike_log_level (integer)
 
-   Time period 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 ex), use a bigger value of this parameter.
+3.1. sampling_time_unit (integer)
 
-   IMPORTANT: a too small value may lead to performance penalties
-   due timer process overloading.
+   Time period 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 ex), use a bigger
+   value of this parameter.
+
+   IMPORTANT: a too small value may lead to performance penalties due
+   timer process overloading.
 
    Default value is 2.
 
@@ -95,13 +125,12 @@ Chapter 1. Admin Guide
 modparam("pike", "sampling_time_unit", 10)
 ...
 
-1.3.2. reqs_density_per_unit (integer)
+3.2. 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.
+   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.
 
@@ -110,11 +139,15 @@ modparam("pike", "sampling_time_unit", 10)
 modparam("pike", "reqs_density_per_unit", 30)
 ...
 
-1.3.3. remove_latency (integer)
+3.3. remove_latency (integer)
 
-   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.
+   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. Note that
+   it is not the duration to keep the IP in state 'blocked'. An IP is
+   unblocked next occurence 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.
 
@@ -123,11 +156,10 @@ modparam("pike", "reqs_density_per_unit", 30)
 modparam("pike", "remove_latency", 130)
 ...
 
-1.3.4. pike_log_level (integer)
+3.4. pike_log_level (integer)
 
-   Log level to be used by module to auto report the blocking
-   (only first time) and unblocking of IPs detected as source of
-   floods.
+   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).
 
@@ -136,25 +168,24 @@ modparam("pike", "remove_latency", 130)
 modparam("pike", "pike_log_level", -1)
 ...
 
-1.4. Exported Functions
+4. Exported Functions
+
+   4.1. pike_check_req()
 
-1.4.1.  pike_check_req()
+4.1.  pike_check_req()
 
-   Process the source IP of the current request and returns false
-   if the IP was exceeding the blocking limit.
+   Process the source IP of the current request and returns false if the
+   IP was exceeding the blocking limit.
 
    Return codes:
-     * 1 (true) - IP is not to be blocked or internal error
-       occured.
+     * 1 (true) - IP is not to be blocked or internal error occured.
 
 Warning
-       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, being previously
-       detected
-     * -2 (false) - IP is detected as a new source of flooding -
-       first time detection
+       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, being previously detected
+     * -2 (false) - IP is detected as a new source of flooding - first
+       time detection
 
    This function can be used from REQUEST_ROUTE.
 
@@ -163,9 +194,11 @@ Warning
 if (!pike_check_req()) { exit; };
 ...
 
-1.5. Exported MI Functions
+5. Exported MI Functions
+
+   5.1. pike_list
 
-1.5.1.  pike_list
+5.1.  pike_list
 
    Lists the nodes in the pike tree.
 
@@ -179,9 +212,8 @@ if (!pike_check_req()) { exit; };
 
 Chapter 2. Developer Guide
 
-   One single tree (for both IPv4 and IPv6) is used. Each node
-   contains a byte, the IP addresses stretching from root to the
-   leafs.
+   One single tree (for both IPv4 and IPv6) is used. Each node contains a
+   byte, the IP addresses stretching from root to the leafs.
 
    Example 2.1. Tree of IP addresses
            / 193 - 175 - 132 - 164
@@ -189,37 +221,33 @@ tree root /                  \ 142
           \ 195 - 37 - 78 - 163
            \ 79 - 134
 
-   To detect the whole address, step by step, from the root to the
-   leafs, the nodes corresponding to each byte of the ip address
-   are expanded. In order to be expended a node has to be hit for
-   a given number of times (possible by different addresses; in
-   the previous example, the node "37" was expended by the
-   195.37.78.163 and 195.37.79.134 hits).
+   To detect the whole address, step by step, from the root to the leafs,
+   the nodes corresponding to each byte of the ip address are expanded. In
+   order to be expended a node has to be hit for a given number of times
+   (possible by different addresses; in the previous example, the node
+   “37� was expended by the 195.37.78.163 and 195.37.79.134 hits).
 
    For 193.175.132.164 with x= reqs_density_per_unit:
-     * After first req hits -> the "193" node is built.
-     * After x more hits, the "175" node is build; the hits of
-       "193" node are split between itself and its child--both of
-       them gone have x/2.
-     * And so on for node "132" and "164".
-     * Once "164" build the entire address can be found in the
-       tree. "164" becomes a leaf. After it will be hit as a leaf
-       for x times, it will become "RED" (further request from
-       this address will be blocked).
-
-   So, to build and block this address were needed 3*x hits. Now,
-   if reqs start coming from 193.175.132.142, the first 3 bytes
-   are already in the tree (they are shared with the previous
-   address), so I will need only x hits (to build node "142" and
-   to make it "RED") to make this address also to be blocked. This
-   is the reason for the variable number of hits necessary to
-   block an IP.
+     * After first req hits -> the “193� node is built.
+     * After x more hits, the “175� node is build; the hits of “193� node
+       are split between itself and its child--both of them gone have x/2.
+     * And so on for node “132� and “164�.
+     * Once “164� build the entire address can be found in the tree. “164�
+       becomes a leaf. After it will be hit as a leaf for x times, it will
+       become “RED� (further request from this address will be blocked).
+
+   So, to build and block this address were needed 3*x hits. Now, if reqs
+   start coming from 193.175.132.142, the first 3 bytes are already in the
+   tree (they are shared with the previous address), so I will need only x
+   hits (to build node “142� and to make it “RED�) to make this address
+   also to be blocked. This is the reason for the variable number of hits
+   necessary to block an IP.
 
    The maximum number of hits to turn an address red are (n is the
    address's number of bytes):
 
-   1 (first byte) + x (second byte) + (x / 2) * (n - 2) (for the
-   rest of the bytes) + (n - 1) (to turn the node to red).
+   1 (first byte) + x (second byte) + (x / 2) * (n - 2) (for the rest of
+   the bytes) + (n - 1) (to turn the node to red).
 
-   So, for IPv4 (n = 4) will be 3x and for IPv6 (n = 16) will be
-   9x. The minimum number of hits to turn an address red is x.
+   So, for IPv4 (n = 4) will be 3x and for IPv6 (n = 16) will be 9x. The
+   minimum number of hits to turn an address red is x.

modules_k/pike/doc/pike_admin.xml

@@ -111,7 +111,12 @@ modparam("pike", "reqs_density_per_unit", 30)
 		<title><varname>remove_latency</varname> (integer)</title>
 		<para>
 		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.
+		request from that IP address. It's a sort of timeout value. Note that
+		it is not the duration to keep the IP in state 'blocked'. An IP is
+		unblocked next occurence 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'.
 		</para>
 		<para>
 		<emphasis>