Handling prefix and suffix realms in the same server

[Alan DeKok]

On Jun 18, 2025, at 9:30 AM, Paul Moser via Freeradius-Users <freeradius-users at lists.freeradius.org> wrote:
> We have tracked down cause of the drop in traffic on our suffix realm to the fact that some of those usernames also have a '/' character in them. Previously when the FreeRadius IPASS realm module parsed those realms, whilst it appeared to find a prefix realm, it found no match in its configuration and so would fall through to letting the suffix module try, which would match and then successfully end up proxying the packet on. With a DEFAULT realm also configured when the IPASS module encounters a suffix realm username that also has a '/' in it then rather than falling through and letting the suffix module handle it it instead matches it against the DEFAULT realm and so ends up sending an Access-Reject back.

  Yes.  The configuration isn't quite intended to have multiple overlapping realms, with multiple DEFAULTs.

> I note that the FreeRadius default config only has the suffix realm configured in the default server - I suspect that maybe the general advice would be only use prefix or suffix realms not both, and if you use both expect such edge-case such issues - would that be a fair opinion?

  That's usually the case.

  But the realm module is mainly there as a short-cut.  You can check / set realms manually via unlang, too.  The only benefit of the realms module is that it checks the User-Name string against the list of defined realms in proxy.conf.

  I suppose we could add an expansion to do that check, and then you could do everything in unlang.

> In the case I have I can resolve it by:
> 
>  *   Either keeping in the realm entries for the realms we are ceasing, but map them to the new virtual server that rejects/logs, and no DEFAULT realm.
>  *   Or remove the mappings for the ceased prefix realms but also instead of adding a DEFAULT realm add a NULL realm that maps to the virtual server that rejects/logs so that the IPASS module won't match, and the suffix module won't match a realm so will return the NULL realm.
> 
> However, I do have another radius server that also handles prefix and suffix realms, already has a DEFAULT and NULL realm configured and I'm now concerned that it may have similar issues that we've not noticed or could in the future as an unintended side effect of another seemingly innocent change we might make.

  The realm module isn't intended to be used with multiple DEFAULTs.  i.e. when you have a prefix realm check, along with "if not found use DEFAULT", then any subsequent suffix realm check is likely to not match.

  You can work around this via unlang, if there is a way to distinguish prefix / suffix realms.  e.g.

	if (User-Name =~ /@/) {
		suffix realm module
	} else {
		prefix realm module
	}

  The problem you're running into is because it's doing checks for *both* types of realms.  If you can change that to running only one "realm" module, then it should be dfine.

> In trying to figure out what was going on I've been through the server logs in debug, through our configuration and even through the rlm_realm.c code. As already mentioned we have ignore_null = true in our IPASS realm configuration, this doesn't seem to be mention in the latest documentation (although Google will throw up an old page that does mentions it), there  use to be a reference to it as a comment  in the default server but that was removed in commit d5d4ba6673cce86ba058583ce7e38fb53a4ddae8 with the commit message "the parameter ignore_null doesn't exist". Looking at the rlm_realm.c C code it is still there, as well as an ignore_default. Have these become undocumented as they are going to be removed, or just because of complexity/complications of using them (and use at your own risk if you fully understand the implications in your context)?

  TBH, I don't recall.

> With v4 on the horizon - I've taken a brief look at it and realm handling is clearly different - do I need to be thinking of getting to a point where a radius server only handles  suffix or prefix realms or will v4 handle this, or does it make it simpler , or does it remain a complex problem (simply because it is a complex problem) to handle both reliably?

  The problem is parsing, not the FreeRADIUS configuration.  If the two types of realm strings are disjoint, then parsing them is easy.  If the two types of realm strings have overlaps, then parsing is harder.  The only way to solve that parsing conflict is to pick one type of realm, and declare that one to be the winner of any parse conflicts.

  For v4, all of the realm configuration has gone away, including the "realms" module.  Rather than having a special thing for realms, there's just a set of better tools to manage strings and database lookups.

  This change means that you can put realm definitions anywhere.  CSV files, redis, LDAP, SQL, etc.  You don't need to put them into a FreeRADIUS-specific "realms" module.

  We're working on much more documentation for v4, including howtos for migrating from v3 to v4.

  Alan DeKok.