Session handling

An administrator can change the following settings in 'Session Handling' in the Site administration.

Once someone logs in to your Moodle server, the server starts a session. The session data allows the server to track users as they access different pages.

Use database for session information

Moodle needs to store the session data in some storage. By default either file or database session storage is selected, this option allows admin to change it. Large installation should use memcached driver described below.

Note that this option disappears after setting the $CFG->session_handler_class in config.php file.

Timeout

If users don't load a new page during the amount of time set here, Moodle will end their session and log them out.

Be sure this time frame is long enough to cover the longest test your teachers may offer. If a student is logged out while they are taking a test, their responses to the test questions may be lost.

Cookie prefix

Most of the time, you can leave this blank, unless you are running more than one Moodle site on the same server. In this case, you will want to customize the name of the cookie each Moodle site uses to track the session. This enables you to be logged into more than one Moodle site at the same time.

Note: If you change "Cookie prefix" or "Cookie path" you will need to login again as the changes take effect immediately.

Cookie path

The relative path to this Moodle installation, this may be used to force sending of Moodle session cookie to parent directories. Invalid values are ignored automatically.

Cookie domain

This can be used to send session cookies to higher domains instead of just the server domain. This may be useful for some SSO solutions. Invalid values are ignored automatically.

Session drivers

User sessions may be stored in different backends. Session drivers can be configured only in config.php file - see examples in config-dist.php file.

Memcached session driver

The Memcached session driver is the fastest driver. It requires external memcached server and memcached PHP extension. Server cluster nodes must use shared session storage.

Configuration options in config.php:

$CFG->session_handler_class = '\core\session\memcached';
$CFG->session_memcached_save_path = '127.0.0.1:11211';
$CFG->session_memcached_prefix = 'memc.sess.key.';
$CFG->session_memcached_acquire_lock_timeout = 120;
$CFG->session_memcached_lock_expire = 7200;       // Ignored if memcached extension <= 2.1.0

Notes:

• Make sure the memcached server has enough memory.
• Use different prefix when storing sessions from multiple Moodle sites in one server.
• If PECL memcached extension version installed is less that 2.2.0, the locking works differently from other drivers - the lock is expired/released at the end of timeout - see MDL-42485.
• Don't use the same memcached server for both sessions and MUC. Events triggering MUC caches to be purged leads to MUC purging the memcached server - thus terminating ALL sessions.
• The $CFG->session_memcached_number_of_replicas option is no longer supported.

For windows users, PHP.net only supplies binaries for memcache, (and not memcached). (http://windows.php.net/downloads/pecl/releases/)

(As of 2.7, two different contribs exist for memcache session handling - see MDL-42011 - it seems the OU one doesn't use prefix/lock_expire for some reason... possibly better to use the catalyst patch, where the only difference to the above config.php is the spelling of memcache(d).)

File session driver

This driver is used by default in new installation.

Configuration options in config.php:

$CFG->session_handler_class = '\core\session\file';
$CFG->session_file_save_path = $CFG->dataroot.'/sessions';

Notes:

• File based sessions require file system that supports file locking.

Database session driver

This type of driver was used by default in Moodle 2.0-2.5.

$CFG->session_handler_class = '\core\session\database';
$CFG->session_database_acquire_lock_timeout = 120;

Notes:

• DB sessions are not compatible with MyISAM database engine.
• If you are using MySQL/MariaDB make sure that \'max_allowed_packet\' in my.cnf (or my.ini) is at least 4M.
• The performance is relatively low, it is not recommended for large sites.

Redis session driver

The Redis session driver is available in Moodle 3.1.3 onwards (see MDL-54606). It requires a Redis server and the Redis extension.

Configuration options in config.php:

$CFG->session_handler_class = '\core\session\redis';
$CFG->session_redis_host = '127.0.0.1';
$CFG->session_redis_port = 6379;  // Optional.
$CFG->session_redis_database = 0;  // Optional, default is db 0.
$CFG->session_redis_auth = ''; // Optional, default is don't set one.
$CFG->session_redis_prefix = ''; // Optional, default is don't set one.
$CFG->session_redis_acquire_lock_timeout = 120;
$CFG->session_redis_acquire_lock_retry = 100; // Optional, default is 100ms (from 3.9)
$CFG->session_redis_lock_expire = 7200;
$CFG->session_redis_serializer_use_igbinary = false; // Optional, default is PHP builtin serializer.

Notes:

• Be careful on changing the default serializer: it requires --enable-redis-igbinary at phpredis extension compile time and you need to remove the previous session data before using Moodle again.

Read only sessions

There is an experimental feature introduced in Moodle 3.9 and stable in 3.11. It allows certain pages to start readonly sessions which do not require a write lock with the aim of high performance at scale.

https://tracker.moodle.org/browse/MDL-58018

Configuration

1) Using a compliant session store

In order to use readonly sessions you need to be using a session store which supports it, which includes database and redis.

2) Mapping session caches

By default all MUC 'session caches' are stored in the $SESSION which is a subtle distinction that is easily misunderstood. MUC caches can be read and written at any time and are independent of the $SESSION being locked. So all cache definitions which have a mode of session need to be mapped to a store which is not in the session such as in redis. If this isn't done errors will be raised highlighting the configuration issue.

3) Turning it on in config.php

$CFG->enable_read_only_sessions = true;

If you have concerns about rolling this out, there is a soft rollout mode which report on any issues and you could leave this on for say a month or two and then turn it on fully:

$CFG->enable_read_only_sessions_debug = true;

4) Adding support for it to core and plugins

Various critical pages and web services in core have been declared and implemented as readonly, if you want to support readonly sessions please read: https://docs.moodle.org/dev/Session_locks

See also

• Sessions FAQ