Obox Advanced Settings

See also

obox plugin


These are advanced obox settings that should normally not be changed.



By default, doing changes to folders (e.g. creating or renaming) uploads changes immediately to object storage. If this setting is enabled, the upload happens sometimes later (within metacache_upload_interval).


Disable caching bundle list.


Disable index merging when opening root or mailbox indexes. This can be used to work around bugs in the merging code that cause crashes. Usually this setting isn’t set in dovecot.conf, but set via doveadm call:

doveadm -o plugin/metacache_disable_merging=yes force-resync -u user@example '*'

New in version v2.3.17.

Disable including secondary indexes into the user root bundle when using the virtual or virtual-attachments plugin (see virtual plugin and virtual-attachments plugin).

This setting can be used to exclude the virtual and virtual-attachments folders from the user root bundle in case any problems are encountered.


New in version v2.3.6.

Changed in version v2.3.16: Changed default from v1 to v2

Specifies the algorithm to use when merging folder indexes.




Alias for metacache_disable_merging


The old dsync-based algorithm, which can cause very inefficient behavior in some situations.


The new algorithm designed specifically for this purpose of merging two indexes. This is the recommended setting.


Maximum number of metacache read/write operations to do in parallel.


This is used only with metacache_index_merging = v2.

If the merging detects that there are more than this many UIDs that are conflicting and would have to be renumbered, don’t renumber any of them. This situation isn’t expected to happen normally, and renumbering too many UIDs can cause unnecessary extra disk I/O.

The downside is that a caching IMAP client might become confused if it had previously seen different UIDs.

  • Default: <empty>

See metacache_size_weights.

  • Default: <empty>

