Adding run-time-access (RTA) to FreeRadius

[Bob Smith]

Awhile ago the FreeRADIUS mailing list had a thread on how to remove
the practical necessity of SIGHUP to load a new configuration.  I am
the author of the Run-Time-Access (RTA) library, the "crazy SQL scheme"
that Alan mentioned in the thread.  I caught part of the thread and asked
Alan if he'd like me to add RTA to part of FreeRADIUS, in particular, to
the RADCLIENT list.  This rather long email is a report to Alan and to
the other FreeRADIUS developers on that effort.  This report has a little
bit of background on RTA, an executive summary, answers to questions in
the thread, some comments on what would be required, and finally, links
to a working demo.


RTA BACKGROUND
In 1993 I helped found a company now called Venturi Wireless.  We made
a compression server for sale to the cellular wireless carriers.  In
order to avoid the then near religious wars between Solaris and Windows
NT we chose to build a compression "appliance" (based on Linux).  Our
first user interface used HTML directly in the compression server (like
CUPS does/did).  This web interface was little more than a editor on
top of a config file and we restarted the server when a use hit the
Commit button.  Customers demanded an SNMP interface, so we added that
directly into the server too.  Then they wanted a command line interface
and we knew we were in trouble.  The backdrop to this was the constant
complaints about restarting the server for even relatively minor
configuration changes.  We eventually decided to break all user interfaces
away from the server and use a common protocol that would let many UIs
talk to the server while it was running and able to do on-the-fly config
changes, and get lots of status and statistics from from the server in
real-time.  We considered the Hayes AT command set but we settled on a
text-based, SQL type interface over TCP.  The Venturi Wireless solution
worked but had many shortcomings and after I left the company I wrote RTA
to overcome those shortcoming.   If multiple, run-time interfaces for
configuration, status, and statistics are of value to you, then read on.
If you think the users of FreeRADIUS are going to remain happy with root
access, 'vi' and 'SIGHUP', then you can skip to the next message in your
InBox.


EXECUTIVE SUMMARY
I believe it will be straightforward but somewhat tedious to add RTA to
the FreeRADIUS server.  There are two issues to be resolve up front -
updates to the data in FreeRADIUS are not thread safe, and if you have
UI driven configuration changes, you can not keep the human readable file
formats now in use.  Please note that neither of these issue are tied to
the API used to access the configuration; they are tied to FreeRADIUS
itself and updating its configuration while FreeRADIUS continues to run.


