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>