Table of Contents
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 or a Windows exectuable.
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.
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 http://www.otrs.com . The following sections describe the installation of OTRS with a pre-built or binary package on SUSE, Red Hat and Microsoft Windows systems. Only if you are unable to use the pre-built packages for some reason should you follow the manual process.
This section describes the installation of our RPM package on a SUSE Linux server. We have tested against all recent SLES and openSUSE versions. Before you start the installation, please visit http://www.otrs.com/downloads and make sure you use the latest OTRS RPM package available.
You can use OTRS using different database back-ends: MySQL, PostgreSQL, Oracle or Microsoft SQL Server. 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.
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 change the line with max_allowed_packet on it, and add a line below, like this:
max_allowed_packet=20M
query_cache_size=32M
Now execute rcmysql restart 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 chkconfig -a mysql in order to make sure mysql is automatically started at server startup time.
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-3.3.*.rpm
....
Retrieving package otrs-3.3.3-01.noarch (1/26), 17.5 MiB (74.3 MiB unpacked)
Installing: otrs-3.3.3-01 [done]
Additional rpm output:
Check OTRS user ... otrs added.
Next steps:
[start database and Apache]
Make sure your database is running and execute 'rcapache2 restart'.
[install the OTRS database]
Use a webbrowser and open this link:
http://myserver.example.com/otrs/installer.pl
[OTRS services]
Start OTRS 'rcotrs start-force' (rcotrs {start|stop|status|restart|start-force| stop-force}).
((enjoy))
Your OTRS Team
http://otrs.org/
otrs-sles:~ #
Script: Command to install OTRS.
The OTRS installation is done. Start your web server to load the OTRS specific changes in its configuration, as shown in the script below. Also run chkconfig to make sure OTRS is automatically started when the server reboots.
otrs-sles:~ # chkconfig -a apache2
apache2 0:off 1:off 2:off 3:on 4:off 5:on 6:off
otrs-sles:~ # rcapache2 start
Starting httpd2 (prefork) httpd2-prefork: Could not reliably determine the server's fully qualified domain name, using 10.x.x.x for ServerName
done
otrs-sles:~ #
Script: Starting the web server.
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 SLES you should add an external repository to the zypper configuration in order to get the modules needed for your system.
Choose the module needed for your OS version from here: http://download.opensuse.org/repositories/devel:/languages:/perl/. Add the repository like this for SLES 11 SP2:
zypper ar -f -n perl http://download.opensuse.org/repositories/devel:/languages:/perl/SLE_11_SP2 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.
This section describes the installation of our RPM package on a Red Hat Enterprise Linux (RHEL) or CentOS server. For OTRS 3.3 and up, RHEL 6 or CentOS 6 is a requirement, version 5 is not supported. Before you start the installation, please visit http://www.otrs.com/downloads and make sure you use the latest OTRS RPM package available.
You can use OTRS using different database back-ends: MySQL, PostgreSQL, Oracle or Microsoft SQL Server. 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 by executing the following command as root:
[root@otrs-centos6 ~]# yum -y install mysql-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 open the file /etc/my.cnf and add the next two lines under the [mysqld] section:
max_allowed_packet=20M
query_cache_size=32M
Now execute service mysqld start 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 chkconfig mysqld on in order to make sure mysql is automatically started at server startup time.
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.
[root@otrs-centos6 ~]# yum install --nogpgcheck otrs-3.3.*.rpm
...
Dependencies Resolved
================================================================================
Package Arch Version Repository Size
================================================================================
Installing:
otrs noarch 3.3.3-01 /otrs-3.3.3-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-3.3.3-01.noarch 26/26
Check OTRS user ... otrs added.
Next steps:
[httpd services]
Restart httpd 'service httpd restart'
[install the OTRS database]
Make sure your database server is running.
Use a web browser and open this link:
http://myserver.example.com/otrs/installer.pl
[OTRS services]
Start OTRS 'service otrs start' (service otrs {start|stop|status|restart).
((enjoy))
Your OTRS Team
Installed:
otrs.noarch 0:3.3.3-01
Dependency Installed:
...
Complete!
[root@otrs-centos6 ~]#
Script: Command to install OTRS.
The OTRS installation is complete. Now you should make sure that Apache is started and that it starts whenever the server reboots.
[root@otrs-centos6 ~]# chkconfig httpd on [root@otrs-centos6 ~]# service httpd start Starting httpd: httpd: Could not reliably determine the server's fully qualified domain name, using 10.x.x.x for ServerName [ OK ] [root@otrs-centos6 ~]#
Script: Starting the web server.
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 6 or CentOS 6, 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:
[root@otrs-centos6 otrs]# yum -y install http://download.fedoraproject.org/pub/epel/6/i386/epel-release-6-8.noarch.rpm
Loaded plugins: security
Setting up Install Process
epel-release-6-8.noarch.rpm | 14 kB 00:00
Examining /var/tmp/yum-root-7jrJef/epel-release-6-8.noarch.rpm: epel-release-6-8.noarch
Marking /var/tmp/yum-root-7jrJef/epel-release-6-8.noarch.rpm to be installed
Resolving Dependencies
--> Running transaction check
---> Package epel-release.noarch 0:6-8 will be installed
--> Finished Dependency Resolution
Dependencies Resolved
=====================================================================================
Package Arch Version Repository Size
=====================================================================================
Installing:
epel-release noarch 6-8 /epel-release-6-8.noarch 22 k
Transaction Summary
=====================================================================================
Install 1 Package(s)
Total size: 22 k
Installed size: 22 k
Downloading Packages:
Running rpm_check_debug
Running Transaction Test
Transaction Test Succeeded
Running Transaction
Installing : epel-release-6-8.noarch 1/1
Verifying : epel-release-6-8.noarch 1/1
Installed:
epel-release.noarch 0:6-8
Complete!
[root@otrs-centos6 otrs]#
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.
[root@otrs-centos6 otrs]# yum -y install "perl(Text::CSV_XS)"
Loaded plugins: security
Setting up Install Process
Resolving Dependencies
--> Running transaction check
---> Package perl-Text-CSV_XS.x86_64 0:0.85-1.el6 will be installed
--> Finished Dependency Resolution
Dependencies Resolved
=====================================================================================
Package Arch Version Repository Size
=====================================================================================
Installing:
perl-Text-CSV_XS x86_64 0.85-1.el6 epel 71 k
Transaction Summary
=====================================================================================
Install 1 Package(s)
Total download size: 71 k
Installed size: 154 k
Downloading Packages:
perl-Text-CSV_XS-0.85-1.el6.x86_64.rpm | 71 kB 00:00
warning: rpmts_HdrFromFdno: Header V3 RSA/SHA256 Signature, key ID 0608b895: NOKEY
Retrieving key from file:///etc/pki/rpm-gpg/RPM-GPG-KEY-EPEL-6
Importing GPG key 0x0608B895:
Userid : EPEL (6) <epel@fedoraproject.org>
Package: epel-release-6-8.noarch (@/epel-release-6-8.noarch)
From : /etc/pki/rpm-gpg/RPM-GPG-KEY-EPEL-6
Is this ok [y/N]: y
Running rpm_check_debug
Running Transaction Test
Transaction Test Succeeded
Running Transaction
Installing : perl-Text-CSV_XS-0.85-1.el6.x86_64 1/1
Verifying : perl-Text-CSV_XS-0.85-1.el6.x86_64 1/1
Installed:
perl-Text-CSV_XS.x86_64 0:0.85-1.el6
Complete!
[root@otrs-centos6 otrs]#
The next step is to configure OTRS using the web installer, as described in this section.
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.
[root@otrs-centos6 otrs]# 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:
[root@otrs-centos6 otrs]# 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.
[root@otrs-centos6 otrs]# export ORACLE_HOME=/usr/lib/oracle/11.2/client64
[root@otrs-centos6 otrs]# export LD_LIBRARY_PATH=$ORACLE_HOME/lib
[root@otrs-centos6 otrs]# 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.
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 \
libgd-text-perl libtext-csv-xs-perl libjson-xs-perl libgd-graph-perl libapache-dbi-perl
Installing OTRS on a Microsoft Windows system is very easy. Download the latest installer for Win32 from http://www.otrs.com/try/ and save the file to your local file system. Then simply double-click on the file to execute the installer, and follow the few installation steps to setup the system. The installation wizard will take care of installing all components for OTRS. The next step is to configure OTRS using the web installer, as described in this section.
The Windows installer for OTRS contains all needed components for OTRS, i.e. the Apache web server, the MySQL database server, Perl (with all needed modules) and cron for Windows. However you can also use it to set up OTRS on the Microsoft IIS Web Server instead of on Apache. Also you can choose to not let it install the bundled MySQL, for instance if you want to deploy on a central MySQL database; a PostgreSQL database, on Microsoft SQL Server or on Oracle.
If you install OTRS using the Windows Installer, it will automatically configure all Perl modules you will typically need. There is one exception to this: if you need to deploy OTRS on an Oracle database, you'll need to post-install the Oracle driver. This is needed because there is no open source driver for Oracle available; we are not allowed to redistribute it in the OTRS package. There are two different perls you can use on Windows; you can choose the bundled Strawberry Perl, which is the default option and is recommended for proof-of-concept setups; or you can choose Active State perl which is a separate download and install. This last option is recommended for production setups.
If you have installed ActiveState Perl it already comes with the Perl database driver DBD::Oracle only this
should be linked to the Oracle C client.
OTRS only works on 32-bit ActiveState Perl. This means you should also download the 32-bit Oracle client.
Navigate to the Oracle client web site
Instant Client Downloads for Microsoft Windows (32-bit) and choose 'Instant Client Package - Basic'. You'll
need to sign up for a free Oracle Web account in order to download the software. Extract the download, a zip file, to the root of your
drive, for instance C:\instantclient_11_2.
Now you should add the client libraries to your path and set an environment variable; 'ORACLE_HOME'. Navigate to Control Panel > System and Security > System, choose 'Advanced System Settings', click on 'New' under 'System variables', enter 'ORACLE_HOME' as Variable Name and use 'C:\instantclient_11_2' as the Variable Value. Select the 'PATH' variable, and append the directory 'C:\instantclient_11_2' to the path. If you now start a new cmd.exe session and run the otrs.CheckModules.pl script located in the OTRS directory, you should see that the DBD::Oracle driver is successfully installed. After this, you should restart the system in order for the other applications to detect the new environment variables.
In order to compile the DBD::Oracle module, you need to have installed the components of the OTRS web installer in a path
without spaces. It should NOT be in C:\Program Files\OTRS but it should rather be in
C:\OTRSComponents or similar.
On Strawberry Perl you should compile the Oracle driver manually.
The OTRS Windows Installer bundles 32-bit Strawberry Perl. This means you should also download the 32-bit Oracle client.
Navigate to the Oracle client web site
Instant Client Downloads for Microsoft Windows (32-bit) and download the packages
'Instant Client Package - Basic', 'Instant Client Package - SQL*Plus', and 'Instant Client Package - SDK'. You'll
need to sign up for a free Oracle Web account in order to download the software. Extract the downloads,
all zip files, to the root of your drive, for instance C:\instantclient_11_2.
Now you should add the client libraries to your path and set an environment variable; 'ORACLE_HOME'. Navigate to Control Panel > System and Security > System, choose 'Advanced System Settings', click on 'New' under 'System variables', enter 'ORACLE_HOME' as Variable Name and use 'C:\instantclient_11_2' as the Variable Value. Select the 'PATH' variable, and append the directory 'C:\instantclient_11_2' to the path. After this, you should restart the system in order for the other applications to detect the new environment variables.
Now you can compile and install the DBD::Oracle module. For this, open a cmd.exe window, and start the cpan client. Download and extract DBD::Oracle via look DBD::Oracle, then type perl Makefile.PL, dmake and dmake install. Sample output is below.
C:\Users\max>cpan
cpan shell -- CPAN exploration and modules installation (v1.9800)
Enter 'h' for help.
cpan> look DBD::Oracle
Database was generated on Thu, 16 May 2013 14:52:41 GMT
Running look for module 'DBD::Oracle'
Trying to open a subshell in the build directory...
....
C:\OTRSCO~1\StrawberryPerl\cpan\build\DBD-Oracle-1.62-kq6los>perl Makefile.PL
Using DBI 1.623 (for perl 5.016003 on MSWin32-x86-multi-thread) installed in C:/
OTRSComponents/StrawberryPerl/perl/vendor/lib/auto/DBI/
Configuring DBD::Oracle for perl 5.016003 on MSWin32 (MSWin32-x86-multi-thread)
...
Checking if your kit is complete...
Looks good
LD_RUN_PATH=c:/instantclient_11_2/lib:c:/instantclient_11_2/rdbms/lib
Using DBD::Oracle 1.62.
Using DBD::Oracle 1.62.
Using DBI 1.623 (for perl 5.016003 on MSWin32-x86-multi-thread) installed in C:/
OTRSComponents/StrawberryPerl/perl/vendor/lib/auto/DBI/
Writing Makefile for DBD::Oracle
Writing MYMETA.yml and MYMETA.json
...
C:\OTRSCO~1\StrawberryPerl\cpan\build\DBD-Oracle-1.62-kq6los>dmake
... lots of output and compiler warnings ...
C:\OTRSCO~1\StrawberryPerl\cpan\build\DBD-Oracle-1.62-kq6los>dmake install
Files found in blib\arch: installing files in blib\lib into architecture depende
nt library tree
Installing C:\OTRSCO~1\StrawberryPerl\perl\site\lib\auto\DBD\Oracle\dbdimp.h
...
Appending installation info to C:\OTRSCO~1\StrawberryPerl\perl\lib/perllocal.pod
C:\OTRSCO~1\StrawberryPerl\cpan\build\DBD-Oracle-1.62-kq6los>exit
cpan> quit
Lockfile removed.
C:\Users\max>
After this, you can start the web installer to configure OTRS, as described in this section.