Installing and configuring the IMAP Server

cyrusimap.org/docs/cyrus-imapd/2.5.6/install-configure.php

This section describes the shell scripts to run and the configuration files to modify once
"configure" and "make" have run.
1. Create a user and group for the Cyrus subsystem. The examples in this document
assume a user of "cyrus" and a group of "mail", though any user and group name
can be used. If a user other than "cyrus" is to be used, it must have been previously
specified in the "--with-cyrus-user=" option to "configure". If a group other than
"mail" is to be used, it must have been previously specified in the " --with-cyrus-
group=" option to "configure".
2. After you've logged in as "root", install the cyrus software.

make install

Be sure that the server programs ended up in the directory specified by "--with-
cyrus-prefix" (by default, "/usr/cyrus/bin").
3. The Cyrus IMAP server uses the 4.3BSD syslog that separates messages into both levels
and categories. Invoke " man syslog " to see if "openlog()" takes three arguments. If it
does not, replace the system "syslogd" and "syslog.conf" with the files provided in
the "syslog" directory.

mv syslogd /etc/syslogd
mv syslog.conf /etc/syslog.conf

If you do not copy the "syslog/syslog.conf" file to the "/etc" directory, be sure to
add support for "local6.debug". The file should include a line like:

local6.debug /var/log/imapd.log

You probably also want to log SASL messages with a line like:

auth.debug /var/log/auth.log

After installation and testing, you probably want to change the ".debug" component to
something a little less verbose. Create the log files:
touch /var/log/imapd.log /var/log/auth.log

4. Create the file "/etc/imapd.conf". Here is a sample "imapd.conf" with a minimal

number of values defined:

configdirectory: /var/imap
partition-default: /var/spool/imap
admins: curtj abell
sasl_pwcheck_method: saslauthd

For a description of all the fields in this file, see the imapd.conf(5) man page. (Note
that this file also exports values to libsasl, the most important of them the
1/9
 pwcheck_method. In this example, users are authenticated via the saslauthd
daemon, which can be run in a number of different ways.)
READ THE imapd.conf(5) MAN PAGE. There are options in there that you will want
to know about and default behavior that you may not like.

Note that everyday users should not be administrators. Admins have powers not
granted to regular users and while the server allows them to receive mail, some
problems will occur if admins are used as regular users. You also should not read mail
as an administrator. You should have separate accounts for reading mail and
administrating. This is especially true if using the altnamespace option, because
admins are always presented with the standard (internal) namespace.

5. Create the configuration directory specified by the "configdirectory" option in

"imapd.conf." The configuration directory is similar in concept to the
"/usr/lib/news" directory. It stores information about the IMAP server as a whole.
This document uses the configuration directory "/var/imap" in its examples. This
directory should be owned by the cyrus user and group and should not permit access
to other users.

cd /var
mkdir imap
chown cyrus imap
chgrp mail imap
chmod 750 imap

6. Create the default partition directories specified in the "/etc/imapd.conf" file.

This document uses a default partition directory of "/var/spool/imap" in the
following example:
cd /var/spool
mkdir imap
chown cyrus imap
chgrp mail imap
chmod 750 imap

The partition directory is similar in concept to /var/spool/news. It is where the

mailboxes are stored. Unlike most netnews systems, Cyrus allows you to have more
than one partition.
7. If you wish to use Sieve, and you didn't configure deliver to look in home directories
(see the imapd.conf man page), create the Sieve directory:

cd /usr
mkdir sieve
chown cyrus sieve
chgrp mail sieve
chmod 750 sieve

8. Change to the Cyrus user and use the tool "tools/mkimap" to create the rest of the
directories (subdirectories of the directories you just created).

su cyrus 2/9
 su cyrus
tools/mkimap
exit

