Installing and Configuring the Cyrus IMAP Server

The Internet Message Access Protocol (IMAP) is an Internet standards-track protocol for accessing messages (mail, news, etc). The IMAP server stores and provides access to messages.

A list of answers to common installation problems is maintained in http://andrew2.andrew.cmu.edu/cyrus/imapd/install-FAQ.

Feedback on the software or on the document may be sent to "cyrus-bugs@andrew.cmu.edu". The info-cyrus@andrew.cmu.edu mailing list exists for the discussion of this server and other Cyrus software; more information is availible in the mailing-list document.

Upgrading From Previous Versions

Upgrading from the Cyrus IMAP server version 1.4 or earlier requires running "reconstruct -r" after installing this version of the software.
Upgrading from the Cyrus IMAP server version 1.3 or earlier requires running "reconstruct -m" after installing this version of the software.
Upgrading from 1.5.2 or earlier requires deleting the delivered database (if duplicate delivery supression is used, the default) and the PTS cache database (if the AFS PTS group support is used, which is not the default). The delivered.db is in the configdirectory; the PTS cache is in /var/ptclient. These files must be removed. (There is no danger in deleting the PTS cache, and if the delivered database is removed, there is a chance that some duplicate messages may come through, but this is not a serious concern.)
The format for the PTS cache for IMSP has changed. If you use AFS ACLs, IMSPd, and IMAPd on the same machine, make sure you have version 1.5a5 of the IMSP server for this version of the IMAP server. (If you don't have IMSP, or AFS, don't worry about it.)

See the file doc/changes in the distribution for more information.

Prerequisites and other notes

The following programs and/or packages are required:

makedepend. A version is included in the makedepend subdirectory of the distribution. Try and install it before installing the Cyrus IMAPd. If it fails, the configure script will use a dummy shell script instead of makedepend, and you should be sure to always give the command "make clean" before "make all".
Tcl, version 7.5 or 7.6, or 8.0. To obtain Tcl, see the comp.lang.tcl FAQ. Other versions of Tcl might work, but it must be at least Tcl 7.5. (Tcl 7.4 ships with some Unix variants, and it is not sufficient.)
If compiling with Kerberos support, the installed Kerberos must include the DES library. Some vendor distributions of Kerberos, including the one with Solaris, do not have this support and cannot be used. Sites in the USA and Canada may obtain Kerberos by following the instructions in ftp://athena-dist.mit.edu/pub/kerberos/README.KRB4. Sites worldwide may wish to use the KTH Kerberos distribution; information is avalible from http://www.pdc.kth.se/kth-krb/. We are not able to assist other sites in obtaining Kerberos.
It is recommended that sites install Sendmail version 8.7.1 or later. Sendmail distributions may be obtained from ftp://ftp.sendmail.org/ucb/sendmail
If you want to export netnews newsgroups using IMAP, the IMAP server must receive newsgroups with the INN news server.

Compiling the IMAP Server

Once you have unpacked the files (see the README file for more information), "cd" to the "cyrus-imapd-1.5.14" directory (assuming the version number is 1.5.14). The configuration files and various subdirectories are stored there. In the directory that the configure file is in, type "./configure" to configure the software.

The "configure" shell script attempts to guess correct values for various system-dependent variables used during compilation. It uses those values to create a "Makefile" in each directory of the package. Finally, it creates a shell script "config.status" that you can run in the future to recreate the current configuration, a file "config.cache" that saves the results of its tests to speed up reconfiguring, and a file "config.log" containing compiler output (useful mainly for debugging "configure").

Running "configure" takes awhile. While running, it prints some messages telling which features it is checking for.

You can compile the package in a different directory from the one containing the source code. Doing so allows you to compile it on more than one kind of computer at the same time. To do this, you must use a version of "make" that supports the "VPATH" variable, such as GNU "make". "cd" to the directory where you want the object files and executables to go and run the "configure" script. "configure" automatically checks for the source code in the directory that "configure" is in and in "..".

By default, "make install" will install files (other than server-specific programs) in "/usr/local/bin", "/usr/local/man", etc. You can specify an installation prefix other than "/usr/local" by giving "configure" the option "--prefix=PATH".

You can specify separate installation prefixes for architecture-specific files and architecture-independent files. If you give "configure" the option "--exec-prefix=PATH", the package will use PATH as the prefix for installing programs and libraries. Documentation and other data files will still use the regular prefix.

By default, "make install" will install the server-specific programs in "/usr/cyrus/bin". You can specify a server-specific installation prefix other than "/usr/cyrus" by giving "configure" the option "--with-cyrus-prefix=PATH".

Here are a list of switches that can be used with "configure".

--cache-file=FILE

Save the results of the tests in FILE instead of "config.cache". Set FILE to "/dev/null" to disable caching, for debugging "configure".

--help

Print a summary of the options to "configure", and exit.

--quiet

--silent

-q

Do not print messages saying which checks are being made.

--srcdir=DIR

Look for the package's source code in directory DIR. Usually "configure" can determine that directory automatically.

--version

Print the version of Autoconf used to generate the "configure" script, and exit.

--with-cyrus-user=USER

Specifies the userid used for installing setuid programs. By default, configure uses "cyrus".

--with-cyrus-group=USER

Specifies the group used for installing setuid programs. By default, configure uses "mail".

--with-statedir=PATH

Specifies the directory used for the pwcheck and/or ptclient state directories. By default, configure uses "/var".

--with-login=METHOD

Specifies the login authentication module to use. Currently implemented authentication modules are:

unix: Unix /etc/passwd file
unix_pwcheck: Unix shadow passwd file, accessed through pwcheck daemon
krb: Kerberos version 4
krb_pwcheck: Either Kerberos version 4 or the pwcheck daemon

By default, configure uses "krb" if the file /etc/krb.conf exists, "unix" otherwise.

If you use shadow passwords, you should use --with-login=unix_pwcheck, not just unix. The Cyrus imapd does not run as root, and the pwcheck daemon is required for authentication if you use shadow passwords.

--with-pwcheck=METHOD

Specifies the password checking module to use inside the pwcheck daemon. This option is only used if the login module has a name ending in "_pwcheck". Currently implemented authentication modules are:

getspnam: SVR4 style getspnam() shadow passwords
getpwnam: NetBSD style shadow passwords

By default, configure uses "getspnam" if the function getspnam exists, "getpwnam" otherwise.

--with-auth=METHOD

Specifies the authorization module to use. Currently implemented authorization modules are:

unix: Unix /etc/passwd and /etc/group file
krb: Kerberos principals
krb_pts: Kerberos principals with AFS PTserver groups

The selected authorization module must be compatible with the login module. By default, uses the authorization module with the same name as the selected login module.

--with-notify=METHOD

--without-notify

Specifies the new mail notification method to use. Currently implemented notification methods are:

zephyr: New mail notification through Zephyr
no: No new mail notification

By default, uses "zephyr" if the Zephyr libraries are available, otherwise "no".

--with-inn=PATH

Specifies the location of INN's NEWSLIB directory. By default, looks for INN in a few common places. It is only necessary for "configure" to find INN if you are going to export newsgroups using IMAP.

--with-krb=PATH

--without-krb

Specifies the path to the Kerberos v4 libraries and header files (optional). By default, looks in "/usr/local" and then in the compiler's default link path.

IMPORTANT: The Kerberos v4 support requires the DES library, even if the "--disable-privacy" configure option is given. Some vendor distributions of Kerberos, including the one with Solaris, do not have this support and cannot be used.

Either "--without-krb" or "--with-krb=no" prevents Kerberos v4 support from being compiled in.

--with-tcl=PATH

--without-tcl

Specifies the path to the Tcl (version 7.5 or 7.6) library and header file (optional). By default, looks in "/usr/local" and then in the compiler's default link path. The Tcl library is necessary to compile "cyradm", the administrative client. If compiling without Tcl, it is necessary to give configure the "--disable-cyradm" switch.

--with-zephyr=PATH

--without-zephyr

Specifies the path to the Zephyr library and header file (optional). By default, looks in "/usr/local" and then in the compiler's default link path. The Zephyr library is optional, if found it may be used to notify users of new mail.

