LFCE 64 🐧 Mail Server — Dovecot Basics - KandZ

⏱️ Estimated read: 12 min | |

Dovecot is the Mail Delivery Agent (MDA) and IMAP/POP3 server that completes the mail system Postfix started. Postfix moves mail between servers and delivers it to a local mailbox; Dovecot lets users read that mail. It serves the IMAP and POP3 protocols, which are the protocols mail clients use to retrieve messages, and it provides the authentication layer that verifies the user’s credentials before granting access to the mailbox. The previous chapter covered Postfix and the SMTP transport; this chapter covers the server that makes the delivered mail accessible.

The configuration differs significantly between Dovecot versions. Dovecot 2.4, released in 2025, changed the configuration syntax, renamed the TLS settings, and replaced the mail_location string with separate settings for the home directory, the driver, and the path . The configuration in this chapter targets the 2.4 syntax, with notes for the 2.3 settings that administrators migrating from older systems will recognize.

Key point: Dovecot is not an SMTP server. It does not accept mail from other servers; Postfix does that. Dovecot’s job is to authenticate users and serve their mailboxes over IMAP or POP3. The mail_home setting defines the user’s home directory, the mail_driver setting selects the mailbox format (Maildir or sdbox), and the mail_path setting points to the actual mail storage. The passdb block defines how passwords are verified, and the userdb block defines how the user’s UID, GID, and home directory are determined.

Why Dovecot requires version-specific configuration

The 2.4 syntax change.

Dovecot 2.4 replaced the single mail_location string with separate settings. The old form mail_location = maildir:~/Maildir becomes three settings: mail_driver = maildir, mail_path = ~/Maildir, and mail_home for the home directory . The TLS settings were also renamed: ssl_cert became ssl_server_cert_file, and ssl_key became ssl_server_key_file . An administrator following a 2.3 tutorial on a 2.4 system will find that the old settings are ignored or rejected.

The authentication problem.

Dovecot does not have a built-in user database. It uses passdb to verify passwords and userdb to look up the user’s attributes. For a simple system with local users, the pam passdb and the passwd userdb work without additional configuration. For virtual users—where the mail users are not system accounts—a passwd-file passdb and a static userdb are the simpler choice . The choice determines whether the system’s /etc/passwd is the source of truth or a separate file is.

The mail-storage problem.

Dovecot supports several mailbox formats. Maildir stores each message in a separate file and is the most portable. sdbox stores messages in a single file per mailbox and is more efficient for large mailboxes. mbox is deprecated and should only be used for legacy access . The format is selected by mail_driver, and the storage location by mail_path. The directory must be writable by the user that Dovecot runs as for mail access.

a. The basic configuration for system users

The simplest Dovecot configuration authenticates against the system’s PAM and delivers to the system user’s home directory.

# /etc/dovecot/dovecot.conf
protocols = imap pop3

mail_home = /home/%{user}
mail_driver = maildir
mail_path = ~/Maildir

passdb pam {
}

userdb passwd {
}

ssl = no
auth_allow_cleartext = yes

The protocols directive enables IMAP and POP3. The mail_home sets the home directory to the system user’s home. The mail_driver = maildir and mail_path = ~/Maildir point to the standard Maildir location . The passdb pam block tells Dovecot to verify passwords against PAM, and the userdb passwd block tells it to look up the user’s UID, GID, and home directory from /etc/passwd. The ssl = no and auth_allow_cleartext = yes disable TLS and allow plaintext authentication, which is acceptable only for testing on localhost.

The service must be restarted after the configuration change.

sudo systemctl restart dovecot
sudo systemctl status dovecot

The doveconf -n command shows the effective configuration, which is useful for confirming that the settings are being read.

sudo doveconf -n | head -30

b. Virtual users with a passwd-file

A virtual-user configuration uses a passwd file for authentication and a static userdb for the mail user’s UID and GID. The mail users are not system accounts; they exist only in the Dovecot configuration.

# Create the vmail user and group
sudo groupadd -g 5000 vmail
sudo useradd -g vmail -u 5000 -d /home/vmail -m vmail

# Create the mail directory
sudo mkdir -p /home/vmail
sudo chown vmail:vmail /home/vmail

# Create the password file
echo "test:{PLAIN}password" | sudo tee /etc/dovecot/passwd
sudo chown root:dovecot /etc/dovecot/passwd
sudo chmod 640 /etc/dovecot/passwd

The vmail user owns the mail storage. The password file contains one line per user in the format username:password. The {PLAIN} prefix indicates that the password is stored in plaintext, which is acceptable only for testing; the doveadm pw command generates hashed passwords .

