 |
The FreeRADIUS server
$Id: 15bac2a4c627c01d1aa2047687b3418955ac7f00 $
|
|
The FreeRADIUS server
$Id: 15bac2a4c627c01d1aa2047687b3418955ac7f00 $
|
Interface to the FreeRADIUS module system. More...
#include <freeradius-devel/server/module_ctx.h>#include <freeradius-devel/server/rcode.h>#include <freeradius-devel/server/request.h>#include <freeradius-devel/features.h>#include <freeradius-devel/io/schedule.h>#include <freeradius-devel/server/cf_util.h>#include <freeradius-devel/server/dl_module.h>#include <freeradius-devel/server/exfile.h>#include <freeradius-devel/server/pool.h>#include <freeradius-devel/server/section.h>#include <freeradius-devel/unlang/action.h>#include <freeradius-devel/unlang/call_env.h>#include <freeradius-devel/unlang/mod_action.h>#include <freeradius-devel/util/event.h>
Include dependency graph for module.h:Go to the source code of this file.
Data Structures | |
| struct | module_data_pool_t |
| struct | module_instance_s |
| Module instance data. More... | |
| struct | module_list_s |
| A list of modules. More... | |
| struct | module_method_binding_s |
| Named methods exported by a module. More... | |
| struct | module_method_group_s |
| A group of methods exported by a module or added as an overlay. More... | |
| struct | module_s |
| Struct exported by a rlm_* module. More... | |
| struct | module_state_func_table_s |
| Map string values to module state method. More... | |
| struct | module_thread_instance_s |
| Per thread per instance data. More... | |
Macros | |
| #define | MODULE_BINDING_TERMINATOR { .section = NULL } |
| Terminate a module binding list. More... | |
| #define | MODULE_INSTANCE_LEN_MAX 256 |
| The maximum size of a module instance. More... | |
Enumerations | |
| enum | module_flags_t { MODULE_TYPE_THREAD_UNSAFE = (1 << 0) , MODULE_TYPE_RETRY = (1 << 2) , MODULE_TYPE_DYNAMIC_UNSAFE = (1 << 3) } |
| enum | module_instance_state_t { MODULE_INSTANCE_BOOTSTRAPPED = (1 << 1) , MODULE_INSTANCE_INSTANTIATED = (1 << 2) , MODULE_INSTANCE_NO_THREAD_INSTANTIATE = (1 << 3) } |
| What state the module instance is currently in. More... | |
Functions | |
| module_list_t * | module_list_alloc (TALLOC_CTX *ctx, module_list_type_t const *type, char const *name, bool write_protect)) |
| Allocate a new module list. More... | |
| void | modules_init (char const *lib_dir) |
| Perform global initialisation for modules. More... | |
Module and module thread initialisation and instantiation | |
| int | module_bootstrap (module_instance_t *mi) |
| Manually complete module bootstrap by calling its instantiate function. More... | |
| module_instance_t * | module_instance_alloc (module_list_t *ml, module_instance_t const *parent, dl_module_type_t type, char const *mod_name, char const *inst_name, module_instance_state_t init_state)) |
| Allocate a new module and add it to a module list for later bootstrap/instantiation. More... | |
| bool const | module_instance_allowed_chars [UINT8_MAX+1] |
| Chars that are allowed in a module instance name. More... | |
| module_instance_t * | module_instance_copy (module_list_t *dst, module_instance_t const *src, char const *inst_name)) |
| Duplicate a module instance, placing it in a new module list. More... | |
| fr_slen_t | module_instance_name_valid (char const *inst_name) |
| Check to see if a module instance name is valid. More... | |
| void | module_instance_uctx_set (module_instance_t *mi, void *uctx) |
| Set the uctx pointer for a module instance. More... | |
| int | module_instantiate (module_instance_t *mi) |
| Manually complete module setup by calling its instantiate function. More... | |
| int | module_thread_instantiate (TALLOC_CTX *ctx, module_instance_t *mi, fr_event_list_t *el) |
| Allocate thread-local instance data for a module. More... | |
| int | modules_bootstrap (module_list_t const *ml) |
| Bootstrap any modules which have not been bootstrapped already. More... | |
| int | modules_instantiate (module_list_t const *ml) |
| Completes instantiation of modules. More... | |
| void | modules_thread_detach (module_list_t *ml) |
| Remove thread-specific data for a given module list. More... | |
| int | modules_thread_instantiate (TALLOC_CTX *ctx, module_list_t const *ml, fr_event_list_t *el) |
| Creates per-thread instance data for modules which need it. More... | |
Module list variants | |
These are passed to the module_list_alloc function to allocate lists of different types Global module lists are used for backend modules, listeners, and process state machines. Thread-local lists are usually runtime instantiated variants of modules, or modules that represent client connections. One major difference (from the module's perspective) is that bootstrap is not called for thread-local modules. | |
| module_list_type_t const | module_list_type_global |
| Initialise a global module, with thread-specific data. More... | |
| module_list_type_t const | module_list_type_thread_local |
| Initialise a thread-local module, which is only used in a single thread. More... | |
Callbacks for the conf_parser_t | |
| int | module_submodule_parse (UNUSED TALLOC_CTX *ctx, void *out, void *parent, CONF_ITEM *ci, UNUSED conf_parser_t const *rule) |
Debugging functions | |
| void | module_instance_debug (module_instance_t const *mi) |
| Print debugging information for a module. More... | |
| void | module_list_debug (module_list_t const *ml) |
| Print the contents of a module list. More... | |
Toggle protection on module instance data | |
This is used for module lists which implement additional instantiation phases (like li->open). It should NOT be used by modules to hack around instance data being read-only after instantiation completes. | |
| int | module_instance_data_protect (module_instance_t const *mi) |
| Mark module data as read only. More... | |
| int | module_instance_data_unprotect (module_instance_t const *mi) |
| Mark module data as read/write. More... | |
Module and module thread lookup | |
| module_instance_t * | module_instance_by_data (module_list_t const *ml, void const *data) |
| Find an existing module instance by its private instance data. More... | |
| module_instance_t * | module_instance_by_name (module_list_t const *ml, module_instance_t const *parent, char const *asked_name)) |
| Find an existing module instance by its name and parent. More... | |
| int | module_instance_conf_parse (module_instance_t *mi, CONF_SECTION *conf) |
| Covert a CONF_SECTION into parsed module instance data. More... | |
| fr_slen_t | module_instance_name_from_conf (char const **name, CONF_SECTION *conf) |
| Avoid boilerplate when setting the module instance name. More... | |
| module_instance_t * | module_instance_root (module_instance_t const *child) |
| Find the module's shallowest parent. More... | |
| char const * | module_instance_root_prefix_str (module_instance_t const *mi) |
| Return the prefix string for the deepest module. More... | |
| static module_thread_instance_t * | module_thread (module_instance_t const *mi) |
| Retrieve module/thread specific instance for a module. More... | |
| module_thread_instance_t * | module_thread_by_data (module_list_t const *ml, void const *data) |
| Retrieve module/thread specific instance data for a module. More... | |
Control which phases are skipped (if any) | |
| bool | module_instance_skip_bootstrap (module_instance_t *mi) |
| Should we bootstrap this module instance? More... | |
| bool | module_instance_skip_instantiate (module_instance_t *mi) |
| Should we instantiate this module instance? More... | |
| bool | module_instance_skip_thread_instantiate (module_instance_t *mi) |
| Should we instantiate this module instance in a new thread? More... | |
| void | module_list_mask_set (module_list_t *ml, module_instance_state_t mask) |
| Set a new bootstrap/instantiate state for a list. More... | |
Interface to the FreeRADIUS module system.
Definition in file module.h.
| struct module_data_pool_t |
| struct module_instance_s |
Module instance data.
Per-module-instance data structure to correlate the modules with the instance names (may NOT be the module names!), and the per-instance data structures.
Collaboration diagram for module_instance_s:| Data Fields | ||
|---|---|---|
| unlang_mod_actions_t | actions | default actions and retries. |
| void * | boot | Data allocated during the boostrap phase. |
| module_data_pool_t | boot_pool | Data to allow mprotect state toggling for bootstrap data. |
| rlm_rcode_t | code | Code module will return when 'force' has has been set to true. |
| CONF_SECTION * | conf | Module's instance configuration. |
| void * | data |
Module's instance data. This is most frequently accessed, so comes first. |
| fr_rb_node_t | data_node | Entry in the data tree. |
| module_t * | exported |
Public module structure. Cached for convenience. This exports module methods, i.e. the functions which allow the module to perform actions. This is an identical address to module->common, but with a different type, containing additional instance callbacks to make it easier to use. |
| bool | force |
Force the module to return a specific code. Usually set via an administrative interface. |
| module_data_pool_t | inst_pool | Data to allow mprotect state toggling for instance data. |
| module_list_t * | ml | Module list this instance belongs to. |
| dl_module_t * | module |
Dynamic loader handle. Contains the module's dlhandle, and the functions it exports. The dl_module is reference counted so that it can be freed automatically when the last instance is freed. This will also (usually) unload the .so or .dylib. |
| pthread_mutex_t | mutex | Used prevent multiple threads entering a thread unsafe module simultaneously. |
| char const * | name | Instance name e.g. user_database. |
| fr_rb_node_t | name_node | Entry in the name tree. |
| uint32_t | number |
Unique module number. Used to assign a stable number to each module instance. |
| module_instance_t const * | parent | Parent module's instance (if any). |
| module_instance_state_t | state | What's been done with this module so far. |
| void * | uctx | Extra data passed to module_instance_alloc. |
| struct module_list_s |
A list of modules.
This used to be a global structure, but was move to a struct.
Module lists allow collections of modules to be created. The module lists themselves can be configured to be thread-local or global, with optional runtime write protection.
Thread-local module lists are used for dynamic modules, i.e. those created at runtime, where as the global module lists are used for backend modules, listeners, and process state machines.
Collaboration diagram for module_list_s:| Data Fields | ||
|---|---|---|
| fr_rb_tree_t * | data_tree | Modules indexed by data. |
| fr_heap_t * | inst_heap | Heap of module instances. |
| uint32_t | last_number | Last identifier assigned to a module instance. |
| module_instance_state_t | mask | Prevent phases from being executed. |
| char const * | name | Friendly list identifier. |
| fr_rb_tree_t * | name_tree | Modules indexed by name. |
| module_list_thread_data_get_t | thread_data_get |
Callback to get thread-specific data. Copy of type->thread_data_get. |
| module_list_type_t const * | type | Type of module list. |
| bool | write_protect | If true, pages containing module boot or instance data will be write protected after bootstrapping and instantiation is complete, to prevent accidental modification. |
| struct module_method_binding_s |
Collaboration diagram for module_method_binding_s:| Data Fields | ||
|---|---|---|
| fr_dlist_t | entry |
Linked list of bindings with the same name1. Allows us to more quickly iterate over all name2 entries after finding a matching name1. This is also temporarily used to verify the ordering of name bindings. DO NOT INITIALISE IN THE MODULE. |
| module_method_t | method | Module method to call. |
| call_env_method_t const * | method_env | Method specific call_env. |
| fr_dlist_head_t | same_name1 |
List of bindings with the same name1. Only initialised for the the first name1 binding. DO NOT INITIALISE IN THE MODULE. |
| section_name_t const * | section | Identifier for a section. |
| struct module_method_group_s |
A group of methods exported by a module or added as an overlay.
Module method groups are organised into a linked list, with each group containing a list of named methods. This allows common collections of methods to be added to a module.
One common use case is adding the instantiate, exists, and detach methods which are added to dynamic modules, and allow dynamic module instances to be created and destroyed at runtime.
Collaboration diagram for module_method_group_s:| Data Fields | ||
|---|---|---|
| module_method_binding_t * | bindings | named methods |
| module_method_group_t * | next | Next group in the list. |
| bool | validated | Set to true by module_method_group_validate. |
| struct module_s |
Struct exported by a rlm_* module.
Determines the capabilities of the module, and maps internal functions within the module to different sections.
Collaboration diagram for module_s:| Data Fields | ||
|---|---|---|
| size_t | boot_size | Size of the module's bootstrap data. |
| char const * | boot_type | talloc type to assign to bootstrap data. |
| module_instantiate_t | bootstrap |
Callback to allow the module to register any global resources like xlat functions and attributes. Instance data is read only during the bootstrap phase and MUST NOT be modified. Any attributes added during this phase that the module need to be re-resolved during the instantiation phase so that dynamic modules (which don't run bootstrap) work correctly.
|
| conf_parser_t const * | config | How to convert a CONF_SECTION to a module instance. |
| module_detach_t | detach | Clean up module resources from the instantiation pahses. |
| DL_MODULE_COMMON | Common fields for all loadable modules. | |
| module_flags_t | flags | Flags that control how a module starts up and how a module is called. |
| size_t | inst_size | Size of the module's instance data. |
| char const * | inst_type | talloc type to assign to instance data. |
| module_instantiate_t | instantiate |
Callback to allow the module to register any per-instance resources like sockets and file handles. After instantiate completes the module instance data is mprotected to prevent modification. |
| module_thread_detach_t | thread_detach | Callback to free thread-specific resources associated < with a module. |
| size_t | thread_inst_size | Size of the module's thread-specific instance data. |
| char const * | thread_inst_type | talloc type to assign to thread instance data. |
| module_thread_instantiate_t | thread_instantiate |
Callback to populate a new module thread instance data. Called once per thread. |
| module_detach_t | unstrap | Clean up module resources from both the bootstrap phase. |
| struct module_state_func_table_s |
Collaboration diagram for module_state_func_table_s:| Data Fields | ||
|---|---|---|
| module_method_t | func | State function. |
| char const * | name | String identifier for state. |
| struct module_thread_instance_s |
Per thread per instance data.
Stores module and thread specific data.
Collaboration diagram for module_thread_instance_s:| Data Fields | ||
|---|---|---|
| uint64_t | active_callers | total number of times we've been called |
| void * | data | Thread specific instance data. |
| fr_event_list_t * | el | Event list associated with this thread. |
| fr_heap_index_t | inst_idx |
Entry in the thread-specific bootstrap heap. Should be an identical value to the global instance data for the same module. |
| module_instance_t * | mi | As opposed to the thread local inst. |
| uint64_t | total_calls | |
| #define MODULE_BINDING_TERMINATOR { .section = NULL } |
| #define MODULE_INSTANCE_LEN_MAX 256 |
| typedef int(* module_detach_t) (module_detach_ctx_t const *inst) |
Module detach callback.
Is called just before the server exits, and after re-instantiation on HUP, to free the old module instance.
Detach should close all handles associated with the module instance, and free any memory allocated during instantiate.
| [in] | inst | to free. |
| typedef struct module_instance_s module_instance_t |
| typedef int(* module_instantiate_t) (module_inst_ctx_t const *mctx) |
| typedef struct module_list_s module_list_t |
| typedef module_thread_instance_t*(* module_list_thread_data_get_t) (module_instance_t const *mi) |
Callback to retrieve thread-local data for a module.
This is public for performance reasons, and should be called through module_thread.
| [in] | mi | to add data to (use mi->ml for the module list). |
| typedef struct module_list_type_s module_list_type_t |
| typedef struct module_method_binding_s module_method_binding_t |
| typedef struct module_method_group_s module_method_group_t |
| typedef unlang_action_t(* module_method_t) (rlm_rcode_t *p_result, module_ctx_t const *mctx, request_t *request) |
Module section callback.
Is called when the module is listed in a particular section of a virtual server, and the request has reached the module call.
| [out] | p_result | Result code of the module method. |
| [in] | mctx | Holds global instance data, thread instance data and call specific instance data. |
| [in] | request | to process. |
| typedef struct module_state_func_table_s module_state_func_table_t |
| typedef int(* module_thread_detach_t) (module_thread_inst_ctx_t const *mctx) |
| typedef struct module_thread_instance_s module_thread_instance_t |
| typedef int(* module_thread_instantiate_t) (module_thread_inst_ctx_t const *mctx) |
| enum module_flags_t |
What state the module instance is currently in.
| int module_bootstrap | ( | module_instance_t * | mi | ) |
Manually complete module bootstrap by calling its instantiate function.
| [in] | mi | Module instance to bootstrap. |
Definition at line 1308 of file module.c.
Here is the call graph for this function: Here is the caller graph for this function:| module_instance_t* module_instance_alloc | ( | module_list_t * | ml, |
| module_instance_t const * | parent, | ||
| dl_module_type_t | type, | ||
| char const * | mod_name, | ||
| char const * | inst_name, | ||
| module_instance_state_t | init_state | ||
| ) |
Allocate a new module and add it to a module list for later bootstrap/instantiation.
| [in] | ml | To add module to. |
| [in] | parent | of the module being bootstrapped, if this is a submodule. If this is not a submodule parent must be NULL. |
| [in] | type | What type of module we're loading. Determines the prefix added to the library name. Should be one of:
|
| [in] | mod_name | The name of this module, i.e. 'redis' for 'rlm_redis'. |
| [in] | inst_name | Instance name for this module, i.e. "aws_redis_01". The notable exception is if this is a submodule, in which case inst_name is usually the mod_name. |
| [in] | init_state | The state the module "starts" in. Can be used to prevent bootstrapping, instantiation, or thread instantiation of the module, by passing one or more of the MODULE_INSTANCE_* flags. Should usually be 0, unless special behaviour is required. |
Definition at line 1651 of file module.c.
Here is the call graph for this function: Here is the caller graph for this function:| module_instance_t* module_instance_by_data | ( | module_list_t const * | ml, |
| void const * | data | ||
| ) |
Find an existing module instance by its private instance data.
| [in] | ml | to search in. |
| [in] | data | to resolve to module_instance_t. |
Definition at line 957 of file module.c.
Here is the call graph for this function: Here is the caller graph for this function:| module_instance_t* module_instance_by_name | ( | module_list_t const * | ml, |
| module_instance_t const * | parent, | ||
| char const * | asked_name | ||
| ) |
Find an existing module instance by its name and parent.
| [in] | ml | to search in. |
| [in] | parent | to qualify search with. |
| [in] | asked_name | The name of the module we're attempting to find. May include '-' which indicates that it's ok for the module not to be loaded. |
Definition at line 903 of file module.c.
Here is the call graph for this function: Here is the caller graph for this function:| int module_instance_conf_parse | ( | module_instance_t * | mi, |
| CONF_SECTION * | conf | ||
| ) |
| module_instance_t* module_instance_copy | ( | module_list_t * | dst, |
| module_instance_t const * | src, | ||
| char const * | inst_name | ||
| ) |
Duplicate a module instance, placing it in a new module list.
| [in] | dst | list to place the new module instance in. |
| [in] | src | to duplicate. |
| [in] | inst_name | new instance name. If null, src->name will be used. |
Definition at line 1534 of file module.c.
Here is the call graph for this function: Here is the caller graph for this function:| int module_instance_data_protect | ( | module_instance_t const * | mi | ) |
| int module_instance_data_unprotect | ( | module_instance_t const * | mi | ) |
| void module_instance_debug | ( | module_instance_t const * | mi | ) |
| fr_slen_t module_instance_name_from_conf | ( | char const ** | name, |
| CONF_SECTION * | conf | ||
| ) |
| fr_slen_t module_instance_name_valid | ( | char const * | inst_name | ) |
Check to see if a module instance name is valid.
| [in] | inst_name | to check. |
Definition at line 1591 of file module.c.
Here is the caller graph for this function:| module_instance_t* module_instance_root | ( | module_instance_t const * | child | ) |
| char const* module_instance_root_prefix_str | ( | module_instance_t const * | mi | ) |
Return the prefix string for the deepest module.
This is useful for submodules which don't have a prefix of their own. In this case we need to use the prefix of the shallowest module, which will be a proto or rlm module.
| [in] | mi | Instance to get the prefix for. |
Definition at line 725 of file module.c.
Here is the call graph for this function: Here is the caller graph for this function:| bool module_instance_skip_bootstrap | ( | module_instance_t * | mi | ) |
| bool module_instance_skip_instantiate | ( | module_instance_t * | mi | ) |
| bool module_instance_skip_thread_instantiate | ( | module_instance_t * | mi | ) |
Should we instantiate this module instance in a new thread?
| [in] | mi | to check. |
Definition at line 1825 of file module.c.
Here is the caller graph for this function:| void module_instance_uctx_set | ( | module_instance_t * | mi, |
| void * | uctx | ||
| ) |
| int module_instantiate | ( | module_instance_t * | instance | ) |
| module_list_t* module_list_alloc | ( | TALLOC_CTX * | ctx, |
| module_list_type_t const * | type, | ||
| char const * | name, | ||
| bool | write_protect | ||
| ) |
Allocate a new module list.
This is used to instantiate and destroy modules in distinct phases for example, we may need to load all proto modules before rlm modules.
If the list is freed all module instance data will be freed. If no more instances of the module exist the module be unloaded.
| [in] | ctx | To allocate the list in. |
| [in] | type | of the list. Controls whether this is a global module list, or a per-thread list containing variants of an existing module. |
| [in] | name | of the list. Used for debugging. |
| [in] | write_protect | Whether to write protect the module data after instantiation and bootstrapping. |
Definition at line 1857 of file module.c.
Here is the call graph for this function: Here is the caller graph for this function:| void module_list_debug | ( | module_list_t const * | ml | ) |
| void module_list_mask_set | ( | module_list_t * | ml, |
| module_instance_state_t | mask | ||
| ) |
| int module_submodule_parse | ( | UNUSED TALLOC_CTX * | ctx, |
| void * | out, | ||
| void * | parent, | ||
| CONF_ITEM * | ci, | ||
| UNUSED conf_parser_t const * | rule | ||
| ) |
|
inlinestatic |
| module_thread_instance_t* module_thread_by_data | ( | module_list_t const * | ml, |
| void const * | data | ||
| ) |
Retrieve module/thread specific instance data for a module.
| [in] | ml | Module list module belongs to. |
| [in] | data | Private instance data of the module. Same as what would be provided by module_instance_by_data. |
Definition at line 980 of file module.c.
Here is the call graph for this function:| int module_thread_instantiate | ( | TALLOC_CTX * | ctx, |
| module_instance_t * | mi, | ||
| fr_event_list_t * | el | ||
| ) |
Allocate thread-local instance data for a module.
The majority of modules will have a single set of thread-specific instance data.
An exception is dynamic modules, which may have multiple sets of thread-specific instance data tied to a specific dynamic use of that module.
| [in] | ctx | Talloc ctx to bind thread specific data to. |
| [in] | mi | Module instance to perform thread instantiation for. |
| [in] | el | Event list serviced by this thread. |
Definition at line 1083 of file module.c.
Here is the call graph for this function: Here is the caller graph for this function:| int modules_bootstrap | ( | module_list_t const * | ml | ) |
Bootstrap any modules which have not been bootstrapped already.
Allows the module to initialise connection pools, and complete any registrations that depend on attributes created during the bootstrap phase.
| [in] | ml | containing modules to bootstrap. |
Definition at line 1372 of file module.c.
Here is the call graph for this function: Here is the caller graph for this function:| void modules_init | ( | char const * | lib_dir | ) |
| int modules_instantiate | ( | module_list_t const * | ml | ) |
Completes instantiation of modules.
Allows the module to initialise connection pools, and complete any registrations that depend on attributes created during the bootstrap phase.
| [in] | ml | containing modules to instantiate. |
Definition at line 1281 of file module.c.
Here is the call graph for this function: Here is the caller graph for this function:| void modules_thread_detach | ( | module_list_t * | ml | ) |
| int modules_thread_instantiate | ( | TALLOC_CTX * | ctx, |
| module_list_t const * | ml, | ||
| fr_event_list_t * | el | ||
| ) |
Creates per-thread instance data for modules which need it.
Must be called by any new threads before attempting to execute unlang sections.
| [in] | ctx | Talloc ctx to bind thread specific data to. |
| [in] | ml | Module list to perform thread instantiation for. |
| [in] | el | Event list serviced by this thread. |
Definition at line 1160 of file module.c.
Here is the call graph for this function: Here is the caller graph for this function:
|
extern |
|
extern |
1.9.1