Changeset 3dbe8f20


Ignore:
Timestamp:
Mar 28, 2019 7:47:08 PM (17 months ago)
Author:
zab2 <zab2@…>
Branches:
master
Children:
3f990b0
Parents:
d90fc42
Message:

document format

File:
1 edited

Legend:

Unmodified
Added
Removed
  • apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/DefinitionParser.java

    rd90fc42 r3dbe8f20  
    1818     * Processes an array of String objects containing the human-readable definition of
    1919     * the filter.
    20      *
    21      * TODO: format
     20     *
     21     * The definition of a filter is a list of Strings.  Each line can represent one of
     22     * these items:
     23     *
     24     * * definition of a default threshold to apply to any remote destinations not
     25     *   listed in this file or any of the referenced files
     26     * * definition of a threshold to apply to a specific remote destination
     27     * * definition of a threshold to apply to remote destinations listed in a file
     28     * * definition of a threshold that if breached will cause the offending remote
     29     *   destination to be recorded in a specified file
     30     *
     31     * The order of the definitions matters.  The first threshold for a given destination
     32     * (whether explicit or listed in a file) overrides any future thresholds for the
     33     * same destination, whether explicit or listed in a file.
     34     *
     35     * Thresholds:
     36     *
     37     * A threshold is defined by the number of connection attempts a remote destination is
     38     * permitted to perform over a specified number of minutes before a "breach" occurs.
     39     * For example the following threshold definition "15/5" means that the same remote
     40     * destination is allowed to make 14 connection attempts over a 5 minute period,  If
     41     * it makes one more attempt within the same period, the threshold will be breached.
     42     *
     43     * The threshold format can be one of the following:
     44     *
     45     * * Numeric definition of number of connections over number minutes - "15/5",
     46     *   "30/60", and so on.  Note that if the number of connections is 1 (as for
     47     *   example in "1/1") the first connection attempt will result in a breach.
     48     * * The word "allow".  This threshold is never breached, i.e. infinite number of
     49     *   connection attempts is permitted.
     50     * * The word "deny".  This threshold is always breached, i.e. no connection attempts
     51     *   will be allowed.
     52     *
     53     * Default threshold
     54     *
     55     * The default threshold applies to any remote destinations that are not explicitly
     56     * listed in the definition or in any of the referenced files.  To set a default
     57     * threshold use the keyword "default".  The following are examples of default thresholds:
     58     *
     59     * -----------------------------
     60     * default 15/5
     61     * default allow
     62     * default deny
     63     * -----------------------------
     64     *
     65     * Explicit thresholds
     66     *
     67     * Explicit thresholds are applied to a remote destination listed in the definition itself.
     68     * Examples:
     69     *
     70     * -----------------------------
     71     * 15/5 explicit asdfasdfasdf.b32.i2p
     72     * allow explicit fdsafdsafdsa.b32.i2p
     73     * deny explicit qwerqwerqwer.b32.i2p
     74     * -----------------------------
     75     *
     76     * Thresholds for destinations listed in a file
     77     *
     78     * For convenience it is possible to maintain a list of destinations in a file and define
     79     * a threshold for all of them in bulk.  Examples:
     80     *
     81     * -----------------------------
     82     * 15/5 file /path/throttled_destinations.txt
     83     * deny file /path/forbidden_destinations.txt
     84     * allow file /path/unlimited_destinations.txt
     85     * -----------------------------
     86     *
     87     * Recorders
     88     *
     89     * Recorders keep track of connection attempts made by a remote destination, and if that
     90     * breaches a certain threshold, that destination gets recorded in a given file.  Examples:
     91     *
     92     * -----------------------------
     93     * recorder 30/5 /path/aggressive.txt
     94     * recorder 60/5 /path/very_aggressive.txt
     95     * -----------------------------
     96     *
     97     * It is possible to use a recorder to record aggressive destinations to a given file,
     98     * and then use that same file to throttle them.  For example, the following snippet will
     99     * define a filter that initially allows all connection attempts, but if any single
     100     * destination exceeds 30 attempts per 5 minutes it gets throttled down to 15 attempts per
     101     * 5 minutes:
     102     *
     103     * -----------------------------
     104     * # by default there are no limits
     105     * default allow
     106     * # but record overly aggressive destinations
     107     * recorder 30/5 /path/throttled.txt
     108     * # and any that end up in that file will get throttled in the future
     109     * 15/5 file /path/throttled.txt
     110     * -----------------------------
     111     *
     112     * It is possible to use a recorder in one tunnel that writes to a file that throttles
     113     * another tunnel.  It is possible to reuse the same file with destinations in multiple
     114     * tunnels.  And of course, it is possible to edit these files by hand.
     115     *
     116     * Here is an example filter definition that applies some throttling by default, no throttling
     117     * for destinations in the file "friends.txt", forbids any connections from destinations
     118     * in the file "enemies.txt" and records any aggressive behavior in a file called
     119     * "suspicious.txt":
     120     *
     121     * -----------------------------
     122     * default 15/5
     123     * allow file /path/friends.txt
     124     * deny file /path/enemies.txt
     125     * recorder 60/5 /path/suspicious.txt
     126     * -----------------------------
    22127     *
    23128     * @return a FilterDefinition POJO representation for internal use
Note: See TracChangeset for help on using the changeset viewer.