# /etc/dovecot/dovecot.conf
protocols = imap

mail_home = /home/vmail/%{user}
mail_driver = maildir
mail_path = ~/Maildir

passdb passwd-file {
  passwd_file_path = /etc/dovecot/passwd
}

userdb static {
  fields {
    uid = vmail
    gid = vmail
    home = /home/vmail/%{user}
  }
}

ssl = no
auth_allow_cleartext = yes

The mail_home uses the %{user} variable to give each user a separate home directory under /home/vmail. The passdb passwd-file block reads the password file, and the userdb static block assigns the vmail UID and GID to every user . The home field in the static userdb overrides the mail_home setting for the home directory, which is necessary when the home directory depends on the username.

c. TLS and the 2.4 certificate settings

A production Dovecot configuration enables TLS for IMAP and POP3. The 2.4 settings use the ssl_server_* prefix, which replaced the 2.3 ssl_* settings.

# /etc/dovecot/dovecot.conf
ssl = required

ssl_server_cert_file = /etc/dovecot/ssl/fullchain.pem
ssl_server_key_file = /etc/dovecot/ssl/privkey.pem

ssl_min_protocol = TLSv1.2

The ssl = required directive disables plaintext authentication entirely. The ssl_server_cert_file and ssl_server_key_file point to the certificate and key. The ssl_min_protocol sets the minimum TLS version . The ssl = yes setting would allow both TLS and plaintext, which is useful during the transition but not recommended for production.

The certificate files must be readable by the Dovecot process. The dovecot user typically needs read access to the certificate and key.

sudo chown root:dovecot /etc/dovecot/ssl/fullchain.pem /etc/dovecot/ssl/privkey.pem
sudo chmod 640 /etc/dovecot/ssl/fullchain.pem /etc/dovecot/ssl/privkey.pem

Complete Example Session

# ============================================
# PART 1: INSTALL DOVECOT
# ============================================
sudo apt install dovecot-core dovecot-imapd
# Or: sudo dnf install dovecot

# ============================================
# PART 2: CREATE THE VMAIL USER
# ============================================
sudo groupadd -g 5000 vmail
sudo useradd -g vmail -u 5000 -d /home/vmail -m vmail
sudo mkdir -p /home/vmail
sudo chown vmail:vmail /home/vmail

# ============================================
# PART 3: CREATE THE PASSWORD FILE
# ============================================
echo "test:{PLAIN}password" | sudo tee /etc/dovecot/passwd
sudo chown root:dovecot /etc/dovecot/passwd
sudo chmod 640 /etc/dovecot/passwd

# ============================================
# PART 4: WRITE THE CONFIGURATION
# ============================================
sudo tee /etc/dovecot/dovecot.conf > /dev/null <<'EOF'
protocols = imap

mail_home = /home/vmail/%{user}
mail_driver = maildir
mail_path = ~/Maildir

passdb passwd-file {
  passwd_file_path = /etc/dovecot/passwd
}

userdb static {
  fields {
    uid = vmail
    gid = vmail
    home = /home/vmail/%{user}
  }
}

ssl = no
auth_allow_cleartext = yes
EOF

# ============================================
# PART 5: VALIDATE THE CONFIGURATION
# ============================================
sudo doveconf -n
# Output shows the effective configuration

# ============================================
# PART 6: RESTART DOVECOT
# ============================================
sudo systemctl restart dovecot
sudo systemctl status dovecot

# ============================================
# PART 7: CHECK THE LISTENING PORTS
# ============================================
sudo ss -tlnp | grep -E ":143|:993"
# Output: LISTEN 0 100 *:143 (IMAP) and *:993 (IMAPS)

# ============================================
# PART 8: TEST IMAP WITH TELNET
# ============================================
telnet localhost 143
# a LOGIN test password
# a LIST "" "*"
# a LOGOUT

# ============================================
# PART 9: CHECK THE MAIL DIRECTORY
# ============================================
ls -la /home/vmail/test/
# Output shows the Maildir directory created by Dovecot

# ============================================
# PART 10: CONFIGURE POSTFIX TO DELIVER VIA LMTP
# ============================================
# In Postfix main.cf:
# mailbox_transport = lmtp:unix:private/dovecot-lmtp
# Then Postfix delivers directly to Dovecot's LMTP socket

