539 lines
14 KiB
Plaintext
539 lines
14 KiB
Plaintext
Cyrus IMAP HOWTO
|
|
Aurora Skarra-Gallagher (Community Vision)
|
|
v1.3, 11 October 2000
|
|
|
|
A comprehensive guide to installing, configuring, and running Cyrus
|
|
Imap and Cyrus Sasl
|
|
______________________________________________________________________
|
|
|
|
Table of Contents
|
|
|
|
|
|
|
|
1. About this HOWTO
|
|
|
|
1.1 Copyrights and Trademarks
|
|
1.2 Feedback
|
|
1.3 CHANGES
|
|
1.4 Document Conventions
|
|
|
|
2. Introduction to IMAP
|
|
|
|
2.1 What is IMAP?
|
|
2.2 IMAP vs. POP
|
|
2.3 Cyrus IMAP vs. Washington IMAP
|
|
|
|
3. Obtaining the Files
|
|
|
|
3.1 Cyrus Imap Homepage
|
|
3.2 Downloading the files
|
|
|
|
4. Different SASL Authentication Methods
|
|
|
|
4.1 sasldb
|
|
4.2 LDAP
|
|
4.3 PAM
|
|
4.4 kerberos_v4
|
|
|
|
5. Cyrus SASL
|
|
|
|
5.1 Uncompress
|
|
5.2 Building the files
|
|
|
|
6. Cyrus IMAP Installation
|
|
|
|
6.1 Uncompress
|
|
6.2 A note on com_err.h
|
|
6.3 Configure
|
|
6.4 Adding the default user
|
|
6.5 Building the files
|
|
|
|
7. Cyrus IMAP Configuration
|
|
|
|
7.1 Editing conf files
|
|
7.2 Creating the necessary directories
|
|
7.3 More configuration file editing
|
|
7.4 If you use postfix instead of sendmail
|
|
|
|
8. Cyrus IMAP Implementation
|
|
|
|
8.1 Add the cyrus administrator
|
|
8.2 Testing Cyrus IMAP
|
|
8.3 Setting up users
|
|
8.4 Delivery database pruning
|
|
8.5 Finishing up
|
|
|
|
9. Troubleshooting
|
|
|
|
|
|
|
|
______________________________________________________________________
|
|
|
|
1. About this HOWTO
|
|
|
|
1.1. Copyrights and Trademarks
|
|
|
|
(c) 2000 Aurora Skarra-Gallagher
|
|
|
|
|
|
This section was copied from the HOWTO-HOWTO:
|
|
|
|
This manual may be reproduced in whole or in part, without fee,
|
|
subject to the following restrictions:
|
|
|
|
|
|
· The copyright notice above and this permission notice must be
|
|
preserved complete on all complete or partial copies
|
|
|
|
· Any translation or derived work must be approved by the author in
|
|
writing before distribution.
|
|
|
|
· If you distribute this work in part, instructions for obtaining the
|
|
complete version of this manual must be included, and a means for
|
|
obtaining a complete version provided.
|
|
|
|
· Small portions may be reproduced as illustrations for reviews or
|
|
quotes in other works without this permission notice if proper
|
|
citation is given. Exceptions to these rules may be granted for
|
|
academic purposes: Write to the author and ask. These restrictions
|
|
are here to protect us as authors, not to restrict you as learners
|
|
and educators. Any source code (aside from the SGML this document
|
|
was written in) in this document is placed under the GNU General
|
|
Public License, available via anonymous FTP from the GNU archive.
|
|
|
|
1.2. Feedback
|
|
|
|
Comments (especially corrections) can be sent to
|
|
asg@CommunityVision.com <mailto:asg@CommunityVision.com>
|
|
|
|
1.3. CHANGES
|
|
|
|
|
|
· v1.3: inetd.conf error fix, authentication information added, more
|
|
troubleshooting info
|
|
|
|
· v1.2: SASL Config error fix, new postfix configuration, and
|
|
database pruning (thanks, Jernej)
|
|
|
|
· v1.1: Fixed sendmail.mc configuration file error and added IMAP
|
|
information to the introduction.
|
|
|
|
1.4. Document Conventions
|
|
|
|
|
|
· Italics signifies a directory
|
|
|
|
· This font signifies instructions to be ran at the command line
|
|
|
|
2. Introduction to IMAP
|
|
|
|
2.1. What is IMAP?
|
|
|
|
This definition is from the ComputerUser.com High-Tech Dictionary
|
|
<http://www.computeruser.com/resources/dictionary/dictionary.html>:
|
|
|
|
Internet Message Access Protocol. A protocol that allows a user to
|
|
perform certain electronic mail functions on a remote server rather
|
|
than on a local computer. Through IMAP the user can create, delete, or
|
|
rename mailboxes; get new messages; delete messages; and perform
|
|
search functions on mail. A separate protocol is required for sending
|
|
mail. Also called Internet Mail Access Protocol.
|
|
|
|
|
|
|
|
2.2. IMAP vs. POP
|
|
|
|
IMAP allows the user to read email from many different locations and
|
|
accounts because email folders are stored on the server, locally, at
|
|
the home or the office, for instance. Even saved and read messages are
|
|
stored on the IMAP server. POP only stores new unread messages on the
|
|
server, and the read and saved messages are stored locally. To force
|
|
POP to not delete email once it has been read can create many copies
|
|
of the same email, creating a waste of space and confusion. However,
|
|
IMAP is usually more complicated to set up. If you only have one email
|
|
account, POP is most likely your best choice. If you want to access
|
|
more than one account, from different locations, IMAP will probably
|
|
serve you most efficiently.
|
|
|
|
2.3. Cyrus IMAP vs. Washington IMAP
|
|
|
|
Cyrus has its own mailbox database which is standalone and increases
|
|
performance, whereas Washington uses the stanard UNIX mailbox format,
|
|
which was designed for a smaller set of users. Washington is portable
|
|
to more UNIX and non-UNIX systems than Cyrus. The main difference is
|
|
that with Cyrus, you don't have to add new users to your linux box
|
|
(i.e. in /etc/passwd) to add new mail users, and with Washington, you
|
|
do.
|
|
|
|
3. Obtaining the Files
|
|
|
|
3.1. Cyrus Imap Homepage
|
|
|
|
The homepage is currently located at:
|
|
|
|
http://asg.web.cmu.edu/cyrus/imapd
|
|
<http://asg.web.cmu.edu/cyrus/imapd>
|
|
|
|
3.2. Downloading the files
|
|
|
|
You will need both IMAP and SASL. Download the latest files here:
|
|
|
|
ftp://ftp.andrew.cmu.edu/pub/cyrus-mail
|
|
<ftp://ftp.andrew.cmu.edu/pub/cyrus-mail>
|
|
|
|
Download cyrus-imapd-X.X.X.tar.gz and cyrus-sasl-X.X.X.tar.gz (where
|
|
X.X.X is the latest release) into your temporary directory.
|
|
|
|
I will use /temp as the directory I've uncompressed the files under
|
|
for the rest of the examples.
|
|
|
|
4. Different SASL Authentication Methods
|
|
|
|
4.1. sasldb
|
|
|
|
This is the default method of authentication. It stores usernames and
|
|
passwords in the SASL secrets file sasldb. In this HOWTO, I assume you
|
|
are using the sasldb method of authentication.
|
|
|
|
4.2. LDAP
|
|
|
|
The following definition came from the OpenLDAP website. Lightweight
|
|
Directory Access Protocol (LDAP) is an open-standard protocol for
|
|
accessing information services. The protocol runs over Internet
|
|
transport protocols, such as TCP, and can be used to access stand-
|
|
alone directory servers or X.500 directories. This method isn't
|
|
discussed in this HOWTO, but here is a link to a page with patches and
|
|
info:
|
|
|
|
http://www.openldap.org/faq/data/cache/428.html
|
|
<http://www.openldap.org/faq/data/cache/428.html>
|
|
4.3. PAM
|
|
|
|
Not enough info to document. Email me if you have some.
|
|
|
|
4.4. kerberos_v4
|
|
|
|
Not enough info to document. Email me if you have some.
|
|
|
|
5. Cyrus SASL
|
|
|
|
5.1. Uncompress
|
|
|
|
Here we untar and gunzip the file in a single step.
|
|
|
|
|
|
1. cd /temp
|
|
|
|
2. tar -zxvf cyrus-sasl-X.X.X.tar.gz
|
|
|
|
3. cd cyrus-sasl-X.X.X
|
|
|
|
5.2. Building the files
|
|
|
|
For most purposes, the following set of instructions works fine. If
|
|
you would like to examine the other configuration options, type
|
|
./configure --help | more
|
|
|
|
|
|
1. ./configure
|
|
|
|
2. make
|
|
|
|
3. make install
|
|
|
|
If you don't want your password check to be the default sasldb, you
|
|
must specify which one of PAM, kerberos_v4, passwd, shadow you wish to
|
|
use. If PAM is the authentication you desire for example, you would
|
|
type:
|
|
|
|
./configure --with-pwcheck_method=PAM
|
|
|
|
instead of the ./configure line above
|
|
|
|
6. Cyrus IMAP Installation
|
|
|
|
6.1. Uncompress
|
|
|
|
The following commands will tar and gunzip cyrus IMAP under /temp.
|
|
|
|
|
|
1. cd /temp
|
|
|
|
2. tar -zxvf tar/cyrus-imapd-1.6.24.tar.gz
|
|
|
|
3. cd cyrus-imapd-1.6.24
|
|
|
|
6.2. A note on com_err.h
|
|
|
|
When I tried to install cyrus IMAP, I got errors regarding the file
|
|
com_err.h. My com_err.h was located in /usr/include/et. It needs to
|
|
reside in /usr/include. Run the following command to make sure it is
|
|
in the correct location:
|
|
|
|
locate com_err.h
|
|
|
|
|
|
This will show you where the file is. If it is under /usr/include, you
|
|
can skip to the next section. If it is in another directory, just copy
|
|
it to /usr/include. If it doesn't exist, download it here:
|
|
http://www.ludd.luth.se/~jnilsson/cvsweb/cvsweb.cgi/src/contrib/com_err
|
|
<http://www.ludd.luth.se/~jnilsson/cvsweb/cvsweb.cgi/src/contrib/com_err>.
|
|
|
|
6.3. Configure
|
|
|
|
./configure --with-auth=unix
|
|
|
|
6.4. Adding the default user
|
|
|
|
Cyrus requires a user to own its files. The default user is cyrus. The
|
|
following command adds a user cyrus with the group of "mail"
|
|
|
|
useradd -g mail cyrus
|
|
|
|
You'll want to set the password for user cyrus.
|
|
|
|
passwd cyrus
|
|
|
|
Type in the password you desire cyrus to have each time you are
|
|
prompted
|
|
|
|
6.5. Building the files
|
|
|
|
|
|
1. make depend
|
|
|
|
2. make all CFLAGS=-O
|
|
|
|
3. make install
|
|
|
|
That's it! You're ready to configure Cyrus IMAP.
|
|
|
|
7. Cyrus IMAP Configuration
|
|
|
|
7.1. Editing conf files
|
|
|
|
|
|
1. Edit /etc/syslog.conf and add the following lines at the bottom:
|
|
|
|
local6.debug /var/adm/imapd.log
|
|
auth.debug /var/adm/auth.log
|
|
|
|
|
|
|
|
2. Edit a new file /etc/imapd.conf and place in it the following
|
|
lines:
|
|
|
|
configdirectory: /var/imap
|
|
partition-default: /var/spool/imap
|
|
admins: cyrus root
|
|
srvtab: /var/imap/srvtab
|
|
allowanonymouslogin: no
|
|
sasl_passwd_check: shadow
|
|
|
|
|
|
|
|
If you don't want your password check to be the default sasldb, you
|
|
must specify which one of PAM, kerberos_v4, passwd, shadow you wish to
|
|
use. If PAM is the authentication you desire for example, you would
|
|
type:
|
|
|
|
sasl_passwd_check: pam
|
|
|
|
instead of the line above
|
|
|
|
7.2. Creating the necessary directories
|
|
|
|
This list of instructions will set up all the directories necessary
|
|
for imap.
|
|
|
|
|
|
1. mkdir /var/adm
|
|
|
|
2. touch /var/adm/imapd.log /var/adm/auth.log
|
|
|
|
3. mkdir /var/imap /var/spool/imap /var/imap/srvtab
|
|
|
|
4. chown cyrus /var/imap /var/spool/imap /var/imap/srvtab
|
|
|
|
5. chgrp mail /var/imap /var/spool/imap /var/imap/srvtab
|
|
|
|
6. chmod 750 /var/imap /var/spool/imap /var/imap/srvtab
|
|
|
|
7. su cyrus
|
|
|
|
You are now the user cyrus. This is necessary for the files to have
|
|
the correct owner and group. Continue:
|
|
|
|
|
|
1. tools/mkimap
|
|
|
|
2. cd /var/imap
|
|
|
|
3. chattr +S . user quota user/* quota/*
|
|
|
|
4. chattr +S /var/spool/imap
|
|
|
|
5. exit
|
|
|
|
You are now root again. The last command:
|
|
|
|
chattr +S /var/spool/mqueue
|
|
|
|
7.3. More configuration file editing
|
|
|
|
|
|
1. Edit /etc/services and check for the following lines. If they do
|
|
not exist, add them:
|
|
|
|
pop3 110/tcp
|
|
imap 143/tcp
|
|
imsp 406/tcp
|
|
kpop 1109/tcp
|
|
sieve 2000/tcp
|
|
|
|
|
|
|
|
2. Edit /etc/inetd.conf and comment out any imap and pop3 lines and
|
|
add the following:
|
|
|
|
imap stream tcp nowait cyrus /usr/cyrus/bin/imapd imapd
|
|
pop3 stream tcp nowait cyrus /usr/cyrus/bin/pop3d pop3d
|
|
|
|
|
|
|
|
3. Edit /etc/sendmail.mc with care not to add extra spaces and add the
|
|
following lines(do not copy and paste directly from this text as
|
|
the tabs won't be added correctly):
|
|
|
|
MAILER(local)
|
|
MAILER(cyrus)
|
|
define(`confLOCAL_MAILER',`cyrus')
|
|
LOCAL_RULE_0
|
|
R$=N $: $#local $: $1
|
|
R$=N < @ $=w . > $: $#local $: $1
|
|
Rbb + $+ < @ $=w . > $#cyrusbb $: $1
|
|
|
|
|
|
Use tabs to separate the data (i.e. R$=N has three tabs between it and
|
|
$: $#local $: $1) Then run: m4 sendmail.mc > sendmail.cf
|
|
|
|
4. Edit /etc/group and add the user daemon to the mail group.
|
|
|
|
7.4. If you use postfix instead of sendmail
|
|
|
|
Postfix is a mail-deliver alternative to sendmail. Most linux
|
|
installations use sendmail by default. If you use postfix, ignore
|
|
configuration #3 from the last section and uncomment or add the
|
|
following line in /etc/postfix/master.cf
|
|
|
|
|
|
cyrus unix - n n - - pipe flags=R user=cyrus argv=/usr/sbin/cyrdeliver -e -m ${extension} ${user}
|
|
|
|
|
|
|
|
Also add or uncomment this line in /etc/postfix/main.cf
|
|
|
|
local_transport = cyrus
|
|
|
|
8. Cyrus IMAP Implementation
|
|
|
|
8.1. Add the cyrus administrator
|
|
|
|
Run the following command to set up a user for cyrus
|
|
|
|
/usr/local/sbin/saslpasswd cyrus
|
|
|
|
8.2. Testing Cyrus IMAP
|
|
|
|
|
|
1. killall -HUP inetd
|
|
|
|
2. su cyrus
|
|
|
|
3. imtest -m login -p imap localhost
|
|
|
|
Enter your password. If you see something like:
|
|
|
|
|
|
(L01 OK User logged in means you're in)
|
|
|
|
|
|
|
|
Then the setup has been successful. Type
|
|
|
|
|
|
. logout
|
|
|
|
|
|
|
|
to log out.
|
|
|
|
|
|
|
|
8.3. Setting up users
|
|
|
|
Still as the user cyrus, type the following commands. They will set up
|
|
the mailbox(es) for each user. Fill in the username where you see the
|
|
(username).
|
|
|
|
|
|
1. cyradm localhost
|
|
|
|
2. cm user.joebob (for all the user joebob)
|
|
|
|
3. quit
|
|
|
|
4. exit (back as root)
|
|
|
|
Now as root, enter a password for each username
|
|
|
|
saslpasswd (username)
|
|
|
|
8.4. Delivery database pruning
|
|
|
|
If you don't periodically prune the database of deliveries, you can
|
|
fill up your file system. Adding a cron job which will run once a day
|
|
is one way to do this. That involves going to /etc/cron.daily and
|
|
creating a file named cyrus-imapd. Inside that file, put the following
|
|
two lines of code:
|
|
|
|
|
|
#!/bin/bash
|
|
su cyrus -s /bin/bash -c '/usr/cyrus/bin/deliver -E 3'
|
|
|
|
|
|
|
|
Make this script executable by running: chmod 755 cyrus-imapd
|
|
|
|
You should also create the deliverdb directory to store database files
|
|
in:
|
|
|
|
mkdir /var/imap/deliverdb
|
|
|
|
8.5. Finishing up
|
|
|
|
Reboot the machine to make sure that everything has been restarted
|
|
under the new configuration
|
|
|
|
9. Troubleshooting
|
|
|
|
If you encounter any errors, you can do the following to view error
|
|
messages:
|
|
|
|
|
|
1. tail /var/log/messages
|
|
|
|
2. tail /var/adm/imapd.log
|
|
|
|
3. killall sendmail && sendmail -bd -X /root/error.log (then read
|
|
/root/error.log)
|
|
|
|
If you are having "virtual memory exhausted errors" when compiling,
|
|
running
|
|
|
|
ulimit -d unlimited
|
|
|
|
as root has been reported to work.
|
|
|
|
|