Upgrading OTRS from 4 to 5

These instructions are for people upgrading OTRS from 4 to 5 or from a 5 to a later patchlevel release 5 and applies both for RPM and source code (tarball) upgrades.

If you are running a lower version of OTRS you have to follow the upgrade path to 4 first (1.1->1.2->1.3->2.0->2.1->2.2->2.3->2.4->3.0->3.1->3.2->3.3->4)! You need to perform a full upgrade to every version in between, including database changes and the upgrading Perl script.

Please note that if you upgrade from OTRS 2.2 or earlier, you have to take an extra step.

Within a single minor version you can skip patch level releases if you want to upgrade. For instance you can upgrade directly from OTRS 5 patchlevel 2 to version 5 patchlevel 6. If you need to do such a "patch level upgrade", you should skip steps 6, 10, 11, 14, 17 and 18.

It is highly recommended to perform a test update on a separate testing machine first.

Step 1: Stop all relevant services

Please make sure there are no more running services or cron jobs that try to access OTRS. This will depend on your service configuration, here is an example:

shell> /etc/init.d/cron stop
shell> /etc/init.d/postfix stop
shell> /etc/init.d/apache stop

Stop OTRS cron jobs and the scheduler or daemon (in this order) depending on the OTRS version you are updating from:

shell> cd /opt/otrs/
shell> bin/Cron.sh stop
shell> bin/otrs.Scheduler.pl -a stop


shell> cd /opt/otrs/
shell> bin/Cron.sh stop
shell> bin/otrs.Daemon.pl stop

