Use Redis for session storage

Last update: September 28, 2024

CREATED FOR:

  • Experienced
  • Admin
  • Developer
IMPORTANT
You must install Redis before continuing.

Commerce now provides command-line options to configure Redis session storage. In previous releases, you edited the <Commerce install dir>app/etc/env.php file. The command line provides validation and is the recommended configuration method, but you can still edit the env.php file.

Run the setup:config:set command and specify Redis-specific parameters.

bin/magento setup:config:set --session-save=redis --session-save-redis-<parameter_name>=<parameter_value>...

where

--session-save=redis enables Redis session storage. If this feature has already been enabled, omit this parameter.

--session-save-redis-<parameter_name>=<parameter_value> is a list of parameter/value pairs that configure session storage:

Command-line ParameterParameter nameMeaningDefault value
session-save-redis-hosthostFully qualified hostname, IP address, or absolute path if using UNIX sockets.localhost
session-save-redis-portportRedis server listen port.6379
session-save-redis-passwordpasswordSpecifies a password if your Redis server requires authentication.empty
session-save-redis-timeouttimeoutConnection timeout, in seconds.2.5
session-save-redis-persistent-idpersistent_identifierUnique string to enable persistent connections (for example, sess-db0).
Known issues with phpredis and php-fpm.
session-save-redis-dbdatabaseUnique Redis database number, which is recommended to protect against data loss.

Important: If you use Redis for more than one type of caching, the database numbers must be different. It is recommended that you assign the default caching database number to 0, the page-caching database number to 1, and the session storage database number to 2.		0
session-save-redis-compression-thresholdcompression_thresholdSet to 0 to disable compression (recommended when suhosin.session.encrypt = On).
Known issue with strings of more than 64 KB.		2048
session-save-redis-compression-libcompression_libraryOptions: gzip, lzf, lz4 or snappy.gzip
session-save-redis-log-levellog_level

Set to any of the following, listed in order from least verbose to most verbose:

  • 0 (emergency: only the most severe errors)
  • 1 (alert: immediate action required)
  • 2 (critical: application component unavailable)
  • 3 (error: runtime errors, not critical but must be monitored)
  • 4 (warning: additional information, recommended)
  • 5 (notice: normal but significant condition)
  • 6 (info: informational messages)
  • 7 (debug: the most information for development or testing only)
1
session-save-redis-max-concurrencymax_concurrencyMaximum number of processes that can wait for a lock on one session. For large production clusters, set this to at least 10% of the number of PHP processes.6
session-save-redis-break-after-frontendbreak_after_frontendNumber of seconds to wait before trying to break the lock for frontend (that is, storefront) session.5
session-save-redis-break-after-adminhtmlbreak_after_adminhtmlNumber of seconds to wait before trying to break the lock for an adminhtml (that is, Admin) session.30
session-save-redis-first-lifetimefirst_lifetimeLifetime, in seconds, of session for non-bots on the first write, or use 0 to disable.600
session-save-redis-bot-first-lifetimebot_first_lifetimeLifetime, in seconds, of session for bots on the first write, or use 0 to disable.60
session-save-redis-bot-lifetimebot_lifetimeLifetime, in seconds, of session for bots on subsequent writes, or use 0 to disable.7200
session-save-redis-disable-lockingdisable_lockingDisable session locking entirely.0 (false)
session-save-redis-min-lifetimemin_lifetimeMinimum session lifetime, in seconds.60
session-save-redis-max-lifetimemax_lifetimeMaximum session lifetime, in seconds.2592000 (720 hours)
session-save-redis-sentinel-mastersentinel_masterRedis Sentinel master nameempty
session-save-redis-sentinel-serverssentinel_serversList of Redis Sentinel servers, comma separatedempty
session-save-redis-sentinel-verify-mastersentinel_verify_masterVerify Redis Sentinel master status flag0 (false)
session-save-redis-sentinel-connect-retriessentinel_connect_retriesConnection retries for sentinels5

Example

The following example sets Redis as the session data store, sets the host to 127.0.0.1, sets the log level to 4, and sets the database number to 2. All other parameters are set to the default value.

bin/magento setup:config:set --session-save=redis --session-save-redis-host=127.0.0.1 --session-save-redis-log-level=4 --session-save-redis-db=2

Result

Commerce adds lines similar to the following to <magento_root>app/etc/env.php:

'session' => [
    'save' => 'redis',
    'redis' => [
        'host' => '127.0.0.1',
        'port' => '6379',
        'password' => '',
        'timeout' => '2.5',
        'persistent_identifier' => '',
        'database' => '2',
        'compression_threshold' => '2048',
        'compression_library' => 'gzip',
        'log_level' => '4',
        'max_concurrency' => '6',
        'break_after_frontend' => '5',
        'break_after_adminhtml' => '30',
        'first_lifetime' => '600',
        'bot_first_lifetime' => '60',
        'bot_lifetime' => '7200',
        'disable_locking' => '0',
        'min_lifetime' => '60',
        'max_lifetime' => '2592000',
    ],
],
INFO
TTL for session records uses the value for Cookie Lifetime, which is configured in the Admin. If Cookie Lifetime is set to 0 (the default is 3600), then Redis sessions expire in the number of seconds specified in min_lifetime (the default is 60). This discrepancy is due to differences in how Redis and session cookies interpret a lifetime value of 0. If that behavior is not desired, increase the value of min_lifetime.

Verify Redis connection

To verify that Redis and Commerce are working together, log in to the server running Redis, open a terminal, and use the Redis monitor command or the ping command.

Redis monitor command

redis-cli monitor

Sample session-storage output:

1476824834.187250 [0 127.0.0.1:52353] "select" "0"
1476824834.187587 [0 127.0.0.1:52353] "hmget" "sess_sgmeh2k3t7obl2tsot3h2ss0p1" "data" "writes"
1476824834.187939 [0 127.0.0.1:52353] "expire" "sess_sgmeh2k3t7obl2tsot3h2ss0p1" "1200"
1476824834.257226 [0 127.0.0.1:52353] "select" "0"
1476824834.257239 [0 127.0.0.1:52353] "hmset" "sess_sgmeh2k3t7obl2tsot3h2ss0p1" "data" "_session_validator_data|a:4:{s:11:\"remote_addr\";s:12:\"10.235.34.14\";s:8:\"http_via\";s:0:\"\";s:20:\"http_x_forwarded_for\";s:0:\"\";s:15:\"http_user_agent\";s:115:\"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/53.0.2785.143 Safari/537.36\";}_session_hosts|a:1:{s:12:\"10.235.32.10\";b:1;}admin|a:0:{}default|a:2:{s:9:\"_form_key\";s:16:\"e331ugBN7vRjGMgk\";s:12:\"visitor_data\";a:3:{s:13:\"last_visit_at\";s:19:\"2016-10-18 21:06:37\";s:10:\"session_id\";s:26:\"sgmeh2k3t7obl2tsot3h2ss0p1\";s:10:\"visitor_id\";s:1:\"9\";}}adminhtml|a:0:{}customer_base|a:1:{s:20:\"customer_segment_ids\";a:1:{i:1;a:0:{}}}checkout|a:0:{}" "lock" "0"
... more ...

Redis ping command

redis-cli ping

PONG should be the response.

If both commands succeeded, Redis is set up properly.