Upgrading From Previous Versions
Upgrading from 2.3.3 or later (64-bit machines)
* Due to byte alignment issues in cyrus.index, all mailboxes will
have to be reconstructed.
Upgrading from 2.3.4 or 2.3.5
* Any mailboxes which had messages appended/delivered/copied with a
2.3.4 service or copied with a 2.3.5 imapd MUST be reconstructed in
order for the new messages to be displayed by clients.
Upgrading from 2.2.x or earlier
* If you wish to use separate metadata partition(s), you MUST first
shut down Cyrus and then perform the following:
1. Set the metapartition-* and metapartition_files options to suit
your configuration. For a full description of these options,
see the imapd.conf(5) man page.
2. Create the metadata partition directory(s) listed in the
metapartition-* option(s), setting the ownership and
permissions in same fashion as step 6 of install-configure.
3. Run the tools/migrate-metadata script (as the cyrus user) to
move the metadata files listed in the metapartition_files
option from the spool partition(s) to the new metadata
partition(s). This script may take a long time to run depending
on the number of mailboxes on the server, but presumably the
metadata partitions are located on high speed storage, so the
writes should be relatively fast.
4. Restart Cyrus.
Upgrading from 2.2.2 or earlier
* The Cyrus database backend configuration is now handled at runtime
using imapd.conf options. If you are not using the default backend
for any of the databases, make sure that you specify the correct
backend(s) in appropriate option(s).
* The format of the newspeer option has been changed. The existing
format will still be parsed, but the option should be upgraded to
use the new format (see imapd.conf(5) for details).
Upgrading from 2.2.1 or earlier
* The sieve bytecode format has changed again to correct an issue
with the short circuiting of the allof and anyof operators. To
upgrade existing scripts (outside of home directories), you can run
the tools/masssievec perl script included with the distribution. It
requires a path to your sievec binary. This should also upgrade
scripts that have already been compiled to bytecode. For example:
masssievec /usr/src/cyrus/sieve/sievec
Upgrading from 2.2.0 or earlier
* The improved directory hashing (fulldirhash) is now a runtime
configuration option. If you are currently using this feature, then
make sure that you enable the fulldirhash option in imapd.conf.
* The format of mailbox index files has changed. They are upgraded on
the fly, so you need to do nothing to upgrade. However, to
downgrade them you will need to remove the cyrus.index files, and
reconstruct the mailboxes, otherwise the index files will be
invalid.
* ctl_deliver -E has been deprecated in favor of cyr_expire -E. This
new tool does both duplicate delivery database pruning as well as
message expunging. You should replace the appropriate EVENTS entry
in cyrus.conf with one of those in the sample configurations in the
master/conf directory.
* The sieve bytecode format has changed. The new format is encoded in
network byte order, and will be transferable between architechures.
To upgrade existing scripts (outside of home directories), you can
run the tools/masssievec perl script included with the
distribution. It requires a path to your sievec binary. This should
also upgrade scripts that have already been compiled to bytecode.
For example:
masssievec /usr/src/cyrus/sieve/sievec
Upgrading from 2.1.x or earlier
General information (ALL SITES)
* The default database formats for the mailbox list and the seen
state databases has been changed to the skiplist backend. There are
two ways of dealing with this if you have been using the defaults.
1. Specify --with-mboxlist-db=berkeley and --with-seen-db=flat to
configure. This will instruct Cyrus to continue to use the
previous defaults.
2. Use the cvt_cyrusdb program to directly convert the databases.
This should be done with the server down, and with the binaries
from the new Cyrus distribution. Change any paths that do not
match your configuration.
For the mailbox list, the command looks like:
/usr/cyrus/bin/cvt_cyrusdb /var/imap/mailboxes.db berkeley /var/imap/mailboxes.db.new skiplist
mv /var/imap/mailboxes.db.new /var/imap/mailboxes.db
Note that the use of full paths to the database files is
important. You should also backup your old mailboxes database
before moving the new one in.
For the seen state databases, the command to get them all in
one fell swoop looks like:
find /var/imap/user -name \*.seen -exec /usr/cyrus/bin/cvt_cyrusdb \{\} flat \{\}.new skiplist \; -exec mv \{\}.new \{\} \;
The slashes are important for shell escaping. Again, you should
back up the contents of your /var/imap/user directory before
executing this command. These commands may take some time to
complete, especially if your databases are large.
We believe that skiplist offers considerable performance advantages
for these two databases over the previous defaults.
* Sieve scripts are now compiled into bytecode. The program sievec is
provided to do this process manually (timsieved will compile
submitted sieve scripts as they are uploaded). To upgrade existing
scripts (outside of home directories), you can run the
tools/masssievec perl script included with the distribution. It
requires a path to your sievec binary. For example:
masssievec /usr/src/cyrus/sieve/sievec
Note that this will fail for scripts that use the "envelope"
extention but do not require it. Cyrus 2.1's timsieved did not do
appropriate checking that the optional envelope test was required
before it was used.
* Configuration subsystem changes:
* The tls_[service]_* configuration options have been removed.
Now use [servicename]_tls_*, where servicename is the service
identifier from cyrus.conf for that particular process.
* The admins and lmtp_admins configuration options no longer
union. Per-service options completely override the default
value when they are specified.
* lmtp_allowplaintext is no longer a defined parameter and must
be specified using the service name of your lmtp process if you
require a specific value.
Specialized information (Murder, AFS, etc.)
* The IMAP IDLE command is now supported by proxyd and is controlled
by the imapidlepoll option, which is enabled by default (60
seconds). To disable IMAP IDLE in proxyd, set imapidlepoll to 0.
* User moves via RENAME and XFER are now controlled by the
allowusermoves option, which defaults to off.
* If you use ptloader, it now runs as a regular cyrus service. This
means that you will need master to acquire and maintain AFS tokens
for it. You will also need to create the ptclient directory under
your imap configdirectory, to hold the PTS cache (now a
full-fledged cyrusdb) and UNIX socket. In cyrus.conf, ptloader
should be setup to listen on <configdirectory>/ptclient/ptsock. See
the master/test/cmu-backend.conf example configuration file.
* Also, ptloader has been given a generic interface. You should now
specify "--with-auth=pts" (instead of "--with-auth=krb_pts") to
configure. There is also a --with-pts= configure option that
defaults to afskrb (Kerberos Canonicalization, AFS PTS Groups).
There is also an experimental ldap module. Note also that if
ptloader fails the lookup, authorization (and therefore
authentication) will now fail, as canonicalization is done inside
of ptloader.
* The format of sieve referrals has changed to be more consistant
with the current managesieve draft, this may cause interoperability
problems when using managesieve clients and servers from different
cyrus versions.
* Clients that use old-style ACL commands that include the "MAILBOX"
directive will no longer function. We do not know of any clients
that have this problem currently.
* Any applications that link libcyrus.a now need to link
libcyrus_min.a as well.
Upgrading from 2.1.13 or earlier
* We are now more forgiving of MIME boundry headers generated by
earlier versions of eudora. However, if you have messages already
in the mailstore that you want to fix you will need to reconstruct
the affected mailboxes to regenerate the cached bodystructure data
to take this into account. Nothing needs to be done for new
messages to be treated in this way.
Upgrading from 2.1.12 or earlier
* timsieved was corrected to behave properly in the altnamespace
configuration. However, this means that it was previously looking
for sieve scripts in "user.name" format instead of the (correct)
"user^name" format. A sample script to do this (which should be run
in the top level of the sieve directory) is in
tools/convert-sieve.pl. Note that this is only needed if you are
running with altnamespace turned on.
Upgrading from 2.1.3 or earlier
* If you use notifications (previously notify_zephyr or notify_unix)
this functionality has been seperated out to notifyd. See the
notifyd manpage and example entries in master/conf.
Upgrading from 2.1.2 or earlier
* Sieve has been updated to be compliant with RFC 3028 and
draft-martin-sieve-notify-01. All notify actions and any fileinto
and/or redirect actions using stringlists will have to be
updated/changed.
Upgrading from 2.0.16 or earlier
* You must install and configure Cyrus SASL version 2 to use Cyrus
IMAP 2.1 and later. You can download SASL at
http://cyrusimap.web.cmu.edu/downloads.html#sasl.
* If you use timsieved to manage Sieve scripts, and have enabled the
alternate namespace and/or the Unix hierarchy separator, run the
script "tools/translatesieve". This script will translate the
folder names in fileinto actions.
* Cyrus now uses the service name "sieve" instead of "imap" for the
SASL profile of timsieved. If you use timsieved to manage Sieve
scripts, be sure to update your password checking mechanism
appropriately,
* If you have enabled the improved directory hashing scheme, run the
script "tools/rehash full". This script will rehash your existing
directories.
* The hashed deliver databases (used for duplicate delivery
suppression and Sieve) have been merged into a single deliver.db
database. You can safely remove the entire /var/imap/deliverdb
directory structure after shutting down the server.
* All of the Cyrus databases have been unified under a single BDB
environment. A new ctl_cyrusdb tool is now used for database
recovery and checkpointing instead of ctl_mboxlist and ctl_deliver.
You should replace the appropriate START and EVENTS entries in
cyrus.conf with those in the sample configurations in the
master/conf directory.
* Cyrus now caches SSL/TLS sessions in an external database. If you
have support for SSL/TLS, and haven't disabled session caching (see
imapd.conf(5)), you should add a line like the following to the
EVENTS section of cyrus.conf to prune expired sessions from the
database:
# this is only necessary if caching TLS sessions
tlsprune cmd="tls_prune" period=1440
Upgrading from 2.0.6, 2.0.7, 2.0.8, or 2.0.9 or earlier
* If you use timsieved to manage Sieve scripts, run the script
"tools/upgradesieve". timsieved now uses symlinks instead of hard
links.
Upgrading from a previous 2.0 version to 2.0.6
Warning: You do not need to follow these instructions if you're
upgrading from version 1.6.
* You can now pick whether to use Berkeley db to store seen state,
the subscription files, and the mailboxes file or a flat text file,
at compile time only. (Look in imap/seen_db.c and imap/mboxlist.h.)
* The format of the mailboxes file and seen state has changed. It is
not possible to preserve seen state, but upgrade the mailboxes file
as follows:
1. Run ctl_mboxlist -d > mboxlist.temp to dump existing mailboxes.
2. Remove old database files: rm mailboxes.db db/* user/*/*.seen
3. With the new version of ctl_mboxlist, run ctl_mboxlist -u <
mboxlist.temp.
Upgrading from 1.6.22 or 1.6.24
Warning: Cyrus imapd 2.0 will automatically convert on-disk file
formats as the server is used. It is not possible to run 1.6 after 2.0
has been used on a mail spool without reconstructing every mailbox.
* Create some extra directories and remove the duplicate delivery
database:
mkdir /var/imap/db
mkdir /var/imap/socket
chown cyrus /var/imap/db /var/imap/socket
rm -rf /var/imap/deliverdb
* Convert mailboxes file to Berkeley DB:
su cyrus
cd /var/imap
ctl_mboxlist -u < mailboxes
ctl_cyrusdb -c
Please keep a backup of your mailboxes file. You can dump an
old-style mailboxes file by using ctl_mboxlist -d.
* remove "/etc/inetd.conf" entries. The imap and popd3d lines need to
be removed from /etc/inetd.conf and inetd needs to be restarted.
* master process configuration: You'll need to configure the master
process Cyrus process and ensure that it starts on boot. see this
section of the configuration instructions.
* MTA configuration. You will have to reconfigure your MTA to speak
to lmtpd. See this section of the configuration document.
* cyrus.seen conversion. The cyrus.seen file will be automatically
upgraded as users read mail. After some time, you might want to
delete the cyrus.seen file in each mailbox; it is superceded by the
user/joe.seen file.
* cyrus.index conversion. The cyrus.index file will be automatically
upgraded the first time each mailbox is SELECTed.
* Netnews conversion. The netnews programs are no longer built. If
you are using netnews, you will need to apply the diff in the
netnews/ directory to INN or see if INN is now distributing those
changes. You will also want to run remotepurge on a regular basis
to purge old netnews posts.
Upgrading from 1.6.13
* Upgrading from the Cyrus IMAP server version 1.6.13 or earlier: if
you use Sieve, you should run the "tools/upgradesieve" script, as
the format of the "/usr/sieve" directory has changed slightly.
timsieved, included in this release, will handle maintenance of
Sieve scripts.
* Upgrading from the Cyrus IMAP server version 1.6.10 or earlier: if
you export news via the IMAP server, you'll have to change your
"newsfeeds" file to contain
collectnews!:*:Tf,WR:collectnews
The format of the input to collectnews has changed.
Duplicate delivery suppression is now required for Sieve.
* Upgrading from the Cyrus IMAP server version 1.6.1 or earlier
(including 1.5.x!): the quota and user directories are now hashed
by the first character of the username. This is to reduce the
number of entries in any given directory. It doesn't do a great job
(and in some cases it will do a really poor job) but as a quick
hack it shouldn't make things worse. Optionally, the data
partitions can also be hashed by enabling the "hashimapspool"
option.
You must hash your directories using the "dohash" script in the
tools subdirectory. (If you want to hash your mail spool, be sure
to set "hashimapspool" before running "dohash".) This must be run
as the Cyrus user. Be sure to stop mail service while converting.
Doing this in single user mode is probably the safest.
Upgrading from 1.5
* Upgrading from the Cyrus IMAP server version 1.5 or earlier:
libsasl is now required. Configuring SASL to work may be a chore,
especially if you use shadow passwords.
* An ANSI C compiler is now required. gcc should work fine and can be
acquired from http://www.gnu.org/software/gcc/gcc.html.
* Make sure to read the upgrading instructions under 1.6 above.
* Upgrading from 1.5.14 or earlier requires deleting the delivered
database. Remove the file delivered.db in the configdirectory and
make a directory called "deliverdb" in the configdirectory. This
may cause some duplicates to get through.
* Upgrading from 1.5.14 or earlier requires removing the PTS cache
database (if the AFS PTS group support is used, which is not the
default). The PTS cache is in /var/ptclient/ptscache.db, and you
should remove it. This is because the format for the PTS cache for
IMSP has changed. If you use AFS ACLs, IMSPd, and IMAPd on the same
machine, make sure you have version 1.5a5 of the IMSP server for
this version of the IMAP server. (If you don't have IMSP, or AFS,
don't worry about it.)