Upgrade Kolab Server from 2.0.x to 2.1
======================================

Preliminary instructions for the upgrade of a Kolab Server from version
2.0.x to Kolab Server 2.1.

NOTE: This is an early version of the upgrade instructions.  It is not
very well tested and may not cover all problems that may occur during
the upgrade.  Before attempting the upgrade, make sure you have a
current and working backup of your data.


Preparation for the Upgrade
---------------------------

1. Backup the old installation.


2. Stop the Kolab Server

    /kolab/bin/openpkg rc all stop

3. Extract ldap data

Copy the contents of the openldap database (use a different output
filename if you want):

    /kolab/sbin/slapcat > ~/kolab-2.0.ldif

4. Prepare for berkeley db update

    cd /kolab/var/imapd/db
    /kolab/bin/db_recover
    rm /kolab/var/imapd/db/*


Installation
------------

The installation of the new packages is done in the normal way.  See the
file 1st.README accompanying the 2.1 server for details.  Do not do
anything after the installation yet.  In particular, do not start any
part of the server again or run kolabconf.


Configuration
-------------

1. Check custom configuration

If you have custom configurations in your templates, the installation
process renames your templates and leaves them in files with the
extension .rpmsave.  Copy any modifications from your templates to the
new one if they are still needed.

After that the files with the extension .rpmsave must be removed or
renamed.  There might be more files with the .rpmsave ending in
/kolab/etc, you can find them for example using the find command:

find /kolab/etc -name '*.rpmsave'

Any files found must be checked and moved out of the way, in most
cases they can just be deleted.


2. Cyrus IMAPd

The default imapd configuration has been changed to enable the
hashimapspool option.  This means that in 2.1 the default directory
layout of the imapd spool (/kolab/var/imapd/spool/) is different from
the one in 2.0.  When you upgrade from 2.0 it's best to keep using the
old structure, so remove or comment out the line "hashimapspool: yes"
in /kolab/etc/kolab/templates/imapd.conf.template *before* running
kolabconf.

For new installations the new default setting is recommended because
it's more efficient especially when you have many mailboxes.

For some background information about this see the dicussion at
https://intevation.de/roundup/kolab/issue1089


3. LDAP

You need to make two small changes to the configuration file
/kolab/etc/openldap/slapd.conf:

  - comment out the line

     require        none

  - Move the line with the suffix setting to just after the "database
    bdb" line.

These changes have already been made in the new slapd.conf.template, so
that could be used for guidance.

Convert the openldap data.  The LDAP data-structures have changed
between 2.0 and 2.1 as described in Kolab2 Architecture Draft:
http://kolab.org/doc/concept-draft-cvs20060921.pdf

There's a Python script that can do the transformation.  The script is
utils/admin/convert-ldif-21.py in Kolab CVS and requires python >= 2.1
and python-ldap >= 2.0, you can download the current version from:

  http://kolab.org/cgi-bin/viewcvs-kolab.cgi/*checkout*/utils/admin/convert-ldif-21.py

The script works on the ldif data that was exported with slapcat earlier:

   python convert-ldif-21.py ~/kolab-2.0.ldif ~/kolab-2.1.ldif


Then restore the openldap data using the output from upgrade-ldap.py:

   rm /kolab/var/openldap/openldap-data/*
   /kolab/sbin/slapadd -l ~/kolab-2.1.ldif

This will issue some warnings which can be safely ignored.


4. kolabconf

Now start the openldap server and run kolabconf

    /kolab/bin/openpkg rc openldap start
    /kolab/sbin/kolabconf


Kolabconf will might complain about be some files ending .rpmnew under
/kolab/etc.  Check those files and move them out of the way.  It's
likely that you can simply remove them.


Start the Server
----------------

Now you should be able to start the server again:

    /kolab/bin/openpkg rc all start


Final Steps
-----------

1. The internal format of the ldap records for the list of privileged
   networks has changed, to updated these recods go to the kolab web
   interface an log in as administrative user.  Open the "Services"
   page and search for the "Privileged Networks" section.  Click the
   update button for the networks list.

2. Kolab 2.1 doesn't need some of the OpenPKG packages which were
   installed for 2.0, these can be removed:

   /kolab/bin/openpkg rpm -e dcron vim pth

   Especially the dcron package should be removed in any case,
   otherwise deprecated cronjobs will be run and generate mails with
   error messages to the kolab administrator.


$Id: kolab_2.0_to_2.1_upgrade_instructions.txt,v 1.4 2006/11/15 17:37:40 thomas Exp $