This documentation is for Dovecot v2.x, see wiki1 for v1.x documentation.
Differences between revisions 1 and 26 (spanning 25 versions)
Revision 1 as of 2006-05-12 23:15:15
Size: 1011
Editor: TimoSirainen
Comment:
Revision 26 as of 2017-11-21 14:56:25
Size: 4846
Editor: JeffKletsky
Comment: Consistent name of file in example
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
= passwd-file =

This file is compatible with regular `/etc/passwd` and a password file used by libpam-pwdfile. It's in the following format:
= Passwd-file =
This file is compatible with a normal `/etc/passwd` file, and a password file used by libpam-pwdfile [[PasswordDatabase/PAM|PAM]] plugin. It's in the following format:
Line 8: Line 7:
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). (gecos) and (shell) fields are unused by Dovecot.
Line 9: Line 9:
For password database, it's enough to have only user and password fields. For user database, you need to set also uid and gid and preferably home (see VirtualUsers). The password field can be in four formats:
Line 11: Line 11:
extra_fields is a space-separated list of key=value pairs which can be used to set various settings, for example you can override default_mail_env setting by giving `mail=mbox:~/mail`.  * `password`: Assume CRYPT [[Authentication/PasswordSchemes|password scheme]].
 * `{SCHEME}password`: The password is in the given [[Authentication/PasswordSchemes|scheme]].
 * `password[13]`: libpam-passwd file compatible format for CRYPT [[Authentication/PasswordSchemes|scheme]].
 * `password[34]`: libpam-passwd file compatible format for MD5 [[Authentication/PasswordSchemes|scheme]].
Line 13: Line 16:
The password field can be in three formats: extra_fields is a space-separated list of key=value pairs which can be used to set various [[PasswordDatabase/ExtraFields|passdb settings]] and [[UserDatabase/ExtraFields|userdb settings]]. Keys which begin with a `userdb_` prefix are used for userdb, others are used for passdb. So for example if you wish to override [[MailLocation|mail_location]] setting for one user, use `userdb_mail=mbox:~/mail`. [[Variables|Variable]] expansion is done for extra_fields.
Line 15: Line 18:
 * password: Assume CRYPT password scheme
 * password[type]: libpam-passwd file compatible format. Type is one of:
  * 13: CRYPT scheme
  * 34: MD5 scheme
 * {SCHEME}password
Empty lines and lines beginning with '#' character are ignored.
Line 21: Line 20:
Here's an example file for used by passdb: == Multiple passwd files ==
You can use all the [[Variables|variables]] in the passwd-file filenames, for example:
Line 24: Line 24:
user:{PLAIN}password 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 [[Authentication/PasswordSchemes|password scheme]]. 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. 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
}}}
== FreeBSD /etc/master.passwd as passdb and userdb ==
On FreeBSD, `/etc/passwd` doesn't work as a password database because the password field is replaced by a `*`. `/etc/master.passwd` can be converted into a format usable by passwd-file.

If only using the result for `name:password:uid:gid` and not using [[PasswordDatabase/ExtraFields]] you may be able to use the extract directly. However, the Linux-style passwd file has fewer fields than that used by FreeBSD and it will need to be edited if any fields past the first four are needed. In particular, it will fail if used directly as a `userdb` as the field used for `home` is not in the same place as expected by the Dovecot parser. The `:class:change:expire` stanza in each line should be removed to be consistent with the Linux-style format. While that stanza often is `::0:0` use of `cut` is likely much safer than `sed` or other blind substitution.

In `/etc/master.passwd`, a password of `*` indicates that password authentication is disabled for that user and the token `*LOCKED*` prevents all login authentication, so you might as well exclude those:

{{{#! sh
# fgrep -v '*' /etc/master.passwd | cut -d : -f 1-4,8-10 > /path/to/file-with-encrypted-passwords
# chmod 640 /path/to/file-with-encrypted-passwords
# chown root:dovecot /path/to/file-with-encrypted-passwords
Line 27: Line 78:
Or for passdb and userdb: or permissions and ownership that may be more appropriate for your install and security needs.

The following will work in many situations, after disabling the inclusion of other `userdb` and `passdb`sections
Line 30: Line 83:
user:{plain}pass:1000:1000::/home/user::mail=maildir:~/Maildir allow_nets=192.168.0.0/24 passdb {
  driver = passwd-file
  args = username_format=%n /path/to/file-with-encrypted-passwords
}
userdb {
  driver = passwd-file
  args = username_format=%n /path/to/file-with-encrypted-passwords
}

Passwd-file

This file is compatible with a normal /etc/passwd file, and a password file used by libpam-pwdfile PAM 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). (gecos) and (shell) fields are unused by Dovecot.

The password field can be in four formats:

  • password: Assume CRYPT password scheme.

  • {SCHEME}password: The password is in the given scheme.

  • password[13]: libpam-passwd file compatible format for CRYPT scheme.

  • password[34]: libpam-passwd file compatible format for MD5 scheme.

extra_fields is a space-separated list of key=value pairs which can be used to set various passdb settings and userdb settings. 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 setting for one user, use userdb_mail=mbox:~/mail. Variable expansion is done for extra_fields.

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

Multiple passwd files

You can use all the variables 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. 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. 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

FreeBSD /etc/master.passwd as passdb and userdb

On FreeBSD, /etc/passwd doesn't work as a password database because the password field is replaced by a *. /etc/master.passwd can be converted into a format usable by passwd-file.

If only using the result for name:password:uid:gid and not using PasswordDatabase/ExtraFields you may be able to use the extract directly. However, the Linux-style passwd file has fewer fields than that used by FreeBSD and it will need to be edited if any fields past the first four are needed. In particular, it will fail if used directly as a userdb as the field used for home is not in the same place as expected by the Dovecot parser. The :class:change:expire stanza in each line should be removed to be consistent with the Linux-style format. While that stanza often is ::0:0 use of cut is likely much safer than sed or other blind substitution.

In /etc/master.passwd, a password of * indicates that password authentication is disabled for that user and the token *LOCKED* prevents all login authentication, so you might as well exclude those:

# fgrep -v '*' /etc/master.passwd | cut -d : -f 1-4,8-10 > /path/to/file-with-encrypted-passwords
# chmod 640 /path/to/file-with-encrypted-passwords
# chown root:dovecot /path/to/file-with-encrypted-passwords

or permissions and ownership that may be more appropriate for your install and security needs.

The following will work in many situations, after disabling the inclusion of other userdb and passdbsections

passdb {
  driver = passwd-file
  args = username_format=%n /path/to/file-with-encrypted-passwords
}
userdb {
  driver = passwd-file
  args = username_format=%n /path/to/file-with-encrypted-passwords
}

None: AuthDatabase/PasswdFile (last edited 2019-09-11 14:15:57 by MichaelSlusarz)