- up to 2.4.13

[packages/cyrus-imapd.git] / cyrus-README

NEW CYRUS IMAP PACKAGE
======================

This package automatically installs an appropriate sendmail.cf which
provides for local delivery to the cyrus imap system. The old sendmail.cf is
saved in /etc/mail/sendmail-pre-cyrus.cf.

Support for procmail delivery is still available due to an installation
based on ideas found here:
http://www.ncworldmag.com/ncw-05-1998/ncw-05-imap.html.

The installed sendmail.cf is based on the mc file found in
/usr/lib/sendmail-cf/cf/redhat-procmail+cyrus.mc (which is now very similar
to the default redhat.mc which comes with RH5.2)

To give a short outline of the process: sendmail delivers local mail through
procmail just as with the standard RedHat setup (i.e. procmail is installed
as the local MDA). Contrary to the standard installation, procmail is given
a receipt directing mail though the cyrus delivery. Thus, messages end up
in the cyrus system.

The cyrus 'deliver' program is not executable by normal users, for security
reasons. This package installs a 'deliver-wrapper' which is world executable
and only provides (hopefully) secure parameters to 'deliver'. This means
that delivery can be done from with a user's own .procmailrc without giving
them special privileges.

If you want to roll your own sendmail.cf which invokes 'deliver' directly,
here are the instructions.


CONFIGURING SENDMAIL FOR CYRUS
==============================

You have two options:

(1) As a full replacement for your local mail system; in this case you will
no longer be able to use elm, pine etc. unless you configure them for IMAP,
because no mail will be delivered to /var/spool/mail/<user>

define(`CYRUS_MAILER_FLAGS',`A5@S')
define(`confLOCAL_MAILER',`cyrus')
mailer(cyrus)

LOCAL_RULE_0
Rbb + $+ < @ $=w . >    $#cyrusbb $: $1

[This last rule allows bb+mailbox@yourdomain to deliver to the named global
mailbox; bb refers to 'bulletin board']

Remove FEATURE(local_procmail) if it exists, or comment it out by putting
'dnl' at the beginning of the line.

(2) As an additional domain, e.g. so that user@imap.your.domain is delivered
into the cyrus mail area.

Create a mailertable (if you don't already have one) in /etc/mailertable,
containing the following line:

imap.your.domain	cyrus:inbox

Then build it like this:

makemap hash /etc/mailertable </etc/mailertable

Your m4 config file needs to contain the following:

FEATURE(mailertable)
define(`CYRUS_MAILER_FLAGS',`S')
mailer(cyrus)

Finally, point an MX record for imap.your.domain pointing to your machine.
Note that users in this domain still need to have entries in /etc/passwd,
otherwise there would be no passwords to authenticate against when reading
their mail. This limitation will go when someone integrates PAM support into
Cyrus, or you can try authenticating against an LDAP server; see
http://www.linc-dev.com/auth.html

CREATING MAILBOXES
==================

Add the usernames of the administrator user(s) to /etc/imapd.conf, separated
with spaces, e.g.

    admins: curtj abell

Then start the cyradm tool:

# cyradm localhost

Login using the username and password of one of the admin users. Type 'help'
for a list of commands.

    To create a mailbox, type:

       cm user.<userid>

    For example, to create a mailbox for the userid "smith", type:

       cm user.smith

    To limit "smith" to 10,000 kilobytes of mail, type:

       setquota user.smith 10000

    Once the inbox is created, users can create their own additional
    mailboxes from a mail program. If Smith created a work mailbox and a
    play mailbox, the full names of the mailboxes would be:

       user.smith.work
       user.smith.play

    Access rights are discussed in detail in the cyradm(1) man pages. Note
    that the administrator must grant herself delete access explicitly
    before she can delete a mailbox:

       setaclmailbox <mail_box> <admin_userid> d
       deletemailbox <mail_box>

    Once you have created mailboxes, your IMAP server installation is done.

CONFIGURING FOR ACCESS TO A NEWS SPOOL
======================================

See doc/install for details; I've not tried this myself

COMMON PROBLEMS
===============

There is a known problem with syslogging error messages about being unable
to create deliverdb messages. You can remove /var/imap/deliverdb/, however
that will then give you errors saying that this directory does not exist :-)

This database is an optimisation which prevents duplicate copies of messages
(with the same Message-ID) being delivered into mailboxes. This feature can
be disabled by removing the '-e' flag from deliver:

define(`CYRUS_MAILER_ARGS', `deliver -m $h -- $u')
define(`CYRUS_BB_MAILER_ARGS', `deliver -m $u')