3b72316f9978dad148c907b378c665e6ea697aeb
[sip-router] / modules_k / pike / doc / pike_admin.xml
1 <?xml version="1.0" encoding='ISO-8859-1'?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
4
5 <!-- Include general documentation entities -->
6 <!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
7 %docentities;
8
9 ]>
10 <!-- Module User's Guide -->
11
12 <chapter>
13         
14         <title>&adminguide;</title>
15         
16         <section>
17         <title>Overview</title>
18         <para>
19                 The module keeps trace of all (or selected ones) incoming request's IP
20                 source and blocks the ones that exceeded some limit. 
21                 Works simultaneous for IPv4 and IPv6 addresses.
22         </para>
23         <para>
24                 The module does not implement any actions on blocking - it just simply
25                 reports that there is a high traffic from an IP; what to do, is
26                 the administator decision (via scripting).
27         </para>
28         </section>
29         <section>
30         <title>Dependencies</title>
31         <section>
32                 <title>&kamailio; Modules</title>
33                 <para>
34                 The following modules must be loaded before this module:
35                         <itemizedlist>
36                         <listitem>
37                         <para>
38                                 <emphasis>No dependencies on other &kamailio; modules</emphasis>.
39                         </para>
40                         </listitem>
41                         </itemizedlist>
42                 </para>
43         </section>
44         <section>
45                 <title>External Libraries or Applications</title>
46                 <para>
47                 The following libraries or applications must be installed before 
48                 running &kamailio; with this module loaded:
49                         <itemizedlist>
50                         <listitem>
51                         <para>
52                                 <emphasis>None</emphasis>.
53                         </para>
54                         </listitem>
55                         </itemizedlist>
56                 </para>
57         </section>
58         </section>
59         <section>
60         <title>Exported Parameters</title>
61         <section>
62                 <title><varname>sampling_time_unit</varname> (integer)</title>
63                 <para>
64                 Time period used for sampling (or the sampling accuracy ;-) ). The 
65                 smaller the better, but slower. If you want to detect peeks, use a 
66                 small one. To limit the access (like total number of requests on a 
67                 long period of time) to a proxy resource (a gateway for ex), use 
68                 a bigger value of this parameter.
69                 </para>
70                 <para>
71                 IMPORTANT: a too small value may lead to performance penalties due 
72                 timer process overloading.
73                 </para>
74                 <para>
75                 <emphasis>
76                         Default value is 2.
77                 </emphasis>
78                 </para>
79                 <example>
80                 <title>Set <varname>sampling_time_unit</varname> parameter</title>
81                 <programlisting format="linespecific">
82 ...
83 modparam("pike", "sampling_time_unit", 10)
84 ...
85 </programlisting>
86                 </example>
87         </section>
88         <section>
89                 <title><varname>reqs_density_per_unit</varname> (integer)</title>
90                 <para>
91                 How many requests should be allowed per sampling_time_unit before 
92                 blocking all the incoming request from that IP. Practically, the 
93                 blocking limit is between ( let's have x=reqs_density_per_unit) x 
94                 and 3*x for IPv4 addresses and between x and 8*x for ipv6 addresses.
95                 </para>
96                 <para>
97                 <emphasis>
98                         Default value is 30.
99                 </emphasis>
100                 </para>
101                 <example>
102                 <title>Set <varname>reqs_density_per_unit</varname> parameter</title>
103                 <programlisting format="linespecific">
104 ...
105 modparam("pike", "reqs_density_per_unit", 30)
106 ...
107 </programlisting>
108                 </example>
109         </section>
110         <section>
111                 <title><varname>remove_latency</varname> (integer)</title>
112                 <para>
113                 For how long the IP address will be kept in memory after the last 
114                 request from that IP address. It's a sort of timeout value. Note that
115                 it is not the duration to keep the IP in state 'blocked'. An IP is
116                 unblocked next occurence of 'sampling_time_unit' that does not exceed
117                 'reqs_density_per_unit'. Keeping an IP in memory results in faster
118                 reaching of blocked state -- see the notes about the limits of getting
119                 to state 'blocked'.
120                 </para>
121                 <para>
122                 <emphasis>
123                         Default value is 120.
124                 </emphasis>
125                 </para>
126                 <example>
127                 <title>Set <varname>remove_latency</varname> parameter</title>
128                 <programlisting format="linespecific">
129 ...
130 modparam("pike", "remove_latency", 130)
131 ...
132 </programlisting>
133                 </example>
134         </section>
135         <section>
136                 <title><varname>pike_log_level</varname> (integer)</title>
137                 <para>
138                 Log level to be used by module to auto report the blocking (only first
139                 time) and unblocking of IPs detected as source of floods.
140                 </para>
141                 <para>
142                 <emphasis>
143                         Default value is 1 (L_WARN).
144                 </emphasis>
145                 </para>
146                 <example>
147                 <title>Set <varname>pike_log_level</varname> parameter</title>
148                 <programlisting format="linespecific">
149 ...
150 modparam("pike", "pike_log_level", -1)
151 ...
152 </programlisting>
153                 </example>
154         </section>
155         </section>
156
157
158         <section>
159         <title>Exported Functions</title>
160         <section>
161                 <title>
162                 <function moreinfo="none">pike_check_req()</function>
163                 </title>
164                 <para>
165                 Process the source IP of the current request and returns false if 
166                 the IP was exceeding the blocking limit.
167                 </para>
168                 <para>
169                 Return codes:
170                 <itemizedlist>
171                         <listitem>
172                         <para>
173                                 <emphasis>1 (true)</emphasis> - IP is not to be blocked or 
174                                 internal error occured.
175                         </para>
176                         <warning>
177                         IMPORTANT: in case of internal error, the function returns true to
178                         avoid reporting the current processed IP as blocked.
179                         </warning>
180                         </listitem>
181                         <listitem>
182                         <para>
183                                 <emphasis>-1 (false)</emphasis> - IP is source of
184                                 flooding, being previously detected
185                         </para>
186                         </listitem>
187                         <listitem>
188                         <para>
189                                 <emphasis>-2 (false)</emphasis> - IP is detected as a new 
190                                 source of flooding - first time detection
191                         </para>
192                         </listitem>
193                 </itemizedlist>
194                 </para>
195                 <para>
196                 This function can be used from REQUEST_ROUTE.
197                 </para>
198                 <example>
199                 <title><function>pike_check_req</function> usage</title>
200                 <programlisting format="linespecific">
201 ...
202 if (!pike_check_req()) { exit; };
203 ...
204 </programlisting>
205                 </example>
206         </section>
207         </section>
208
209         <section>
210         <title>Exported MI Functions</title>
211         <section>
212                 <title>
213                 <function moreinfo="none">pike_list</function>
214                 </title>
215                 <para>
216                 Lists the nodes in the pike tree.
217                 </para>
218                 <para>
219                 Name: <emphasis>pike_list</emphasis>
220                 </para>
221                 <para>Parameters: <emphasis>none</emphasis></para>
222                 <para>
223                 MI FIFO Command Format:
224                 </para>
225                 <programlisting  format="linespecific">
226                 :pike_list:_reply_fifo_file_
227                 _empty_line_
228                 </programlisting>
229         </section>
230         </section>
231
232
233 </chapter>
234