<?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.8 2006/05/15 10:05:08 cs Exp $ -->

<chapter id="installation-and-basic-configuration">
<title>Installation 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
manually from source or with a binary package, ex. rpm or for Win32.
</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 config 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 prebuilt packages</title>

<para>
The simplest and most comfortable way to install OTRS is to use prebuilt
packages. Many prebuilt 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 prebuilt
or binary package on SUSE, Debian and Microsoft Windows systems. Use
prebuilt 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 distro</title>

<para>
This section describes the installation of a prebuilt 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 webserver.

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

[install the OTRS database]
 Use a webbrowser 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 webserver 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 backend, 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 - 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>

<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 admin and configure the system for your
needs. To log in as OTRS admin use the username root@localhost and the
password root.
</para>

<warning>
<para>
Please change the pasword for the OTRS admin as soon as possible. It is
also a default password!
</para>
</warning>

</sect2>

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

<para>
This section Describes the installation of OTRS on Debian 3.1 (Sarge).
</para>

<para>
Install OTRS with <application>apt-get</application> via the command line.
OTRS needs some other packages to be installed, for example a database
server, a web server or some perl modules. Let
<application>apt-get</application> take care of these dependences. Execute
the following command to install OTRS:
</para>

<para>
<screen>
linux:~# apt-get install otrs
Reading Package Lists... Done
Building Dependency Tree... Done
Suggested packages:
  otrs-doc
The following NEW packages will be installed:
  otrs
0 upgraded, 1 newly installed, 0 to remove and 0 not upgraded.
Need to get 947kB of archives.
After unpacking 6132kB of additional disk space will be used.
Get:1 ftp://ftp.uni-erlangen.de sarge/main otrs 1.3.2p01-5 [947kB]
Fetched 947kB in 10s (93.7kB/s)
Selecting previously deselected package otrs.
(Reading database ... 73351 files and directories currently installed.)
Unpacking otrs (from .../otrs_1.3.2p01-5_all.deb) ...
Setting up otrs (1.3.2p01-5) ...
Adding system user `otrs'...
Adding new user `otrs' (105) with group `www-data'.
Not creating home directory.
SetPermissions.sh &lt;$Revision: 1.8 $&gt; - set OTRS file permissions
Copyright (c) 2001-2003 Martin Edenhofer &lt;martin@otrs.org&gt;
Setting file permissions...
chown -R 0:0 /usr/share/otrs
chown otrs:www-data /usr/share/otrs
chown -R otrs:www-data /usr/share/otrs/var/
chown -R www-data:www-data /usr/share/otrs/var/sessions/
touch &amp;&amp; chown otrs:www-data
/usr/share/otrs/var/log/TicketCounter.log
chmod -R 755 /usr/share/otrs/bin/
(chown &amp;&amp; chmod 700) otrs:0
/usr/share/otrs/bin/DeleteSessionIDs.pl
(chown &amp;&amp; chmod 700) otrs:0 /usr/share/otrs/bin/UnlockTickets.pl
(chown &amp;&amp; chmod 700) otrs:0 /usr/share/otrs/bin/otrs.getConfig

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

<para>
After the installation of the OTRS package you need to configure the
webserver for the trouble ticket system (on debian systems this is not done
automaticly).
</para>

<important>
<para>
The following description is based on the fact, that you use the web server
<application>apache</application> 2.x. If you are using
<application>apache</application> 1.3.x you have to do the same things. The
configuration files of <application>apache</application> 1.3.x are
located at <filename>/etc/apache</filename>.
</para>
</important>

<para>
Create the file <filename>otrs.conf</filename> and insert the following
lines. Save the file into the directory
<filename>/etc/apache2/conf.d</filename>.
</para>

<para>
<programlisting id="basic-apache-config-under-debian">
#
# Basic apache configuration file for OTRS
#
# agent, admin and customer frontend
#
ScriptAlias /otrs/ "/usr/share/otrs/bin/cgi-bin/"
Alias /otrs-web/ "/usr/share/otrs/var/httpd/htdocs/"
#
&lt;Directory "/usr/share/otrs/bin/cgi-bin/"&gt;
    AllowOverride None
    Options +ExecCGI -Includes
    Order allow,deny
    Allow from all
&lt;/Directory&gt;
&lt;Directory "/usr/share/otrs/var/httpd/htdocs/"&gt;
    AllowOverride None
    Order allow,deny
    Allow from all
&lt;/Directory&gt;
</programlisting>
</para>

<para>
Restart your webserver to use the new config settings.
</para>

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

<para>
In the next step you have to setup the OTRS database. If you use
<application>MySQL</application> for the database backend, 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 - 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>

<para>
Now the installation of OTRS is finished. You should be able to use the web
interface of OTRS. The cron jobs, which are needed for OTRS, are
automaticallyi
installed and configured. Log in as OTRS admin and configure the system for
your needs. Go to the address

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

