Modules

Syntax

<module>

The <module> statement is a reference to the named module. Common module names include pap, chap, files, eap, and sql. The modules { … } subsection of radiusd.conf contains all of the valid modules.

When processing reaches a named module, the pre-compiled module is called. The module may succeed or fail and will return a status code to the unlang interpreter detailing success or failure.

Example

chap
sql

Module Return Codes

When a module is called, it returns one of the following codes to the interpreter; the meaning of each code is detailed to the right of the source, below:

Module Return Codes

The below table describes the purpose of the rcodes that may be returned by a module call. In this case the 'operation' referenced in the table is the current module call.

Return code Description

Return code	Description
`fail`	The operation failed. Usually as a result of an external dependency like a database being unavailable or an internal error.
`handled`	The request has been "handled", no further policies in the current section should be called, and the section should immediately exit.
`invalid`	The request, or operation, was invalid. In the case of requests this usually indicates absent or malformed attribute values.
`noop`	The operation did nothing.
`notfound`	A 'lookup' operation returned no results.
`ok`	Operation completed successfully but did not change any attributes in the request.
`reject`	The operation indicates the current request should be 'rejected'. What this actually means is different from protocol to protocol. It usually means that access to the requested resource should be denied, or that the current request should be NAKd. Usually returned when provided credentials were invalid.
`updated`	The operation completed successfully and updated one or more attributes in the request.
`disallow`	Access to a particular resource is denied. This is similar to `reject` but is the result of an authorizational check failing, as opposed to credentials being incorrect.
`yield`	Returned by an operation when execution of a request should be suspended.

fail

The operation failed. Usually as a result of an external dependency like a database being unavailable or an internal error.

handled

The request has been "handled", no further policies in the current section should be called, and the section should immediately exit.

invalid

The request, or operation, was invalid. In the case of requests this usually indicates absent or malformed attribute values.

noop

The operation did nothing.

notfound

A 'lookup' operation returned no results.

ok

Operation completed successfully but did not change any attributes in the request.

reject

The operation indicates the current request should be 'rejected'. What this actually means is different from protocol to protocol. It usually means that access to the requested resource should be denied, or that the current request should be NAKd. Usually returned when provided credentials were invalid.

updated

The operation completed successfully and updated one or more attributes in the request.

disallow

Access to a particular resource is denied. This is similar to reject but is the result of an authorizational check failing, as opposed to credentials being incorrect.

yield

Returned by an operation when execution of a request should be suspended.

In versions ≤ v3.0.x the disallow rcode was called userlock. disallow and userlock have an identical meaning. disallow will be returned in any instance where userlock was returned in v3.0.x

These return codes can be used in a subsequent conditional expression thus allowing policies to perform different actions based on the behaviour of the modules.

Example

sql
if (notfound) {
    update reply {
        Reply-Message = "We don't know who you are"
    }
    reject
}

Module Return Code priority overrides

In the case of modules, rcodes can be modified on a per-call basis.

Module priority overrides are specified in a block inline with the module call. The format of an override is <rcode> = (0+|<rcode>|return) - That is, a number greater than or equal to 0, the priority of another rcode, or the special priority return which causes the current section to immediately exit.

ldap { (1)
	fail = 1        (2)
	ok = handled    (3)
	reject = return (4)
}

1	Call to the `ldap` module.
2	Sets the priority of the `fail` rcode to be `1`. If the priority of the rcode for the request is `0`, then the request request rcode will be set to `fail` if the module returns `fail`.
3	Sets the priority of the `ok` rcode to be whatever the default is for `handled` in this section. As the default for `handled` is usually `return`. If `ok` is returned, the current section will immediately exit.
4	Sets the priority of `reject` to be `return`. If the module returns `reject`, the current section will immediately exit.