Passwd-file
===========

This file is compatible with a normal '/etc/passwd' file, and a password file
used by libpam-pwdfile <PAM> [PasswordDatabase.PAM.txt] plugin. It's in the
following format:

---%<-------------------------------------------------------------------------
user:password:uid:gid:(gecos):home:(shell):extra_fields
---%<-------------------------------------------------------------------------

For a password database it's enough to have only the user and password fields.
For a user database, you need to set also uid, gid and preferably also home
(see <VirtualUsers.txt>). (gecos) and (shell) fields are unused by Dovecot.

The password field can be in four formats:

 * 'password': Assume CRYPT <password scheme>
   [Authentication.PasswordSchemes.txt].
 * '{SCHEME}password': The password is in the given <scheme>
   [Authentication.PasswordSchemes.txt].
 * 'password[13]': libpam-passwd file compatible format for CRYPT <scheme>
   [Authentication.PasswordSchemes.txt].
 * 'password[34]': libpam-passwd file compatible format for MD5 <scheme>
   [Authentication.PasswordSchemes.txt].

extra_fields is a space-separated list of key=value pairs which can be used to
set various <passdb settings> [PasswordDatabase.ExtraFields.txt] and <userdb
settings> [UserDatabase.ExtraFields.txt]. Keys which begin with a 'userdb_'
prefix are used for userdb, others are used for passdb. So for example if you
wish to override <mail_location> [MailLocation.txt] setting for one user, use
'userdb_mail=mbox:~/mail'.

Empty lines and lines beginning with '#' character are ignored.

Multiple passwd files
---------------------

You can use all the <variables> [Variables.txt] in the passwd-file filenames,
for example:

---%<-------------------------------------------------------------------------
passdb {
  driver = passwd-file
  # Each domain has a separate passwd-file:
  args = /etc/auth/%d/passwd
}
---%<-------------------------------------------------------------------------

Parameters
----------

 * *scheme=<s>*: Allows you to specify the default <password scheme>
   [Authentication.PasswordSchemes.txt]. The default is CRYPT. This is
   available only for passdb.
 * *username_format=<s>*: Look up usernames using this format instead of the
   full username ('%u'). If you want to enable user@domain logins but have only
   "user" in the file, set this to '%n'.

For example:

---%<-------------------------------------------------------------------------
passdb {
  driver = passwd-file
  args = scheme=plain-md5 username_format=%n /etc/imap.passwd
}
userdb {
  driver = passwd-file
  args = username_format=%n /etc/imap.passwd
}
---%<-------------------------------------------------------------------------

Examples
--------

This file can be used as a passdb:

---%<-------------------------------------------------------------------------
user:{plain}password
user2:{plain}password2
---%<-------------------------------------------------------------------------

passdb with extra fields:

---%<-------------------------------------------------------------------------
user:{plain}password::::::allow_nets=192.168.0.0/24
---%<-------------------------------------------------------------------------

This file can be used as both a passwd and a userdb:

---%<-------------------------------------------------------------------------
user:{plain}pass:1000:1000::/home/user::userdb_mail=maildir:~/Maildir
allow_nets=192.168.0.0/24
user2:{plain}pass2:1001:1001::/home/user2
---%<-------------------------------------------------------------------------

(This file was created from the wiki on 2011-11-16 14:09)