Actions and Return Codes

The module syntax allows for the module return codes to be over-ridden on a per-module basis. The actions section allows for section return codes to be over-ridden on a per-section basis.

Syntax

actions {
	fail = 1
	ok = handled
	reject = return
	retry {
		max_rtx_time = 1
		max_rtx_count = 3
		max_rtx_duration = 3
	}
}

Section priority overrides are specified in an actions block, which must be the last thing in a section. Actions can be set in blocks for the following keywords:

case
catch
else
elsif
foreach
if
group
limit
switch
timeout
transaction

The actions block cannot be used in blocks for the following keywords:

redundant
redundant-load-balance
load-balance
parallel

Those sections already have default actions to take for the various return codes. Allowing the actions block to over-ride those default actions would cause those sections to behave differently, and therefore operate incorrectly.

Priorities

Higher numbers mean higher priorities. An rcode of fail with priority 3 will over-ride an rcode of ok with priority 1,

Override Syntax

The format of an override is <rcode> = (<integer>|<action>) - That is, a number greater than or equal to 0, or a named action.

Table 1. Named Actions
Action	Description
`break`	To "break" out of the parent block and stop processing it.
`reject`	Return a `reject` rcode.
`retry`	Re-run the section, as given by the `retry` subsection.
`return`	Return out of the parent block and stop processing it.

You can use the special keyword default on the left side to set all rcodes that haven’t been assigned a priority. For example, default = 1 means any rcode without an assigned priority will now have a priority of "1". The rcodes that have already been set are not affected. The default keyword provides a fallback value for unspecified rcodes, reducing repetitive setup.

Return code Description

Return code	Description
`disallow`	Access to a particular resource is denied. This is similar to `reject` but is the result of an authorization check failing, as opposed to credentials being incorrect.
`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.
`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.
`timeout`	The operation failed due to a timeout.
`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 authorization check failing, as opposed to credentials being incorrect.

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.

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.

timeout

The operation failed due to a timeout.

updated

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

There is an additional internal rcode which has a "not set" value. It is used by the interpreter and generally not visible. You cannot check for this value, or use it in any situation where an rcode is allowed. If this rcode is returned by a module, it indicates an internal problem in the server.

In versions before 4.0, the disallow rcode was called userlock. The terms disallow and userlock have an identical meaning. disallow will be returned in any instance where userlock was returned in v3.0.x or v3.2.x

Retry subsection

The retry subsection is optional, and is only used when the right-hand side of an action is retry.

Table 2. Retry Configuration
Configuration	Description
`max_rtx_count`	Maximum number of times this section is retried.
`max_rtx_time`	Maximum time for one try before it is time out, and another retry made.
`max_rtx_duration`	Maximum time for all retries before the section returns `fail`.

All times and durations are parsed as the data type time_delta.

If no value is given, it is assumed to be zero.

The initial_rtx_time is used for module-level retries, and sets the time until the first retransmission attempt. It is not set on section-level retries.