--- a/dovecot-example.conf	Mon Mar 07 11:42:54 2005 +0200
+++ b/dovecot-example.conf	Mon Mar 07 20:55:13 2005 +0200
@@ -484,12 +484,6 @@
 ## Authentication processes
 ##
 
-# You can have multiple authentication processes. With plaintext authentication
-# the password is checked against each process, the first one which succeeds is
-# used. This is useful if you want to allow both system users (/etc/passwd)
-# and virtual users to login without duplicating the system users into virtual
-# database.
-
 # Executable location
 #auth_executable = /usr/libexec/dovecot/dovecot-auth
 
@@ -545,29 +539,111 @@
   #   plain digest-md5 cram-md5 apop anonymous
   mechanisms = plain
 
-  # Password database specifies only the passwords for users.
+  #
+  # Password database is used to verify user's password (and nothing more).
+  # You can have multiple passdbs and userdbs. This is useful if you want to
+  # allow both system users (/etc/passwd) and virtual users to login without
+  # duplicating the system users into virtual database.
+  #
   # http://wiki.dovecot.org/Authentication
-  #   passwd: /etc/passwd or similiar, using getpwnam()
-  #   shadow: /etc/shadow or similiar, using getspnam()
-  #   pam [<service> | *]: PAM authentication
-  #   checkpassword <path>: checkpassword executable authentication
-  #   passwd-file <path>: passwd-like file with specified location
-  #   vpopmail: vpopmail authentication
-  #   ldap <config path>: LDAP, see doc/dovecot-ldap.conf
-  #   sql <config path>: SQL database, see doc/dovecot-sql.conf
-  passdb = pam
+  #
+
+  # PAM authentication. Preferred nowadays by most systems.
+  # Note that PAM can only be used to verify if user's password is correct,
+  # 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 {
+    # Service name or * as parameter. * means the authenticating service name
+    # is used, eg. pop3 or imap.
+    #args = dovecot
+  }
+
+  # /etc/passwd or similar, using getpwnam()
+  # In many systems nowadays this uses Name Service Switch, which is
+  # configured in /etc/nsswitch.conf.
+  #passdb passwd {
+  #}
+
+  # /etc/shadow or similiar, using getspnam(). Deprecated by PAM nowadays.
+  #passdb shadow {
+  #}
 
+  # passwd-like file with specified location
+  #passdb passwd-file {
+    # Path for passwd-file
+    #args = 
+  #}
+
+  # checkpassword executable authentication
+  #passdb checkpassword {
+    # Path for checkpassword binary
+    #args = 
+  #}
+
+  # SQL database
+  #passdb sql {
+    # Path for SQL configuration file, see doc/dovecot-sql.conf for example
+    #args = 
+  #}
+
+  # LDAP database
+  #passdb ldap {
+    # Path for LDAP configuration file, see doc/dovecot-ldap.conf for example
+    #args = 
+  #}
+
+  # vpopmail authentication
+  #passdb vpopmail {
+  #}
+
+  #
   # User database specifies where mails are located and what user/group IDs
   # own them. For single-UID configuration use "static".
+  #
   # http://wiki.dovecot.org/Authentication
   # http://wiki.dovecot.org/VirtualUsers
-  #   passwd: /etc/passwd or similiar, using getpwnam()
-  #   passwd-file <path>: passwd-like file with specified location
-  #   static uid=<uid> gid=<gid> home=<dir template>: static settings
-  #   vpopmail: vpopmail library
-  #   ldap <config path>: LDAP, see doc/dovecot-ldap.conf
-  #   sql <config path>: SQL database, see doc/dovecot-sql.conf
-  userdb = passwd
+  #
+
+  # /etc/passwd or similar, using getpwnam()
+  # In many systems nowadays this uses Name Service Switch, which is
+  # configured in /etc/nsswitch.conf.
+  userdb passwd {
+  }
+
+  # passwd-like file with specified location
+  #userdb passwd-file {
+    # Path for passwd-file
+    #args =
+  #}
+
+  # static settings generated from template
+  #userdb static {
+    # Template for settings. Can return anything a userdb could normally
+    # return, eg.: uid, gid, home, mail, nice
+    #
+    # A few examples:
+    #
+    #  args = uid=500 gid=500 home=/var/mail/%u
+    #  args = uid=500 gid=500 home=/home/%u mail=mbox:%h/mail nice=10
+    #
+    #args =
+  #}
+
+  # SQL database
+  #userdb sql {
+    # Path for SQL configuration file, see doc/dovecot-sql.conf for example
+    #args = 
+  #}
+
+  # LDAP database
+  #userdb ldap {
+    # Path for LDAP configuration file, see doc/dovecot-ldap.conf for example
+    #args = 
+  #}
+
+  # vpopmail
+  #userdb vpopmail {
+  #}
 
   # User to use for the process. This user needs access to only user and
   # password databases, nothing else. Only shadow and pam authentication
@@ -579,6 +655,7 @@
 
   # Directory where to chroot the process. Most authentication backends don't
   # work if this is set, and there's no point chrooting if auth_user is root.
+  # Note that valid_chroot_dirs isn't needed to use this setting.
   #chroot = 
 
   # Number of authentication processes to create
@@ -588,31 +665,6 @@
   #ssl_require_client_cert = no
 }
 
-# PAM doesn't provide a way to get uid, gid or home directory. If you don't
-# want to use a separate user database (passwd usually), you can use static
-# userdb.
-
-#auth onlypam {
-#  mechanisms = plain
-#  userdb = static uid=500 gid=500 home=/var/mail/%u
-#  passdb = pam
-#  user = dovecot-auth
-#}
-
-#auth ldap {
-#  mechanisms = plain
-#  userdb = ldap /etc/dovecot-ldap.conf
-#  passdb = ldap /etc/dovecot-ldap.conf
-#  user = dovecot-auth
-#}
-
-#auth virtualfile {
-#  mechanisms = plain digest-md5
-#  userdb = passwd-file /etc/passwd.imap
-#  passdb = passwd-file /etc/passwd.imap
-#  user = dovecot-auth
-#}
-
 # It's possible to export the authentication interface to other programs,
 # for example SMTP server which supports talking to Dovecot. Client socket
 # handles the actual authentication - you give it a username and password
@@ -624,8 +676,10 @@
 # settings given inside the auth section
 #auth default_with_listener {
 #  mechanisms = plain
-#  passdb = passwd
-#  userdb = pam
+#  passdb passwd {
+#  }
+#  userdb pam {
+#  }
 #  socket listen {
 #    master {
 #      path = /var/run/dovecot/auth-master