doc/rlm_fastusers

   1
   2 Radius FastUsers Module
   3
   4 0.  INTRODUCTION
   5
   6     The 'fastusers' module provides an interface for authentication
   7     very similar to the standard RADIUS 'users' file.  However, because
   8     the users are stored in a different way, there are three main
   9     differences to be aware of:
  10
  11     a.  It's much faster than standard 'users' authentication
  12     b.  Order of the entries in the file does *not* matter
  13     c.  DEFAULT entries behave differently than in 'users'
  14
  15 1.  WHAT DOES IT DO
  16
  17     Very simply, the module reads in the file you specify in radiusd.conf
  18     into a hash table and then authenticates the users out of it.  This
  19     is very similar to the way that passwd caching works (see README.cache),
  20     but because of the 'users' file format, we can specify arbitrary
  21     check items and reply items for each user.
  22
  23 2.  HOW DO I USE IT
  24
  25     First thing you do is declare the module in radiusd.conf.  The
  26     default setting looks like this:
  27
  28     fastusers {
  29        usersfile = ${confdir}/users_fast
  30        hashsize = 1000
  31        compat = no
  32     }
  33
  34     A.  usersfile
  35
  36         The 'usersfile' is the path and filename of the file you want
  37         fastusers to read and use to authenticate users.  The format
  38         is similar to that of the standard 'users' file, but you must
  39         keep the following differences in mind:
  40
  41         1.  Order does not matter
  42
  43             Order of the standard 'users' file is important, where in
  44             fastusers it is not.  Multiple DEFAULT entries are not
  45             possible (see below), so don't be surprised when things
  46             don't work exactly as they would in 'users'.
  47
  48         2.  DEFAULT entries
  49
  50             While you can have multiple DEFAULT entries in the file
  51             you use with fastusers, only the last one will be used.
  52             Furthermore, the DEFAULT entry has a *very* different
  53             purpose in fastusers than it does in 'users'.
  54
  55             In fastusers, if you add a DEFAULT entry, what you are
  56             telling the server is:  Add the check items and reply
  57             items I list for this DEFAULT entry to *every* request
  58             that matches a user in this file.  Example:
  59
  60             test Auth-Type:=Local, Password=="test"
  61                 Reply-Message = "User test"
  62
  63             test2 Auth-Type:=Local, Password=="test2"
  64                 Reply-Message = "User test2"
  65
  66             DEFAULT Simultaneous-Use == 1
  67                 Service-Type = Framed-User
  68
  69             Normally you would expect that if a user other than 'test'
  70             or 'test2' logged in, the DEFAULT entry would apply.  This
  71             is not the case in fastusers.
  72
  73             NOTE:  No users other than ones listed explicitly in the file
  74                    can authenticate via fastusers because DEFAULT entries
  75                    do not work like they do in the 'users' file.
  76
  77             Now, if either test or test2 logs in with their respec-
  78             tive password, when the request is passed back to the main
  79             server (and to the NAS), the check item Simultaneous-Use==1
  80             and the reply item Service-Type=Framed-User will be added.
  81
  82             Why does it behave this way?  The reason is because if it
  83             does not do this, the administrator will have to duplicate
  84             the check items and reply items for every user in the file
  85             unnecessarily.  This will cause the fastusers file to be
  86             substantially larger than necessary, which in turn takes
  87             the server long to read on startup or when it receives
  88             a -HUP signal.
  89
  90             This way, you need only put the necessary check and reply
  91             items on the DEFAULT entry, and then the individual users
  92             will need only have the items that are *unique* to them
  93             listed explicitly (ie, password, static ip address, etc).
  94
  95             This behaviour will probably be configurable in future
  96             releases of the module.  For now, you don't have to add
  97             a DEFAULT entry if you don't want one, and the attributes
  98             listed for each individual will be the ones used for check
  99             and reply items.
 100
 101             NOTE:  Because the attributes from DEFAULT are added to the
 102                    user authenticating, it is best to *AVOID* listing an
 103                    Auth-Type in the DEFAULT entry.  If you set one in
 104                    the DEFAULT entry, it will override the one you set
 105                    for the user in the file.  Just don't do it, it's not
 106                    worth the confusion.
 107
 108     B.  hashsize
 109
 110         The 'hashsize' variable controls how many 'buckets' or 'nodes'
 111         the hash table will have in it.  This allows the admnistrator
 112         to control how much memory is allocated to the hash table.  It
 113         also allows him/her to significantly impact the performance of
 114         the hash (for better or worse!!).
 115
 116         Each hash 'bucket' is a pointer to a list of users that fit
 117         the requirements to be in that bucket.  If the number of users
 118         is very high and the 'hashsize' is very small, that means you
 119         will have a large number of users per bucket.  This will
 120         *negatively* impact performance.  In an ideal world, you would
 121         have exactly one user per bucket, but this is very unlikely to
 122         happen.  Conversely, if you have only 10 users in listed in the
 123         file and you set 'hashsize' to be 1000, you know that you have
 124         100 times as many buckets as users, and are therefore wasting
 125         memory.
 126
 127         So what should you shoot for?  Well, I'll tell you as a general
 128         rule to simply take the number of users you list in the file
 129         and use that for the 'hashsize' value.  However, the frugal
 130         admin could divide that number by 5 or 10 and still achieve
 131         much greater performance that that produced by 'users'.  Still,
 132         if you aren't strapped for memory, I recommend going no lower
 133         than 'hashsize= # of users / 3'.  It's up to you though, test
 134         it with different values and see how it affects performance
 135         (see README.testing).
 136
 137         NOTE:  If you use value of '1' for hashsize, you will have
 138                effectively created a singly linked list, and thus
 139                removed all performance benefit of using the module.
 140
 141     C.  compat
 142
 143         This works the same as it does in the rlm_users config section.
 144         It allows you to declare cistron compatibility mode when reading
 145         in the 'users' file.
 146
 147     Finally, you must put 'fastusers' in the 'authorize{}' section of your
 148     radiusd.conf.  For example:
 149
 150     authorize {
 151        preprocess
 152        realm
 153        fastusers
 154     }
 155
 156 3.  CAVEATS
 157
 158     *NOTE:  DEFAULT USERS DON'T WORK AS YOU MIGHT EXPECT!  SEE ABOVE!!!
 159
 160 4.  ACKNOWLEDGEMENTS
 161
 162     Author - Jeff Carneal
 163