|
|
|
| Computing Services Home |
| ASG Home |
| What's New |
| Cyrus Wiki |
| Employment |
| Contact Us |
This document has not been reviewed in detail since 1997. However, the technical content is still basically valid (as of 2002).
In the initial implementation, non-ASCII characters, shell metacharacters, and "/" are not permitted in mailbox names. Later versions of the server may make the set of permissible characters configurable at each site.
All personal mailboxes for user "bovik" begin with the string "user.bovik.". The mailbox "user.bovik" is a special case. From user bovik's point of view, the mailbox user.bovik is named INBOX. If the access control list of the user.bovik mailbox permits other users to see the mailbox, it appears to the other users as user.bovik.
The mailbox user.bovik is referred to in this document as user bovik's INBOX.
Administrators create and delete users by creating and deleting the users' INBOX. If a user has an INBOX, then they are allowed to subscribe to mailboxes. Only users without dots in their userid are permitted to have an INBOX. (A user with a dot in their userid would be able to login but would not be able to receive mail.)
When an administrator deletes a user's INBOX, all of the user's personal mailboxes are deleted as well.
With the one notable exception of INBOX, all mailbox names are system-wide--they refer to the same mailbox regardless of the user. Access control lists determine which users can access or see which mailboxes.
In contexts which permit relative mailbox names, the mailbox namespace works as follows:
Thus, if you are
working with folder names and the top of the
hierarchy is named cmu., the name comp.infosystems.www
resolves to comp.infosystems.www and the name
.comp.infosystems.www resolves to cmu.comp.infosystems.www.
Access
This section describes Access Control Lists and access rights.
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.
The defined rights are:
You can combine access rights in different ways. For example:
In the Unix authorization mechanism, identifiers are either a
userid listed in /etc/passwd or the string group:
followed by a group listed in /etc/group. Thus:
If .instance is omitted, it defaults to the null string. If
@realm is omitted, it defaults to the local realm.
Principal, instance, or realm may be
replaced by the * wildcard.
None of the above refer to the anonymous user.
The file /etc/krb.equiv 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
/etc/krb.equiv of:
A site may wish to write their own authorization mechanism, perhaps
to implement a local group mechanism.
Any of the above defined identifiers may be prefixed with a "-"
character. The associated rights are then removed from that
identifier. These are referred to as "negative rights."
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.
For example, given the ACL:
The user fred will be granted the rights lrswip
and the anonymous user will be granted the rights lrp.
Regardless of the ACL on a mailbox, users who are listed in the
"admins" configuration option in /etc/imapd.conf implicitly have the
l and a rights on all mailboxes. Users also implicitly
have the l and a rights on their INBOX and all of
their personal mailboxes.
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 INBOX 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 defaultacl option in
/etc/imapd.conf
This section discusses different types of logins that can be used
with IMAP.
The Cyrus IMAP server comes with two login authentication mechanisms,
one for use with Kerberos, one for use with Unix /etc/passwd files.
Since authentication is closely tied with authorization, the
login authentication mechanism chosen must be compatible with the
authorization mechanism chosen.
Regardless of the login authentication mechanism chosen, the server
can support anonymous login. If the allowanonymouslogin
option in /etc/imapd.conf is turned on, then the server
will permit plaintext password logins using the user anonymous
and any password.
The Kerberos mechanism supports both the KERBEROS_V4
authentication mechanism and plaintext logins, verifying information
using Kerberos version 4. The mechanism requires that a
srvtab file exist in the location given in the
srvtab configuration option. The srvtab file must
be readable by the Cyrus server and must contain a
imap.<host>@<realm> service key, where
<host> is the first component of the server's host name
and <realm> is the server's Kerberos realm. Plaintext
passwords are verified by obtaining a ticket for the server's Kerberos
identity, to protect against Kerberos server spoofing attacks.
The server will permit logins by identities in the local realm and identities
in the realms listed in the loginrealms option in
/etc/imapd.conf.
The file /etc/krb.equiv 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.
The imap server identities for the hosts listed in the
imspservers configuration option are permitted to log in as
any user. This permits IMSP servers to perform commands for their
clients by proxy.
If the loginuseacl configuration option is turned on, than any
Kerberos identity that is granted the a right on the user's
INBOX is permitted to log in as that user.
The Unix mechanism permits plaintext logins, verifying the supplied
user and password against information in the Unix passwd file.
Quotas allow server administrators to limit resources used by
hierarchies of mailboxes on the server.
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.
Quotas are applied to quota roots, which can be at any level of the
mailbox hierarchy. Quota roots need not also be mailboxes.
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.
For example, if the mailboxes
exist and the quota roots
exist, then the quota root user.bovik applies to the mailboxes
user.bovik and user.bovik.todo; the quota root
user.bovik.list applies to the mailboxes user.bovik.list.imap
and user.bovik.list.info-cyrus; and the quota root
user.bovik.saved applies to the mailbox user.bovik.saved.
Quota roots are created automatically when they
are mentioned in the
setquota command. Quota roots may not be deleted through the
protocol, see Removing Quota Roots for
instructions on how to delete them.
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.
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.
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.
When a user selects a mailbox whose quota root has usage that is close
to or over the limit and the user has dd 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 quotawarn configuration option.
The server only issues warnings when the user has d rights because
only users with d rights are capable of correcting the problem.
Quota roots are independent of partitions. A single
quota root can apply to mailboxes in different partitions.
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.
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 create 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 defaultpartition configuration
option.
The optional second argument to the create command can
usually be given only when using a specialized administrative client
such as cyradm.
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 INBOX, the partition of a mailbox does not change.
If a third argument to rename is not given and the first argument is
INBOX, the newly created mailbox gets the same partition it would
get from the create command.
This section contains an overview of concepts related to exporting
news groups through the IMAP server.
The partition named news is reserved for netnews and cannot be used
for any other purpose.
The IMAP server can export netnews newsgroups as IMAP mailboxes. This
is done by creating a partition named news which points to the news
spool directory and arranging for the IMAP server's auxiliary
databases to be maintained. The server software includes programs for
integrating with the INN netnews server. The following information
assumes working knowledge of the INN netnews server.
The collectnews program takes as input a list of article file
path names relative to the news spool directory. It then adds those
messages to the auxiliary databases. If collectnews encounters a
newsgroup that does not have a corresponding IMAP
mailbox listed in the mailboxes file (described later), it adds it there.
The collectnews program is normally run from cron as
the cyrus user. It is given as input a news overview feed. Since
collectnews needs to write the auxiliary databases in the news spool
area, the cyrus user must be in the news group and the news group must
be able to write to the news spool area.
The rmnews program takes a list of article pathnames relative to the
news spool directory. It removes (expunges) any mention of those
messages from the auxiliary databases and unlinks the article files.
The rmnews program is used to remove both expired and canceled articles.
Rmnews takes the same input as the fastrm program. It is
normally run to clean up after expire by invoking
news.daily with the delayrm argument and having
RMPROC in expirerm changed from fastrm to
rmnews.
Rmnews is also normally run from cron as the cyrus
user to remove canceled and superseded articles. It is given as input
a special cancel feed. Patches to INN to add support for a cancel
feed are included in the Cyrus IMAP server distribution.
As rmnews is invoked at expire time by the news user and
must be able to write to the auxiliary databases, it must be installed with
set-uid to the cyrus user and set-gid to the news group.
[[Removes the entry in mailboxes for removed newsgroups. Not written yet.]]
[[defer until implemented]]
The Cyrus IMAP server software comes with a compatible POP3 server.
Due to limitations in the POP3 protocol, the server can only access a
user's INBOX 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 INBOX open,
expunge operations from any concurrent IMAP session will fail.
When Kerberos login authentication is being used, the POP3 server uses
the server identity pop.host@realm instead of
imap.host@realm, where host is the first component
of the server's host name and realm is the server's Kerberos
realm. When the POP3 server is invoked with the -k switch,
the server exports MIT's KPOP protocol instead of generic POP3.
The Cyrus IMAP server software sends log messages to the local6
syslog facility. The severity levels used are:
The reconstruct program can be used to recover from
corruption in mailbox directories. If reconstruct 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 reconstruct attempts to preserve includes the flag
names, flag state, and internal date. Reconstruct
derives all other information from the message files.
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.
The reconstruct program does not adjust the quota usage recorded in
any quota root files. After running reconstruct, it is advisable to
run quota -f (described below) in order to fix the quota root files.
The subdirectory quota of the configuration directory (specified in
the configdirectory 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.
The quota program, when invoked with the -f switch,
recalculates the quota root of each mailbox and the quota usage of
each quota root.
To remove a quota root, remove the quota root's file. Then run
quota -f to make the quota files consistent again.
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. Because the ACL is security-critical information that cannot be
reconstructed from information stored elsewhere, there is no program
to recover from a damaged mailboxes file.
To protect the contents of the mailboxes, we suggest
making frequent, even hourly backups of the
mailboxes file to some other part of the disk.
The subdirectory user of the configuration directory contains user
subscriptions. There is one file per user, with a filename of the
userid followed by .sub. Each file contains a sorted list of
subscribed mailboxes.
There is no program to recover from damaged subscription files. A
site may recover from lost files simply by restoring from backups.
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.
The subdirectory log under the configuration directory permits
administrators to keep protocol telemetry logs on a per-user basis.
If a subdirectory of log 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.
The subdirectory proc 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:
The file may contain arbitrary characters after the first newline
character.
The proc subdirectory is normally be cleaned out on server reboot.
The following sites contain additional information about
IMAP:
The user may select the mailbox, fetch data, perform searches,
and copy messages from the mailbox.
The identifier part of an ACL entry specifies the user or group
for which the entry applies. The meaning of an identifier
usually depends on the authorization mechanism being used.
With any authorization mechanism, two special identifiers are defined.
The identifier anonymous refers to the anonymous, or unauthenticated
user. The identifier anyone refers to all users, including the
anonymous user.
The Cyrus IMAP server comes with two authorization mechanisms, one for
use with Unix /etc/passwd files, one for use with Kerberos.
root Refers to the user root
group:staff Refers to the group staff
Using the Kerberos authorization mechanism, identifiers are of the
form:
anyone lrsp
fred lwi
-anonymous s
user.bovik
user.bovik.list.imap
user.bovik.list.info-cyrus
user.bovik.saved
user.bovik.todo
user.bovik
user.bovik.list
user.bovik.saved
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.
The largest database is the mailbox directory. Each
mailbox directory contains the following files: