Quickstart Guide
****************

* Introduction to Cyrus IMAP

  * What is IMAP?


Quick install
=============

A quick guide to getting a basic installation of Cyrus up and running
in 5 minutes.

The first place to start with a new installation of Cyrus IMAP is with
your OS distribution of choice and their packaging, where available.

If there is no Cyrus IMAP 3.4.4 package available yet from your
distro, download the official source tarball from GitHub.  The
Compiling guide will help you get it built and installed.


1. Install Cyrus package(s)
---------------------------

Install the Cyrus IMAP package(s), either from your distribution’s
package manager, or from a release tarball.

Your distribution might have split Cyrus IMAP into several packages.
Check their documentation if you’re not sure what you need.


2. Setup the cyrus:mail user and group
--------------------------------------

Now let’s create a **special user account just for the Cyrus server**
to sandbox Cyrus: called "cyrus". We’ll also create a "mail" group as
well. This allows Cyrus to give other programs some permissions if
they are run under the "mail" group, again, without causing a Cyrus
bug to delete all of your cat pictures. Disaster!

If you have installed from packages, your package vendor may have
already done this for you.  To check, use these commands:

   $ getent group mail
   mail:x:8:

   $ getent passwd cyrus
   cyrus:x:999:8:Cyrus IMAP Server:/var/lib/imap:/bin/bash

Example group and user creation commands for GNU/Linux:

   groupadd -fr mail
   useradd -c "Cyrus IMAP Server" -d /var/lib/imap -g mail -s /bin/bash -r cyrus

The "var/lib/imap" directory above is an example. Use the same
directory specified in the "configdirectory" option in imapd.conf(5).


configdirectory
^^^^^^^^^^^^^^^

*This shows the default value: change it in imapd.conf to suit your
needs.*

   "configdirectory:" <none>

      The pathname of the IMAP configuration directory.  This field is
      required.

If your installation uses system locations for things like SSL
certificates (i.e. "/etc/ssl/certs /etc/ssl/private"), then you should
also add the "cyrus" user to the appropriate group to gain access to
the PKI files.  On Debian/Ubuntu systems, for example, this group is
"ssl-cert":

   usermod -aG ssl-cert cyrus


3. Setting up authentication with SASL
--------------------------------------

Now, let’s set up **SASL**. This will allow you to connect to your
local IMAP server and login, just like any IMAP user would before
checking for new emails.

Create a "saslauth" group and add the "cyrus" user to the group, so
Cyrus can access SASL. (on Debian, this group is called ‘sasl’: adjust
the following commands to suit.)

   groupadd -fr saslauth
   usermod -aG saslauth cyrus

Change the default SASL configuration in "/etc/default/saslauthd".
   1. Make sure that the "START" option is set to *yes*
      "(START=yes)" and

   2. Set the``MECHANISMS`` option to **sasldb**
      "(MECHANISMS="sasldb")".

Start the SASL auth daemon:

   /etc/init.d/saslauthd start

Now, we’ll create the IMAP user inside SASL. This is the user you’ll
use to login to the IMAP server later on.

   echo 'secret' | saslpasswd2 -p -c imapuser

You can replace "secret" with a more suitable password you want and
"imapuser" with the username you want. Once this is done, check that
the user exists and is set up correctly:

   testsaslauthd -u imapuser -p secret

You should get an "0: OK "Success."" message.


4. Setup mail delivery from your MTA
------------------------------------

Your Cyrus IMAP server will want to receive the emails accepted by
your SMTP server (ie Sendmail, Postfix, etc). In Cyrus, this happens
via a protocol called LMTP, which is usually supported by your SMTP
server.


Install Sendmail
~~~~~~~~~~~~~~~~

We’ll set up LMTP with the Sendmail SMTP server.

   sudo apt-get install -y sendmail

