Skip to content
Permalink
Browse files

More documentation for return codes

  • Loading branch information
arr2036 committed Sep 25, 2019
1 parent b582100 commit dc886b3208a405f736441eead7e537fc505e6cc2
@@ -2,6 +2,7 @@
** xref:list.adoc[Attribute Lists]
** xref:attr.adoc[Attribute References]
** xref:return_codes.adoc[Return Codes]

** xref:keywords.adoc[Keywords]
*** xref:break.adoc[break]
@@ -40,15 +41,14 @@
** 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/not.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]
@@ -18,7 +18,7 @@ Conditions are expressed using the following syntax:
|=====
| 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

This file was deleted.

@@ -11,7 +11,7 @@ integer
----

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
@@ -0,0 +1,35 @@
= 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.
@@ -30,19 +30,11 @@ the source, below:

.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
@@ -60,5 +52,35 @@ if (notfound) {
}
----

== 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.
@@ -0,0 +1,17 @@
= 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.
@@ -0,0 +1,39 @@
[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
====

0 comments on commit dc886b3

Please sign in to comment.
You can’t perform that action at this time.