Installation from source (Linux, Unix)

Preparing the installation from source

If you have to install OTRS from source, first download the .tar.gz or .tar.bz2 file with the sources from http://www.otrs.org please.

Unpack the archive for example with tar e.g. into the directory /opt:

linux:/opt# tar xf /tmp/otrs-2.0.0.tar.gz
linux:/opt# ls
otrs
linux:/opt#

Because the modules of OTRS should not be executed with root rights, a new user for OTRS will be added in the next step. The home directory of this new user should be /opt/otrs. If your webserver is not running with the same user rights like the new otrs users (this 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 -d /opt/otrs/ -c 'OTRS user' otrs
linux:/opt# usermod -G nogroup otrs
linux:/opt#

Now some demo config files of OTRS have to be copied. The system will later use the copied files. The files are located in /opt/otrs/Kernel and /opt/otrs/Kernel/Config and have the ending .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# for foo in *.dist; do cp $foo `basename
$foo .dist`; done
linux:/opt/otrs/Kernel/Config#

The last step to prepare the installation of OTRS is to set the proper access rights for the files of the ticket system. You can use the script SetPermissions.sh, which is located in the bin directory in the home directory of the OTRS user. The script can be executed 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 ]

Is your web server 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. You would use the command SetPermissions.sh /opt/otrs otrs wwwrun to set the proper access rights.

Installation of needed perl modules

OTRS needs some additional per modules. If you install OTRS from source, you'll have to install these modules manually. This can either be done with the packagemanager of your distro (yast, apt-get) or, like described in this section, through the perl shell and CPAN.

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 backend.
DBD::mysql Module with special functions to connect to the MySQL database backend.
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 This module makes it possible to process emails based on the RFC 822 standard.
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::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 mailservers.
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.
XML::Parser This module is needed to read and write xml configuration files. The graphical configuration front-end of OTRS uses this module.


To install one of the modules from above with 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.

After you have installed all modules you can use the script otrss.checkModules to check if OTRS has all needed perl modules. 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
                  CGI ... ok
          Date::Pcalc ... ok
                  DBI ... ok
           DBD::mysql ... ok
          Digest::MD5 ... ok
       LWP::UserAgent ... ok
           IO::Scalar ... ok
             IO::Wrap ... ok
         MIME::Base64 ... ok
          MIME::Tools ... ok
       Mail::Internet ... ok
             Net::DNS ... ok
            Net::POP3 ... ok
            Net::LDAP ... ok
            Net::SMTP ... ok
         Authen::SASL ... ok
                   GD ... ok
             GD::Text ... ok
            GD::Graph ... ok
     GD::Graph::lines ... ok
      GD::Text::Align ... ok
          XML::Parser ... ok
linux:/opt/otrs/bin#

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", you have a proper perl installation to use with OTRS.

linux:~# cd /opt/otrs
linux:/opt/otrs# perl -cw cgi-bin/installer.pl
cgi-bin/installer.pl syntax OK
linux:/opt/otrs# perl -cw 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. The web server should be able to execute CGI scripts. OTRS won't work if no perl scripts can be parsed. Check the config 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 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 and change to the conf.d directory and open/create a file called otrs.conf. Insert the following lines into this file:

#
# Basic apache configuration file for OTRS
#
# agent, admin and customer frontend
#
ScriptAlias /otrs/ "/opt/otrs/bin/cgi-bin/"
Alias /otrs-web/ "/opt/otrs/var/httpd/htdocs/"
#
# 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>

Save the file and restart your webserver to load the new config settings for the web server. On most systems you can start/restart your webserver 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 webserver should be basicaly configured for OTRS.

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
initial_insert.sapdb.sql    otrs-schema-post.maxdb.sql
initial_insert.sql          otrs-schema-post.mysql.sql
otrs-schema.maxdb.sql       otrs-schema-post.oracle.sql
otrs-schema.mysql.sql       otrs-schema-post.postgresql.sql
otrs-schema.oracle.sql      otrs-schema.xml
otrs-schema.postgresql.sql
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 either the file initial_insert.sql or initial_insert.sapdb.sql to insert the initial data.

  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:


    # 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.

linux:/opt/otrs/var/cron# for foo in `ls -1 *.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
Cron.sh - start/stop OTRS cronjobs - <$Revision: 1.8 $>
Copyright (c) 2002 Martin Edenhofer <martin@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) 2002-2003 Martin Edenhofer <martin+code@otrs.org>
# --
# $Id: installation-and-basic-configuration.xml,v 1.8 2006/05/15 10:05:08 cs Exp $
# This software comes with ABSOLUTELY NO WARRANTY.
# --
# Who gets the cron emails?
MAILTO="root@localhost"

# --
# cron/fetchmail - fetchmail cron of the OTRS
# Copyright (C) 2002-2003 Martin Edenhofer <martin+code@otrs.org>
# --
# $Id: installation-and-basic-configuration.xml,v 1.8 2006/05/15 10:05:08 cs 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) 2002-2003 Martin Edenhofer <martin+code@otrs.org>
# --
# $Id: installation-and-basic-configuration.xml,v 1.8 2006/05/15 10:05:08 cs Exp $
# --
# 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-2004 Martin Edenhofer <martin+code@otrs.org>
# --
# $Id: installation-and-basic-configuration.xml,v 1.8 2006/05/15 10:05:08 cs Exp $
# --
# 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) 2002-2003 Martin Edenhofer <martin+code@otrs.org>
# --
# $Id: installation-and-basic-configuration.xml,v 1.8 2006/05/15 10:05:08 cs Exp $
# --
# 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) 2002-2003 Martin Edenhofer <martin+code@otrs.org>
# --
# $Id: installation-and-basic-configuration.xml,v 1.8 2006/05/15 10:05:08 cs Exp $
# --
# 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) 2002-2003 Martin Edenhofer <martin+code@otrs.org>
# --
# $Id: installation-and-basic-configuration.xml,v 1.8 2006/05/15 10:05:08 cs Exp $
# --
# 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) 2002-2003 Martin Edenhofer <martin+code@otrs.org>
# --
# $Id: installation-and-basic-configuration.xml,v 1.8 2006/05/15 10:05:08 cs Exp $
# 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-2004 Martin Edenhofer <martin+code@otrs.org>
# --
# $Id: installation-and-basic-configuration.xml,v 1.8 2006/05/15 10:05:08 cs Exp $
# 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) 2002-2003 Martin Edenhofer <martin+code@otrs.org>
# --
# $Id: installation-and-basic-configuration.xml,v 1.8 2006/05/15 10:05:08 cs Exp $
# 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#