From: Arran Cudbard-Bell Date: Wed, 25 Sep 2019 10:57:28 +0000 (-0500) Subject: More documentation for return codes X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=dc886b3208a405f736441eead7e537fc505e6cc2;p=thirdparty%2Ffreeradius-server.git More documentation for return codes --- diff --git a/doc/antora/modules/unlang/nav.adoc b/doc/antora/modules/unlang/nav.adoc index 935c8ad2bdb..5a4f8903476 100644 --- a/doc/antora/modules/unlang/nav.adoc +++ b/doc/antora/modules/unlang/nav.adoc @@ -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,7 +41,7 @@ ** 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] @@ -48,7 +49,6 @@ *** 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] diff --git a/doc/antora/modules/unlang/pages/condition/index.adoc b/doc/antora/modules/unlang/pages/condition/index.adoc index 5e8d3a13c09..1c738d7bc1c 100644 --- a/doc/antora/modules/unlang/pages/condition/index.adoc +++ b/doc/antora/modules/unlang/pages/condition/index.adoc @@ -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 diff --git a/doc/antora/modules/unlang/pages/condition/module.adoc b/doc/antora/modules/unlang/pages/condition/module.adoc deleted file mode 100644 index 390c2e81cc4..00000000000 --- a/doc/antora/modules/unlang/pages/condition/module.adoc +++ /dev/null @@ -1,46 +0,0 @@ -= 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. diff --git a/doc/antora/modules/unlang/pages/condition/operands.adoc b/doc/antora/modules/unlang/pages/condition/operands.adoc index ce7442371b3..f4de6beb997 100644 --- a/doc/antora/modules/unlang/pages/condition/operands.adoc +++ b/doc/antora/modules/unlang/pages/condition/operands.adoc @@ -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 diff --git a/doc/antora/modules/unlang/pages/condition/return_codes.adoc b/doc/antora/modules/unlang/pages/condition/return_codes.adoc new file mode 100644 index 00000000000..ebba4dd6840 --- /dev/null +++ b/doc/antora/modules/unlang/pages/condition/return_codes.adoc @@ -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. diff --git a/doc/antora/modules/unlang/pages/module.adoc b/doc/antora/modules/unlang/pages/module.adoc index 6a196d6a2ed..4a483dc9661 100644 --- a/doc/antora/modules/unlang/pages/module.adoc +++ b/doc/antora/modules/unlang/pages/module.adoc @@ -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 ` = (0+||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. diff --git a/doc/antora/modules/unlang/pages/return_codes.adoc b/doc/antora/modules/unlang/pages/return_codes.adoc new file mode 100644 index 00000000000..3b09c2dc525 --- /dev/null +++ b/doc/antora/modules/unlang/pages/return_codes.adoc @@ -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. diff --git a/doc/antora/modules/unlang/partials/rcode_table.adoc b/doc/antora/modules/unlang/partials/rcode_table.adoc new file mode 100644 index 00000000000..e114e745078 --- /dev/null +++ b/doc/antora/modules/unlang/partials/rcode_table.adoc @@ -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 +====