pipelimit Module Daniel-Constantin Mierla Hendrik Scholz Edited by Ovidiu Sas 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. Algorithms 3. Dependencies 3.1. Kamailio Modules 3.2. External Libraries or Applications 4. Parameters 4.1. hash_size (int) 4.2. db_url (string) 4.3. plp_table_name (string) 4.4. plp_pipeid_column (string) 4.5. plp_limit_column (string) 4.6. plp_algorithm_column (string) 4.7. timer_interval (integer) 4.8. timer_mode (integer) 4.9. load_fetch (integer) 4.10. reply_code (integer) 4.11. reply_reason (string) 4.12. clean_unused (int) 5. Functions 5.1. pl_check(name [, algorithm, limit]) 5.2. pl_active(name) 5.3. pl_drop([ [min ], max ]) 6. RPC Commands 6.1. pl.list 6.2. pl.stats 6.3. pl.set_pipe 6.4. pl.reset_pipe 6.5. pl.rm_pipe 6.6. pl.get_pipes 6.7. pl.set_pid 6.8. pl.get_pid 6.9. pl.push_load List of Examples 1.1. Set hash_size parameter 1.2. Set db_url parameter 1.3. Set plp_table_name parameter 1.4. Set plp_pipeid_column parameter 1.5. Set plp_limit_column parameter 1.6. Set plp_algorithm_column parameter 1.7. Set timer_interval parameter 1.8. Set timer_mode parameter 1.9. Set load_fetch parameter 1.10. Set reply_code parameter 1.11. Set reply_code parameter at runtime 1.12. Set reply_reason parameter 1.13. Set reply_reason parameter at runtime 1.14. Set clean_unused parameter 1.15. Set clean_unused parameter at runtime 1.16. pl_check usage 1.17. pl_active usage 1.18. pl_drop usage Chapter 1. Admin Guide Table of Contents 1. Overview 2. Algorithms 3. Dependencies 3.1. Kamailio Modules 3.2. External Libraries or Applications 4. Parameters 4.1. hash_size (int) 4.2. db_url (string) 4.3. plp_table_name (string) 4.4. plp_pipeid_column (string) 4.5. plp_limit_column (string) 4.6. plp_algorithm_column (string) 4.7. timer_interval (integer) 4.8. timer_mode (integer) 4.9. load_fetch (integer) 4.10. reply_code (integer) 4.11. reply_reason (string) 4.12. clean_unused (int) 5. Functions 5.1. pl_check(name [, algorithm, limit]) 5.2. pl_active(name) 5.3. pl_drop([ [min ], max ]) 6. RPC Commands 6.1. pl.list 6.2. pl.stats 6.3. pl.set_pipe 6.4. pl.reset_pipe 6.5. pl.rm_pipe 6.6. pl.get_pipes 6.7. pl.set_pid 6.8. pl.get_pid 6.9. 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 reference to an IP address, to a network or a trunk. The association 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, the implementation of queues was discarded. 2. Algorithms Algorithms are based from the ratelimit module, which describes the algorithms in more detail. The algorithms are used by the pipelimit module to determine if a message should be blocked. Tail Drop Algorithm (TAILDROP) This is a trivial algorithm that imposes some risks when used in conjunction with long timer intervals. At the start of each interval an internal counter is reset and incremented for each incoming message. Once the counter hits the configured limit pl_check() returns false (negative value). Random Early Detection Algorithm (RED) The Random Early Detection Algorithm tries to circumvent the synchronization problem imposed by the tail drop algorithm by measuring the average load and adapting the drop rate dynamically. When running with the RED algorithm (enabled by default) Kamailio will return errors to the Kamailio routing engine every n'th packet trying to evenly spread the measured load of the last timer interval onto the current interval. As a negative side effect Kamailio might drop messages although the limit might not be reached within the interval. Decrease the timer interval if you encounter this. Network Algorithm (NETWORK) This algorithm relies on information provided by network interfaces. The total amount of bytes waiting to be consumed on all the network interfaces is retrieved once every timer_interval seconds. If the returned amount exceeds the limit specified in the modparam, pl_check() returns false (negative value). Feedback Algorithm (FEEDBACK) Using the PID Controller model (see Wikipedia page), the drop rate is adjusted dynamically based on the load factor so that the load factor always drifts towards the specified limit (or setpoint, in PID terms). As reading the CPU load average is relatively expensive (opening /proc/stat, parsing it, etc), this only happens once every timer_interval seconds and consequently the FEEDBACK value is only at these intervals recomputed. This in turn makes it difficult for the drop rate to adjust quickly. Worst case scenarios are request rates going up/down instantly by thousands - it takes up to 20 seconds for the controller to adapt to the new request rate. 3. Dependencies 3.1. Kamailio Modules 3.2. External Libraries or Applications 3.1. Kamailio Modules The following modules must be loaded before this module: * database connection module. * sl: Stateless Request Handling. 3.2. External Libraries or Applications The following libraries or applications must be installed before running Kamailio with this module loaded: * None. 4. Parameters 4.1. hash_size (int) 4.2. db_url (string) 4.3. plp_table_name (string) 4.4. plp_pipeid_column (string) 4.5. plp_limit_column (string) 4.6. plp_algorithm_column (string) 4.7. timer_interval (integer) 4.8. timer_mode (integer) 4.9. load_fetch (integer) 4.10. reply_code (integer) 4.11. reply_reason (string) 4.12. clean_unused (int) 4.1. hash_size (int) Used to compute the number of slots for the internal hash table, as power of 2 (number of slots = 2^hash_size, aka 1<