DOVEADM-FTS(1)

💖 doveadm-fts(1) — the Dovecot manual, but make it make sense 💖

okay bestie, listen up, because this one is the full text search page. It lives in the Dovecot manual family, it's called doveadm-fts(1), and it's about messing with your FTS index. Yes, the search index. Yes, the one that makes your mail search not take nine business days. Let's go. ✨

---

🌸 NAME 🌸

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

---

🎀 SYNOPSIS 🎀

doveadm [GLOBAL OPTIONS] fts command [OPTIONS] [ARGUMENTS]

---

🦋 DESCRIPTION 🦋

The doveadm fts COMMANDS are your little toolkit for manipulating the Full Text Search (FTS) index. That's it, that's the vibe. 💅

---

⭐ GLOBAL OPTIONS ⭐

These are the global doveadm(1) options, so they apply across the board, not just to fts. Iconic behaviour fr fr.

• -D — Turns on verbosity AND debug messages. She's chatty, she's telling you everything. 🔥
• -O — Don't read any config file, just roll with the defaults. The dovecot_storage_version setting defaults to the latest version, but you can override that with -o if you're feeling spicy.
• -k — Preserves the entire environment for doveadm, not just whatever's in the import_environment setting.
• -v — Verbosity ON, and yes, that includes a progress counter. Very satisfying to watch, no cap.
• -i instance-name — If you're running multiple Dovecot instances, pick the config file based on this instance name. Peep the instance_name setting for the deets.
• -c config-file — Read config from the given config-file. By default it reads the config socket first, then falls back to /etc/dovecot/dovecot.conf. You can also point this at the config socket of some instance running a compatible version. Slay, flexible. 🫶
• -o setting=value — Overrides the config setting from /etc/dovecot/dovecot.conf and from the userdb with the given value. Wanna override multiple settings? Just pass -o as many times as you want, she doesn't mind.

Also, a lil FYI: this command uses by default the output formatter flow (without the key= prefix). 💫

---

✨ OPTIONS ✨

• -A — If -A is present, the command runs for all users. ⚠️ But listen, using this with system users from userdb { driver = passwd } is not recommended, because that also contains users with a lower UID than whatever you set with the first_valid_uid setting. So like, be careful, bestie.
  • If you're using the SQL userdb module, make sure the userdb_sql_iterate_query setting matches your database layout. (Yes, the manpage literally says "setting setting". We keep the facts exactly as they are. 💀)
  • If you're using the LDAP userdb module, make sure the userdb_fields setting and the userdb_ldap_iterate_fields setting match your LDAP schema. Otherwise doveadm(1) will simply be unable to iterate over all users, and that's a bad time. 😭
• -F file — Execute the command for all the users in the file. Basically -A's cousin, except instead of pulling the user list from the userdb, they're read from the given file. One username per line. Simple, clean, organised. 🎀
• --no-userdb-lookup — Don't do a userdb lookup at all. Use the USER environment variable to specify the username instead. Main character energy: you decide who you are. 👑
• -S socket_path — The argument is either an absolute path to a local UNIX domain socket, OR a hostname and port (hostname:port), so you can connect to a remote host via a TCP socket. This lets an administrator execute doveadm(1) mail commands through the given socket. 🌈
• -u user/mask — Run the command only for the given user. You can also use '*' and '?' wildcards, e.g. -u *@example.org. Chef's kiss. 💅

---

🧚 ARGUMENTS 🧚

• namespace — The name of a namespace, e.g. the name of the shared namespace. When no namespace is given, the user's private namespace gets used. Default behaviour, love that for us.

---

👑 COMMANDS 👑

🍓 fts optimize

doveadm [GLOBAL OPTIONS] fts optimize [-u user | -A | -F file | --no-
userdb-lookup] [-S socket_path] [namespace]

Optimize the full text search index. Now, the FTS engines also do this automatically, but this one enforces it, like, right now, whether the engine feels like it or not. 💪

---

🍓 fts rescan

doveadm [GLOBAL OPTIONS] fts rescan [-u user | -A | -F file | --no-
userdb-lookup] [-S socket_path] [namespace]

