mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
668 lines
16 KiB
668 lines
16 KiB
<?xml version="1.0" encoding='ISO-8859-1'?>
|
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
|
|
|
|
<!-- Include general documentation entities -->
|
|
<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
|
|
%docentities;
|
|
|
|
]>
|
|
<!-- Module User's Guide -->
|
|
|
|
<chapter>
|
|
|
|
<title>&adminguide;</title>
|
|
|
|
<section>
|
|
<title>Overview</title>
|
|
<para>
|
|
This module implements traffic limiting for SIP requests.
|
|
</para>
|
|
<para>
|
|
The module defines in an abstract mode the notion of 'pipe',
|
|
which can be a link to an IP address, to a network or a trunk.
|
|
The associtiation of traffic to a pipe is done in the config file,
|
|
therefore, a pipe could represent SIP traffic coming from a user or
|
|
the flow of specific SIP requests such as INVITE or REGISTER.
|
|
</para>
|
|
<para>
|
|
Pipelimit started from ratelimit module, adding support for definition
|
|
of pipes limits in database and dynamic names. Complexity of keeping
|
|
everything in a module and make it dual mode functional resulted in a
|
|
new module which is focused on just traffic shaping policies. For
|
|
description of the algorithms see the README of ratelimit.
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>Dependencies</title>
|
|
<section>
|
|
<title>&kamailio; Modules</title>
|
|
<para>
|
|
The following modules must be loaded before this module:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>database connection module</emphasis>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>External Libraries or Applications</title>
|
|
<para>
|
|
The following libraries or applications must be installed before
|
|
running &kamailio; with this module loaded:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>None</emphasis>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
</section>
|
|
<section>
|
|
<title>Parameters</title>
|
|
<section>
|
|
<title><varname>db_url</varname> (string)</title>
|
|
<para>
|
|
URL of the database server to be used.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>&defaultdb;</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>db_url</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("pipelimit", "db_url", "&exampledb;")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>plp_table_name</varname> (string)</title>
|
|
<para>
|
|
Name of DB table where data definition for pipes is stores.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>pl_pipes</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>plp_table_name</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("pipelimit", "plp_table_name", "mypipes")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>plp_pipeid_column</varname> (string)</title>
|
|
<para>
|
|
Name of 'pipeid' column.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>pipeid</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>plp_pipeid_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("pipelimit", "plp_pipeid_column", "name")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>plp_limit_column</varname> (string)</title>
|
|
<para>
|
|
Name of 'limit' column.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>limit</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>plp_limit_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("pipelimit", "plp_limit_column", "name")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>plp_algorithm_column</varname> (string)</title>
|
|
<para>
|
|
Name of 'algorithm' column.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>algorithm</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>plp_algorithm_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("pipelimit", "plp_algorithm_column", "name")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>timer_interval</varname> (integer)</title>
|
|
<para>
|
|
The initial length of a timer interval in seconds. All amounts of
|
|
messages have to be divided by this timer to get a messages per second
|
|
value.
|
|
</para>
|
|
<para>
|
|
IMPORTANT: A too small value may lead to performance penalties due to
|
|
timer process overloading.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is 10.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>timer_interval</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("pipelimit", "timer_interval", 5)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title><varname>reply_code</varname> (integer)</title>
|
|
<para>
|
|
The code of the reply sent by &kamailio; while limiting.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is 503.
|
|
</emphasis>
|
|
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>reply_code</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("pipelimit", "reply_code", 505)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
This value can be modified at runtime using &sercmd;
|
|
</para>
|
|
<example>
|
|
<title> Set <varname>reply_code</varname> parameter at runtime </title>
|
|
<programlisting format="linespecific">
|
|
|
|
&sercmd; cfg.set_now_int pipelimit reply_code 505
|
|
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title><varname>reply_reason</varname> (string)</title>
|
|
<para>
|
|
The reason of the reply sent by &kamailio; while limiting.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is "Server Unavailable".
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>reply_reason</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("pipelimit", "reply_reason", "Limiting")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
This value can be modified at runtime using &sercmd;
|
|
</para>
|
|
<example>
|
|
<title> Set <varname>reply_reason</varname> parameter at runtime </title>
|
|
<programlisting format="linespecific">
|
|
|
|
&sercmd; cfg.set_now_string pipelimit reply_reason "Limiting"
|
|
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
</section>
|
|
<section>
|
|
<title>Functions</title>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">pl_check(name)</function>
|
|
</title>
|
|
<para>
|
|
Check the current request against the 'name' pipe.
|
|
The pipe name can be provided via a pseudo variabile.
|
|
</para>
|
|
<para>The method will return:
|
|
<itemizedlist>
|
|
<listitem><para><emphasis>-2</emphasis> if no pipe was found</para></listitem>
|
|
<listitem><para><emphasis>-1</emphasis> if pipe limit was reached</para></listitem>
|
|
<listitem><para><emphasis>1</emphasis> if pipe limit was NOT reached</para></listitem>
|
|
<listitem><para><emphasis>2</emphasis> if pipe has NOP algorithm</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>Meaning of the parameters is as follows:</para>
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
<emphasis>name</emphasis> - the pseudovariable holding the pipe name.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
This function can be used from REQUEST_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>rl_check</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
# perform pipe match for current method
|
|
if (!pl_check("one")) {
|
|
pl_drop();
|
|
exit;
|
|
}
|
|
...
|
|
# use pipe 'one' for the current method via PV
|
|
$var(p) = "one";
|
|
$var(check_result) = pl_check("$var(p)");
|
|
switch($var(check_result)) {
|
|
case -2:
|
|
xlog("L_ALERT","pl_check(\"$var(p)\") drop -pipe NOT found\n");
|
|
pl_drop();
|
|
exit;
|
|
break;
|
|
case -1:
|
|
xlog("L_ALERT","pl_check(\"$var(p)\") drop\n");
|
|
pl_drop();
|
|
exit;
|
|
break;
|
|
case 1:
|
|
xlog("L_INFO", "pl_check(\"$var(p)\") pass\n");
|
|
break;
|
|
case 2:
|
|
xlog("L_ALERT","pl_check(\"$var(p)\") pass -NOP algorithm\n");
|
|
break;
|
|
default:
|
|
xlog("L_ERR","pl_check(\"$var(p)\") dropping \
|
|
with unexpected retcode=$var(check_result)\n");
|
|
pl_drop();
|
|
exit;
|
|
}
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">pl_drop([ [min ], max ])</function>
|
|
</title>
|
|
<para>
|
|
For the current request, a "503 - Server Unavailable" reply is sent back.
|
|
The reply may or may not have a "Retry-After" header. If no parameter is given,
|
|
there will be no "Retry-After" header. If only the
|
|
<emphasis>max</emphasis> parameter is given, the
|
|
reply will contain a "Retry-After: <emphasis>max</emphasis>" header. If both
|
|
<emphasis>min</emphasis> and <emphasis>max</emphasis> params are given, the
|
|
reply will contain a "Retry-After: <emphasis>random</emphasis>" header with
|
|
<emphasis>random</emphasis> being a random value between the given min and max.
|
|
</para>
|
|
<para>Meaning of the parameters is as follows:</para>
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
<emphasis>min</emphasis> - the minimum value of "Retry-After" header.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>max</emphasis> - the maximum value of "Retry-After" header.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
This function can be used from REQUEST_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>pl_drop</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
if (!pl_check("one")) {
|
|
# send back a "503 - Server Unavailable"
|
|
# with a "Retry-After: 5"
|
|
pl_drop("5");
|
|
exit;
|
|
}
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
</section>
|
|
|
|
<section>
|
|
<title>MI Commands</title>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">pl_stats</function>
|
|
</title>
|
|
<para>
|
|
Lists the parameters and variabiles in the pipelimit module.
|
|
</para>
|
|
<para>
|
|
Name: <emphasis>pl_stats</emphasis>
|
|
</para>
|
|
<para>Parameters: <emphasis>none</emphasis></para>
|
|
<para>
|
|
MI FIFO Command Format:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
:pl_stats:_reply_fifo_file_
|
|
_empty_line_
|
|
</programlisting>
|
|
</section>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">pl_set_pipe</function>
|
|
</title>
|
|
<para>
|
|
Sets the pipe parameters for the given pipe id.
|
|
</para>
|
|
<para>
|
|
Name: <emphasis>pl_set_pipe</emphasis>
|
|
</para>
|
|
<para>Parameters:</para>
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
<emphasis>pipe_id</emphasis> - pipe id.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>pipe_algorithm</emphasis> - the
|
|
algorithm assigned to the given pipe id.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>pipe_limit</emphasis> - the limit
|
|
assigned to the given pipe id.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
MI FIFO Command Format:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
:pl_set_pipe:_reply_fifo_file_
|
|
2
|
|
RED
|
|
10
|
|
_empty_line_
|
|
</programlisting>
|
|
</section>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">pl_get_pipes</function>
|
|
</title>
|
|
<para>
|
|
Gets the list of in use pipes.
|
|
</para>
|
|
<para>
|
|
Name: <emphasis>pl_get_pipes</emphasis>
|
|
</para>
|
|
<para>Parameters: <emphasis>none</emphasis></para>
|
|
<para>
|
|
MI FIFO Command Format:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
:pl_get_pipes:_reply_fifo_file_
|
|
_empty_line_
|
|
</programlisting>
|
|
</section>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">pl_set_pid</function>
|
|
</title>
|
|
<para>
|
|
Sets the PID Controller parameters for the Feedback Algorithm.
|
|
</para>
|
|
<para>
|
|
Name: <emphasis>pl_set_pid</emphasis>
|
|
</para>
|
|
<para>Parameters:</para>
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
<emphasis>ki</emphasis> - the integral parameter.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>kp</emphasis> - the proportional parameter.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>kd</emphasis> - the derivative parameter.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
MI FIFO Command Format:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
:pl_set_pid:_reply_fifo_file_
|
|
0.5
|
|
0.5
|
|
0.5
|
|
_empty_line_
|
|
</programlisting>
|
|
</section>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">pl_get_pid</function>
|
|
</title>
|
|
<para>
|
|
Gets the list of in use PID Controller parameters.
|
|
</para>
|
|
<para>
|
|
Name: <emphasis>pl_get_pid</emphasis>
|
|
</para>
|
|
<para>Parameters: <emphasis>none</emphasis></para>
|
|
<para>
|
|
MI FIFO Command Format:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
:pl_get_pid:_reply_fifo_file_
|
|
_empty_line_
|
|
</programlisting>
|
|
</section>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">pl_push_load</function>
|
|
</title>
|
|
<para>
|
|
Force the value of the load parameter. This command is useful
|
|
for testing the Feedback algorithm.
|
|
</para>
|
|
<para>
|
|
Name: <emphasis>pl_push_load</emphasis>
|
|
</para>
|
|
<para>Parameters:</para>
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
<emphasis>load</emphasis> - the forced value of load
|
|
(it must be greater then 0.0 and smaller then 1.0).
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
MI FIFO Command Format:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
:pl_push_load:_reply_fifo_file_
|
|
0.85
|
|
_empty_line_
|
|
</programlisting>
|
|
</section>
|
|
</section>
|
|
|
|
<section>
|
|
<title>RPC Commands</title>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">pl.stats</function>
|
|
</title>
|
|
<para>
|
|
Lists the parameters and variabiles in the pipelimit module:
|
|
pipe id, pipe load and pipe couter.
|
|
</para>
|
|
<para>
|
|
Name: <emphasis>pl.stats</emphasis>
|
|
</para>
|
|
<para>Parameters: <emphasis>none</emphasis></para>
|
|
<para>
|
|
RPC Command Format:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
kamcmd pl.stats
|
|
</programlisting>
|
|
</section>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">pl.set_pipe</function>
|
|
</title>
|
|
<para>
|
|
Sets the pipe parameters for the given pipe id.
|
|
</para>
|
|
<para>
|
|
Name: <emphasis>pl.set_pipe</emphasis>
|
|
</para>
|
|
<para>Parameters:</para>
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
<emphasis>pipe_id</emphasis> - pipe id.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>pipe_algorithm</emphasis> - the
|
|
algorithm assigned to the given pipe id.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>pipe_limit</emphasis> - the limit
|
|
assigned to the given pipe id.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
RPC Command Format:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
kamcmd pl.set_pipe 2 RED 10
|
|
</programlisting>
|
|
</section>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">pl.get_pipes</function>
|
|
</title>
|
|
<para>
|
|
Gets the list of in use pipes.
|
|
</para>
|
|
<para>
|
|
Name: <emphasis>pl.get_pipes</emphasis>
|
|
</para>
|
|
<para>Parameters: <emphasis>none</emphasis></para>
|
|
<para>
|
|
RPC Command Format:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
kamcmd pl.get_pipes
|
|
</programlisting>
|
|
</section>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">pl.set_pid</function>
|
|
</title>
|
|
<para>
|
|
Sets the PID Controller parameters for the Feedback Algorithm.
|
|
</para>
|
|
<para>
|
|
Name: <emphasis>pl.set_pid</emphasis>
|
|
</para>
|
|
<para>Parameters:</para>
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
<emphasis>ki</emphasis> - the integral parameter.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>kp</emphasis> - the proportional parameter.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>kd</emphasis> - the derivative parameter.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
RPC Command Format:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
kamcmd pl.set_pid 0.5 0.5 0.5
|
|
</programlisting>
|
|
</section>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">pl.get_pid</function>
|
|
</title>
|
|
<para>
|
|
Gets the list of in use PID Controller parameters.
|
|
</para>
|
|
<para>
|
|
Name: <emphasis>pl.get_pid</emphasis>
|
|
</para>
|
|
<para>Parameters: <emphasis>none</emphasis></para>
|
|
<para>
|
|
RPC Command Format:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
kamcmd pl.get_pid
|
|
</programlisting>
|
|
</section>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">pl.push_load</function>
|
|
</title>
|
|
<para>
|
|
Force the value of the load parameter. This command is useful
|
|
for testing the Feedback algorithm.
|
|
</para>
|
|
<para>
|
|
Name: <emphasis>pl.push_load</emphasis>
|
|
</para>
|
|
<para>Parameters:</para>
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
<emphasis>load</emphasis> - the forced value of load
|
|
(it must be greater then 0.0 and smaller then 1.0).
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
RPC Command Format:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
kamcmd pl.push_load 0.85
|
|
</programlisting>
|
|
</section>
|
|
</section>
|
|
|
|
</chapter>
|