Kolab2 Server Install and Upgrade Information ============================================= See http://kolab.org/ for general information about Kolab, or look at http://wiki.kolab.org/ for specific topics. It is recommended to subscribe to the announcement mailing list at http://kolab.org/mailman/listinfo/kolab-announce to receive security advisories and release announcements. * This development snapshot is not recommended for use in production! * Quick install instructions -------------------------- For a fresh install /kolab needs to be an empty directory with at least 2GB of free disk space. You can use a symlink, but do _not_ use an NFS mounted drive. If the directory does not yet exist, it will automatically be created. Make sure that the following names are not in /etc/passwd or /etc/groups, as openpkg will want to create them: "kolab" "kolab-r" "kolab-n" Check http://www.openpkg.org/documentation/ for additional documentation for the OpenPKG packaging system. To install the Kolab server, you need to download the files from the directory containing this file (1st.README) to some local directory. You can check the integrity of the downloaded files with: $ gpg --verify MD5SUMS $ md5sum -c MD5SUMS Then as root, cd into that local (and writable) directory and run # ./install-kolab.sh -H -F 2>&1 | tee kolab-install.log to build and install packages in /kolab. The command output will be logged to install-kolab.log so that you have a reference in case an errors occurs during installation. The install script needs to be able to write in the current working directory, so if you want to keep this directory clean or install install packages from a read-only location (e.g. CD-ROM), you can create a new directory and pass the path to the packages to the script using the -i option: # /path/to/packages/install-kolab.sh -H -F -i /path/to/packages If you do not want to install the Horde groupware client and/or the free/busy view tool, you can drop the flag "-H" and/or "-F". By default, the Kolab server will now be started at boottime, so you have to bootstrap the server configuration now to prevent unconfigured components from being started. Please run: # /kolab/etc/kolab/kolab_bootstrap -b and follow the instructions. General update instructions --------------------------- Usually an update of the Kolab server works as described here. In some cases you will need to deviate from these instructions a bit. All such cases are documented below, so read the release specific update instructions for all releases newer than the one you already have before you start the update. In any case you should completely read *all* relevant update instruction *before* starting the upgrade procedure. Always make sure you have a recent backup of your /kolab directory before you attempt to upgrade Kolab. The installation of the new packages works just as for the initial installation. Download the files as described above and run # ./install-kolab.sh -H -F 2>&1 | tee kolab-update.log If you installed without Horde or F/B-View you need to drop the corresponding flags again. install-kolab.sh will usually automatically determine which packages need to be built. If you have made changes to configuration files or an updated package includes configuration files which are usually regenerated from files in /kolab/etc/kolab/templates/ the old configuration file will be saved with the extension .rpmsave. For files generated from templates you just have to remove the rpmsave file, because services will refuse to start if there still is an rpmsave file, e.g.: # rm /kolab/etc/clamav/*.conf.rpmsave For other changed files (e.g. the template files themselves) you may want to transfer your changes from the .rpmsave backup to the new files. Then regenerate the configuration and restart Kolab with: # /kolab/sbin/kolabconf # /kolab/bin/openpkg rc all restart Or alternatively if the Kolab server was stopped before the upgrade: # /kolab/bin/openpkg rc openldap start # /kolab/sbin/kolabconf # /kolab/bin/openpkg rc all start Upgrade from 2.2-beta1 to 2.2-beta2 ----------------------------------- Before running install-kolab.sh, you should stop the running Kolab server and remove some packages which got renamed or will no longer be needed by running this command: # /kolab/bin/openpkg rc all stop # /kolab/bin/openpkg rpm -e --nodeps apache2 apache2-php getopt proftpd \ pth sharutils kolab-horde-fbview kolab-resource-handlers Ignore errors about pth or sharutils not being installed, these were included in the beta1 release but not installed by default. Upgrade from Kolab server 2.1 or before --------------------------------------- Instructions for upgrading from Kolab server 2.0 or 2.1 will be added in a future version of this document. Direct upgrade from Kolab1 is not supported. We suggest that you back up your IMAP store, install Kolab2 and manually recreate user accounts and then restore the IMAP data from the backup. Known problems and workarounds ------------------------------ - Your system (C library) has to support all languages you want to have available in the web admin interface and fbview. For most languages you have to use the non-UTF-8 and non-euro locales, i.e. de_DE, fr_FR, it_IT, nl_NL instead of e.g. de_DE@euro. For fbview some languages need a UTF-8 locale, e.g. ja_JP.UTF-8 for Japanese. See kolab/issue881 and kolab/issue1585 for details. - If login on https://yourserver.example.com/fbview and triggering free/busy regeneration does not work, try as user kolab: /kolab/bin/php -r 'imap_open("{localhost:143/notls}", "" ,"");' If it yields "Segmentation fault (core dumped)", then there probably is a conflict between a dynamically loaded libdb3 from your system and a statically linked libdb4 from the OpenpPKG php package. If it yields a "PHP Warning: ...", this part of the system works correctly. One reason for such a conflict could be the mere presence of /lib/libnss_db.so.*, which is installed on some distributions by default. On Debian systems it is contained in the package "libnss-db". If you really need this library, you could work around the loading of libdb3 by placing a symbolic link with the correct name in /kolab/lib, e.g.: ldd /lib/libnss_db.so.2 libnss_files.so.2 => /lib/tls/libnss_files.so.2 (0xb7f16000) ---> libdb3.so.3 => /usr/lib/libdb3.so.3 (0xb7e6b000) libc.so.6 => /lib/tls/libc.so.6 (0xb7d36000) /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x80000000) ln -s /dev/null /kolab/lib/libdb3.so.3 See kolab/issue1607 (need to replace gdbm for pfbcache, because of license clash gdbm vs php) for details. - /kolab/etc/kolab/kolab_bootstrap -b fails to start the temporary slapd on Linux 2.4 kernels if binaries compiled on Linux 2.6 (as provided on kolab.org) are used. See kolab/issue1795 for details. - Under some circumstance the Kolab server may not create or delete users or update the configuration after changes have been made in the web interface. This happens most often immediately after the bootstrap. In that case restart the kolabd: /kolab/bin/openpkg rc kolabd restart If user accounts are still not created or deleted, you can try removing the file /kolab/var/kolab/mailbox-uidcache.db and restarting kolabd. See kolab/issue1068 (Mailboxes are not created until kolabd restart) and kolab/issue1098 (Changes in the service tab are not accepted after bootstrap) for details. - If modifying or deleting of address book entries doesn't work, restarting openldap can help, see kolab/issue854 for details. - There is a report that the manager can only see users in the primary domain, see kolab/issue1485. We can't reproduce this problem, please tell us if you can. - Calendar folders for group/resource accounts can't be created for domains which were added after bootstrap, i.e. via the web admin interface. See kolab/issue1313 for details. - When deleting domains via the web admin interface, the corresponding LDAP data and IMAP spool stay on the server and have to be deleted manually. See kolab/issue1571 and kolab/issue1576 for details. $Id: README.1st,v 1.63 2007/10/19 17:17:19 thomas Exp $