We need to make Sendmail aware of the fact we are using the Cyrus IMAP
server: modify the "/etc/mail/sendmail.mc" file. Add this line before
the "MAILER_DEFINITIONS" section:

   define(`confLOCAL_MAILER', `cyrusv2')dnl

And right below "MAILER_DEFINITIONS", add this:

   MAILER(`cyrusv2')dnl

This enables the **cyrusv2** mailer for local mail delivery. This is a
sendmail property that tells sendmail it’s talking to Cyrus. (Cyrus
3.x works with this property, despite the naming confusion.)

Next, we run a script that takes the "/etc/mail/sendmail.mc" file and
and prepares it for use by Sendmail. This may take some time.

   sudo sendmailconfig


Sendmail communication
~~~~~~~~~~~~~~~~~~~~~~

One last thing we need to do for LMTP to work with Sendmail is to
create a folder that will contain the UNIX socket used by Sendmail and
Cyrus to deliver/receive emails:

   sudo mkdir -p /var/run/cyrus/socket
   sudo chown cyrus:mail /var/run/cyrus/socket
   sudo chmod 750 /var/run/cyrus/socket


Install Postfix
~~~~~~~~~~~~~~~

We’ll set up LMTP with the Postfix SMTP server (consider which other
Postfix related packages you may also desire):

   sudo apt-get install -y postfix postfix-doc postfix-pcre postfix-ldap ...

We need to make Postfix aware of the fact we are using the Cyrus IMAP
server and engineer delivery via LMTP.  The following examples show
the "postconf" commands to run to add the necessary configuration to
"/etc/postfix/main.cf", these are not complete configurations.

Note: Postfix supports a great many configurations for mail delivery
  transport, so these settings will depend on whether you’re planning
  to use the "local", "virtual" or "lmtp" destination definitions. For
  our examples we’ll be using "virtual".  Adjust as needed for your
  purposes, and please consult the Postfix documentation at
  http://www.postfix.org/postconf.5.html

1. Setup your recipient maps, thus defining for which recipients
   the "virtual" destination will be used:

      postconf -e "virtual_mailbox_domains=hash:/etc/postfix/virtual_recipient_domains"
      postconf -e "virtual_mailbox_maps=hash:/etc/postfix/virtual_recipients"

   or, if you have enabled smmapd you can automatically track
   mailboxes with:

      postconf -e "virtual_mailbox_domains=hash:/etc/postfix/virtual_recipient_domains"
      postconf -e "virtual_mailbox_maps=socketmap:unix:/run/cyrus/socket/smmap"

2. Optional: Set the concurrency and recipient limits for LMTP
   delivery to the "virtual" destination:

      postconf -e "virtual_destination_concurrency_limit=300"
      postconf -e "virtual_destination_recipient_limit=300"

   The purpose of those two settings is to allow for a large number of
   simultaneous delivery threads between the MTA (Postfix) and the MDA
   (Cyrus), and to allow for a large number of recipients to be listed
   for any given message, thus avoiding splitting up delivery of
   messages with lots of recipients into many separate deliveries.

3. Send mail for those recipients to Cyrus via LMTP.  This first
   example is for delivery via TCP to a different host:

      postconf -e "virtual_transport=lmtp:inet:lmtp.example.org:2003"

   If your Postfix and Cyrus are on the same host, then use some
   version of this, where the socket patch matches what’s set in the
   "lmtpsocket" option in imapd.conf(5):

      postconf -e "virtual_transport=lmtp:unix:/run/cyrus/socket/lmtp"


5. Protocol ports
-----------------

The Cyrus IMAP server provides service interfaces via either TCP/IP
ports or Unix domain sockets.  For the former, Cyrus requires that
there are proper entries in the host’s "/etc/services" file.  The
following are required for any host using the listed services:

   pop3      110/tcp  # Post Office Protocol v3
   nntp      119/tcp  # Network News Transport Protocol
   imap      143/tcp  # Internet Mail Access Protocol rev4
   imsp      406/tcp  # Internet Message Support Protocol (deprecated)
   nntps     563/tcp  # NNTP over TLS
   imaps     993/tcp  # IMAP over TLS
   pop3s     995/tcp  # POP3 over TLS
   kpop      1109/tcp # Kerberized Post Office Protocol
   lmtp      2003/tcp # Lightweight Mail Transport Protocol service
   smmap     2004/tcp # Cyrus smmapd (quota check) service
   csync     2005/tcp # Cyrus replication service
   mupdate   3905/tcp # Cyrus mupdate service
   sieve     4190/tcp # timsieved Sieve Mail Filtering Language service

Make sure that these lines are present or add them if they are
missing.


6. Configuring Cyrus
--------------------

(Nearly there)

Set up a simple directory structure for Cyrus to store emails, owned
by the "cyrus" user and group "mail":

   sudo mkdir -p /var/lib/cyrus /var/spool/cyrus
   sudo chown -R cyrus:mail /var/lib/cyrus /var/spool/cyrus
   sudo chmod 750 /var/lib/cyrus /var/spool/cyrus

The "/var/spool/cyrus" directory is the partition where Cyrus will
store mail and must be allocated sufficient storage. The exact
location can be configured in imapd.conf(5) in the partitions options.

Following installation, a fairly comprehensive set of sample
configuration files may be found in "/usr/share/doc/cyrus-
doc/examples/".  Select one from each of the "cyrus_conf" and
"imapd_conf" directories, and install as "/etc/cyrus.conf" and
"/etc/imapd.conf" respectively.

A basic description of these files:

* Stand-alone server configurations (pick one):

  * small.conf

       A simple small server

  * normal.conf

       A more typical server

  * prefork.conf

       As above, but with several server processes pre-forked for
       faster connection initialization.

  Note: The "normal.conf" file in the "imapd_conf" directory is
    intended to work with any of the above files from the "cyrus_conf"
    directory.

* Cyrus Aggregation - Murder – configurations (these constitute a
  set, with at least one of each required):

  * murder-mupdate.conf

       The Mupdate Master server; holds the canonical copy of the
       "mailboxes.db" database.

  * murder-backend.conf

       A backend server which holds the actual mailboxes and interacts
       with frontend proxies and/or clients.

  * murder-frontend.conf

       A frontend server which holds no mailboxes, but either refers
       clients to the proper backend server for each requests, or
       proxies those requests directly.

* Replication configurations (these constitute a set, with one
  master and at least one replica required):

  * normal-master.conf

       The master server which uses the "sync_client" program to send
       mailbox updates to each replica on a rolling or periodic basis.

  * normal-replica.conf

       A typical replica server, which accepts updates from the
       master.

  Note: When working with replication or aggregation (Murder), the
    example files in "cyrus_conf" and "imapd_conf" of the same name
    are intended to be used together.

You should review each of these and then install as desired to
"/etc/", making changes as needed.  In particular, you’ll need to set
passwords for the various users used to authenticate between instances
in a Murder or Replication environment.

For example:

   install -m 600 doc/examples/cyrus_conf/normal.conf /etc/cyrus.conf
   install -m 600 doc/examples/imapd_conf/normal.conf /etc/imapd.conf
   vi /etc/imapd.conf
   ...
   vi /etc/cyrus.conf
   ...


7. Launch Cyrus
---------------

If using a distribution package, you probably now have an init script
installed, that you can invoke with your system’s usual service
control mechanism.

If you built from source, you will need to write your own init script.
The simplest one will simply start/stop the master(8) binary, with
suitable options, as root (master will drop root privileges itself as
soon as it possibly can).
