From: Alan T. DeKok <aland@freeradius.org>
Date: Tue, 15 Nov 2022 11:01:39 +0000 (-0500)
Subject: add documentation for limit and timeout
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=320059db8720fa11541e180e81ef00a16e9772c1;p=thirdparty%2Ffreeradius-server.git

add documentation for limit and timeout
---

diff --git a/doc/antora/modules/reference/nav.adoc b/doc/antora/modules/reference/nav.adoc
index 45f85c0d292..f26f43987c4 100644
--- a/doc/antora/modules/reference/nav.adoc
+++ b/doc/antora/modules/reference/nav.adoc
@@ -15,6 +15,7 @@
 **** xref:unlang/group.adoc[group]
 **** xref:unlang/if.adoc[if]
 **** xref:unlang/load-balance.adoc[load-balance]
+**** xref:unlang/limit.adoc[limit]
 **** xref:unlang/map.adoc[map]
 **** xref:unlang/parallel.adoc[parallel]
 **** xref:unlang/redundant-load-balance.adoc[redundant-load-balance]
@@ -22,6 +23,7 @@
 **** xref:unlang/return.adoc[return]
 **** xref:unlang/subrequest.adoc[subrequest]
 **** xref:unlang/switch.adoc[switch]
+**** xref:unlang/timeout.adoc[timeout]
 **** xref:unlang/update.adoc[update]
 
 *** xref:unlang/interpreter.adoc[Interpreter]
diff --git a/doc/antora/modules/reference/pages/unlang/keywords.adoc b/doc/antora/modules/reference/pages/unlang/keywords.adoc
index 5a7ae89da8c..6796412b35b 100644
--- a/doc/antora/modules/reference/pages/unlang/keywords.adoc
+++ b/doc/antora/modules/reference/pages/unlang/keywords.adoc
@@ -19,6 +19,8 @@ looping, etc.
 | xref:unlang/elsif.adoc[elsif]     | Check for condition when a previous `if` does not match.
 | xref:unlang/foreach.adoc[foreach] | Loop over a list of attributes.
 | xref:unlang/if.adoc[if]           | Check for a condition, and execute a sub-policy if it matches.
+| xref:unlang/limit.adoc[limit]     | Limit the number of requests in a section
+| xref:unlang/timeout.adoc[timeout] | Enforce a timeout for processing a section
 | xref:unlang/return.adoc[return]   | Immediately stop processing a section.
 | xref:unlang/switch.adoc[switch]   | Check for multiple values.
 |=====
diff --git a/doc/antora/modules/reference/pages/unlang/limit.adoc b/doc/antora/modules/reference/pages/unlang/limit.adoc
new file mode 100644
index 00000000000..1b89f46214b
--- /dev/null
+++ b/doc/antora/modules/reference/pages/unlang/limit.adoc
@@ -0,0 +1,48 @@
+= The limit Statement
+
+.Syntax
+[source,unlang]
+----
+limit <value> {
+    [ statements ]
+}
+----
+
+.Description
+The `limit` statement limits the number of requests which are actively
+being processed through a section.  If too many requests are being
+processed through the `limit` section, it immediately returns `fail`.
+
+The _<value>_ text can be a number, or a dynamic expansion, or an
+attribute reference.  The contents of _<value>_ are interpreted as an
+integer `uint32` data type.
+
+.Example
+[source,unlang]
+----
+limit 4 {
+    foo
+    bar
+}
+----
+
+In general, the best way to use `limit` is in conjunction with a
+`redundant` block.  In the following example, the configuration allows
+`4` packets to be outstanding in the `proxy` module.  If more than `4`
+packets are outstanding, _or_ if the `proxy` module fails, the
+`detail` module is called.
+
+.Example using redundant
+[source,unlang]
+----
+redundant
+    limit 4 {
+        proxy
+    }
+
+    detail
+}
+----
+
+// Copyright (C) 2022 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/timeout.adoc b/doc/antora/modules/reference/pages/unlang/timeout.adoc
new file mode 100644
index 00000000000..73cc4c15a7f
--- /dev/null
+++ b/doc/antora/modules/reference/pages/unlang/timeout.adoc
@@ -0,0 +1,51 @@
+= The timeout Statement
+
+.Syntax
+[source,unlang]
+----
+timeout <value> {
+    [ statements ]
+}
+----
+
+.Description
+The `timeout` statement limits the total time which a section can use
+to process a particular request.  If the request takes more than the
+given time, it returns `fail`.
+
+The _<value>_ text can be a number, or a dynamic expansion, or an
+attribute reference.  The contents of _<value>_ are interpreted as a
+`time_delta`, with default scale in seconds.
+
+The time scale can be changed by appending `s`, `us`, `ms`, `ns`, etc. as
+with all uses of `time_delta` values.
+
+.Example
+[source,unlang]
+----
+timeout 1ms {
+    foo
+    bar
+}
+----
+
+In general, the best way to use `timeout` is in conjunction with a
+`redundant` block.  In the following example, the configuration allows
+the `proxy` module to run for `4` seconds.  If the `proxy` module
+takes more than `4` seconds to return, _or_ if the `proxy` module
+fails, the `detail` module is called.
+
+.Example using redundant
+[source,unlang]
+----
+redundant
+    timeout 4s {
+        proxy
+    }
+
+    detail
+}
+----
+
+// Copyright (C) 2022 Network RADIUS SAS.  Licenced under CC-by-NC 4.0.
+// Development of this documentation was sponsored by Network RADIUS SAS.