If Perl is not available, it should be easy (but time consuming) to create these directories
by hand.
9. LINUX SYSTEMS USING EXT2FS ONLY: Set the user, quota, and partition directories to
update synchronously. Failure to do this may lead to data corruption and/or loss of
mail after a system crash. Unfortunately, doing so may result in a serious performance
hit. If you are using a newer filesystem than ext2fs on Linux, this step should not be
necessary. (Running ext3 in any mode is safe.)
cd /var/imap
chattr +S user quota user/* quota/*
chattr +S /var/spool/imap /var/spool/imap/*

Also set the queue directory of the mail daemon to update synchronously. The
following example is for sendmail:
chattr +S /var/spool/mqueue

10. To enable STARTTLS support, see how to configure OpenSSL below.

11. Add the following lines to the "/etc/services" file if they aren't already there.

pop3 110/tcp
nntp 119/tcp
imap 143/tcp
imsp 406/tcp
nntps 563/tcp
acap 674/tcp
imaps 993/tcp
pop3s 995/tcp
kpop 1109/tcp
lmtp 2003/tcp
sieve 4190/tcp
fud 4201/udp

12. Remove "/etc/[x]inetd.conf" entries. Any imap, imaps, pop3, pop3s, kpop, lmtp
and sieve lines need to be removed from /etc/[x]inetd.conf and [x]inetd needs
to be restarted.

Configuring the Master Process

1. Choose a configuration from the master/conf directory:
small.conf
bare-bones server supporting IMAP and POP
normal.conf
server supporting IMAP, POP, the SSL wrapped versions, and the Sieve script
management protocol
prefork.conf
3/9
 The same configuration as above, but with some preforked processes for faster
processing.
backend-cmu.conf
Our configuration (for Murder Backend / typical IMAP servers)
frontend-cmu.conf
Our configuration (for Murder Frontend servers)

To use normal.conf, do:

cp master/conf/normal.conf /etc/cyrus.conf

Optionally, you can edit /etc/cyrus.conf to disable or enable certain services, or to

tune the number of preforked copies. Be sure not to remove the entries that are
labeled required.

2. Arrange to start "/usr/cyrus/bin/master" as root when the system starts. It will

bind some ports and then give up its root privileges. Until your system reboots, you can
start the master process by hand:
/usr/cyrus/bin/master &

3. Monitor the progress of the master process by examining the imapd.log file. It should
never exit by itself, but you can shut down the mail system by sending it a signal with
kill.
4. Clean Shutdown - you can shut the master process down cleanly by sending it a
SIGQUIT rather than SIGTERM signal. This will cause the master process to send
SIGQUIT to all its children and then wait for them to finish cleanly. This avoids issues
like a message being appended by lmtpd but the sync_log record never being written.
Since a clean shutdown may never finish if a child process is stuck for some reason the
recommended approach is to send a SIGQUIT then loop on the master process sending
a signal 0 every second until either the master process has gone away or a suitable
time has expired (maybe 10 seconds). You can then send a SIGTERM if the process still
exists.

At FastMail the following snippet of perl is used (warning: Linux specific signal numbers
- check your own system before using this):

4/9
 my $pid = `cat $PIDFILE`;
chomp($pid);
print "Trying nice shutdown - killing $pid with SIGQUIT\n";
kill 3, $pid;
foreach my $num (1..10) {
if (kill 0, $pid) {
print "Not dead yet after $num seconds\n";
sleep 1;
}
else {
last;
}
}
if (kill 0, $pid) {
print "No more Mr. Nice Guy - killing $pid with SIGTERM\n";
kill 15, $pid;
}

Configuring the Mail Transfer Agent

In order to deliver mail to the Cyrus system, you'll have to configure your MTA (Sendmail,
Postfix, Exim, etc.) to use LMTP.

Configuring Sendmail
Generate a sendmail configuration file which delivers local mail to the IMAP server. See the
file cf/README in the Sendmail distribution for information on how to create a complete
configuration file. This file also lists variables that can be used to customize the mailer
definitions mentioned below.
The following configurations assume that you are using the lmtpunix service from one of
the sample cyrus.conf files discussed above.

For Sendmail 8.12.4 and higher, use the cyrusv2 mailer definition in the Sendmail
distribution:

define(`confLOCAL_MAILER', `cyrusv2')
MAILER(`cyrusv2')

If you wish to change the name of the UNIX socket or switch to TCP, define
CYRUSV2_MAILER_ARGS appropriately as described in cf/README.
For Sendmail 8.10 - 8.12.3, use the cyrusv2.mc file as a template to create a Sendmail
configuration file.
For Sendmail 8.9.x and earlier, use the cyrus mailer definition in the Sendmail
distribution:

define(`confLOCAL_MAILER', `cyrus')
MAILER(`cyrus')

Edit /etc/group and add user "daemon" to the "mail" group. This will permit
sendmail to run the "deliver" (LMTP client) program to deliver mail to the IMAP

5/9
 server.

Cyrus also includes a socket map daemon smmapd which can be used by Sendmail 8.13 and
higher (a patch for 8.12 is available) to verify at RCPT TO time that a message can be
delivered to the particular mailbox. To use this daemon, add smmapd as a service in
cyrus.conf and configure Sendmail accordingly.

Configuring Postfix
The Postfix source distribution comes with the file "README_FILES/LMTP_README". Even if
you are using a binary distribution of Postfix, it would be well worth your while to download
the full Postfix source. Not only will you get the above file, but numerous other "readme"
files and sample configuration files.
One thing you need to watch out for is the UID and GID of the Postfix software. As it states in
the Postfix "INSTALL" document, you must create a new account that does not share its UID
and GID with any other user account. This is for security reasons. If you installed Postfix with
a GID of "mail", you will need to select a different GID for Cyrus. See the Cyrus configure
options "--with-cyrus-user" and "--with-cyrus-group". (This was more crucial when
the use of Cyrus' "deliver" was more prevalent, but it is still a good idea to follow this
policy.)

Another thing to note is the location of your " sendmail" command. On some platforms this
will be "/usr/sbin/sendmail", on others, "/usr/lib/sendmail". Cyrus will need to know
where this command is. See Installing Sieve for more details.

Assuming that you are using the lmtpunix service from one of the sample cyrus.conf files
discussed above, the Postfix configuration file "/etc/postfix/main.cf" should have the
following line:

mailbox_transport = lmtp:unix:/var/imap/socket/lmtp

Naturally, both the Postfix UID and the Cyrus UID need to be able to access the specified
socket file.

Starting with Postfix snapshot-20010222, you can improve the efficiency of LMTP delivery via
the "mailbox_transport" by putting the following entries in "/etc/postfix/main.cf":

local_destination_recipient_limit = 300
local_destination_concurrency_limit = 5

Of course you should adjust these settings as appropriate for the capacity of the hardware
you are using. The recipient limit setting can be used to take advantage of the single instance
message store capability of Cyrus. The concurrency limit can be used to control how many
simultaneous LMTP sessions will be permitted to the Cyrus message store.

Additional examples are included in the Postfix file "README_FILES/LMTP_README".

Configuring Exim 4
6/9
Generate an Exim configuration file which delivers local mail to the IMAP server. See the
Exim documentation for information on how to create a complete configuration file.

Cyrus is designed to be used as a black-box server -- there are usually no local user accounts.
As a result, you must define the following "router":

localuser:
driver = accept
transport = local_delivery

The following "transports" assume that you are using either the lmtpunix or lmtp service
from one of the sample cyrus.conf files discussed above.

Using lmtpunix (UNIX socket):

local_delivery:
driver = lmtp
command = "/usr/cyrus/bin/deliver -l"
batch_max = 20
user = cyrus

Using lmtp (TCP socket -- Exim and Cyrus on same host):

local_delivery:
driver = smtp
protocol = lmtp
hosts = localhost
allow_localhost

For more advanced configurations (such as address verification, etc), consult the Exim
documentation and sample configurations.

Exporting Netnews via IMAP

If you wish to use export Netnews via IMAP, consult install-netnews.php.

SSL, TLS, and OpenSSL

Transport Layer Security (TLS), is a standardized version of the Secure Sockets Layer (SSL v3)
standard. IMAP can make use of two different versions of TLS/SSL: STARTTLS and an SSL
wrapped session.

In STARTTLS, a client connects to the IMAP port as normal and then issues the STARTTLS
command, which begins a TLS negotiation. This is currently supported by the Cyrus IMAP
server when it is compiled with OpenSSL.

The alternative, a SSL wrapped connection, involves the client connected to a seperate port
("imaps") and negotiating a SSL session before starting the IMAP protocol. Again, this is
supported natively by the Cyrus IMAP server when it is compiled with OpenSSL.

7/9
Both TLS and SSL require a server key and a certificate. Optionally, in addition to establishing
a secure connection, TLS can authenticate the client.

Configuring Cyrus with OpenSSL

1. OpenSSL requires the certificate and key in PEM format. You can create the server's
private key and certificate yourself using OpenSSL. Here, we create a self-signed key
for the machine "foobar.andrew.cmu.edu" and put both the certificate and key in
the file "/var/imap/server.pem".

Please do not blindly enter in the information to OpenSSL below. Instead, enter the
appropriate information for your organization (i.e., NOT Carnegie Mellon University for
the Organization Name, etc.).

openssl req -new -x509 -nodes -out /var/imap/server.pem -keyout /var/imap/server.pem -days 365
Using configuration from /usr/local/lib/openssl/openssl.cnf
Generating a 1024 bit RSA private key
.............+++++
......................+++++
writing new private key to '/var/imap/server.pem'
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]: US
State or Province Name (full name) [Some-State]: Pennsylvania
Locality Name (eg, city) []: Pittsburgh
Organization Name (eg, company) [Internet Widgits Pty Ltd]: Carnegie Mellon University
Organizational Unit Name (eg, section) []: Andrew Systems Group
Common Name (eg, YOUR name) []: foobar.andrew.cmu.edu
Email Address []:

2. Make sure to make key file(s) readable by the Cyrus user. For example: chown cyrus
/var/imap/server.pem
3. Add the following to /etc/imapd.conf to tell the server where to find the certificate
and key files (used for ALL services):

server_cert_file: /var/imap/server.cert
server_key_file: /var/imap/server.key

Optionally, you can use separate certificates and key files for each service:

[servicename]_server_cert_file: /var/imap/imap-server.cert
[servicename]_server_key_file: /var/imap/imap-server.key

"servicename" here refers to the name of the service as specified in cyrus.conf. It is

not necessarily the name of the binary.
This is useful if you want to use different hostnames for each service (e.g., via virtual
8/9
 host interfaces or DNS CNAMEs). In the absence of any of the service specific options,
the value of the global option is used. A value of disabled for the certificate or key file
for a particular service will disable SSL/TLS for that service.

If you have a Certificate Authority (CA), you may wish to generate a certificate request
and send it to be signed by your CA.

By default, Cyrus will cache SSL/TLS sessions for reuse for up to 24 hours. By adjusting
the value of the tls_session_timeout option in imapd.conf, the session caching
can be disabled (0) or the expiration period shortened.

4. You can test STARTTLS by using imtest:

imtest -t "" foobar.andrew.cmu.edu

Client-side certificates
Client certificates are somewhat harder to configure than server certificates. You'll need a CA
(certificate authority) and need to generate client certificates signed by that CA. STARTTLS in
Sendmail and other MTAs have similiar problems, so Claus Assman's page is a good
reference.

You can use the self-signed certificate generated above as a CA for client certificates. To do
this, try the following:

TODO: write me!

Unfortunately, there's no standard on how to convert the client's authenticate DN

(distinguished name) to a SASL authentication name.

Alternate Namespace and UNIX Hierarchy Convention

If you wish to use the alternate namespace and/or the UNIX hierarchy convention, consult
altnamespace.php.

last modified: $Date: 2010/01/06 17:01:29 $

9/9