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

Instructions for upgrading Kolab Server 2.0.4 to 2.1.0

NOTE: Before attempting the upgrade, make sure you have a
current and working backup of your data.


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

1. Stop the Kolab Server and related cronjobs:

   Comment out all OpenPKG entries in /etc/crontab, then run:

    # /kolab/bin/openpkg rc all stop

2. Backup the old installation:

   You could use rsync on the running server and then rsync again
   to transfer only changed files to keep the downtime short.

3. Extract ldap data:

   Copy the contents of the openldap database, use a different output
   filename if you want. You should make sure that no other users can
   read the sensitive data contained in the ldif file, e.g. with umask:

    # umask 077
    # /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


The default database format for /kolab/var/imapd/annotations.db and
/kolab/var/imapd/mailboxes.db has changed from skiplist to berkeley db.

If you want to keep the old format, comment out or remove the lines
"annotation_db: berkeley" and "mboxlist_db: berkeley" in the file
"/kolab/etc/kolab/templates/imapd.conf.template" and make sure the file
"/kolab/etc/imapd/imapd.conf" reflects this, too.

To convert the databases to berkeley db format, execute as root:

    # su - kolab-r
    $ cd /kolab/var/imapd/
    $ mv annotations.db annotations.db-skiplist
    $ cvt_cyrusdb /kolab/var/imapd/annotations.db-skiplist skiplist \
                  /kolab/var/imapd/annotations.db berkeley
    $ mv mailboxes.db mailboxes.db-skiplist
    $ cvt_cyrusdb /kolab/var/imapd/mailboxes.db-skiplist skiplist \
                  /kolab/var/imapd/mailboxes.db berkeley
    $ exit

See http://wiki.kolab.org/index.php/Kolab2_IMAPD_annotations.db_Problems
for details about this topic.


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,
it requires python-ldap:

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


Then restore the openldap data using the output from convert-ldif-21.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 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


Resource Accounts
-----------------

With server version 2.1 the way in which the kolab resource manager
accesses the calender folders of resources has changed.  To make old
resource accounts work after the upgrade, you have to grant access to
the resources imap folders to the so called calender user.

First you have to identify the existing resource accounts, this can be
done using the convert-ldif-21.py script, which was introduced in the
section on converting the LDAP data.

    # python convert-ldif-21.py --list-resources ~/kolab-2.0.ldif

lists the UIDs (normally the email addresses) of all resource accounts.

Now you have to add ACLs to the mailboxes of the resources, which
allow the calendar user to access them.  Per default the calendar user
is calendar@YOUR_DOMAIN:

Connect with cyradm to the Kolab imap server as user manager:

    # /kolab/bin/cyradm -u manager localhost

Then use the `setaclmailbox' command (sam) to set the necessary
permissions.  You can generate a list of commands which should do the
right thing on most standard installations with:

    # python convert-ldif-21.py --list-resources ~/kolab-2.0.ldif | \
      sed 's-\(.*\)\(@.*\)-sam */\1*\2 calendar\2 all-'


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.

3. Activate the entries for OpenPKG in /etc/crontab again.

4. The database backend for the free/busy cache was changed to solve licensing
   issues between php4+ and gdbm. See kolab/issue1607 for details.
   The old cache file has to be deleted manually:

     # rm /kolab/var/kolab/www/freebusy/cache/pfbcache.db

   Then updating the free/busy cache has to be triggered for all calendar
   folders of all accounts:
   - Users need to create or update an appointment in their folders.
   - Resources can be invited to a new appointment or send them an update
     to an existing appointment.

   Alternatively you can trigger each folder with an https request:
   https://[server]/freebusy/trigger/[email]/[path_to_calendar_folder].pfb,
   e.g. https://kolab.example.com/freebusy/trigger/user@example.com/Calendar.pfb
   (you need to authenticate with the user's credentials)

$Id: kolab_2.0_to_2.1_upgrade_instructions.txt,v 1.12 2007/04/20 15:01:05 thomas Exp $