---
title: Setting up Dovecot
lastUpdated: 2023-10-04
slug: ispmail-bookworm/setting-up-dovecot
sidebar:
order: 120
---
import { Aside } from "@astrojs/starlight/components";
This chapter of our journey leads us to Dovecot – the software that…
- gets emails destined to your users from Postfix and saves them to disk
- executes user-based _sieve_ filter rules (can be used to e.g. move emails to different folders based on certain
criteria or to send automated vacation responses)
- allows the user to fetch emails using POP3 or IMAP
Before we get to the actual configuration for security reasons I recommend that you create a new system user that will
own all virtual mailboxes. The following shell commands will create a system group “vmail” with GID (group ID) 5000 and
a system user “vmail” with UID (user ID) 5000. (Make sure that UID and GID are not yet used or choose another – the
number can be anything between 1000 and 65000 that is not yet used):
```
groupadd -g 5000 vmail
useradd -g vmail -u 5000 vmail -d /var/vmail -m
```
If the /var/vmail directory was already there because you assigned it a dedicated mount point then you should make sure
that the permissions are set correctly:
```
chown -R vmail:vmail /var/vmail
```
The configuration files for Dovecot are found in `/etc/dovecot/conf.d`. All these files are loaded by Dovecot. This is
done by this magical line at the end of the `/etc/dovecot/dovecot.conf` file:
```
!include conf.d/*.conf
```
It loads all files in `/etc/dovecot/conf.d/` that end in “.conf” in alphanumerical order. So “10-auth.conf” is loaded
first and “90-sieve-extprograms.conf” is loaded last. The big advantage is that you can edit or replace parts of the
configuration without having to overwrite the entire configuration. The main `/etc/dovecot/dovecot.conf` file does not
require any changes. Those other files in conf.d/ however do.
## conf.d/
### 10-auth.conf
The most common
[authentication mechanism](https://doc.dovecot.org/configuration_manual/authentication/authentication_mechanisms/#authentication-authentication-mechanisms)
is called _PLAIN_. However if you have Outl\*\*k users then you may need to add the _LOGIN_ mechanism, too.:
```
auth_mechanisms = plain login
```
These two mechanisms would ask for a password without enforcing encryption to secure the password. But don’t worry. By
default Dovecot sets `disable_plaintext_auth = yes` which ensures that authentication is only accepted over
TLS-encrypted connections.
At the end of this file you will find various authentication backends that Dovecot ships with. By default it will use
system users (those from the /etc/passwd). But we want to use the MariaDB database backend so go ahead and change this
block to:
```
#!include auth-system.conf.ext
!include auth-sql.conf.ext
#!include auth-ldap.conf.ext
#!include auth-passwdfile.conf.ext
#!include auth-checkpassword.conf.ext
#!include auth-static.conf.ext
```
### 10-mail.conf
Change the mail_location setting to:
```
mail_location = maildir:~/Maildir
```
This is the directory where Dovecot will look for the emails of a specific user. The tilde character (~) means the
user’s _home directory_. That does not make sense yet. But further down on this page we will tell Dovecot what the _home
directory_ is supposed to mean. For example `john@example.org` will have his home directory in
/var/vmail/example.org/john.
Further down in the 10-mail.conf file you will find sections defining the
[namespaces](https://doc.dovecot.org/configuration_manual/namespace/). Those are folder structures that your email
program sees when connecting to the mail server. If you use POP3 you can only access the “inbox” – which is where all
incoming email is stored. Using the IMAP protocol you get access to a hierarchy of folders and subfolders. And you can
even share folders between users. Or use a public folder that can be accessed by anyone – even anonymously. So IMAP is
generally to be preferred.
Also edit the “mail*plugins” line to enable the \_quota* plugin we will configure later and turn it into:
```
mail_plugins = quota
```
### 10-master.conf
This configuration file deals with typical service ports like IMAP or POP3.
So most settings are sane here and do not have to be changed. However one change is required in the “service auth”
section because we want Postfix to allow Dovecot as an authentication service. Make it look like this:
```
# Postfix smtp-auth
unix_listener /var/spool/postfix/private/auth {
mode = 0660
user = postfix
group = postfix
}
```
Well, Postfix runs in a chroot environment located at /var/spool/postfix. It can't access anything outside of that
directory. So to allow communication with Postfix we tell Dovecot to place a communication socket into that chroot.
### 10-ssl.conf
Earlier in this guide you created both a key and a certificate file to encrypt the communication with POP3, IMAPs and
HTTPS between the users and your mail server. You need to tell Dovecot where to find these files:
```
ssl\_cert = \
Ending a line with a backslash (\) means that it is continued on the next line. It keeps the configuration more
readable when it is split over multiple lines.
What these lines mean:
- driver: the kind of database. MariaDB is the same kind as MySQL.
- connect: where to find the MySQL database and how to access it (username, password)
- user_query: an SQL query that returns the user name (=the email address), the quota, the home directory, user ID and
group ID.
- password_query: this SQL query just gets the password hash from the database
- iterate_query: ‘doveadm’ uses this query to get a list of all users. That allows you to use the “doveadm user ‘\*'”
command later.
The _user_query_ gets several pieces of information from the database. Let’s look at it one by one:
- email AS user
It gets the the _email_ field from the database which corresponds to the user name. Dovecot expects it in the _user_
field so we set an alias to _“user”._
- userdb_quota_rule
This is the user’s quota in bytes. Think of it as the maximum possible space on disk that the user can occupy. As
[documented](https://doc.dovecot.org/configuration_manual/quota/#per-user-quota) Dovecot expects the quota in a
special format like “\*:bytes=10000” if the user should not be able to store more than 10,000 bytes. That’s why we
begin the string with ‘\*:bytes=’.
- userdb_home
This leads to the directory where all emails and various control files for this user are located. The placeholder
‘%d’ replaces the domain and ‘%n’ the user part. So for John that makes it “/var/vmail/example.org/john”.
- userdb*uid and userdb_gid
Those are the user ID and group ID of \_vmail* user – 5000 for both. Dovecot uses it to set the permissions of files
it creates. As all users share the same system user “vmail” this is just a static number.s
## Fix permissions
Make sure that only root can access the SQL configuration file so nobody else is reading your database access passwords:
```
chown root:root /etc/dovecot/dovecot-sql.conf.ext
chmod go= /etc/dovecot/dovecot-sql.conf.ext
```
Restart Dovecot from the shell:
```
systemctl restart dovecot
```
Look at your /var/log/mail.log logfile. You should see:
```
... Dovecot v2.3.13 (f79e8e7e4) starting up for imap, lmtp, sieve, pop3 (core dumps disabled)
```
If you get any error messages please double-check your configuration files.