with a web browser and use "root@localhost" as username and "root" as password
to access the web interface of the ticket system.
</para>

<warning>
<para>
Please change this password as soon as possible too! It is also a default
password!
</para>
</warning>

</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/">
<citetitle>http://www.otrs.org</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 have to install OTRS from source, first download the .tar.gz or
.tar.bz2 file with the sources from

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

please.
</para>

<para>
Unpack the archive for example with <command>tar</command> e.g. into the
directory <filename>/opt</filename>:
</para>

<para>
<screen>
linux:/opt# tar xf /tmp/otrs-2.0.0.tar.gz
linux:/opt# ls
otrs
linux:/opt#
</screen>
</para>

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

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

<para>
Now some demo config files of OTRS have to be copied. 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 ending .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# for foo in *.dist; do cp $foo `basename
$foo .dist`; done
linux:/opt/otrs/Kernel/Config#
</screen>
</para>

<para>
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
<command>SetPermissions.sh</command>, which is located in the
<filename>bin</filename> directory in the home directory of the OTRS user.
The script can be executed 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>
Is your web server 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. You would use the
command <command>SetPermissions.sh /opt/otrs otrs wwwrun</command> to set
the proper access rights.
</para>

</sect2>

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

<para>
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 (<application>yast</application>,
<application>apt-get</application>) or, like described in this section,
through the perl shell and CPAN.
</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 backend.
        </entry>
      </row>
      <row>
        <entry>
          DBD::mysql
        </entry>
        <entry>
          Module with special functions to connect to the MySQL
          database backend.
        </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>
          This module makes it possible to process emails based on the
          RFC 822 standard.
        </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::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 mailservers.
        </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>
          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>
    </tbody>
  </tgroup>
</table>

</para>

<para>
To install one of the modules from above with 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>
After you have installed all modules you can use the script
<command>otrss.checkModules</command> to check if OTRS has all needed perl
modules. 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
                  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#
</screen>
</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", you have a proper perl installation to use
with OTRS.
</para>

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

</sect2>

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

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

<para>
<programlisting id="load-cgi-module">
LoadModule cgi_module /usr/lib/apache2/modules/mod_cgi.so
</programlisting>
</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 and change to the
<filename>conf.d</filename> directory and open/create a file called
<filename>otrs.conf</filename>. Insert the following lines into this file:
</para>

<para>
<programlisting id="basic-apache-configuration-for-otrs">
#
# 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
#
&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;
</programlisting>
</para>

<para>
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 <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 webserver should be basicaly configured for OTRS.
</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
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#
</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 either the file
<filename>initial_insert.sql</filename> or
<filename>initial_insert.sapdb.sql</filename> to insert the initial data.
</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>

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

<para>
<screen>
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#
</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
Cron.sh - start/stop OTRS cronjobs - &lt;$Revision: 1.8 $&gt;
Copyright (c) 2002 Martin Edenhofer &lt;martin@otrs.org&gt;
(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) 2002-2003 Martin Edenhofer &lt;martin+code@otrs.org&gt;
# --
# $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 &lt;martin+code@otrs.org&gt;
# --
# $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 &gt;&gt; /dev/null

# --
# cron/generic_agent - GenericAgent.pl cron of the OTRS
# Copyright (C) 2002-2003 Martin Edenhofer &lt;martin+code@otrs.org&gt;
# --
# $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 &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-2004 Martin Edenhofer &lt;martin+code@otrs.org&gt;
# --
# $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 &gt;&gt; /dev/null
# --
# cron/pending_jobs - pending_jobs cron of the OTRS
# Copyright (C) 2002-2003 Martin Edenhofer &lt;martin+code@otrs.org&gt;
# --
# $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 &gt;&gt; /dev/null
# --
# cron/postmaster - postmaster cron of the OTRS
# Copyright (C) 2002-2003 Martin Edenhofer &lt;martin+code@otrs.org&gt;
# --
# $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 &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) 2002-2003 Martin Edenhofer &lt;martin+code@otrs.org&gt;
# --
# $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 &gt;&gt; /dev/null
# --
# cron/rebuild_ticket_index - rebuild ticket index for OTRS
# Copyright (C) 2002-2003 Martin Edenhofer &lt;martin+code@otrs.org&gt;
# --
# $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 &gt;&gt; /dev/null

# --
# cron/session - delete old session ids of the OTRS
# Copyright (C) 2001-2004 Martin Edenhofer &lt;martin+code@otrs.org&gt;
# --
# $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 &gt;&gt; /dev/null

# --
# cron/unlock - unlock old locked ticket of the OTRS
# Copyright (C) 2002-2003 Martin Edenhofer &lt;martin+code@otrs.org&gt;
# --
# $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 &gt;&gt; /dev/null

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

</sect2>

</sect1>

</chapter>