4. Upgrading¶
4.1. Preparing¶
Before upgrading to a new version of KC, it is recommended to make a backup of the database and the configuration files, especially when upgrading is done by skipping some minor versions.
First stop the MTA server running on your server. Should there be any problems during the upgrade no e-mail will get lost, as mails would be queued for re-delivery until the MTA is back available. In case of postfix, run:
/etc/init.d/postfix stop
Now stop the running services, so the database is not in use anymore:
service kopano-spooler stop
service kopano-server stop
And the optional services too, if they were started:
service kopano-dagent stop
service kopano-gateway stop
service kopano-ical stop
service kopano-search stop
service kopano-monitor stop
4.1.1. Database Attachments¶
With Kopano it is possible (and advised) to store all attachments outside the MySQL database. The split architecture of attachments was made to provide a more efficient MySQL caching system and get smaller, more manageable databases.
4.1.1.1. Configuring storage method¶
The attachment storage can be configured in the server.cfg file via the option attachment_storage. When using the install script the default value is set to files, so the attachments are stored in the filesystem per default. To store the attachment inside of the database, set this option to database. Make sure that there is enough space on the partition wherever your attachments are configured (whether in database or files).
Important
We do not recommend the usage of the “database” attachment store method. Using database driver is stable, but will make your database, depending on the amount of attachments harder to manage and at the same time the efficiency of mysql caching will drastically be lowered, resulting in lower performance of the overall system. For production environments, we only recommend to use either ‘files’ or ‘s3’ attachment storage.
4.1.1.2. Migrating database attachments to files¶
Existing installations that already have the attachments in the database have the possibility to migrated to the file storage. In the /usr/share/doc/kopano directory there is a script available called db-convert-attachments-to-files. This perl script will directly login to MySQL and dump the attachments to the specified directory. You have the run the script with the following options:
perl db-convert-attachments-to-files mysqluser mysqlpassword mysqldatabase \
path_to_filesystem [delete]
The last delete option is optional. This option will delete the attachments from the database. The script can ran multiple times after each other, without having the attachments duplicated. To enable this settings you have to restart your Kopano-server one time with the option –ignore-attachment-storage-conflict.
kopano-server --ignore-attachment-storage-conflict
4.1.1.3. Storage layout¶
The attachments are not all stored in a single directory, but spread over 200 directories. Below the specified attachment_path there are 10 directories (0 - 9). Each directory has 20 subdirectories (0 - 19). Through the attachment id in the database, the exact location can be calculated via a fast algorithm. The attachment is in one of the directories with the id as filename. The stored attachment is the same as the attachment you will see in your email. With the file command you can see the probable type of the attachment.
4.2. Creating backups¶
Now create backups of the database and configuration files. Make a copy of the /etc/kopano directory, which contains the configuration files.
cp -r /etc/kopano /etc/kopano.bck
As Kopano stores attachments of items on the filesystem, make a copy of the attachment directory.
cp -r /var/lib/kopano/attachments /var/lib/kopano/attachments.bck
To backup the MySQL database a mysqldump can be executed:
mysqldump -p --single-transaction --routines kopano > kopano.sql
or the complete mysql data directory can be copied:
/etc/init.d/mysqld stop
cp -r /var/lib/mysql /var/lib/mysql.bck
cp -r /etc/my.cnf /etc/my.cnf.bck
Note
The paths could be different when default configuration is changed.
4.2.1. Consistent backups¶
Creating consistent backups between the database and the filesystem is possible by for example using snapshotting methods. There is no direct necessity to backup all data simultaneously, it is recommended to backup database first (with –single-transaction or any alike snapshotting method) and to backup attachments afterwards. This makes sure that in the worst case there are minor extra attachments instead of any missing.
4.3. KC 8 dependencies¶
After the backup is successfully created, the Kopano packages can be upgraded. There are some new dependencies that need to be resolved before the packages can be updated.
Table 3.1. KC 8 dependencies
| Distribution | Dependencies |
|---|---|
| Debian 7 | libboost-filesystem1.49.0 [1], libboost-system1.49.0 [1], libicu48, w3m |
| Debian 8 | libboost-filesystem1.55.0 [1], libboost-system1.55.0 [1], libicu52, w3m |
| RHEL6 | boost-filesystem [1], boost-system [1], libicu, w3m |
| RHEL7 | boost-filesystem [1], boost-system [1], libicu, w3m |
| SLES11 | libicu, w3m |
| SLES12 | libicu, w3m |
| Ubuntu 12.04 | libboost-filesystem1.46.1 [1], libboost-system1.46.1 [1], libicu48, w3m |
| Ubuntu 14.04 | libboost-filesystem1.54.1 [1], libboost-system1.54.1 [1], libicu52, w3m |
| Ubuntu 16.04 | libboost-filesystem1.58.1 [1], libboost-system1.58.1 [1], libicu55, w3m |
| [1] | (1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14) Not needed anymore for releases after 8.3.0. |
4.4. Performing the Upgrade on RPM based distributions¶
After the backups have been created the upgrade can be performed similarly to how a package would be installed manually. For RPM based installations use the following command:
rpm -Uvh <package name>.rpm
Note
Not necessarily all packages are required in your environment. Especially packages for clustering for example are required only for HA environments and are not required to be installed. We recommend only the installation/upgrade of packages that are really used.
After the new packages are installed, the example configuration files found in the /usr/share/doc/kopano/example-config directory can be checked for new configuration options. The new changes can also be found in the section Release Notes.
4.5. Performing the Upgrade on Debian based distributions¶
Unpack the tarball:
tar zxvf core-8.x.x-<revision>-<distribution>-<arch>.tar.gz
Install the new libvmime 0.9 that comes with Kopano:
dpkg -Bi libvmime0*
Install the python-mapi packages that comes with Kopano:
dpkg -i python-mapi*
For Debian based installations run the following command to upgrade the KC installation:
dpkg -Bi <package name>
Depending on the set of packages you may have installed, this command may end with errors on the “kopano” packages. Due to the big split and renaming of packages some conflicts are not directly resolvable by “dpkg”. If you receive any errors during the upgrade of these packages, a second try installing these packages using:
dpkg -i <package name>
or run the following command:
apt-get install -f
which should resolve everything properly.
When prompted about changed kopano configuration files it depends greatly on you current situation what the best option is.
After the new packages are installed, the example configuration files found in the /usr/share/doc/kopano/example-config directory can be checked for new configuration options. The new changes can also be found in the Kopano Changelog document.
For most people, upgrading is as easy as upgrading the packages. But before you restart the services you should manually update your configuration files and optionally make some changes to your LDAP (or Active Directory) server. Debian packages will automatically restart services. Some services will not correctly restart because of configuration options that change. You might see errors on your screen, but this is normal, and not destructive. All your data will still be present. The config files have changed quite a bit. Use the diff command to find the differences between your version of the config file and the version shipped with KC in /usr/share/doc/kopano/example-config. Most important are the server.cfg and ldap.cfg (in case you use LDAP or Active Directory) files.
To protect the server from deleting users a safe mode option is available in the server.cfg. Enabling this option will disable all delete and create actions of users and groups.
Add the following option in the /etc/kopano/server.cfg to enable safe mode:
user_safe_mode = yes
Check the server logfile after starting the Kopano Server for detection of user changes. If no users are recreated or deleted the configuration file is correct and user_safe_mode can safely be disabled.
Important
It’s strongly advised only to use the safe_mode during upgrade testing. When the upgrade has successfully completed, the safe_mode should be disabled. Running a production system with safe_mode enabled can result in performance issues and unexpected behaviour (like not creating stores for new users).
Note
When using LDAP or Active Directory (ADS), set applicable shared stores to ‘room’ or ‘equipment’ resource types to extend the addressbook. (for ADS a new plugin is required, for LDAP there is a new kopano.schema file required)
If you list the users with “kopano-admin -l” and you get an “Object not found” error, then please do an ldapsearch on the commandline with the ldap_search_base as search base. Most likely you will get an error “Size limit exceeded” with the ldapsearch.
If you are using ADS and the ldapsearch returns a “Size limit exeeded”, please increase the “MaxPageSize” policy. This value is the maximum number of results that ADS is allowed to return to a LDAP query.
When finished the migration, and before running in production again, we recommend the following checklist:
- Check if all users are there
- Check if all groups are there
- Check if companies are correct (if running multi company)
- Check if multi-server is working correctly (if running a multi server setup)
- Check if group memberships are correct
- Check if send-as permissions are correct
- Check if contacts are there
- Check if addresslists are working
- Check if dynamic-groups are working
4.6. Finalizing the upgrade¶
After the new configuration options have been checked, the services can be started again:
service kopano-server start
service kopano-spooler start
The optional services can also be started again:
service kopano-dagent start
service kopano-gateway start
service kopano-ical start
service kopano-search start
service kopano-monitor start
Important
Run kopano-search-upgrade-findroots.py if you upgrade from a Kopano Core version lower then 8.2.0. Without running it searching in shared mailboxes is not available.
Since upgrades usually include a changed php-mapi extension, the webserver has to be restarted as well:
service apache2 restart
or
service httpd restart
KC has a new improved IMAP/POP3 gateway. The new gateway offers better compatibility and higher performance by using additional information which is stored in the database and in the Kopano attachment directory. As this addition information will use more diskspace and is only used when users are connecting over IMAP, the IMAP/POP3 features are by default disabled.
When users should have access to IMAP or POP3 this features has to manually enabled. Read more about enabling/disabling features in Kopano Feature management.
To generate for all existing message an optimized IMAP version, the optimize-imap.py script is available. By executing this script for every existing email the envelope structure and body structure and store these entries in the database. Additionally the whole RFC822 message file is generated and stored gzip compressed in the attachment directory.
The script will only generate this data for the users who have IMAP and POP3 enabled.
To execute the script use the following command:
python /usr/share/doc/kopano-gateway/optimize-imap.py
To optimize one or more specific users use the following command: python /usr/share/doc/kopano-gateway/optimize-imap.py <user1> <user2> <user3>
Note
For new emails received on Kopano Core the optimized IMAP data is stored automatically when users have IMAP or POP3 enabled.