For those upgrading from 2.3.X; newer releases of Cyrus IMAP will use
significantly more memory per selected mailbox. This is not an error
or bug; it’s a feature. The newer code is holding more data and
metadata in memory for purposes of faster access to more of the
mailbox. This is not a memory leak.

You will need to install from our packaged tarball. We provide a full list of libraries that Debian requires, but we aren’t able to test all platforms: you may find you need to install additional or different libraries to support v3.0.

Ideally, you will do a sandboxed test installation of 3.0 using a snapshot of your existing data before you switch off your existing installation. The rest of the instructions are assuming a sandboxed 3.0 installation.

If you’re familiar with replication, and your current installation is 2.4 or newer, you can set up your existing
installation to replicate data to a new 3.0 installation and failover to the new installation when you’re
ready. The replication protocol has been kept backwards compatible.

If you are upgrading in place, you will need to shut down Cyrus
entirely while you install the new package. If your old installation
was using Berkeley DB format databases, you will need to convert or
upgrade the databases before you upgrade. Cyrus v3.0 does not
support Berkeley DB at all.

Since the various files, databases, directories, etc. used by Cyrus
must be readable and writable as the cyrus user, please make sure
to always perform Cyrus commands as the cyrus user, and not
as root. In our documentation, we will always reference Cyrus
commands in this form – cyr_info(8) – before using
examples of them, so you’ll know that those commands must be run as
the cyrus user.

Doing so in most systems is as simple as using either the su or
sudo commands, like so:

(You do already have a backup strategy in place, right? Once you’re on 3.0, you can
consider using the new inbuilt backup tools.)

Copy all of this to the new instance, using rsync or similar tools.

Note

Cyrus keeps its data and databases in various locations, some of
which may be tailored by your configuration. Please consult
File & Directory Locations for guidance on where data lives in your
current installation.

For example, to copy from an existing Debian or Ubuntu installation
using their standard locations, you might execute this series of
commands on the new server (where “oldimap” is the name of the old
server):

You don’t need to copy the following databases as Cyrus 3.0 will
recreate these for you automatically:

duplicate delivery (deliver.db),

TLS cache (tls_sessions.db),

PTS cache (ptscache.db),

STATUS cache (statuscache.db).

Note

You may wish to consider relocating these four databases to ephemeral
storage, such as /run/cyrus (Debian/Ubuntu) or /var/run/cyrus
or whatever suitable tmpfs is provided on your distro. It will place
less IO load on your disks and run faster.

Warning

Please be warned that some packages place tasks such as tlsprune
(tls_prune(8)) in the START{} stanza of
cyrus.conf(5). This will cause a startup problem if the
tls_sessions_db is not present. The solution to this is to
remove the tlsprune task from START{} and schedule it in
EVENTS{}, further down.

Again, check the locations on your specific installation. For example,
on FreeBSD systems, the configuration files imapd.conf(5)
and cyrus.conf(5) are in /usr/local/etc, rather than
/etc/. Run this command on the old server:

scp /etc/cyrus.conf /etc/imapd.conf newimap:/etc/

Using the cyr_info(8) command, check to see if your
imapd.conf file contains any deprecated options. Run this command on
the new server:

cyr_info conf-lint -C <path to imapd.conf> -M <path to cyrus.conf>

You need to provide both imapd.conf and cyrus.conf so that conf-lint knows
the names of all your services and can check service-specific overrides.

To check your entire system’s configuration you can use the conf-all
action. This command takes all the system defaults, along with anything
you have provided overrides for in your config files:

If your 2.4 imapd.conf(5) made use of the xlist-XX
directive(s), you can convert these to per-user special-use annotations
in your new install with the cvt_xlist_specialuse(8) tool

Sieve Scripts

Since defaults for options: unixhierarchysep: and
altnamespace: have changed in imapd.conf(5), you
may very likely need to modify any sieve scripts already on your
system. Fear not, there’s a tool for this task, called
translatesieve(8). This tool can handle situations
where either or both of these settings need change. Please consult
the man page for details.

Consider the following example, where the prior configuration was
already using altnamespace:on, but was not using
unixhierarchysep:on:

If you have any databases using Berkeley db, they’ll need to be
converted to skiplist or flat in your existing installation. And
then optionally converted to whatever final format you’d like in
your 3.0 installation.

Your upgrade is complete! We have a super-quick survey (3 questions only,
anonymous responses) we would love for you to fill out, so we can get a feel for
how many Cyrus installations are out there, and how the upgrade process went.

If you upgrade murder frontends before you upgrade all the backends,
they may advertise features to clients which the backends don’t support,
which will cause the commands to fail when they are proxied to the backend.

Generally accepted wisdom when upgrading a Murder configuration is to
upgrade all your back end servers first. This can be done one at a time.

Upgrade your mupdate master and front ends last.

If you are upgrading from 2.4, and wish to use XFER to transfer your
mailboxes to your new 3.0 server, please consider first upgrading your
2.4 setup to version 2.4.19 or later. Earlier versions of 2.4 do not
correctly recognise the 2.5 and 3.0 mailbox versions, and will
downgrade mailboxes (losing metadata) in transit. 2.4.19 and later
versions correctly recognise 2.5 and 3.0 servers, and will not
downgrade mailbox versions in transit.