--with-lock=METHOD

Specifies the locking method to use. Currently implemented locking methods are:

flock: flock() locking
fcntl: fcntl() locking

By default, uses "flock" if the "flock()" function exists, "fcntl" otherwise.

--disable-cyradm

Do not compile the cyradm administrative client.

--disable-privacy

Disables all network privacy support. Use this if you do not have the appropriate routines in the authentication libraries (for example, krb_rd_priv() and krb_mk_priv() for Kerberos v4) or are compiling binaries subject to export control restrictions.

--enable-amssync

Include AMS (Andrew Message System) to IMAP bboard synchronization support. Requires the AMS libraries.

--enable-cmulocal

Include Carnegie Mellon's internal support features. (Ignore this if you're not at CMU.)

"configure" ignores any other arguments that you give it.

Some systems require unusual options for compilation or linking that the "configure" script does not know about. You can give "configure" initial values for variables by setting them in the environment. Using a Bourne-compatible shell, you can do that on the command line like this:

   CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure

Or on systems that have the "env" program, you can do it like this:

   env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure

The "make" variables that you might want to override with environment variables when running "configure" are:

CC: C compiler program.
Default is "cc", or "gcc" if "gcc" is in your PATH.
(For "CC", any value given in the environment overrides the value that "configure" would choose.)
CFLAGS: Debugging and optimization options for the C compiler.
CPPFLAGS: Header file search directory ("-IDIR") and any other miscellaneous options for the C preprocessor and compiler. If it is not set in the environment when "configure" runs, the default value is empty.
LDFLAGS: Stripping ("-s") and any other miscellaneous options for the linker. If it is not set in the environment when "configure" runs, the default value is empty.
DEFS: Configuration options, in the form "-Dfoo -Dbar ..."
LIBS: Libraries to link with, in the form "-lfoo -lbar ..."
(For "DEFS" and "LIBS", any value given in the environment is added to the value that "configure" chooses.)

If you need to do unusual things to compile the package, we encourage you to figure out how "configure" could check whether to do them, and mail diffs or instructions to "cyrus-bugs@andrew.cmu.edu" so we can include them in the next release.

The file "configure.in" is used as a template to create "configure" by a program called "autoconf". You will only need it if you want to regenerate "configure" using a newer version of "autoconf".

Once you have successfully run "configure", execute the following commands:

   make depend
   make all CFLAGS=-O

If you want, you can override the "make" variables CFLAGS and LDFLAGS by entering the following:

   make all CFLAGS=-O2 LDFLAGS=-s

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
```
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 cyrus-imapd-1.5.14/syslog directory.
```
   mv syslogd /etc/syslogd
   mv syslog.conf /etc/syslog.conf
```
If you do not copy the "syslog.conf" file in "cyrus-imapd-1.5.14/syslog" to the "/etc" directory, be sure to add support for "local6.debug". The file should include a line like:
```
   local6.debug  /var/adm/imapd.log
```
Create the imapd.log file:
```
   touch /var/adm/imapd.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
   srvtab: /var/imap/srvtab
```
For a description of all the fields in this file, see the imapd.conf(5) man page.
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.
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
```

In the configuration directory, create the empty file "mailboxes" and a set of empty directories:

   cd imap
   true >> mailboxes
   mkdir user quota proc log msg
   chown cyrus *
   chgrp mail *

