
Radius FastUsers Module

0.  INTRODUCTION

    The 'fastusers' module provides an interface for authentication
    exactly like the standard RADIUS 'users' file.  It's function is
    is exactly like that of rlm_files in FreeRadius, but it is consid-
    ably faster.  So why keep rlm_files around?  Because it's good,
    working code, and rlm_fastusers may still have bugs causing it
    to behave differently from rlm_files in very exotic cases. 

1.  WHAT DOES IT DO

    Very simply, the module reads in the file you specify in radiusd.conf
    into a hash table and then authenticates the users out of it.  This
    is very similar to the way that passwd caching works (see README.cache),
    but because of the 'users' file format, we can specify arbitrary
    check items and reply items for each user.
   
2.  HOW DO I USE IT

    First thing you do is declare the module in radiusd.conf.  The
    default setting looks like this:

    fastusers {
       usersfile = ${confdir}/users_fast
       hashsize = 1000
       compat = no
       hash_reload = 600
    }

    See below for a detailed explanation of the module options.
            
    Then you must put 'fastusers' in the 'authorize{}' section of your
    radiusd.conf.  For example:

    authorize {
       preprocess
       realm
       fastusers
    }

3.  MODULE OPTIONS 

    A.  usersfile

        The 'usersfile' is the path and filename of the file you want
        fastusers to read and use to authenticate users.  The format
        is exactly like that used by rlm_files.

    B.  hashsize

        The 'hashsize' variable controls how many 'buckets' or 'nodes'
        the hash table will have in it.  This allows the admnistrator
        to control how much memory is allocated to the hash table.  It
        also allows him/her to significantly impact the performance of
        the hash (for better or worse!!).

        Each hash 'bucket' is a pointer to a list of users that fit 
        the requirements to be in that bucket.  If the number of users
        is very high and the 'hashsize' is very small, that means you
        will have a large number of users per bucket.  This will 
        *negatively* impact performance.  In an ideal world, you would
        have exactly one user per bucket, but this is very unlikely to
        happen.  Conversely, if you have only 10 users in listed in the
        file and you set 'hashsize' to be 1000, you know that you have
        100 times as many buckets as users, and are therefore wasting
        memory.

        So what should you shoot for?  Well, I'll tell you as a general
        rule to simply take the number of users you list in the file 
        and use that for the 'hashsize' value.  However, the frugal 
        admin could divide that number by 5 or 10 and still achieve
        much greater performance that that produced by 'users'.  Still,
        if you aren't strapped for memory, I recommend going no lower
        than 'hashsize= # of users / 3'.  It's up to you though, test
        it with different values and see how it affects performance
        (see README.testing).
        
        NOTE:  If you use value of '1' for hashsize, you will have 
               effectively created a singly linked list, and thus
               removed all performance benefit of using the module.
            
    C.  compat

        This works the same as it does in the rlm_users config section.
        It allows you to declare cistron compatibility mode when reading
        in the 'users' file.

    D.  hash_reload = 600

        Number of seconds between automatic reloading of the users
        cache.  Using this option means the module will double memory
        usage, but only while the reload is in progress.  However, it
        will eliminate blocking of user access during a reload and
        allow longer times between server HUPs.

        You can disable this feature with hash_reload = 0;

4.  CAVEATS

    It probably still has bugs.  Most notably, there is a small memory
    leak somewhere in the reloading code.  I suspect it's in pairlist_read
    from files.c, but I have no proof yet.  

5.  ACKNOWLEDGEMENTS

    Author - Jeff Carneal <jeff@apex.net>

