** xref:list.adoc[Attribute Lists]
** xref:attr.adoc[Attribute References]
+** xref:return_codes.adoc[Return Codes]
** xref:keywords.adoc[Keywords]
*** xref:break.adoc[break]
** xref:condition/index.adoc[Conditional Expressions]
*** xref:condition/cmp.adoc[Comparisons]
*** xref:condition/operands.adoc[Operands]
-*** xref:condition/module.adoc[The module-code Operator]
+*** xref:condition/return_code.adoc[The Return Code Operator]
*** xref:condition/eq.adoc[The '==' Operator]
*** xref:condition/and.adoc[The '&&' Operator]
*** xref:condition/or.adoc[The '||' Operator]
*** xref:condition/para.adoc[The '( )' Operator]
*** xref:condition/regex.adoc[Regular Expressions]
-
** xref:xlat/index.adoc[String Expansion]
*** xref:xlat/alternation.adoc[Alternation Syntax]
*** xref:xlat/builtin.adoc[Built-in Expansions]
|=====
| Syntax | Description
| xref:attr.adoc[&Attribute-Name] | Check for attribute existence.
-| xref:condition/module.adoc[module-code] | Check return code of a previous module.
+| xref:condition/return_code.adoc[rcode] | Check return code of a previous module.
| xref:condition/operands.adoc[data] | Check value of data.
| xref:condition/cmp.adoc[lhs OP rhs] | Compare two kinds of data.
| xref:condition/para.adoc[( condition )] | Check sub-condition
+++ /dev/null
-= The module-code Operator
-
-.Syntax
-[source,unlang]
-----
-module-code
-----
-
-The Unlang interpreter tracks the return code of any module that has
-been called. This return code can be checked in any condition. If the
-saved return code matches the `code` given here, then the condition evaluates
-to `true`. Otherwise, it evaluates to `false`.
-
-Module return codes cannot be set in a condition. Module return codes
-cannot be compared with anything else.
-
-The list of valid return codes is as follows:
-
-.Module Return Codes
-
-[options="header"]
-|==================================================
-|Name |Meaning
-|notfound |information was not found
-|noop |the module did nothing
-|ok |the module succeeded
-|updated |the module updated the request
-|fail |the module failed
-|reject |the module rejected the request
-|userlock |the user was locked out
-|invalid |the configuration was invalid
-|handled |the module has handled the request itself
-|==================================================
-
-.Examples
-
-[source,unlang]
-----
-sql
-if (notfound) {
- ...
-}
-----
-
-// Copyright (C) 2019 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
-// Development of this documentation was sponsored by Network RADIUS SAS.
----
Any text not matching xref:attr.adoc[&Attribute-Name] or
-xref:condition/module.adoc[module-code] is interpreted as a value for a
+xref:condition/return_code.adoc[Return Code] is interpreted as a value for a
particular xref:type/index.adoc[data type].
Double-quoted strings and back-quoted strings are dynamically expanded
--- /dev/null
+= The return code Operator
+
+.Syntax
+[source,unlang]
+----
+rcode
+----
+
+The Unlang interpreter tracks the return code of any module, string expansion
+or keyword that has been called.
+
+This return code can be checked in any condition. If the saved return code
+matches the `code` given here, then the condition evaluates to `true`.
+Otherwise, it evaluates to `false`.
+
+rcodes cannot be set in a condition. rcodes cannot be compared with anything else.
+
+The list of valid return codes is as follows:
+
+.Return Codes
+
+include::partial$rcode_table.adoc[]
+
+.Examples
+
+[source,unlang]
+----
+sql
+if (notfound) {
+ ...
+}
+----
+
+// Copyright (C) 2019 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
+// Development of this documentation was sponsored by Network RADIUS SAS.
.Module Return Codes
-[options="header"]
-|==================================================
-|Name |Meaning
-|reject |the module rejected the request
-|fail |the module failed
-|ok |the module succeeded
-|handled |the module has handled the request itself
-|invalid |the configuration was invalid
-|userlock |the user was locked out
-|notfound |information was not found
-|noop |the module did nothing
-|updated |the module updated the request
-|==================================================
+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.
+
+include::partial$rcode_table.adoc[]
These return codes can be used in a subsequent
xref:condition/index.adoc[conditional expression] thus allowing policies to
}
----
+== 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.
+
+[source, unlang]
+----
+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.
+
+
// Copyright (C) 2019 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// Development of this documentation was sponsored by Network RADIUS SAS.
--- /dev/null
+= Return codes
+
+Many operations in the server produce a return code (rcode).
+The different rcodes give a course indication of whether a particular operation
+(a module call, string expansion, or keyword) was successful.
+
+Unlike return values in other languages, FreeRADIUS' rcodes are are always taken
+from a fixed compiled-in set.
+
+include::partial$rcode_table.adoc[]
+
+Return codes propagate through nested unlang sections based on their priority.
+If a rcode returned by an operation has a higher priority than the current rcode
+associated with the request, then the request rcode is overwritten.
+
+Return code priorities are assigned by the section the module call, expansion or
+keyword was used in.
--- /dev/null
+[options="header"]
+[cols="15%,85%"]
+|=====
+| 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.
+|=====
+
+[NOTE]
+====
+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
+====
projects / thirdparty / freeradius-server.git / commitdiff