Create the default partition directory 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.
LINUX SYSTEMS ONLY: Set the configuration, 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.
```
   cd /var/imap
   chattr +S . user quota
   chattr +S /var/spool/imap
```
Also set the queue directory of the mail daemon to update synchronously. The following example is for sendmail:
```
   /sbin/chattr +S /var/spool/mqueue
```
If the Cyrus IMAP server was configured to use the pwcheck daemon, install pwcheck. The pwcheck daemon verifies passwords against the shadow password database. Create the directory "/var/pwcheck" and make it readable by only the cyrus user:
```
   mkdir /var/pwcheck
   chown cyrus /var/pwcheck
   chmod 700 /var/pwcheck
```
Upon system startup, arrange for the daemon /usr/cyrus/bin/pwcheck to be run as root in the background.
If the Cyrus IMAP server was compiled with Kerberos v4 authentication, create a Kerberos v4 identity for the server and add the server's key to the "srvtab" file. The file must be readable by the cyrus user. The server's Kerberos identity is "imap.HOST@REALM", where "HOST" is the first component of the machine's host name and "REALM" is the machine's Kerberos realm.
Here is a sample session, creating a srvtab file for the host named "foobar":
```
   ksrvutil -f /var/imap/srvtab add
```
Here is the information "ksrvutil" requests. Respond by filling in values or by pressing RETURN. In this example, the host name is "foobar" and the realm is "ANDREW.CMU.EDU".
```
   Name: imap
   Instance: foobar
   Realm: ANDREW.CMU.EDU
   Version number: 
   New principal: imap.foobar@ANDREW.CMU.EDU; version 0
   Is this correct? (y,n) [y] 
   Password: 
   Verifying, please re-enter Password: 
   Key successfully added.
   Would you like to add another key? (y,n) [y] n
```
If you plan to install Kerberized POP, create the Kerberos identity "pop.HOST@REALM" and add the key to the "srvtab" file.
Make the "srvtab" file owned by the cyrus user:
```
   chown cyrus /var/imap/srvtab
```

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

   pop3      110/tcp
   imap      143/tcp
   imsp      406/tcp
   kpop      1109/tcp

Add the following line to the "/etc/inetd.conf" file.
```
   imap  stream  tcp  nowait  cyrus  /usr/cyrus/bin/imapd  imapd
```
If you want to run the POP3 protocol, add the following line.
```
   pop3  stream  tcp  nowait  cyrus  /usr/cyrus/bin/pop3d  pop3d
```
If you want to run MIT's KPOP (Kerberized POP) protocol, add the following line
```
   kpop  stream  tcp  nowait  cyrus  /usr/cyrus/bin/pop3d  pop3d -k
```
"cyrus" is the Cyrus user and "/usr/cyrus/bin/" is the path name to the executable.
If you wish to use the interm finger information service, you need to enable support for it in "/etc/services" and "/etc/inetd.conf".
Note that this requires a finger client that supports this service. If you don't know that yours supports it, it doesn't. At this time, we are not providing a finger client that supports this.
1. Add the following line to the "/etc/services" file if it isn't already there.
```
   fud       4201/udp
```
2. Add the following line to the "/etc/inetd.conf" file.
```
   fud  dgram  udp  wait  cyrus  /usr/cyrus/bin/fud   fud
```
Restart inetd. Many systems provide an easy way to do this, but the generic method is to find the process id of inetd (use /bin/ps -elf on most systems), then kill -HUP pid.
Sendmail versions 8.7 and later include support for the Cyrus IMAP server. If you are running a verson of Sendmail older than 8.7.1, replace it with 8.7.1 or later. Sendmail distributions may be obtained from ftp://ftp.cs.berkely.edu/ucb/sendmail
Generate a sendmail configuration file which delivers local mail to the IMAP server. See the files cf/README and cf/cf/cyrusproto.mc in the Sendmail distribution for information on how to do this.
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.
The Cyrus IMAP server support in Sendmail defaults to enabling duplicate delivery suppression, by invoking the "deliver" program with the ies the group used for installing setuid programs. By default, configure uses "mail".

--with-statedir=PATH
Specifies the directory used for the pwcheck and/or ptclient state directories. By default, configure uses "/var".

--with-login=METHOD
Specifies the login authentication module to use. Currently implemented authentication modules are:

unix
Unix /etc/passwd file
unix_pwcheck
Unix shadow passwd file, accessed through pwcheck daemon
krb
Kerberos version 4
krb_pwcheck
Either Kerberos version 4 or the pwcheck daemon
By default, configure uses "krb" if the file /etc/krb.conf exists, "unix" otherwise.
If you use shadow passwords, you should use --with-login=unix_pwcheck, not just unix. The Cyrus imapd does not run as root, and the pwcheck daemon is required for authentication if you use shadow passwords.

