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://asg.web.cmu.edu/cyrus/imapd/install-FAQ.html. It is very out of date and will eventually be updated.

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 available in the mailing-list document. Be sure to include the version numbers of imapd and libsasl you are using, as well as your system type (and version!) and any configuration options you selected.

For detailed changes, refer to the file doc/changes in the distribution.

Upgrading From Previous Versions

Upgrading from 1.6

Upgrading from 1.5

Upgrading from before 1.3

Prerequisites and other notes

The following programs and/or packages are required:

Compiling the IMAP Server

Once you have unpacked the files by extracting the tar archive, "cd" to the "cyrus-imapd-NNNN" directory where NNNN is the version number. 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 ptclient state directories. By default, configure uses "/var".

--with-sasldir=PATH
Specifies the path to the directories containing the library (.../lib) and include (.../include) files for libsasl.

--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
Since the login module is now SASL, this is much more confusing. We are considering adding group support to libsasl, thus solving this ambiguity. Make sure you select an authorization module compatible with your system.

--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. 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-sieve
By default, Sieve support is enabled. Note that you need duplicate delivery suppression enabled if you're going to use Sieve. Use --disable-sieve to disable compiling Sieve support

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

--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.
  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
    
  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 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
    
    You probably also want to log SASL messages with a line like:
       auth.debug /var/adm/auth.log
    
    Create the log files:
       touch /var/adm/imapd.log /var/adm/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
       srvtab: /var/imap/srvtab
    
    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 srvtab setting here is in place of the srvtab setting in the SASL configuration file.)

    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.

  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. Do not use the string "news" as a partition name, as it is reserved for netnews.
  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
       chown 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
       tools/mkimap
    
    
    If perl is not available, it should be easy to create these directories by hand.

  9. 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 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
    
  10. 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
    
  11. 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
       sieve     2000/tcp
    
  12. 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
    
    If you wish to use to timsieved service, add the following line
       sieve  stream  tcp  nowait  cyrus  /usr/cyrus/bin/timsieved timsieved
    
    "cyrus" is the Cyrus user and "/usr/cyrus/bin/" is the path name to the executable.

    If you'd like to be able to do a ps and see what the imapd or pop3d is doing, you may need to add this to the end of imapd or pop3d inetd.conf entry.

     junk to allow room for setproctitle xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    

  13. 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
      

  14. 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.

  15. 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. Be sure the sendmail configuration file gets reloaded after you make the changes.

  16. 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.

  17. The Cyrus IMAP server support in Sendmail defaults to enabling duplicate delivery suppression, by invoking the "deliver" program with the "-e" switch. This prevents two messages with the same Message-ID: (Resent-Message-ID: if it exits) from being delivered to the same mailbox. Add a cron job to periodically prune the database of deliveries by running "/usr/cyrus/bin/deliver -E 3" daily as the cyrus user.

    Duplicate delivery suppression is required if you are using Sieve.

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

    1. 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
      

    2. Set the "partition-news" and "newsspool" options to appropriate values:
         partition-news: /var/spool/imap-news
         newsspool: /var/spool/news
      

    3. 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.

    4. Add the following line to the newsfeeds file
         collectnews!:*:Tf,WO:collectnews
      

    5. 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.)

Testing the IMAP Server

To test the IMAP server, reboot and perform the following steps (all of these samples use "foobar" as the IMAP server name). A list of answers to common installation problems is maintained in http://asg.web.cmu.edu/cyrus/imapd/install-FAQ.

  1. If the server is compiled with Kerberos v4 authentication, run the program "krbck" as the cyrus user on the IMAP server. This program will diagnose some common Kerberos configuration errors.

  2. From your normal account, telnet to the IMAP port on the server you're setting up:
       telnet foobar imap
    
    If your server is running, you'll get the following message:
       Trying 128.2.232.95...
       Connected to foobar.andrew.cmu.edu.
       Escape character is '^]'.
       * OK foobar.andrew.cmu.edu Cyrus IMAP4 v1.6.0 server ready
    

    Any message other than one starting with "* OK" means there is a problem. To terminate the connection, type ". logout".

    Naturally the version number should match the version you just installed.

  3. Use "imtest" to test logging in with plaintext passwords.
       /usr/local/bin/imtest -m login -p imap foobar
    
    If your server is running, you'll get the following message:
       * OK foobar.andrew.cmu.edu Cyrus IMAP4 v1.6.0 server ready
       Password: <enter your password, imtest does not echo it>
       . LOGIN smith X
       . OK User logged in
    
    Any message other than one starting with a ". OK" means there is a problem. If the test fails, a more specific error message is written through syslog to the server log. To terminate the connection, type ". logout".

  4. You should now test the server with each of the various authentication mechanisms you have installed. First to find the mechanisms the server thinks are installed use imtest as above. After imtest logs in type:
     
       . CAPABILITY
    
    This should produce a message similar to:
      * CAPABILITY IMAP4 IMAP4rev1 ACL QUOTA LITERAL+ NAMESPACE UIDPLUS 
      X-NON-HIERARCHICAL-RENAME NO_ATOMIC_RENAME AUTH=PLAIN AUTH=ANONYMOUS
      AUTH=KERBEROS_V4 AUTH=DIGEST-MD5 AUTH=CRAM-MD5 UNSELECT
      . OK Completed
    
    Each of the mechanism names is preceded by a 'AUTH='. For this example PLAIN, ANONYMOUS, KERBEROS_V4, DIGEST-MD5, and CRAM-MD5 are available. If a mechanism does not appear that you believe should appear it may be because the mechanism is unable to initialize. For example, if the server is unable to access the srvtab file the KERBEROS_V4 mechanism will be unable to initialize. To terminate the imtest connection, type ". logout". Once you are satisfied with the authentication mechanism list you should attempt to log in with each of those mechanisms. Change to the "cyrus-v1.5.14" directory and run imtest specify\ing which mechanism you would like to use. The mechanism name must be in all capital letters. For example for KERBEROS_V4 type:
       /usr/local/bin/imtest -m KERBEROS_V4 -p imap foobar
       * OK foobar.andrew.cmu.edu Cyrus IMAP4 v1.5.14 server ready
       . AUTHENTICATE KERBEROS_V4
       + Ln8h6Q==
       BAcBQU5EUkVXLkNNVS5FRFUAOCA+0y5YnrqIVikng46sam7RSObZXCVSA9xCx
       BZSGgOy9ehHRj8NQjLjxDpib0D9uT0fo7QaXhLM6zCp9dQ1pX4FfNO2V39vBp
       Q19QIK4S1410prvM2c45qeizecI7zAvA=
       2cRhIC+aH70WHqYaW18YnQ==
       . OK User logged in (no protection)
       __No integrity protection__
    
    Any message other than one starting with a "A01 OK" means there is a problem. If the test fails, a more specific error message is written through syslog to the server log. To terminate the connection, type ". logout". Make sure to test each mechanism this way. Also, many mechanisms have security layers. You should test each layer for mechanisms that support layers. imtest by default will choose the strongest layer. Use the '-l' parameter to force imtest to use a weaker layer. The '-l' parameter takes the security strength factor. A security strength factor of 0 means no layer and 1 means integrity layer. Privacy layer security strength factors depend upon the mechanism. For example KERBEROS_V4 has 3 layers: none, integrity, and privacy with security strength factors of 0,1, and 56 respectivly. By default imtest will attempt to use privacy layer. To force imtest to negotiate an integrity layer type:
      imtest -m KERBEROS_V4 -l 1 -p imap foobar
    
    See the libsasl documentation for a full description of what mechanisms support what layers.

