Trying to wrap my head around FreeRadius config

[Phil Mayers]

On 07/19/2011 05:20 AM, Moe, John wrote:

> 1) When a RADIUS request gets received by the server, it first looks up
> the device in the clients.conf file.  If it doesn't exist there, it
> ignores the request (with a message being logged saying it ignored the
> request).

More or less.

The full version goes as follows:

  1. Packet is received on a socket
  2. FreeRADIUS looks up the "clients" for the corresponding "listen { 
}" section, or the corresponding virtual server, or the global clients 
if both those unset
  3. It gets the shared secret for the client
  4. If present, it verifies the Message-Authenticator, dropping the 
packet if invalid

>
> 2) If it has the client listed in clients.conf, it then runs the request
> through the sites-enabled/default file.  That file seems to say,
> starting with the authorize section, run it through the preprocess
> module, then chap, mschap, suffix, eap, unix, files, expiration,
> logintime and finally, pap.

Again, more or less.

It actually runs the request through whatever virtual server is 
specified in the clients or listen block, or "default" if unset.

And yes, it processes through the modules one at a time. See 
doc/configurable_failover for more info.

>
> This is where things start to get a bit blurry for me.  I understand
> that the preprocess module is rlm_preprocess, and that the config lives
> in modules/preprocess, where I can read a description of that module and
> what it does.  Likewise for chap and mschap.  However, suffix doesn't
> appear to be a module; where'd this come from, and what does it do?

"suffix" is a named instance of the "realm" module; see modules/realm. 
Basically, you can have >1 instance of a module with different config e.g.

realm suffix {
  ...
}


In 2.x, the "unlang" feature of the server also allows you to write 
"conditional" statements that internally are just modules in the 
processing list, like so:

if (User-Name == foo) {
   sql2
}
# note "else" must be on it's own line
# because it's a module, see - line-based
else {
   sql1
}

...which is a series of 2 modules - an "if" module, an "else" module 
(that only runs when the "if" doesn't) and their child module(s).

It's all just modules though; all the way down.

> There also appear to be some modules in /usr/lib64/rlm_* that appear to
> have neither a man page, nor a config file in the modules directory, nor
> any sort of description in the Configuration Files section of the Wiki
> page.

Possibly. Which ones, specifically?

>
> 3) The chap, mschap and eap modules seem to all look at the request and
> decide if the request is using any of these.  If so, they add "Auth-Type
> :=<one of them>" to the config item list.  The eap module isn't

Correct

> configured under the modules directory, but in the root directory in
> eap.conf, the others in their respective file in the modules directory.

Yes, that's historical. In the 3.x versions of the server, the default 
"eap" module config lives in modules/eap.

>
> 4) Given the information in the config items, it tries match the request
> against the unix and files modules, and add/modify config items
> appropriately.  The "files" module is configured by default to read in
> the entries from the users file, where I should add "DEFAULT" entries to
> match the various types of authentication and authorization I'm trying
> to configure.  In there, if it matches against any ruleset, it adds the
> reply items to the request.

Sort of. Your terminology is a bit confusing.

*All* modules work by matching & modifying 3 lists of variables:

  1. request - came from the client
  2. config - internal to the server
  3. reply - sent back to the client

Ignoring the "unix" module (which isn't generally that useful) the 
"files" module basically does this:

  1. Expands the "key" variable (defaults to "%{User-Name}")
  2. Walk through the entries in the file as follows:
     * If key matches or key==DEFAULT, process entry
       If Fall-Through = yes, proceed to next entry

The entry process basically works as follows:

  * All compare/set operations are on the 1st line
  * Compare operations are made against request variables
  * Set operations are made against check/control variables

e.g. in the "users" file, this:

DEFAULT	Foo == "bar", Baz := "ban"

...means: compare Foo in the request against "bar"; if it matches set 
"Baz" in the control items to "ban"


>
> 5) It then runs the config items against the expiration and logintime
> modules, which checks the Expiration attribute and some Time attributes
> for authorization limitations.

What is "It" in this sentence?

The modules themselves do the comparison.

