Chapter 2. Installation

Table of Contents

The Simple Way - Installation of Pre-Built Packages
Installing the RPM on a SUSE Linux server
Preparing the database for OTRS
Installing OTRS
Installation of additional perl modules
Installing OTRS on a Red Hat Enterprise Linux or CentOS system
Preparation: Disable SELinux
Preparing the database for OTRS
Installing OTRS
Installation of additional perl modules
Installation of Oracle database driver on Red Hat / CentOS
Installing OTRS on a Debian or Ubuntu system
Installation From Source (Linux, Unix)
Using the Web Installer
OTRS on Windows
How to migrate existing Windows installations to Linux
Introduction and preparation
Get OTRSCloneDB script to clone databases
Enable remote access for the PostgreSQL database of target system
Stop OTRS services
Drop the existing database of your target system to have an empty database for the clone data
Get the PostgreSQL password of your database
Clone your database into the target system
Copy the following files from your Windows based system to the target system
Reinstall all packages
Disable remote access for the PostgreSQL database of your target system
Start OTRS services
Upgrading OTRS
Additional Applications
FAQ

Abstract

This chapter describes the installation and basic configuration of the central OTRS framework. It covers information on installing OTRS from source, or with a binary package such as an RPM.

Topics covered here include configuration of the web and database servers, the interface between OTRS and the database, the installation of additional Perl modules, setting proper access rights for OTRS, setting up the cron jobs for OTRS, and some basic settings in the OTRS configuration files.

Follow the detailed steps in this chapter to install OTRS on your server. You can then use its web interface to login and administer the system.

The Simple Way - Installation of Pre-Built Packages

If available for your platform you should use pre-built packages to install OTRS, since it is the simplest and most convenient method. You can find them in the download area at www.otrs.com. The following sections describe the installation of OTRS with a pre-built or binary package on SUSE and Red Hat systems. Only if you are unable to use the pre-built packages for some reason should you follow the manual process.

Installing the RPM on a SUSE Linux server

This section describes the installation of our RPM package on a SUSE Linux server.

Preparing the database for OTRS

You can use OTRS using different database back-ends: MySQL, PostgreSQL or Oracle. The most popular database to deploy OTRS on is MySQL. This chapter shows the steps you need to take to configure MySQL on a SUSE-based server. Of course you can install the database on a dedicated database server if needed for scalability or other purposes.

Note

If you follow this chapter on openSUSE 12.3 and up you'll actually not install MySQL but MariaDB instead, a MySQL compatible fork of the MySQL code. This is no problem, it will work just as well (and even a little better at some points).

Install MySQL by executing the following command as root:

linux:~ # zypper install mysql perl-DBD-mysql
        

This will install MySQL with the default options on your system. You'll need to change the defaults in order to make it suitable for OTRS. With a text editor open the file /etc/my.cnf and add following lines under the [mysqld] section:

max_allowed_packet   = 20M
query_cache_size     = 32M
innodb_log_file_size = 256M
        

Note

Please note that OTRS requires utf8 as database storage encoding.

Now execute systemctl restart mysql.service to re-start the database server and activate these changes. Then run /usr/bin/mysql_secure_installation and follow the on-screen instructions to set a database root password, remove anonymous access and remove the test database. Lastly, run systemctl enable mysql.service in order to make sure MySQL is automatically started at server startup time.

Installing OTRS

Install OTRS with via the command line using zypper. This will also pull in some dependencies such as the Apache web server and some Perl modules. Make sure you copied the OTRS RPM file to the current directory.

otrs-sles:~ # zypper install otrs*.rpm
....
Retrieving package otrs-x.x.x-01.noarch (1/26), 17.5 MiB (74.3 MiB unpacked)
Installing: otrs-x.x.x-01 [done]
Additional rpm output:
Check OTRS user ... otrs added.

...

otrs-sles:~ #
        

Now restart Apache with the command systemctl restart apache2.service to load the configuration changes for OTRS.

Installation of additional perl modules

OTRS needs more modules than can be installed via the package manager per default. You can post-install them manually. Running the otrs.CheckModules.pl script located at /opt/otrs/bin/ will let you know which modules are missing, and must or can be installed. Optional modules may include those needed for communication with MDAs via IMAP(S) or gernerating PDF output.

On SLES you shoud add an external repository in order to get missing modules. Choose the repository needed for your OS version from here: http://download.opensuse.org/repositories/devel:/languages:/perl/ . As an example, the repository for SLES 11 SP 3 would be added like this:

zypper ar -f -n perl http://download.opensuse.org/repositories/devel:/languages:/perl/SLE_11_SP3 Perl
            

On openSUSE 12.3 the extra repository is only needed for the Mail::IMAPClient module, which you'd only need if you need to collect mails from an IMAP server secured with TLS. The corresponding line would look like this:

zypper ar -f -n perl http://download.opensuse.org/repositories/devel:/languages:/perl/openSUSE_12.3/ Perl
            

