RLM Module Interface (for developers)
--------------------------------------
+=====================================
-Section 1 - overview
+Overview
+--------
-Section 1.1 Intent of the server.
+Intent of the server
+^^^^^^^^^^^^^^^^^^^^
FreeRADIUS is an authentication server. It does RADIUS authorization,
authentication, and accounting. It does NOT do database management,
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
+- 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
and more difficult to maintain.
-Section 1.2 Intent of the modules.
+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
that functionality, and it only listens for RADIUS requests.
-Section 1.3 Module outline
+Module outline
+^^^^^^^^^^^^^^
-The fundamental concepts of the rlm interface are module, instance, and
-component.
+The fundamental concepts of the rlm interface are module, instance,
+and component.
-A module is a chunk of code that knows how to deal with a particular kind of
-database, or perhaps a collection of similar databases. Examples:
+A module is a chunk of code that knows how to deal with a particular
+kind of database, or perhaps a collection of similar
+databases. Examples:
- - rlm_sql contains code for talking to MySQL or Postgres, and for mapping
- RADIUS records onto SQL tables.
- - rlm_unix contains code for making radiusd fit in well on unix-like
- systems, including getpw* authentication and utmp/wtmp-style logging.
+- rlm_sql contains code for talking to MySQL or Postgres, and for mapping RADIUS records onto SQL tables
+- rlm_unix contains code for making radiusd fit in well on unix-like systems, including getpw* authentication and utmp/wtmp-style logging.
-An instance specifies the actual location of a collection data that can be
-used by a module. Examples:
+An instance specifies the actual location of a collection data that
+can be used by a module. Examples:
- - /var/log/radutmp
- - "the MySQL database on bigserver.theisp.com.example"
+- /var/log/radutmp
+- "the MySQL database on bigserver.theisp.com.example"
-A module can have up to 4 (soon to be 5? 6?) components which act on RADIUS
-requests at different stages. The components are:
+A module can have multiple components which act on
+RADIUS requests at different stages. The components are:
- - 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.
- - authentication: verify that the password is correct.
- - 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: 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
+- 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.
+- authentication: verify that the password is correct.
+- 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: 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
-in its "module_t rlm_*" structure.
+A module declares which components it supports by putting function
+pointers in its "module_t rlm_*" structure.
-Section 2 - Module configuration:
-The administrator requests the creation of a module instance by adding it
-inside the modules{} block in radiusd.conf. The instance definition looks
-like this:
+Module configuration
+^^^^^^^^^^^^^^^^^^^^
+
+The administrator requests the creation of a module instance by adding
+it inside the modules{} block in radiusd.conf. The instance definition
+looks like this::
module_name [instance_name] {
param1 = value1
}
The module_name is used to load the module. To see the names of the available
-modules, look for the rlm_*.so files in $installprefix/lib. The module_name
-is that, minus the rlm_ and the .so.
+modules, look for the rlm\_\*.so files in $installprefix/lib. The module_name
+is that, minus the rlm\_ and the .so.
instance_name is an identifier for distinguishing multiple instances of the
same module. If you are only loading a module once, you can leave out the
preacct{} sets Proxy-To-Realm.
For an explanation of what "calling" a config block means, see
-README.failover.
+the "configurable_failover" file.
+
-Section 3 - The lifetime of a module
+The lifetime of a module
+^^^^^^^^^^^^^^^^^^^^^^^^
When the server is starting up, or reinitializing itself as a result of a
SIGHUP, it reads the modules{} section. Each configured module will be loaded
-and its init() method will be called.
+and its init() method will be called::
int init(void)
For each configured instance, after the init() method, the instantiate()
method is called. It is given a handle to the configuration block holding its
-parameters, which it can access with cf_section_parse().
+parameters, which it can access with cf_section_parse().::
- int instantiate(CONF_SECTION *cs, void **instance)
+ int instantiate(CONF_SECTION \*cs, void \**instance)
The instantiate() function should look up options in the config section, and
open whatever files or network connections are necessary for the module to do
its job. It also should create a structure holding all of the persistent
variables that are particular to this instance (open file descriptors,
-configured pathnames, etc.) and store a pointer to it in *instance. That
-void * becomes a handle (some would call it a "cookie") representing this
+configured pathnames, etc.) and store a pointer to it in \*instance. That
+void \* becomes a handle (some would call it a "cookie") representing this
instance. The instance handle is passed as a parameter in all subsequent
calls to the module's methods, so they can determine which database they are
supposed to act on.
The authorize(), authenticate(), preaccounting(), and accounting() functions
-are all called the same way:
+are all called the same way::
- int authorize(void *instance, REQUEST *request)
- int authenticate(void *instance, REQUEST *request)
- int preaccounting(void *instance, REQUEST *request)
- int accounting(void *instance, REQUEST *request)
+ int authorize(void \*instance, REQUEST \*request)
+ int authenticate(void \*instance, REQUEST \*request)
+ int preaccounting(void \*instance, REQUEST \*request)
+ int accounting(void \*instance, REQUEST \*request)
they each receive the instance handle and the request, and are expected to
act on the request using the database pointed to by the instance handle
(which was set by the instantiate() function).
When the server is being shut down (as the first part of SIGHUP for example)
-detach() is called for each module instance.
+detach() is called for each module instance.::
- int detach(void *instance)
+ int detach(void \*instance)
The detach() method should release whatever resources were allocated by the
instantiate() method.
-After all instances are detached, the destroy() method is called.
+After all instances are detached, the destroy() method is called.::
int destroy(void)
Supervising the Radiusd Daemon
+==============================
-0. INTRODUCTION
+Introduction
+------------
- We all hope that our radius daemons won't die in the middle of the
- nite stranding customer and beeping beepers. But, alas, it's going
- to happen, and when you least expect it. That's why you want a
- another process watching your radius daemon, restarting it if and
- when it dies.
+We all hope that our radius daemons won't die in the middle of the
+nite stranding customer and beeping beepers. But, alas, it's going to
+happen, and when you least expect it. That's why you want a another
+process watching your radius daemon, restarting it if and when it
+dies.
- This text describes how to setup both the free radius daemon so that
- it is automatically restarted upon death. To do this, we'll use
- either Dan Bernstein's 'daemontools' package or the inittab file.
+This text describes how to setup both the free radius daemon so that
+it is automatically restarted if the process quits unexpectedly. To
+do this, we'll use either Dan Bernstein's 'daemontools' package or the
+inittab file. Note: The radwatch script that used to be part of this
+distribution, is depreciated and SHOULD NOT BE USED.
- Note: The radwatch script that used to be part of this distribution,
- is depreciated and SHOULD NOT BE USED.
+Setting Up Daemontools
+----------------------
-1. SETTING UP DAEMONTOOLS
+First, download (and install) daemontools from:
- First, download (and install) daemontools from:
+ http://cr.yp.to/daemontools.html
- http://cr.yp.to/daemontools.html
+The latest version as of this writing is 0.70. It would be well worth
+your while to read all the documentation at that site too, as you can
+do much more with daemontools than I describe here.
- The latest version as of this writing is 0.70. It would be well
- worth your while to read all the documentation at that site too,
- as you can do much more with daemontools than I describe here.
+Next, we'll need a directory for the radius 'service' to use with
+daemontools. I usually create a dir '/var/svc' to hold all my
+daemontool supervised services. i.e.::
- Next, we'll need a directory for the radius 'service' to use with
- daemontools. I usually create a dir '/var/svc' to hold all my
- daemontool supervised services. Ie:
+ $ mkdir /var/svc
+ $ mkdir /var/svc/radiusd
- # mkdir /var/svc
- # mkdir /var/svc/radiusd
+Now we just need a short shell script called 'run' in our new service
+directory that will start our daemon. The following should get you
+started::
- Now we just need a short shell script called 'run' in our new
- service directory that will start our daemon. The following should
- get you started:
+ #!/bin/sh
+ # Save as /var/svc/radiusd/run
+ exec /usr/local/sbin/radiusd -s -f
- /var/svc/radiusd/run:
- ---------------------
- #!/bin/sh
- exec /usr/local/sbin/radiusd -s -f
+Of course you'll want to make that 'run' file executable::
- Of course you'll want to make that 'run' file executable:
+ $ chmod +x /var/svc/radiusd/run
- # chmod +x /var/svc/radiusd/run
+Note, you *MUST* use the '-f' option when supervising. That option
+tells radiusd not to detach from the tty when starting. If you don't
+use that option, the daemontools will always think that radiusd has
+just died and will (try to) restart it. Not good.
- Note, you *MUST* use the '-f' option when supervising. That option
- tells radiusd not to detach from the tty when starting. If you don't
- use that option, the daemontools will always think that radiusd has
- just died and will (try to) restart it. Not good.
+Now the only left to do is to start the 'supervise' command that came
+with daemontools. Do that like so::
- Now the only left to do is to start the 'supervise' command that
- came with daemontools. Do that like so:
+ $ supervise /var/svc/radiusd
- # supervise /var/svc/radiusd
+Maintenance With Daemontools
+----------------------------
-2. MAINTENANCE WITH DAEMONTOOLS
+ Any maintenance you need to do with almost certainly be done with the
+ 'svc' program in the deamontools package. i.e.::
- Any maintenance you need to do with almost certainly be done with the
- 'svc' program in the deamontools package. Ie:
+ Shutdown radiusd:
+ $ svc -d /var/svc/radiusd
+
+ Start it back up:
+ $ svc -u /var/svc/radiusd
+
+ Send HUP to radiusd:
+ $ svc -h /var/svc/radiusd
+
+ Shutdown and stop supervising radiusd:
+ $ svc -dx /var/svc/radiusd
- Shutdown radiusd:
- # svc -d /var/svc/radiusd
+Supervising With Inittab
+------------------------
- Start it back up:
- # svc -u /var/svc/radiusd
+This is really pretty easy, but it is system dependent. I strongly
+suggest you read the man pages for your 'init' before playing with
+this. You can seriously hose your system if you screw up your
+inittab.
+
+Add this line (or something similar to it) to your inittab::
- Send HUP to radiusd:
- # svc -h /var/svc/radiusd
+ fr:23:respawn:/usr/local/sbin/radiusd -f -s &> /dev/null
- Shutdown and stop supervising radiusd:
- # svc -dx /var/svc/radiusd
+Now all that's left is to have the system reread the inittab. Usually
+that's done with one of the following::
-3. SUPERVISING WITH INITTAB
+ $ telinit Q
- This is really pretty easy, but it is system dependent. I strongly
- suggest you read the man pages for your 'init' before playing with
- this. You can seriously hose your system if you screw up your
- inittab.
-
- Add this line (or something similar to it) to your inittab:
+or::
- fr:23:respawn:/usr/local/sbin/radiusd -f -s &> /dev/null
+ $ init q
- Now all that's left is to have the system reread the inittab. Usually
- that's done with one of the following:
+Now you should see a 'radiusd' process when you issue a 'ps'. If you
+don't, try to run the radiusd command you put in inittab manually. If
+it works, that means you didn't tell the system to reread inittab
+properly. If it doesn't work, that means your radius start command is
+bad and you need to fix it.
- # telinit Q
- <or>
- # init q
+Acknowledgements
+----------------
- Now you should see a 'radiusd' process when you issue a 'ps'. If you
- don't, try to run the radiusd command you put in inittab manually.
- If it works, that means you didn't tell the system to reread inittab
- properly. If it doesn't work, that means your radius start command
- is bad and you need to fix it.
+ Document author : Jeff Carneal
+ daemontools auther : Dan Bernstein
+ Further daemontool notes (below): Antonio Dias
+ Radwatch note : Andrey Melnikov
-4. ACKNOWLEDGEMENTS
-
- Document author: Jeff Carneal
- daemontools auther: Dan Bernstein
- Further daemontool notes (below): Antonio Dias
- Radwatch note: Andrey Melnikov
+Further Daemontools notes
+=========================
-5. FURTHER DAEMONTOOLS NOTES
+Here are some notes by Antonia Dias sent to the free radius mailing
+list. Some of you may find this useful after reading the above and the
+docs for daemontools.
- Here are some notes by Antonia Dias sent to the free radius mailing list.
- Some of you may find this useful after reading the above and the docs for
- daemontools.
-
- -------------------------------------------------------------------------
-
- daemontools instructions
-
- I am running radiusd under supervise from daemontools without problems.
- The only thing I am missing right now is an option to force radiusd to
- send log to stderr so I can manage logs better with multilog (also
- included in daemontools package). Here is the procedure I've been
- following (for Cistron RADIUS):
-
- root@storm:~> groupadd log
- root@storm:~> useradd -g log log
- root@storm:~> mkdir /etc/radiusd
- root@storm:~> mkdir /etc/radiusd/log
- root@storm:~> mkdir /etc/radiusd/log/main
- root@storm:~> chmod +t+s /etc/radiusd /etc/radiusd/log
- root@storm:~> chown log.log /etc/radiusd/log/main
+Daemontools Instructions
+------------------------
- Here are the contents of run files from /etc/radiusd and /etc/radiusd/log
+I am running radiusd under supervise from daemontools without
+problems. The only thing I am missing right now is an option to force
+radiusd to send log to stderr so I can manage logs better with
+multilog (also included in daemontools package). Here is the procedure
+I've been following (for Cistron RADIUS)::
+
+ $ groupadd log
+ $ useradd -g log log
+ $ mkdir /etc/radiusd
+ $ mkdir /etc/radiusd/log
+ $ mkdir /etc/radiusd/log/main
+ $ chmod +t+s /etc/radiusd /etc/radiusd/log
+ $ chown log.log /etc/radiusd/log/main
- root@storm:~> cd /etc/radiusd
- root@storm:/etc/radiusd> cat run
- #!/bin/sh
- exec 2>&1
- exec /usr/sbin/radiusd -fyzx
- root@storm:/etc/radiusd> cd /etc/radiusd/log
- root@storm:/etc/radiusd/log> cat run
- #!/bin/sh
- exec setuidgid log multilog t ./main
+Here are the contents of run files from '/etc/radiusd' and '/etc/radiusd/log'::
+
+ $ cd /etc/radiusd
+ $ cat run
+ #!/bin/sh
+ exec 2>&1
+ exec /usr/sbin/radiusd -fyzx
+ $ cd /etc/radiusd/log
+ $ cat run
+ #!/bin/sh
+ exec setuidgid log multilog t ./main
- To make service wake-up do:
- root@storm:~> ln -sf /etc/radiusd /service
-
- Hang-up (to reload config) it using:
- root@storm:~> svc -h /service/radiusd
-
- Disable (down) it using:
- root@storm:~> svc -d /service/radiusd
+ To make service wake-up do::
+
+ $ ln -sf /etc/radiusd /service
- Reenable (up) it using:
- root@storm:~> svc -u /service/radiusd
+ Hang-up (to reload config) it using::
+
+ $ svc -h /service/radiusd
- --
- Antonio Dias
+Disable (down) it using::
+
+ $ svc -d /service/radiusd
+Reenable (up) it using::
+
+ $ svc -u /service/radiusd
projects / freeradius.git / commitdiff