Upgrade/Migrate trouble-free from OTRS 5 to OTRS/Znuny 6

Sadly the documentation of upgrading OTRS 5 to OTRS/Znuny 6 is not that quality that it is obviously and easy to handle. This HowTo is built on top of many issues faced on upgrading from OTRS 5 to Znuny 6. OTRS 6 and Znuny 6 are equivalent, since Znuny 6 is exactly OTRS 6, despite of logo changes and naming changes.
If you are a administrator of OTRS/Znuny and mostly maintaining the (web-)servers based on Linux or like recommended from our side on Ubuntu, you may face also the issues, that the major issues come from a unclear documentation of OTRS/Znuny. And it looks like the documentation was made by very experienced admins or developers TO very experienced Znuny admins or Znuny developers.

In this article you will find tools and paths how to ensure a clean migration from OTRS 5 to Znuny 6 under Ubuntu 20.04.
If you are on a different OS like CentOS and you want to switch to Ubuntu read How to migrate OTRS / Znuny from centOS to Ubuntu

How to get started?

The best way to start is to have a clone or a new instance of your current environment, there you can run the migration tests before doing on production.

You are on VMware, proxmox, Hyper-V or other virtualized environments?

If you have a virtual environment you may already be a very lucky admin. You can easily clone your instance based on snapshots and run your tests, without messing around with the production environment. Also nearly all other virtual environments have solutions like snapshots.

If you have a solution which is installed directly on hardware without a virtualizer, you can do also the same by cloning the server into a virtual environment. E.g. on VMware it is called VMware (vCenter) Converter, which is able to clone any operating system into a virtual environment. You could also use any desktop virtualizer like Virtual Box.

If you do not have these virtualization options it will get harder but still possible to solve. In this case you should restore your system from backup on a new system/hardware.

In any case DO NOT START your new machine without reading next chapter!

Highly critical steps before starting

After cloning or restoring from backup, you have a fully identical copy of production. This is great but also a root cause for many lost e-mails or tickets!

Your new environment is fetching also e-mails from pop3 or imap if you have configured the services accordingly. Means if you do not ensure, that the fetching is disabled your will run into a hell of a mess. The more messages you receive per hour, the bigger your pain will be.

In any case on virtual environments:
ensure on your newly cloned system that your network connectivity is disabled
This ensures that your new server is impossible to fetch or receive new messages from any mailbox at all.

In any case on physical hardware environments:
ensure the network cable is un-plugged
and if you run on PCs or laptops your tests, no network is available via alternative paths like WiFi or via mobile networks

After starting the new server you should disable all services which may cause you issues:

sudo service cron stop
sudo -u otrs /opt/otrs/bin/Cron.sh stop
sudo -u otrs /opt/otrs/bin/otrs.Daemon.pl stop
sudo service postfix stop
sudo service apache2 stop

Now you have a system which is cleanly stopped. Since we are paranoid on ensuring to avoid any possible risks on the mess, we do also

sudo update-rc.d cron disable
sudo update-rc.d postfix disable
sudo update-rc.d apache2 disable
reboot

Now check after the reboot, that cron, postfix and apache2 are disabled.

service apache2 status|grep "Active"

and you will get hopefully the status inactive (dead) like

Active: inactive (dead) since Thu 2022-02-17 20:52:50 CET; 1s ago

Do the same checks with

service cron status|grep "Active"
service postfix status|grep "Active"

If all services are inactive, you are fine to enable the network interface or to plug the network cable in.

Don’t be a fool, create a backup!

Do not go on without ensuring a backup of your data. There is a high probability of a migration failure.

Creating a snapshot as a backup

Create a clean snapshot. For the snapshots I recommend you to

sudo shutdown -h now

and after virtual machine is halted to create a clean snapshot.
For backup solutions ensure, that the backup is taking clean “snapshotted” database backups.

Create a backup with OTRS scripts

Alternatively create a backup with OTRS scripts. We recommend to do the paranoid double backup 😉
In this example the backup gets created in the folder /tmp/backup (missing folders are auto-created).
Of course you should use a folder, which will not be deleted on each reboot 😉

cd /opt/otrs
./scripts/backup.pl -d /tmp/backup

Doing the migration

First we ensure our required packages are installed

sudo apt install wget findutils git screen

The migration is separated into 3 steps.

Migration preparation

Now let us prepare the migration steps.

cd /opt
git clone https://github.com/itgovernanceportal/otrs-znuny-helpers.git
cd /opt/otrs-znuny-helpers/migrationHelpers/otrs5_2_znuny6

Now let us create a backup of your OTRS installation under /opt/otrs containing your OTRS configs and your OTRS filesystem data for the migration. Store the backup to /tmp:

./10_migrationPrepare-otrs2znuny.sh /opt/otrs /tmp

will return you something like

created backup file /tmp/2022-02-20-16-45-01-znuny-conf-backup.tar.gz

Now we have your configurations in a backup file

Starting the migration from OTRS to Znuny

Now we can start with the migration itself. First we ensure our required packages are installed

sudo apt install wget findutils screen

Now run the download znuny and integrate our prior backuped configuration files

cd /opt/otrs-znuny-helpers/migrationHelpers/otrs5_2_znuny6
sudo ./20_migrationFilesOnly-otrs2znuny.sh /tmp

okay we have now the required new files copied into /tmp/otrs

your new installation folder is located under /tmp/otrs

And we have prepared a clean and new Znuny installation folder. Now lets go to the last step, installing Znuny and running all needed migrations

Final migration step

You can verify the prior folder if your config files are added in folder /tmp/otrs. (of course the script shall ensure it 😉
You will need very probably this packages during the execution of the next script. So you shall install them before:

sudo apt install -y libcss-minifier-xs-perl libjavascript-minifier-xs-perl

Let run the command in a screen, so even if we loose connection to the system, we can see the progress

screen

Now we can give it a try to upgrade OTRS 5 to Znuny 6 with

cd /opt/otrs-znuny-helpers/migrationHelpers/otrs5_2_znuny6
sudo ./30_migrationZnuny-otrs2znuny.sh /tmp/otrs /opt/otrs

Do not wonder, the migration can run for hours, depending how big your database is. E.g. in the case of 10.000.000 tickets the migration can take 4-6h of execution time! You will see some output like this:

Step 41 of 44: Refresh configuration cache another time …
Step 42 of 44: Deploy ACLs …
Step 43 of 44: Deploy processes …
Step 44 of 44: Check invalid settings …

If you are lucky the migration went through without any issues. If not see the related articles, if some of your issues is already covered there.

Related articles

Avoid apache2 coredumps with Znuny
Avoid upgrade error character_set_database utf8
Fix unsafe ownership errors .gnupg in log
Upgrades of Znuny