Read Dovecot Index and Log Files with doveadm dump

A Dovecot mailbox is misbehaving and you want to see what its index says, without touching it. doveadm dump turns index and log files into readable text in about ten minutes.

The examples use Dovecot 2.3.21 from the Ubuntu dovecot-core package installed on this machine. Check your own package before relying on a type added by a later build. You will finish with the original mailbox files unchanged, a readable dump or a useful error, and enough to hand to whoever is diagnosing Dovecot.

1. Check the installed command and your access

Run these checks as the account that can read the mailbox storage. Do not use sudo automatically. If the mailbox belongs to a Dovecot service account and your normal account cannot read it, use the least-privileged approved account, or ask an administrator to run the read-only check.

$ command -v doveadm
/usr/bin/doveadm
$ dpkg-query -W -f='${Package} ${Version}\n' dovecot-core
dovecot-core 1:2.3.21+dfsg1-2ubuntu6.5
$ test -r /path/to/mailbox/dovecot.index && echo readable
readable

The package version is a local check, not a universal version command: this installed doveadm rejects --version. The relevant manual page is doveadm-dump(1), whose synopsis is doveadm [-Dv] dump [-t type] path.

2. Start with automatic type detection

Give doveadm dump a mailbox directory when you are unsure which file type it holds. The command can inspect files below a directory and select a recognised type.

$ doveadm dump /path/to/mailbox/

A successful run prints the selected index or log contents in a human-readable format. The exact fields and ordering depend on the file and Dovecot build. This is diagnostic output, not a stable format for a parser.

3. Dump an index or log explicitly

These documented types cover the files most administrators meet when investigating mailbox state:

• index for dovecot.index and dovecot.map.index.
• log for dovecot.index.log and dovecot.map.index.log.
• mailboxlog for dovecot.mailbox.log.
• thread for dovecot.index.thread.
• dbox for an m.n sdbox or mdbox mailbox file.

For example, inspect one index directly:

$ doveadm dump -t index /path/to/mailbox/dovecot.index

For a dbox file, the path is the storage file rather than the directory containing it:

$ doveadm dump -t dbox /path/to/storage/m.42

4. Use specialised types only when they match

The manual also documents fts-expunge-log, fts-lucene, imapzlib, dcrypt-file and dcrypt-key. They are not interchangeable troubleshooting modes. For example, imapzlib expects a compressed IMAP traffic log, while dcrypt-file and dcrypt-key report metadata for encrypted objects. Choose the type from the file's role and your problem, not from a guess based on its name.

There is a version boundary here. The installed 2.3.21 binary's usage output also advertises a multiplex type, although the installed doveadm-dump(1) page does not list it. Treat that as build-specific: confirm it with your local command help, and do not write a script that assumes every Dovecot 2.3 package provides it.

5. Add diagnostics without changing the mailbox

Use -v for verbosity and a progress counter, and -D for debug messages. They make output noisy, so add one at a time when the ordinary dump is not enough.

$ doveadm -v dump -t index /path/to/mailbox/dovecot.index
$ doveadm -D dump -t index /path/to/mailbox/dovecot.index

The global -o setting=value option overrides a Dovecot configuration setting for this invocation and can be repeated. Use it only when your diagnostic question requires the override, and record the exact command. Avoid copying secrets into shell history or a support ticket.

6. Read failures before blaming the index

A missing or unreadable path is an access or path problem, not evidence that the index is corrupt. Check it without modifying anything:

$ ls -l /path/to/mailbox/dovecot.index
$ test -f /path/to/mailbox/dovecot.index && echo exists
$ test -r /path/to/mailbox/dovecot.index && echo readable

With a nonexistent path, the installed command reports Fatal: Couldn't open index ... and returns a non-zero status. An unknown type reports the available types and Fatal: Unknown type: .... Both tell you to fix the path or type before investigating the dump itself.