Index Dovecot Mailboxes Safely with doveadm index

Search in a Dovecot mailbox is missing recent mail, and doveadm index is how you make the index catch up. You will index one mailbox, optionally feed the full-text search data, and choose between immediate and queued work. Allow about fifteen minutes for one mailbox, longer for a busy or large account.

The examples match the installed dovecot-core package, version 2.3.21+dfsg1-2ubuntu6.5, and its Dovecot v2.3 manpage.

• What you need: shell access to the Dovecot host and a mailbox that already exists.
• Privileges: most examples need an administrator account, because they inspect another user's mail.

1. Check the installed command

Read the local command help before copying an example. This is an ordinary, read-only check:

$ doveadm help index
DOVEADM-INDEX(1)                    Dovecot                   DOVEADM-INDEX(1)

NAME
       doveadm-index - Index mailboxes

SYNOPSIS
       doveadm [-Dv] index [-S socket_path] [-q] [-n max_recent] mailbox

Record the package and version separately:

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

2. Index one user's mailbox

The safest useful start is one named user and one mailbox. Replace both placeholders with real values:

$ sudo doveadm index -u '[email protected]' INBOX

-u selects the user and the final argument is the mailbox name. The command adds unindexed messages to the mailbox's index and cache files. If full-text search is enabled, it also adds the missing messages to the FTS database.

A successful run normally has no friendly summary to print. Check the exit status straight away if you need a machine-readable result:

$ sudo doveadm index -u '[email protected]' INBOX
$ printf 'exit status: %s\n' "$?"
exit status: 0

3. Queue production work

Use -q when you want the indexer process to do the work instead of the current doveadm process:

$ sudo doveadm index -u '[email protected]' -q INBOX
$ printf 'exit status: %s\n' "$?"
exit status: 0

Queued work can return before the mailbox has finished indexing. Status 0 confirms the request was accepted, not that the queue has drained. The v2.3 manpage says -q should usually be used on production, because some backends, including fts-lucene, cannot safely handle multiple processes updating indexes at once.

• One-off test on a quiet mailbox: omit -q so the command runs directly.
• Production repair or large mailbox: schedule the queued operation and watch the host's normal Dovecot indexer and service logs.
• No progress printed: do not add a second parallel indexing job just because the first command was quiet.

4. Limit work for mailboxes with many recent messages

-n max_recent is a skip threshold, not a batch size. If a mailbox holds more than that number of messages with the IMAP \Recent flag, Dovecot does not index it:

$ sudo doveadm index -u '[email protected]' -n 100 INBOX

That can save time on a large mailbox nobody has opened yet. It also means a successful command does not prove indexing happened: the mailbox may have exceeded the threshold and been left alone. Leave out -n when you need the mailbox indexed whatever its recent-message count.

5. Target several users carefully

Use -F with a file holding one username per line when you have an explicit, reviewed target list:

$ sudo install -m 600 /dev/null /tmp/dovecot-users.txt
$ sudo sh -c 'printf "%s\n" "[email protected]" "[email protected]" > /tmp/dovecot-users.txt
$ sudo doveadm index -F /tmp/dovecot-users.txt -q INBOX

The file is read as usernames, not mailbox names. Review it before running the command. Remove it after the maintenance window, because it contains account identifiers:

$ sudo sed -n '1,20p' /tmp/dovecot-users.txt
$ sudo rm -- /tmp/dovecot-users.txt

6. Understand FTS and cache limits

doveadm index does not turn on full-text search. It only feeds unindexed messages into an FTS database when an FTS plugin is configured. For automatic indexing during delivery and other message additions, the local manpage documents this setting in /etc/dovecot/conf.d/90-plugin.conf:

plugin {
  fts_autoindex = yes
}

7. Diagnose a failed request

Start with the narrowest command and add verbosity only when needed:

$ sudo doveadm -v index -u '[email protected]' -q INBOX
$ printf 'exit status: %s\n' "$?"
exit status: 0

• -v and -D. -v enables verbosity and a progress counter. -D adds debug messages.
• User or mailbox not found. Check the spelling, user database, namespace and mailbox name before trying a wider target.
• Remote doveadm service. -S can select an absolute UNIX socket or a hostname:port endpoint. Use the endpoint the Dovecot administrator has documented, and treat remote access as security-sensitive.