Repair and Maintain Dovecot FTS Indexes with doveadm

You will finish with a cautious workflow for maintaining Dovecot Full Text Search indexes: optimise an existing index, rescan it against the mailboxes, or check consistency when the installed Dovecot Pro command supports that feature. The examples match Dovecot Core 1:2.3.21+dfsg1-2ubuntu6.5 and its installed doveadm-fts(1) manual page.

Allow about fifteen minutes for the commands and a little longer if a large mailbox set needs attention. You need shell access to the Dovecot host, a working Dovecot configuration, and an FTS backend already configured. Read-only inspection is ordinary user work. Index maintenance normally needs the Dovecot administration account or sudo, depending on how the service is configured.

1. Check the installed command and feature set

Start with the local help page. This does not alter mail, indexes or service state:

$ doveadm help fts
DOVEADM-FTS(1)                      Dovecot                     DOVEADM-FTS(1)

NAME
       doveadm-fts - Manipulate the Full Text Search (FTS) index

COMMANDS
   fts optimize
   fts rescan
   fts check fast
   fts check full

The shortened output above shows the command family. The installed help also describes the global options, targets and exit codes. Confirm the package version separately:

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

Do not use a remembered option list from another Dovecot release. The manual page on this host is labelled Dovecot v2.3 and documents this syntax.

2. Choose the narrowest user target

Every maintenance command can take a namespace, but the user scope is selected with one of -u, -A or -F. If none is supplied, doveadm uses the environment of the currently logged-in user. That default is easy to miss, so make the target explicit for an administrative run:

# sudo doveadm fts optimize -u '[email protected]'

Replace the address with a real user from your user database. The quotes keep the shell from interpreting characters in a more complicated username or mask. You can use wildcards such as *@example.org with -u, although a broad mask still affects many accounts.

For a controlled batch, put one username per line in a file that only the administrator can read, then pass it with -F:

# sudo doveadm fts optimize -F /root/fts-users.txt

-A obtains all users by iterating the user database. The manual warns that this is unsuitable without care when the user database is the system passwd driver, because it can include system users below first_valid_uid. SQL and LDAP deployments also need working iteration settings. Check that scope before using -A.

3. Optimise an existing FTS index

Use optimize when you want to force index optimisation:

# sudo doveadm fts optimize -u '[email protected]'

The FTS engines optimise automatically, so this command is an enforcement point rather than a routine requirement. It does not rebuild missing messages. Add a namespace only when you deliberately want a namespace other than the user's private namespace:

# sudo doveadm fts optimize -u '[email protected]' shared

A successful command normally returns to the prompt. If you need progress or diagnostic detail, add -v for progress and verbosity, or -D for debug messages:

# sudo doveadm -v fts optimize -u '[email protected]'
# printf 'exit status: %s\n' "$?"
exit status: 0

The status belongs to the command immediately before printf. A zero status says that this invocation completed; it is not a content-level proof that every mailbox is searchable.

4. Rescan after index and mailbox drift

Use rescan when the index may no longer match the mailboxes. It compares indexed mail with what exists, removes entries for already-expunged messages, and makes the next doveadm index able to index missing mail:

# sudo doveadm fts rescan -u '[email protected]'

There is no general undo command for a rescan. Recovery is to let the configured backend rebuild its index, usually by running the normal indexing workflow after checking the backend documentation:

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

The last command is a separate doveadm-index(1) operation, not part of doveadm fts. Substitute the mailbox or indexing scope appropriate to your deployment. Do not claim recovery until a search client or your FTS monitoring confirms that messages are searchable again.

5. Know when consistency checks are available

fts check fast and fts check full exist only when the fts_dovecot plugin from Dovecot Pro FTS is loaded. They are not a feature of every Dovecot Core installation. On a standard Core-only host, seeing an unknown-command or plugin-related error is a capability result, not evidence that the index has failed.

The fast check uses local cache information. Its statuses are:

• 0: the mailbox is fully consistent.
• 2: the mailbox is not fully consistent.
• 68: local metacache information is insufficient. Retry with --refresh, or use the full check.

# sudo doveadm fts check fast -u '[email protected]' --print-mismatches-only
# printf 'exit status: %s\n' "$?"
exit status: 0

--print-mismatches-only reduces output to affected mailboxes. If status 68 is returned, the documented retry is:

# sudo doveadm fts check fast -u '[email protected]' --refresh

The full check provides more detail and can print IMAP UID numbers and FTS triplet names:

# sudo doveadm fts check full -u '[email protected]' --print-details

Full-check status 0 means consistent and status 2 means inconsistent. Treat other failures as operational errors. Do not use --refresh, optimise or rescan as a blind repair: first record the result and identify the affected user or namespace.

6. Handle remote administration deliberately

The -S option selects a local UNIX socket by absolute path or a remote TCP endpoint written as hostname:port:

# sudo doveadm -S /run/dovecot/admin fts optimize -u '[email protected]'

Replace the socket path with one that exists in your deployment. Use this form only after checking the socket's ownership, authentication and transport security. A TCP socket exposes an administration interface, so do not send credentials or mailbox-control traffic over an untrusted network.