Installation from source (Linux, Unix)

Preparing the installation from source

If you want to install OTRS from source, first download the source archive as .tar.gz, .tar.bz2, or .zip file from http://www.otrs.org/download/

Unpack the archive for example with tar into the directory /opt and rename the directory from otrs-2.4.x to otrs:

linux:/opt# tar xf /tmp/otrs-2.4.x.tar.gz
linux:/opt# mv otrs-2.4.-x otrs
linux:/opt# ls
otrs
linux:/opt#

Because the modules of OTRS should not be executed with root rights, you should add a new user for OTRS as the next step. The home directory of this new user should be /opt/otrs. If your web server is not running with the same user rights as the new otrs user, which is the case on most systems, you have to add the new otrs user to the group of the web server user:

linux:/opt# useradd -r -d /opt/otrs/ -c 'OTRS user' otrs
linux:/opt# usermod -G nogroup otrs
linux:/opt#

Now you have to copy some sample configuration files. The system will later use the copied files. The files are located in /opt/otrs/Kernel and /opt/otrs/Kernel/Config and have the suffix .dist.

linux:/opt# cd otrs/Kernel/
linux:/opt/otrs/Kernel# cp Config.pm.dist Config.pm
linux:/opt/otrs/Kernel# cd Config
linux:/opt/otrs/Kernel/Config#  cp GenericAgent.pm.dist GenericAgent.pm

The last step to prepare the installation of OTRS is to set the proper access rights for the files. You can use the script SetPermissions.sh, which is located in the bin directory in the home directory of the OTRS user. You can execute the script with the following parameters:

SetPermissions.sh { Home directory of the OTRS user } { OTRS user } { Web server user } [ Group of the OTRS user ] [ Group of the web server user ]

If your web server is running with the same user rights as OTRS, the command to set the proper access rights is SetPermissions.sh /opt/otrs otrs otrs. On SUSE systems the web server is running with the user rights of wwwrun. On Debian-based systems this is www-data. You would use the command SetPermissions.sh /opt/otrs otrs wwwrun nogroup www to set the proper access rights.

Installation of Perl modules

OTRS needs some additional Perl modules. If you install OTRS from source, you'll have to install these modules manually. This can either be done with the package manager of your Linux distribution (yast, apt-get) or, like described in this section, through the Perl shell and CPAN. If you're using ActiveState Perl, for instance on Windows, you could use PPM, the built-in Perl Package Manager. If possible we advise you to use your package manager.

OTRS requires the following additional Perl modules:

Table 3.1. Needed Perl modules for OTRS

Name Description
CGI This module is needed by the web interface of OTRS.
Date::Pcalc This module is needed for date calculations. OTRS uses this module for example in time specific calculations for tickets.
DBI OTRS needs this module to connect to the database back-end.
DBD::mysql Module with special functions to connect to the MySQL database back-end. (only required if you use MySQL)
DBD::pg Module with special functions to connect to the PostgreSQL database back-end. (only required if you use PostgreSQL)
Digest::MD5 This module makes it possible to use the md5 algorithm.
LWP::UserAgent Module to process HTTP requests.
MIME::Base64 En- and decoding Base64 strings, e.g. for mail attachments.
MIME::Tools This module provide some tools to process messages with MIME parts.
Mail::Internet Used for OTRS email processing.
Net::DNS Perl interface to the domain name system.
Net::POP3 This module contains procedures to access and process messages on a POP3 server.
Net::POP3Client This module contains procedures to access and process messages on a POP3 server.
IO::Socket::SSL Required for SSL connections to your mail server.
Net::LDAP Perl interface to a LDAP directory. You only need to install this module, if you want to use a LDAP back-end.
Net::SMTP Module that contains procedures to send emails.
Authen::SASL SASL authentication framework, e.g. needed for the authentication against mail servers.
Net::SMTP::SSL Required if you use SSL connections to your SMTP server.
GD Interface to the GD graphics library. You only need to install this module, if you want to use the stats module in OTRS.
GD::Text, GD::Graph, GD::Graph::lines, GD::Text::Align Some more text- and graphic tools for the GD graphics library. You only need to install this modules, if you want to use the stats module of OTRS.
SOAP::Lite This module is needed if you'd like to use the XML-RPC interface of OTRS.
XML::Parser This module is needed to read and write xml configuration files. The graphical configuration front-end of OTRS uses this module.
PDF::API2, Compress::Zlib This module are needed to generate the PDF output for reports, search results or for the ticket print view.


You can verify which modules you need to install with otrs.checkModules. The script is located in the bin directory in the home directory of the OTRS user.

