doc/rlm_fastusers

   1
   2 Radius FastUsers Module
   3
   4 0.  INTRODUCTION
   5
   6     The 'fastusers' module provides an interface for authentication
   7     exactly like the standard RADIUS 'users' file.  It's function is
   8     is exactly like that of rlm_files in FreeRadius, but it is consid-
   9     ably faster.  So why keep rlm_files around?  Because it's good,
  10     working code, and rlm_fastusers may still have bugs causing it
  11     to behave differently from rlm_files in very exotic cases.
  12
  13 1.  WHAT DOES IT DO
  14
  15     Very simply, the module reads in the file you specify in radiusd.conf
  16     into a hash table and then authenticates the users out of it.  This
  17     is very similar to the way that passwd caching works (see README.cache),
  18     but because of the 'users' file format, we can specify arbitrary
  19     check items and reply items for each user.
  20
  21 2.  HOW DO I USE IT
  22
  23     First thing you do is declare the module in radiusd.conf.  The
  24     default setting looks like this:
  25
  26     fastusers {
  27        usersfile = ${confdir}/users_fast
  28        hashsize = 1000
  29        compat = no
  30        hash_reload = 600
  31     }
  32
  33     See below for a detailed explanation of the module options.
  34
  35     Then you must put 'fastusers' in the 'authorize{}' section of your
  36     radiusd.conf.  For example:
  37
  38     authorize {
  39        preprocess
  40        realm
  41        fastusers
  42     }
  43
  44 3.  MODULE OPTIONS
  45
  46     A.  usersfile
  47
  48         The 'usersfile' is the path and filename of the file you want
  49         fastusers to read and use to authenticate users.  The format
  50         is exactly like that used by rlm_files.
  51
  52     B.  hashsize
  53
  54         The 'hashsize' variable controls how many 'buckets' or 'nodes'
  55         the hash table will have in it.  This allows the admnistrator
  56         to control how much memory is allocated to the hash table.  It
  57         also allows him/her to significantly impact the performance of
  58         the hash (for better or worse!!).
  59
  60         Each hash 'bucket' is a pointer to a list of users that fit
  61         the requirements to be in that bucket.  If the number of users
  62         is very high and the 'hashsize' is very small, that means you
  63         will have a large number of users per bucket.  This will
  64         *negatively* impact performance.  In an ideal world, you would
  65         have exactly one user per bucket, but this is very unlikely to
  66         happen.  Conversely, if you have only 10 users in listed in the
  67         file and you set 'hashsize' to be 1000, you know that you have
  68         100 times as many buckets as users, and are therefore wasting
  69         memory.
  70
  71         So what should you shoot for?  Well, I'll tell you as a general
  72         rule to simply take the number of users you list in the file
  73         and use that for the 'hashsize' value.  However, the frugal
  74         admin could divide that number by 5 or 10 and still achieve
  75         much greater performance that that produced by 'users'.  Still,
  76         if you aren't strapped for memory, I recommend going no lower
  77         than 'hashsize= # of users / 3'.  It's up to you though, test
  78         it with different values and see how it affects performance
  79         (see README.testing).
  80
  81         NOTE:  If you use value of '1' for hashsize, you will have
  82                effectively created a singly linked list, and thus
  83                removed all performance benefit of using the module.
  84
  85     C.  compat
  86
  87         This works the same as it does in the rlm_users config section.
  88         It allows you to declare cistron compatibility mode when reading
  89         in the 'users' file.
  90
  91     D.  hash_reload = 600
  92
  93         Number of seconds between automatic reloading of the users
  94         cache.  Using this option means the module will double memory
  95         usage, but only while the reload is in progress.  However, it
  96         will eliminate blocking of user access during a reload and
  97         allow longer times between server HUPs.
  98
  99         You can disable this feature with hash_reload = 0;
 100
 101 4.  CAVEATS
 102
 103     It probably still has bugs.  Most notably, there is a small memory
 104     leak somewhere in the reloading code.  I suspect it's in pairlist_read
 105     from files.c, but I have no proof yet.
 106
 107 5.  ACKNOWLEDGEMENTS
 108
 109     Author - Jeff Carneal <jeff@apex.net>
 110