rlm_cache

Synopsis

The cache module caches attributes and subsequently produces them on a later execution of the module.

The purpose of the cache module is either to allow caching of information across requests or to cache results from database lookups. The cached values are then added to requests when repeated requests for the same information occur.

Each instance of the module can cache only one set of attributes. If multiple different sets of attributes are required to be cached, then multiple instances of the module should be defined.

Default configuration

Processing Sections

authorize

When listed in the authorize section, the cache module will either look up or add entries to the cache.

If the control:Cache-TTL attribute is set to 0, the corresponding cache entry (if any) will be deleted.

If the control`Cache-Merge attribute is set to `yes+, then any new data is merged with the data in the cache. Otherwise, the old data is left in the cache, and the new data is not added to it.

Each time the cache is accessed, old entries are expired.

When cache entries are created, they are marked with a "time to live" (TTL). The ttl directive is used as the default value for cache entries. This default can be over-ridden dynamically by setting control:Cache-TTL to another value.

Return codes: ok The module found a cache entry.
: updated The module added a cache entry.
: noop The module did nothing.
: notfound The add_stats directive is set to true, and the module did not find a cache entry.

post-auth

See authorize, above.

preproxy

See authorize, above.

post-proxy

See authorize, above.

Expansions

This module registers only one expansion.

cache

Syntax: %{cache:<list>:Attribute-Name}
Contents: The contents of the expansion should be a reference to an attribute that is contained in the modules' update section. The output of the expansion is a string composed of the current cache value of that attribute.

Directives

add_stats

Syntax: add_stats = boolean
Default: no
Description: The module can operate in status-only mode where it will not add new cache entries or merge existing ones. To enable that mode, set control:Cache-Status-Only = yes.
: If set to yes, the request:Cache-Entry-Hits attribute will be added. Its value will be the number of times that this entry has been retrieved.

epoch

Syntax: epoch = integer
Default: 0
Description: The epoch is a timestamp used to mark versions of the cache. The epoch can be changed via the following radmin command:

Command

$ radmin -e "set module config cache epoch _integer_"

Where the last value is a 32-bit Unix timestamp in the form of seconds since January 1, 1970. Cache entries older than this value are expired, and new entries are added.

The configuration file should always have epoch = 0. Changing the epoch in the configuration file has no purpose.

key

Syntax: key = "%{User-Name}"
Default: string
Description: The key used to index the cache. It is dynamically expanded at run time.

ttl

Syntax: ttl = integer
Limits: 10 .. 86400
Default: 10
Description: The "time to live" of cache entries, in seconds. Entries older than this value will be expired. The TTL per cache entry can be set by adding the Cache-TTL attribute to the control list. The value given by that attribute will override the one in the configuration for the current request. Setting Cache-TTL = 0 means "delete the cache entry associated with the current request".

update

Syntax: update { … }
Description: The update directive is a sub-section that contains a list of attributes to cache for the given key. Each unique key will map to the same set of cached attributes, which are given in this sub-section.
: When a given key is stored, the module will process this update section to dynamically expand the values for each attribute. It will cache the the attribute list, name, operator, and value for later updates. The cached attributes are also added to the current request.
: When a given key is read from the cache, the module will copy the cached attributes. Each attribute will be placed into the named list, using the operator, with the value that was stored in the cache.
: Please see man unlang for the syntax of the attributes in the update section.

Example update section

update {
	# [outer.]:  

	# Cache all instances of Reply-Message in the reply list
	reply:Reply-Message += reply:Reply-Message

	# Add our own to show when the cache was last updated
	reply:Reply-Message += "Cache last updated at %t"

	# Add a random Class attribute
	reply:Class := "%{randstr:ssssssssssssssssssssssssssssssss}"
}