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

Caching of authentication results

Dovecot supports caching the results of password and user database lookups. The following rules apply to using the authentication cache:

The authentication cache can be flushed by sending a SIGHUP to dovecot-auth.

Sending SIGUSR2 to dovecot-auth makes it log the number of cache hits and misses. You can use that information for tuning the cache size and TTL.

Settings

The settings related to the authentication cache are:

It should be pretty safe to set very high TTLs, because the only field that usually can change is the user's password, and Dovecot attempts to catch those cases (see the rules above).

Cache keys

Usually only the username uniquely identifies a user, but in some setups you may need something more, for example the remote IP address. For SQL and LDAP lookups Dovecot figures this out automatically by using all the used %variables as the cache key. For example if your SQL query contains %s, %u and %r the cache entry is used only if all of them (service name, username and remote IP) match for the new lookup.

With other databases Dovecot doesn't know what could affect caching, so you have to tell Dovecot manually. The following databases require specifying the cache key:

For example if the PAM lookup depends on username and service, you can use:

passdb {
  driver = pam
  args = cache_key=%s%u *
}

Password changing scenarios

Normal scenario:

  1. User logs in with password X. The password X is added to cache and login succeeds.
  2. Password is changed to Y.
  3. User logs in with password Y. The cached password X doesn't match Y, but since the previous authentication was successful Dovecot does another backend passdb lookup to see if the password changed. It did, so the password Y is cached and login succeeds.

Using old cached password scenario:

  1. User logs in with password X. The password X is added to cache and login succeeds.
  2. Password is changed to Y.
  3. User logs in with password X. The cached password X matches X, so login succeeds.

Early change scenario:

  1. User logs in with password X. The password X is added to cache and login succeeds.
  2. User logs in with password Y. The cached password X doesn't match Y, but since the previous authentication was successful Dovecot does another backend passdb lookup to see if the password changed. It didn't, so the login fails.
  3. Password is changed to Y.
  4. User logs in with password Y. The cached password X doesn't match Y and the previous authentication was unsuccessful, so Dovecot doesn't bother doing another backend passdb lookup (until cache TTL expires). The login fails.

Authentication/Caching (last edited 2012-01-16 13:27:39 by TimoSirainen)