FREQUENTLY ASKED QUESTIONS (from the "HUP handling: a thought" thread)
You might like http://linuxfocus.org/English/May2004/article338.shtml as
a quick introduction to RTA.  Scanning it may answer more questions than
are covered below.
1) Does the replace SIGHUP ?
It does not need to but, yes, it can.  That is, you can still restart on
SIGHUP but shouldn't ever _need_ to use SIGHUP.
2) Would root access and 'vi' still be required?
The hope is that FreeRADIUS would become an appliance without ever requiring
root access or vi after the initial installation.  To do this, every config
parameter in FreeRADIUS would have to be mapped to an RTA accessible table.
(straightforward but tedious)
3) Use Webmin for the web interface!
You can do this but under the covers you're still editing the config files
and sending a SIGHUP.  Webmin, as good as it is, does nothing to solve the
SNMP and CLI problems.
4) RTA is not thread safe!
While true, I don't think this is the issue.  RTA is an API for other programs
to access your data.  Would you ask that the Hayes AT command set be thread
safe? Of course not.  I think the real issue is that FreeRADIUS is not thread
safe for configuration updates.  This is why you have to let all the threads
die before doing the restart on SIGHUP.  The FreeRADIUS databases themselves
are not thread save to asynchronous updates.  I do not have a good answer for
this.  SQLite is thread-safe but, like all ACID databases, is not at all "lite".
You could remove thread support but that would cause no end of developer turmoil.
(For what it's worth, I'll be happy to make RTA thread safe if it helps.)
5) Does RTA support transactions?
No.  Again compare it to an AT command set used to manage a modem. It is only
an API.  It _is_ atomic at the row. level.  That is, updates to rows fail or
succeed on the whole row, and failed updates return the row it its original
state.
6) RTA has too many dependencies!
Actually RTA only requires libc (if I recall correctly).  Your user interface
programs will require the PostgreSQL client library.  BTW: using PostgreSQL
means your UIs can be written in C, C++, PHP, Java, Perl, Ruby...on and on....
7) We've put too much effort into our config file syntax to give them up.
This is not really an RTA issue; it is an issue for any scheme to allow dynamic
configuration updates.  Yes, you _could_ have the server try to write the config
back to disk int the same human-readable format, but you'd be crazy to try.  The
simple truth is that if you're going to have dynamic configuration updates, then
you're eventually going to have to give up the human-readable config files.
(BTW: Yes, RTA saves its configuration tables as a series of (human readable, vi
editable) SQL statements. This reduces code and bugs since the same parser for
the API is used to parse the config files.  Think of all the config parsing code
you could take out of FreeRADIUS!)
8) SQL is too CPU intensive for use in FreeRADIUS.
We haven't found that to be the case.  For one thing, the SQL parser in RTA is
a lex/yacc state machine, but, more importantly, RTA is only invoked when the
user wants to update a configuration or view some statistic.  Relative to the
overall CPU load, these bursts of user-initiated CPU activity are negligible.
9) RTA is useless without INSERT and DELETE.
This has long been a criticism of RTA.  While there are simple ways around this
most people still expect INSERT and DELETE for tables where the data is stored
as a linked-list or other editable structure.  I've had a difficult time getting
people to see RTA as an API and *not* as a database.  Adding INSERT and DELETE
will make this task all the more difficult.  That said, I've recently been
convinced that adding INSERT and DELETE for tables with dynamically allocated
rows would be a good thing.  Sigh... INSERT and DELETE will be in the next
release of RTA.
10) We can not live with RTA's hard coded limits.
I'm not sure I understand this one entirely.  There is an upper bound on the
number of tables and an upper bound on the number of rows but these are high
enough not to not cause a problem for FreeRADIUS (and they're easy to change).
The rest of the hard coded limits are for things like the string length for the
name of a column or table, things that reasonably should have some limit.  Let
know the specifics and I'll think about how to make them soft limits.
11) My users like 'vi' and copying config files.
This should be the heart of the debate.  If you or your users really want vi
and human readable files then you should forget about RTA, FUSE, or any of the
alternatives.  I can answer questions about RTA but I can not help with this
fundamental question.


ADDING RTA TO FreeRADIUS
   Giving up on human-readable config files, while emotionally difficult, will
happen over time.  The bigger problem is whether to give up on threads or to
make all updates of configuration tables thread safe.
   If you choose to continue looking at RTA, then I'd suggest that you start
with an inventory of all of the configuration data and try to map that data
into tables with columns and row.  BTW: typically an RTA "row" is an instance
of a C data structure, a "table" is an array or linked-list of those structures,
and a "column" corresponds to a single member of the data structure.
   While doing the above inventory be sure add in all the status and statistics
that make sense.  Relatively low CPU-cost access to status and statistics is
one of the best parts of RTA.


A WORKING DEMO
It's not much but I added RTA to FreeRADIUS as far as the RADCLIENT structure
is concerned.  I had to modify radiusd.c to add the RTA library calls and I
modified the RADCLIENT structure to make it easier for you to see the changes.
(In retrospect I probably should not have touched RADCLIENT.)  All of the RTA
code is in use_rta.c.  The files are at:
    http://www.linuxappliancedesign.com/projects/rad/use_rta.c
    http://www.linuxappliancedesign.com/projects/rad/radiusd.c
    http://www.linuxappliancedesign.com/projects/rad/radiusd.h

RTA include a generic table editor.  The table editor is to RTA tables what
vi is to text files -- a simple way to view and change them.  The table editor
is _not_ meant to be the final user interface.  You can view and edit the
RADCLIENT table in the demo server here:
    http://www.linuxappliancedesign.com/projects/rad/rta_apps.html
Be warned that this version of RTA does not have INSERT and DELETE so to add
a new row you have to fill in the single blank row there and to delete a row
you have to clear our the ipaddr column.


I will remain on this mailing list to answer question until the end of the
week.  At the end of the week I'll remove myself from the mailing list and
shut down the demo server.  (If you reply to this email would you mind not
quoting the whole thing?  Instead, please quote just the section relevant
to your comment or questions.)


thanks,
Bob Smith