The ten parts demonstrate the Dovecot basics: installation, vmail user creation, password file, configuration, validation, service start, port check, IMAP test, mail directory inspection, and the Postfix integration. The critical verification is Part 8: the IMAP login succeeds, which confirms that the authentication and the mail location are configured correctly.

Quick Reference

Dovecot 2.4 Settings

Setting	Purpose	Example
`protocols`	Enabled protocols	`imap pop3`
`mail_home`	User’s home directory	`/home/vmail/%{user}`
`mail_driver`	Mailbox format	`maildir` or `sdbox`
`mail_path`	Mail storage path	`~/Maildir`
`passdb`	Password verification	`pam` or `passwd-file`
`userdb`	User attribute lookup	`passwd` or `static`
`ssl`	TLS requirement	`required` or `no`
`ssl_server_cert_file`	Certificate path	`/path/fullchain.pem`
`ssl_server_key_file`	Private key path	`/path/privkey.pem`

Mailbox Formats

Format	Driver	Use Case
Maildir	`maildir`	Portable; one file per message
sdbox	`sdbox`	Efficient for large mailboxes
mbox	`mbox`	Deprecated; legacy only

Verification Commands

Command	Purpose
`doveconf -n`	Show effective configuration
`doveadm pw -s sha256-crypt`	Generate a password hash
`systemctl status dovecot`	Check service state
`ss -tlnp \| grep :143`	Confirm IMAP listening
`telnet localhost 143`	Test IMAP manually

Best Practices

✅ Do This:

# Use the 2.4 syntax for mail location
mail_home = /home/vmail/%{user}
mail_driver = maildir
mail_path = ~/Maildir                                        # ✅

# Use a dedicated vmail user for virtual mail
useradd -g vmail -u 5000 -d /home/vmail -m vmail             # ✅

# Require TLS in production
ssl = required                                                # ✅

# Use hashed passwords, not plaintext
doveadm pw -s sha256-crypt                                    # ✅

# Validate with doveconf before restarting
doveconf -n                                                   # ✅

❌ Don’t Do This:

# Use the 2.3 mail_location string on 2.4
mail_location = maildir:~/Maildir    # Ignored in 2.4         # ❌

# Leave plaintext authentication enabled in production
auth_allow_cleartext = yes           # Credentials exposed    # ❌

# Run the mail storage as root
mail_uid = root                      # Security risk          # ❌

# Forget to chown the mail directory
chown root:root /home/vmail          # Dovecot cannot write   # ❌

# Use mbox for a new installation
mail_driver = mbox                   # Deprecated             # ❌

Common Pitfalls

Pitfall	Why It Happens	Fix
Login fails	Wrong passdb or password file permissions	Check `doveconf -n passdb`; verify file mode
Mail directory not created	`mail_home` or `mail_path` wrong	Verify the path and the vmail user’s ownership
Dovecot does not start	Configuration syntax error	`doveconf -n` reports the error
Port 143 not listening	Protocol not enabled	Add `imap` to `protocols`
Certificate permission denied	Key not readable by dovecot	`chown root:dovecot` and `chmod 640`

Real-World Examples

1. Basic system-user config

protocols = imap pop3
mail_home = /home/%{user}
mail_driver = maildir
mail_path = ~/Maildir
passdb pam { }
userdb passwd { }

2. Virtual user config

mail_home = /home/vmail/%{user}
mail_driver = maildir
mail_path = ~/Maildir
passdb passwd-file { passwd_file_path = /etc/dovecot/passwd }
userdb static { fields { uid = vmail gid = vmail home = /home/vmail/%{user} } }

3. TLS config

ssl = required
ssl_server_cert_file = /etc/dovecot/ssl/fullchain.pem
ssl_server_key_file = /etc/dovecot/ssl/privkey.pem

4. Password hash generation

doveadm pw -s sha256-crypt

5. Effective configuration

doveconf -n

6. Check IMAP port

ss -tlnp | grep :143

7. Test IMAP login

telnet localhost 143

8. Restart Dovecot

systemctl restart dovecot

9. Check service status

systemctl status dovecot

10. Postfix LMTP delivery

mailbox_transport = lmtp:unix:private/dovecot-lmtp

Visual

Dovecot’s Role in the Mail System

