SQUATTER(8)

📦

version 3.12.4 · 6 versions

💅 NAME 💅

okay so this is squatter(8) from the Cyrus IMAP docs bestie, and it's literally the tool that creates SQUAT and Xapian indexes for mailboxes. iconic behavior, honestly. 🎀

✨ SYNOPSIS ✨

no thoughts, just syntax. copy it exactly, don't freestyle:

general:
squatter [ -C config-file ] [mode] [options] [source]

i.e.:
squatter [ -C config-file ] [ -v ] [ -a ] [ -S seconds ] [ -Z ]
squatter [ -C config-file ] [ -v ] [ -a ] [ -i ] [ -N name ] [ -S seconds ] [ -r ] [ -Z ] mailbox...
squatter [ -C config-file ] [ -v ] [ -a ] [ -i ] [ -N name ] [ -S seconds ] [ -r ] [ -Z ] -u user...
squatter [ -C config-file ] [ -v ] [ -a ] -R [ -n channel ] [ -d ] [ -S seconds ] [ -Z ]
squatter [ -C config-file ] [ -v ] [ -a ] -f synclogfile [ -S seconds ] [ -Z ]
squatter [ -C config-file ] [ -v ] -t srctier(s)... -z desttier [ -B ] [ -F ] [ -U ] [ -T reindextiers ] [ -X ] [ -o ] [ -S seconds ] [ -u user... ]

🌸 DESCRIPTION 🌸

NOTE: bestie, the lore drop first — the name "squatter" used to mean two things at once: the SQUAT indexing engine AND the command you run to build indexes. but now that Cyrus supports more than one index type (SQUAT and Xapian, as of this writing 👀), "squatter" just means the command that controls index creation. "SQUAT" or "SQUAT index(es)" = the indexes from the older SQUAT engine. and post v3, the search_engine setting in imapd.conf is the one deciding which search engine gets used. periodt. 💅

so squatter creates a brand new text index for one or more IMAP mailboxes. that index is a unified index of all the header and body text of every message in a given mailbox, and it's the reason IMAP SEARCH gets so much faster on that mailbox. it's giving glow-up for your searches, fr fr. 🔥

mode is one of indexer, search, rolling, synclog, compact or audit.

by default, squatter indexes ALL the messages in the mailbox — not just the ones since last time it ran. if you want the incremental update life, that's the -i option. and heads up 🫶: any messages appended to the mailbox after squatter runs will NOT be in the index. to get new messages indexed you gotta run squatter again, or put it on a regular schedule via crontab, or an entry in the EVENTS section of cyrus.conf(5), or just vibe with rolling mode (-R).

first synopsis → squatter indexes all mailboxes. all of them. every single one.
second synopsis → squatter indexes the specified mailbox(es), space-separated. 🦋
third synopsis → squatter indexes the specified user(s) mailbox(es).

for those last two index modes (mailbox, user) you can optionally pass -r to recurse from the specified start, or -a to limit the action only to mailboxes which have the shared /vendor/cmu/cyrus-imapd/squat annotation set to "true". so it's like, choose your own adventure. 🎀

in the fourth synopsis, squatter runs in rolling mode. in this mode squatter backgrounds itself and runs as a daemon (unless -d is set), listening to a sync log channel chosen with the -n option, set up using the sync_log_channels setting in imapd.conf(5). very soon after messages get delivered or uploaded to mailboxes, squatter will incrementally index the affected mailbox (see the notes below, bestie 👇).

in the fifth synopsis, squatter reads a single sync log file and does incremental indexing on the mailbox(es) listed in it. sometimes this is the move for cleaning up after rolling mode had a whole meltdown. 😭

in the sixth synopsis, squatter will compact indices from srctier(s) to desttier, optionally reindexing (-X) or filtering expunged records (-F) in the process. the optional -T flag lets you specify members of srctiers which must be reindexed. these files are eventually copied with rsync -a and then removed by rm. lowkey important warning though: rsync can increase the load average of the system, especially when the temporary directory is on tmpfs. to throttle rsync it's possible to modify the call in imap/search_xapian.c and pass --bwlimit=<number> as a further parameter. the -o flag can be used to direct that a single index be copied, rather than compacted, from srctier to desttier. and the -u flag restricts the operation to the specified user(s).

for all modes, the -S option may be specified, which makes squatter pause seconds seconds after each mailbox, to smooth out the loads. self-care for your server, honestly. ✨

when using the Xapian engine, the -Z option may be specified, for the indexing modes. this tells squatter to consult the Xapian internally indexed GUIDs, rather than relying on what's stored in cyrus.indexed.db — which lets you recover from a broken cyrus.indexed.db at the sacrifice of efficiency. tradeoffs, bestie. 🫶

NOTE: incremental updates are very inefficient with the SQUAT search engine. if you're using SQUAT for large and active mailboxes, you should run squatter periodically as an EVENT in cyrus.conf(5). do not skip this, it's giving "please listen to me" energy. 💀