>
> 6) It finally runs it through the PAP module to see if it's a PAP
> request, and adds "Auth-Type := PAP" to the config items.

Again, the "pap" module does this

>
> Where do the rest of the attributes that get sent with the packet get
> added to the config item list?  Does that happen first?  Does that
> happen later?  Or is the incoming request with all its attributes
> immediately turned into a list of config items?  None of the modules
> listed seem to say they parse the request and add the request's
> attributes to the config items.

They don't. That doesn't happen.

Each radius request has 3 lists:

  1. Request - populated initially with the AVPs from the packet
  2. Config/control - initially empty
  3. Reply - initially empty

The request variables don't get copied to config/control; that wouldn't 
make sense. They're control variables after all.

Modules are expected to populate the "control" list. The core "control" 
attributes that matter are:

  1. Cleartext-Password - expected to be set in the "authorize" section 
by one of the "database" or "lookup" modules (e.g. SQL, LDAP). Used 
later to in the "authenticate" section by "pap", "mschap" etc.

  2. XXX-Password - same as above, but various types of password hash 
that are compatible with the authentication module; e.g. NT-Password for 
"mschap", Crypt-Password for PAP

  3. Auth-Type - set by the relevant module to "itself" in "authorize"; 
used to "re-run" the module in "authenticate" after the various database 
modules have had a chance to add XX-Password

  4. Proxy-To-Realm - set by the "realm" module, or manually. Used to 
proxy the request. Stops "authenticate" being run.

There are various others, but those are the main ones.

>
> After all this, it then runs through the authenticate section of the
> sites-enable/default file, where it does the user/password checking:
>
> 1) It checks to see if the Auth-Type is PAP, CHAP, or MS-CHAP, and then
> runs them through the appropriate module.
>
> 2) It runs the request through the unix module
>
> 3) It runs it through the eap module (again, configured in eap.conf)

Yeah, that's all a bit confusing and historical. Basically the 
"authenticate" section just works; don't worry about it too much. 
Provided you don't fiddle with Auth-Type, the right module will be run.

>
> At some point, (I believe in both the authorize and authentication
> sections, in the eap module), if it finds that a request is using PEAP,
> it does much the same thing again, but runs the inner
> "data/packet/encryption/not sure what to call it here" through the
> sites-enabled/inner-tunnel file, with sections set up similarly to the
> sites-enabled/default file.

Not quite. EAP is a multi-packet challenge/response mechanism; PEAP in 
particular basically tunnels TLS over radius, then the "inner" auth over 
TLS. So the packet flow is as follows:

  1. Access-Request from client with TLS inside EAP-Message
  2. Access-Challenge from server with TLS
  3. Repeat 1/2 several times until TLS is setup
  4. Access-Request from client with TLS payload inside EAP-Message
     a. payload decrypted and turned into a fake radius packet
     b. fake packet sent to "inner-tunnel" virtual server
     c. reply comes back - maybe Access-Challenge or Access-Accept
     d. reply turned back into TLS payload
  5. Access-Challenge from server with TLS payload
  6. Repeat 4/5 until inner-tunnel succeeds with Access-Accept
  7. Access-Request from client with TLS "PEAP success" payload
  8. Access-Accept from server

...all the numbered steps run in the "outer" server. All the lettered 
steps run in the "inner" server.

For extra fun, steps 4/5 in the outer server make the "eap" module 
return "ok" in the "authorize" section, which allows you to stop 
processing the rest of the "authorize" section, because you know you 
don't need to - it'll all happen in the inner-tunnel.


>
> Then there are the session and post-auth sections, that I haven't even

post-auth is run for the final Access-Accept or Access-Reject. It allows 
you to do things which only need to be done on the final packet. For 
example, really post-auth is where the vlan assignment lookup should be 
run - though a lot of people do it in "authorize" for various reasons, 
this can lead to >1 "database" lookup for multi-pass radius exchanges 
e.g. EAP.

session is for Simultaneous-Use; I've never used it, so never bothered 
to figure out how it works.


Really something like the above info should live in the wiki. The 
request processing pipeline is a common question.