--- /dev/null
+= Actions and Return Codes
+
+The xref:unlang/module.adoc[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
+[source, unlang]
+----
+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`
+* `if`
+* `else`
+* `elsif`
+* `group`
+
+== 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.
+
+.Named Actions
+[options="header"]
+[cols="30%,70%"]
+|=====
+| Action | Description
+| break | "break" out of the parent block and stop processing it.
+| default | Use the defaut priority for this rcode.
+| reject | return a `reject` rcode.
+| retry | re-run the section, as given by the the `retry` subsection.
+| return | return out of the parent block and stop processing it.
+|=====
+
+include::partial$rcode_table.adoc[]
+
+== Retry subsection
+
+The `retry` subsection is optional, and is only used when the
+right-hand side of an action is `retry`.
+
+.Retry Configuration
+[options="header"]
+[cols="30%,70%"]
+|=====
+| 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.
== Module Return Code priority overrides
In the case of modules, rcodes can be modified on a per-call basis.
+These over-rides use the same syntax as the
+xref:unlang/actions.adoc[actions] subsection.
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,
<4> Sets the priority of `reject` to be `return`. If the module returns
`reject`, the current section will immediately exit.
+See the xref:unlang/actions.adoc[actions] page for more information on
+the syntax of the `actions` section.
+
// Copyright (C) 2021 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// Development of this documentation was sponsored by Network RADIUS SAS.
projects / thirdparty / freeradius-server.git / commitdiff
