From: Alan T. DeKok Date: Mon, 14 Nov 2022 11:58:03 +0000 (-0500) Subject: document actions and retries X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ad016c5988dca53c0e0068dba12e3dd27601b1f2;p=thirdparty%2Ffreeradius-server.git document actions and retries --- diff --git a/doc/antora/modules/reference/pages/unlang/actions.adoc b/doc/antora/modules/reference/pages/unlang/actions.adoc new file mode 100644 index 00000000000..d6984de0d54 --- /dev/null +++ b/doc/antora/modules/reference/pages/unlang/actions.adoc @@ -0,0 +1,69 @@ += 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 ` = (|)` - 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. diff --git a/doc/antora/modules/reference/pages/unlang/case.adoc b/doc/antora/modules/reference/pages/unlang/case.adoc index 526436e163d..1a0f7f5c1ba 100644 --- a/doc/antora/modules/reference/pages/unlang/case.adoc +++ b/doc/antora/modules/reference/pages/unlang/case.adoc @@ -42,5 +42,7 @@ switch &User-Name { } ---- +The last entry in a `case` section can also be an xref:unlang/actions.adoc[actions] subsection. + // Copyright (C) 2021 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/reference/pages/unlang/else.adoc b/doc/antora/modules/reference/pages/unlang/else.adoc index 71ee7268bc0..4e4926f1eaa 100644 --- a/doc/antora/modules/reference/pages/unlang/else.adoc +++ b/doc/antora/modules/reference/pages/unlang/else.adoc @@ -26,5 +26,7 @@ else { } ---- +The last entry in an `else` section can also be an xref:unlang/actions.adoc[actions] subsection. + // Copyright (C) 2021 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/reference/pages/unlang/elsif.adoc b/doc/antora/modules/reference/pages/unlang/elsif.adoc index 800136f9c1e..125d0f4fa67 100644 --- a/doc/antora/modules/reference/pages/unlang/elsif.adoc +++ b/doc/antora/modules/reference/pages/unlang/elsif.adoc @@ -39,5 +39,7 @@ elsif (&User-Name == "doug") { } ---- +The last entry in an `elsif` section can also be an xref:unlang/actions.adoc[actions] subsection. + // Copyright (C) 2021 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/reference/pages/unlang/group.adoc b/doc/antora/modules/reference/pages/unlang/group.adoc index 520a023281a..aa0e40f6b8d 100644 --- a/doc/antora/modules/reference/pages/unlang/group.adoc +++ b/doc/antora/modules/reference/pages/unlang/group.adoc @@ -35,5 +35,7 @@ group { } ---- +The last entry in a `group` section can also be an xref:unlang/actions.adoc[actions] subsection. + // Copyright (C) 2021 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/reference/pages/unlang/if.adoc b/doc/antora/modules/reference/pages/unlang/if.adoc index e2d7c68086a..e6c519f8297 100644 --- a/doc/antora/modules/reference/pages/unlang/if.adoc +++ b/doc/antora/modules/reference/pages/unlang/if.adoc @@ -25,5 +25,7 @@ if (&User-Name == "bob") { } ---- +The last entry in an `if` section can also be an xref:unlang/actions.adoc[actions] subsection. + // Copyright (C) 2021 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/reference/pages/unlang/module.adoc b/doc/antora/modules/reference/pages/unlang/module.adoc index 449a03ad989..af9669b1f25 100644 --- a/doc/antora/modules/reference/pages/unlang/module.adoc +++ b/doc/antora/modules/reference/pages/unlang/module.adoc @@ -55,6 +55,8 @@ if (notfound) { == 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 ` = (0+||return)` - That is, @@ -81,6 +83,9 @@ ldap { <1> <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.