wilde: doc/raw-howtos kolab_2.0_to_2.1_upgrade_instructions.txt, NONE, 1.1

[cvs at kolab.org]

Author: wilde

Update of /kolabrepository/doc/raw-howtos
In directory doto:/tmp/cvs-serv13665

Added Files:
	kolab_2.0_to_2.1_upgrade_instructions.txt 
Log Message:
Added file with upgrade instructions from server 2.0.x to 2.1
This is the first draft written by Bernhard Herzog.


--- NEW FILE: kolab_2.0_to_2.1_upgrade_instructions.txt ---
Upgrade Kolab Server from 2.0.x to 2.1
======================================
2006-10-12, Bernhard Herzog <bh at intevation.de>


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.


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 corresponding line 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. The script works on the ldif data that was
exported with slapcat earlier:

   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



4. kolabconf

Now start the openldap server and run kolabconf

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


Kolabconf will most likely complain about be some files ending in
.rpmsave or .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