Caching of authentication results
=================================

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

 * Data is used from cache if it's not expired ('auth_cache_ttl' setting)
    * If authentication fails this time, but it didn't fail last time, it's
      assumed that the password had changed and the database lookup is done.
 * If database lookup failed because of some internal error, but data still
   exists in cache (even if expired), the cached data is used. This allows
   Dovecot to log in some users even if the database is temporarily down.

Authentication cache can be flushed by sending SIGHUP to dovecot-auth.

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

Settings
--------

The settings related to authentication cache are:

 * 'auth_cache_size': Authentication cache size in kilobytes, 0 disables
   caching (default). A typical passdb cache entry is around 50 bytes and a
   typical userdb cache entry is around 100-200 bytes, depending on the amount
   of information your user and password database lookups return.
 * 'auth_cache_ttl': Time to live in seconds for cache entries. A cache entry
   is no longer used (except for internal failures) if it was created more than
   this many seconds ago. Entries are removed from cache only when the cache is
   full and a new entry is being added.
 * 'auth_cache_negative_ttl': (v1.1+ only) If passdb or userdb lookup didn't
   return any data (i.e. user didn't exist), it's also stored to cache as a
   negative entry. This setting allows you to give negative entries a different
   TTL. 0 disables negative caching completely.

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> [Variables.txt] 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 it to Dovecot manually. The following databases require specifying
cache key:

 * vpopmail
 * pam
 * bsdauth

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

---%<-------------------------------------------------------------------------
passdb pam {
  args = cache_key=%s%u *
}
---%<-------------------------------------------------------------------------

(This file was created from the wiki on 2007-10-31 04:42)
