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).

* Archive Partitions

* Configuration file locations

* State Directories

* Per-user State Directories

* Directory Hashing

* Spool Directories

* Metadata Partitions

* Search Tiers


Partitions
==========

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

   * Mail Spool Partitions

   * Mailbox Metadata Partitions

   * Archive Partitions

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.


Types of Partitions
-------------------

Cyrus supports several different types of partitions:

* Mail Spool Partitions

* Metadata Partitions

* Archive Partitions

* Search Partitions

Each of these are discussed in their own sections of the
documentation. All share in common a few aspects in how they are
configured.  For each partition defined, you must tell Cyrus where the
partition is rooted in the filesystem.  This is accomplished via a
"*partition*-*name*:" directive for each partition, where
"*partition*" specifies the partition type and "*name*" is the actual
name of the partition.

Here are some sample declarations of each different type of partition
supported within Cyrus.  For the purposes of this example, we'll
stipulate the following:

* There are two main storage pools, "fast" and "slow," which are on
  SSDs and traditional disks, respectively.

* The mailboxes are divided alphabetically, with A to M in one group
  and N to Z in the other.

   # The Mail Spool Partitions
   partition-atom: /var/spool/cyrus/fast/mail/atom/
   partition-ntoz: /var/spool/cyrus/fast/mail/ntoz/

   # The Metadata Partitions
   metapartition-atom: /var/spool/cyrus/fast/meta/atom/
   metapartition-ntoz: /var/spool/cyrus/fast/meta/ntoz/

   # Archive Partitions
   archivepartition-atom: /var/spool/cyrus/slow/mail/atom/
   archivepartition-ntoz: /var/spool/cyrus/slow/mail/ntoz/

   # Search Partitions
   defaultsearchtier: tier1
   tier1searchpartition-atom: /var/spool/cyrus/slow/search/atom/
   tier1searchpartition-ntoz: /var/spool/cyrus/slow/search/ntoz/


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/cyrus" 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 **part1**, then
      the **partition-part1** 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*


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.


Search Partitions
-----------------

Modern Cyrus uses the Xapian search engine to index messages for
server-side search support.  Index data are stored in search "tiers"
which are themselves related to search partitions.  There are two key
settings for search tiers:

   "defaultsearchtier:" <empty string>

      Name of the default tier that messages will be indexed to.
      Search indexes can be organized in tiers to allow index storage
      in different directories and physical media. See the man page of
      squatter for details. The default search tier also requires the
      definition of an according *searchtierpartition-name* entry.

      This option MUST be specified for xapian search.

   "searchpartition-name:" <none>

      The pathname where to store the xapian search indexes of
      *searchtier* for mailboxes of partition *name*. This must be
      configured for the *defaultsearchtier* and any additional search
      tier (see squatter for details).

      For example: if *defaultpartition* is defined as part1 and
      *defaultsearchtier* as tier1 then the configuration must contain
      an entry *tier1searchpartition-part1* that defines the path
      where to store this tier1's search index for the part1
      partition.

      This option MUST be specified for xapian search.

Back to Administrator Guide
