pike(k): add parameter unit, reported from dirtytoni at gmx dot de
[sip-router] / modules_k / pike / README
1 pike Module
2
3 Bogdan-Andrei Iancu
4
5    Voice Sistem SRL
6
7 Edited by
8
9 Bogdan-Andrei Iancu
10
11    Copyright © 2003 FhG FOKUS
12      __________________________________________________________________
13
14    Table of Contents
15
16    1. Admin Guide
17
18         1. Overview
19         2. Dependencies
20
21               2.1. Kamailio Modules
22               2.2. External Libraries or Applications
23
24         3. Exported Parameters
25
26               3.1. sampling_time_unit (integer)
27               3.2. reqs_density_per_unit (integer)
28               3.3. remove_latency (integer)
29               3.4. pike_log_level (integer)
30
31         4. Exported Functions
32
33               4.1. pike_check_req()
34
35         5. Exported MI Functions
36
37               5.1. pike_list
38
39    2. Developer Guide
40
41    List of Examples
42
43    1.1. Set sampling_time_unit parameter
44    1.2. Set reqs_density_per_unit parameter
45    1.3. Set remove_latency parameter
46    1.4. Set pike_log_level parameter
47    1.5. pike_check_req usage
48    2.1. Tree of IP addresses
49
50 Chapter 1. Admin Guide
51
52    Table of Contents
53
54    1. Overview
55    2. Dependencies
56
57         2.1. Kamailio Modules
58         2.2. External Libraries or Applications
59
60    3. Exported Parameters
61
62         3.1. sampling_time_unit (integer)
63         3.2. reqs_density_per_unit (integer)
64         3.3. remove_latency (integer)
65         3.4. pike_log_level (integer)
66
67    4. Exported Functions
68
69         4.1. pike_check_req()
70
71    5. Exported MI Functions
72
73         5.1. pike_list
74
75 1. Overview
76
77    The module keeps trace of all (or selected ones) incoming request's IP
78    source and blocks the ones that exceeded some limit. Works simultaneous
79    for IPv4 and IPv6 addresses.
80
81    The module does not implement any actions on blocking - it just simply
82    reports that there is a high traffic from an IP; what to do, is the
83    administator decision (via scripting).
84
85 2. Dependencies
86
87    2.1. Kamailio Modules
88    2.2. External Libraries or Applications
89
90 2.1. Kamailio Modules
91
92    The following modules must be loaded before this module:
93      * No dependencies on other Kamailio modules.
94
95 2.2. External Libraries or Applications
96
97    The following libraries or applications must be installed before
98    running Kamailio with this module loaded:
99      * None.
100
101 3. Exported Parameters
102
103    3.1. sampling_time_unit (integer)
104    3.2. reqs_density_per_unit (integer)
105    3.3. remove_latency (integer)
106    3.4. pike_log_level (integer)
107
108 3.1. sampling_time_unit (integer)
109
110    Time period in seconds used for sampling (or the sampling accuracy).
111    The smaller the better, but slower. If you want to detect peeks, use a
112    small one. To limit the access (like total number of requests on a long
113    period of time) to a proxy resource (a gateway for ex), use a bigger
114    value of this parameter.
115
116    IMPORTANT: a too small value may lead to performance penalties due
117    timer process overloading.
118
119    Default value is 2.
120
121    Example 1.1. Set sampling_time_unit parameter
122 ...
123 modparam("pike", "sampling_time_unit", 10)
124 ...
125
126 3.2. reqs_density_per_unit (integer)
127
128    How many requests should be allowed per sampling_time_unit before
129    blocking all the incoming request from that IP. Practically, the
130    blocking limit is between ( let's have x=reqs_density_per_unit) x and
131    3*x for IPv4 addresses and between x and 8*x for ipv6 addresses.
132
133    Default value is 30.
134
135    Example 1.2. Set reqs_density_per_unit parameter
136 ...
137 modparam("pike", "reqs_density_per_unit", 30)
138 ...
139
140 3.3. remove_latency (integer)
141
142    For how long the IP address will be kept in memory after the last
143    request from that IP address. It's a sort of timeout value, in seconds.
144    Note that it is not the duration to keep the IP in state 'blocked'. An
145    IP is unblocked next occurence of 'sampling_time_unit' that does not
146    exceed 'reqs_density_per_unit'. Keeping an IP in memory results in
147    faster reaching of blocked state -- see the notes about the limits of
148    getting to state 'blocked'.
149
150    Default value is 120.
151
152    Example 1.3. Set remove_latency parameter
153 ...
154 modparam("pike", "remove_latency", 130)
155 ...
156
157 3.4. pike_log_level (integer)
158
159    Log level to be used by module to auto report the blocking (only first
160    time) and unblocking of IPs detected as source of floods.
161
162    Default value is 1 (L_WARN).
163
164    Example 1.4. Set pike_log_level parameter
165 ...
166 modparam("pike", "pike_log_level", -1)
167 ...
168
169 4. Exported Functions
170
171    4.1. pike_check_req()
172
173 4.1.  pike_check_req()
174
175    Process the source IP of the current request and returns false if the
176    IP was exceeding the blocking limit.
177
178    Return codes:
179      * 1 (true) - IP is not to be blocked or internal error occured.
180
181 Warning
182        IMPORTANT: in case of internal error, the function returns true to
183        avoid reporting the current processed IP as blocked.
184      * -1 (false) - IP is source of flooding, being previously detected
185      * -2 (false) - IP is detected as a new source of flooding - first
186        time detection
187
188    This function can be used from REQUEST_ROUTE.
189
190    Example 1.5. pike_check_req usage
191 ...
192 if (!pike_check_req()) { exit; };
193 ...
194
195 5. Exported MI Functions
196
197    5.1. pike_list
198
199 5.1.  pike_list
200
201    Lists the nodes in the pike tree.
202
203    Name: pike_list
204
205    Parameters: none
206
207    MI FIFO Command Format:
208                 :pike_list:_reply_fifo_file_
209                 _empty_line_
210
211 Chapter 2. Developer Guide
212
213    One single tree (for both IPv4 and IPv6) is used. Each node contains a
214    byte, the IP addresses stretching from root to the leafs.
215
216    Example 2.1. Tree of IP addresses
217            / 193 - 175 - 132 - 164
218 tree root /                  \ 142
219           \ 195 - 37 - 78 - 163
220            \ 79 - 134
221
222    To detect the whole address, step by step, from the root to the leafs,
223    the nodes corresponding to each byte of the ip address are expanded. In
224    order to be expended a node has to be hit for a given number of times
225    (possible by different addresses; in the previous example, the node
226    “37” was expended by the 195.37.78.163 and 195.37.79.134 hits).
227
228    For 193.175.132.164 with x= reqs_density_per_unit:
229      * After first req hits -> the “193” node is built.
230      * After x more hits, the “175” node is build; the hits of “193” node
231        are split between itself and its child--both of them gone have x/2.
232      * And so on for node “132” and “164”.
233      * Once “164” build the entire address can be found in the tree. “164”
234        becomes a leaf. After it will be hit as a leaf for x times, it will
235        become “RED” (further request from this address will be blocked).
236
237    So, to build and block this address were needed 3*x hits. Now, if reqs
238    start coming from 193.175.132.142, the first 3 bytes are already in the
239    tree (they are shared with the previous address), so I will need only x
240    hits (to build node “142” and to make it “RED”) to make this address
241    also to be blocked. This is the reason for the variable number of hits
242    necessary to block an IP.
243
244    The maximum number of hits to turn an address red are (n is the
245    address's number of bytes):
246
247    1 (first byte) + x (second byte) + (x / 2) * (n - 2) (for the rest of
248    the bytes) + (n - 1) (to turn the node to red).
249
250    So, for IPv4 (n = 4) will be 3x and for IPv6 (n = 16) will be 9x. The
251    minimum number of hits to turn an address red is x.