"Fossies" - the Fresh Open Source Software Archive

Member "opensips-3.0.1/modules/pike/README" (1 Oct 2019, 12664 Bytes) of package /linux/misc/opensips-3.0.1.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "README": 3.0.0_vs_3.0.1.

    1 pike Module
    2      __________________________________________________________
    3 
    4    Table of Contents
    5 
    6    1. Admin Guide
    7 
    8         1.1. Overview
    9         1.2. How to use
   10         1.3. Dependencies
   11 
   12               1.3.1. OpenSIPS Modules
   13               1.3.2. External Libraries or Applications
   14 
   15         1.4. Exported Parameters
   16 
   17               1.4.1. sampling_time_unit (integer)
   18               1.4.2. reqs_density_per_unit (integer)
   19               1.4.3. remove_latency (integer)
   20               1.4.4. check_route (integer)
   21               1.4.5. pike_log_level (integer)
   22 
   23         1.5. Exported Functions
   24 
   25               1.5.1. pike_check_req()
   26 
   27         1.6. Exported MI Functions
   28 
   29               1.6.1. pike_list
   30               1.6.2. pike_rm
   31 
   32         1.7. Exported Events
   33 
   34               1.7.1. E_PIKE_BLOCKED
   35 
   36    2. Developer Guide
   37    3. Contributors
   38 
   39         3.1. By Commit Statistics
   40         3.2. By Commit Activity
   41 
   42    4. Documentation
   43 
   44         4.1. Contributors
   45 
   46    List of Tables
   47 
   48    3.1. Top contributors by DevScore^(1), authored commits^(2) and
   49           lines added/removed^(3)
   50 
   51    3.2. Most recently active contributors^(1) to this module
   52 
   53    List of Examples
   54 
   55    1.1. Set sampling_time_unit parameter
   56    1.2. Set reqs_density_per_unit parameter
   57    1.3. Set remove_latency parameter
   58    1.4. Set check_route parameter
   59    1.5. Set pike_log_level parameter
   60    1.6. pike_check_req usage
   61    2.1. Tree of IP addresses
   62 
   63 Chapter 1. Admin Guide
   64 
   65 1.1. Overview
   66 
   67    The module provides a simple mechanism for DOS protection - DOS
   68    based on floods at network level. The module keeps trace of all
   69    (or selected ones) IPs of incoming SIP traffic (as source IP)
   70    and blocks the ones that exceeded some limit. Works
   71    simultaneous for IPv4 and IPv6 addresses.
   72 
   73    The module does not implement any actions on blocking - it just
   74    simply reports that there is a high traffic from an IP; what to
   75    do, is the administator decision (via scripting).
   76 
   77 1.2. How to use
   78 
   79    There are 2 ways of using this module (as detecting flood
   80    attacks and as taking the right action to limit the impact on
   81    the system):
   82      * manual - from routing script you can force the check of the
   83        source IP of an incoming requests, using "pike_check_req"
   84        function. Note that this checking works only for SIP
   85        requests and you can decide (based on scripting logic) what
   86        source IPs to be monitored and what action to be taken when
   87        a flood is detected.
   88      * automatic - the module will install internal hooks to catch
   89        all incoming requests and replies (even if not well formed
   90        from SIP point of view) - more or less the module will
   91        monitor all incoming packages (from the network) on the SIP
   92        sockets. Each time the source IP of a package needs to be
   93        analyse (to see if trusted or not), the module will run a
   94        script route - see "check_route" module parameter -, where,
   95        based on custom logic, you can decide if that IP needs to
   96        be monitored for flooding or not. As action, when flood is
   97        detected, the module will automatically drop the packages.
   98 
   99 1.3. Dependencies
  100 
  101 1.3.1. OpenSIPS Modules
  102 
  103    The following modules must be loaded before this module:
  104      * No dependencies on other OpenSIPS modules.
  105 
  106 1.3.2. External Libraries or Applications
  107 
  108    The following libraries or applications must be installed
  109    before running OpenSIPS with this module loaded:
  110      * None.
  111 
  112 1.4. Exported Parameters
  113 
  114 1.4.1. sampling_time_unit (integer)
  115 
  116    Time period used for sampling (or the sampling accuracy ;-) ).
  117    The smaller the better, but slower. If you want to detect
  118    peaks, use a small one. To limit the access (like total number
  119    of requests on a long period of time) to a proxy resource (a
  120    gateway for ex), use a bigger value of this parameter.
  121 
  122    IMPORTANT: a too small value may lead to performance penalties
  123    due timer process overloading.
  124 
  125    Default value is 2.
  126 
  127    Example 1.1. Set sampling_time_unit parameter
  128 ...
  129 modparam("pike", "sampling_time_unit", 10)
  130 ...
  131 
  132 1.4.2. reqs_density_per_unit (integer)
  133 
  134    How many requests should be allowed per sampling_time_unit
  135    before blocking all the incoming request from that IP.
  136    Practically, the blocking limit is between ( let's have
  137    x=reqs_density_per_unit) x and 3*x for IPv4 addresses and
  138    between x and 8*x for ipv6 addresses.
  139 
  140    Default value is 30.
  141 
  142    Example 1.2. Set reqs_density_per_unit parameter
  143 ...
  144 modparam("pike", "reqs_density_per_unit", 30)
  145 ...
  146 
  147 1.4.3. remove_latency (integer)
  148 
  149    For how long the IP address will be kept in memory after the
  150    last request from that IP address. It's a sort of timeout
  151    value.
  152 
  153    Note: If the remove_latency value is lower than
  154    sampling_time_unit value, nodes might expire before being
  155    unblocked, therefore losing some UNBLOCK events. In order to
  156    prevent this, if the remove_latency is lower, OpenSIPS
  157    internally forces its value to sampling_time_unit + 1.
  158 
  159    Default value is 120.
  160 
  161    Example 1.3. Set remove_latency parameter
  162 ...
  163 modparam("pike", "remove_latency", 130)
  164 ...
  165 
  166 1.4.4. check_route (integer)
  167 
  168    The name of the script route to be triggers (in automatic way)
  169    when a package is received from the network. If you do a "drop"
  170    in this route, it will indicate to the module that the source
  171    IP of the package does not need to be monitored. Otherwise, the
  172    source IP will be automatically monitered.
  173 
  174    By defining this parameter, the automatic checking mode is
  175    enabled.
  176 
  177    Default value is NONE (no auto mode).
  178 
  179    Example 1.4. Set check_route parameter
  180 ...
  181 modparam("pike", "check_route", "pike")
  182 ...
  183 route[pike]{
  184     if ($si==111.222.111.222)  /*trusted, do not check it*/
  185         drop;
  186     /* all other IPs are checked*/
  187 }
  188 ....
  189 
  190 1.4.5. pike_log_level (integer)
  191 
  192    Log level to be used by module to auto report the blocking
  193    (only first time) and unblocking of IPs detected as source of
  194    floods.
  195 
  196    Default value is 1 (L_WARN).
  197 
  198    Example 1.5. Set pike_log_level parameter
  199 ...
  200 modparam("pike", "pike_log_level", -1)
  201 ...
  202 
  203 1.5. Exported Functions
  204 
  205 1.5.1.  pike_check_req()
  206 
  207    Process the source IP of the current request and returns false
  208    if the IP was exceeding the blocking limit.
  209 
  210    Return codes:
  211      * 1 (true) - IP is not to be blocked or internal error
  212        occurred.
  213 
  214 Warning
  215        IMPORTANT: in case of internal error, the function returns
  216        true to avoid reporting the current processed IP as
  217        blocked.
  218      * -1 (false) - IP is source of flooding, being previously
  219        detected
  220      * -2 (false) - IP is detected as a new source of flooding -
  221        first time detection
  222 
  223    This function can be used from REQUEST_ROUTE.
  224 
  225    Example 1.6. pike_check_req usage
  226 ...
  227 if (!pike_check_req()) { exit; };
  228 ...
  229 
  230 1.6. Exported MI Functions
  231 
  232 1.6.1.  pike_list
  233 
  234    Lists the nodes in the pike tree.
  235 
  236    Name: pike_list
  237 
  238    Parameters: none
  239 
  240    MI FIFO Command Format:
  241                 opensips-cli -x mi pike_list
  242 
  243 1.6.2.  pike_rm
  244 
  245    Remove a node from the pike tree by IP address.
  246 
  247    Name: pike_rm
  248 
  249    Parameters:
  250      * IP - IP address currently blocked.
  251 
  252    MI FIFO Command Format:
  253                 opensips-cli -x mi pike_rm 10.0.0.106
  254 
  255 1.7. Exported Events
  256 
  257 1.7.1.  E_PIKE_BLOCKED
  258 
  259    This event is raised when the pike module decides that an IP
  260    should be blocked.
  261 
  262    Parameters:
  263      * ip - the IP address that has been blocked.
  264 
  265 Chapter 2. Developer Guide
  266 
  267    One single tree (for both IPv4 and IPv6) is used. Each node
  268    contains a byte, the IP addresses stretching from root to the
  269    leafs.
  270 
  271    Example 2.1. Tree of IP addresses
  272            / 193 - 175 - 132 - 164
  273 tree root /                  \ 142
  274           \ 195 - 37 - 78 - 163
  275            \ 79 - 134
  276 
  277    To detect the whole address, step by step, from the root to the
  278    leafs, the nodes corresponding to each byte of the ip address
  279    are expanded. In order to be expended a node has to be hit for
  280    a given number of times (possible by different addresses; in
  281    the previous example, the node “37” was expended by the
  282    195.37.78.163 and 195.37.79.134 hits).
  283 
  284    For 193.175.132.164 with x= reqs_density_per_unit:
  285      * After first req hits -> the “193” node is built.
  286      * After x more hits, the “175” node is build; the hits of
  287        “193” node are split between itself and its child--both of
  288        them gone have x/2.
  289      * And so on for node “132” and “164”.
  290      * Once “164” build the entire address can be found in the
  291        tree. “164” becomes a leaf. After it will be hit as a leaf
  292        for x times, it will become “RED” (further request from
  293        this address will be blocked).
  294 
  295    So, to build and block this address were needed 3*x hits. Now,
  296    if reqs start coming from 193.175.132.142, the first 3 bytes
  297    are already in the tree (they are shared with the previous
  298    address), so I will need only x hits (to build node “142” and
  299    to make it “RED”) to make this address also to be blocked. This
  300    is the reason for the variable number of hits necessary to
  301    block an IP.
  302 
  303    The maximum number of hits to turn an address red are (n is the
  304    address's number of bytes):
  305 
  306    1 (first byte) + x (second byte) + (x / 2) * (n - 2) (for the
  307    rest of the bytes) + (n - 1) (to turn the node to red).
  308 
  309    So, for IPv4 (n = 4) will be 3x and for IPv6 (n = 16) will be
  310    9x. The minimum number of hits to turn an address red is x.
  311 
  312 Chapter 3. Contributors
  313 
  314 3.1. By Commit Statistics
  315 
  316    Table 3.1. Top contributors by DevScore^(1), authored
  317    commits^(2) and lines added/removed^(3)
  318      Name DevScore Commits Lines ++ Lines --
  319    1. Bogdan-Andrei Iancu (@bogdan-iancu) 137 56 4151 2665
  320    2. Andrei Pelinescu-Onciul 16 8 120 336
  321    3. Razvan Crainea (@razvancrainea) 13 11 94 18
  322    4. Daniel-Constantin Mierla (@miconda) 11 9 24 20
  323    5. Liviu Chircu (@liviuchircu) 11 8 28 66
  324    6. Jan Janak (@janakj) 9 4 386 34
  325    7. Vlad Patrascu (@rvlad-patrascu) 8 6 73 52
  326    8. Jiri Kuthan (@jiriatipteldotorg) 6 3 257 0
  327    9. Jarrod Baumann (@jarrodb) 5 3 111 22
  328    10. Henning Westerholt (@henningw) 4 2 2 2
  329 
  330    All remaining contributors: Elena-Ramona Modroiu, Ancuta
  331    Onofrei, Konstantin Bokarius, Julián Moreno Patiño, Jesus
  332    Rodrigues, Norman Brandinger (@NormB), Peter Lemenkov
  333    (@lemenkov), Edson Gellert Schubert.
  334 
  335    (1) DevScore = author_commits + author_lines_added /
  336    (project_lines_added / project_commits) + author_lines_deleted
  337    / (project_lines_deleted / project_commits)
  338 
  339    (2) including any documentation-related commits, excluding
  340    merge commits. Regarding imported patches/code, we do our best
  341    to count the work on behalf of the proper owner, as per the
  342    "fix_authors" and "mod_renames" arrays in
  343    opensips/doc/build-contrib.sh. If you identify any
  344    patches/commits which do not get properly attributed to you,
  345    please submit a pull request which extends "fix_authors" and/or
  346    "mod_renames".
  347 
  348    (3) ignoring whitespace edits, renamed files and auto-generated
  349    files
  350 
  351 3.2. By Commit Activity
  352 
  353    Table 3.2. Most recently active contributors^(1) to this module
  354                       Name                   Commit Activity
  355    1.  Razvan Crainea (@razvancrainea)     May 2011 - Sep 2019
  356    2.  Bogdan-Andrei Iancu (@bogdan-iancu) Jun 2002 - Apr 2019
  357    3.  Vlad Patrascu (@rvlad-patrascu)     May 2017 - Apr 2019
  358    4.  Peter Lemenkov (@lemenkov)          Jun 2018 - Jun 2018
  359    5.  Liviu Chircu (@liviuchircu)         Mar 2014 - Jun 2018
  360    6.  Julián Moreno Patiño                Feb 2016 - Feb 2016
  361    7.  Jarrod Baumann (@jarrodb)           Apr 2015 - Apr 2015
  362    8.  Norman Brandinger (@NormB)          Aug 2013 - Aug 2013
  363    9.  Daniel-Constantin Mierla (@miconda) Nov 2006 - Mar 2008
  364    10. Konstantin Bokarius                 Mar 2008 - Mar 2008
  365 
  366    All remaining contributors: Edson Gellert Schubert, Henning
  367    Westerholt (@henningw), Jesus Rodrigues, Ancuta Onofrei,
  368    Elena-Ramona Modroiu, Andrei Pelinescu-Onciul, Jan Janak
  369    (@janakj), Jiri Kuthan (@jiriatipteldotorg).
  370 
  371    (1) including any documentation-related commits, excluding
  372    merge commits
  373 
  374 Chapter 4. Documentation
  375 
  376 4.1. Contributors
  377 
  378    Last edited by: Razvan Crainea (@razvancrainea), Peter Lemenkov
  379    (@lemenkov), Liviu Chircu (@liviuchircu), Vlad Patrascu
  380    (@rvlad-patrascu), Julián Moreno Patiño, Jarrod Baumann
  381    (@jarrodb), Norman Brandinger (@NormB), Bogdan-Andrei Iancu
  382    (@bogdan-iancu), Daniel-Constantin Mierla (@miconda),
  383    Konstantin Bokarius, Edson Gellert Schubert, Jesus Rodrigues,
  384    Elena-Ramona Modroiu, Jan Janak (@janakj).
  385 
  386    Documentation Copyrights:
  387 
  388    Copyright © 2005-2009 Voice Sistem SRL
  389 
  390    Copyright © 2003 FhG FOKUS