Edit Page

sails.config.session

Configuration for Sails built-in session store.

Sails session integration leans heavily on the great work already done by Express and Connect, but also adds a bit of its own special sauce to unify Socket.io with the Connect session store. It uses Connect’s cookie parser to normalize configuration differences between Express and Socket.io and hooks into Sails’ request interpreter to allow Sails to automatically access and auto-save changes your code makes to req.session when handling a virtual request from Socket.io. That means that you can just write code that uses req.session in the way you might be used to from Express or Connect.

Properties

Property	Default	Details
`adapter`	`undefined`	If left unspecified, Sails will use the default memory store bundled in the underlying session middleware. In production, you should specify the package name of a scalable session store instead (e.g. `connect-redis`). See below for details.
`key`	`sails.sid`	Session key is set as `sails.sid` by default. This is the name of the key which is added to the cookie of visitors to your site when sessions are enabled (which is the case by default for Sails apps). If you are running multiple different Sails apps from the same shared cookie namespace (i.e. the top-level DNS domain, like `frog-enthusiasts.net`), you must be especially careful to configure separate unique keys for each separate app, otherwise the wrong cookie could be used (like crossing streams)
`secret`	n/a	This session secret is automatically generated when your new app is created. Care should be taken any time this secret is changed in production-- doing so will invalidate the sesssion cookies of your users, forcing them to log in again. Note that this is also used as the "cookie secret" for signed cookies.
`cookie`	see express-session#cookie	Options for the session cookie. See the express-session docs for more info.
`routesDisabled`	`[]`	An array of route address strings for which built-in session support will be skipped. Useful for performance tuning; particularly preventing the unnecessary creation of sessions in requests for assets (e.g. `['GET /js/', 'GET /styles/', 'GET /images/*']`).

Production Config

In production, you should configure a session store that can be shared across multiple servers. To do so, you will need to set sails.config.session.adapter, set up your session database, and then add any other configuration specific to the Connect session adapter you are using.

Configuring Redis as Your Session Store

The most popular session store for production Sails applications is Redis. It works great as a session database since it is inherently good at ephemeral storage, but Redis' popularity probably has more to do with the fact that, if you are using sockets and plan to scale your app to multiple servers, you will need a Redis instance anyway.

The easiest way to set up Redis as your app's shared session store is to uncomment the following line in config/session.js:

adapter: 'connect-redis',

Then install the connect-redis session adapter as a dependency of your app:

npm install connect-redis@~3.0.2 --save --save-exact

The following settings are optional, since if no redis configuration other than adapter is provided, Sails assumes you want it to use a redis instance running on localhost.

host: 'localhost',
  port: 6379,
  ttl: <redis session TTL in seconds>,
  db: 0,
  pass: <redis auth password>
  prefix: 'sess:'

Property	Default	Details
`db`	`undefined`	The index of the database to use within your redis instance.
`host`	`'127.0.0.1'`	Hostname of your redis instance.
`pass`	`undefined`	The password for your redis instance. Leave blank if you are not using a password.
`port`	`6379`	Port of your redis instance.

Using Other Connect-Compatible Session Stores

Any session adapter written for Connect/Express works in Sails, as long as you use a compatible version.

For example, to use Mongo as your session store, install connect-mongo:

npm install [email protected] --save --save-exact

Then set the your adapter in config/session.js:

adapter: 'connect-mongo',

The following values are optional, and should only be used if relevant for your Mongo configuration. You can read more about these, and other available options, at https://github.com/kcbanner/connect-mongo:

// Note: user, pass and port are optional
  url: 'mongodb://user:pass@host:port/database',
  collection: 'sessions',
  auto_reconnect: false,
  ssl: false,
  stringify: true

Notes:

When using Node version <= 0.12.x, install connect-mongo version 0.8.2. For Node version >= 4.0, install connect-mongo version 1.1.0.

If you run into kerberos-related issues when using the MongoDB as your session store or the database for one or more of your app's models, be sure and have a look at the relevant troubleshooting page in the Mongo docs. Also see #3362 for more diagnostic information about using Kerberos with Mongo in your Sails app.

Disabling sessions

Sessions are enabled by default in Sails. To disable sessions in your app, disable the session hook by changing your .sailsrc file. The process for disabling session is identical to the process for disabling the Grunt hook (just type session: false instead of grunt: false).

Note: If the session hook is disabled, the session secret configured as sails.config.session.secret will still be used to support signed cookies, if relevant. If the session hook is disabled AND no session secret configuration exists for your app (e.g. because you deleted config/session.js), then signed cookies will not be usable in your application. To make more advanced changes to this behavior, you can customize any of your app's HTTP middleware manually using sails.config.http.

Is something missing?

If you notice something we've missed or could be improved on, please follow this link and submit a pull request to the sails-docs repo. Once we merge it, the changes will be reflected on the website the next time it is deployed.

Documentation

Reference

Built with Love

The Sails framework is maintained by a web & mobile studio in Austin, TX, with the help of our contributors. We created Sails in 2012 to assist us on Node.js projects. Naturally we open-sourced it. We hope it makes your life a little bit easier!