rlm_cache.c File Reference

Cache values and merge them back into future requests. More...

#include <freeradius-devel/server/base.h>
#include <freeradius-devel/server/module_rlm.h>
#include <freeradius-devel/server/modpriv.h>
#include <freeradius-devel/server/dl_module.h>
#include <freeradius-devel/server/rcode.h>
#include <freeradius-devel/server/tmpl.h>
#include <freeradius-devel/util/debug.h>
#include <freeradius-devel/util/types.h>
#include <freeradius-devel/util/value.h>
#include <freeradius-devel/unlang/xlat_func.h>
#include <freeradius-devel/unlang/call_env.h>
#include "rlm_cache.h"

Include dependency graph for rlm_cache.c:

Go to the source code of this file.

Data Structures
struct	cache_call_env_t
struct	cache_htrie_t

Macros
#define	LOG_PREFIX   mctx->inst->name

Functions
static int	cache_acquire (rlm_cache_handle_t **out, rlm_cache_t const *inst, request_t *request)
	Get exclusive use of a handle to access the cache. More...
static rlm_cache_entry_t *	cache_alloc (rlm_cache_t const *inst, request_t *request)
	Allocate a cache entry. More...
static unlang_action_t	cache_expire (rlm_rcode_t *p_result, rlm_cache_t const *inst, request_t *request, rlm_cache_handle_t **handle, fr_value_box_t const *key)
	Expire a cache entry (removing it from the datastore) More...
static unlang_action_t	cache_find (rlm_rcode_t *p_result, rlm_cache_entry_t **out, rlm_cache_t const *inst, request_t *request, rlm_cache_handle_t **handle, fr_value_box_t const *key)
	Find a cached entry. More...
static void	cache_free (rlm_cache_t const *inst, rlm_cache_entry_t **c)
	Free memory associated with a cache entry. More...
static unlang_action_t	cache_insert (rlm_rcode_t *p_result, rlm_cache_t const *inst, request_t *request, rlm_cache_handle_t **handle, fr_value_box_t const *key, map_list_t const *maps, fr_time_delta_t ttl)
	Create and insert a cache entry. More...
static int	cache_key_parse (TALLOC_CTX *ctx, void *out, tmpl_rules_t const *t_rules, CONF_ITEM *ci, char const *section_name1, char const *section_name2, void const *data, call_env_parser_t const *rule)
static rlm_rcode_t	cache_merge (rlm_cache_t const *inst, request_t *request, rlm_cache_entry_t *c)
	Merge a cached entry into a request_t. More...
static int	cache_reconnect (rlm_cache_handle_t **handle, rlm_cache_t const *inst, request_t *request)
	Reconnect an suspected inviable handle. More...
static void	cache_release (rlm_cache_t const *inst, request_t *request, rlm_cache_handle_t **handle)
	Release a handle we previously acquired. More...
static unlang_action_t	cache_set_ttl (rlm_rcode_t *p_result, rlm_cache_t const *inst, request_t *request, rlm_cache_handle_t **handle, rlm_cache_entry_t *c)
	Update the TTL of an entry. More...
static xlat_action_t	cache_ttl_get_xlat (TALLOC_CTX *ctx, fr_dcursor_t *out, xlat_ctx_t const *xctx, request_t *request, UNUSED fr_value_box_list_t *in)
static void	cache_unref (request_t *request, rlm_cache_t const *inst, rlm_cache_entry_t *entry, rlm_cache_handle_t *handle)
	Release the allocated resources and cleanup the avps. More...
static int	cache_update_section_parse (TALLOC_CTX *ctx, call_env_parsed_head_t *out, tmpl_rules_t const *t_rules, CONF_ITEM *ci, char const *section_name1, char const *section_name2, void const *data, call_env_parser_t const *rule)
static int	cache_update_section_parse (TALLOC_CTX *ctx, call_env_parsed_head_t *out, tmpl_rules_t const *t_rules, CONF_ITEM *ci, UNUSED char const *section_name1, UNUSED char const *section_name2, UNUSED void const *data, UNUSED call_env_parser_t const *rule)
static int	cache_verify (map_t *map, void *uctx)
	Verify that a map in the cache section makes sense. More...
