<!-- Module User's Guide -->

<chapter>
	<chapterinfo>
	<revhistory>
		<revision>
		<revnumber>$Revision: 1827 $</revnumber>
		<date>$Date: 2007-03-12 17:22:53 +0200 (Mon, 12 Mar 2007) $</date>
		</revision>
	</revhistory>
	</chapterinfo>
	<title>User's Guide</title>
	
	<section>
	<title>Overview</title>
	<para>
		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.
	</para>
	<para>
		The module does not implement any actions on blocking - it just simply
		reports that the there is an high traffic from an IP; what to do, is
		the administator decision (via scripting).
	</para>
	</section>
	<section>
	<title>Dependencies</title>
	<section>
		<title>&ser; Modules</title>
		<para>
		The following modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>No dependencies on other &ser; modules</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	<section>
		<title>External Libraries or Applications</title>
		<para>
		The following libraries or applications must be installed before 
		running &ser; with this module loaded:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>None</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>
	<section>
	<title>Exported Parameters</title>
	<section>
		<title><varname>sampling_time_unit</varname> (integer)</title>
		<para>
		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.
		</para>
		<para>
		IMPORTANT: a too small value may lead to performance penalties due 
		timer process overloading.
		</para>
		<para>
		<emphasis>
			Default value is 2.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>sampling_time_unit</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("pike", "sampling_time_unit", 10)
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>reqs_density_per_unit</varname> (integer)</title>
		<para>
		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.
		</para>
		<para>
		<emphasis>
			Default value is 30.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>reqs_density_per_unit</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("pike", "reqs_density_per_unit", 30)
...
</programlisting>
		</example>
	</section>
	<section>
		<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.
		</para>
		<para>
		<emphasis>
			Default value is 120.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>remove_latency</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("pike", "remove_latency", 130)
...
</programlisting>
		</example>
	</section>
	</section>
	<section>
	<title>Exported Functions</title>
	<section>
		<title>
		<function moreinfo="none">pike_check_req()</function>
		</title>
		<para>
		Process the source IP of the current request and returns false if 
		the IP was exceeding the blocking limit.
		</para>
		<para>
		IMPORTANT: in case of internal error, the function returns true to
		avoid reporting the current processed IP as blocked.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>pike_check_req</function> usage</title>
		<programlisting format="linespecific">
...
if (!pike_check_req()) { break; };
...
</programlisting>
		</example>
	</section>
	</section>

	<section>
	<title>Exported MI Functions</title>
	<section>
		<title>
		<function moreinfo="none">pike_list</function>
		</title>
		<para>
		Lists the nodes in the pike tree.
		</para>
		<para>
		Name: <emphasis>pike_list</emphasis>
		</para>
		<para>Parameters: <emphasis>none</emphasis></para>
 		<para>
		MI FIFO Command Format:
		</para>
        <programlisting  format="linespecific">
		:pike_list:_reply_fifo_file_
		_empty_line_
		</programlisting>
    </section>
    </section>

	
</chapter>

<!-- Keep this element at the end of the file
Local Variables:
sgml-parent-document: ("pike.sgml" "Book" "chapter")
End:
-->
