sipwise
/
kamailio
mirror of https://github.com/sipwise/kamailio.git
1
0
Fork 0
Code Issues Releases Wiki Activity
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.
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '4.0.3-5'
${ noResults }
kamailio/modules/pipelimit/README

535 lines
12 KiB
Raw Permalink Blame History

pipelimit Module
Daniel-Constantin Mierla
Hendrik Scholz
Edited by
Ovidiu Sas
Edited by
Daniel-Constantin Mierla
Copyright © 2013 VoIPEmbedded Inc.
Copyright © 2010 Asipto.com
Copyright © 2006 Freenet Cityline GmbH
__________________________________________________________________
Table of Contents
1. Admin Guide
1. Overview
2. Dependencies
2.1. Kamailio Modules
2.2. External Libraries or Applications
3. Parameters
3.1. db_url (string)
3.2. plp_table_name (string)
3.3. plp_pipeid_column (string)
3.4. plp_limit_column (string)
3.5. plp_algorithm_column (string)
3.6. timer_interval (integer)
3.7. reply_code (integer)
3.8. reply_reason (string)
4. Functions
4.1. pl_check(name)
4.2. pl_drop([ [min ], max ])
5. MI Commands
5.1. pl_stats
5.2. pl_set_pipe
5.3. pl_get_pipes
5.4. pl_set_pid
5.5. pl_get_pid
5.6. pl_push_load
6. RPC Commands
6.1. pl.stats
6.2. pl.set_pipe
6.3. pl.get_pipes
6.4. pl.set_pid
6.5. pl.get_pid
6.6. pl.push_load
List of Examples
1.1. Set db_url parameter
1.2. Set plp_table_name parameter
1.3. Set plp_pipeid_column parameter
1.4. Set plp_limit_column parameter
1.5. Set plp_algorithm_column parameter
1.6. Set timer_interval parameter
1.7. Set reply_code parameter
1.8. Set reply_code parameter at runtime
1.9. Set reply_reason parameter
1.10. Set reply_reason parameter at runtime
1.11. rl_check usage
1.12. pl_drop usage
Chapter 1. Admin Guide
Table of Contents
1. Overview
2. Dependencies
2.1. Kamailio Modules
2.2. External Libraries or Applications
3. Parameters
3.1. db_url (string)
3.2. plp_table_name (string)
3.3. plp_pipeid_column (string)
3.4. plp_limit_column (string)
3.5. plp_algorithm_column (string)
3.6. timer_interval (integer)
3.7. reply_code (integer)
3.8. reply_reason (string)
4. Functions
4.1. pl_check(name)
4.2. pl_drop([ [min ], max ])
5. MI Commands
5.1. pl_stats
5.2. pl_set_pipe
5.3. pl_get_pipes
5.4. pl_set_pid
5.5. pl_get_pid
5.6. pl_push_load
6. RPC Commands
6.1. pl.stats
6.2. pl.set_pipe
6.3. pl.get_pipes
6.4. pl.set_pid
6.5. pl.get_pid
6.6. pl.push_load
1. Overview
This module implements traffic limiting for SIP requests.
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.
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.
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:
* database connection module.
2.2. External Libraries or Applications
The following libraries or applications must be installed before
running Kamailio with this module loaded:
* None.
3. Parameters
3.1. db_url (string)
3.2. plp_table_name (string)
3.3. plp_pipeid_column (string)
3.4. plp_limit_column (string)
3.5. plp_algorithm_column (string)
3.6. timer_interval (integer)
3.7. reply_code (integer)
3.8. reply_reason (string)
3.1. db_url (string)
URL of the database server to be used.
Default value is "mysql://kamailio:kamailiorw@localhost/kamailio".
Example 1.1. Set db_url parameter
...
modparam("pipelimit", "db_url", "dbdriver://username:password@dbhost/dbname")
...
3.2. plp_table_name (string)
Name of DB table where data definition for pipes is stores.
Default value is "pl_pipes".
Example 1.2. Set plp_table_name parameter
...
modparam("pipelimit", "plp_table_name", "mypipes")
...
3.3. plp_pipeid_column (string)
Name of 'pipeid' column.
Default value is "pipeid".
Example 1.3. Set plp_pipeid_column parameter
...
modparam("pipelimit", "plp_pipeid_column", "name")
...
3.4. plp_limit_column (string)
Name of 'limit' column.
Default value is "limit".
Example 1.4. Set plp_limit_column parameter
...
modparam("pipelimit", "plp_limit_column", "name")
...
3.5. plp_algorithm_column (string)
Name of 'algorithm' column.
Default value is "algorithm".
Example 1.5. Set plp_algorithm_column parameter
...
modparam("pipelimit", "plp_algorithm_column", "name")
...
3.6. timer_interval (integer)
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.
IMPORTANT: A too small value may lead to performance penalties due to
timer process overloading.
Default value is 10.
Example 1.6. Set timer_interval parameter
...
modparam("pipelimit", "timer_interval", 5)
...
3.7. reply_code (integer)
The code of the reply sent by Kamailio while limiting.
Default value is 503.
Example 1.7. Set reply_code parameter
...
modparam("pipelimit", "reply_code", 505)
...
This value can be modified at runtime using kamcmd
Example 1.8. Set reply_code parameter at runtime
kamcmd cfg.set_now_int pipelimit reply_code 505
3.8. reply_reason (string)
The reason of the reply sent by Kamailio while limiting.
Default value is "Server Unavailable".
Example 1.9. Set reply_reason parameter
...
modparam("pipelimit", "reply_reason", "Limiting")
...
This value can be modified at runtime using kamcmd
Example 1.10. Set reply_reason parameter at runtime
kamcmd cfg.set_now_string pipelimit reply_reason "Limiting"
4. Functions
4.1. pl_check(name)
4.2. pl_drop([ [min ], max ])
4.1. pl_check(name)
Check the current request against the 'name' pipe. The pipe name can be
provided via a pseudo variabile.
The method will return:
* -2 if no pipe was found
* -1 if pipe limit was reached
* 1 if pipe limit was NOT reached
* 2 if pipe has NOP algorithm
Meaning of the parameters is as follows:
* name - the pseudovariable holding the pipe name.
This function can be used from REQUEST_ROUTE.
Example 1.11. rl_check usage
...
# 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;
}
...
4.2. pl_drop([ [min ], max ])
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
max parameter is given, the reply will contain a "Retry-After: max"
header. If both min and max params are given, the reply will contain a
"Retry-After: random" header with random being a random value between
the given min and max.
Meaning of the parameters is as follows:
* min - the minimum value of "Retry-After" header.
* max - the maximum value of "Retry-After" header.
This function can be used from REQUEST_ROUTE.
Example 1.12. pl_drop usage
...
if (!pl_check("one")) {
# send back a "503 - Server Unavailable"
# with a "Retry-After: 5"
pl_drop("5");
exit;
}
...
5. MI Commands
5.1. pl_stats
5.2. pl_set_pipe
5.3. pl_get_pipes
5.4. pl_set_pid
5.5. pl_get_pid
5.6. pl_push_load
5.1. pl_stats
Lists the parameters and variabiles in the pipelimit module.
Name: pl_stats
Parameters: none
MI FIFO Command Format:
:pl_stats:_reply_fifo_file_
_empty_line_
5.2. pl_set_pipe
Sets the pipe parameters for the given pipe id.
Name: pl_set_pipe
Parameters:
* pipe_id - pipe id.
* pipe_algorithm - the algorithm assigned to the given pipe id.
* pipe_limit - the limit assigned to the given pipe id.
MI FIFO Command Format:
:pl_set_pipe:_reply_fifo_file_
2
RED
10
_empty_line_
5.3. pl_get_pipes
Gets the list of in use pipes.
Name: pl_get_pipes
Parameters: none
MI FIFO Command Format:
:pl_get_pipes:_reply_fifo_file_
_empty_line_
5.4. pl_set_pid
Sets the PID Controller parameters for the Feedback Algorithm.
Name: pl_set_pid
Parameters:
* ki - the integral parameter.
* kp - the proportional parameter.
* kd - the derivative parameter.
MI FIFO Command Format:
:pl_set_pid:_reply_fifo_file_
0.5
0.5
0.5
_empty_line_
5.5. pl_get_pid
Gets the list of in use PID Controller parameters.
Name: pl_get_pid
Parameters: none
MI FIFO Command Format:
:pl_get_pid:_reply_fifo_file_
_empty_line_
5.6. pl_push_load
Force the value of the load parameter. This command is useful for
testing the Feedback algorithm.
Name: pl_push_load
Parameters:
* load - the forced value of load (it must be greater then 0.0 and
smaller then 1.0).
MI FIFO Command Format:
:pl_push_load:_reply_fifo_file_
0.85
_empty_line_
6. RPC Commands
6.1. pl.stats
6.2. pl.set_pipe
6.3. pl.get_pipes
6.4. pl.set_pid
6.5. pl.get_pid
6.6. pl.push_load
6.1. pl.stats
Lists the parameters and variabiles in the pipelimit module: pipe id,
pipe load and pipe couter.
Name: pl.stats
Parameters: none
RPC Command Format:
kamcmd pl.stats
6.2. pl.set_pipe
Sets the pipe parameters for the given pipe id.
Name: pl.set_pipe
Parameters:
* pipe_id - pipe id.
* pipe_algorithm - the algorithm assigned to the given pipe id.
* pipe_limit - the limit assigned to the given pipe id.
RPC Command Format:
kamcmd pl.set_pipe 2 RED 10
6.3. pl.get_pipes
Gets the list of in use pipes.
Name: pl.get_pipes
Parameters: none
RPC Command Format:
kamcmd pl.get_pipes
6.4. pl.set_pid
Sets the PID Controller parameters for the Feedback Algorithm.
Name: pl.set_pid
Parameters:
* ki - the integral parameter.
* kp - the proportional parameter.
* kd - the derivative parameter.
RPC Command Format:
kamcmd pl.set_pid 0.5 0.5 0.5
6.5. pl.get_pid
Gets the list of in use PID Controller parameters.
Name: pl.get_pid
Parameters: none
RPC Command Format:
kamcmd pl.get_pid
6.6. pl.push_load
Force the value of the load parameter. This command is useful for
testing the Feedback algorithm.
Name: pl.push_load
Parameters:
* load - the forced value of load (it must be greater then 0.0 and
smaller then 1.0).
RPC Command Format:
kamcmd pl.push_load 0.85
Reference in new issue View Git Blame Copy Permalink