2 RLM Module Interface (for developers)
3 =====================================
11 FreeRADIUS is an authentication server. It does RADIUS authorization,
12 authentication, and accounting. It does NOT do database management,
13 user configuration updates, or email. All of those functions may be
14 more easily (and correctly) performed in programs outside of the
17 The only functionality performed by the server is:
19 - receive a RADIUS request
21 - look up information one or more databases
22 - store information in one or more databases (proxying can be viewed this way)
23 - respond to the request
25 There is no room, or need, for timers, listening on sockets, or
26 anything else in the server. Adding those functions to the server
27 means that it will become more complex, more unstable, more insecure,
28 and more difficult to maintain.
34 The intent of modules is that they do small, simple, well-defined
35 things when RADIUS packets are received. If the module does things
36 when RADIUS packets are NOT received, then it has no business being in
37 the server. Similarly, the module infrastructure is NOT intended to
38 allow servers, applications, timed events, or anything other than
39 handling incoming RADIUS packets.
41 Modules perform an action when RADIUS packets are received. Modules
42 which do more (creating threads, forking programs) will NOT be added
43 to the server, and the server core will NOT be modified to enable
44 these kinds of modules. Those functions more properly belong in a
47 Modules ARE permitted to open sockets to other network programs, and
48 to send and receive data on those sockets. Modules are NOT permitted
49 to open sockets, and to listen for requests. Only the server core has
50 that functionality, and it only listens for RADIUS requests.
56 The fundamental concepts of the rlm interface are module, instance,
59 A module is a chunk of code that knows how to deal with a particular
60 kind of database, or perhaps a collection of similar
63 - rlm_sql contains code for talking to MySQL or Postgres, and for mapping RADIUS records onto SQL tables
64 - rlm_unix contains code for making radiusd fit in well on unix-like systems, including getpw* authentication and utmp/wtmp-style logging.
66 An instance specifies the actual location of a collection data that
67 can be used by a module. Examples:
70 - "the MySQL database on bigserver.theisp.com.example"
72 A module can have multiple components which act on
73 RADIUS requests at different stages. The components are:
75 - authorization: check that a user exists, decide on an authentication method or proxy realm, and possibly apply some attributes to be returned in the reply packet.
76 - authentication: verify that the password is correct.
77 - preaccounting: decide whether to proxy the request, and possibly add attributes that should be included in any logs
78 - accounting: record the request in the log
79 - checksimul: count the number of active sessions for the user
80 - postauth: process the response before it's sent to the NAS
81 - preproxy: process a request before it's proxied
82 - postproxy: filter attributes from a reply to a proxied request
84 A module declares which components it supports by putting function
85 pointers in its "module_t rlm_*" structure.
91 The administrator requests the creation of a module instance by adding
92 it inside the modules{} block in radiusd.conf. The instance definition
95 module_name [instance_name] {
102 The module_name is used to load the module. To see the names of the available
103 modules, look for the rlm\_\*.so files in $installprefix/lib. The module_name
104 is that, minus the rlm\_ and the .so.
106 instance_name is an identifier for distinguishing multiple instances of the
107 same module. If you are only loading a module once, you can leave out the
108 instance_name and it will be assumed to be the same as the module_name.
110 The parameters inside the module block are passed without interpretation to
111 the module and generally point to the exact location of a database or enable
112 optional features of the module. Each module should document what parameters
113 it accepts and what they do.
115 For each Access-Request that comes to the server, the authorize{}
116 block is called. Then one of the Auth-Type{} blocks from authenticate{}
117 is called, depending on the Auth-Type attribute that was chosen by
118 authorize{}. Finally, the post-auth{} block is called. If authorize{}
119 set the Proxy-To-Realm attribute, then proxying takes over via
120 pre-proxy{} and post-proxy{}, and the local authenticate{} phase is
123 For each Accounting-Request that comes to the server, the preacct{} block is
124 called, followed by the accounting{} block. accounting{} is skipped if
125 preacct{} sets Proxy-To-Realm.
127 For an explanation of what "calling" a config block means, see
128 the "configurable_failover" file.
131 The lifetime of a module
132 ^^^^^^^^^^^^^^^^^^^^^^^^
134 When the server is starting up, or reinitializing itself as a result of a
135 SIGHUP, it reads the modules{} section. Each configured module will be loaded
136 and its init() method will be called::
140 The init() method should take care of
141 any setup that is not tied to a specific instance. It will only be called
142 once, even if there are multiple instances configured.
144 For each configured instance, after the init() method, the instantiate()
145 method is called. It is given a handle to the configuration block holding its
146 parameters, which it can access with cf_section_parse().::
148 int instantiate(CONF_SECTION \*cs, void \**instance)
150 The instantiate() function should look up options in the config section, and
151 open whatever files or network connections are necessary for the module to do
152 its job. It also should create a structure holding all of the persistent
153 variables that are particular to this instance (open file descriptors,
154 configured pathnames, etc.) and store a pointer to it in \*instance. That
155 void \* becomes a handle (some would call it a "cookie") representing this
156 instance. The instance handle is passed as a parameter in all subsequent
157 calls to the module's methods, so they can determine which database they are
160 The authorize(), authenticate(), preaccounting(), and accounting() functions
161 are all called the same way::
163 int authorize(void \*instance, REQUEST \*request)
164 int authenticate(void \*instance, REQUEST \*request)
165 int preaccounting(void \*instance, REQUEST \*request)
166 int accounting(void \*instance, REQUEST \*request)
168 they each receive the instance handle and the request, and are expected to
169 act on the request using the database pointed to by the instance handle
170 (which was set by the instantiate() function).
172 When the server is being shut down (as the first part of SIGHUP for example)
173 detach() is called for each module instance.::
175 int detach(void \*instance)
177 The detach() method should release whatever resources were allocated by the
178 instantiate() method.
180 After all instances are detached, the destroy() method is called.::
184 It should release resources that were acquired by the init() method.
186 --Alan Curry <pacman@world.std.com>