Der eigene Mailserver II: Cyrus IMAP

This post is the second of two on running your own mail server without having to maintain dozens of configuration files and struggling through hundreds or thousands of settings. The first one is on setting up OpenSMTPD as a mail transfer agent (MTA) — Running you own mail server I: OpenSMTPD. This one wraps it up with a straightforward companion for managing local mail boxes: Cyrus IMAP.

Meet Cyrus IMAP

Dating back to 1993, Cyrus is now an open-source IMAP server that can also manage contacts and maintain a calendar. I focus here on the mail delivery agent (MDA), but you can find all the other possibilities at the Cyrus website. Cyrus IMAP comes with its own licence, which is basically a four-clause BSD licence, thus limiting you in no way.

There are binary distributions for many operating systems, including multiple varieties of Linux, and FreeBSD. On FreeBSD, installation involves pkg install cyrus-imapd36-http and it will also get and install Cyrus' Simple Authentication and Security Layer (SASL) packages — plus anything else you need.

Setting up an IMAP server is a bit more complicated than an SMTP server, but still nothing to be afraid of. There are two main configuration files: imapd.conf and cyrus.conf. The former is about the mail boxes and their users, the latter about Cyrus and its interfaces itself. imapd.conf explains may of its options in comments itself; details can be found on the manual page. To make things easier, I present a reduced configuration file here, that contains everything you need to run a simple IMAP server for virtual mail boxes that works with the OpenSMTPD installation for the other post. cyrus.conf also has a manual page and is considerably shorter. The one I use here stays close to the sample version.

Installation

After installing the binary packages, a few things need to be organised. What I present here is based on FreeBSD, so things may be different if you use another OS. Simply check what needs to be done.

Installation creates the user cyrus. It needs to be a member of the wheel group, so, as root:

In order to avoid permission problems, I duplicate some data and give Cyrus its own playground:

You now have a bunch of directories with the correct ownership.

Configuring Cyrus

The configuration file for Cyrus itself can remain largely standard. The one here differs in only a few points from the sample version. First, there are only three rather than four SERVICES. The first is for serving IMAP clients through insecure connections (you may even want to scrap that one, too). The second is for serving mail clients through a TLS connection. This opens the listener on the well-known port for imaps, 993 and is the port on which your mail client will connect to receive messages and synchronise all server-side mailboxes. The third line creates the Unix socket for the Local Mail Transfer Protocol, through which Cyrus IMAP receives the incoming messages from OpenSMPTD. The alternative is a network port too, but as we only want delivery of messages from within the local machine, a Unix socket to me seems a much more elegant solution than a network port on localhost.

The second change is on line 13, where Cyrus IMAP is instructed to not only remove duplicates in the database after three days (-E 3), but also to remove previously deleted mail boxes (-D 28) and messages (-X 28) after 28 days. The EVENTS listed here are run like cron jobs, so these clean-ups are done every day at 4 a.m.

START {

  recover cmd="ctl_cyrusdb -r"

}

SERVICES {

  imap cmd="imapd" listen="imap" prefork=0

  imaps cmd="imapd -s" listen="imaps" prefork=0

  lmtpunix cmd="lmtpd" listen="/var/imap/socket/lmtp" prefork=0

}

EVENTS {

  checkpoint cmd="ctl_cyrusdb -c" period=30

  delprune cmd="cyr_expire -E 3 -D 28 -X 28" at=0400

  tlsprune cmd="tls_prune" at=0400

}

DAEMON {

  idled cmd="idled"

}

Configuring IMAP

Here is my as-easy-as-it-gets configuration file for managing mail boxes with Cyrus IMAP:

configdirectory: /var/imap

partition-default: /var/spool/imap

unixhierarchysep: yes

admins: imapadmin

sasl_pwcheck_method: saslauthd

sasl_opiekeys: /usr/local/cyrus/opiekeys

tls_server_cert: /etc/ssl/certs/example_com.crt

tls_server_key: /etc/ssl/private/example_com.key

virtdomains: userid

Lines 1, 2, and 6 direct Cyrus to the configuration directories and the file for OPIE keys we have created before. Line 3 activates the use of the Unix hierarchy separator, better known as the slash (/); the default is a period — like for domain names — but for the mailbox structure, a separator related to the local file system is more appropriate. Line 4 defines the user name for the mail box administrator; imapadmin is the user name you will be using to add or remove users. Line 5 instructs Cyrus IMAP to turn to the SASL database to authenticate users. More on that below.

Lines 7 and 8 refer to your servers private key and certificate. They can usually be the same as the ones used for OpenSMPTD in smtpd.conf, as it is the same server clients are talking to. Without it, you cannot use the IMAPS protocol on port 993. Finally, line 9 instructs Cyrus IMAP to split a user identifier at the last at-sign (@) to find the domain for authenticating users. The option userid should be the default, but it isn't, so it needs to be set explicitly.

What else

That is all you need to run your IMAP server, albeit without any users or actual mail boxes for now — see the next section for that. Running the server means running both cyrus_imapd and saslauthd for user authentication. On FreeBSD, you must include saslauthd_flags="-a sasldb" in your /etc/rc.conf or /etc/rc.conf.local for the SASL authenticator to actually use the database you will maintain.

Creating the administrator account

Simple run saslpasswd2 -c imapadmin to create the administrator user specified in the configuration file before. You need to provide an appropiate password, obviously. The successful creation of the user in the database can be checked by trying to authenticate using testsaslauthd -u imapadmin -p {password}, where {password} should be the actual password you set. If everything goes well, you will see OK.

You can always see for whom there are authentication accounts in the database by running sasldblistusers2.

Creating user accounts

Using the administrator account, you can create and destroy user mail boxes. The tool for this is cyradm. Log in by typing cyradm -i imapadmin localhost and providing your adminstrator password. You should see the prompt localhost>.

Create a new mail box with the cm command, followed by the account name — the full mail address is most logical — which is preceded by user/, like cm user/john.doe@example.com. You can check whether John's mail box exists by listing all mail boxes: lm. exit when you are done creating mail boxes.

The only thing that is missing now, is an account in the authentication database, so that users can actually connect to the server and collect their messages. The command is the same as for creating the administrator password: saslpasswd2 -c john.doe@example.com. For manual testing, you need to specify the user name and the realm separately, using the -r option, so testing John's password would be testsaslauthd -u john.doe -r example.com -p {password}.

Removing user accounts

You can remove users from the authentication database using the -d option to saslpasswd2. You remove mail boxes with the dm command in cyradm, but with one caveat: you need to give the permission to do so to the administrator himself first. For this, you need the command sam user/john.doe@example.com imapadmin all.

Whenever you create or destroy mail boxes, restart imapd afterwards.