Last modified 19 months ago

Migrating from Zentyal 2.0 to 2.2

This page contains instructions on how to migrate from a working Zentyal 2.0 server to Zentyal 2.2 (latest version). A tool has been developed to automatize the process, so you only need to run it and wait.

Before you start

  • Backup! You must make a backup of your system before starting. Migrations are complex processes that can fail at some point.
  • Check your Internet connectivity. Migration tool will need a working Internet connection to download new packages and upgrade old ones.
  • We strongly recommend you, if possible, to try this first on a test machine (a VM for example) restoring the configuration backup of your production server, or even better if you can clone an image of the whole disk. If that's not possible and you decide to directly migrate your production server, make sure you have a way to restore it.
  • First of all, in case your Zentyal 2.0 is not already up-to-date, the migration tool will upgrade your system to the latest 2.0 packages available in the community repositories, this is necessary in order to have a successful migration. After that, you will be able to check that everything is OK before proceeding with the migration.

Migration tool

tar xvzf zentyal-migrate-2.0-to-2.2.tar.gz
cd zentyal-migrate-2.0-to-2.2
sudo ./migrate.sh

Migration tool will ask for confirmation before starting and then the following steps will be taken. This is an automatic process, but you can check that everything is correct:

  • Replace old 2.0 Zentyal PPA with the new 2.2 one in /etc/apt/sources.list
  • Get the list for your installed packages
  • Save current configuration (redis database)
  • Remove 2.0 packages (remove only, not purge)
  • Update, upgrade everything from the new PPA and install Zentyal 2.2 packages
  • Stop every Zentyal 2.0 module
  • Migration:
    • Copy 2.0 data (/var/lib/ebox) to new 2.2 dir (/var/lib/zentyal)
    • Import previously saved configuration (redis)
    • Upgrade objects schema to new format
    • Upgrade LDAP configuration (if present)
    • Create new core SQL tables
    • Adapt bandwidth throttling rules to the new unit (KBytes instead of Bytes)
  • Purge 2.0 packages
  • Start Zentyal 2.2 modules

Known issues

Third-party or unofficial modules

  • If you have any non-official modules installed, you have to purge them before starting the migration process.
  • You'll be able to install them again after the migration process is completed.

Zarafa 7

  • The migration from Zarafa 6 to Zarafa 7 is not trivial. Furthermore, it might be a long process and present even a risk of data loss if something fails.
  • This tool does not migrate to Zarafa 7, so if you need to use this version, you will have to migrate manually. However, take into account that Zentyal 2.2 is also compatible with Zarafa 6, so perhaps this migration is not necessary.

User Corner

  • As this functionality comes now in a new zentyal-usercorner package (it was in the users package before), you need to install and enable it manually if you want to use it.
  • If you had your usercorner listening on a port different than the default 8888, don't forget to change it.

Custom configuration and stubs

  • If you have any custom configurations (/etc/ebox/*.conf files) you will need to migrate them by hand. New files are located at /etc/zentyal/. We recommend you to manually merge your changes in the new files instead of just replacing them as some packages have included new configuration keys or may contain other changes.
  • The same as above apply to stubs (/etc/ebox/stubs), the new path for them is /etc/zentyal/stubs, and some of the original templates (at /usr/share/zentyal/stubs) have changed, so you should copy the new templates you want to modify and re-apply your changes, if you just copy your customized stubs from /etc/ebox you might break some stuff.

New firewall services

  • Some services in modules like Mail and Groupware have changed (or more specifically, they have been renamed and reorganized), so it's very likely you'll have some duplicated firewall rules after the migration (with the old and the new ones), this shouldn't be a problem in general, but maybe you can have a look at your rules and clean them a bit.