# Upgrading From Previous Versions

## Upgrading from 2.3.15

- The SQL detection code in configure has been reworked. Separate options for the include directories and lib directories have been added. Previous SQL options may not work as expected.

## Upgrading from 2.3.10

- STARTTLS is now allowed for externally preauth'd LMTP connections. If you don't want STARTTLS to be advertised and used by preauth'd clients, you can set `<service_name>_tls_cert_file: disabled` in imapd.conf.

## Upgrading from 2.3.9

- The method used for generating Globally Unique IDentifiers used for replication has been changed to be the SHA1 hash of the messages. If you wish to upgrade the existing GUIDs in particular mailbox(es) or the entire server, perform the following steps in the listed order. Note that is is NOT REQUIRED that existing GUIDs be upgraded.
  1. Zero GUIDs on the replica (`reconstruct -g`)
  2. Regenerate GUIDs on the master (`reconstruct -G`)
  3. Regenerate GUIDs on the replica (`reconstruct -G`)

## Upgrading from 2.3.8

- You must install and configure Cyrus SASL version 2.1.17 or later to use Cyrus IMAP 2.3.9 and later. You can download SASL at http://cyrusimap.web.cmu.edu/downloads.html#sasl.
- The default value of the `allowplaintext` option has been changed to disabled (0). If you need to allow cleartext passwords on the wire, then you will have to explicitly enable the `allowplaintext` option in `imapd.conf`.

## 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.)

last modified: $Date: 2009/12/03 20:48:14 $