plugin {
  metacache_priority_weights = 10% +1d 10% +1d 50% +1h 100% 0
  metacache_size_weights = 2M +30 1G +120

Whenever metacache notices that metacache_max_space has been reached, it needs to delete some older index files to make space for new ones. This is done by calculating cleanup weights.

The simplest cleanup weight is to just use the user’s last access UNIX timestamp as the weight. The lowest weight gets deleted first.

It’s possible to enable using only simple weights by explicitly setting metacache_priority_weights and metacache_size_weights to empty values. However, by default priorities are taken into account when calculating the weight.

The metacache_priority_weights setting can be used to fine tune how metacache adjusts the cleanup weights for different index priorities. There are 4 major priorities (these are also visible in e.g. doveadm metacache list output):

  • 0 = User root indexes (highest priority)

  • 1 = FTS indexes

  • 2 = INBOX and Junk folder indexes (“special” folders)

  • 3 = Non-special folder indexes (lowest priority)

The metacache_priority_weights contains <percentage> <weight adjustment> pairs for each of these priorities. So, for example, the first 10% +1d applies to the user root priority and the last 100% 0 applies to other folders’ priority.

The weight calculation is then done by:

  • Initial weight is the user’s last access UNIX timestamp

  • metacache_priority_weights is next looked up for the given priority indexes

  • If the total disk space used by the indexes is equal or less than the <percentage>, add <weight adjustment> to weight. So, for example, with 10% +1d if the disk space used by index files of this priority type take <= 10% of metacache_max_space, increase the weight by 1d = 60*60*24 = 86400.

  • Because the initial weight is based on UNIX timestamp, the weight adjustment is also given as time. This practically means that e.g. +1d typically gives 1 extra day for the index files to exist compared to index files that don’t have the weight boost.

  • <percentage> exists so that the weight boost doesn’t cause some index files to dominate too much. For example, if root indexes’ weights weren’t limited, it could be possible that the system would be full of only root indexes and active users’ other indexes would be cleaned almost immediately.

The metacache_size_weights setting is used to do final adjustments depending on the disk space used by this user’s indexes of the specific priority. The setting is in format <low size> <low weight adjustment> <max size> <high weight adjustment>.

The weight adjustment calculation is:

  • If disk space is equal or less than <low size>, increase weight by (<low size> - <disk space>) * <low weight adjustment> / <low size>

  • Otherwise, cap the <disk space> to <max size> and increase weight by (<disk space> - <low size>) * <high weight adjustment> / (<max size> - <low size>)

  • The idea here is to give extra weight boost for

    • Small indexes, because they’re small enough that it won’t matter if they live longer than most, AND

    • Very large indexes, because it’s so expensive to keep uploading/downloading them in object storage

  • With the default 2M +30 1G +120 value the priority adjustments will look like:

    • 0 kB: +30

    • 500 kB: +23

    • 1 MB: +15

    • 1,5 MB: +8

    • 2 MB: 0

    • 10 MB: +1

    • 50 MB: +6

    • 100 MB: +12

    • 258 MB: +30

    • 500 MB: +60

    • >=1 GB: +120

  • Default: metacache

  • Values: String

Path to communicate with metacache process.

  • Default: metacache/metacache-users.db

  • Values: String

Path to a database which metacache process periodically writes to.

This database is read by metacache at startup to get the latest state.

The path is relative to state_dir.



This setting is not safe to use, because it could cause various problems with indexing. Most importantly if the root index bundles weren’t accessible, it could have created whole new INBOX and other folders. In general it was also possible for FTS indexes to become desynchronized, which required rebuilding them. Even if everything had worked properly, performance could have been rather bad if many mails were missing from the local indexes.

Even in case of object storage errors, try to allow accessing the emails as well as possible. This especially means that if the local metacache already has a copy of the indexes, they can be used to provide access to user’s emails even if the object storage is unavailable.


New in version v2.3.6.

Normally Dovecot attempts to make sure that IMAP UIDs aren’t lost even if a backend crashes (or if user is moved to another backend without indexes first being uploaded). This requires uploading index bundles whenever expunging recently saved mails. Setting this to “yes” avoids this extra index bundle upload at the cost of potentially changing IMAP UIDs. This could cause caching IMAP clients to become confused, possibly even causing it to delete wrong mails. Also FTS indexes may become inconsistent since they also rely on UIDs.


If activated, when an unexpected 404 is found when retrieving a message from object storage, Dovecot will rescan the mailbox by listing its objects. If the 404-object is still listed in this query, Dovecot issues a HEAD to determine if the message actually exists. If this HEAD request returns a 404, the message is dropped from the index. The message object is not removed from the object storage.


Avoid getting the email’s size from the cache whenever the email body is opened anyway. This avoid unnecessary errors if a lot of the vsizes are wrong. The vsize in dovecot.index is also automatically updated to the fixed value with or without this setting.

This setting was mainly useful due to earlier bugs that caused the vsize to be wrong in many cases.


Workaround for object storages with a broken copy operation. Instead perform copying by reading and writing the full object.


New in version v2.3.0.

This is the reverse of obox_use_object_ids with newer Dovecot versions. See its description for more details.


Cassandra: Object exists in dict, but not in storage errors will be handled by returning empty emails to the IMAP client. The tagged FETCH response will be OK instead of NO.

  • Default: recovered-lost-folder-

  • Values: String

If folder name is lost entirely due to lost index files, generate a name for the folder using this prefix.


Upload indexes after this many mails have been saved since the last upload. A higher value reduces the number of uploads, but increases the number of mail downloads to fill the caches after a backend crash.


Enable if there are no migrated POP3 UIDLs. If enabled, don’t try to look up UIDLs in any situation.

  • Default: warn-read

  • Values: read, stat, warn-read

This setting controls what should be done when the mail object is missing the size metadata.





Same as warn-read, but doesn’t log a warning.


Use fs_stat() to get the size, which is the fastest but doesn’t work if mails are compressed or encrypted.


Log a warning and fallback to reading the email to calculate its size.


Removed in version v2.3.0.

Access objects directly via their IDs instead of by paths, if possible. This can bypass index lookups with Scality CDMI and fs-dictmap/Cassandra.

This setting was removed from v2.3 and made the default. (Although there is obox_dont_use_object_ids to disable it if really needed.)


Overrides the obox username in storage.