There are two different scenarios to obtain a newer OTRS version:
-
Patch level update: you are using OTRS 8 or OTRS and you want to have the latest OTRS version.
-
Major upgrade: you are using an OTRS 7 and you want to have the latest OTRS version.
- Updating from an earlier version of OTRS 8 or OTRS
-
You can update directly from any previous patch level release to the latest available patch level release.
Note
It is highly recommended to perform a test update on a separate testing machine first.
- Upgrading from OTRS 7
-
OTRS can be upgraded from any OTRS 7 patch level release to the latest available OTRS patch level release.
Note
OTRS is upgraded by the Customer Solutions Team. Please contact us via support@otrs.com or in the OTRS Portal.
- Upgrading from OTRS 6 or earlier
-
OTRS cannot be upgraded from OTRS 6 or earlier directly to OTRS. Upgrades to all available major versions have to be made sequentially instead. For example, if you come from OTRS 5, OTRS has to be upgraded to OTRS 6 first, then to OTRS 7 and finally to OTRS.
Note
OTRS is upgraded by the Customer Solutions Team. Please contact us via support@otrs.com or in the OTRS Portal.
Step 1: Stop All Relevant Services and the OTRS Daemon
Please make sure there are no more running services or cron jobs that try to access OTRS. This will depend on your service configuration and OTRS version.
The following systemctl
commands are only examples and may differ on the target system if it uses different mailer or web server.
root> systemctl stop postfix
root> systemctl stop apache2
root> systemctl stop otrs-daemon
root> systemctl stop otrs-webserver
Step 2: Backup Files and Database
Create a backup of the following files and folders:
-
Kernel/Config.pm
-
Kernel/WebApp.conf
-
var/*
-
files which are not part of the official release package but added manually to the system (custom language files, logos, CSS style sheets, XML configuration, etc.)
-
as well as the database
Note
It is recommended to have an up-to-date list of files which are added manually or changed in the system.
Warning
Don’t proceed without a complete backup of your system. Use the Backup script for this.
Step 3: Install the New Release
You can obtain either otrs-patchlevel-update-x.y.z.tar.gz
or otrs-patchlevel-update-x.y.z.tar.bz2
. Unpack the source archive (for example, using tar
) into the directory /opt
, and create a symbolic link /opt/otrs
that points to /opt/otrs-x.y.z
.
Do not forget to replace the version numbers!
Note
Package bzip2
is not installed in some systems by default. Make sure, that bzip2
is installed before unpacking otrs-patchlevel-update-x.y.z.tar.bz2
.
Unpack command for otrs-patchlevel-update-x.y.z.tar.gz
:
root> tar -xzf otrs-patchlevel-update-x.y.z.tar.gz -C /opt
Unpack command for otrs-patchlevel-update-x.y.z.tar.bz2
:
root> tar -xjf otrs-patchlevel-update-x.y.z.tar.bz2 -C /opt
It is recommended to create a symbolic link named /opt/otrs
that always points to the latest OTRS version. Using symbolic link makes it easier to manage the OTRS updates, because you can leave the directory of the previous version untouched, only the symbolic link needs to be changed.
Execute this command to create a symbolic link:
root> ln -fns /opt/otrs-x.y.z /opt/otrs
If you need to revert the update, you can change the target of the symbolic link back if you did not run the migration script already in step 4. If the migration script was executed, the database needs to be restored from the backup in case of a rollback.
Restore Old Configuration Files
Copy the following files from the backup created in step 2 into the same destination:
-
Kernel/Config.pm
-
Kernel/WebApp.conf
-
files which are not part of the official release package but added manually to the system (custom language files, logos, CSS style sheets, XML configuration, etc.)
Warning
Copy only custom files added by you manually, not the files shipped with OTRS. Overwriting the default files may lead to issues after the update.
Check for hidden files with the ls -a
command like .fetchmailrc
, .mailfilter
, .procmailrc
in the previous OTRS directory. If these files exist without .dist
extension, copy them to the OTRS folder using the cp -p
command to preserve the permissions.
Restore Article Data
If you configured OTRS to store article data in the file system you have to restore the article
folder to /opt/otrs/var/
or the folder specified in the system configuration.
Restore Already Installed Default Statistics
If you have additional packages with default statistics you have to restore the stats XML files with the suffix *.installed
to /opt/otrs/var/stats
.
root> cd OTRS-BACKUP/var/stats
root> cp *.installed /opt/otrs/var/stats
Set File Permissions
Please execute the following command to set the file and directory permissions for OTRS. It will try to detect the correct user and group settings needed for your setup.
root> /opt/otrs/bin/otrs.SetPermissions.pl
Install Required Programs and Perl Modules
Use the following script to get an overview of all installed and required CPAN modules and other external dependencies.
root> perl /opt/otrs/bin/otrs.CheckEnvironment.pl
Checking for Perl Modules:
o Archive::Tar.....................ok (v1.90)
o Archive::Zip.....................ok (v1.37)
o Crypt::Eksblowfish::Bcrypt.......ok (v0.009)
...
Note
Please note that OTRS requires a working Perl installation with all core modules such as the module version
. These modules are not explicitly checked by the script. You may need to install a perl-core
package on some systems like RHEL that do not install the Perl core packages by default.
To install the required and optional packages, you can use either CPAN or the package manager of your Linux distribution.
Execute this command to get an install command to install the missing dependencies:
root> /opt/otrs/bin/otrs.CheckEnvironment.pl --list
OTRS requires a supported stable version of Node.js to be installed. Please refer to the Node.js installation instructions.
Step 4: Run the Migration Script
The migration script will perform many checks on your system and give you advice on how to install missing Perl modules etc., if that is required. If all checks succeeded, the necessary migration steps will be performed.
Note
Please also run this script in case of patch level updates.
Run the migration script:
otrs> /opt/otrs/scripts/DBUpdate.pl
Warning
Do not continue the upgrading process if this script did not work properly for you. Otherwise malfunction or data loss may occur.
The migration script also checks if ACLs and system configuration settings are correct. In case of an invalid system configuration setting, script will offer you an opportunity to fix it by choosing from a list of possible values. In case the script runs in a non-interactive mode, it will try to automatically fix invalid settings. If this fails, you will be asked to manually update the setting after the migration.
If there are outdated ACLs, the system will not be able to fix them automatically, and they need to be corrected by the administrator. Please see the last step for manual changes for details.
Step 5: Update Installed Packages
Note
Packages for OTRS 7 are not compatible with OTRS and have to be upgraded.
You can use the command below to update all installed packages. This works for all packages that are available from online repositories. You can update other packages later via the package manager (this requires a running OTRS daemon).
otrs> /opt/otrs/bin/otrs.Console.pl Admin::Package::UpgradeAll
otrs> /opt/otrs/bin/otrs.Console.pl Admin::Package::ReinstallAll
Step 6: Start your Services
Now the services can be started. This will depend on your service configuration, here is an example:
root> systemctl start postfix
root> systemctl start apache2
Note
The OTRS daemon is required for correct operation of OTRS such as sending emails. Please activate it as described in the next step.
Step 7: Start the OTRS Daemon and Web Server
The OTRS web application will be built for the new version upon the first start. This may take a while and causes a timeout if started with the systemd commands. To prevent this, start the OTRS web server once as otrs
user to build the OTRS web application and stop it afterwards. Then it can be started with the systemd commands as root
user.
otrs> ~/bin/otrs.WebServer.pl --deploy-assets
otrs> ~/bin/otrs.WebServer.pl --stop
OTRS comes with example systemd configuration files that can be used to make sure that the OTRS daemon and web server are started automatically after the system starts.
root> systemctl start otrs-daemon
root> systemctl start otrs-webserver
Now you can log into your system.
Step 8: Manual Migration Tasks and Changes
Warning
Read this step carefully and apply the actions only if they are relevant to your system.
The system maintenance feature has been dropped.
With OTRS 8 a new default password policy for agents and customer users is in effect. The password policy rules can be changed in the system configuration (AgentPersonalPreference###Password
and CustomerPersonalPreference###Password
).
Password Policy Rule |
Default |
---|---|
|
8 |
|
Yes |
|
Yes |
|
10 |
|
30 days |
|
5 days |
|
Yes |
It is also possible to add some password policy exceptions for agents or customer users. Please check the following configuration options for details:
PasswordPolicy::ExceptAgentPasswordComplexity
PasswordPolicy::ExceptAgentPasswordTTL
PasswordPolicy::ExceptAgentPasswordHistory
PasswordPolicy::ExceptAgentPasswordChangeAfterFirstLogin
PasswordPolicy::ExceptCustomerPasswordComplexity
PasswordPolicy::ExceptCustomerPasswordTTL
PasswordPolicy::ExceptCustomerPasswordHistory
PasswordPolicy::ExceptCustomerPasswordChangeAfterFirstLogin
Since the old agent interface screens are no longer present, some ACLs need to be corrected manually by the administrator. The migration script already informed you if this is the case.
Affected ACLs are those that refer to a non-existing agent interface screen in their Action
setting. This front end Action
rule needs to be replaced with a corresponding Endpoint
rule. A table with possible mapping is included below.
Action |
Endpoint |
---|---|
|
No replacement (feature dropped) |
|
No replacement (feature dropped) |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
No replacement (feature dropped) |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
No replacement (feature dropped) |
|
|
|
|
Upgrade Elasticsearch
Upgrade your Elasticsearch installation if newer version is available. For more information read the Upgrade Elasticsearch chapter in the official documentation.
See also
Please refer to the Hardware and Software Requirements chapter for the supported versions.
Additionally, OTRS requires plugins to be installed into Elasticsearch. When a newer Elasticsearch version is installed, the plugins have to be removed and installed again.
In Elasticsearch 7:
root> /usr/share/elasticsearch/bin/elasticsearch-plugin remove analysis-icu
root> /usr/share/elasticsearch/bin/elasticsearch-plugin remove ingest-attachment
root> /usr/share/elasticsearch/bin/elasticsearch-plugin install --batch ingest-attachment
root> /usr/share/elasticsearch/bin/elasticsearch-plugin install --batch analysis-icu
In Elasticsearch 8:
root> /usr/share/elasticsearch/bin/elasticsearch-plugin remove analysis-icu
root> /usr/share/elasticsearch/bin/elasticsearch-plugin remove ingest-attachment
root> /usr/share/elasticsearch/bin/elasticsearch-plugin install --batch analysis-icu
Note
Restart Elasticsearch afterwards, or indexes will not be built.
To verify the Elasticsearch installation, you can use the following command:
otrs> /opt/otrs/bin/otrs.Console.pl Maint::DocumentSearch::Check
Trying to connect to cluster...
Connection successful.
One of the Elasticsearch options is explicitly interesting for OTRS, which is the maximum amount of open scroll contexts, that has a value of 500.
In normal situations, this value should not be reached, but we recommend to set this value back to 1000 with the following option, that has to be added to the configuration file elasticsearch.yml
:
search.max_open_scroll_context: 1000
Recommendation: Convert Your MySQL Database
OTRS 7 and previous versions only supported the utf8
MySQL database character set, which is not able to store all Unicode characters. Since OTRS 8 the utf8mb4
character set is also supported, which removes this limitation. It is recommended to convert your database at your convenience with the built-in migration script.
Running the migration script without options will display only if something needs to be converted.
otrs> /opt/otrs/bin/otrs.Console.pl Maint::Database::MySQL::UTF8MB4Migration
The following tasks need to be done:
- 1 table(s) need to be converted to 'DYNAMIC' row format
- the database needs to be converted to 'utf8mb4'
- 411 column(s) need to be converted to 'utf8mb4'
- 156 table(s) need to be converted to 'utf8mb4'
Use the --force
option to perform the actual migration.
otrs> /opt/otrs/bin/otrs.Console.pl Maint::Database::MySQL::UTF8MB4Migration --force
...
After the migration is done, you need to add a new switch to file Kernel/Config.pm
to activate the utf8mb4
support.
$Self->{'Database::mysql::utf8mb4'} = 1;
Note
OTRS can be operated in the utf8
character set, without this migration. But future versions will only support the utf8mb4
character set. Therefore this migration needs to be done at some point.
Allow Program Safe to Run
External programs to be run by OTRS are blocked by default due to security reasons. You have to add the program to the allow list as described in the Allow Program Safe to Run chapter of the administration manual.