doc/rlm_attr_filter

   1
   2
   3         Attribute Filtering Module
   4
   5
   6 -1. CAVEAT
   7
   8
   9 RLM_ATTR_FILTER
  10
  11 0.  INTRODUCTION
  12
  13   This module exists for filtering certain attributes and values in received
  14   radius packets from remote proxy servers.  It gives the proxier (us) a very
  15   flexible framework to filter the attributes that proxy servers send us in
  16   their replies.  This makes sense in an out-sourced dialup situation for
  17   example, where the client proxy is permitted only certain values for setting
  18   the Idle-Timeout.
  19
  20   Filter rules are defined and applied on a per-realm basis, where the realm
  21   can be anything you have defined via the rlm_realm module.
  22
  23 1.  MODULE CONFIGURATION
  24
  25   The module configuration section is very simple.  There is only one attribute
  26   that needs to be set, the file to read the filter rules from.
  27
  28   As an example, here is the default configuration from radiusd.conf:
  29
  30        modules {
  31            ...
  32            attr_filter {
  33                 attrsfile = ${confdir}/attrs
  34            }
  35            ...
  36        }
  37
  38   If attrsfile is not specified, it defaults to the above configuration.
  39
  40   This module supports multiple named instances per the normal method.
  41
  42   Once defined in the modules section of the config file, you must add the
  43   module instance name ( the name of the module itself by default ) into the
  44   'authorize{}' section.  It should be placed *before* the realm modules.
  45
  46   As an example:
  47
  48        authorize {
  49            preprocess
  50            attr_filter
  51            realm
  52            files
  53        }
  54
  55   If the incoming packet is not a proxy reply, the module returns a NOOP,
  56   so that the rest of the 'authorize{}' is called normally.
  57
  58 3.  MODULE OPTIONS
  59
  60   The file that defines the attribute filter rules is layed out and parsed
  61   very similar to the users file.  There are a couple main differences:
  62
  63      o  There are no "check items" on the first line of the profile other
  64         than the "realm".
  65
  66      o  There is only one DEFAULT entry.  This is due to the fact that there
  67         are no "check items" beyond the realm name.  Fall-Through does work
  68         though, allowing you to put the commonly allowed attribute rules into
  69         the DEFAULT entry and only put realm specific rules in the specific
  70         realm entry.
  71
  72      o  The operators used for specifying the attributes are as follows:
  73
  74            =    -  NOT ALLOWED.  If used, it becomes "=="
  75
  76            :=   -  Set ( used to ensure a specific a/v is present )
  77            ==   -  Equal  ( exact )
  78            =*   -  Always Equal ( will allow all values for attribute )
  79            !*   -  Always Not Equal ( will block all values for attribute )
  80            !=   -  Not equal
  81            >=   -  Greater than or equal to
  82            <=   -  Less than or equal to
  83            >    -  Greater than
  84            <    -  Less than
  85
  86            If you have regular expressions enabled you also have:
  87
  88            =~   -  Regular expression equal
  89            !~   -  Regular expression not equal
  90
  91
  92   See the comments in the default 'attrs' file for examples and additional
  93   explanation.
  94
  95 4.  MODULE FUNCTION
  96
  97   The way the module works is as follows:
  98
  99      o  Build a list of a/v pair rules from the 'attrs' file at module
 100         instantiation.
 101
 102      o  When a proxy reply packet is received and passed to the module, it
 103         checks for a Realm attribute in the original request a/v pairs.
 104         ( The Realm attribute is added there by the proxy code ).
 105
 106      o  The module walks the list of a/v pair rules until it finds a
 107         match for the Realm value or it reaches the DEFAULT entry.
 108
 109      o  If there are any rules with SET operators, those attributes are
 110         added to the top of a temporary reply list.
 111
 112      o  Each a/v pair in the proxy reply is compared to the list of
 113         rules.
 114
 115      o  If an a/v pair in the proxy reply passes *ALL* of the rules that
 116         relate to the attribute, the a/v is added to a temporary list.
 117         ( Note, if it fails 1 or more rules, or is not matched, then the
 118           a/v pair will *NOT* be transferred to the temporary list. )
 119
 120      o  When all the reply vps have been checked, the original proxy reply
 121         vps are freed and the temporary list ( containing only those a/v
 122         that passed the rules ) becomes the new proxy reply vps.
 123
 124      o  The module then returns UPDATED and the rest of the authorize block
 125         is called as usual.
 126
 127 ---
 128 Please send corrections/input/comments/flames to <cparker@starnetusa.net>
 129