The first time you use zypper after you added this repository, you will be prompted to add its key. Now you can install missing modules like below.

otrs-sles:/opt/otrs # zypper install -y "perl(YAML::LibYAML)"
Refreshing service 'susecloud'.
Retrieving repository 'perl' metadata [\]

New repository or package signing key received:
Key ID: DCCA98DDDCEF338C
Key Name: devel:languages:perl OBS Project <devel:languages:perl@build.opensuse.org>
Key Fingerprint: 36F0AC0BCA9D8AF2871703C5DCCA98DDDCEF338C
Key Created: Wed Oct 10 22:04:18 2012
Key Expires: Fri Dec 19 22:04:18 2014
Repository: perl

Do you want to reject the key, trust temporarily, or trust always? [r/t/a/?] (r): a
Retrieving repository 'perl' metadata [done]
Building repository 'perl' cache [done]
Loading repository data...
Reading installed packages...
'perl(YAML::LibYAML)' not found in package names. Trying capabilities.
Resolving package dependencies...

The following NEW package is going to be installed:
  perl-YAML-LibYAML

The following package is not supported by its vendor:
  perl-YAML-LibYAML

Retrieving package perl-YAML-LibYAML-0.38-12.4.x86_64 (1/1), 75.0 KiB (196.0 KiB unpacked)
Retrieving: perl-YAML-LibYAML-0.38-12.4.x86_64.rpm [done (55.7 KiB/s)]
Installing: perl-YAML-LibYAML-0.38-12.4 [done]
            

The next step is to configure OTRS using the web installer, as described in this section.

Now you can start the OTRS daemon and activate corresponding watchdog cron job (this must be done by the otrs user):

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

That's it, congratulations!

Installing OTRS on a Red Hat Enterprise Linux or CentOS system

This section describes the installation of our RPM package on a Red Hat Enterprise Linux (RHEL) or CentOS server.

Preparation: Disable SELinux

Note

If your system uses SELinux, you should disable it, otherwise OTRS will not work correctly.

Here's how to disable SELinux for RHEL/CentOS/Fedora:

  • Configure SELINUX=disabled in the /etc/selinux/config file:

    # This file controls the state of SELinux on the system.
    # SELINUX= can take one of these three values:
    #       enforcing - SELinux security policy is enforced.
    #       permissive - SELinux prints warnings instead of enforcing.
    #       disabled - No SELinux policy is loaded.
    SELINUX=disabled
    # SELINUXTYPE= can take one of these two values:
    #       targeted - Targeted processes are protected,
    #       mls - Multi Level Security protection.
    SELINUXTYPE=targeted
                            

  • Reboot your system. After reboot, confirm that the getenforce command returns Disabled:

    shell> getenforce
    Disabled
                            

Preparing the database for OTRS

You can use OTRS using different database back-ends: MySQL, PostgreSQL or Oracle. The most popular database to deploy OTRS on is MySQL. This chapter shows the steps you need to take to configure MySQL on a RHEL-based server. Of course you can install the database on a dedicated database server if needed for scalability or other purposes.

Install MySQL (or MariaDB) by executing the following command as root:

shell> yum -y install mariadb-server
        

This will install MySQL with the default options on your system. You'll need to change the defaults in order to make it suitable for OTRS. With a text editor create a new file /etc/my.cnf.d/zotrs.cnf with the following content:

[mysqld]
max_allowed_packet   = 20M
query_cache_size     = 32M
innodb_log_file_size = 256M
        

Now execute systemctl start mariadb to re-start the database server and activate these changes. Then run /usr/bin/mysql_secure_installation and follow the on-screen instructions to set a database root password, remove anonymous access and remove the test database.

Note

Please note that OTRS requires utf8 as database storage encoding.

Installing OTRS

Install OTRS with via the command line using yum. This will also pull in some dependencies such as the Apache web server and some Perl modules. Make sure you copied the OTRS RPM file to the current directory.

shell> yum install --nogpgcheck otrs-x.x.*.rpm
...
Dependencies Resolved

================================================================================
 Package                    Arch   Version                Repository       Size
================================================================================
Installing:
 otrs                       noarch x.x.x-01               /otrs-x.x.x-01.noarch
                                                                           74 M
Installing for dependencies:
 apr                        x86_64 1.3.9-5.el6_2          updates         123 k
 ...
 procmail                   x86_64 3.22-25.1.el6          base            163 k

Transaction Summary
================================================================================
Install      26 Package(s)

Total size: 80 M
Total download size: 6.0 M
Installed size: 88 M
Downloading Packages:
(1/25): apr-1.3.9-5.el6_2.x86_64.rpm                     | 123 kB     00:00
...
(25/25): procmail-3.22-25.1.el6.x86_64.rpm               | 163 kB     00:00
--------------------------------------------------------------------------------
Total                                           887 kB/s | 6.0 MB     00:06
Running rpm_check_debug
Running Transaction Test
Transaction Test Succeeded
Running Transaction
  Installing : apr-1.3.9-5.el6_2.x86_64                               1/26
  ...
  Installing : otrs-x.x.x-01.noarch                                   26/26
