Generate and Verify Dovecot Password Hashes with doveadm pw

You will create a Dovecot password hash, check that it matches the intended password, and leave the original password out of the command history. The examples use Dovecot 2.3.21 from the installed dovecot-core package. Allow about ten minutes. You need a shell and the Dovecot utilities; no service restart or configuration edit is required.

1. Check the installed command

Start with ordinary, read-only checks. This identifies the binary and package version you are about to use:

$ command -v doveadm
/usr/bin/doveadm
$ dpkg-query -W -f='${Package} ${Version}\n' dovecot-core
dovecot-core 1:2.3.21+dfsg1-2ubuntu6.5

Your package revision may differ. The manual page installed with this package documents doveadm pw as Dovecot v2.3, and the exact list of schemes depends partly on the libraries available on the host.

2. List schemes available here

Ask the installed command rather than assuming that a scheme from another server is present:

$ doveadm pw -l
SHA1 SSHA512 SCRAM-SHA-256 BLF-CRYPT PLAIN HMAC-MD5 OTP SHA DES-CRYPT CRYPT SSHA MD5-CRYPT PLAIN-MD4 PLAIN-MD5 SCRAM-SHA-1 SHA512-CRYPT CLEAR CLEARTEXT ARGON2I ARGON2ID SSHA256 MD5 PBKDF2 SHA256 CRAM-MD5 PLAIN-TRUNC SHA256-CRYPT SMD5 DIGEST-MD5 LDAP-MD5

The output is host-specific. A missing scheme is not fixed by changing its spelling. Choose one that your Dovecot passdb accepts and that appears in this list. For a new deployment, follow your organisation's password-policy decision; this command can generate modern schemes such as ARGON2ID on the installed version, as well as compatibility schemes such as SHA512-CRYPT.

3. Generate a hash without putting the password in history

Use the interactive form and select the scheme explicitly. This is an ordinary command. It does not need sudo, and it does not write a Dovecot configuration file:

$ doveadm pw -s ARGON2ID
Enter new password:
Retype new password:
{ARGON2ID}$argon2id$v=19$...$...

The password is not echoed. The returned value has a {scheme} prefix, followed by the scheme's encoded hash. Copy the complete line, including that prefix, into the password store expected by your passdb. Do not copy the prompt text or the dollar signs shown in this illustrative output as a literal value.

Do not normally use -p password with a real secret. The manual supports it, but a password placed in the command line can be exposed through shell history or process inspection. It is suitable only for a controlled, non-secret test value. Piping a password is also a poor default because it leaves the secret in the command's input and may enter logs or a script.

4. Set rounds only when you have a reason

-r controls encryption rounds for BLF-CRYPT, SHA256-CRYPT and SHA512-CRYPT. If omitted, the command applies its documented default. The installed manual gives these limits:

For a repeatable compatibility test, you can deliberately select the lower valid SHA-512 setting with an interactive prompt:

$ doveadm pw -s SHA512-CRYPT -r 1000
Enter new password:
Retype new password:
{SHA512-CRYPT}$6$rounds=1000$...$...

Do not reduce rounds on a live system merely to make authentication faster. A lower cost changes the protection of every hash generated with it. Treat a rounds change as a password-policy decision and test the login workload before rollout.

5. Verify the generated value

Verification checks a supplied hash against a plaintext password. Keep the hash in a shell variable only for a short-lived test, and quote it: the hash commonly contains dollar signs.

$ hash=$(doveadm pw -s SHA512-CRYPT -p 'Example-only-password' | tail -n 1)
$ doveadm pw -t "$hash" -p 'Example-only-password'
{SHA512-CRYPT}$6$...$... (verified)

This example uses a deliberately obvious test password because -p is visible in history. Use the interactive form for a real credential. A successful verification prints the hash and (verified). A mismatch is an error, not a harmless warning:

$ doveadm pw -t "$hash" -p 'Different-example-password'
Fatal: reverse password verification check failed: Password mismatch
$ printf 'exit status: %s\n' "$?"
exit status: 75

Do not deploy a hash after a mismatch. Re-enter the password carefully, generate a fresh hash, and verify that fresh value. Hashes normally contain a random salt, so generating the same password twice should produce different strings while both should verify.

6. Handle special schemes and deployment boundaries

DIGEST-MD5 is the exception that most often causes an incomplete command: the username is part of the generated value, so supply it with -u:

$ doveadm pw -s DIGEST-MD5 -u '[email protected]'
Enter new password:
Retype new password:
{DIGEST-MD5}...

For ordinary schemes, -u is not required. Encoding suffixes such as .hex, .b64 and .base64 can be appended to a scheme where supported. Use them only when the target password database requires that representation. The scheme prefix is part of the stored value and lets Dovecot override a passdb's default for that entry.

Generating a hash does not install it. Updating a passwd file, SQL row or LDAP directory is a separate operation, often requiring elevated privileges or database credentials. Before that change, make a protected backup according to your platform's procedure and confirm the target account. Never paste a plaintext password into a world-readable configuration file. If you overwrite a value by mistake, restore the backup or replace the entry with a newly verified hash; there is no undo action in doveadm pw.

7. Diagnose the common failures

• If doveadm pw -l omits the scheme you need, check the installed Dovecot package and the host's available password libraries. Do not silently substitute a weaker scheme.
• If the two interactive entries differ, the command refuses to generate a usable result. Re-enter them; do not disable the confirmation prompt.
• If a hash is rejected by authentication, confirm that the complete {scheme} prefix was stored and that the selected scheme is supported by the configured passdb.
• If a command reports a local Dovecot socket permission warning but still prints a hash, separate the warning from the hash-generation result. Check the command's final status and verify the value before using it. Do not grant broad socket access just to hide a warning.