<HTML><HEAD> <title>Cyrus IMAP Server: Overview and Concepts</title> <!-- $Id: overview.html,v 1.5 2005/03/05 00:36:25 dasenbro Exp $ --> </HEAD><BODY> <H1>Cyrus IMAP Server: Overview and Concepts</H1> <p>This document gives an overview of the Cyrus IMAP server. The Cyrus IMAP (Internet Message Access Protocol) server provides access to personal mail and system-wide bulletin boards through the IMAP protocol. The Cyrus IMAP server is a scalable enterprise mail system designed for use from small to large enterprise environments using standards-based technologies. <p>A full Cyrus IMAP implementation allows a seamless mail and bulletin board environment to be set up across multiple servers. It differs from other IMAP server implementations in that it is run on "sealed" servers, where users are not normally permitted to log in. The mailbox database is stored in parts of the filesystem that are private to the Cyrus IMAP system. All user access to mail is through software using the IMAP, IMAPS, POP3, POP3S, or KPOP protocols. <p>The private mailbox database design gives the server large advantages in efficiency, scalability, and administratability. Multiple concurrent read/write connections to the same mailbox are permitted. The server supports access control lists on mailboxes and storage quotas on mailbox hierarchies. <p>This document is organized into the following areas: <UL> <LI><a href="#mboxname">Mailbox Namespace</a> <UL> <li><A href="#mboxnamestd">Standard (Internal) Namespace</A> <li><A href="#mboxnamealt">Alternate Namespace</A> </UL> <LI><a href="#acl">Access Control Lists</a> <UL> <li><A href="#aclrt">Access Rights</A> <li><A href="#aclident">Identifiers</A> <li><A href="#aclany">"<TT>anonymous</TT>" and "<TT>anyone</TT>"</A> <li><A href="#aclauth">Kerberos vs. Unix Authorization</A> <LI><A HREF="#aclneg">Negative Rights</A> <li><A href="#acluser">Calculating Users' Rights</A> <li><A HREF="#acladm">Implicit Rights for Administrators on Personal Mailboxes</A> <li><A href="#aclmbox">Initial ACLs for Newly Created Mailboxes</A> </UL> <li><a href="#login">Login Authentication</A> <UL> <li><a href="#loginanon">Anonymous Logins</A> <li><a href="#loginker">Kerberos Logins</A> <li><a href="#loginunix">Unix Logins</A> </UL> <li><a href="#quota">Quotas</a> <UL> <li><a href="#quotasup">Supports Quotas on Storage</a> <li><a href="#quotaroots">Quota Roots</a> <li><a href="#quotamail">Mail Delivery Behavior</a> <li><a href="#quotawarnings">Quota Warnings Upon Select When User Has "<TT>d</TT>" Rights</a> <li><a href="#quotapartitions">Quotas and Partitions</a> </UL> <li><a href="#notification">New Mail Notification</a> <li><a href="#partitions">Partitions</a> <UL> <li><a href="#partitionscreate">Specifying Partitions with "<TT>create</TT>"</a> <li><a href="#partitionsrename">Changing Partitions with "<TT>rename</TT>"</a> </UL> <li><a href="#news">News</a> <li><A href="#pop3">POP3 Server</A> <li><A href="#syslog">The <TT>syslog</TT> facility</A> <li><A href="#recovery">Mail Directory Recovery</A> <UL> <li><a href="#recoverymboxdir">Reconstructing Mailbox Directories</a> <li><a href="#recoverymbox">Reconstructing the Mailboxes File</a> <li><a href="#recoveryquotas">Reconstructing Quota Roots</a> <li><a href="#recoveryquotasrm">Removing Quota Roots</a> <li><a href="#recoverysubs">Subscriptions</a> </UL> <li><a href="#configdir">Configuration Directory</a> <UL> <li><a href="#configdirlog">"<TT>log</TT>" Directory</a> <li><a href="#configdirproc">"<TT>proc</TT>" Directory</a> </UL> <li><a href="#messagedelivery">Message Delivery</a> <ul> <li><a href="#lmtp">Local Mail Transfer Protocol</a> <li><a href="#singleinstance">Single Instance Store</a> <li><a href="#duplicate">Duplicate Delivery Suppression</a> <li><a href="#sieve">Sieve, a Mail Filtering Language</a> </ul> </UL> <H2><a name="mboxname">Mailbox Namespace</a></H2> By default, the Cyrus IMAP server presents mailboxes using the <TT>netnews</TT> namespace convention. Mailbox names are case-sensitive. A mailbox name may not start or end with a "." character, nor may it contain two "." characters in a row. <p>In this implementation, non-ASCII characters and shell metacharacters are not permitted in mailbox names. <p>Optionally, the server can present mailboxes using the <a href=altnamespace.html#unixhiersep> UNIX hierarchy convention</a>. <H3><A NAME="mboxnamestd">Standard (Internal) Namespace</A></H3> <p>All personal mailboxes for user "<TT>bovik</TT>" begin with the string "<TT>user.bovik.</TT>". For example, if user "<TT>bovik</TT>" had a personal "<TT>work</TT>" mailbox, it would be called "<TT>user.bovik.work</TT>". To user "<TT>bovik</TT>", however, the prefix "<TT>user.bovik.</TT>" normally appears as "<TT>INBOX.</TT>". The mailbox "<TT>user.bovik.work</TT>" would therefore appear as "<TT>INBOX.work</TT>". If the <A HREF="#acl">access control list</A> of the mailbox permitted other users to see that mailbox, it would appear to them as "<TT>user.bovik.work</TT>". <P>The mailbox "<TT>user.bovik</TT>" is where the user "<TT>bovik</TT>" normally receives new mail, and normally appears to user "<TT>bovik</TT>" as "<TT>INBOX</TT>". The mailbox "<TT>user.bovik</TT>" is referred to in this document as user "<TT>bovik</TT>"'s <TT>INBOX</TT>. <p>Administrators create and delete users by creating and deleting the users' <TT>INBOX</TT>. If a user has an <TT>INBOX</TT>, then they are allowed to subscribe to mailboxes. Only users without dots in their userid are permitted to have an <TT>INBOX</TT>. (A user with a dot in their userid would be able to login but would not be able to receive mail. Note that when using the unix hierarchy seperator, this is not the case, and any user may have a dot in their userid.) <p>When an administrator deletes a user's <TT>INBOX</TT>, all of the user's personal mailboxes are deleted as well. <p>With the one notable exception of <TT>INBOX</TT>, all mailbox names are system-wide--they refer to the same mailbox regardless of the user. <A HREF="#acl">Access control lists</A> determine which users can access or see which mailboxes. Using <p>In contexts which permit relative mailbox names, the mailbox namespace works as follows: <UL> <LI> Names that do not start with "." are fully qualified. <LI> Names that start with "." are relative to the current context. </UL> Thus, if you are working with folder names and the top of the hierarchy is named "<TT>cmu.</TT>", the name "<TT>comp.infosystems.www</TT>" resolves to "<TT>comp.infosystems.www</TT>" and the name "<TT>.comp.infosystems.www</TT>" resolves to "<TT>cmu.comp.infosystems.www</TT>". <H3><A NAME="mboxnamealt">Alternate Namespace</A></H3> The Cyrus IMAP server can also use an <a href=altnamespace.html#altname> alternate namespace</a> which allows a user's personal mailboxes to appear as if they reside at the same level as that user's <TT>INBOX</TT> as opposed to children of it. With this feature, it may appear that there are non-unique names for mailboxes between users (2 different users may each have a top level "work" mailbox), but the internal representation is still <tt>user.name.work</tt>. <H2><A NAME="acl">Access Control Lists</A></H2> Access to each mailbox is controlled by each mailbox's access control list. Access Control Lists (ACLs) provide a powerful mechanism for specifying the users or groups of users who have permission to access the mailboxes. An ACL is a list of zero or more entries. Each entry has an identifier and a set of rights. The identifier specifies the user or group of users for which the entry applies. The set of rights is one or more letters or digits, each letter or digit conferring a particular privilege. <H3><A NAME="aclrt">Access Rights</A></H3> The defined rights are: <DL compact> <DT><TT>l<dd>lookup </TT> - The user may see that the mailbox exists. <dt><TT>r<dd>read </TT> - The user may read the mailbox. The user may select the mailbox, fetch data, perform searches, and copy messages from the mailbox. <dt><TT>s<dd>seen </TT> - Keep per-user seen state. The "Seen" and "Recent" flags are preserved for the user. <dt><TT>w<dd>write </TT> - The user may modify flags and keywords other than "Seen" and "Deleted" (which are controlled by other sets of rights). <dt><TT>i<dd>insert </TT> - The user may insert new messages into the mailbox. <dt><TT>p<dd>post </TT> - The user may send mail to the submission address for the mailbox. This right differs from the "<TT>i</TT>" right in that the delivery system inserts trace information into submitted messages. <dt><TT>c<dd>create </TT> - The user may create new sub-mailboxes of the mailbox, or delete or rename the current mailbox. <dt><TT>d<dd>delete </TT> - The user may store the "Deleted" flag, and perform expunges. <dt><TT>a<dd>administer </TT> - The user may change the ACL on the mailbox. </DL> You can combine access rights in different ways. For example: <DL compact> <DT><TT>lrs</TT> <DD>The user can read the mailbox. </DL> <DL> <DT><TT>lrsp</TT> <DD>The user can read the mailbox, and can post to it through the delivery system. Most delivery systems do not provide authentication, so the "<TT>p</TT>" right usually has meaning only for the "anonymous" user. </DL> <DL> <DT><TT>lr</TT> <DD> The user can see the mailbox and can read it, but the server does not preserve the "Seen" and "Recent" flags. This set of rights is primarily useful for "anonymous IMAP." </DL> <DL> <DT><TT>rs</TT> <DD>The user can read the mailbox and the server preserves the "Seen" and "Recent" flags, but the mailbox is not visible to the user through the various mailbox listing commands. The user must know the name of the mailbox to be able to access it. </DL> <DL> <DT><TT>lrsip</TT> <DD> The user can read and append to the mailbox, either through IMAP, or through the delivery system. </DL> <H3><A name="aclident">Identifiers</A></H3> The identifier part of an ACL entry specifies the user or group for which the entry applies. <p>There are two special identifiers, "anonymous", and "anyone", which are explained below. The meaning of other identifiers usually depends on the authorization mechanism being used (selected by <tt>--with-auth</tt> at compile time, defaulting to Unix). <H4><A NAME="aclany">"<TT>anonymous</TT>" and "<TT>anyone</TT>"</A></H4> With any authorization mechanism, two special identifiers are defined. The identifier "<TT>anonymous</TT>" refers to the anonymous, or unauthenticated user. The identifier "<TT>anyone</TT>" refers to all users, including the anonymous user. <H3><A NAME="aclauth">Kerberos vs. Unix Authorization</A></H3> The Cyrus IMAP server comes with four authorization mechanisms, one is compatible with Unix-style ("<tt>/etc/passwd</tt>") authorization, one for use with Kerberos 4, one for use with Kerberos 5, and one for use with an external authorization process (ptloader) which can interface with other group databases (e.g. AFS PTS groups, LDAP Groups, etc). <p>Note that authorization is <b>not</b> authentication. Authentication is the act of proving who you are. Authorization is the act of determining what rights you have. Authentication is discussed in the <a href="#login">Login Authentication</a> part of this document. <p>In the Unix authorization mechanism, identifiers are either a valid userid or the string "<tt>group</tt>": followed by a group listed in "<tt>/etc/group</tt>". Thus: <pre> root Refers to the user root group:staff Refers to the group staff </pre> <p>It is also possible to use unix groups with users authenticated through a non-/etc/passwd backend. Note that using unix groups in this way (without associated /etc/passwd entries) is not recommended. <p>Using the Kerberos authorization mechanism, identifiers are of the form: <pre> <VAR>principal</VAR>.<VAR>instance</VAR>@<VAR>realm</VAR> </pre> If "<TT>.<VAR>instance</VAR></TT>" is omitted, it defaults to the null string. If "<TT>@<VAR>realm</VAR></TT>" is omitted, it defaults to the local realm. <p>The file "<TT>/etc/krb.equiv</TT>" contains mappings between Kerberos principals. The file contains zero or more lines, each containing two fields. Any identity matching the first field of a line is changed to the second identity during canonicalization. For example, a line in "<TT>/etc/krb.equiv</TT>" of: <pre> bovik@REMOTE.COM bovik </pre> will cause the identity "<TT>bovik@REMOTE.COM</TT>" to be treated as if it were the local identity "<TT>bovik</TT>". <p>A site may wish to write their own authorization mechanism, perhaps to implement a local group mechanism. If it does so (by implementing an <tt>auth_[whatever]</tt> module), it will dictate its own form and meaning of identifiers. <H3><A name="aclneg">Negative Rights</A></H3> Any of the above defined identifiers may be prefixed with a "<TT>-</TT>" character. The associated rights are then removed from that identifier. These are referred to as "negative rights". <H3><A NAME="acluser">Calculating Users' Rights</A></H3> To calculate the set of rights granted to a user, the server first calculates the union of all of the rights granted to the user and to all groups the user is a member of. The server then calculates and removes the union of all the negative rights granted to the user and to all groups the user is a member of. <p>For example, given the ACL: <pre> anyone lrsp fred lwi -anonymous s </pre> The user "<TT>fred</TT>" will be granted the rights "<TT>lrswip</TT>" and the anonymous user will be granted the rights "<TT>lrp</TT>". <H4><A name="acladm">Implicit Rights for Administrators on Personal Mailboxes</A></H4> Regardless of the ACL on a mailbox, users who are listed in the "admins" configuration option in "<tt>/etc/imapd.conf</tt>" implicitly have the "<tt>l</tt>" and "<tt>a</tt>" rights on all mailboxes. Users also implicitly have the "<tt>l</tt>" and "<tt>a</tt>" rights on their INBOX and all of their personal mailboxes. <H3><A name="aclmbox">Initial ACLs for Newly Created Mailboxes</A></H3> When a mailbox is created, its ACL starts off with a copy of the ACL of its closest parent mailbox. When a user is created, the ACL on the user's <TT>INBOX</TT> starts off with a single entry granting all rights to the user. When a non-user mailbox is created and does not have a parent, its ACL is initialized to the value of the "<TT>defaultacl</TT>" option in "<tt>/etc/imapd.conf</tt>"<p> Note that some rights are available implicitly, for example 'anonymous' always has 'p' on user INBOXes, and users always have rights on mailboxes within their INBOX hierarchy. <h2><a name="login">Login Authentication</A></H2> This section discusses different types of authentication (ways of logging in) that can be used with Cyrus IMAP. <p>The Cyrus IMAP server uses the Cyrus SASL library for authentication. This section describes how to configure SASL with use with Cyrus imapd. Please consult the Cyrus SASL System Administrator's Guide for more detailed, up-to-date information. <h3><a name="loginanon">Anonymous Logins</A></H3> Regardless of the SASL mechanism used by an individual connection, the server can support anonymous login. If the "<TT>allowanonymouslogin</TT>" option in "<tt>/etc/imapd.conf</tt>" is turned on, then the server will permit plaintext password logins using the user "<TT>anonymous</TT>" and any password. Additionally, the server will enable any SASL mechanisms that allow anonymous logins. <h3><a name="loginplain">Plaintext Authentication</a></h3> The SASL library has several ways of verifying plaintext passwords Plaintext passwords are passed either by the IMAP <tt>LOGIN</tt> command or by the SASL <TT>PLAIN</TT> mechanism (under a TLS layer). <ul> <li>PAM <li>Kerberos v4 Plaintext passwords are verified by obtaining a ticket for the server's Kerberos identity, to protect against Kerberos server spoofing attacks. <li><tt>/etc/passwd</tt> <li><tt>/etc/shadow</tt> <li>etc. </ul> <tt>sasl_auto_transition</tt> automatically creates secrets for shared secret authentication when given a password. <p>The method of plaintext password verification is always through the SASL library, even in the case of the internal LOGIN command. This is to allow the SASL library to be the only source of authentication information. You'll want to look at the <tt>sasl_pwcheck_method</tt> option in the SASL documentation to understand how to configure a plaintext password verifier for your system. <p>To disallow the use of plaintext passwords for authentication, you can set <tt>allowplaintext: no</tt> in imapd.conf. This will still allow PLAIN under TLS, but IMAP LOGIN commands will now fail. <h3><a name="loginker">Kerberos Logins</A></H3> The Kerberos SASL mechanism supports the <TT>KERBEROS_V4</TT> authentication mechanism. The mechanism requires that a <TT>srvtab</TT> file exist in the location given in the "<TT>srvtab</TT>" configuration option. The <TT>srvtab</TT> file must be readable by the Cyrus server and must contain a "<TT>imap.<VAR><host></VAR><VAR>@<realm></VAR></TT>" service key, where <TT><VAR><host></VAR></TT> is the first component of the server's host name and <TT><VAR><realm></VAR></TT> is the server's Kerberos realm. <p>The server will permit logins by identities in the local realm and identities in the realms listed in the "<TT>loginrealms</TT>" option in "<tt>/etc/imapd.conf</tt>". <p>The file "<TT>/etc/krb.equiv</TT>" contains mappings between Kerberos principals. The file contains zero or more lines, each containing two fields. Any identity matching the first field of a line is permitted to log in as the identity in the second field. <p>If the "<TT>loginuseacl</TT>" configuration option is turned on, than any Kerberos identity that is granted the "<tt>a</tt>" right on the user's <TT>INBOX</TT> is permitted to log in as that user. <h3><a name="loginmd5">Shared Secrets Logins</a></h3> Some mechanisms require the user and the server to share a secret (generally a password) that can be used for comparison without actually passing the password in the clear across the network. For these mechanism (such as CRAM-MD5 and DIGEST-MD5), you will need to supply a source of passwords, such as the sasldb (which is described more fully in the Cyrus SASL distribution) <h2><a name="quota">Quotas</a></h2> Quotas allow server administrators to limit resources used by hierarchies of mailboxes on the server. <h3><a name="quotasup">Supports Quotas on Storage</a></h3> <p>The Cyrus IMAP server supports quotas on storage, which is defined as the number of bytes of the relevant RFC-822 messages, in kilobytes. Each copy of a message is counted independently, even when the server can conserve disk space use by making hard links to message files. The additional disk space overhead used by mailbox index and cache files is not charged against a quota. <h3><a name="quotaroots">Quota Roots</a></h3> Quotas are applied to quota roots, which can be at any level of the mailbox hierarchy. Quota roots need not also be mailboxes. <p>Quotas on a quota root apply to the sum of the usage of any mailbox at that level and any sub-mailboxes of that level that are not underneath a quota root on a sub-hierarchy. This means that each mailbox is limited by at most one quota root. <p>For example, if the mailboxes <pre> user.bovik user.bovik.list.imap user.bovik.list.info-cyrus user.bovik.saved user.bovik.todo </pre> <p>exist and the quota roots <pre> user.bovik user.bovik.list user.bovik.saved </pre> exist, then the quota root "<TT>user.bovik</TT>" applies to the mailboxes "<TT>user.bovik</TT>" and "<TT>user.bovik.todo</TT>"; the quota root "<tt>user.bovik.list</tt>" applies to the mailboxes "<tt>user.bovik.list.imap</tt>" and "<tt>user.bovik.list.info-cyrus</tt>"; and the quota root "<tt>user.bovik.saved</tt>" applies to the mailbox "<tt>user.bovik.saved</tt>". <p>Quota roots are created automatically when they are mentioned in the "<tt>setquota</tt>" command. Quota roots may not be deleted through the protocol, see <A href="#recoveryquotasrm">Removing Quota Roots</A> for instructions on how to delete them. <h3><a name="quotamail">Mail Delivery Behavior</a></h3> Normally, in order for a message to be inserted into a mailbox, the quota root for the mailbox must have enough unused storage so that inserting the message will not cause the block quota to go over the limit. <p>Mail delivery is a special case. In order for a message to be delivered to a mailbox, the quota root for the mailbox must not have usage that is over the limit. If the usage is not over the limit, then one message may be delivered regardless of its size. This puts the mailbox's usage over the quota, causing a user to be informed of the problem and permitting them to correct it. If delivery were not permitted in this case, the user would have no practical way of knowing that there was mail that could not be delivered. <p>If the usage is over the limit, then the mail delivery will fail with a temporary error. This will cause the delivery system to re-attempt delivery for a couple of days (permitting the user time to notice and correct the problem) and then return the mail to the sender. <h3><a name="quotawarnings">Quota Warnings Upon Select When User Has "<TT>d</TT>" Rights</a></h3> When a user selects a mailbox whose quota root has usage that is close to or over the limit and the user has "<TT>d</TT>" rights on the mailbox, the server will issue an alert notifying the user that usage is close to or over the limit. The threshold of usage at which the server will issue quota warnings is set by the "<TT>quotawarn</TT>" configuration option. <p>The server only issues warnings when the user has "<TT>d</TT>" rights because only users with "<TT>d</TT>" rights are capable of correcting the problem. <h3><a name="quotapartitions">Quotas and Partitions</a></h3> Quota roots are independent of <A href="#partitions">partitions</A>. A single quota root can apply to mailboxes in different partitions. <h2><a name="notification">New Mail Notification</a></h2> <p>The Cyrus IMAP server comes with a notification daemon which supports multiple mechanisms for notifying users of new mail. Notifications can be configured to be sent upon normal delivery (<tt>"MAIL"</tt> class) and/or sent as requested by a <a href=specs.html#sieve>Sieve</a> script (<tt>"SIEVE"</tt> class). <p>By default, both types of notifications are disabled. Notifications are enabled by using one or both of the following configuration options: <ul> <li> the "<TT>mailnotifier</TT>" option selects the <a href=man/notifyd.8.html>notifyd</a> method to use for "<tt>MAIL</tt>" class notifications </li> <li> the "<TT>sievenotifier</TT>" option selects the <a href=man/notifyd.8.html>notifyd</a> method to use for "<tt>SIEVE</tt>" class notifications (when no method is specified by the Sieve action) </li> </ul> <h2><a name="partitions">Partitions</a></h2> Partitions allow administrators to store different mailboxes in different parts of the Unix filesystem. This is intended to be used to allow hierarchies of mailboxes to be spread across multiple disks. <h3><a name="partitionscreate">Specifying Partitions with "<TT>create</TT>"</a></h3> When an administrator creates a new mailbox, the name of the partition for the mailbox may be specified using an optional second argument to the "<TT>create</TT>" command. Non-administrators are not permitted to specify the partition of a mailbox. If the partition is not specified, then the mailbox inherits the partition of its most immediate parent mailbox. If the mailbox has no parent, it gets the partition specified in the "<TT>defaultpartition</TT>" configuration option. <P>The optional second argument to the "<TT>create</TT>" command can usually be given only when using a specialized Cyrus-aware administrative client such as <I>cyradm</I>. <h3><a name="partitionsrename">Changing Partitions with "<TT>rename</TT>"</a></h3> An administrator may change the partition of a mailbox by using the rename command with an optional third argument. When a third argument to rename is given, the first and second arguments can be the same--this changes the partition of a mailbox without changing its name. If a third argument to rename is not given and the first argument is not "<TT>INBOX</TT>", the partition of a mailbox does not change. If a third argument to rename is not given and the first argument is "<TT>INBOX</TT>", the newly created mailbox gets the same partition it would get from the "<TT>create</TT>" command. <h2><A NAME="news">News</a></h2> Cyrus has the ability to export Usenet via IMAP and/or export shared IMAP mailboxes via an NNTP server which is included with Cyrus. For more information on exporting news groups through the IMAP server, see <a href="install-netnews.html">install-netnews.html</a>. <h2><a name="pop3">POP3 Server</a></h2> The Cyrus IMAP server software comes with a compatibility POP3 server. Due to limitations in the POP3 protocol, the server can only access a user's <tt>INBOX</tt> and only one instance of a POP3 server may exist for any one user at any time. While a POP3 server has a user's <tt>INBOX</tt> open, expunge operations from any concurrent IMAP session will fail. <p>When Kerberos login authentication is being used, the POP3 server uses the server identity "<TT>pop.<VAR>host</VAR>@<VAR>realm</VAR></TT>" instead of "<TT>imap.<VAR>host</VAR>@<VAR>realm</VAR></TT>", where "<TT><VAR>host</VAR></TT>" is the first component of the server's host name and "<TT><VAR>realm</VAR></TT>" is the server's Kerberos realm. When the POP3 server is invoked with the "<TT>-k</TT>" switch, the server exports MIT's KPOP protocol instead of generic POP3. <h3><a name="syslog">The <TT>syslog</TT> facility</a></h3> The Cyrus IMAP server software sends log messages to the "<TT>local6</TT>" syslog facility. The severity levels used are: <UL> <LI><TT>CRIT</TT> - Critical errors which probably require prompt administrator action <LI><TT>ERR</TT> - I/O errors, including failure to update quota usage. The syslog message includes the specific file and Unix error. <LI><TT>WARNING</TT> - Protection mechanism failures, client inactivity timeouts <LI><TT>NOTICE</TT> - Authentications, both successful and unsuccessful <LI><TT>INFO</TT> - Mailbox openings, duplicate delivery suppression </UL> <h2><a name="recovery">Mail Directory Recovery</a></h2> This section describes the various databases used by the Cyrus IMAP server software and what can be done to recover from various inconsistencies in these databases. <h3><a name="recoverymboxdir">Reconstructing Mailbox Directories</a></h3> The largest database is the mailbox directories. Each mailbox directory contains the following files: <DL> <DT>message files <DD> There is one file per message, containing the message in RFC 822 format. Lines in the message are separated by CRLF, not just LF. The file name of each message is the message's UID followed by a dot (.). <P>In netnews newsgroups, the message files instead follow the format and naming conventions imposed by the netnews software. <P> <DT><TT>cyrus.header</TT> <DD>This file contains a magic number and variable-length information about the mailbox itself. <P> <DT><TT>cyrus.index</TT> <DD>This file contains fixed-length information about the mailbox itself and each message in the mailbox. <P> <DT><TT>cyrus.cache</TT> <DD>This file contans variable-length information about each message in the mailbox. <P> <DT><TT>cyrus.seen</TT> <DD>This file contains variable-length state information about each reader of the mailbox who has "<TT>s</TT>" permissions. </DL> The "<TT>reconstruct</TT>" program can be used to recover from corruption in mailbox directories. If "<TT>reconstruct</TT>" can find existing header and index files, it attempts to preserve any data in them that is not derivable from the message files themselves. The state "<TT>reconstruct</TT>" attempts to preserve includes the flag names, flag state, and internal date. "<TT>Reconstruct</TT>" derives all other information from the message files. <p>An administrator may recover from a damaged disk by restoring message files from a backup and then running reconstruct to regenerate what it can of the other files. <p>The "<TT>reconstruct</TT>" program does not adjust the quota usage recorded in any quota root files. After running reconstruct, it is advisable to run "<TT>quota -f</TT>" (described below) in order to fix the quota root files. <h3><a name="recoverymbox">Reconstructing the Mailboxes File</a></h3> <B><I> NOTE: CURRENTLY UNAVAILABLE </I></B> <p> The mailboxes file in the configuration directory is the most critical file in the entire Cyrus IMAP system. It contains a sorted list of each mailbox on the server, along with the mailboxes quota root and ACL. To reconstruct a corrupted mailboxes file, run the "<TT>reconstruct -m</TT>" command. The "<TT>reconstruct</TT>" program, when invoked with the "<TT>-m</TT>" switch, scavenges and corrects whatever data it can find in the existing mailboxes file. It then scans all partitions listed in the imapd.conf file for additional mailbox directories to put in the mailboxes file. <p>The <TT>cyrus.header</TT> file in each mailbox directory stores a redundant copy of the mailbox ACL, to be used as a backup when rebuilding the mailboxes file. <h3><a name="recoveryquotas">Reconstructing Quota Roots</a></h3> The subdirectory "<TT>quota</TT>" of the configuration directory (specified in the "<TT>configdirectory</TT>" configuration option) contains one file per quota root, with the file name being the name of the quota root. These files store the quota usage and limits of each of the quota roots. <p>The "<TT>quota</TT>" program, when invoked with the "<TT>-f</TT>" switch, recalculates the quota root of each mailbox and the quota usage of each <a href="#quotaroots">quota root</a>. <h4><a name="recoveryquotasrm">Removing Quota Roots</a></h4> To remove a quota root, remove the quota root's file. Then run "<TT>quota -f</TT>" to make the quota files consistent again. <h3><a name="recoverysubs">Subscriptions</a></h3> The subdirectory "<TT>user</TT>" of the configuration directory contains user subscriptions. There is one file per user, with a filename of the userid followed by "<TT>.sub</TT>". Each file contains a sorted list of subscribed mailboxes. <p>There is no program to recover from damaged subscription files. A site may recover from lost subscription files by restoring from backups. <h2><a name="configdir">Configuration Directory</a></h2> Many objects in the configuration directory are discussed in the Database Recovery section. This section documents two other directories that reside in the configuration directory. <h3><a name="configdirlog">"<TT>log</TT>" Directory</a></h3> The subdirectory "<TT>log</TT>" under the configuration directory permits administrators to keep protocol telemetry logs on a per-user basis. <p>If a subdirectory of "<TT>log</TT>" exists with the same name as a user, the IMAP and POP3 servers will keep a telemetry log of protocol sessions authenticating as that user. The telemetry log is stored in the subdirectory with a filename of the server process-id and starts with the first command following authentication. <h3><a name="configdirproc">"<TT>proc</TT>" Directory</a></h3> The subdirectory "<TT>proc</TT>" under the configuration directory contains one file per active server process. The file name is the ASCII representation of the process id and the file contains the following tab-separated fields: <UL> <LI>hostname of the client <LI>login name of the user, if logged in <LI>selected mailbox, if a mailbox is selected </UL> The file may contain arbitrary characters after the first newline character. <p>The "<TT>proc</TT>" subdirectory is normally be cleaned out on server reboot. <h2>Message Delivery</h2><a name="messagedelivery"></a> <p>Mail transport agents such as Sendmail, Postfix, or Exim communicate with the Cyrus server via LMTP (the Local Mail Transport Protocol) implemented by the LMTP daemon. This can be done either directly by the MTA (prefered, for performance reasons) or via the <tt>deliver</tt> LMTP client. <h3>Local Mail Transfer Protocol</h3><a name="lmtp"></a> <p>LMTP, the Local Mail Transfer Protocol, is a variant of SMTP design for transferring mail to the final message store. LMTP allows MTAs to deliver "local" mail over a network. This is an easy optimization so that the IMAP server doesn't need to maintain a queue of messages or run an MTA.</p> <p>The Cyrus server implements LMTP via the <tt>lmtpd</tt> daemon. LMTP can either be used over a network via TCP or local via a UNIX domain socket. There are security differnces between these two alternatives; read more below</p> <p>For final delivery via LMTP over a TCP socket, it is necessary to use LMTP AUTH. This is accomplished using SASL to authenticate the delivering user. If your mail server is performing delivery via LMTP AUTH (that is, using a SASL mechanism), you will want their authentication id to be an LMTP admins (either via the <tt>admins</tt> imapd.conf option or via the <tt><service>_admins</tt> option, typically <tt>lmtp_admins</tt>).</p> <p>Alternatively you may deliver via LMTP to a unix domain socket, and the connection will be preauthenticated as an administrative user (and access control is accomplished by controlling access to the socket).</p> <p>Note that if a user has a sieve script, the sieve script runs authorized as *that* user, and the rights of the posting user are ignored for the purposes of determining the outcome of the sieve script.</p> <h3>Single Instance Store</h3><a name="singleinstance"></a> <p>If a delivery attempt mentions several recipients (only possible if the MTA is speaking LMTP to <tt>lmtpd</tt>), the server attempts to store as few copies of a message as possible. It will store one copy of the message per partition, and create hard links for all other recipients of the message.</p> <p>Single instance store can be turned off by using the "singleinstancestore" flag in the configuration file.</p> <h3>Duplicate Delivery Suppression</h3><a name="duplicate"></a> A message is considered a duplicate if two copies of a message with the same message-id and the same envelope receipient are received. Cyrus uses the duplicate delivery database to hold this information, and it looks approximately 3 days back in the default install. <p>Duplicate delivery suppression can be turned off by using the "duplicatesuppression" flag in the configuration file.</p> <h3>Sieve, a Mail Filtering Language</h3><a name="sieve"></a> Sieve is a mail filtering language that can filter mail into an appropriate IMAP mailbox as it is delivered via lmtp. For more information, look <A HREF="sieve.html">here</a>. <h3>Cyrus Murder, the IMAP Aggregator</h3><a name="aggregator"></a> Cyrus now supports the distribution of mailboxes across a number of IMAP servers to allow for horizontal scalability. For information on setting up this configuration, see <A href="install-murder.html">here</A>. <P><HR><P> <A HREF="index.html">Return</A> to the Cyrus IMAP Server Home Page </BODY></HTML>