linux:~# cd /opt/otrs/bin/
linux:/opt/otrs/bin# ./otrs.checkModules
   o CGI............................ok (v3.43)
   o Date::Pcalc....................ok (v1.2)
   o Date::Format...................ok (v2.22)
   o DBI............................ok (v1.607)
   o DBD::mysql.....................ok (v4.008)
   o Digest::MD5....................ok (v2.36_01)
   o Crypt::PasswdMD5...............ok (v1.3)
   o LWP::UserAgent.................ok (v5.819)
   o Encode::HanExtra...............ok (v0.23)
   o IO::Scalar.....................ok (v2.110)
   o IO::Wrap.......................ok (v2.110)
   o MIME::Base64...................ok (v3.07_01)
   o Mail::Internet.................ok (v2.04)
   o MIME::Tools....................ok (v5.427)
   o Net::DNS.......................ok (v0.63)
   o Net::POP3......................ok (v2.29)
   o Mail::POP3Client...............ok (v2.18 )
      o IO::Socket::SSL.............ok (v1.18)
   o Net::IMAP::Simple..............ok (v1.17)
      o Net::IMAP::Simple::SSL......ok (v1.3)
   o Net::SMTP......................ok (v2.31)
      o Authen::SASL................ok (v2.12)
      o Net::SMTP::SSL..............ok (v1.01)
   o Net::LDAP......................ok (v0.39)
   o GD.............................ok (v2.39)
      o GD::Text....................ok (v0.86)
      o GD::Graph...................ok (v1.44)
      o GD::Graph::lines............ok (v1.15)
      o GD::Text::Align.............ok (v1.18)
   o PDF::API2......................ok (v0.73)
   o SOAP::Lite.....................ok (v0.710.08)
   o XML::Parser....................ok (v2.36)
linux:/opt/otrs/bin#

To install one of the modules from above via CPAN, you have to execute the command perl -e shell -MCPAN. The Perl shell will be started in interactive mode and the CPAN module will be loaded. If CPAN is already configured, you can install the modules with the command install followed by the name of the module. CPAN takes care of the dependencies of a module to other Perl modules and lets you know, if other modules are needed.

Execute also the two commands perl -cw bin/cgi-bin/index.pl and perl -cw bin/PostMaster.pl after changing into the directory /opt/otrs. If the output of both commands is "syntax OK", your Perl is properly set up.

linux:~# cd /opt/otrs
linux:/opt/otrs# perl -cw bin/cgi-bin/installer.pl
cgi-bin/installer.pl syntax OK
linux:/opt/otrs# perl -cw bin/PostMaster.pl
PostMaster.pl syntax OK
linux:/opt/otrs#

Configuring the apache web server

This section describes the basic configuration of the apache web server for OTRS for use with mod_cgi . The web server should be able to execute CGI scripts. OTRS won't work if the Perl scripts cannot be parsed. Check the configuration files of your web server, and search for the line that loads the CGI module. If you see something like the following, the CGI module should already be in use.

LoadModule cgi_module /usr/lib/apache2/modules/mod_cgi.so

To access the web interface of OTRS comfortably, via a short address, an Alias and a ScriptAlias entry is needed. Most apache installations have a conf.d directory included. On linux systems you can find this directory very often under /etc/apache or /etc/apache2. Log in as root, change to the conf.d directory and copy the appropriate template to a file called otrs.conf.

First find the example configuration file in otrs/scripts/ that is fitting for your version of the apache web server. Either: Apache2 apache2-httpd-new.include.conf

# --
# added for OTRS (http://otrs.org/)
# $Id: installation-and-basic-configuration.xml,v 1.28 2009/09/27 19:13:26 mb Exp $
# --

# agent, admin and customer frontend
ScriptAlias /otrs/ "/opt/otrs/bin/cgi-bin/"
Alias /otrs-web/ "/opt/otrs/var/httpd/htdocs/"

# if mod_perl is used
<IfModule mod_perl.c>

    # load all otrs modules
    Perlrequire /opt/otrs/scripts/apache2-perl-startup.pl

    # Apache::Reload - Reload Perl Modules when Changed on Disk
    PerlModule Apache2::Reload
    PerlInitHandler Apache2::Reload
    PerlModule Apache2::RequestRec

    # set mod_perl2 options
    <Location /otrs>
#        ErrorDocument 403 /otrs/customer.pl
        ErrorDocument 403 /otrs/index.pl
        SetHandler  perl-script
        PerlResponseHandler ModPerl::Registry
        Options +ExecCGI
        PerlOptions +ParseHeaders
        PerlOptions +SetupEnv
        Order allow,deny
        Allow from all
    </Location>