Check OTRS user ... otrs added.

...

shell>
        

Now restart Apache with the command systemctl restart httpd.service to load the configuration changes for OTRS.

Installation of additional perl modules

OTRS needs some more modules than can be installed by the RPM. You can post-install them manually. You can check what modules you are missing by running the bin/otrs.CheckModules.pl script located in the /opt/otrs directory. Some modules are only needed for optional functionality, such as communication with IMAP(S) servers or PDF generation. On Red Hat or CentOS we recommend installing these modules from the EPEL repository, a repository maintained by the Fedora project, which provides high quality packages for RHEL and derivatives. Check for more information the EPEL web site.

If you're on RHEL 7 or CentOS 7, you can get the latest package for EPEL from this site. You can add this repository to yum it in one go by copying the RPM URL you find on this page and executing this command:

shell> yum -y install http://download.fedoraproject.org/pub/epel/7/x86_64/e/epel-release-7-8.noarch.rpm

...

Installed:
  epel-release.noarch 0:7-8

Complete!
            

The first time you use yum after you added this repository, you will be prompted to add its key. Now you can install missing modules like below.

shell> yum -y install "perl(Text::CSV_XS)"

...

Installed:
  perl-Text-CSV_XS.x86_64 0:0.85-1.el6

Complete!
shell>
            

The next step is to configure OTRS using the web installer, as described in this section.

Now you can start the OTRS daemon and activate corresponding watchdog cron job (this must be done by the otrs user):

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

That's it, congratulations!

Installation of Oracle database driver on Red Hat / CentOS

If you want to deploy OTRS on an Oracle database, you'll need to compile and install the DBD::Oracle database driver. This is slightly more complicated than installing any of the other packages; this is because Oracle is a proprietary database and Red Hat nor the CentOS project are allowed to distribute drivers in their RPM repositories.

First of all, we'd need to install gcc, make and CPAN so we can compile and install the driver. Below you see the command on CentOS; on other versions it might look a little different.

shell> yum -y install gcc make "perl(CPAN)"
            

The next step is to obtain and install the database client. For this you would need to sign up for a free account at the Oracle website. You can download the drivers from this page: http://www.oracle.com/technetwork/database/features/instant-client/index-097480.html Please choose the Linux x86 or x86-64 version corresponding to the architecture of your system. You can check this with the uname -i. It is either 'x86_64' for x86-64 or 'i386' for x86. You should download the packages 'Instant Client Package - Basic', 'Instant Client Package - SQL*Plus', and 'Instant Client Package - SDK'. Save them to a location on your disk. Now as the root user you can install the packages using the following command:

shell> yum install oracle-instantclient*
            

After this you should set two environment variables and compile the DBD::Oracle driver. Again, perform these tasks as the root user. The steps are outlined below. Please note that for briefness some lines outputted by the commands have been removed.

shell> export ORACLE_HOME=/usr/lib/oracle/11.2/client64
shell> export LD_LIBRARY_PATH=$ORACLE_HOME/lib
shell> cpan
cpan[1]> look DBD::Oracle
...
Fetching with LWP:
  http://www.perl.org/CPAN/authors/id/P/PY/PYTHIAN/CHECKSUMS
Checksum for /root/.cpan/sources/authors/id/P/PY/PYTHIAN/DBD-Oracle-1.62.tar.gz ok
Scanning cache /root/.cpan/build for sizes
DONE
...
Working directory is /root/.cpan/build/DBD-Oracle-1.62-ZH6LNy
[root@localhost DBD-Oracle-1.62-ZH6LNy]# perl Makefile.PL
...
[root@localhost DBD-Oracle-1.62-ZH6LNy]# make
...
[root@localhost DBD-Oracle-1.62-ZH6LNy]# make install
...
cpan[2]> exit
Terminal does not support GetHistory.
Lockfile removed.
            

Now you should edit the file Kernel/Config.pm to provide ORACLE_HOME. The next step is to configure OTRS using the web installer, as described in this section.

Note

Please note that OTRS requires utf8 as database storage encoding.

Installing OTRS on a Debian or Ubuntu system

Important

Please install OTRS from source, and do not use the OTRS packages that Debian/Ubuntu provides.

The installation of required Perl modules is easier if you use the available packages:

apt-get install libapache2-mod-perl2 libdbd-mysql-perl libtimedate-perl libnet-dns-perl libnet-ldap-perl \
    libio-socket-ssl-perl libpdf-api2-perl libdbd-mysql-perl libsoap-lite-perl libtext-csv-xs-perl \
    libjson-xs-perl libapache-dbi-perl libxml-libxml-perl libxml-libxslt-perl libyaml-perl \
    libarchive-zip-perl libcrypt-eksblowfish-perl libencode-hanextra-perl libmail-imapclient-perl \
    libtemplate-perl