Testing the sieve server

  1. The Sieve server, "timsieved", is used for transporting user Sieve scripts to the sealed IMAP server. It is incompatible with the "sieveusehomedir" option. It is named after the principal author, Tim Martin, who desperately wanted something named after him in the Cyrus distribution.

  2. From your normal account, telnet to the sieve port on the server you're setting up:
       telnet foobar sieve
    
    If your server is running, you'll get a message similar to the following one:
       Trying 128.2.10.192...
       Connected to cyrus-dev.andrew.cmu.edu.
       Escape character is '^]'.
       "CMU Experimental Sieved version 0.99" "SASL={GSSAPI, ANONYMOUS, PLAIN, KERBEROS_V4}"
    

    Any message other than one similar to the one above means there is a problem. Make sure all of authentication methods you wish to support are listed. This list should be identical to the one listed by "imapd" earlier. Next terminate the connection, by typing "logout".

  3. Next test authenticating to the sieve server. To do this run the "installsieve" utility. You must specify the server. You may have to specify the port if you run this utility from a different machine without the "sieve" entry in "/etc/services". To specify the port use the "-p [port]" switch.
      "installsieve foobar"
    
    This should produce the message "Authentication failed" with a description of the failure if there was a problem.

    You might wish to test all authentication types. To force installsieve to use a specific mechanism use the "-m [mechanism]" switch.

  4. Next you should attempt to place a sieve script on the server. To do this create a file named "myscript.script" with the following lines. Replace "foo@bar.org" with an email address you can send mail from, but that is not the one you are working on now.
      require ["reject","fileinto"];
    
      if address :is :all "From" "foo@bar.org"
      {
        reject "testing";
      }
    
    To place this script on the server run the following command "installsieve -i myscript.script foobar" This should place your script on the server and make it the active script.

  5. Test that the sieve script is actually run from deliver. Send a message to the address you're working on from the address mentioned in the sieve script. The message should be rejected.

Administering Mailboxes

The "cyradm" command (see the cyradm(8) man page for complete documentation) manages the creation of, deletion of, ACLs on, and quotas on mailboxes. To get an overview of the command, type "cyradm <host>". Once "cyradm" has started, the user prompt is replaced with the name of the host followed by a ">". Type "help" at the new prompt. The following information is displayed:
   createmailbox, cm        create a mailbox
   deleteaclmailbox, dam    delete an ACL on a mailbox
   deletemailbox, dm        delete a mailbox
   help                     get help on commands
   listaclmailbox, lam      list the ACL on a mailbox
   listmailbox, lm          list mailboxes
   listquota, lq            list quota on root
   listquotaroot, lqr, lqm  list quota roots on mailbox
   quit                     exit program
   renamemailbox, renm      rename a mailbox
   setaclmailbox, sam       set an ACL on a mailbox
   setquota, sq             set quota limits
Note:If you run "cyradm" on a system where Kerberos v4 is not running, you are prompted for your user name an password before you can issue any "cyradm" commands.

The mailbox naming convention requires that the primary mailbox (inbox) for anyone must be named "user.<userid>". To create a mailbox, type:

   createmailbox user.<userid>
For example, to create a mailbox for the userid "smith", type:
   createmailbox 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. You must then configure a mail interface, such as Pine, to work with the IMAP server.

Performance Notes

If your configuration directory is not /var/imap, adjust accordingly.


Last modified: Tue Oct 5 12:15:14 EDT 1999