Lesson 008 · Linux MTA Operations Learning Path

Dovecot SQL Virtual Users, Maildir and Mail Protocols

Anil Jalela · Published Sep 3, 2026 · 7 min read

Dovecot verifies mailbox credentials and maps virtual users to stable storage identities without creating a Linux account for every address. This lesson treats Dovecot SQL virtual users and Maildir as one decision point in a longer message path. The configuration is useful only when an operator can show which message entered it, which identity and rule matched, what the next daemon returned, and how a failure is retried or contained.

Prerequisites and inherited lab checkpoint

Use the SELECT-only SQL identity and active, disabled and missing fixtures from Lesson 4, plus the recipient truth from Lesson 5.

For the Dovecot SQL virtual users and Maildir lab, use reserved domain example.test, documentation addresses and disposable messages. Preserve postconf -n, postconf -M, package versions, DNS answers and a queue baseline before changing the lab. Keep console access and do not copy credentials, private keys or customer messages into the evidence record.

Install and prepare the required components

sudo dnf info dovecot dovecot-mysql
sudo dnf install -y dovecot dovecot-mysql
sudo cp -a /etc/dovecot /etc/dovecot.before-nitwings
rpm -q dovecot dovecot-mysql

• Confirm package availability and ownership in the enabled RHEL repositories before adding a third-party source. Record the repository, signing key fingerprint, version and support lifecycle.
• A package install creates files and service identities; it does not establish safe relay, authentication, delivery or filtering behavior.
• Back up only the files this lesson changes and record modes, owners and SELinux labels so rollback restores more than text.
• Use systemctl cat, package file lists and local manual pages to identify paths on the installed build instead of assuming a path from another distribution.

Build the Dovecot SQL virtual users and Maildir configuration and understand every boundary

Use one bounded vmail UID and a root-readable SQL query file. Confirm variable syntax against the installed Dovecot major version.

# 90-virtual-sql.conf
protocols = imap lmtp
mail_driver = maildir
mail_path = /var/vmail/%{user | domain}/%{user | username}/Maildir
first_valid_uid = 5000
last_valid_uid = 5000
passdb sql {
  driver = mysql
  args = /etc/dovecot/dovecot-sql.conf.ext
}
userdb static {
  fields { uid = 5000 gid = 5000 home = /var/vmail/%{user | domain}/%{user | username} }
}

Passdb answers authentication. Userdb supplies UID, GID, home and mailbox location. The SQL file contains a generated secret and therefore stays root-owned with mode 0600.

Verify the working path

sudo chmod 0600 /etc/dovecot/dovecot-sql.conf.ext
sudo doveconf -n
sudo doveadm auth test [email protected]
sudo doveadm user [email protected]
sudo doveadm auth test [email protected]
sudo systemctl enable --now dovecot
sudo ss -lntp | grep -E ':(143|993) '

• Run the syntax or lookup test before reload. A reload must never be the first parser of a production configuration.
• The positive test proves the intended path. The negative test proves an unauthorized sender, recipient or client is not accidentally accepted.
• Stop the named dependency in the disposable lab and verify temporary failure or controlled bypass matches the documented policy.
• Repeat the accepted path after restart and reboot, then compare effective configuration rather than only source files.

Production decisions before continuing

Place Dovecot SQL virtual users and Maildir in the message path

Maildir stores one message per file under new, cur and tmp. Dovecot indexes can often be rebuilt, but message files, subscriptions and Sieve state require backup.

Understand the component before configuring it

Build it step by step

1. Draw the path. Mark the connection, envelope, content and authenticated identities available at this stage.
2. Inventory the effective state. Capture package version, active service, sockets, Postfix parameters, master services and lookup results.
3. Prepare one coherent configuration. Substitute documented lab values and verify ownership, mode and SELinux context.
4. Validate before activation. Run component syntax checks, map queries and a non-delivering test where supported.
5. Exercise three outcomes. Send an intended message, an intended denial and a message while the named dependency is unavailable.
6. Trace one queue ID. Join ingress, policy, filtering, routing and final delivery events without relying on subject text.
7. Close the change. Restart or reboot where relevant, repeat tests, check queue age and document rollback.

Operate and inspect the component

doveconf -n
doveadm auth test [email protected]
doveadm user [email protected]
doveadm mailbox list -u [email protected]
namei -om /var/vmail/example.test/user/Maildir
ls -ldZ /var/vmail/example.test/user
journalctl -u dovecot --since '-15 minutes'

• Replace sample hostnames, addresses and queue IDs only after resolving them from the lab. Do not paste production identities into a public command transcript.
• postconf -n shows non-default global parameters; postconf -M and postconf -P expose master service and field overrides.
• A successful lookup proves only that input. Test present, absent, disabled and dependency-unavailable results separately.
• Use the queue ID as the correlation key. Message subjects and recipient addresses are not unique and may contain sensitive information.

Evidence and acceptance criteria

Root-owned Maildir breaks a valid login

A manual delivery test creates the first mailbox as root. Authentication works, but IMAP cannot update indexes or move messages. Mode 0777 would hide the model failure; the repair is bounded vmail ownership plus restored SELinux labels.

Troubleshooting by symptom

Unsafe operations and recovery boundaries

• Unsafe: mode 0777 on /var/vmail exposes message data.
• Unsafe: plaintext or command-line passwords disclose credentials.
• Unsafe: changing the vmail UID after data exists strands ownership.

Rewritten knowledge checks

What does passdb return?

Authentication success and credential-related fields.

What does userdb return?

UID, GID, home and mailbox attributes.

Are Dovecot index files a backup?

No. They are metadata and do not replace mailbox backup.

Why test an absent value?

It proves the configuration denies or returns not-found instead of matching a broad default.

Why retain a queue ID?

It joins SMTP, policy, routing, filtering and delivery evidence without relying on non-unique subject text.

What must be captured before this change?

The effective configuration, package versions, owned sockets, a UTC test result and the exact files or database rows that rollback will restore.

Why is a service restart not an acceptance test?

A running process does not prove the intended message path, denial path, dependency failure behavior or persistence.

What makes a placeholder safe to replace?

Its source, format, owner and scope are explained and the substituted value is verified before activation.

When should rollout stop?

Stop when identity is ambiguous, syntax fails, the negative test becomes permissive, a dependency failure produces permanent loss or rollback cannot be executed.

What evidence belongs in handover?

The reviewed configuration, syntax output, positive and negative transcripts, logs, monitoring threshold, backup location and tested rollback result.

Cumulative lab checkpoint

1. Capture the inherited checkpoint and state the exact sender, recipient, client address and expected SMTP result.
2. Install the required package from a recorded source and save the package/file/service inventory.
3. Apply the complete lab configuration, including permissions, socket paths, map generation and service ownership.
4. Run syntax and lookup validation, then activate without closing the recovery session.
5. Complete positive, negative and dependency-outage tests while retaining queue IDs and UTC logs.
6. Restart the participating services, repeat the accepted path and confirm no unexplained deferred mail remains.
7. Execute rollback once, prove the previous behavior, then reapply the reviewed state as the checkpoint for the next lesson.

Primary references

• Dovecot CE documentation
• Dovecot SQL authentication
• Dovecot LMTP with Postfix