--- a/dovecot-example.conf	Sun Oct 16 15:03:37 2005 +0300
+++ b/dovecot-example.conf	Sun Oct 16 15:49:14 2005 +0300
@@ -513,10 +513,13 @@
 # Set max. process size in megabytes.
 #auth_process_size = 256
 
-# Authentication cache size in kilobytes.
+# Authentication cache size in kilobytes. 0 means it's disabled.
+# Note that bsdauth, PAM and vpopmail require cache_key to be set for caching
+# to be used.
 #auth_cache_size = 0
-# Time to live in seconds for cached data. After this many seconds a cached
-# record is forced out of cache.
+# Time to live in seconds for cached data. After this many seconds the cached
+# record is no longer used, *except* if the main database lookup returns
+# internal failure.
 #auth_cache_ttl = 3600
 
 # Space separated list of realms for SASL authentication mechanisms that need
@@ -586,10 +589,21 @@
   # so it can't be used as userdb. If you don't want to use a separate user
   # database (passwd usually), you can use static userdb.
   passdb pam {
-    # [-session] [<service name>]
+    # [-session] [cache_key=<key>] [<service name>]
     #
     # -session makes Dovecot open and immediately close PAM session. Some
     # PAM plugins need this to work.
+    #
+    # cache_key can be used to enable authentication caching for PAM
+    # (auth_cache_size also needs to be set). It isn't enabled by default
+    # because PAM modules can do all kinds of checks besides checking password,
+    # such as checking IP address. Dovecot can't know about these checks
+    # without some help. cache_key is simply a list of variables (see
+    # doc/variables.txt) which must match for the cached data to be used.
+    # Here are some examples:
+    #   %u - Username must match. Probably sufficient for most uses.
+    #   %u%r - Username and remote IP address must match.
+    #   %u%s - Username and service (ie. IMAP, POP3) must match.
     # 
     # If service name is "*", it means the authenticating service name
     # is used, eg. pop3 or imap.
@@ -606,6 +620,12 @@
   #passdb shadow {
   #}
 
+  # BSD authentication. Used by at least OpenBSD.
+  #passdb bsdauth {
+    # [cache_key=<key>] - See cache_key in PAM for explanation.
+    #args =
+  #}
+
   # passwd-like file with specified location
   #passdb passwd-file {
     # Path for passwd-file
@@ -633,6 +653,8 @@
 
   # vpopmail authentication
   #passdb vpopmail {
+    # [cache_key=<key>] - See cache_key in PAM for explanation.
+    #args =
   #}
 
   #