┌──────────────────────────────────────────────────────────────┐
│  POSTFIX MOVES MAIL; DOVECOT SERVES IT                       │
│                                                              │
│  MUA (Thunderbird)                                           │
│       │ IMAP/POP3                                            │
│       ▼                                                      │
│  ┌────────────────────────────────────────────────────────┐  │
│  │ Dovecot (MDA/IMAP server)                              │  │
│  │ ├── authenticates the user (passdb)                    │  │
│  │ ├── looks up the user's mail path (userdb)             │  │
│  │ └── serves the mailbox over IMAP/POP3                  │  │
│  └──────────────────────────┬─────────────────────────────┘  │
│                             │                                │
│                             ▼                                │
│  ┌────────────────────────────────────────────────────────┐  │
│  │ Mail storage                                           │  │
│  │ /home/vmail/test/Maildir/{new,cur,tmp}                 │  │
│  └────────────────────────────────────────────────────────┘  │
│                             ▲                                │
│                             │ LMTP                           │
│  ┌──────────────────────────┴─────────────────────────────┐  │
│  │ Postfix (MTA)                                          │  │
│  │ receives mail via SMTP and delivers to Dovecot         │  │
│  └────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────┘

2.4 Configuration Settings

┌──────────────────────────────────────────────────────────────┐
│  mail_location WAS REPLACED BY THREE SETTINGS                │
│                                                              │
│  2.3:                                                        │
│  mail_location = maildir:~/Maildir                           │
│                                                              │
│  2.4:                                                        │
│  mail_home = /home/%{user}                                   │
│  mail_driver = maildir                                       │
│  mail_path = ~/Maildir                                       │
│                                                              │
│  The home directory, the format, and the path are separate.  │
└──────────────────────────────────────────────────────────────┘

Authentication Flow

┌──────────────────────────────────────────────────────────────┐
│  PASSDB VERIFIES; USERDB LOOKS UP                             │
│                                                              │
│  Client → Dovecot: LOGIN test password                       │
│       │                                                      │
│       ▼                                                      │
│  passdb passwd-file                                          │
│  ├── reads /etc/dovecot/passwd                               │
│  └── verifies the password                                   │
│       │                                                      │
│       ▼ (if valid)                                           │
│  userdb static                                               │
│  ├── uid = vmail                                             │
│  ├── gid = vmail                                             │
│  └── home = /home/vmail/test                                 │
│       │                                                      │
│       ▼                                                      │
│  Dovecot serves the mailbox at that path.                    │
└──────────────────────────────────────────────────────────────┘

Summary

Item	Value
Role	MDA / IMAP / POP3 server
Configuration	`/etc/dovecot/dovecot.conf`
Protocols	`imap`, `pop3`
Mail format	`mail_driver = maildir` or `sdbox`
Mail path	`mail_path` setting
Home directory	`mail_home` setting
Authentication	`passdb` (pam or passwd-file)
User lookup	`userdb` (passwd or static)
TLS certificate (2.4)	`ssl_server_cert_file`
TLS key (2.4)	`ssl_server_key_file`
Effective config	`doveconf -n`
IMAP port	143 (plain), 993 (TLS)
POP3 port	110 (plain), 995 (TLS)

Key takeaways:

Dovecot is the IMAP/POP3 server, not the SMTP server. Postfix receives mail from other servers and delivers it locally. Dovecot lets users read that mail. The two services are complementary, not interchangeable.
The 2.4 configuration replaces mail_location with three settings. mail_home defines the user’s home directory, mail_driver selects the format, and mail_path points to the storage. The 2.3 string is not read by 2.4 .
Authentication is split between passdb and userdb. The passdb verifies the password, and the userdb looks up the UID, GID, and home directory. For virtual users, a passwd-file passdb and a static userdb are the simplest combination .
The vmail user owns the mail storage. The userdb must return the correct UID and GID, and the storage directory must be writable by that user. A permission mismatch produces a login failure or an empty mailbox.
TLS uses the ssl_server_* settings in 2.4. The ssl_server_cert_file and ssl_server_key_file replaced the 2.3 ssl_cert and ssl_key. The ssl = required directive disables plaintext authentication entirely .
doveconf -n shows the effective configuration. It is the equivalent of nginx -t and postfix check: the command that confirms the settings are being read and the syntax is valid before the service is restarted.

Remember: Dovecot completes the mail system. Postfix handles the SMTP transport; Dovecot handles the user access. The 2.4 configuration separates the home directory, the format, and the path into distinct settings. The passdb verifies the password, and the userdb provides the mail user’s identity. The vmail user owns the storage. TLS is required for production, and doveconf -n validates the configuration. Configure the mail location, define the authentication, set the TLS certificates, restart the service, and test with an IMAP login. The mail is accessible when the client can log in and list the mailbox.

Was this helpful?

Stop using slow, ad-bloated tool sites! 🤮

🔎 Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)

⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free

🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!