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.
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
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
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
/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
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.
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
- Make sure that the
STARToption is set to yes
- Set the``MECHANISMS`` option to sasldb
- Make sure that the
Start the SASL auth daemon:
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.
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
And right below
MAILER_DEFINITIONS, add this:
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.
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
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.
Postfix supports a great many configurations for mail delivery
transport, so these settings will depend on whether you’re planning
to use the
definitions. For our examples we’ll be using
as needed for your purposes, and please consult the Postfix
documentation at http://www.postfix.org/postconf.5.html
Setup your recipient maps, thus defining for which recipients the
virtualdestination 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"
Optional: Set the concurrency and recipient limits for LMTP delivery to the
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.
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
lmtpsocketoption 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¶
Set up a simple directory structure for Cyrus to store emails, owned by
cyrus user and group
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
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
imapd_conf directories, and install as
A basic description of these files:
Stand-alone server configurations (pick one):
- A simple small server
- A more typical server
- As above, but with several server processes pre-forked for faster connection initialization.
normal.conffile in the
imapd_confdirectory is intended to work with any of the above files from the
Cyrus Aggregation - Murder – configurations (these constitute a set, with at least one of each required):
- The Mupdate Master server; holds the canonical copy of the
- A backend server which holds the actual mailboxes and interacts with frontend proxies and/or clients.
- 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):
- The master server which uses the
sync_clientprogram to send mailbox updates to each replica on a rolling or periodic basis.
- A typical replica server, which accepts updates from the master.
When working with replication or aggregation (Murder), the example files in
imapd_confof 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.
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).