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

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 -f /var/run/saslauthd/mux

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, Exim). See Mail delivery from your MTA.

### 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
    nntps     563/tcp  # NNTP over TLS
    imaps     993/tcp  # IMAP over TLS
    pop3s     995/tcp  # POP3 over TLS
    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).