--with-pwcheck=METHOD
Specifies the password checking module to use inside the pwcheck daemon. This option is only used if the login module has a name ending in "_pwcheck". Currently implemented authentication modules are:

getspnam
SVR4 style getspnam() shadow passwords
getpwnam
NetBSD style shadow passwords
By default, configure uses "getspnam" if the function getspnam exists, "getpwnam" otherwise.

--with-auth=METHOD
Specifies the authorization module to use. Currently implemented authorization modules are:

unix
Unix /etc/passwd and /etc/group file
krb
Kerberos principals
krb_pts
Kerberos principals with AFS PTserver groups
The selected authorization module must be compatible with the login module. By default, uses the authorization module with the same name as the selected login module.

--with-notify=METHOD
--without-notify
Specifies the new mail notification method to use. Currently implemented notification methods are:

zephyr
New mail notification through Zephyr
no
No new mail notification
By default, uses "zephyr" if the Zephyr libraries are available, otherwise "no".

--with-inn=PATH
Specifies the location of INN's NEWSLIB directory. By default, looks for INN in a few common places. It is only necessary for "configure" to find INN if you are going to export newsgroups using IMAP.

--with-krb=PATH
--without-krb
Specifies the path to the Kerberos v4 libraries and header files (optional). By default, looks in "/usr/local" and then in the compiler's default link path.
IMPORTANT: The Kerberos v4 support requires the DES library, even if the "--disable-privacy" configure option is given. Some vendor distributions of Kerberos, including the one with Solaris, do not have this support and cannot be used.
Either "--without-krb" or "--with-krb=no" prevents Kerberos v4 support from being compiled in.

--with-tcl=PATH
--without-tcl
Specifies the path to the Tcl (version 7.5 or 7.6) library and header file (optional). By default, looks in "/usr/local" and then in the compiler's default link path. The Tcl library is necessary to compile "cyradm", the administrative client. If compiling without Tcl, it is necessary to give configure the "--disable-cyradm" switch.

--with-zephyr=PATH
--without-zephyr
Specifies the path to the Zephyr library and header file (optional). By default, looks in "/usr/local" and then in the compiler's default link path. The Zephyr library is optional, if found it may be used to notify users of new mail.

--with-lock=METHOD
Specifies the locking method to use. Currently implemented locking methods are:

flock
flock() locking
fcntl
fcntl() locking
By default, uses "flock" if the "flock()" function exists, "fcntl" otherwise.

--disable-cyradm
Do not compile the cyradm administrative client.

--disable-privacy
Disables all network privacy support. Use this if you do not have the appropriate routines in the authentication libraries (for example, krb_rd_priv() and krb_mk_priv() for Kerberos v4) or are compiling binaries subject to export control restrictions.

--enable-amssync
Include AMS (Andrew Message System) to IMAP bboard synchronization support. Requires the AMS libraries.

--enable-cmulocal
Include Carnegie Mellon's internal support features. (Ignore this if you're not at CMU.) "configure" ignores any other arguments that you give it.
Some systems require unusual options for compilation or linking that the "configure" script does not know about. You can give "configure" initial values for variables by setting them in the environment. Using a Bourne-compatible shell, you can do that on the command line like this:
```
   CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure
```
Or on systems that have the "env" program, you can do it like this:
```
   env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure
```
The "make" variables that you might want to override with environment variables when running "configure" are:

CC
C compiler program.
Default is "cc", or "gcc" if "gcc" is in your PATH.
(For "CC", any value given in the environment overrides the value that "configure" would choose.)
CFLAGS
Debugging and optimization options for the C compiler.

CPPFLAGS
Header file search directory ("-IDIR") and any other miscellaneous options for the C preprocessor and compiler. If it is not set in the environment when "configure" runs, the default value is empty.

LDFLAGS
Stripping ("-s") and any other miscellaneous options for the linker. If it is not set in the environment when "configure" runs, the default value is empty.
DEFS
Configuration options, in the form "-Dfoo -Dbar ..."

LIBS
Libraries to link with, in the form "-lfoo -lbar ..."
(For "DEFS" and "LIBS", any value given in the environment is added to the value that "configure" chooses.)
If you need to do unusual things to compil