Configuration¶
Beaker can be configured several different ways, depending on how it is to be
used. The most recommended style is to use a dictionary of preferences that
are to be passed to either the SessionMiddleware
or
the CacheManager
.
Since both Beaker’s sessions and caching use the same back-end container storage system, there’s some options that are applicable to both of them in addition to session and cache specific configuration.
Most options can be specified as a string (necessary to config options that are setup in INI files), and will be coerced to the appropriate value. Only datetime’s and timedelta’s cannot be coerced and must be the actual objects.
Frameworks using Beaker usually allow both caching and sessions to be configured in the same spot, Beaker assumes this condition as well and requires options for caching and sessions to be prefixed appropriately.
For example, to configure the cookie_expires
option for Beaker sessions
below, an appropriate entry in a Pylons INI file would be:
# Setting cookie_expires = true causes Beaker to omit the
# expires= field from the Set-Cookie: header, signaling the cookie
# should be discarded when the browser closes.
beaker.session.cookie_expires = true
Note
When using the options in a framework like Pylons or TurboGears2, these
options must be prefixed by beaker.
, for example in a Pylons INI file:
beaker.session.data_dir = %(here)s/data/sessions/data
beaker.session.lock_dir = %(here)s/data/sessions/lock
Or when using stand-alone with the SessionMiddleware
:
from beaker.middleware import SessionMiddleware
session_opts = {
'session.cookie_expires': True
}
app = SomeWSGIAPP()
app = SessionMiddleware(app, session_opts)
Or when using the CacheManager
:
from beaker.cache import CacheManager
from beaker.util import parse_cache_config_options
cache_opts = {
'cache.type': 'file',
'cache.data_dir': '/tmp/cache/data',
'cache.lock_dir': '/tmp/cache/lock'
}
cache = CacheManager(**parse_cache_config_options(cache_opts))
Note
When using the CacheManager directly, all dict options must be run through the
beaker.util.parse_cache_config_options()
function to ensure they’re valid
and of the appropriate type.
Options For Sessions and Caching¶
- data_dir (optional, string)
- Used with any back-end that stores its data in physical files, such as the dbm or file-based back-ends. This path should be an absolute path to the directory that stores the files.
- lock_dir (required, string)
- Used with every back-end, to coordinate locking. With caching, this lock file is used to ensure that multiple processes/threads aren’t attempting to re-create the same value at the same time (The Dog-Pile Effect)
- memcache_module (optional, string)
- One of the names
memcache
,cmemcache
,pylibmc
, orauto
. Default isauto
. Specifies which memcached client library should be imported when using the ext:memcached backend. If left at its default ofauto
,pylibmc
is favored first, thencmemcache
, thenmemcache
. New in 1.5.5. - type (required, string)
The name of the back-end to use for storing the sessions or cache objects.
Available back-ends supplied with Beaker:
file
,dbm
,memory
,ext:memcached
,ext:database
,ext:google
,ext:mongodb
, andext:redis
.For sessions, the additional type of
cookie
is available which will store all the session data in the cookie itself. As such, size limitations apply (4096 bytes).Some of these back-ends require the url option as listed below.
- webtest_varname (optional, string)
- The name of the attribute to use when stashing the session object into the environ for use with WebTest. The name provided here is where the session object will be attached to the WebTest TestApp return value.
- url (optional, string) URL is specific to use of either
ext:memcached
, ext:database
,ext:mongodb
, orext:redis
. When using one of those types, this option is required.When used with
ext:memcached
, this should be either a single, or semi-colon separated list of memcached servers:session_opts = { 'session.type': 'ext:memcached', 'session.url': '127.0.0.1:11211', }
When used with
ext:database
, this should be a valid SQLAlchemy database string.When used with
ext:redis
, this should be an URL as passed toStrictRedis.from_url()
.
Session Options¶
The Session handling takes a variety of additional options relevant to how it stores session id’s in cookies, and when using the optional encryption.
- auto (optional, bool)
When set to True, the session will save itself anytime it is accessed during a request, negating the need to issue the
save()
method.Defaults to False.
- cookie_expires (optional, bool, datetime, timedelta, int)
Determines when the cookie used to track the client-side of the session will expire. When set to a boolean value, it will either expire at the end of the browsers session, or never expire.
Setting to a datetime forces a hard ending time for the session (generally used for setting a session to a far off date).
Setting to an integer will result in the cookie being set to expire in that many seconds. I.e. a value of
300
will result in the cookie being set to expire in 300 seconds.Defaults to never expiring.
- cookie_domain (optional, string)
What domain the cookie should be set to. When using sub-domains, this should be set to the main domain the cookie should be valid for. For example, if a cookie should be valid under
www.nowhere.com
andfiles.nowhere.com
then it should be set to.nowhere.com
.Defaults to the current domain in its entirety.
Alternatively, the domain can be set dynamically on the session by calling, see Session Attributes / Keys.
- key (required, string)
- Name of the cookie key used to save the session under.
- save_accessed_time (optional, bool)
Whether beaker should save the session’s access time (true) or only modification time (false).
Defaults to true.
- secret (required, string)
Used with the HMAC to ensure session integrity. This value should ideally be a randomly generated string.
When using in a cluster environment, the secret must be the same on every machine.
- secure (optional, bool)
- Whether or not the session cookie should be marked as secure. When marked as secure, browsers are instructed to not send the cookie over anything other than an SSL connection.
- timeout (optional, integer)
Seconds until the session is considered invalid, after which it will be ignored and invalidated. This number is based on the time since the session was last accessed, not from when the session was created.
Defaults to never expiring.
Requires that save_accessed_time be true.
Encryption Options¶
These options should then be used instead of the secret
option when
a cookie only session is used and together with the secret
option
when a server side session is used.
- encrypt_key (required, string)
- Encryption key to use for the AES cipher. This should be a fairly long randomly generated string.
- validate_key (required, string)
- Validation key used to sign the AES encrypted data.
- crypto_type (optional, string)
Encryption backend to use. If
default
is used, one of the installed backends is picked.Other valid choices are
cryptography
,nss
,pycrypto
.
Note
You may need to install additional libraries to use Beaker’s cookie-based session encryption. See the Encryption section for more information.
Cache Options¶
For caching, options may be directly specified on a per-use basis with the
cache()
decorator, with the rest of these
options used as fallback should one of them not be specified in the call.
Only the lock_dir
option is strictly required, unless using the file-based
back-ends as noted with the sessions.
- expire (optional, integer)
- Seconds until the cache is considered old and a new value is created.
Cache Region Options¶
Starting in Beaker 1.3, cache regions are now supported. These can be thought of as bundles of configuration options to apply, rather than specifying the type and expiration on a per-usage basis.
- enabled (optional, bool)
Quick toggle to disable or enable caching across an entire application.
This should generally be used when testing an application or in development when caching should be ignored.
Defaults to True.
- regions (optional, list, tuple)
Names of the regions that are to be configured.
For each region, all of the other cache options are valid and will be read out of the cache options for that key. Options that are not listed under a region will be used globally in the cache unless a region specifies a different value.
For example, to specify two batches of options, one called
long-term
, and one calledshort-term
:cache_opts = { 'cache.data_dir': '/tmp/cache/data', 'cache.lock_dir': '/tmp/cache/lock' 'cache.regions': 'short_term, long_term', 'cache.short_term.type': 'ext:memcached', 'cache.short_term.url': '127.0.0.1.11211', 'cache.short_term.expire': '3600', 'cache.long_term.type': 'file', 'cache.long_term.expire': '86400',