static xlat_action_t	cache_xlat (TALLOC_CTX *ctx, fr_dcursor_t *out, xlat_ctx_t const *xctx, request_t *request, fr_value_box_list_t *in)
	Allow single attribute values to be retrieved from the cache. More...
static int	mod_bootstrap (module_inst_ctx_t const *mctx)
	Register module xlats. More...
static unlang_action_t	mod_cache_it (rlm_rcode_t *p_result, module_ctx_t const *mctx, request_t *request)
	Do caching checks. More...
static int	mod_detach (module_detach_ctx_t const *mctx)
	Free any memory allocated under the instance. More...
static int	mod_instantiate (module_inst_ctx_t const *mctx)
	Create a new rlm_cache_instance. More...
static unlang_action_t	mod_method_clear (rlm_rcode_t *p_result, module_ctx_t const *mctx, request_t *request)
	Delete the entries by ${key}. More...
static unlang_action_t	mod_method_load (rlm_rcode_t *p_result, module_ctx_t const *mctx, request_t *request)
	Load the avps by ${key}. More...
static unlang_action_t	mod_method_status (rlm_rcode_t *p_result, module_ctx_t const *mctx, request_t *request)
	Get the status by ${key} (without load) More...
static unlang_action_t	mod_method_store (rlm_rcode_t *p_result, module_ctx_t const *mctx, request_t *request)
	Create, or update a cache entry. More...
static unlang_action_t	mod_method_ttl (rlm_rcode_t *p_result, module_ctx_t const *mctx, request_t *request)
	Change the TTL on an existing entry. More...
static unlang_action_t	mod_method_update (rlm_rcode_t *p_result, module_ctx_t const *mctx, request_t *request)
	Create, or update a cache entry. More...

Variables
static fr_dict_attr_t const *	attr_cache_allow_insert
static fr_dict_attr_t const *	attr_cache_allow_merge
static fr_dict_attr_t const *	attr_cache_entry_hits
static fr_dict_attr_t const *	attr_cache_merge_new
static fr_dict_attr_t const *	attr_cache_status_only
static fr_dict_attr_t const *	attr_cache_ttl
static const call_env_method_t	cache_method_env
static xlat_arg_parser_t const	cache_xlat_args []
static fr_dict_t const *	dict_freeradius
static const conf_parser_t	module_config []
module_rlm_t	rlm_cache
fr_dict_autoload_t	rlm_cache_dict []
fr_dict_attr_autoload_t	rlm_cache_dict_attr []

Detailed Description

Cache values and merge them back into future requests.

Id

e2192ab223e0dcd3db0176a4f724983517120861

Copyright

2024 Arran Cudbard-Bell (a.cud.nosp@m.bard.nosp@m.b@fre.nosp@m.erad.nosp@m.ius.o.nosp@m.rg)

2012-2014 The FreeRADIUS server project

Definition in file rlm_cache.c.

---

Data Structure Documentation

cache_call_env_t

struct cache_call_env_t

Definition at line 60 of file rlm_cache.c.

Collaboration diagram for cache_call_env_t:

Data Fields
fr_value_box_t *	key	To lookup the cache entry with.
map_list_t *	maps	Attribute map applied to cache entries.

cache_htrie_t

struct cache_htrie_t

Definition at line 65 of file rlm_cache.c.

Data Fields
fr_type_t	ktype	Key type.

Macro Definition Documentation

LOG_PREFIX

#define LOG_PREFIX   mctx->inst->name

Definition at line 27 of file rlm_cache.c.

Function Documentation

cache_acquire()

static int cache_acquire ( rlm_cache_handle_t **  out, rlm_cache_t const *  inst, request_t *  request  )

static

Get exclusive use of a handle to access the cache.

