Configuring the IMAP Server

This section describes the shell scripts to run and the configuration files to modify once "configure" and "make" have run.

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".
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").
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
```
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: passwd
```
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 pwcheck_method. In this example, users are authenticated via the getpwnam() call.)
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.
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
```
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. Do not use the string "news" as a partition name, as it is reserved for netnews.
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
```
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
   tools/mkimap
   exit
```
If Perl is not available, it should be easy (but time consuming) to create these directories by hand.
LINUX SYSTEMS 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. Note this is for ext2fs. If you are using a newer filesystem, either the performance hit may not be as bad or you may not need to do this.
```
   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
```
To enable STARTTLS support, see how to configure OpenSSL below.

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

   pop3      110/tcp
   imap      143/tcp
   imsp      406/tcp
   acap      674/tcp
   imaps     993/tcp
   pop3s     995/tcp
   kpop      1109/tcp
   sieve     2000/tcp
   lmtp      2003/tcp
   fud       4201/udp

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

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
The same configuration as above, but with some preforked processes for faster processing.
cmu.conf
Our configuration

To use normal.conf, do:
```
   cp master/conf/normal.conf /etc/cyrus.conf
```
Optionally, you can edit /etc/cyrus.conf to disable or enabling certain services, or to tune the number of preforked copies. Be sure not to remove the entries that are labeled required.
Arrange to start "/usr/cyrus/bin/master" as root when the system starts. It will bind some ports and then give up it's root privileges. Until your system reboots, you can start the master process by hand:
```
   /usr/cyrus/bin/master &
```
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.

Configuring the Mail Transfer Agent

In order to deliver mail to the Cyrus system, you'll have to configure your MTA (usually Sendmail) appropriately.

Generate a sendmail configuration file which delivers local mail to the IMAP server. See the files cf/README in the Sendmail distribution for information on how to do this. A suggested "config.mc" file to create a Sendmail configuration file can be found here. This requires Sendmail 8.10 or newer.
The interface between the MTA and Cyrus has changed in Cyrus version 2, so take care when using older Sendmails.
Edit /etc/group and add user "daemon" to the "mail" group. This will permit sendmail to run the "deliver" program to deliver mail to the IMAP server.

Exporting Netnews via IMAP

If you want to export netnews newsgroups using IMAP do the following:

Create a directory for the "news" partition. This directory should be different than the news spool directory. This document uses a news partition directory of "/var/spool/imap-news" in the following examples:
```
   cd /var/spool
   mkdir imap-news
   chown cyrus imap-news
   chgrp mail imap-news
   chmod 750 imap-news
```

Set the "partition-news" and "newsspool" options to appropriate values:

   partition-news: /var/spool/imap-news
   newsspool: /var/spool/news

The cyrus user must be able to write to the out.going ("/var/spool/news/out.going") directory. This can be done by putting the cyrus user into the news group and making the oug.going directory group writable.
Add the following line to the newsfeeds file
```
   collectnews!:*:Tf,WO:collectnews
```
Add a cron job to run "/usr/cyrus/bin/feedcyrus" every ten minutes as the cyrus user. Also add a cron job to run "/usr/cyrus/bin/syncnews /var/news/active >/dev/null 2>&1" nightly. (Using the appropriate path to the active file.)

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.

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

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 []:

Make sure to make key file(s) readable by the Cyrus user. For example: chown cyrus /var/imap/server.pem
Add the following to /etc/imapd.conf to tell the server where to find the certificate and key file:
```
tls_cert_file: /var/imap/server.pem
tls_key_file: /var/imap/server.pem
```
If you have a Certificate Authority (CA), you may wish to generate a certificate request and send it to be signed by your CA.
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.

last modified: $Date: 2001/07/05 15:47:39 $