Beaker's cache and session options are configured via a dictionary.

When used with the Paste package, all Beaker options should be prefixed with beaker. so that Beaker can discriminate its options from other application configuration options.

General Config Options (prefix with either session. or cache.)

data_dir

Accepts: string
Default: None

The data directory where cache data will be stored. If this argument is not present, the regular data_dir parameter is used, with the path "./sessions" appended to it.

type

Accepts: string
Default: dbm

Type of storage used for the session, current types are "dbm", "file", "memcached", "database", and "memory". The storage uses the Container API that is also used by the cache system.

When using dbm files, each user's session is stored in its own dbm file, via the class beaker.container.DBMNamespaceManager class.

When using 'database' or 'memcached', additional configuration options are required as documented in the appropriate section below.

For sessions only, there is an additional choice of a "cookie" type, which requires the Sessions "secret" option to be set as well.

Database Configuration

When the type is set to 'database', the following additional options can be used.

url (required)

Accepts: string (formatted as required for an SQLAlchemy db uri)
Default: None

The database URI as formatted for SQLAlchemy to use for the database. The appropriate database packages for the database must also be installed.

table_name

Accepts: string
Default: beaker_cache

Table name to use for beaker's storage.

optimistic

Accepts: boolean
Default: False

Use optimistic session locking, note that this will result in an select when updating a cache value to compare version numbers.

sa_opts (Only for SQLAlchemy 0.3)

Accepts: dict
Default: None

A dictionary of values to use that are passed directly to SQLAlchemy's engine. Note that this is only applicable for SQLAlchemy 0.3.

sa.*

Accepts: Valid SQLAlchemy 0.4 database options
Default: None

When using SQLAlchemy 0.4 and above, all options prefixed with sa. are passed to the SQLAlchemy database engine. Common parameters are pool_size, pool_recycle, etc.

Memcached Options

url (required)

Accepts: string
Default: None

The url should be a single IP address, or list of semi-colon separated IP addresses that should be used for memcached.

Beaker can use either py-memcached or cmemcache to communicate with memcached, but it should be noted that cmemcache can cause Python to segfault should memcached become unreachable.

Session Options

cookie_expires

Accepts: boolean, datetime, timedelta
Default: True

The expiration time to use on the session cookie. Defaults to "True" which means, don't specify any expiration time (the cookie will expire when the browser is closed). A value of "False" means, never expire (specifies the maximum date that can be stored in a datetime object and uses that). The value can also be a datetime.timedelta() object which will be added to the current date and time, or a datetime.datetime() object.

cookie_domain

Accepts: string
Default: The entire domain name being used, including sub-domain, etc.

By default, Beaker's sessions are set to the cookie domain of the entire hostname. For sub-domains, this should be set to the top domain the cookie should be valid for.

id

Accepts: string
Default: None

Session id for this session. When using sessions with cookies, this parameter is not needed as the session automatically creates, writes and retrieves the value from the request. When using a URL-based method for the session, the id should be retreived from the id data member when the session is first created, and then used in writing new URLs.

key

Accepts: string
Default: beaker_session_id

The key that will be used as a cookie key to identify sessions. Changing this could allow several different applications to have different sessions underneath the same hostname.

secret

Accepts: string
Default: None

Secret key to enable encrypted session ids. When non-None, the session ids are generated with an MD5-signature created against this value.

When used with the "cookie" Session type, the secret is used for encrypting the contents of the cookie, and should be a reasonably secure randomly generated string of characters no more than 54 characters.

timeout

Accepts: integer
Default: None

Time in seconds before the session times out. A timeout occurs when the session has not been loaded for more than timeout seconds.

Session Options (For use with cookie-based Sessions)

encrypt_key

Accepts: string
Default: None

The key to use for the session encryption, if not provided the session will not be encrypted. This will only work if a strong hash scheme is available, such as pycryptopp's or Python 2.5's hashlib.sha256.

validate_key

Accepts: string
Default: None

The key used to sign the encrypted session, this is used instead of a secret option.