File & Directory Locations

Cyrus IMAP maintains several directories for configuration, state and data storage. The locations of these directories and, in many cases, of individual files, may be controlled by settings in imapd.conf(5).


Partitioning is a means to divide storage resources into separate pools and may be defined for the following types of data:

Please consult the documents linked above for more information on these.

You may also find more examples and possible scenarios in the document on Mailbox Distribution.

In general, Cyrus allows one to maintain several separate partitions for each of these data types, and to establish rules governing distribution of data within each pool.

Working With Partitions

All partition operations are controlled via settings in imapd.conf(5), and thus require server restarts to effect. There are no administrative commands to manipulate partitions.

Here are the settings for each class of partition:

Mail Spool Partitions

While Cyrus itself has no default values for these settings, most distributions use default and /var/spool/imap or /var/spool/cyrus:

defaultpartition: <none>

The partition name used by default for new mailboxes. If not specified, the partition with the most free space will be used for new mailboxes.

Note that the partition specified by this option must also be specified as partition-name, where you substitute ‘name’ for the alphanumeric string you set defaultpartition to.

partition-name: <none>

The pathname of the partition name. At least one partition pathname MUST be specified. If the defaultpartition option is used, then its pathname MUST be specified. For example, if the value of the defaultpartion option is default, then the partition-default field is required.

Metadata Partitions

Metadata is information used to process the mailbox data, rather than the contents of the messages withing the mailbox. Examples include headers, caches, indexes, etc.

metapartition-name: <none>

The pathname of the metadata partition name, corresponding to spool partition partition-name. For any mailbox residing in a directory on partition-name, the metadata files listed in metapartition_files will be stored in a corresponding directory on metapartition-name. Note that not every partition-name option is required to have a corresponding metapartition-name option, so that you can selectively choose which spool partitions will have separate metadata partitions.

metapartition_files: <empty string>

Space-separated list of metadata files to be stored on a metapartition rather than in the mailbox directory on a spool partition. Allowed values: header, index, cache, expunge, squat, annotations, lock, dav, archivecache

Backup Partitions

Cyrus Backups are a replication-based backup service for Cyrus IMAP servers.

backuppartition-name: <none>

The pathname of the backup partition name. At least one backup partition pathname MUST be specified if backups are in use. Note that there is no relationship between spool partitions and backup partitions.

Archive Partitions

Cyrus Archiving will migrate mailbox data from the normal mail spool partitions to separate archive partitions, based upon criteria such as age and size. Typical use cases would be to keep so-called “hot” data, such as recent messages, on fast drives, such as SSDs, and migrate “cold” data, such as older or large messages, to slower but cheaper media.

archivepartition-name: <none>

The pathname of the archive partition name, corresponding to spool partition partition-name. For any mailbox residing in a directory on partition-name, the archived messages will be stored in a corresponding directory on archivepartition-name. Note that not every partition-name option is strictly required to have a corresponding archivepartition-name option, but that without one there’s no benefit to enabling archiving.

Back to Administrator Guide