Index Dovecot Mailboxes Safely with doveadm index

You will finish with a repeatable way to add missing messages to a Dovecot mailbox index, optionally update full-text search data, and choose between immediate and queued work. The examples match the installed dovecot-core package, version 2.3.21+dfsg1-2ubuntu6.5, and its Dovecot v2.3 manpage.

Allow about fifteen minutes for one mailbox, longer for a busy or large account. You need shell access to the Dovecot host and a mailbox that already exists. Most examples need an administrator account because they inspect another user's mail. Do not run a broad indexing command during a maintenance-sensitive period: indexing consumes storage and I/O, and it can make full-text search backends busy.

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

The package and version can be recorded separately:

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

Checkpoint: confirm that the local synopsis includes the option you plan to use. This guide follows the installed v2.3 command. A newer Dovecot release can add options, so do not copy a current online synopsis over the local one without checking the host.

2. Index one user's mailbox

The safest useful starting point 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 immediately if you need a machine-readable result:

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

Exit status 0 means doveadm completed the request. It does not mean that every message now has every possible cached field. Dovecot only caches fields already present in the mailbox's caching decisions. A mailbox that no client has accessed may therefore gain less cache data than you expected.

3. Queue production work

Use -q when you want the indexer process to perform 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, so status 0 confirms that 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 the same time.

For a one-off test on a quiet mailbox, omit -q so the command runs directly. For a production repair or a large mailbox, schedule the queued operation and observe the host's normal Dovecot indexer and service logs. Do not add a second parallel indexing job just because the first command printed no progress.

4. Limit work for mailboxes with many recent messages

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

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

This can avoid spending time on a large mailbox that nobody has opened yet. It also means that a successful command does not prove that indexing happened: the mailbox may have exceeded the threshold and been left alone. Leave out -n when the required result is to index the mailbox regardless of its current recent-message count.

Checkpoint: if you use -n, write the chosen threshold into the maintenance record. Otherwise a later operator may mistake an intentional skip for a broken indexer.

5. Target several users carefully

Use -F with a file containing 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, and 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

There is no undo command for indexing. Removing an index file manually is not a recovery procedure: it can cause extra work, lose useful cache state, or make an already busy service less stable. If the wrong users were selected, stop issuing new jobs, keep the mail data intact, and let the queued work finish or ask the Dovecot administrator to cancel it using the site's normal operational procedure.

-A obtains the users from the user database and indexes the named mailbox for all of them. Treat it as a high-impact operation. With a passwd user database it can include system users below Dovecot's first_valid_uid; with SQL or LDAP, iteration settings must match the database or directory schema. Prefer a reviewed -F file when the target set is not truly every user.

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
}

Changing that configuration is a separate, service-affecting task. Back up the current configuration, follow the host's normal configuration validation and reload process, and make a deliberate rollback plan before enabling it. This guide only invokes the existing index command.

When you need to understand why a mailbox did not gain expected cached fields, inspect its current caching decisions with doveadm dump. That is diagnostic work; do not edit the generated index or cache files by hand.

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 enables verbosity and a progress counter. -D adds debug messages. If the command cannot find the user or mailbox, check the spelling, user database, namespace and mailbox name before trying a wider target. If the host uses a remote doveadm service, -S can select an absolute UNIX socket or a hostname:port endpoint; use the endpoint already documented by the Dovecot administrator, and treat remote access as security-sensitive.

If you omit -u, -A and -F, the command runs with the environment of the currently logged-in user. That is easy to overlook: a command that appears to target the administrator's account may actually operate on the shell user's mailbox. Make the user selection explicit in scripts and maintenance notes.