Upgrading cyrus-imapd to cyrus2-imapd on Debian
$Id: UPGRADE.Debian,v 1.17 2006-01-19 13:55:42 hmh Exp $
(thanks to David D. Kilzer <ddkilzer@theracingworld.com> for this document)
-----------------------------------------------

For more information, see README.Debian[.gz] in /usr/share/doc/cyrus21-common/
and the web page below, part of the cyrus-utils project at SourceForge:

  http://cyrus-utils.sourceforge.net/faq

This document describes the procedure for upgrading from the old cyrus-imapd
(v1.5.x) package to the new cyrus21-imapd (v2.1) package.  While this is a
manual process, it is very straightforward.

The procedure for converting a v1.6 cyrus store to v2.1 is not explained here,
but the tools to convert the sieve scripts are in /usr/lib/cyrus/upgrade.

Your SASL installation may require further conversion steps, as Cyrus v2.1 uses
SASL v2, while Cyrus v1.5 used SASL v1.5.  /usr/share/doc/libsasl2 has more
information on SASL v2.  Do pay attention to your SASL v2 installation, such
as permissions and such.  When in doubt, read the README.simpleinstall
document, as it describes an initial SASLv2 setup.

NOTE: If you've already installed the cyrus21 packages, skip to step 5.

 1. Become the "root" user on your local system.

    $ /bin/su -
    #

 2. Look for any running cyrus daemons using the ps(1) command.  Use
    kill(1) to stop any processes that are found.

    # /etc/init.d/pwcheck stop
    # ps auwwx | grep cyr
    # ps auwwx | grep pop3d
    # ps auwwx | grep imapd
    # ps auwwx | grep nntpd

 3. Remove the old cyrus packages.

    ######################################################################
    WARNING  WARNING  WARNING  WARNING  WARNING  WARNING  WARNING  WARNING
    ######################################################################
    
    Some versions of the cyrus-imapd packages, with versions 1.5.19-9.10
    up to 1.5.19-20 (shipped in Debian Sarge 3.1r1) will entirely erase
    the mail spool when purged with no questions asked.
    
    You must NOT purge these packages before moving /var/lib/cyrus and
    /var/spool/cyrus to somewhere safe.  Failure to do so will cause data
    loss.
    
    # mv /var/lib/cyrus /var/lib/old-cyrus
    # mv /var/spool/cyrus /var/spool/old-cyrus

    The cyrus-imapd packages in Woody (1.5.19-9.2) are safe, as well as
    the fixed cyrus-imapd packages 1.5.19-20sarge1 which should make it to
    Debian Sarge 3.1r2.

    ######################################################################

    # apt-get --purge remove cyrus-common cyrus-admin cyrus-imapd cyrus-pop3d \
      cyrus-nntpd   [BUT SEE THE ABOVE WARNING FIRST!!!]

    or use dselect/aptitude/synaptic/your favorite deb management tool.

    IMPORTANT: You must answer "n" to this question:  "Do you want me to
    remove the Cyrus mail and news spool (y/n) [n] ?"

    NOTE: You could also copy -a the /var/spool/cyrus and /var/lib/cyrus
    folders somewhere else, just in case.

 4. Install the new cyrus21-imapd packages. Make sure no user will try
    to connect to imapd/pop3d and that no MTA will try to deliver to lmtpd
    until you do step 5.

    cyrus21-common       [required]
    cyrus21-admin        [required]
    cyrus21-imapd        [optional; must have one of imapd or pop3d]
    cyrus21-pop3d        [optional; must have one of imapd or pop3d]
    libcyrus-imap-perl21 [required]

    # apt-get install PACKAGE-NAME [PACKAGE_NAME ...]

    or use dselect.

 5. Stop the cyrmaster process.

    # /etc/init.d/cyrus21 stop

 5a. Make sure Cyrus won't start until the upgrade process is over.

    # cp -f /usr/lib/cyrus/upgrade/cyrus-db-types.upgrading_from_1.5.txt \
            /usr/lib/cyrus/cyrus-db-types.active

 6. Install the libdb3-util package.

    # apt-get install libdb3-util

 7. Change to the "cyrus" user.

    # /bin/su - cyrus
    $

 8. Run the rehash program.

    $ /usr/lib/cyrus/upgrade/rehash basic

 9. Run ctl_mboxlist to update the "mailboxes" file.

    $ cd /var/lib/cyrus
    $ /usr/sbin/ctl_mboxlist -u < mailboxes

10. Run the cyrreconstruct program from the /var/spool/cyrus directory
    to reconstruct the mailboxes.

    $ cd /var/spool/cyrus
    $ /usr/sbin/cyrreconstruct -r user.*

    (you may need to cyrreconstruct other mailboxes, if you have any
    system mailboxes or shared mailboxes not in the user hierarchy)

11. Exit the "cyrus" user, back to "root".

    $ exit
    #

12. Upgrade all of the db2 files used by Cyrus from to db3.

    # find /var/lib/cyrus -name \*.db -print -exec /usr/bin/db3_upgrade {} \;

13. Convert the state databases to those used by new Cyrus 2.1

    Read /usr/share/doc/cyrus21-common/README.Debian.database, and follow
    whatever steps you need to change the backends from db3 to skiplist.

    This step needs some work, if you can send your experiences with it
    to hmh@debian.org, I will update this document accordingly.

**** The upgrade of Cyrus' stores are now complete ****

You may want to remove any left-over empty directories from the old version,
and re-run /usr/sbin/cyrus-makedirs just in case you got one of them wrong.

Now, you need to reconfigure the new Cyrus imapd to adequate it to your system
and SASL requirements. The Cyrus config files are /etc/imapd.conf,
/etc/cyrus.conf and /etc/default/cyrus21.

Depending on your SASL configuration, you may also need to modify
/etc/pam.d/{imap,pop,sieve,lmtp} and other SASL configuration files.

Do not forget to edit /etc/imapd.conf to e.g. set the "admins: cyrus" line (if
you use "cyrus" as the name for the administrator).