documentation and project organization (Was: Using LDAP with EAP-TLS)

[John Dennis]

On 05/16/2011 10:13 AM, Alexandros Gougousoudis wrote:
> Phil, I also understand a lot of things and I can read, but the
> documentation of FR is not ideal. I've googled around, looked examples
> and had more questions than before. Where are all these features
> documented, like the "if then"-things in the conf, all the keywords like
> "ok=return" and so on, what's the difference between Autz-Type and
> Auth-Type? The only thing to get help is here on the list, on the net
> you find a lot infos to FR 1.1 and 2 (one is deployinradius and one the
> FR site) sites containing a little bit information, no much more than
> the conf-files coming with the FR-archive. I'am not complaining, because
> it's an open source project, but you should note that it's sometimes not
> the lack of understanding than the lack of well documented features. And
> if I can't find the infos I need in the docs, I start to try things out.

+1

I have to agree, the lack of comprehensive documentation, including an 
overview of concepts and the flow of operations is the greatest 
impediment to the success of FreeRADIUS as an open source project. The 
power and flexibility of FreeRADIUS is awesome, Alan and the other 
developers have done a wonderful job of providing the open source 
community with a fantastic piece of critical software. They have 
excelled at constant innovation and timely bug fixes. The response on 
the mailing is exceptional.

But all these positive attributes are sometimes negated by the 
difficulty of understanding the system. Many justifiably feel 
configuring FreeRADIUS is a black art. It's often been pointed out that 
config files, doc directory and the wiki contains all you need to know. 
There is a modicum of truth in that. But the reality is it's very 
difficult to locate, extract, interpret and interpolate the missing 
pieces to form a functioning mental model in order to accomplish a 
specific deployment task.

I've worked with FreeRADIUS for a while now and I'm still confounded 
things I don't know, incorrect expectations of behavior (e.g. != does 
not work for group testing). There are things which as far as I can tell 
are simply not documented. Just last week I had to help someone who was 
frustrated by the inability to add attributes to successfully proxied 
Auth-Accept's using a users file. By reading the source I found the 
postproxy_users_file config, as far as I could tell this is completely 
undocumented. When it comes to supporting users "Use the source Luke" 
isn't viable.

I'd like to suggest the next most import task item for the team is not 
the 3.0 release, it's not any change to the code base. Rather the single 
most import task is producing comprehensive documentation collected in a 
single location augmented with cookbook examples of how to solve common 
deployment problems.

I'll wager the time spent on this list answering questions will greatly 
diminish thus providing free time for feature enhancements and bug 
fixes. I'm also concerned at the obvious frustration expressed countless 
times on this list were folks have spent days, weeks, or in some cases 
months beating their heads against the wall in frustration. There will 
be a tipping point at some point in the future where that frustration 
will doom the project as it gets replaced by an alternative or forked. 
I've been in open source long enough to have seen this scenario play out 
multiple times.

Just my 2 cents, worth what you paid for it :-) I'll now return you to 
your regular scheduled programming :-)

And in case you missed it above, Alan and everyone else have done a 
wonderful job and provided a fantastic service to the community. All I'm 
suggesting here is the task priorities need to be tweaked a bit.

P.S.:

One thing which has been lacking in the project is public list of the 
project team. One might make the assumption Alan is the sole 
contributor, if so then that's truly amazing. But I'm going to guess 
others are involved. We would like to thank them as well and perhaps 
have some more insight into the project's organization. At best all I've 
been able to do in intuit based on reading this list and the dev list 
over an extended period that some list participants seem to have such an 
extensive knowledge it suggests to me they must be on the development 
team, either that or just like myself they've spent a lot of time 
reading the source code out of necessity. Questions like, what is the 
project's timeline, what is upcoming in new releases, what is the 
anticipated release schedule, how is the project organized, who are 
significant players and what are their roles are information unusually 
published by open source projects but have been missing (maybe just 
another example of missing documentation?).

-- 
John Dennis <jdennis at redhat.com>

Looking to carve out IT costs?
www.redhat.com/carveoutcosts/