From 851f53cec716bee00eb925e4a818696df6ba4945 Mon Sep 17 00:00:00 2001
From: "Alan T. DeKok" <aland@freeradius.org>
Date: Wed, 12 Feb 2025 15:00:32 -0500
Subject: [PATCH] regenerate

---
 .../pages/raddb/mods-available/radius.adoc    | 112 +++++++++++++++++-
 1 file changed, 108 insertions(+), 4 deletions(-)

diff --git a/doc/antora/modules/reference/pages/raddb/mods-available/radius.adoc b/doc/antora/modules/reference/pages/raddb/mods-available/radius.adoc
index 129df05e93..e986255d29 100644
--- a/doc/antora/modules/reference/pages/raddb/mods-available/radius.adoc
+++ b/doc/antora/modules/reference/pages/raddb/mods-available/radius.adoc
@@ -529,7 +529,7 @@ are the same for all packet types.
 
 
 
-### Access requests packets
+### Access Request packets
 
 
 initial_rtx_time::  If there is no response within this time,
@@ -665,12 +665,36 @@ along with all per-packet timeouts.
 
 
 
-A dynamic proxy module
+## Dynamic Proxying
 
+This module supports dynamic proxying via a run-time function:
 
 
-We are not opening a socket from our server to their
-server.  We are replicating packets.
+The first part of the function name (e.g. `proxy`) is taken from
+the module name.  The rest is fixed as `sendto.ipaddr()`
+
+The arguments to the function are:
+
+  * destination IP address.
+  * destination port
+  * shared secret
+
+The function will return the type of response packet if it receives
+as a response, or else the function all will fail.
+
+
+The packet name must be a quoted string.
+
+The proxying is done asynchronously.  i.e. the packet is sent, and
+the server goes on to do other work.  At some point in the future,
+a response is received, the module processes it, and the server
+continues.
+
+The timeouts are controlled as described above.
+
+
+
+The mode.
 
 
 
@@ -685,6 +709,32 @@ src_ipaddr:: The source IP address used by the module.
 
 
 
+src_port_start:: Start of source port range.
+
+The outgoing proxy normally uses random source
+ports.  When all of the RADIUS IDs are used for one
+connection, it opens up another random source port.
+
+However, it is sometimes useful to restrict the
+range of source ports to known values.  The
+`src_port_start` and `src_port_end` configuration
+flags allow the port range to be controlled.  The
+module will then restrict the source ports it is
+using to be within this range.
+
+When all ports in this range are used, the module
+will not be able to open any more outgoing
+connections.x
+
+These two configuratiuon items can only be used for
+UDP sockets.
+
+
+
+src_port_end:: End of source port range.
+
+
+
 `src_port` cannot be used.  If it is used here, the
 module will refuse to start.  Instead, the module
 will open a unique source port per thread.
@@ -694,6 +744,44 @@ will be ignored.
 
 
 
+Dynamic proxying does *not* support the `status_check`
+section.
+
+
+
+home_server_lifetime:: The lifetime of the home server.
+
+When a new dynamic home server is used, the module caches
+information about it.  So long as the home server is still
+being used, it will not expire.  But if it has received all
+expected responses (or timeouts), _and_ it has reached its
+expected lifetime, then the home server will be deleted.
+
+This process allows for the secret to change over time.
+However, the secret can only be changed if there are no
+outstanding packets.  Otherwise, changing the secret would
+involve having multiple packets outstanding which have
+different secrets.  That doesn't work, and can't be fixed
+through any code changes on the server.
+
+The solution to that is to switch to using TLS.
+
+
+
+These are allowed, but are less useful.  If the home server
+doesn't respond, it will often just hit the home server
+lifetime, and be deleted.
+
+
+
+## Timeouts
+
+Timeouts for proxying are controlled in sections named for
+the packet type.  See the examples above for full
+documentation.
+
+
+
 ## Connection trunking
 
 See above for documentation on connection trunking.
@@ -917,12 +1005,28 @@ radius replicate {
 		src_ipaddr = *
 	}
 }
+#	%proxy.sendto.ipaddr(127.0.0.1, 1812, "testing123")
+#	if (%proxy.sendto.ipaddr(127.0.0.1, 1812, "testing123") == 'Access-Accept') {
+#	  ...
+#	}
 radius proxy {
 	type = Access-Request
 	mode = dynamic-proxy
 	transport = udp
 	udp {
 		src_ipaddr = *
+		src_port_start = 10000
+		src_port_end = 11000
+	}
+	home_server_lifetime = 3600
+	response_window = 15
+	zombie_period = 10
+	revive_interval = 3600
+	Access-Request {
+		initial_rtx_time = 2
+		max_rtx_time = 16
+		max_rtx_count = 5
+		max_rtx_duration = 30
 	}
 	pool {
 		start = 0
-- 
2.47.3