</IfModule>

# directory settings
<Directory "/opt/otrs/bin/cgi-bin/">
    AllowOverride None
    Options +ExecCGI -Includes
    Order allow,deny
    Allow from all
</Directory>
<Directory "/opt/otrs/var/httpd/htdocs/">
    AllowOverride None
    Order allow,deny
    Allow from all
</Directory>

# MaxRequestsPerChild (so no apache child will be to big!)
MaxRequestsPerChild 400

Apache1 apache-httpd.include.conf

# --
# added for OTRS (http://otrs.org/)
# --

# agent, admin and customer frontend (mod_alias required!)
ScriptAlias /otrs/ "/opt/otrs/bin/cgi-bin/"
Alias /otrs-web/ "/opt/otrs/var/httpd/htdocs/"

# if mod_perl is used
<IfModule mod_perl.c>

    # load all otrs modules (speed improvement!)
#   Perlrequire /opt/otrs/scripts/apache-perl-startup.pl

    # Apache::StatINC - Reload %INC files when updated on disk
    # (just use it for testing, setup, ... not for high-load systems)
#   PerlInitHandler Apache::StatINC

    <Location /otrs>
#        ErrorDocument 403 /otrs/customer.pl
        ErrorDocument 403 /otrs/index.pl
        SetHandler  perl-script
        PerlHandler Apache::Registry
        Options ExecCGI
        PerlSendHeader On
        PerlSetupEnv On
    </Location>

</IfModule>

# MaxRequestsPerChild (so no apache child will be to big!)
MaxRequestsPerChild 400

Restart your web server to load the new configuration settings for the web server. On most systems you can start/restart your web server with the command /etc/init.d/apache restart or /etc/init.d/apache2 restart.

linux:/etc/apache2/conf.d# /etc/init.d/apache2 restart
Forcing reload of web server: Apache2.
linux:/etc/apache2/conf.d#

Now your web server should be configured for OTRS.

If you choose to increase performance, and you can install mod_perl, then you can leave mod_cgi off, and configure the apache web server for use with mod_perl, in the following manner.

Please ensure that mod_perl is installed, and loaded, in order to take advantage of this feature. Due to the nature of the start-up script, your server will not fail to start, if the mod_perl is not properly loaded or compiled in your apache web server, unless mod_cgi is also on. Technically speaking you can leave mod_cgi on as well, but you should not.

Search your /etc/apache* directory directory for mod_perl.so i.e.

 #:/ grep -Rn mod_perl.so /etc/apache*

to see if the module is already loaded somewhere, or not.

When you use the appropriate start script (listed above), and the module is loaded, the script (when commented in) /opt/otrs/scripts/apache-perl-startup.pl can be used to load the perl modules into memory one time, saving on load times and increasing performance.

Configuring the database

The simple way - Using the web installer (works only with MySQL)

If you are using MySQL for database back-end, you can easily configure the OTRS database via a web front-end. Use the URL http://localhost/otrs/installer.pl to access the start page of the web installer. Just follow the few steps through the installation process.

Warning

It is never a good idea to use default passwords. Please change the default password for the OTRS database!

Installing the OTRS database manually

If you can't use the web installer to setup the OTRS database, you have to set it up manually. Scripts with the SQL statements to create and configure the database are located in scripts/database in the home directory of the OTRS user.

linux:~# cd /opt/otrs/scripts/database/
linux:/opt/otrs/scripts/database# ls
otrs-initial_insert.db2.sql         otrs-schema.mysql.sql
otrs-schema.oracle.sql
otrs-initial_insert.mssql.sql       otrs-schema-post.db2.sql
otrs-initial_insert.mysql.sql       otrs-schema.postgresql.sql
otrs-initial_insert.oracle.sql
otrs-initial_insert.postgresql.sql  otrs-schema-post.mssql.sql
otrs-initial_insert.xml             otrs-schema-post.mysql.sql
otrs-schema.db2.sql                 otrs-schema-post.oracle.sql
 otrs-schema-post.postgresql.sql
otrs-schema.mssql.sql               otrs-schema.xml
linux:/opt/otrs/scripts/database#

To setup the database for the different database back-ends the .sql files must be processed in a special order.