Scans what mails actually exist in the FTS index, then compares those against what actually exists in mailboxes. It removes mails from the index that have already been expunged, and makes sure that the next doveadm index will index all the missing mails (if there are any).

⚠️ Heads up: currently most FTS drivers do not implement this properly, and instead they just delete all the FTS indexes. That may change in future versions. So like… know that going in. 🙈

---

🍓 fts flatcurve check

doveadm [GLOBAL OPTIONS] fts flatcurve check [-u user | -A | -F file |
--no-userdb-lookup] [-S socket_path] [mailbox ...]

Runs a simple check on Dovecot Xapian databases, and attempts to fix basic errors. It's the same checking done by the xapian-check command with the -F command-line option. Same energy, different wrapper. ✨

mailbox is the list of mailboxes to process. You can use wildcards (* and ?) in this value. 🦋

For each mailbox that has FTS data, it outputs the following key/value fields:

• mailbox — The human-readable mailbox name. (key is hidden)
• guid — The GUID of the mailbox.
• errors — The number of errors reported by the Xapian library.
• shards — The number of index shards processed.

---

🍓 fts flatcurve remove

doveadm [GLOBAL OPTIONS] fts flatcurve remove [-u user | -A | -F file |
--no-userdb-lookup] [-S socket_path] [mailbox ...]

Removes all FTS data for a mailbox. Gone. Poof. 💀

mailbox is the list of mailboxes to process. You can use wildcards (* and ?) in this value. 🌸

For each mailbox removed, it outputs the following key/value fields:

• mailbox — The human-readable mailbox name. (key is hidden)
• guid — The GUID of the mailbox.

---

🍓 fts flatcurve rotate

doveadm [GLOBAL OPTIONS] fts flatcurve rotate [-u user | -A | -F file |
--no-userdb-lookup] [-S socket_path] [mailbox ...]

Triggers an index rotation for a mailbox. Fresh index, new era, glow-up season. 🔄✨

mailbox is the list of mailboxes to process. You can use wildcards (* and ?) in this value. 💜

For each mailbox rotated, it outputs the following key/value fields:

• mailbox — The human-readable mailbox name. (key is hidden)
• guid — The GUID of the mailbox.

---

🍓 fts flatcurve stats

doveadm [GLOBAL OPTIONS] fts flatcurve stats [-u user | -A | -F file |
--no-userdb-lookup] [-S socket_path] [mailbox ...]

Returns FTS data for a mailbox. The receipts, basically. 🧾

mailbox is the list of mailboxes to process. You can use wildcards (* and ?) in this value. ⭐

For each mailbox that has FTS data, it outputs the following key/value fields:

• mailbox — The human-readable mailbox name. (key is hidden)
• guid — The GUID of the mailbox.
• last_uid — The last UID indexed in the mailbox.
• messages — The number of messages indexed in the mailbox.
• shards — The number of index shards.
• version — The (Dovecot internal) version of the FTS data.

---

…and that's where part 1 wraps, bestie. Part 2 is coming, don't go anywhere. 🫶

🐛 REPORTING BUGS 🐛

Okay bestie, found a bug? First of all, thank you for your service 💖. Second of all, do NOT just scream into the void — report it to the Dovecot Mailing List at dovecot@dovecot.org.

And listen, this part is important: include your doveconf -n output with the report. Like, the whole thing. It's giving "receipts or it didn't happen" and the maintainers literally need it to help you. 🙏

All the deets on how to report bugs properly live right here:

• https://dovecot.org/bugreport.html

---

👀 SEE ALSO 👀

The girlies you should also be reading:

• doveadm(1) — the main character, obviously
• doveadm-search-query(7) — for all your search syntax needs

🌈 Additional resources 🌈

• the fts plugin documentation ✨

---

And that's the whole page, bestie!! 🫶 This was DOVEADM-FTS(1), version/source tag f979264, dated April 2026 — so you know it's fresh ✨. Go forth and full-text-search slay, ily, mwah 💅🎀🦋