Definition at line 153 of file rlm_cache.c.

Here is the caller graph for this function:

cache_alloc()

static rlm_cache_entry_t* cache_alloc ( rlm_cache_t const *  inst, request_t *  request  )

static

Allocate a cache entry.

This is used so that drivers may use their own allocation functions to allocate structures larger than the normal rlm_cache_entry_t.

If the driver doesn't specify a custom allocation function, the cache entry is talloced in the NULL ctx.

Definition at line 193 of file rlm_cache.c.

Here is the caller graph for this function:

cache_expire()

static unlang_action_t cache_expire ( rlm_rcode_t *  p_result, rlm_cache_t const *  inst, request_t *  request, rlm_cache_handle_t **  handle, fr_value_box_t const *  key  )

static

Expire a cache entry (removing it from the datastore)

Returns

• RLM_MODULE_OK on success.
• RLM_MODULE_NOTFOUND if no entry existed.
• RLM_MODULE_FAIL on failure.

Definition at line 345 of file rlm_cache.c.

Here is the call graph for this function:

Here is the caller graph for this function:

cache_find()

static unlang_action_t cache_find ( rlm_rcode_t *  p_result, rlm_cache_entry_t **  out, rlm_cache_t const *  inst, request_t *  request, rlm_cache_handle_t **  handle, fr_value_box_t const *  key  )

static

Find a cached entry.

Returns

• RLM_MODULE_OK on cache hit.
• RLM_MODULE_FAIL on failure.
• RLM_MODULE_NOTFOUND on cache miss.

Definition at line 275 of file rlm_cache.c.

Here is the call graph for this function:

Here is the caller graph for this function:

cache_free()

static void cache_free ( rlm_cache_t const *  inst, rlm_cache_entry_t **  c  )

static

Free memory associated with a cache entry.

This does not necessarily remove the entry from the cache, cache_expire should be used for that.

This function should be called when an entry that is known to have been retrieved or inserted into a data store successfully, is no longer needed.

Some drivers (like rlm_cache_rbtree) don't register a free function. This means that the cache entry never needs to be explicitly freed.

Parameters

[in]	inst	Module instance.
[in,out]	c	Cache entry to free.

Definition at line 214 of file rlm_cache.c.

Here is the caller graph for this function:

cache_insert()

static unlang_action_t cache_insert ( rlm_rcode_t *  p_result, rlm_cache_t const *  inst, request_t *  request, rlm_cache_handle_t **  handle, fr_value_box_t const *  key, map_list_t const *  maps, fr_time_delta_t  ttl  )

static

Create and insert a cache entry.

Returns

• RLM_MODULE_OK on success.
• RLM_MODULE_UPDATED if we merged the cache entry.
• RLM_MODULE_FAIL on failure.

Definition at line 373 of file rlm_cache.c.

Here is the call graph for this function:

Here is the caller graph for this function:

cache_key_parse()

static int cache_key_parse ( TALLOC_CTX *  ctx, void *  out, tmpl_rules_t const *  t_rules, CONF_ITEM *  ci, char const *  section_name1, char const *  section_name2, void const *  data, call_env_parser_t const *  rule  )

static

Definition at line 105 of file rlm_cache.c.

Here is the call graph for this function:

cache_merge()

static rlm_rcode_t cache_merge ( rlm_cache_t const *  inst, request_t *  request, rlm_cache_entry_t *  c  )

static

Merge a cached entry into a request_t.

Returns

• RLM_MODULE_OK if no entries were merged.
• RLM_MODULE_UPDATED if entries were merged.

Definition at line 229 of file rlm_cache.c.

Here is the call graph for this function:

Here is the caller graph for this function:

cache_reconnect()

static int cache_reconnect ( rlm_cache_handle_t **  handle, rlm_cache_t const *  inst, request_t *  request  )

static

Reconnect an suspected inviable handle.

Definition at line 178 of file rlm_cache.c.

Here is the call graph for this function:

Here is the caller graph for this function:

cache_release()

