raddb/mods-available/cache

   1 # -*- text -*-
   2 #
   3 #  $Id$
   4
   5 #
   6 #       A module to cache attributes.  The idea is that you can look
   7 #       up information in a database, and then cache it.  Repeated
   8 #       requests for the same information will then have the cached
   9 #       values added to the request.
  10 #
  11 #       The module can cache a fixed set of attributes per key.
  12 #       It can be listed in "authorize", "post-auth", "pre-proxy"
  13 #       and "post-proxy".
  14 #
  15 #       If you want different things cached for authorize and post-auth,
  16 #       you will need to define two instances of the "cache" module.
  17 #
  18 #       The module returns "ok" if it found or created a cache entry.
  19 #       The module returns "updated" if it merged a cached entry.
  20 #       The module returns "noop" if it did nothing.
  21 #       The module returns "fail" on error.
  22 #
  23 cache {
  24         #  The backend datastore used to store the cache entries.
  25         #  Current datastores are
  26         #    rlm_cache_rbtree    - An in memory, non persistent rbtree based datastore.
  27         #                          Useful for caching data locally.
  28         #    rlm_cache_memcached - A non persistent "webscale" distributed datastore.
  29         #                          Useful if the cached data need to be shared between
  30         #                          a cluster of RADIUS servers.
  31 #       driver = "rlm_cache_rbtree"
  32
  33         #
  34         #  Some drivers accept specific options, to set them a
  35         #  config section with the the name as the driver should be added
  36         #  to the cache instance.
  37         #
  38         #  Driver specific options are:
  39         #
  40 #       memcached {
  41 #               # Memcached configuration options, as documented here:
  42 #               #    http://docs.libmemcached.org/libmemcached_configuration.html#memcached
  43 #               options = "--SERVER=localhost"
  44 #
  45 #               pool {
  46 #                       start = ${thread[pool].start_servers}
  47 #                       min = ${thread[pool].min_spare_servers}
  48 #                       max = ${thread[pool].max_servers}
  49 #                       spare = ${thread[pool].max_spare_servers}
  50 #                       uses = 0
  51 #                       lifetime = 0
  52 #                       idle_timeout = 60
  53 #               }
  54 #       }
  55
  56         #  The key used to index the cache.  It is dynamically expanded
  57         #  at run time.
  58         key = "%{User-Name}"
  59
  60         #  The TTL of cache entries, in seconds.  Entries older than this
  61         #  will be expired.
  62         #
  63         #  This value should be between 10 and 86400.
  64         ttl = 10
  65
  66         #  You can flush the cache via
  67         #
  68         #       radmin -e "set module config cache epoch 123456789"
  69         #
  70         #  Where last value is a 32-bit Unix timestamp.  Cache entries older
  71         #  than this are expired, as new entries added.
  72         #
  73         #  You should never set the "epoch" configuration item in this file.
  74
  75         #  If yes the following attributes will be added to the request:
  76         #      * &request:Cache-Entry-Hits - The number of times this entry
  77         #                                    has been retrieved.
  78         #
  79         #  Note: Not supported by the rlm_cache_memcached module.
  80         add_stats = no
  81
  82         #
  83         #  The list of attributes to cache for a particular key.
  84         #
  85         #  Each key gets the same set of cached attributes. The attributes
  86         #  are dynamically expanded at run time.
  87         #
  88         #  The semantics of this construct are identical to an unlang
  89         #  update block, except the left hand side of the expression
  90         #  represents the cache entry. see man unlang for more information
  91         #  on update blocks.
  92         #
  93         #  Note: Only request, reply, control and session-state lists
  94         #  are available in cache entries. Attempting to store attributes
  95         #  in other lists will raise an error during config validation.
  96         #
  97         update {
  98                 # <list>:<attribute> <op> <value>
  99
 100                 # Cache all instances of Reply-Message in the reply list
 101                 &reply:Reply-Message += &reply:Reply-Message
 102
 103                 # Add our own to show when the cache was last updated
 104                 &reply:Reply-Message += "Cache last updated at %t"
 105
 106                 &reply:Class := "%{randstr:ssssssssssssssssssssssssssssssss}"
 107         }
 108
 109         #  This module supports a number of runtime configuration parameters
 110         #  represented by attributes in the &control: list.
 111         #
 112         #  &control:Cache-TTL - Sets the TTL of an entry to be created, or
 113         #  modifies the TTL of an existing entry.
 114         #    - Setting a Cache-TTL of > 0 means set the TTL of the entry to
 115         #      the new value (and reset the expiry timer).
 116         #    - Setting a Cache-TTL of < 0 means expire the existing entry
 117         #      (without merging) and create a new one with TTL set to
 118         #      value * -1.
 119         #    - Setting a Cache-TTL of 0 means expire the existing entry
 120         #      (without merging) and don't create a new one.
 121         #
 122         #  &control:Cache-Status-Only - If present and set to 'yes' will
 123         #  prevent a new entry from being created, and existing entries from
 124         #  being merged.  It will also alter the module's return codes.
 125         #    - The module will return "ok" if a cache entry was found.
 126         #    - The module will return "notfound" if no cache entry was found.
 127         #
 128         #  &control:Cache-Read-Only - If present and set to 'yes' will
 129         #  prevent a new entry from being created, but will allow existing
 130         #  entries to be merged.  It will also alter the module's return codes.
 131         #    - The module will return "updated" if a cache entry was found.
 132         #    - The module will return "notfound" if no cache was found.
 133         #
 134         #  &control:Cache-Merge - If present and set to 'yes' will merge new
 135         #  cache entries into the current request. Useful if results
 136         #  of execs or expansions are stored directly in the cache.
 137         #
 138         #  All runtime configuration attributes will be removed from the
 139         #  &control: list after the cache module is called.
 140
 141 }