<?xml version='1.0' encoding='ISO-8859-1'?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
  "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<!-- $Id: installation-and-basic-configuration.xml,v 1.28 2009/09/27 19:13:26 mb Exp $ -->

<chapter id="installation-and-basic-configuration">
<title>Installation / Upgrade of the OTRS framework</title>

<abstract>
<para>
This chapter describes the installation and the basic configuration of the
central OTRS framework. You'll find information about installing OTRS
from source or with a binary package, for example RPM or with the
Windows Installer.
</para>

<para>
The configuration of the web and database server, the interface between
OTRS and the database, the installation of needed Perl modules, setting
proper access rights for OTRS, setting up the cron jobs for OTRS and some
basic settings in the configuration files of OTRS are described in this chapter.
</para>

<para>
When you have finished reading this chapter, you should have a running OTRS
system installed on your operating system where you can login and
administrate the system via the web interface.
</para>
</abstract>

<sect1 id="installation-of-prepared-packages">
<title>The simple way - Installation of pre-built packages</title>

<para>
The simplest and most comfortable way to install OTRS is to use pre-built
packages. Many pre-built packages of OTRS can be found in the download area
on

<ulink url="http://www.otrs.org">
<citetitle>http://www.otrs.org</citetitle>
</ulink>

. The following sections describe the installation of OTRS with a pre-built
or binary package on SUSE, Debian and Microsoft Windows systems. Use
pre-built packages to install OTRS and only setup OTRS manually, if you have
no other possibility.
</para>

<sect2 id="installation-on-suse">
<title>Installing the rpm on a SUSE Linux server</title>

<para>
This section describes the installation of a pre-built rpm package on a SUSE
Linux distro. We tested the SUSE versions from 7.x to 10.0. Before you
start the installation please have a look on

<ulink url="http://www.otrs.org/">
<citetitle>http://www.otrs.org</citetitle>
</ulink>

and check, if a newer OTRS rpm package is available. Please use the newer
rpm package, if available.
</para>

<para>
Please install OTRS with <application>yast</application> (yast2) or via
the command line and <command>rpm</command>. Because OTRS needs some Perl
modules which are not installed on a SUSE system by default, we recommend
to use <application>yast</application>, because
<application>yast</application> solves the package dependencies automatically.
</para>

<para>
If you decide to install OTRS via the command line and
<application>rpm</application>, you have to install the needed Perl modules
manually before. Lets say, that you have saved the file
<filename>otrs.rpm</filename> into the directory
<filename>/tmp</filename>, you can execute the following command to install
OTRS:
</para>

<para>
<screen>
linux:~ # rpm -ivh /tmp/otrs.rpm
otrs                        ##################################################
Check OTRS user (/etc/passwd)... otrs exists.

Next steps:

[SuSEconfig]
 Execute 'SuSEconfig' to configure the web server.

[start Apache and MySQL]
 Execute 'rcapache restart' and 'rcmysql start' in case they don't run.

[install the OTRS database]
 Use a web browser and open this link:
 http://localhost/otrs/installer.pl

[OTRS services]
 Start OTRS 'rcotrs start-force' (rcotrs {start|stop|status|restart|start-force|stop-force}).

Have fun!

 Your OTRS Team
 http://otrs.org/

linux:~ #
</screen>
</para>

<para>
After the installation of the OTRS rpm package, you have to run
<application>SuSEconfig</application>. Use the following command:
</para>

<para>
<screen>
linux:~ # SuSEconfig
Starting SuSEconfig, the SuSE Configuration Tool...
Running in full featured mode.
Reading /etc/sysconfig and updating the system...
Executing /sbin/conf.d/SuSEconfig.aaa_at_first...
Executing /sbin/conf.d/SuSEconfig.apache...
Including /opt/otrs/scripts/apache-httpd.include.conf
Executing /sbin/conf.d/SuSEconfig.bootsplash...
Executing /sbin/conf.d/SuSEconfig.doublecheck...
Executing /sbin/conf.d/SuSEconfig.guile...
Executing /sbin/conf.d/SuSEconfig.hostname...
Executing /sbin/conf.d/SuSEconfig.ispell...
Executing /sbin/conf.d/SuSEconfig.perl...
Executing /sbin/conf.d/SuSEconfig.permissions...
Executing /sbin/conf.d/SuSEconfig.postfix...
Setting up postfix local as MDA...
Setting SPAM protection to "off"...
Executing /sbin/conf.d/SuSEconfig.profiles...
Finished.
linux:~ #
</screen>
</para>

