doc/module_interface

   1
   2 RLM Module Interface (for developers)
   3 -------------------------------------
   4
   5 Section 1 - overview
   6
   7 The fundamental concepts of the rlm interface are module, instance, and
   8 component.
   9
  10 A module is a chunk of code that knows how to deal with a particular kind of
  11 database, or perhaps a collection of similar databases. Examples:
  12
  13   - rlm_sql contains code for talking to MySQL or Postgres, and for mapping
  14     RADIUS records onto SQL tables.
  15   - rlm_unix contains code for making radiusd fit in well on unix-like
  16     systems, including getpw* authentication and utmp/wtmp-style logging.
  17
  18 An instance specifies the actual location of a collection data that can be
  19 used by a module. Examples:
  20
  21   - /var/log/radutmp
  22   - "the MySQL database on bigserver.theisp.com.example"
  23
  24 A module can have up to 4 (soon to be 5? 6?) components which act on RADIUS
  25 requests at different stages. The components are:
  26
  27   - authorization: check that a user exists, decide on an authentication
  28     method or proxy realm, and possibly apply some attributes to be returned
  29     in the reply packet.
  30   - authentication: verify that the password is correct.
  31   - preaccounting: decide whether to proxy the request, and possibly add
  32     attributes that should be included in any logs
  33   - accounting: record the request in the log
  34   - checksimul (AVAILABLE AS EXTERNAL PATCH): count the number of active
  35     sessions for the user
  36   - postproxyauth (DOES NOT EXIST YET): filter attributes from a reply to a
  37     proxied request
  38
  39 A module declares which components it supports by putting function pointers
  40 in its "module_t rlm_*" structure.
  41
  42 Section 2 - Module configuration:
  43
  44 The administrator requests the creation of a module instance by adding it
  45 inside the modules{} block in radiusd.conf. The instance definition looks
  46 like this:
  47
  48   module_name [instance_name] {
  49     param1 = value1
  50     param2 = value2
  51     param3 = value3
  52     ...
  53   }
  54
  55 The module_name is used to load the module. To see the names of the available
  56 modules, look for the rlm_*.so files in $installprefix/lib. The module_name
  57 is that, minus the rlm_ and the .so.
  58
  59 instance_name is an identifier for distinguishing multiple instances of the
  60 same module. If you are only loading a module once, you can leave out the
  61 instance_name and it will be assumed to be the same as the module_name.
  62
  63 The parameters inside the module block are passed without interpretation to
  64 the module and generally point to the exact location of a database or enable
  65 optional features of the module. Each module should document what parameters
  66 it accepts and what they do.
  67
  68 For each Access-Request that comes to the server, the authorize{} block is
  69 called. Then one of the authtype{} blocks from authenticate{} is called,
  70 depending on the Auth-Type attribute that was chosen by authorize{}. If
  71 authorize{} set the Proxy-To-Realm attribute, then proxying takes over and
  72 the local authenticate{} phase is skipped.
  73
  74 For each Accounting-Request that comes to the server, the preacct{} block is
  75 called, followed by the accounting{} block. accounting{} is skipped if
  76 preacct{} sets Proxy-To-Realm.
  77
  78 For an explanation of what "calling" a config block means, see
  79 README.failover.
  80
  81 Section 3 - The lifetime of a module
  82
  83 When the server is starting up, or reinitializing itself as a result of a
  84 SIGHUP, it reads the modules{} section. Each configured module will be loaded
  85 and its init() method will be called.
  86
  87   int init(void)
  88
  89 The init() method should take care of
  90 any setup that is not tied to a specific instance. It will only be called
  91 once, even if there are multiple instances configured.
  92
  93 For each configured instance, after the init() method, the instantiate()
  94 method is called. It is given a handle to the configuration block holding its
  95 parameters, which it can access with cf_section_parse().
  96
  97   int instantiate(CONF_SECTION *cs, void **instance)
  98
  99 The instantiate() function should look up options in the config section, and
 100 open whatever files or network connections are necessary for the module to do
 101 its job. It also should create a structure holding all of the persistent
 102 variables that are particular to this instance (open file descriptors,
 103 configured pathnames, etc.) and store a pointer to it in *instance. That
 104 void * becomes a handle (some would call it a "cookie") representing this
 105 instance. The instance handle is passed as a parameter in all subsequent
 106 calls to the module's methods, so they can determine which database they are
 107 supposed to act on.
 108
 109 The authorize(), authenticate(), preaccounting(), and accounting() functions
 110 are all called the same way:
 111
 112   int authorize(void *instance, REQUEST *request)
 113   int authenticate(void *instance, REQUEST *request)
 114   int preaccounting(void *instance, REQUEST *request)
 115   int accounting(void *instance, REQUEST *request)
 116
 117 they each receive the instance handle and the request, and are expected to
 118 act on the request using the database pointed to by the instance handle
 119 (which was set by the instantiate() function).
 120
 121 When the server is being shut down (as the first part of SIGHUP for example)
 122 detach() is called for each module instance.
 123
 124   int detach(void *instance)
 125
 126 The detach() method should release whatever resources were allocated by the
 127 instantiate() method.
 128
 129 After all instances are detached, the destroy() method is called.
 130
 131   int destroy(void)
 132
 133 It should release resources that were acquired by the init() method.
 134
 135 See also src/modules/README for more information.
 136
 137 --Alan Curry <pacman@world.std.com>