Upgrading to 3.4¶
Note
This guide assumes that you are familiar and comfortable with administration of a Cyrus installation, and system administration in general.
It assumes you are installing from source or tarball. If you want to install from package, use the upgrade instructions from the package provider.
Upgrading: an overview
-
Note..4.
How are you planning on upgrading?¶
Ideally, you will do a sandboxed test installation of 3.4 using a snapshot of your existing data before you switch off your existing installation. The rest of the instructions are assuming a sandboxed 3.4 installation.
Upgrade by replicating¶
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.4 installation and failover to the new installation when you're ready. The replication protocol has been kept backwards compatible.
If your old installation contains mailboxes or messages that are older than 2.4, they may not have GUID fields in their indexes (index version too old), or they may have their GUID field set to zero. 3.4 will not accept message replications without valid matching GUIDs, so you need to fix this on your old installation first.
You can check for affected mailboxes by examining the output from the mbexamine(8) tool:
- mailboxes that report a 'Minor Version:' less than 10 will need to have their index upgraded using reconstruct(8) with the -V <version> parameter to be at least 10.
- mailboxes containing messages that report 'GUID:0' will need to have their GUIDs recalculated using reconstruct(8) with the -G parameter.
If you have a large amount of data, these reconstructs will take a long time, so it's better to identify the mailboxes needing attention and target them specifically. But if you have a small amount of data, it might be less work to just reconstruct -G -V max everything.
Upgrade in place¶
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.4 does not support Berkeley DB at all.
Note
If you are upgrading from Cyrus version 2.5 or earlier, and your system is configured with the following combination in imapd.conf(5):
fulldirhash: yes hashimapspool: either yes or no unixhierarchysep: yes
then you will not be able to upgrade-in-place. This is due to a change in how directory hashes are calculated for users whose localpart contains a dot, which was introduced in 3.0.0. After an in-place upgrade, Cyrus will not be able to find these users' metadata and/or mailboxes.
If you have this configuration, you will need to upgrade by replicating, not in place..4 Cyrus¶
Download the release 3.4, you can consider using the experimental in imapd.conf(5) changed in 3.0, which will affect you
if you are upgrading to 3.4 from something earlier than 3.0. Implications
are outlined in the Note in User Namespace Mode and
Switching the Alternative Namespace. Please also see "Sieve Scripts,"
below.
- unixhierarchysep: on
- altnamespace: on
In cyrus.conf(5) move idled from the START section to the DAEMON
Warning
Berkeley db format no longer supported since 3.0
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.4 installation.
Databases potentially affected: mailboxes, annotations, conversations, quotas.
On old install, prior to migration:
cvt_cyrusdb /<configdirectory>mailboxes.db berkeley /tmp/new-mailboxes.db skiplist
If you don't want to use flat or skiplist for 3.4, you can use cvt_cyrusdb(8) to swap to new format:
cvt_cyrusdb /tmp/new-mailboxes.db skiplist /<configdirectory>/mailboxes.db <new file format>
Note
The cvt_cyrusdb(8) command does not accept relative paths.
7. Start new 3.4 Cyrus and verify¶
sudo ./master/master -d
Check
/var/log/syslog for errors so you can quickly understand potential problems.
When you're satisfied version 3
If you are upgrading from 3.0, and have the reverseacls feature enabled in imapd.conf(5), you may need to regenerate the data it uses (which is stored in mailboxes.db). This is automatically regenerated at startup by ctl_cyrusdb -r if the reverseacls setting has changed. So, to force a regeneration:
- Shut down Cyrus
- Change reverseacls to 0 in imapd.conf(5)
- Run ctl_cyrusdb(8) with the -r switch (or just start Cyrus, assuming your cyrus.conf(5) contains a ctl_cyrusdb -r entry in the START section). The old RACL entries will be removed
- (If you started Cyrus, shut it down again)
- Change reverseacls back to 1
- Start up Cyrus (or run ctl_cyrusdb -r). The RACL entries will be rebuilt
9. Do you want any new features?¶
3.4 comes with many lovely new features. Consider which ones you want to enable. Check the 3.4 release notes for the full list..
If you are upgrading from 2.4, and wish to use XFER to transfer your mailboxes to your new 3.4 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 later mailbox versions, and will downgrade mailboxes (losing metadata) in transit. 2.4.19 and later versions correctly recognise 2.5 and later servers, and will not downgrade mailbox versions in transit.