<para>
The installation of the OTRS rpm is finished. Restart your web server to
load the OTRS specific changes in your web server configuration:
</para>

<para>
<screen>
linux:~ # rcapache restart
Shutting down httpd                                         done
Starting httpd [ PERL ]                                     done
linux:~ #
</screen>
</para>

<para>
In the next step you have to setup the OTRS database. If you use
<application>MySQL</application> as the database back-end, you can use the web
installer of OTRS to setup the database. Use the following address to
access the web installer start file.
</para>

<para>
<ulink url="http://localhost/otrs/installer.pl">
<citetitle>http://localhost/otrs/installer.pl</citetitle>
</ulink>
</para>

<para>
The web installer starts. Please follow the steps and setup the system.
</para>

<para>
<screenshot>
<screeninfo>installer.pl screen - License (1/4)</screeninfo>
<graphic srccredit="installer.pl - screenshot" scale="40" fileref="screenshots/installer.png"></graphic>
</screenshot>
</para>

<para>
<screenshot>
<screeninfo>installer.pl screen - Create database (2/4)</screeninfo>
<graphic srccredit="installer.pl - screenshot" scale="40" fileref="screenshots/installer1.png"></graphic>
</screenshot>
</para>

<warning>
<para>
It is never a good idea to use default passwords. Please change the default
password for the OTRS database!
</para>
</warning>

<para>
<screenshot>
<screeninfo>installer.pl screen - Create Database (2/4)</screeninfo>
<graphic srccredit="installer.pl - screenshot" scale="40" fileref="screenshots/installer2.png"></graphic>
</screenshot>
</para>

<para>
<screenshot>
<screeninfo>installer.pl screen - System Settings (3/4)</screeninfo>
<graphic srccredit="installer.pl - screenshot" scale="40" fileref="screenshots/installer3.png"></graphic>
</screenshot>
</para>

<para>
<screenshot>
<screeninfo>installer.pl screen - Finished (4/4)</screeninfo>
<graphic srccredit="installer.pl - screenshot" scale="40" fileref="screenshots/installer4.png"></graphic>
</screenshot>
</para>

<para>
Please restart the OTRS service now, to use the new configuration settings:
</para>

<para>
<screen>
linux:~ # rcotrs restart-force
Shutting down OTRS
 Disable /opt/otrs/bin/PostMaster.pl ... done.
no crontab for otrs
 Shutting down cronjobs ... failed!
Shutting down OTRS (completely)
 Shutting down Apache ... done.
 Shutting down MySQL ... done.
                                                                     done
Starting OTRS (completely)
 Starting Apache ... done.
 Starting MySQL ... done.
