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'. <Variable> [Variables.txt] expansion is done for
extra_fields.

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
}
---%<-------------------------------------------------------------------------

Passwd-file args
----------------

 * *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'.

Examples
--------

---%<-------------------------------------------------------------------------
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
  default_fields = uid=vmail gid=vmail home=/home/vmail/%u
}
---%<-------------------------------------------------------------------------

 * The default_fields is explained in <UserDatabase#Userdb_settings>
   [UserDatabase.txt]. They can be used to provide default userdb fields based
   on templates in case they're not specified for everyone in the passwd file.
   If you leave any of the standard userdb fields (uid, gid, home) empty, these
   defaults will be used.

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
---%<-------------------------------------------------------------------------

Passwd as a password database on FreeBSD
----------------------------------------

On FreeBSD, passwd doesn't work as a password database because the password
field is replaced by a '*'. But you can convert '/etc/master.passwd' into a
passwd-file. In '/etc/master.passwd', a password of '*' indicates that password
authentication is disabled, so you might as well exclude those:

---%<-------------------------------------------------------------------------
# grep -v '*' /etc/master.passwd > file-with-encrypted-passwords
# chmod 400 file-with-encrypted-passwords
# chown dovecot file-with-encrypted-passwords
---%<-------------------------------------------------------------------------

Then use:

---%<-------------------------------------------------------------------------
passdb {
  driver = passwd-file
  args = path-to-file-with-encrypted-passwords
}
---%<-------------------------------------------------------------------------

(This file was created from the wiki on 2017-05-11 04:42)