This documentation is for Dovecot v2.x, see wiki1 for v1.x documentation.

Login referrals

Login referrals are an IMAP extension specified by RFC 2221. Their purpose is to redirect clients to an different IMAP4 server in case of hardware failures or organizational changes. No client action is needed to invoke the LOGIN-REFERRALS capability: the redirection is triggered by the server and occurs transparently.

A security consideration is in order. As also stated by RFC 2221, a man in the middle attack may use a rogue 'password catching' server to collect login data and redirect your clients to their own rogue IMAP4 server. Although this would be avoided by enforcing SSL/TLS. Login referrals are not supported by many clients, so you probably don't want to use them anyway.

Dovecot does not use login referrals by default.


Note that the "host" field is also used by proxying. Login referrals are used only if the proxy field isn't set.

Login referrals can be used in two ways:

  1. Tell the client to log into another server without allowing to log in locally.
  2. Suggest the client to log into another server, but log it in anyway.

The following fields can be used to configure login referrals:

Using the above settings you can suggest client to log in elsewhere. To require it, you'll also have to return:

Client support

The following clients are known to support login referrals:


Forward user to another server after successful authentication:

password_query = SELECT password, host, 'Y' as nologin FROM users WHERE userid = '%u'

Forward all users to another server without authentication:

password_query = \
  SELECT NULL AS password, 'Y' AS nopassword \
  '' AS host, \
  'This server is down, try another one.' AS reason, \
  'Y' AS nologin, \
  'Y' AS nodelay