All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
modules.h
Go to the documentation of this file.
1 /*
2  * This program is free software; you can redistribute it and/or modify
3  * it under the terms of the GNU General Public License as published by
4  * the Free Software Foundation; either version 2 of the License, or
5  * (at your option) any later version.
6  *
7  * This program is distributed in the hope that it will be useful,
8  * but WITHOUT ANY WARRANTY; without even the implied warranty of
9  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
10  * GNU General Public License for more details.
11  *
12  * You should have received a copy of the GNU General Public License
13  * along with this program; if not, write to the Free Software
14  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
15  */
16 #ifndef _FR_MODULES_H
17 #define _FR_MODULES_H
18 /**
19  * $Id: 04e1618633db734ed80fb9f89782cf2056fbf84e $
20  *
21  * @file include/modules.h
22  * @brief Interface to the RADIUS module system.
23  *
24  * @copyright 2013 The FreeRADIUS server project
25  */
26 RCSIDH(modules_h, "$Id: 04e1618633db734ed80fb9f89782cf2056fbf84e $")
27 
28 #include <freeradius-devel/conffile.h>
29 #include <freeradius-devel/features.h>
30 #include <freeradius-devel/connection.h>
31 
32 #ifdef __cplusplus
33 extern "C" {
34 #endif
35 
36 /** The different section components of the server
37  *
38  * Used as indexes in the methods array in the module_t struct.
39  */
40 typedef enum rlm_components {
41  MOD_AUTHENTICATE = 0, //!< 0 methods index for authenticate section.
42  MOD_AUTHORIZE, //!< 1 methods index for authorize section.
43  MOD_PREACCT, //!< 2 methods index for preacct section.
44  MOD_ACCOUNTING, //!< 3 methods index for accounting section.
45  MOD_SESSION, //!< 4 methods index for checksimul section.
46  MOD_PRE_PROXY, //!< 5 methods index for preproxy section.
47  MOD_POST_PROXY, //!< 6 methods index for postproxy section.
48  MOD_POST_AUTH, //!< 7 methods index for postauth section.
49 #ifdef WITH_COA
50  MOD_RECV_COA, //!< 8 methods index for recvcoa section.
51  MOD_SEND_COA, //!< 9 methods index for sendcoa section.
52 #endif
53  MOD_COUNT //!< 10 how many components there are.
55 
56 extern const FR_NAME_NUMBER mod_rcode_table[];
57 
58 /** Map a section name, to a section typename, to an attribute number
59  *
60  * Used by modules.c to define the mappings between names, types and control
61  * attributes.
62  */
63 typedef struct section_type_value_t {
64  char const *section; //!< Section name e.g. "Authorize".
65  char const *typename; //!< Type name e.g. "Auth-Type".
66  int attr; //!< Attribute number.
68 
69 /** Mappings between section names, typenames and control attributes
70  *
71  * Defined in modules.c.
72  */
74 
75 #define RLM_TYPE_THREAD_SAFE (0 << 0) //!< Module is threadsafe.
76 #define RLM_TYPE_THREAD_UNSAFE (1 << 0) //!< Module is not threadsafe.
77  //!< Server will protect calls
78  //!< with mutex.
79 #define RLM_TYPE_HUP_SAFE (1 << 2) //!< Will be restarted on HUP.
80  //!< Server will instantiated
81  //!< new instance, and then
82  //!< destroy old instance.
83 
84 
85 /* Stop people using different module/library/server versions together */
86 #define RLM_MODULE_INIT RADIUSD_MAGIC_NUMBER
87 
88 /** Module section callback
89  *
90  * Is called when the module is listed in a particular section of a virtual
91  * server, and the request has reached the module call.
92  *
93  * @param[in] instance created in instantiated, holds module config.
94  * @param[in,out] request being processed.
95  * @return the appropriate rcode.
96  */
97 typedef rlm_rcode_t (*packetmethod)(void *instance, REQUEST *request);
98 
99 /** Module instantiation callback
100  *
101  * Is called once per module instance. Is not called when new threads are
102  * spawned. Modules that require separate thread contexts should use the
103  * connection pool API.
104  *
105  * @param[in] mod_cs Module instance's configuration section.
106  * @param[out] instance Module instance's configuration structure, should be
107  * alloced by by callback and freed by detach.
108  * @return
109  * - 0 on success.
110  * - -1 if instantiation failed.
111  */
112 typedef int (*instantiate_t)(CONF_SECTION *mod_cs, void *instance);
113 
114 /** Module detach callback
115  *
116  * Is called just before the server exits, and after re-instantiation on HUP,
117  * to free the old module instance.
118  *
119  * Detach should close all handles associated with the module instance, and
120  * free any memory allocated during instantiate.
121  *
122  * @param[in] instance to free.
123  * @return
124  * - 0 on success.
125  * - -1 if detach failed.
126  */
127 typedef int (*detach_t)(void *instance);
128 
129 /** Metadata exported by the module
130  *
131  * This determines the capabilities of the module, and maps internal functions
132  * within the module to different sections.
133  */
134 typedef struct module_t {
135  uint64_t magic; //!< Used to validate module struct.
136  char const *name; //!< The name of the module (without rlm_ prefix).
137  int type; //!< One or more of the RLM_TYPE_* constants.
138  size_t inst_size; //!< Size of the instance data
139  CONF_PARSER const *config; //!< Configuration information
140  instantiate_t bootstrap; //!< register dynamic attrs, etc.
141  instantiate_t instantiate; //!< Function to use for instantiation.
142  detach_t detach; //!< Function to use to free module instance.
143  packetmethod methods[MOD_COUNT]; //!< Pointers to the various section functions.
144 } module_t;
145 
146 
147 /*
148  * Share connection pool instances between modules
149  */
151  void *opaque,
154  char const *prefix);
155 
156 /*
157  * Create free and destroy module instances
158  */
161 int modules_free(void);
162 int modules_hup(CONF_SECTION *modules);
163 
164 /*
165  * Call various module sections
166  */
167 rlm_rcode_t process_authorize(int type, REQUEST *request);
168 rlm_rcode_t process_authenticate(int type, REQUEST *request);
170 rlm_rcode_t process_accounting(int type, REQUEST *request);
171 int process_checksimul(int type, REQUEST *request, int maxsimul);
172 rlm_rcode_t process_pre_proxy(int type, REQUEST *request);
173 rlm_rcode_t process_post_proxy(int type, REQUEST *request);
174 rlm_rcode_t process_post_auth(int type, REQUEST *request);
175 
176 #ifdef WITH_COA
177 rlm_rcode_t process_recv_coa(int type, REQUEST *request);
178 rlm_rcode_t process_send_coa(int type, REQUEST *request);
179 # define MODULE_NULL_COA_FUNCS ,NULL,NULL
180 #else
181 # define MODULE_NULL_COA_FUNCS
182 #endif
183 
185 
188 
189 #ifdef __cplusplus
190 }
191 #endif
192 #endif /* _FR_MODULES_H */
5 methods index for preproxy section.
Definition: modules.h:46
#define RCSIDH(h, id)
Definition: build.h:136
int(* detach_t)(void *instance)
Module detach callback.
Definition: modules.h:127
rlm_rcode_t process_authorize(int type, REQUEST *request)
Definition: modules.c:2098
packetmethod methods[MOD_COUNT]
Pointers to the various section functions.
Definition: modules.h:143
int attr
Attribute number.
Definition: modules.h:66
struct section_type_value_t section_type_value_t
Map a section name, to a section typename, to an attribute number.
Metadata exported by the module.
Definition: modules.h:134
rlm_rcode_t process_send_coa(int type, REQUEST *request)
Definition: modules.c:2189
int(* fr_connection_alive_t)(void *opaque, void *connection)
Check a connection handle is still viable.
Definition: connection.h:113
CONF_PARSER const * config
Configuration information.
Definition: modules.h:139
7 methods index for postauth section.
Definition: modules.h:48
rlm_rcode_t process_post_auth(int type, REQUEST *request)
Definition: modules.c:2178
int virtual_servers_init(CONF_SECTION *config)
Definition: modules.c:1577
int(* instantiate_t)(CONF_SECTION *mod_cs, void *instance)
Module instantiation callback.
Definition: modules.h:112
rlm_rcode_t indexed_modcall(rlm_components_t comp, int idx, REQUEST *request)
Definition: modules.c:908
int modules_hup(CONF_SECTION *modules)
Definition: modules.c:1691
rlm_rcode_t process_recv_coa(int type, REQUEST *request)
Definition: modules.c:2184
int virtual_servers_bootstrap(CONF_SECTION *config)
Definition: modules.c:1457
Defines a CONF_PAIR to C data type mapping.
Definition: conffile.h:267
struct module_t module_t
Metadata exported by the module.
instantiate_t instantiate
Function to use for instantiation.
Definition: modules.h:141
const FR_NAME_NUMBER mod_rcode_table[]
Definition: modcall.c:186
int modules_init(CONF_SECTION *)
Instantiate the modules.
Definition: modules.c:2064
fr_connection_pool_t * module_connection_pool_init(CONF_SECTION *module, void *opaque, fr_connection_create_t c, fr_connection_alive_t a, char const *prefix)
Initialise a module specific connection pool.
Definition: modules.c:1759
static int comp(void const *a, void const *b)
Definition: rbmonkey.c:44
rlm_rcode_t process_authenticate(int type, REQUEST *request)
Definition: modules.c:2106
4 methods index for checksimul section.
Definition: modules.h:45
3 methods index for accounting section.
Definition: modules.h:44
rlm_rcode_t process_accounting(int type, REQUEST *request)
Definition: modules.c:2123
const section_type_value_t section_type_value[]
Mappings between section names, typenames and control attributes.
Definition: modules.c:64
rlm_rcode_t process_pre_proxy(int type, REQUEST *request)
Definition: modules.c:2161
rlm_rcode_t process_post_proxy(int type, REQUEST *request)
Definition: modules.c:2169
0 methods index for authenticate section.
Definition: modules.h:41
enum rlm_rcodes rlm_rcode_t
Return codes indicating the result of the module call.
detach_t detach
Function to use to free module instance.
Definition: modules.h:142
rlm_rcode_t module_preacct(REQUEST *request)
Definition: modules.c:2115
10 how many components there are.
Definition: modules.h:53
static char const * prefix
Definition: mainconfig.c:81
uint64_t magic
Used to validate module struct.
Definition: modules.h:135
rlm_rcode_t(* packetmethod)(void *instance, REQUEST *request)
Module section callback.
Definition: modules.h:97
size_t inst_size
Size of the instance data.
Definition: modules.h:138
int process_checksimul(int type, REQUEST *request, int maxsimul)
Definition: modules.c:2135
enum rlm_components rlm_components_t
The different section components of the server.
int type
One or more of the RLM_TYPE_* constants.
Definition: modules.h:137
A connection pool.
Definition: connection.c:85
rlm_components
The different section components of the server.
Definition: modules.h:40
int modules_free(void)
Definition: modules.c:413
int modules_bootstrap(CONF_SECTION *)
Definition: modules.c:1866
6 methods index for postproxy section.
Definition: modules.h:47
2 methods index for preacct section.
Definition: modules.h:43
char const * name
The name of the module (without rlm_ prefix).
Definition: modules.h:136
8 methods index for recvcoa section.
Definition: modules.h:50
Map a section name, to a section typename, to an attribute number.
Definition: modules.h:63
9 methods index for sendcoa section.
Definition: modules.h:51
1 methods index for authorize section.
Definition: modules.h:42
instantiate_t bootstrap
register dynamic attrs, etc.
Definition: modules.h:140
void *(* fr_connection_create_t)(TALLOC_CTX *ctx, void *opaque, struct timeval const *timeout)
Create a new connection handle.
Definition: connection.h:98
char const * section
Section name e.g. "Authorize".
Definition: modules.h:64