rlm_realm

Synopsis

The realm module splits a User-Name attribute into "user" and "realm" portions. If the realm is found, the modules sets the control:Proxy-To-Realm attribute to the realm name. The server will then proxy the packet to the given realm.

The default configuration of the module includes the two most common variations: user@realm and realm\user. Two older formats are also defined: realm/username and user%realm.

It is possible to use multiple realm formats at the same time. To do so, list the different realm modules in the relevant subsection.

Known realms are defined in the proxy.conf file. These realms are independent of the format specified by the realm module. That is, all realms are global, no matter what is in the User-Name attribute.

Processing Sections

authorize

When listed in the authorize section, the realm module searches the User-Name attribute for the delimiter, as given below. If no delimiter is found, then the module stops and does nothing more.

When a delimiter is found, the format is used to find the realm portion. If format = suffix, the realm is taken from the string directly after the delimiter. If format = prefix, the realm is taken from the string directly before the delimiter.

The found realm is then looked up in the set of "realms" defined in proxy.conf. If no matching realm is found, the module stops and does nothing more.

If a matching realm is found, that realm configuration is checked to see whether or not the "user" portion of the User-Name should be separated from the "realm" portion. If the realm has nostrip set, then the User-Name is left alone. Otherwise, the Stripped-User-Name attribute is created and set to the value of the "user" portion of the User-Name attribute.

This Stripped-User-Name is often used for database lookups, as it contains the user identifier without any delimiter or realm portion.

The Realm attribute is also set to the value of the "realm" portion of the User-Name attribute.

If the realm found in the proxy.conf file is a local realm, then the module stops and does nothing more.

Otherwise, the control:Proxy-To-Realm attribute is set to the realm name. The server will then find this attribute and proxy the request instead of performing local authentication.

If the User-Name does not contain a delimiter, then the module uses the NULL realm for processing the request. If the User-Name contains a delimiter but the realm was not found in proxy.conf, then the module uses the DEFAULT realm for processing the request.

The NULL realm and the DEFAULT realm allow generic handling of non-existent or unknown realms.

Return codes

noop The module did nothing.

ok The realm was local.

updated The packet is marked as to be proxied.

preacct

When listed in the preacct section, the realm module performs realm checking as described above in authorize. The acct_pool is also used for proxying.

The module checks if the Accounting-Request packet was received from a home server for that realm. If so, it does not proxy the packet to that realm. This check enables a simple fail-over configuration, where two servers can proxy Accounting-Request packets to each other without worrying about infinite proxy loops.

recv-coa

When listed in the recv-coa section, the realm module performs realm checking as described above in authorize. The one change is that the realm checking is performed on the Operator-Name attribute instead of the User-Name attribute. The coa_pool is also used for proxying.

This change allows the server to proxy CoA-Request packets from a home server to a NAS.

Expansions

None.

Directives

delimiter
Syntax

delimiter = string

Default

@

Description

The delimiter is a single character that is used to separate the User-Name attribute into a "user" portion and a "realm" portion.

If the delimiter is not found, then the module assumes that the User-Name does not contain a realm, and did nothing.

format
Syntax

format = prefix | suffix

Default

suffix

Description

Indicates whether the realm portion is before or after the delimiter. The default configuration assumes "user@realm".