Why documentation is the way it is

[Alan DeKok]

Jan-Frode Myklebust wrote:
> I agree that freeradius definitely doesn't pass the grandma test.

  For some things.  For basic authentication?  Add a "client"
definition, add a user / password in the "users" file, and about 15
authentication methods will Just Work.  The rest of this rant isn't
directed at you... it's just an explanation as to WHY things are they
way they are.


  For more complex authentication, see my web page,
http://deployingradius.com/.  The only complaints I've gotten in 10
years have been people pointing out typos or spelling mistakes.

  Are there basic howtos on SQL, LDAP, etc.?  No.  Why?  No one has
submitted them.  In 15 years of people complaining about the "bad
documentation", not one single complainer has ever said:

  "You know, I don't want anyone else to go through the same pain I did.
 So to help people like me, I'm going to write a quick howto, and put it
on the Wiki".

  No.  Every single complainer cares only about their problems, and
cares nothing for anyone else.  They complain that other people have to
do MORE work for them, for free.  They refuse to contribute anything
themselves.  It's pretty obvious after 15 years, the more someone
complains, the less they follow instructions, and the less they get done.

  The people who DO get work done fit another personality type.  They
just get things done.  They submit patches, documentation fixes, etc.,
and generally have empathy for other people.

> 113 files in /etc/raddb seems a but much,

  It's called "documentation".  The modules don't have module-specific
documentation, like http://wiki.nginx.org/Modules.  Instead, we supply
*working* configurations as examples.

  I can't tell you how many times I've installed a piece of software
with great documentation, and no examples.  When I try to create a
working configuration from the documentation, it often doesn't work.
Why?  It's impossible to find out.

  The "sites-available" directory is full of working examples for many
different scenarios.  The comments in each file describe what the
problem is, and how the file creates the solution.  It describes how to
change the example to suit your local configuration.

  Again, in about 5 years of having those examples, the only complaints
have been about typos.

  So there *is* a lot of FreeRADIUS documentation.  It's just not
organized into web pages.

> so I've been struggeling for a very
> long time trying to understand which files needs changes to achive what.
> But I guess this also is part of the power of freeradius. A lot of stuff
> is implemented, and is tweakable in the modules/ and sites-*/ files.

  Exactly.  FreeRADIUS ships with more examples, and more working
protocols than any comparable server: DNS, DHCP, HTTP, FTP, etc.

> I'm getting ready to dig into "unlang" myself to try to define a access
> regime of groups of NAS'es and groups of people. It looks like it should
> be able to do just about anything.

  Exactly.  FreeRADIUS can do just about anything.  But for anything
past the basic && common configuration... you've got to put the pieces
together yourself.

  The reason is that people want a RADIUS server to do MUCH more than a
typical DNS or DHCP server.  So configuring DNS or DHCP is trivial.
Edit one text file, and you're done.  Configuring a RADIUS server means
juggling database configurations, schemas, policies, etc.

  Doing that requires a certain level of competence, and more
importantly, a methodical approach.  Some people just can't do that.

  Alan DeKok.