Note final changes

[freeradius.git] / doc / module_interface

diff --git a/doc/module_interface b/doc/module_interface
index 5a08fca..11409be 100644 (file)
--- a/doc/module_interface
+++ b/doc/module_interface
@@ -4,6 +4,52 @@ RLM Module Interface (for developers)
 
 Section 1 - overview
 
+Section 1.1 Intent of the server.
+
+FreeRADIUS is an authentication server.  It does RADIUS authorization,
+authentication, and accounting.  It does NOT do database management,
+user configuration updates, or email.  All of those functions may be
+more easily (and correctly) performed in programs outside of the
+server.
+
+The only functionality performed by the server is:
+
+       - receive a RADIUS request
+       - process the request
+               - look up information one or more databases
+               - store information in one or more databases
+                 (proxying can be viewed this way)
+       - respond to the request
+
+There is no room, or need, for timers, listening on sockets, or
+anything else in the server.  Adding those functions to the server
+means that it will become more complex, more unstable, more insecure,
+and more difficult to maintain.
+
+
+Section 1.2 Intent of the modules.
+
+The intent of modules is that they do small, simple, well-defined
+things when RADIUS packets are received.  If the module does things
+when RADIUS packets are NOT received, then it has no business being in
+the server.  Similarly, the module infrastructure is NOT intended to
+allow servers, applications, timed events, or anything other than
+handling incoming RADIUS packets.
+
+Modules perform an action when RADIUS packets are received.  Modules
+which do more (creating threads, forking programs) will NOT be added
+to the server, and the server core will NOT be modified to enable
+these kinds of modules.  Those functions more properly belong in a
+seperate application.
+
+Modules ARE permitted to open sockets to other network programs, and
+to send and receive data on those sockets.  Modules are NOT permitted
+to open sockets, and to listen for requests.  Only the server core has
+that functionality, and it only listens for RADIUS requests.
+
+
+Section 1.3 Module outline
+
 The fundamental concepts of the rlm interface are module, instance, and
 component.
 
@@ -31,9 +77,10 @@ requests at different stages. The components are:
   - preaccounting: decide whether to proxy the request, and possibly add
     attributes that should be included in any logs
   - accounting: record the request in the log
-  - checksimul (AVAILABLE AS EXTERNAL PATCH): count the number of active
-    sessions for the user
-  - postproxyauth (DOES NOT EXIST YET): filter attributes from a reply to a
+  - checksimul: count the number of active sessions for the user
+  - postauth: process the response before it's sent to the NAS
+  - preproxy: process a request before it's proxied
+  - postproxy: filter attributes from a reply to a
     proxied request
 
 A module declares which components it supports by putting function pointers
@@ -65,11 +112,13 @@ the module and generally point to the exact location of a database or enable
 optional features of the module. Each module should document what parameters
 it accepts and what they do.
 
-For each Access-Request that comes to the server, the authorize{} block is
-called. Then one of the authtype{} blocks from authenticate{} is called,
-depending on the Auth-Type attribute that was chosen by authorize{}. If
-authorize{} set the Proxy-To-Realm attribute, then proxying takes over and
-the local authenticate{} phase is skipped.
+For each Access-Request that comes to the server, the authorize{}
+block is called. Then one of the Auth-Type{} blocks from authenticate{}
+is called, depending on the Auth-Type attribute that was chosen by
+authorize{}. Finally, the post-auth{} block is called.  If authorize{}
+set the Proxy-To-Realm attribute, then proxying takes over via
+pre-proxy{} and post-proxy{}, and the local authenticate{} phase is
+skipped.
 
 For each Accounting-Request that comes to the server, the preacct{} block is
 called, followed by the accounting{} block. accounting{} is skipped if