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 😉
./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.
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:
Let run the command in a screen, so even if we loose connection to the system, we can see the progress
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.