Step 2: Backup everything below /opt/otrs/

  • Kernel/Config.pm

  • Kernel/Config/GenericAgent.pm (only for reference, this file is not needed any more)

  • Kernel/Config/Files/ZZZAuto.pm

  • var/*

  • as well as the database

Step 3: Make sure that you have backed up everything ;-)

Step 4: Install the new release (tar or RPM)

Step 4.1: With the tarball:

shell> cd /opt
shell> mv otrs otrs-old
shell> tar -xzf otrs-x.x.x.tar.gz
shell> mv otrs-x.x.x otrs
Restore old configuration files

  • Kernel/Config.pm

  • Kernel/Config/Files/ZZZAuto.pm

Restore TicketCounter.log

In order to let OTRS continue with the correct ticket number, restore the TicketCounter.log to /opt/otrs/var/log/. This is especially important if you use incremental ticketnumbers.

Restore article data

If you configured OTRS to store article data in the filesystem you have to restore the article folder to /opt/otrs/var/ or the folder specified in the SysConfig.

Set file permissions

Please execute

shell> cd /opt/otrs/
shell> bin/otrs.SetPermissions.pl

with the permissions needed for your system setup. For example:

  • Web server which runs as the OTRS user:

    shell> bin/otrs.SetPermissions.pl --web-group=otrs

  • Webserver with wwwrun user (e. g. SUSE):

    shell> bin/otrs.SetPermissions.pl --web-group=wwwrun

  • Webserver with apache user (e. g. Red Hat, CentOS):

    shell> bin/otrs.SetPermissions.pl --web-group=apache

  • Webserver with www-data user (e. g. Debian, Ubuntu):

    shell> bin/otrs.SetPermissions.pl --web-group=www-data

Step 4.2: With the RPM:

shell> rpm -Uvh otrs-x.x.x.-01.rpm

In this case the RPM update automatically restores the old configuration files and sets file permissions.

Step 5: Check needed Perl modules

Verify that all needed Perl modules are installed on your system and install any modules that might be missing.

shell> /opt/otrs/bin/otrs.CheckModules.pl

Step 6: Apply the database changes

Step 6.1: Database schema update



Note: new tables created in the MySQL UPGRADING process will be created with the default table storage engine set in your MySQL server. In MySQL 5.5 the new default type is InnoDB. If existing tables, e.g. "users", have the table storage engine e.g. MyISAM, then an error will be displayed when creating the foreign key constraints. In this case we recommend to switch all tables to InnoDB with the console command bin/otrs.Console.pl Maint::Database::MySQL::InnoDBMigration.

Any problems with regards to the storage engine will be reported by the bin/otrs.Console.pl Maint::Database::Check command, so please run it to check for possible issues.

shell> cd /opt/otrs/
shell> cat scripts/DBUpdate-to-5.mysql.sql | mysql -p -f -u root otrs
shell> bin/otrs.Console.pl Maint::Database::Check


shell> cd /opt/otrs/
shell> cat scripts/DBUpdate-to-5.postgresql.sql | psql --set ON_ERROR_STOP=on --single-transaction otrs otrs

Step 6.2: Database migration script

Run the migration script (as user otrs, NOT as root):

shell> scripts/DBUpdate-to-5.pl

Do not continue the upgrading process if this script did not work properly for you. Otherwise data loss may occur.

Step 7: Refresh the configuration cache and delete caches

Please run (as user otrs, not as root):

shell> cd /opt/otrs/
shell> bin/otrs.Console.pl Maint::Config::Rebuild
shell> bin/otrs.Console.pl Maint::Cache::Delete

Step 8: Restart your services

e. g. (depends on used services):

shell> /etc/init.d/apache start
shell> /etc/init.d/postfix start
shell> /etc/init.d/cron start

Now you can log into your system.

Step 9: Check installed packages


The OTRS packages of 4 are NOT compatible with OTRS 5, so you have to perform a package upgrade!

The following packages are automatically uninstalled after the upgrade process (if they where installed before):

  • OTRSGenericInterfaceMappingXSLT

Step 10: Configure NodeIDs (only for multi-frontend clustered setups)


This step is only needed if you have a clustered setup with several frontend machines.

From OTRS 5 on, every frontend server needs to have its own unique NodeID. This defaults to 1 and thus does not need to be configured for single-frontend setups. If you have more than one machine, each machine needs to have this value set to a unique value between 1 and 999. This configuration needs to be done in the file Kernel/Config.pm:

$Self->{'NodeID'} =  '2';   # assign a unique value for every frontend server

Step 11: Check follow-up detection configuration

The follow-up detection settings were reorganized. Now OTRS searches by default in email subject and references to detect follow-ups. Please check in AdminSysConfig Ticket -> Core::PostMaster if you need to make any changes to the follow-up detection configuration (for example to search in body, attachments or raw email content).

Step 12: Start the OTRS Daemon

The new OTRS daemon is responsible for handling any asynchronous and recurring tasks in OTRS. What has been in cron file definitions previously is now handled by the OTRS daemon, which is now required to operate OTRS. The daemon also handles all GenericAgent jobs and must be started from the otrs user.

shell> /opt/otrs/bin/otrs.Daemon.pl start

Step 13: Update and activate cron jobs

There are two default OTRS cron files in /opt/otrs/var/cron/*.dist, and their purpose is to make sure that the OTRS Daemon is running. They need to be activated by copying them without the ".dist" filename extension.

shell> cd /opt/otrs/var/cron
shell> for foo in *.dist; do cp $foo `basename $foo .dist`; done

To schedule these cron jobs on your system, you can use the script Cron.sh with the otrs user.

shell> /opt/otrs/bin/Cron.sh start

Please note that if you had any custom cron jobs, you should consider moving them to SysConfig (Daemon -> Daemon::SchedulerCronTaskManager::Task) to have them executed by the OTRS daemon as well. You might also need to adapt your custom scripts, because now most OTRS commands are managed by bin/otrs.Console.pl instead of single scripts.


The console command Dev::Code::Generate::ConsoleCommand can help to create new console commands for your custom scripts. This command creates a template where the script logic and its parameters can be adapted.

Step 14: Review your ticket notifications

With OTRS 5 ticket notifications are configured differently than in previous versions. They are now part of the "Event Notifications" that were previously available as well (now called just "Ticket Notifications"). Your existing ticket notifications have been migrated into the list of ticket notifications, but deactivated. You have also received the new default ticket notifications, active by default.

In case you did not modify the old ticket notifications you don't have to do anything. If you have made local modifications or translations, you have two choices: a) you can migrate your modifications to the new ticket notifications (recommended) or b) you can deactivate the new notifications and activate the old notifications again.

Please also review the escalation notification recipient settings and see if they match with your expectations (agents who have the ticket in one of their custom queues vs. all agents with read permissions). This was configured via a setting in the file Kernel/Config/GenericAgent.pm (now obsolete) previously and can now be controlled via the GUI for each notification separately.

Step 15: Update system registration (optional)

If the system is already registered with OTRS Group, it is strongly recommended to update the registration information at this time. This will update the registered version of the system (among other changes) in the OTRS Group records, in order to get much accurate information from the cloud services.

If you don't update the registration information manually, it will be done automatically on a regular basis, but this could happen some hours or days after. During this period it might be possible to get wrong information from cloud services like OTRS Business Solution™ updates.

shell> cd /opt/otrs/
shell> bin/otrs.Console.pl Maint::Registration::UpdateSend --force
shell> bin/otrs.Console.pl Maint::Cache::Delete

Step 16: Migrate custom Perl based GenericAgent jobs (optional)

This is only relevant if you had any custom GenericAgent jobs in Perl OTRS 4 configuration files such as Kernel/Config/GenericAgent.pm that cannot be handled with the regular ticket notifications. Such jobs now need to be registered as OTRS Daemon cron tasks in the SysConfig (Daemon -> Daemon::SchedulerCronTaskManager::Task), in order to be executed on a regular basis.

There are 5 settings in the SysConfig prepared for this purpose (Daemon::SchedulerCronTaskManager::Task###GenericAgentFile1 to Daemon::SchedulerCronTaskManager::Task###GenericAgentFile5). If more settings are needed they can be added in a custom SysConfig setting file.

Please replace "<ModuleName>" with the file that contains the custom GenericAgent jobs configuration, e.g. Kernel::Config::GenericAgent for the file: Kernel/Config/GenericAgent.pm, set the schedule to match the periodicity as it was executed before, mark the setting as active and save the changes.


To get more information about other parameters that can be used while running the GenericAgent jobs, please execute:

shell> bin/otrs.Console.pl Maint::GenericAgent::Run --help

Step 17: Setup bash autocompletion (optional)

All regular OTRS command line operations now happen via the OTRS Console interface bin/otrs.Console.pl. This provides an auto completion for the bash shell which makes finding the right command and options much easier.

You can activate the bash autocompletion by installing the package bash-completion. It will automatically detect and load the file /opt/otrs/.bash_completion for the otrs user.

After restarting your shell, you can just type bin/otrs.Console.pl followed by TAB, and it will list all available commands. If you type a few characters of the command name, TAB will show all matching commands. After typing a complete command, all possible options and arguments will be shown by pressing TAB.

Step 18: Review ticket action screen configurations (optional)

Some ticket action screens like "Note" had default subjects in OTRS 4 (configurable via SysConfig, Ticket::Frontend::AgentTicketNote###Subject in this case). These default subjects have been removed to reduce the amount of potentially redundant/meaningless data. You might want to re-add them if they are mandatory for you.

Step 19: Review Ticket Event Module Configurations

Because of a bugfix in OTRS 5s, configuration names for a few ticket event modules had to be changed. Any possible customizations need to be re-applied. Please review your settings in SysConfig -> Ticket -> Core::Ticket and check all settings that start with Ticket::EventModulePost to see if your custiomizations have to be re-applied. This could be the case if you had activated and configured the event handler to save customer data in ticket dynamic fields, for example.

Step 20: Well done!