Starting OTRS
 Checking Apache ... done.
 Checking MySQL ... done.
 Checking database connect... (It looks Ok!).
 Enable /opt/otrs/bin/PostMaster.pl ... done.
 Checking otrs spool dir...  done.
 Creating cronjobs (source /opt/otrs/var/cron/*) ... done.

  -->> http://linux.example.com/otrs/index.pl &lt;&lt;--
                                                                     done
                                                                     done
linux:~ #
</screen>
</para>

<para>
Now the installation of OTRS is finished and you should be able to work
with the system. To log into the web interface of OTRS, use the address

<ulink url="http://localhost/otrs/index.pl">
<citetitle>http://localhost/otrs/index.pl</citetitle>
</ulink>

in your web browser. Log in as OTRS administrator and configure the system for your
needs. To log in as OTRS administrator use the username root@localhost and the
default password root.
</para>

<warning>
<para>
Please change the password for the root@localhost account as soon as possible.
</para>
</warning>

</sect2>

<sect2 id="installation-on-debian">
<title>Installing OTRS on a Debian system</title>

<para>
Torsten Werner, the maintainer of the Debian OTRS package, kindly provided
excellent documentation on the installation of OTRS on Debian systems. The
document can be found on:

<ulink url="http://docs.google.com/View?docid=drm3kmx_0cbr3x9">
http://www.writely.com/View?docid=drm3kmx_0cbr3x9
</ulink>

.
</para>

</sect2>

<sect2 id="installation-on-windows">
<title>Installing OTRS on Microsoft Windows systems</title>

<para>
Installing OTRS on a Microsoft Window system is very easy. Download the latest
installer for Win32 from

<ulink url="http://www.otrs.org/download/">
<citetitle>http://www.otrs.org/download/</citetitle>
</ulink>

and save the file to your local file system. Then simply click on the file
to execute the installer. Follow the few installation steps to setup the
system, after installation you should be able to login as OTRS
administrator.
</para>

<important>
<para>
The Win32 installer for OTRS contains all needed components for the trouble
ticket system. That means, that also the <application>apache2</application>
web server, the <application>MySQL</application> database server,
<application>Perl</application> with all needed modules and
<application>cron</application> for Windows will be installed. For that reason
you should only install OTRS on Windows systems that don't already have
 <application>apache2</application> or another web server and
<application>MySQL</application> installed.
</para>
</important>

</sect2>

</sect1>

<sect1 id="manual-installation-of-otrs">
<title>Installation from source (Linux, Unix)</title>

<sect2 id="preparing-manual-installation">
<title>Preparing the installation from source</title>

<para>
If you want to install OTRS from source, first download the source archive as .tar.gz,
.tar.bz2, or .zip file from

<ulink url="http://www.otrs.org/download/">
<citetitle>http://www.otrs.org/download/</citetitle>
</ulink>
</para>

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

<para>
<screen>
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#
</screen>
</para>

<para>
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 <filename>/opt/otrs</filename>. 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:
</para>

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

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

<para>
<screen>
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
</screen>
</para>

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

<para>
<cmdsynopsis>
  <command>SetPermissions.sh</command>
    <arg choice='req'>
      <replaceable>Home directory of the OTRS user</replaceable>
    </arg>
    <arg choice='req'>
      <replaceable>OTRS user</replaceable>
    </arg>
    <arg choice='req'>
      <replaceable>Web server user</replaceable>
    </arg>
    <arg choice='opt'>
      <replaceable>Group of the OTRS user</replaceable>
    </arg>
    <arg choice='opt'>
      <replaceable>Group of the web server user</replaceable>
    </arg>
  </cmdsynopsis>
</para>

<para>
If your web server is running with the same user rights as OTRS, the command
to set the proper access rights is
<command>SetPermissions.sh /opt/otrs otrs otrs</command>. 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 <command>SetPermissions.sh /opt/otrs otrs wwwrun nogroup www</command> to set
the proper access rights.
</para>

</sect2>

<sect2 id="installation-of-perl-modules">
<title>Installation of Perl modules</title>

<para>
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 (<application>yast</application>,
<application>apt-get</application>) 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.
</para>

<para>
OTRS requires the following additional Perl modules:
</para>

<para>

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

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

<para>
<screen>
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#
</screen>
</para>

<para>
To install one of the modules from above via CPAN, you have to execute the
command <command>perl -e shell -MCPAN</command>. 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
<command>install</command> 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.
</para>


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

<para>
<screen>
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#
</screen>
</para>

</sect2>

<sect2 id="web-server-configuration">
<title>Configuring the apache web server</title>

<para>
This section describes the basic configuration of the
<application>apache</application> 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.
</para>

<para>
LoadModule cgi_module /usr/lib/apache2/modules/mod_cgi.so
</para>


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


<para>
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
<screen>
# --
# 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
&lt;IfModule mod_perl.c&gt;

    # 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
    &lt;Location /otrs&gt;
#        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
    &lt;/Location&gt;

&lt;/IfModule&gt;

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

# MaxRequestsPerChild (so no apache child will be to big!)
MaxRequestsPerChild 400
</screen>
Apache1
apache-httpd.include.conf
<screen>
# --
# 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
&lt;IfModule mod_perl.c&gt;

    # 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

    &lt;Location /otrs&gt;
#        ErrorDocument 403 /otrs/customer.pl
        ErrorDocument 403 /otrs/index.pl
        SetHandler  perl-script
        PerlHandler Apache::Registry
        Options ExecCGI
        PerlSendHeader On
        PerlSetupEnv On
    &lt;/Location&gt;

&lt;/IfModule&gt;

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

</screen>

</para>

<para>
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 <command>/etc/init.d/apache restart</command> or
<command>/etc/init.d/apache2 restart</command>.
</para>

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

<para>
Now your web server should be configured for OTRS.
</para>

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

<para>
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.
</para>

<para>
Search your /etc/apache* directory directory for mod_perl.so
i.e.<screen> #:/ grep -Rn mod_perl.so /etc/apache*</screen>
to see if the module is already loaded somewhere, or not.
</para>

<para>
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.
</para>
</sect2>
<sect2 id="database-configuration">
<title>Configuring the database</title>

<sect3 id="installation-of-database-with-the-web-installer">
<title>The simple way - Using the web installer (works only with
<application>MySQL</application>)</title>

<para>
If you are using <application>MySQL</application> for database back-end, you
can easily configure the OTRS database via a web front-end. Use the URL

<ulink url="http://localhost/otrs/installer.pl">
<citetitle>http://localhost/otrs/installer.pl</citetitle>
</ulink>

to access the start page of the web installer. Just follow the few steps
through the installation process.
</para>

<para>
<screenshot>
<screeninfo>installer.pl screen - Licence (1/4)</screeninfo>
<graphic srccredit="installer.pl - screenshot" scale="40" fileref="screenshots/installer.png"></graphic>
</screenshot>
</para>

<para>
<screenshot>
<screeninfo>installer.pl screen - Create database (2/4)</screeninfo>
<graphic srccredit="installer.pl - screenshot" scale="40" fileref="screenshots/installer1.png"></graphic>
</screenshot>
</para>

<warning>
<para>
It is never a good idea to use default passwords. Please change the default
password for the OTRS database!
</para>
</warning>

<para>
<screenshot>
<screeninfo>installer.pl screen - Create Database (2/4)</screeninfo>
<graphic srccredit="installer.pl - screenshot" scale="40" fileref="screenshots/installer2.png"></graphic>
</screenshot>
</para>

<para>
<screenshot>
<screeninfo>installer.pl screen - System Settings (3/4)</screeninfo>
<graphic srccredit="installer.pl - screenshot" scale="40" fileref="screenshots/installer3.png"></graphic>
</screenshot>
</para>

<para>
<screenshot>
<screeninfo>installer.pl screen - Finished (4/4)</screeninfo>
<graphic srccredit="installer.pl - screenshot" scale="40" fileref="screenshots/installer4.png"></graphic>
</screenshot>
</para>

</sect3>

<sect3 id="manual-installation-of-database">
<title>Installing the OTRS database manually</title>

<para>
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 <filename>scripts/database</filename> in the
home directory of the OTRS user.
</para>

<para>
<screen>
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#
</screen>
</para>

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

<para>
<orderedlist numeration="arabic">
<title>Create the OTRS database manually step by step</title>
<listitem>
<para>
Creating the DB: Create the database, that you want to use for OTRS, with
your database client or your database interface.
</para>
</listitem>
<listitem>
<para>
Creating the tables: With the otrs-schema.DatabaseType.sql files
(e.g.. <filename>otrs-schema.oracle.sql</filename>,
<filename>otrs-schema.postgresql.sql</filename>) you can create the tables
in your OTRS database.
</para>
</listitem>
<listitem>
<para>
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
<filename>otrs-initial_insert.mysql.sql</filename>,
<filename>otrs-initial_insert.db2.sql</filename>,
<filename>otrs-initial_insert.oracle.sql</filename>,
<filename>otrs-initial_insert.postgresql.sql</filename> or
<filename>otrs-initial_insert.mssql.sql </filename>.
</para>
</listitem>
<listitem>
<para>
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. <filename>otrs-schema-oracle.post.sql</filename>,
<filename>otrs-schema-post.postgresql.sql</filename>).
</para>
</listitem>
</orderedlist>
</para>

<para>
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.
</para>

<para>
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
<filename>Kernel/Config.pm</filename> in the home directory of the OTRS
user and change the following parameters to your needs:
</para>

<para>
<programlisting>

    # 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';

</programlisting>
</para>

</sect3>

</sect2>

<sect2 id="cronjobs">
<title>Setting up the cron jobs for OTRS</title>

<para>
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.
</para>

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

<para>
<screen>
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#
</screen>
</para>

<para>
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.
</para>

<para>
<screen>
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#
</screen>
</para>

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

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

<para>
To setup all cron jobs the script <filename>bin/Cron.sh</filename> 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:
</para>

<para>
<cmdsynopsis>
  <command>Cron.sh</command>
    <arg choice='req'>
      <replaceable>start</replaceable>
    </arg>
    <arg choice='req'>
      <replaceable>stop</replaceable>
    </arg>
    <arg choice='req'>
      <replaceable>restart</replaceable>
    </arg>
    <arg choice='opt'>
      <replaceable>OTRS user</replaceable>
    </arg>
  </cmdsynopsis>
</para>

<para>
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
<command>su otrs</command>. Execute the following command to install the
cronjobs:
</para>

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

<para>
<screen>
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 - &lt;$Revision: 1.28 $&gt;
Copyright (C) 2001-2009 OTRS AG, http://otrs.org/
(using /opt/otrs) done
linux:~/bin$ exit
exit
linux:/opt/otrs/bin#
</screen>
</para>

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

<para>
<screen>
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 &gt;&gt; /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 &gt;&gt; /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" &gt;&gt; /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 &gt;&gt; /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 &gt;&gt; /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 &amp; /etc/init.d/otrs cleanup &gt;&gt; /dev/null; test -e /etc/rc.d/init.d/otrs &amp;&amp; /etc/rc.d/init.d/otrs cleanup &gt;&gt; /dev/null
10 0 * * * $HOME/bin/otrs.cleanup &gt;&gt; /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 &gt;&gt; /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 &gt;&gt; /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 &gt;&gt; /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 &gt;&gt; /dev/null

linux:/opt/otrs/bin#
</screen>
</para>

</sect2>

</sect1>

<sect1 id="upgrade">
<title>Upgrading the OTRS Frameworks</title>
<para>
These instructions are for people upgrading OTRS from "2.3" to "2.4".
</para>
<para>
If you are running a lower version of OTRS you need to follow the upgrade path
to 2.4 first (1.1-&gt;1.2-&gt;1.3-&gt;2.0-&gt;2.1-&gt;2.2-&gt;2.3-&gt;2.4 ...).
</para>

<sect2 id="upgrade-tar-gz">
  <title>Upgrading .tar.gz</title>

  <para>
  This section shows you how to upgrade OTRS from "2.3" to "2.4" with .tar.gz.
  </para>
  <itemizedlist>
      <listitem>
        <para>
Stop all your services
        </para>
        <para>
    e. g. (depends on used services):
        </para>
        <para>
    shell&gt; /etc/init.d/cron stop
        </para>
        <para>
    shell&gt; /etc/init.d/postfix stop
        </para>
        <para>
    shell&gt; /etc/init.d/apache stop
        </para>
        <para>
    shell&gt; /etc/init.d/mysql stop
        </para>
      </listitem>
      <listitem>
        <para>
Backup everything below $OTRS_HOME (default: OTRS_HOME=/opt/otrs). Kernel/Config.pm, Kernel/Config/GenericAgent.pm, Kernel/Config/Files/ZZZAuto.pm, var/*, as well as the database.
        </para>
      </listitem>
      <listitem>
        <para>
Make sure that you have backed up everything.
        </para>
      </listitem>
      <listitem>
        <para>
Try this install on a separate machine, on a test machine first.
        </para>
      </listitem>
      <listitem>
        <para>
Install the new release tar.gz
        </para>
        <para>
Note: The OTRS themes between 2.3 and 2.4 are _not_ compatible (don't use the old themes)!
        </para>
      </listitem>
      <listitem>
        <para>
Execute $OTRS_HOME/bin/SetPermissions.pl!
        </para>
      </listitem>
      <listitem>
        <para>
Update the database changes with (part 1/2)
        </para>
        <para>
MySQL: cat $OTRS_HOME/scripts/DBUpdate-to-2.4.mysql.sql | mysql -p -f -u root otrs
        </para>
        <para>
PostgreSQL: cat $OTRS_HOME/scripts/DBUpdate-to-2.4.postgresql.sql | psql otrs
        </para>
      </listitem>
      <listitem>
        <para>
Run the migration script (as OTRS user, _not_ as root):
You must execute the migration script to migrate some data from the old database
structure to the new one. Run $OTRS_HOME/scripts/DBUpdate-to-2.4.pl!
        </para>
      </listitem>
      <listitem>
        <para>
Update the database changes with (part 2/2):
        </para>
        <para>
MySQL: cat $OTRS_HOME/scripts/DBUpdate-to-2.4-post.mysql.sql | mysql -p -f -u root otrs
        </para>
        <para>
PostgreSQL: cat $OTRS_HOME/scripts/DBUpdate-to-2.4-post.postgresql.sql | psql otrs
        </para>
      </listitem>
      <listitem>
        <para>
Restart your services
        </para>
        <para>
    e. g. (depends on used services):
        </para>
        <para>
<screen>
shell&gt; /etc/init.d/mysql stop
</screen>
        </para>
        <para>
<screen>
shell&gt; /etc/init.d/apache stop
</screen>
        </para>
        <para>
<screen>
shell&gt; /etc/init.d/postfix stop
</screen>
        </para>
        <para>
<screen>
shell&gt; /etc/init.d/cron stop
</screen>
        </para>
      </listitem>
  </itemizedlist>
</sect2>

<sect2 id="upgrade-rpm">
<title>Upgrading RPM</title>
  <para>
  This section shows you how to upgrade OTRS from "2.3" to "2.4" with .rpm.
  </para>
  <itemizedlist>
      <listitem>
        <para>
Stop all your services
        </para>
        <para>
    e. g. (depends on used services):
        </para>
        <para>
<screen>
shell&gt; /etc/init.d/cron stop
</screen>
        </para>
        <para>
<screen>
shell&gt; /etc/init.d/postfix stop
</screen>
        </para>
        <para>
<screen>
shell&gt; /etc/init.d/apache stop
</screen>
        </para>
        <para>
<screen>
shell&gt; /etc/init.d/mysql stop
</screen>
        </para>
      </listitem>
      <listitem>
        <para>
Backup everything below $OTRS_HOME (default: OTRS_HOME=/opt/otrs). Kernel/Config.pm, Kernel/Config/GenericAgent.pm, Kernel/Config/Files/ZZZAuto.pm, var/*, as well as the database.
        </para>
      </listitem>
      <listitem>
        <para>
Make sure that you have backed up everything.
        </para>
      </listitem>
      <listitem>
        <para>
Try this install on a separate machine, on a test machine first.
        </para>
      </listitem>
      <listitem>
        <para>
Install the new release RPM
        </para>
        <para>
<screen>
shell&gt; rpm -Uvh otrs-2.4.x-noarch.rpm
</screen>
        </para>
        <para>
Note: The OTRS themes between 2.3 and 2.4 are _not_ compatible (don't use the old themes)!
        </para>
      </listitem>
      <listitem>
        <para>
Update the database changes with (part 1)
        </para>
        <para>
MySQL: cat $OTRS_HOME/scripts/DBUpdate-to-2.4.mysql.sql | mysql -p -f -u root otrs
        </para>
        <para>
PostgreSQL: cat $OTRS_HOME/scripts/DBUpdate-to-2.4.postgresql.sql | psql otrs
        </para>
      </listitem>
      <listitem>
        <para>
Run the migration script (as OTRS user, _not_ as root):
You must execute the migration script to migrate some data from the old database
structure to the new one. Run $OTRS_HOME/scripts/DBUpdate-to-2.4.pl!
        </para>
      </listitem>
      <listitem>
        <para>
Update the database changes with (part 2):
        </para>
        <para>
MySQL: cat $OTRS_HOME/scripts/DBUpdate-to-2.4-post.mysql.sql | mysql -p -f -u root otrs
        </para>
        <para>
PostgreSQL: cat $OTRS_HOME/scripts/DBUpdate-to-2.4-post.postgresql.sql | psql otrs
        </para>
      </listitem>
      <listitem>
        <para>
Restart your services
        </para>
        <para>
    e. g. (depends on used services):
        </para>
        <para>
<screen>
shell&gt; /etc/init.d/mysql stop
</screen>
        </para>
        <para>
<screen>
shell&gt; /etc/init.d/apache stop
</screen>
        </para>
        <para>
<screen>
shell&gt; /etc/init.d/postfix stop
</screen>
        </para>
        <para>
<screen>
shell&gt; /etc/init.d/cron stop
</screen>
        </para>
      </listitem>
  </itemizedlist>
</sect2>

<!--
<sect2 id="upgrade-windows-installer">
<title>Upgrading Windows Installer</title>
<para>
</para>
</sect2>
-->

</sect1>

</chapter>