Generate and Verify Password Hashes with doveadm pw

doveadm pw generates a Dovecot password hash interactively, so the plaintext password never has to touch your shell history. This guide creates a hash, checks it against the intended password, and covers the schemes and rounds settings the installed manual documents. The examples use Dovecot 2.3.21 from the installed dovecot-core package; allow about ten minutes, and no service restart or configuration edit is required.

1. Check the installed command

Start with ordinary, read-only checks to identify 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 installed manual page 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 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, and 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: 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 needs no 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, prefix included, 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.

4. Set rounds only when you have a reason

-r controls encryption rounds for BLF-CRYPT, SHA256-CRYPT and SHA512-CRYPT. Leave it out and 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 just to make authentication faster: a lower cost weakens 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, since 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, and both should still verify.

6. Handle special schemes and deployment boundaries

DIGEST-MD5 is the scheme that most often produces an incomplete command, because the username is part of the generated value; supply it with -u:

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

• Ordinary schemes do not need -u. It only matters for schemes like DIGEST-MD5 that bind the username into the hash.
• Encoding suffixes such as .hex, .b64 and .base64 can be appended to a scheme where supported, but only use them when the target password database requires that representation.
• The scheme prefix is part of the stored value. It lets Dovecot override a passdb's default for that one entry.

Generating a hash does not install it. Updating a passwd file, SQL row or LDAP directory is a separate operation, often needing elevated privileges or database credentials. Make a protected backup according to your platform's procedure and confirm the target account before that change, and 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.

Common traps

• Scheme missing from doveadm pw -l. Check the installed Dovecot package and the host's available password libraries; do not silently substitute a weaker scheme.
• The two interactive entries differ. The command refuses to generate a usable result; re-enter them rather than disabling the confirmation prompt.
• A hash is rejected by authentication. Confirm the complete {scheme} prefix was stored and that the selected scheme is supported by the configured passdb.
• A local socket permission warning appears alongside 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 silence a warning.