static void cache_release ( rlm_cache_t const *  inst, request_t *  request, rlm_cache_handle_t **  handle  )

static

Release a handle we previously acquired.

Definition at line 166 of file rlm_cache.c.

Here is the caller graph for this function:

cache_set_ttl()

static unlang_action_t cache_set_ttl ( rlm_rcode_t *  p_result, rlm_cache_t const *  inst, request_t *  request, rlm_cache_handle_t **  handle, rlm_cache_entry_t *  c  )

static

Update the TTL of an entry.

Returns

• RLM_MODULE_OK on success.
• RLM_MODULE_FAIL on failure.

Definition at line 550 of file rlm_cache.c.

Here is the call graph for this function:

Here is the caller graph for this function:

cache_ttl_get_xlat()

static xlat_action_t cache_ttl_get_xlat ( TALLOC_CTX *  ctx, fr_dcursor_t *  out, xlat_ctx_t const *  xctx, request_t *  request, UNUSED fr_value_box_list_t *  in  )

static

Definition at line 946 of file rlm_cache.c.

Here is the call graph for this function:

Here is the caller graph for this function:

cache_unref()

static void cache_unref ( request_t *  request, rlm_cache_t const *  inst, rlm_cache_entry_t *  entry, rlm_cache_handle_t *  handle  )

static

Release the allocated resources and cleanup the avps.

Definition at line 986 of file rlm_cache.c.

Here is the call graph for this function:

Here is the caller graph for this function:

cache_update_section_parse() [1/2]

static int cache_update_section_parse ( TALLOC_CTX *  ctx, call_env_parsed_head_t *  out, tmpl_rules_t const *  t_rules, CONF_ITEM *  ci, char const *  section_name1, char const *  section_name2, void const *  data, call_env_parser_t const *  rule  )

static

cache_update_section_parse() [2/2]

static int cache_update_section_parse ( TALLOC_CTX *  ctx, call_env_parsed_head_t *  out, tmpl_rules_t const *  t_rules, CONF_ITEM *  ci, UNUSED char const *  section_name1, UNUSED char const *  section_name2, UNUSED void const *  data, UNUSED call_env_parser_t const *  rule  )

static

Definition at line 1405 of file rlm_cache.c.

Here is the call graph for this function:

cache_verify()

static int cache_verify ( map_t *  map, void *  uctx  )

static

Verify that a map in the cache section makes sense.

Definition at line 1393 of file rlm_cache.c.

Here is the call graph for this function:

Here is the caller graph for this function:

mod_bootstrap()

static int mod_bootstrap ( module_inst_ctx_t const *  mctx )

static

Register module xlats.

Definition at line 1460 of file rlm_cache.c.

Here is the call graph for this function:

mod_cache_it()

static unlang_action_t mod_cache_it ( rlm_rcode_t *  p_result, module_ctx_t const *  mctx, request_t *  request  )

static

Do caching checks.

Since we can update ANY VP list, we do exactly the same thing for all sections (autz / auth / etc.)

If you want to cache something different in different sections, configure another cache module.

Definition at line 606 of file rlm_cache.c.

Here is the call graph for this function:

mod_detach()

static int mod_detach ( module_detach_ctx_t const *  mctx )

static

Free any memory allocated under the instance.

Definition at line 1373 of file rlm_cache.c.

mod_instantiate()

static int mod_instantiate ( module_inst_ctx_t const *  mctx )

static

Create a new rlm_cache_instance.

Definition at line 1439 of file rlm_cache.c.

mod_method_clear()

static unlang_action_t mod_method_clear ( rlm_rcode_t *  p_result, module_ctx_t const *  mctx, request_t *  request  )

static

Delete the entries by ${key}.

Returns

• RLM_MODULE_OK on success.
• RLM_MODULE_NOTFOUND on cache miss.
• RLM_MODULE_FAIL on failure.

Definition at line 1265 of file rlm_cache.c.

Here is the call graph for this function:

mod_method_load()

