On 28 Mar 2014, at 17:17, John Dennis <jdennis@redhat.com> wrote:

I think one of the problems with user contributed doc is it ends up being:

"A How-To of how to solve my unique problem exactly the way I did"

Many of the thorny problems that trip up users are directly related to
their unique deployment requirements. One of the great things about
FreeRADIUS is it's enormous flexibility, but that's also it's liability
when it comes to documentation. There are often multiple ways to
accomplish the same thing and the final solution is often dictated by
constraints unique to the deployment or personal taste. Usually these
How-To's do not serve as a good generic guide.

To my mind the fundamental documentation problem is not the lack of
specific documentation detailing the details, there is plenty of that.
What's missing is an overarching explanation of how all the pieces fit
together and/or can be assembled. My general observation is many users
have problems because they do not understand how the server works in
broad terms and how that behaviour can be adjusted to meet certain
deployment requirements.

Until folks have a working mental model of what's going on any
documentation about pulling a specific lever or turning a certain knob
isn't going to help them because they don't understand the "why" behind
the recommendation.

I agree, there needs to be more documentation around fundamental concepts
as opposed to specific scenarios.

The behaviour of the server is actually really simple.

Just an expanded version of http://wiki.freeradius.org/guide/Concepts
with some diagrams would be nice.

so in the interim I've compiled this comprehensive flow chart that should

cover pretty much every scenario.

Arran Cudbard-Bell <a.cudbardb@freeradius.org>
FreeRADIUS Development Team

FD31 3077 42EC 7FCD 32FE 5EE2 56CF 27F9 30A8 CAA2