From a0008e2f3e69c136fe21744a212cd58eb3a1c4a7 Mon Sep 17 00:00:00 2001
From: Linus Nordberg <linus@nordu.net>
Date: Sat, 18 Feb 2012 11:12:13 -0800
Subject: Remove documentation on dynamic lookup since it doesn't work.

Also, add some notes about dynamic lookup esp. wrt. freeing of resources to develdoc.txt.
---
 develdoc.txt           | 63 ++++++++++++++++++++++++++++++++++++++++++++++++++
 radsecproxy.conf.5.xml |  9 +-------
 2 files changed, 64 insertions(+), 8 deletions(-)

diff --git a/develdoc.txt b/develdoc.txt
index 05ee56e..e697b35 100644
--- a/develdoc.txt
+++ b/develdoc.txt
@@ -1,6 +1,7 @@
 radsecproxy documentation for developers
 
 1. Overall design
+=================
 
 At startup client and server configurations are read. Two lists
 are created, called clconfs and srvconfs. Both contain clsrvconf
@@ -35,7 +36,9 @@ xxxserverrd, where xxx is the transport name. The server reader
 is responsible for creating a server writer thread that takes care
 of sending RADIUS replies to a client.
 
+
 2. RADIUS message processing
+============================
 
 In 1 we described the threads used and the high level operations.
 We will now describe how RADIUS messages are processed and flow
@@ -277,3 +280,63 @@ addresses after initial startup.
 Can be defined it extra initialisation is needed for the transport.
 
 };
+
+
+3. Dynamic servers
+==================
+
+A server block can contain the 'dynamicLookupCommand' option, naming
+an executable file which will be executed (fork, exec) with the realm
+of the user being authenticated as its only argument.  The output from
+the program (read from stdout) is used as configuration text and
+parsed as if it was read from a configuration file.
+
+[XXX describe what happens when config is read -- set in
+createsubrealmservers() if the server block has the
+'dynamicLookupCommand' option]
+
+[XXX describe what happens when a packet is handled -- findserver()
+creating a realm object]
+
+Dynamic freeing of resources
+----------------------------
+
+At the end of clientwr(), if server->dynamiclookuparg != NULL, the
+removeserversubrealms(list, server) function is called and normally
+so is freeclsrvconf(server).
+
+removeserversubrealms() traverses the list of realms (taking a lock on
+each realm) and calls _internal_removeserversubrealms(subrealm,
+server) on each subrealm.  If the list of subrealms is empty after
+this, it's being destroyed.
+
+The _internal_removeserversubrealms(realm list, SERVER) function
+traverses the list of realms and for each realm:
+
+  - increase the refcount on the realm
+
+  - take the lock on the realm
+
+  - for srv in realm->srvconfs: if srv == SERVER: decrease ref on realm
+
+  - free all servers in realm->srvconfs matching SERVER
+    (list_removedata() TODO: is this function correct?)
+
+  - same thing for realm->accsrvconfs as for srvconfs
+
+  - if none of the realm->srvconfs nor the realm->accsrvonfs has a
+    dynamiclookupcommand:
+
+    - for each srv in realm->srvconfs: free srv and decrease ref on realm
+
+    - destroy realm->srvconfs
+
+    - same thing for realm->accsrvconfs as for srvconfs
+
+    - release the realm lock
+
+    - decrease the refcount on the realm
+
+freeclsrvconf() performs 15 calls to free() and also invokes
+freegconfmstr(), freehostports(), regfree() and
+pthread_mutex_destroy().
diff --git a/radsecproxy.conf.5.xml b/radsecproxy.conf.5.xml
index 3871e06..35182f0 100644
--- a/radsecproxy.conf.5.xml
+++ b/radsecproxy.conf.5.xml
@@ -633,8 +633,7 @@ blocktype name {
       <literal>AddTTL</literal>, <literal>rewrite</literal>,
       <literal>rewriteIn</literal>, <literal>rewriteOut</literal>,
       <literal>statusServer</literal>, <literal>retryCount</literal>,
-      <literal>retryInterval</literal>,
-      <literal>dynamicLookupCommand</literal> and
+      <literal>retryInterval</literal> and
       <literal>LoopPrevention</literal>.
     </para>
     <para>
@@ -669,12 +668,6 @@ blocktype name {
       an interval of 5s.
     </para>
     <para>
-      The option <literal>dynamicLookupCommand</literal> can be used
-      to specify a command that should be executed to dynamically
-      configure and use a server.  The use of this feature will be
-      documented separately/later.
-    </para>
-    <para>
       Using the <literal>LoopPrevention</literal> option here
       overrides any basic setting of this option.  See section
       <literal>BASIC OPTIONS</literal> for details on this option.
-- 
cgit v1.1