static unlang_action_t mod_method_load ( rlm_rcode_t *  p_result, module_ctx_t const *  mctx, request_t *  request  )

static

Load the avps by ${key}.

Returns

• RLM_MODULE_UPDATED on success.
• RLM_MODULE_NOTFOUND on cache miss.
• RLM_MODULE_FAIL on failure.

Definition at line 1068 of file rlm_cache.c.

Here is the call graph for this function:

mod_method_status()

static unlang_action_t mod_method_status ( rlm_rcode_t *  p_result, module_ctx_t const *  mctx, request_t *  request  )

static

Get the status by ${key} (without load)

Returns

• RLM_MODULE_OK on success.
• RLM_MODULE_NOTFOUND on cache miss.
• RLM_MODULE_FAIL on failure.

Definition at line 1030 of file rlm_cache.c.

Here is the call graph for this function:

mod_method_store()

static unlang_action_t mod_method_store ( rlm_rcode_t *  p_result, module_ctx_t const *  mctx, request_t *  request  )

static

Create, or update a cache entry.

Returns

• RLM_MODULE_NOOP if an entry already existed.
• RLM_MODULE_UPDATED if we inserted a cache entry.
• RLM_MODULE_FAIL on failure.

Definition at line 1198 of file rlm_cache.c.

Here is the call graph for this function:

mod_method_ttl()

static unlang_action_t mod_method_ttl ( rlm_rcode_t *  p_result, module_ctx_t const *  mctx, request_t *  request  )

static

Change the TTL on an existing entry.

Returns

• RLM_MODULE_UPDATED on success.
• RLM_MODULE_NOTFOUND on cache miss.
• RLM_MODULE_FAIL on failure.

Definition at line 1309 of file rlm_cache.c.

Here is the call graph for this function:

mod_method_update()

static unlang_action_t mod_method_update ( rlm_rcode_t *  p_result, module_ctx_t const *  mctx, request_t *  request  )

static

Create, or update a cache entry.

Returns

• RLM_MODULE_OK on success.
• RLM_MODULE_UPDATED if we merged the cache entry.
• RLM_MODULE_FAIL on failure.

Definition at line 1110 of file rlm_cache.c.

Here is the call graph for this function:

Variable Documentation

attr_cache_allow_insert

fr_dict_attr_t const* attr_cache_allow_insert

static

Definition at line 90 of file rlm_cache.c.

attr_cache_allow_merge

fr_dict_attr_t const* attr_cache_allow_merge

static

Definition at line 89 of file rlm_cache.c.

attr_cache_entry_hits

fr_dict_attr_t const* attr_cache_entry_hits

static

Definition at line 92 of file rlm_cache.c.

attr_cache_merge_new

fr_dict_attr_t const* attr_cache_merge_new

static

Definition at line 87 of file rlm_cache.c.

attr_cache_status_only

fr_dict_attr_t const* attr_cache_status_only

static

Definition at line 88 of file rlm_cache.c.

attr_cache_ttl

fr_dict_attr_t const* attr_cache_ttl

static

Definition at line 91 of file rlm_cache.c.

cache_method_env

const call_env_method_t cache_method_env

static

Initial value:

= {
        FR_CALL_ENV_METHOD_OUT(cache_call_env_t),
        .env = (call_env_parser_t[]) {
                { FR_CALL_ENV_OFFSET("key", FR_TYPE_VOID, CALL_ENV_FLAG_REQUIRED, cache_call_env_t, key), .pair.func = cache_key_parse },
                { FR_CALL_ENV_SUBSECTION_FUNC("update", CF_IDENT_ANY, CALL_ENV_FLAG_NONE, cache_update_section_parse) },
                CALL_ENV_TERMINATOR
        }
}

Definition at line 70 of file rlm_cache.c.

cache_xlat_args

xlat_arg_parser_t const cache_xlat_args[]

static

Initial value:

= {
        { .required = true, .single = true, .type = FR_TYPE_STRING },
        XLAT_ARG_PARSER_TERMINATOR
}

