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

        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 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. 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
           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
           tools/mkimap
           exit


        If Perl is not available, it should be easy (but time consuming) to
        create these directories by hand. 

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

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

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

     2. 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 &

     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. 

Configuring the Mail Transfer Agent

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

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

     2. 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: 

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

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

     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 file (used for ALL services): 

        tls_cert_file: /var/imap/server.pem
        tls_key_file: /var/imap/server.pem

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

        tls_imap_cert_file: /var/imap/imap-server.pem
        tls_imap_key_file: /var/imap/imap-server.pem

        tls_pop3_cert_file: /var/imap/pop3-server.pem
        tls_pop3_key_file: /var/imap/pop3-server.pem

        tls_lmtp_cert_file: /var/imap/lmtp-server.pem
        tls_lmtp_key_file: /var/imap/lmtp-server.pem

        tls_sieve_cert_file: /var/imap/sieve-server.pem
        tls_sieve_key_file: /var/imap/sieve-server.pem

        This is useful if you want to use different hostnames for each
        service (e.g. via virtual 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.html. 