Create the OTRS database manually step by step

  1. Creating the DB: Create the database, that you want to use for OTRS, with your database client or your database interface.

  2. Creating the tables: With the otrs-schema.DatabaseType.sql files (e.g.. otrs-schema.oracle.sql, otrs-schema.postgresql.sql) you can create the tables in your OTRS database.

  3. Inserting the initial system data: OTRS needs some initial system data to work properly (e.g. the different ticket states, ticket and notification types). Depending on the type of your database Use one of the files otrs-initial_insert.mysql.sql, otrs-initial_insert.db2.sql, otrs-initial_insert.oracle.sql, otrs-initial_insert.postgresql.sql or otrs-initial_insert.mssql.sql .

  4. Creating references between tables: The last step is to create the references between the different tables in the OTRS database. Use the otrs-schema-post.DatabaseType.sql files to create these references (e.g. otrs-schema-oracle.post.sql, otrs-schema-post.postgresql.sql).

After you have finished the database setup you should check and set proper access rights for the OTRS database. It should be enough to grant access to one user. Depending on the database server you are using setting up the access rights differs, but it should be possible either with your database client or your graphical database front-end.

If your database and the access rights are configured properly, you have to tell OTRS which database back-end you want to use and how the ticket system can connect to the database. Open the file Kernel/Config.pm in the home directory of the OTRS user and change the following parameters to your needs:


    # DatabaseHost
    # (The database host.)
    $Self->{'DatabaseHost'} = 'localhost';

    # Database
    # (The database name.)
    $Self->{Database} = 'otrs';

    # DatabaseUser
    # (The database user.)
    $Self->{DatabaseUser} = 'otrs';

    # DatabasePw
    # (The password of database user.)
    $Self->{DatabasePw} = 'some-pass';

Setting up the cron jobs for OTRS

OTRS needs some cron jobs to work properly. The cron jobs should be run with the same user rights that were specified for the OTRS modules. That means that the cron jobs must be inserted into the crontab file of the OTRS user.

All scripts with the cron jobs are located in var/cron in the home directory of the OTRS user.

linux:~# cd /opt/otrs/var/cron
linux:/opt/otrs/var/cron# ls
aaa_base.dist                pending_jobs.dist          session.dist
fetchmail.dist               postmaster.dist            unlock.dist
generic_agent-database.dist  postmaster_pop3.dist
generic_agent.dist           rebuild_ticket_index.dist
linux:/opt/otrs/var/cron#

All scripts are ending in .dist. You should copy them to files with no ending. If you are using bash, you might use the command listed below.

linux:/opt/otrs/var/cron# for foo in *.dist; do cp $foo
`basename $foo .dist`; done
linux:/opt/otrs/var/cron# ls
aaa_base                     generic_agent.dist    rebuild_ticket_index
aaa_base.dist                pending_jobs
rebuild_ticket_index.dist
fetchmail                    pending_jobs.dist     session
fetchmail.dist               postmaster            session.dist
generic_agent                postmaster.dist       unlock
generic_agent-database       postmaster_pop3       unlock.dist
generic_agent-database.dist  postmaster_pop3.dist
linux:/opt/otrs/var/cron#

The following table describes what the several scripts are doing and why they are need to be a cron job for the OTRS user.

Table 3.2. Description of the several cron job scripts

Script Function
aaa_base This script sets the basics for the crontab of the OTRS user.
fetchmail If new mails shell be fetched with fetchmail into the ticket system, this script can be used.
generic_agent This script executes the jobs of the GenericAgent that are not stored in the database but in own config files.
generic_agent-database This script executes the jobs of the GenericAgent that are stored in the database.
pending_jobs This script checks the system for waiting (pending) tickets.
postmaster This script checks the message queue of the ticket system and delivers messages that are still in the queues.
postmaster_pop3 This script fetches the mails from the POP3 accounts that were specified in the admin area in the section for "PostMaster POP3 Account".
rebuild_ticket_index This script rebuilds the ticket index. That improves the speed of the QueueView.
session This script removes old and not longer needed session ID's.
unlock This script unlocks tickets in the system.


To setup all cron jobs the script bin/Cron.sh can be used, which is located in the home directory of the OTRS user. the script needs a parameter when it is executed that tells if you like to install, remove or reinstall the cron jobs. The following parameters can be used:

Cron.sh { start } { stop } { restart } [ OTRS user ]

Because the cron jobs need to be installed in the crontab file of the OTRS user, you need to be logged in as OTRS user. If you are logged in as root, you can change to the OTRS user with the command su otrs. Execute the following command to install the cronjobs:

Warning

Please note that other crontab entries of the OTRS user will be overwritten or removed by the Cron.sh script. Please change the Cron.sh script to keep also other crontab entries.

