doc/readme.crules

   1 SmartRoute
   2 Rule based connects
   3 Draft 4 - Aug 19, 1994
   4 by Tony Vencill
   5
   6 Rule based connects allow an admin to specify under what conditions
   7 a connect should not be allowed.  If no rules are specified for a
   8 given C and/or N line it will be allowed under any condition.
   9
  10 A rule may consist of any legal combination of the following functions
  11 and operators.
  12
  13 Functions
  14 ---------
  15 connected(targetmask)     - true if a server other than that processing
  16                             the rule is connected that matches the
  17                             target mask
  18 directcon(targetmask)     - true if a server other than that processing
  19                             the rule is directly connected that matches
  20                             the target mask
  21 via(viamask, targetmask)  - true if a server other than that processing
  22                             the rule matches the target mask and is
  23                             connected via a directly connected server
  24                             that matches the via mask
  25 directop()                - true if an oper is directly connected
  26
  27 Unary operators
  28 ---------------
  29 !    eg: !argument        - true if the argument is false
  30
  31 Binary operartors
  32 -----------------
  33 &&   eg: arg1&&arg2       - true if arg1 and arg2 are both true
  34 ||   eg: arg1||arg2       - true if arg1, arg2, or both are true
  35
  36 Parenthesis () are allowed for grouping arguments, but if no parenthesis
  37 are included, && will take precedence over ||, ! will take precedence
  38 over both && and ||, and the function will be evaluated from left to
  39 right.  White space in a rule is ignored.  Invalid characters in a rule
  40 will lead to the rule being ignored.
  41
  42 Examples
  43 --------
  44
  45 A simple example of a connect rule might be:
  46
  47 connected(*eu.under*)
  48
  49 This might be used in a US undernet server for a Europe CN pair to
  50 insure that a second Europe link is not allowed if one US-EU link
  51 already exists.  Note that on the undernet, US server names are
  52 city.state.us.undernet.org and Europe server names are
  53 city.country.eu.undernet.org.
  54
  55 A more interesting example might be:
  56
  57 connected(*eu.under*) &&
  58   ( !direct(*eu.under*) || via(manhat*, *eu.under*) )
  59
  60 Imagine the Boston undernet server uses this rule on its Europe CN
  61 pairs.  This says that if a Europe server is already connected, a
  62 Boston-Europe connect will not be allowed.  It also says that if a
  63 Europe server does already exist and Boston is not directly connected
  64 to one or more Europe servers or Manhattan is, the Boston-Europe
  65 connect will not be allowed.  This has the effect of allowing multiple
  66 US-EU links but attempting to limit these links to one server (ie:
  67 Boston will not initiate its first Europe link if another server is
  68 already linking Europe).  This rule will also prefer to let Manhattan
  69 handle the US-EU link by disallowing Boston-Europe links if a Europe
  70 server is already linked to Manhattan.
  71
  72 A example of the remaining function, directop(), is:
  73
  74 connected(*eu.under*) || directop()
  75
  76 If this line is used on Boston for the Paderborn CN pair, it will allow
  77 connects to Paderborn only if another Europe server is not already
  78 connected and there is not an oper on Boston.  If this rule is
  79 overrideable (ie: is applied only to autoconnects as described below),
  80 then it will disallow Boston autoconnects to Paderborn while a Boston
  81 oper is online, but allow oper-initiated connects to Paderborn under any
  82 circumstance.  This directop() function could be used to invoke less
  83 prefered routes only when an oper is not present to handle routing, or
  84 conversly to allow use of less preferable routes only when an oper is
  85 present to monitor their performance.
  86
  87 ircd.conf entries
  88 -----------------
  89
  90 A rule is listed in the ircd.conf file using a D or d line (which can
  91 be thought of as a "disallow" line).  D lines will apply to all oper
  92 and server originated connects, while d lines will apply only to
  93 autoconnects (ie: they are overrideable by opers).  The formats are:
  94
  95 D:targetmask::rule
  96 d:targetmask::rule
  97
  98 Remember that newlines are not allowed in conf lines.  Two examples
  99 (from above) are:
 100
 101 D:*eu.under*::connected(*eu.under*)
 102 d:*eu.under*::connected(*eu.under*) || directop()
 103
 104 Connects originating from other servers will be checked against and
 105 matching D lines, while matching d lines will be ignored as it will not
 106 be clear whether or not the connection attempt is oper initiated.
 107
 108 Checking and viewing rules
 109 --------------------------
 110
 111 The chkconf program that comes with the servers has been modified to
 112 also check your connect rules.  If running in debug mode, parsing errors
 113 will show up at debug level 8.  To view rules online, "/stats d" can be
 114 used to see all rules and "/stats D" can be used to view those rules
 115 which affect oper initiated connects and accepts.
 116
 117 Processing and storage
 118 ----------------------
 119
 120 The rules are parsed when the conf file is read and transformed into a
 121 more efficiently computed form, then all applicable rules are
 122 evaluated each time a connect command is given or an autoconnect is
 123 due.  If more than one applicable rule is given, only one need
 124 evaluate to true for the connect to be allowed (ie: the rules are ored
 125 together).  Note that conditions that exist when the connect is
 126 initiated might differ from conditions when the link is established.