Repair and Maintain Dovecot FTS Indexes with doveadm fts

Search in webmail has gone quiet, and doveadm fts is the command that tells your Dovecot full text index to tidy itself or start again. You will optimise an index, rescan it against the mailboxes, and run consistency checks where your build supports them.

Allow about fifteen minutes, a little longer for a large mailbox set. The examples match Dovecot Core 1:2.3.21+dfsg1-2ubuntu6.5 and its installed doveadm-fts(1) manual page.

• What you need: shell access to the Dovecot host, a working Dovecot configuration and an FTS backend that is already set up.
• Privileges: read-only inspection is ordinary user work. Index maintenance normally needs the Dovecot administration account or sudo, depending on how the service is configured.
• Consistency checks: these need the Dovecot Pro command set, so they may not exist on your host.

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

That output is shortened to show 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

2. Pick the narrowest user target

Every maintenance command can take a namespace, but the user scope comes from one of -u, -A or -F. If you supply none, 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 stop the shell interpreting characters in a more complicated username or mask. Wildcards such as *@example.org work with -u, but a broad mask still hits many accounts.

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

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

3. Optimise an existing FTS index

Use optimize to force index optimisation:

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

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

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

A successful command normally returns straight to the prompt. For progress or diagnostics, add -v (progress and verbosity) or -D (debug messages):

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

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 lets the next doveadm index pick up missing mail:

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

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

That last command is a separate doveadm-index(1) operation, not part of doveadm fts. Substitute the mailbox or indexing scope that suits your deployment. Do not call it recovered until a search client or your FTS monitoring confirms messages are searchable again.

5. Run consistency checks if your build has them

fts check fast and fts check full exist only when the fts_dovecot plugin from Dovecot Pro FTS is loaded. Standard Dovecot Core installs do not have them. On a Core-only host, an unknown-command or plugin-related error tells you about capability, not about a failed index.

The fast check uses local cache information. Its statuses:

• 0 means the mailbox is fully consistent.
• 2 means the mailbox is not fully consistent.
• 68 means 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 trims the output to affected mailboxes. If status 68 comes back, the documented retry is:

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

The full check gives 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 any other failure as an operational error.

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. Check the socket's ownership, authentication and transport security first.