NOTE: messages and mailboxes that have not been indexed CAN still be SEARCHed — just not as quickly as the ones with an index. so like, nothing is broken, it's just slow. 😌

squatter reads its configuration options out of the imapd.conf(5) file unless specified otherwise by -C.

(part 1 done, but we are NOT done — more of this page is coming, so don't go anywhere bestie) 💜

✨ OPTIONS ✨

okay bestie, this is the part where squatter really shows out. every single flag, no skips, let's go 💅

-C config-file — use config-file as the config file instead of the default imapd.conf(5). like, "not that one, THIS one" 🫶
-a, --squat-annot — only make indexes for mailboxes that have the shared /vendor/cmu/cyrus-imapd/squat annotation set to "true".

so the way annotations work: the value of /vendor/cmu/cyrus-imapd/squat gets inherited by all children of the given mailbox. meaning you can index (or not index) a whole entire mailbox tree by setting one single annotation on the root of that tree, set to "true" (or "false"). if a mailbox doesn't have /vendor/cmu/cyrus-imapd/squat set on it, and doesn't inherit it from anywhere, then it's just not indexed. periodt. in other words, the implicit value of /vendor/cmu/cyrus-imapd/squat is "false" — it's giving opt-in only, no cap 🚫

-A, --audit — audits the mailboxes you specify (or all of them), and reports any unindexed messages. lowkey a vibe check for your index. this feature is only available on the master branch.
-d, --nodaemon — in rolling mode, don't background, and do emit log messages on standard error. super useful for debugging. this feature was introduced in version 3.0.
-B, --skip-locked — in compact mode, use a non-blocking lock to start, and skip any users who have their xapianactive file locked at that moment (i.e. another reindex task is already on it). not me waiting in line, no thanks 💀 this feature is only available on the master branch.
-F, --filter — in compact mode, filter the resulting database so it only includes messages which are not expunged in mailboxes with existing name/uidvalidity. this feature was introduced in version 3.0.
-f synclogfile, --synclog=synclogfile — read the synclogfile and incrementally index every mailbox listed in there, then exit. this feature was introduced in version 3.0.
-h, --help — display this usage information. the classic 🎀
-i, --incremental — incremental updates, but only where indexes already exist.
-N name, --name=name — only index mailboxes beginning with name while iterating through the mailbox list derived from other options. it's giving filter, but make it name-based ✨
-n channel, --channel=channel — in rolling mode, specify the name of the sync log channel that squatter will listen to. default is "squatter". this channel has to be defined in imapd.conf(5) before you use it, no exceptions. this feature was introduced in version 3.0.
-o, --copydb — in compact mode, if only one source database is selected, just copy it to the destination rather than compacting it. why do the work if you don't gotta 🔥 this feature was introduced in version 3.0.
-p, --allow-partials — when indexing, allow messages to be partially indexed. this can happen if attachment indexing is enabled but indexing failed for one or more attachment body parts. if this flag is set, the message is partially indexed and squatter just continues on its merry way. otherwise, squatter aborts with an error. also see -P. Xapian only. this feature is only available on the master branch.
-P, --reindex-partials — when reindexing, attempt to reindex any partially indexed messages (see -p). setting this flag implies -Z. Xapian only. this feature is only available on the master branch.
-L, --reindex-minlevel=level — when reindexing, index all messages that have an index level less than level. rn Cyrus only supports two index levels, so listen up:
- a message for which attachment indexing was never attempted has index level 1.
- a message that has indexed attachments, or does not contain attachments, has index level 3.

consequently, running squatter with minlevel set to 3 will cause it to attempt reindexing all messages for which attachment indexing never was attempted. future Cyrus versions may introduce additional levels (iykyk, watch this space). setting this flag implies -Z. Xapian only. this feature is only available on the master branch.

-R, --rolling — run in rolling mode; squatter runs as a daemon listening to a sync log channel and continuously, incrementally indexing mailboxes. see also -d and -n. this feature was introduced in version 3.0. main character daemon energy fr fr 👑
-r, --recursive — recursively create indexes for all sub-mailboxes of the user, mailboxes, or mailbox prefixes you gave as arguments. it's giving "and everyone they know" 🌈
-s delta, --squat-skip=delta — skip mailboxes that haven't been modified since the last index. how does it know? by comparing the last modification time of a mailbox to the last time the squat index of that mailbox got updated. if the mailbox modification time plus delta is less than the squat index modification time, then the mailbox is skipped. the argument value delta is defined in seconds and must be greater than or equal to zero. the historical default delta was 60, and that's still a good general choice, but for technical reasons it must now be specified explicitly. Squat only. 🍓
-S seconds, --sleep=seconds — after processing each mailbox, sleep for seconds before continuing. can be used to provide some load balancing. accepts fractional amounts, so yes, 0.5 is valid bestie. this feature was introduced in version 3.0.
-T reindextiers, --reindex-tier=reindextiers — in compact mode, a comma-separated subset of the source tiers (see -t) to be reindexed. similar to -X but it lets you limit which tiers will be reindexed. this feature was introduced in version 3.0.
-t srctiers, --srctier=srctiers — in compact mode, the comma-separated source tier(s) for the compacted indices. at least one source tier must be specified in compact mode, no skipping. Xapian only. this feature was introduced in version 3.0.
-u name, --user=name — extra options refer to usernames (e.g. foo@bar.com) rather than mailbox names. usernames are space-separated. this feature was introduced in version 3.0.
-U, --only-upgrade — in compact mode, only compact if re-indexing. Xapian only. this feature is only available on the master branch.
-v, --verbose — increase the verbosity of progress/status messages. sometimes additional messages are emitted on the terminal with this option, and the messages are unconditionally sent to syslog. sometimes messages are sent to syslog only if -v is provided. in rolling and synclog modes, -vv sends even more messages to syslog. the way that more v's = more lore 😭
-X, --reindex — reindex all the messages before compacting. this mode reads all the lists of messages indexed by the listed tiers, and re-indexes them into a temporary database before compacting that into place. Xapian only. this feature was introduced in version 3.0.
-z desttier, --compact=desttier — in compact mode, the destination tier for the compacted indices. this must be specified in compact mode. Xapian only. this feature was introduced in version 3.0.
-Z, --internalindex — when indexing messages, use the Xapian internal cyrusid rather than referencing the ranges of already indexed messages to know if a particular message is indexed. useful if the ranges get out of sync with the actual messages (e.g. if files on a tier are lost) — 🙈 Xapian only. this feature is only available on the master branch.

🌸 EXAMPLES 🌸

squatter is typically deployed via entries in cyrus.conf(5), in either the DAEMON or EVENTS sections. yes, both. it's flexible like that 💖

for the older SQUAT search engine, which offers poor performance in rolling mode (-R) — ngl, it's just not that girl in rolling mode — we recommend triggering periodic runs via entries in the EVENTS section, as follows:

sample entries from the EVENTS section of cyrus.conf(5) for periodic squatter runs:

EVENTS {
    # reindex changed mailboxes (fulltext) approximately every three hours
    squatter1   cmd="/usr/bin/ionice -c idle /usr/lib/cyrus/bin/squatter -i" period=180

    # reindex all mailboxes (fulltext) daily
    squattera   cmd="/usr/lib/cyrus/bin/squatter" at=0117
}

for the newer Xapian search engine, and with sufficiently fast storage, rolling mode (-R) offers advantages. but using rolling mode requires that squatter be invoked in the DAEMON section. rules are rules 🎀

sample entries for the DAEMON section of cyrus.conf(5) for rolling squatter operation:

DAEMON {
  # run a rolling squatter using the default sync_log channel "squatter"
  squatter cmd="squatter -R"

  # run a rolling squatter using a specific sync_log channel
  squatter cmd="squatter -R -n indexer"
}

NOTE: when using the -R rolling mode, you MUST enable sync_log operation in imapd.conf(5) via the sync_log: on setting, and you MUST define a sync_log channel via the sync_log_channels: setting. if you're also using replication, you must either explicitly specify your replication sync_log channel via the sync_log_channels directive with a name, or specify the default empty name with "" (the two-character string U+22 U+22). [please see imapd.conf(5) for details]. not me stressing the MUSTs but like, they're MUSTs bestie 💀

NOTE: when configuring rolling search indexing on a replica, you gotta consider whether sync_logs will be written at all. in this case, please consider the setting sync_log_unsuppressable_channels to make sure that the sync_log channel your squatter instance depends on will continue to be written. see imapd.conf(5) for details. 🦋

NOTE: when using the Xapian search engine, you must define various settings in imapd.conf(5). please read all the relevant Xapian documentation in this release before using Xapian. read first, index later, that's the rule ✨

[NB: More examples needed] — yes the manpage literally says this, iconic honestly, they left it in 🙈

📜 HISTORY 📜

support for additional search engines was added in version 3.0.

the following command-line switches were added in version 3.0:

-F -R -X -d -f -o -u

the following command-line settings were added in version 3.0:

-S <seconds>, -T <directory>, -f <synclogfile>, -n <channel>, -t srctier..., -z desttier

🗂 FILES 🗂

/etc/imapd.conf
/etc/cyrus.conf

👀 SEE ALSO 👀

imapd.conf(5), cyrus.conf(5)

💜 AUTHOR 💜

the Cyrus Team, Nic Bernstein (Onlight)

1993–2026, The Cyrus Team

and that's a wrap on the whole page, bestie!! 🎀 this was version 3.12.4, dated Sep 09, 2026, and it's the SQUATTER(8) manual page — go forth and index responsibly, you absolute icon 👑💖

📦 where this page comes from

fedora 44: cyrus-imapd 3.12.4-1.fc44 · BSD-Attribution-HPND-disclaimer
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms