Test Dovecot Authentication Without Guessing What Failed

A login that fails gives no clue whether the password, the passdb, the socket or the cache is at fault, until you check each in order. This guide covers doveadm auth: checking a passdb lookup, testing a real login, and clearing stale cache entries. The examples target the installed Dovecot 2.3.21 package, reported here as dovecot-core 1:2.3.21+dfsg1-2ubuntu6.5.

Allow about fifteen minutes. You need shell access to the Dovecot host, the doveadm command, and a test account whose password you're allowed to use. Read-only lookups may work as an ordinary account, but reaching Dovecot's Unix sockets commonly needs the dovecot group or elevated privileges. Reach for sudo only when socket permissions require it.

1. Confirm the local command and version

Start with read-only checks, so the guide stays tied to what's actually installed:

$ command -v doveadm
/usr/bin/doveadm
$ dpkg-query -W -f='${Package} ${Version}\n' dovecot-core
dovecot-core 1:2.3.21+dfsg1-2ubuntu6.5
$ doveadm auth
usage: doveadm [-Dv] [-f <formatter>] auth <command> [<args>]

The local 2.3 command exposes cache flush, lookup and test. Don't copy options from documentation for a different release without checking doveadm auth on this machine: the local manpage is the contract for this workflow.

2. Check the auth sockets before testing

The three subcommands use different sockets by default. The local manpage lists these paths:

• /run/dovecot/auth-userdb for auth lookup
• /run/dovecot/auth-client for auth test
• /run/dovecot/auth-master for auth cache flush

Inspect them without changing anything:

$ sudo stat -c '%A %U:%G %n' /run/dovecot/auth-userdb /run/dovecot/auth-client /run/dovecot/auth-master
srw-rw---- dovecot:dovecot /run/dovecot/auth-userdb
srw-rw---- dovecot:dovecot /run/dovecot/auth-client
srw-rw---- dovecot:dovecot /run/dovecot/auth-master

Your ownership and mode may differ. A missing socket usually means Dovecot is stopped, its base_dir is elsewhere, or this isn't the instance serving your mail. -a selects an alternative absolute socket path when the config deliberately puts one elsewhere. Don't create a socket by hand.

3. Inspect passdb data with auth lookup

auth lookup runs a passdb lookup without authenticating anyone. It's useful for checking whether a login name reaches the expected backend:

$ sudo doveadm auth lookup '[email protected]'
passdb: [email protected]
  [email protected]

Output depends on the configured passdb and the fields it returns; some backends give more fields, and an unknown user or backend failure returns an error. The command accepts more than one user, so you can compare two known test identities in one go:

$ sudo doveadm auth lookup '[email protected]' '[email protected]'
passdb: [email protected]
  [email protected]
Error: authentication database lookup failed

Use -f field for one particular field:

$ sudo doveadm auth lookup -f user '[email protected]'
[email protected]

A successful lookup is not proof the password works. It checks passdb data, not authentication.

4. Test the password through the auth service

Use auth test for a real password check. Leave the password off the command line and doveadm prompts for it, which keeps the secret out of shell history:

$ sudo doveadm auth test -x service=imap -x rip=192.0.2.143 '[email protected]'
Password:
passdb: [email protected] auth succeeded
extra fields:
  [email protected]

service=imap models an IMAP login; use pop3 or smtp for whichever service you're diagnosing. rip is the client address Dovecot should evaluate, so swap in a permitted test value for the documentation address above. Other useful context fields: lip, lport, rport, local_name, client_id, session. Repeat -x for each one.

A failed test is only a symptom. Check the username spelling, service context, passdb logs and the socket you picked before touching the password database. A successful lookup followed by a failed test usually points at the password, the mechanism, or the context, not user discovery.

5. Add network context deliberately

Authentication decisions can depend on connection details. Start with the smallest test that reproduces the problem, then add only the fields that matter:

$ sudo doveadm auth test \
    -x service=smtp \
    -x rip=192.0.2.143 \
    -x local_name=mail.example.test \
    '[email protected]'
Password:
passdb: [email protected] auth succeeded

The manpage says these fields go to the auth process unvalidated, which makes them useful for reproducing policy decisions but also means a typo produces a misleading result. Record the exact values in a diagnostic note. For proxied connections, real_rip and real_lip represent the original endpoints, while rip and lip represent the proxy side.

6. Flush stale cache data only when needed

Authentication caching can keep an old result around after a password or backend change. Flushing is state-changing, so target the smallest scope first:

$ sudo doveadm auth cache flush '[email protected]'

With a username, only that user's cached data is cleared. With none, every user's cache is flushed:

$ sudo doveadm auth cache flush

Success usually produces no output. Re-run the exact auth test that failed and compare. Flushing doesn't repair a passdb, change a password or restart Dovecot: it only clears cached authentication data.

7. Separate permission errors from authentication failures

If the command can't connect to a socket, that isn't a bad password. Compare the socket path, service state and permissions:

$ sudo doveadm auth test '[email protected]'
Password:
Error: net_connect_unix(/run/dovecot/auth-client) failed: Permission denied
$ sudo doveadm auth test '[email protected]'
Password:
passdb: [email protected] auth succeeded

The exact error text varies. A missing socket, a permission denial and a rejected password are three different failures. If sudo only fixes the socket access, arrange the least-privileged operational access your team allows rather than making the socket world-writable. For a non-standard socket path, use the matching -a /absolute/path and verify it against the active configuration.