linux:/opt/otrs/var/cron# cd /opt/otrs/bin/
linux:/opt/otrs/bin# su otrs
linux:~/bin$ ./Cron.sh start
/opt/otrs/bin
Cron.sh - start/stop OTRS cronjobs - <$Revision: 1.28 $>
Copyright (C) 2001-2009 OTRS AG, http://otrs.org/
(using /opt/otrs) done
linux:~/bin$ exit
exit
linux:/opt/otrs/bin#

the command crontab -l -u otrs, which can be executed as root, shows you the crontab file of the OTRS user and you can check if all entries are right:

linux:/opt/otrs/bin# crontab -l -u otrs
# --
# cron/aaa_base - base crontab package
# Copyright (C) 2001-2009 OTRS AG, http://otrs.org/
# --
# This software comes with ABSOLUTELY NO WARRANTY.
# --
# Who gets the cron emails?
MAILTO="root@localhost"

# --
# cron/fetchmail - fetchmail cron of the OTRS
# Copyright (C) 2001-2009 OTRS AG, http://otrs.org/
# --
# $Id: installation-and-basic-configuration.xml,v 1.28 2009/09/27 19:13:26 mb Exp $
# This software comes with ABSOLUTELY NO WARRANTY.
# --
# fetch every 5 minutes emails via fetchmail
#*/5 * * * * /usr/bin/fetchmail -a >> /dev/null

# --
# cron/generic_agent - GenericAgent.pl cron of the OTRS
# Copyright (C) 2001-2009 OTRS AG, http://otrs.org/
# --
# --
# This software comes with ABSOLUTELY NO WARRANTY.
# --
# start generic agent every 20 minutes
*/20 * * * * $HOME/bin/GenericAgent.pl >> /dev/null
# example to execute GenericAgent.pl on 23:00 with
# Kernel::Config::GenericAgentMove job file
#0 23 * * * $HOME/bin/GenericAgent.pl -c "Kernel::Config::GenericAgentMove" >> /dev/null
# --
# cron/generic_agent - GenericAgent.pl cron of the OTRS
# Copyright (C) 2001-2009 OTRS AG, http://otrs.org/
# --
# This software comes with ABSOLUTELY NO WARRANTY.
# --
# start generic agent every 10 minutes
*/10 * * * * $HOME/bin/GenericAgent.pl -c db >> /dev/null
# --
# cron/pending_jobs - pending_jobs cron of the OTRS
# Copyright (C) 2001-2009 OTRS AG, http://otrs.org/
# --
# This software comes with ABSOLUTELY NO WARRANTY.
# --
# check every 120 min the pending jobs
45 */2 * * * $HOME/bin/PendingJobs.pl >> /dev/null
# --
# cron/postmaster - postmaster cron of the OTRS
# Copyright (C) 2001-2009 OTRS AG, http://otrs.org/
# --
# This software comes with ABSOLUTELY NO WARRANTY.
# --
# check daily the spool directory of OTRS
#10 0 * * * * test -e /etc/init.d/otrs & /etc/init.d/otrs cleanup >> /dev/null; test -e /etc/rc.d/init.d/otrs && /etc/rc.d/init.d/otrs cleanup >> /dev/null
10 0 * * * $HOME/bin/otrs.cleanup >> /dev/null
# --
# cron/postmaster_pop3 - postmaster_pop3 cron of the OTRS
# Copyright (C) 2001-2009 OTRS AG, http://otrs.org/
# --
# This software comes with ABSOLUTELY NO WARRANTY.
# --
# fetch emails every 10 minutes
*/10 * * * * $HOME/bin/PostMasterPOP3.pl >> /dev/null
# --
# cron/rebuild_ticket_index - rebuild ticket index for OTRS
# Copyright (C) 2001-2009 OTRS AG, http://otrs.org/
# --
# This software comes with ABSOLUTELY NO WARRANTY.
# --
# just every day
01 01 * * * $HOME/bin/RebuildTicketIndex.pl >> /dev/null

# --
# cron/session - delete old session ids of the OTRS
# Copyright (C) 2001-2009 OTRS AG, http://otrs.org/
# --
# This software comes with ABSOLUTELY NO WARRANTY.
# --
# delete every 120 minutes old/idle session ids
55 */2 * * * $HOME/bin/DeleteSessionIDs.pl --expired >> /dev/null

# --
# cron/unlock - unlock old locked ticket of the OTRS
# Copyright (C) 2001-2009 OTRS AG, http://otrs.org/
# --
# This software comes with ABSOLUTELY NO WARRANTY.
# --
# unlock every hour old locked tickets
35 * * * * $HOME/bin/UnlockTickets.pl --timeout >> /dev/null

linux:/opt/otrs/bin#