Definition at line 864 of file rlm_cache.c.

dict_freeradius

fr_dict_t const* dict_freeradius

static

Definition at line 79 of file rlm_cache.c.

module_config

const conf_parser_t module_config[]

static

Initial value:

= {
        { FR_CONF_OFFSET_TYPE_FLAGS("driver", FR_TYPE_VOID, 0, rlm_cache_t, driver_submodule), .dflt = "rbtree",
                         .func = module_rlm_submodule_parse },
        { FR_CONF_OFFSET("ttl", rlm_cache_config_t, ttl), .dflt = "500s" },
        { FR_CONF_OFFSET("max_entries", rlm_cache_config_t, max_entries), .dflt = "0" },
 
        
        { FR_CONF_OFFSET("epoch", rlm_cache_config_t, epoch), .dflt = "0" },
        { FR_CONF_OFFSET("add_stats", rlm_cache_config_t, stats), .dflt = "no" },
        CONF_PARSER_TERMINATOR
}

Definition at line 48 of file rlm_cache.c.

rlm_cache

module_rlm_t rlm_cache

Initial value:

= {
        .common = {
                .magic          = MODULE_MAGIC_INIT,
                .name           = "cache",
                .inst_size      = sizeof(rlm_cache_t),
                .config         = module_config,
                .bootstrap      = mod_bootstrap,
                .instantiate    = mod_instantiate,
                .detach         = mod_detach
        },
        .method_names = (module_method_name_t[]){
                { .name1 = "status", .name2 = CF_IDENT_ANY,             .method = mod_method_status,    .method_env = &cache_method_env },
                { .name1 = "load", .name2 = CF_IDENT_ANY,               .method = mod_method_load,      .method_env = &cache_method_env },
                { .name1 = "update", .name2 = CF_IDENT_ANY,             .method = mod_method_update,    .method_env = &cache_method_env },
                { .name1 = "store", .name2 = CF_IDENT_ANY,              .method = mod_method_store,     .method_env = &cache_method_env },
                { .name1 = "clear", .name2 = CF_IDENT_ANY,              .method = mod_method_clear,     .method_env = &cache_method_env },
                { .name1 = "ttl", .name2 = CF_IDENT_ANY,                .method = mod_method_ttl,       .method_env = &cache_method_env },
                { .name1 = CF_IDENT_ANY, .name2 = CF_IDENT_ANY,         .method = mod_cache_it,         .method_env = &cache_method_env },
                MODULE_NAME_TERMINATOR
        }
}

Definition at line 1497 of file rlm_cache.c.

rlm_cache_dict

fr_dict_autoload_t rlm_cache_dict

Initial value:

= {
        { .out = &dict_freeradius, .proto = "freeradius" },
        { NULL }
}

Definition at line 82 of file rlm_cache.c.

rlm_cache_dict_attr

fr_dict_attr_autoload_t rlm_cache_dict_attr

Initial value:

= {
        { .out = &attr_cache_merge_new, .name = "Cache-Merge-New", .type = FR_TYPE_BOOL, .dict = &dict_freeradius },
        { .out = &attr_cache_status_only, .name = "Cache-Status-Only", .type = FR_TYPE_BOOL, .dict = &dict_freeradius },
        { .out = &attr_cache_allow_merge, .name = "Cache-Allow-Merge", .type = FR_TYPE_BOOL, .dict = &dict_freeradius },
        { .out = &attr_cache_allow_insert, .name = "Cache-Allow-Insert", .type = FR_TYPE_BOOL, .dict = &dict_freeradius },
        { .out = &attr_cache_ttl, .name = "Cache-TTL", .type = FR_TYPE_INT32, .dict = &dict_freeradius },
        { .out = &attr_cache_entry_hits, .name = "Cache-Entry-Hits", .type = FR_TYPE_UINT32, .dict = &dict_freeradius },
        { NULL }
}

Definition at line 95 of file rlm_cache.c.