<?xml version='1.0' encoding='UTF-8'?>
<!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.70 2012/02/23 09:19:52 mb Exp $ -->

<chapter id="installation">
<title>Installation</title>

<abstract>
<para>
This chapter describes the installation and basic configuration of the central OTRS framework. It covers information on installing OTRS from source, or with a binary package such as an RPM or a Windows exectuable.
</para>

<para>
Topics covered here include configuration of the web and database servers, the interface between OTRS and the database, the installation of additional Perl modules, setting proper access rights for OTRS, setting up the cron jobs for OTRS, and some basic settings in the OTRS configuration files.
</para>

<para>
Follow the detailed steps in this chapter to install OTRS on your server. You can then use its web interface to login and administer the system.
</para>
</abstract>

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

<para>
You should use pre-built packages to install OTRS, since it is the simplest and most convenient method. You can find them in the download area at
<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. Only if you are unable to use the pre-built packages for some reason should you follow the manual process.
</para>

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

<para>
This section demonstrates the installation of a pre-built RPM package on a SUSE Linux distro. We have tested against all recent SLES and openSUSE versions. Before you start the installation, please have a look at
<ulink url="http://www.otrs.org/downloads">
	<citetitle>http://www.otrs.org/downloads</citetitle>
</ulink>
and check if a newer OTRS RPM package is available. Always use the latest RPM package.
</para>

<para>
Install OTRS with <application>yast</application> (yast2) or via the command line and <command>rpm</command>. OTRS needs some Perl modules which are not installed on a SUSE system by default, and so we recommend using <application>yast</application>, since it addresses the package dependencies automatically.
</para>

<para>
If you decide to install OTRS via the command line and <command>rpm</command>, first you have to manually install the needed Perl modules. Assuming you saved the file <filename>otrs.rpm</filename> in the directory <filename>/tmp</filename>, you can execute the command specified in the following script to install OTRS.
</para>

<para>
<screen>
linux:~ # rpm -i /tmp/otrs-xxx.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>
<emphasis>Script: Command to install OTRS.</emphasis>
</para>

<para>
After the installation of the OTRS RPM package, you have to run <application>SuSEconfig</application>, as shown in the following script.
</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>
<emphasis>Script: Running the SuSEconfig command.</emphasis>
</para>

<para>
The OTRS installation is done. Restart your web server to load the OTRS specific changes in its configuration, as shown in the script below.
</para>

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

<para>
<emphasis>Script: Restarting the web server.</emphasis>
</para>

<para>
The next step is to setup the OTRS database, as described at <link linkend="database-configuration">section 3.2.4.</link>
</para>

</section>

<section id="installation-on-centos">
<title>Installing OTRS on a CentOS system</title>

<para>
On the OTRS Wiki you can find detailed instructions for setting up OTRS on a CentOS system. Please note that these instructions will also apply to Red Hat Linux systems since they use the same source:
<ulink url="http://wiki.otrs.org/index.php?title=Installation_of_OTRS_3.0b1_on_CentOS_5.5">
http://wiki.otrs.org/index.php?title=Installation_of_OTRS_3.0b1_on_CentOS_5.5
</ulink>
.
</para>

</section>

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

<para>
On the OTRS Wiki you can find detailed instructions for setting up OTRS on a Debian system:
<ulink url="http://wiki.otrs.org/index.php?title=Installation_on_Debian_5.04_lenny">
http://wiki.otrs.org/index.php?title=Installation_on_Debian_5.04_lenny
</ulink>
.
</para>

</section>

<section id="installation-on-ubuntu">
<title>Installing OTRS on a Ubuntu system</title>

<para>
On the OTRS Wiki you can find detailed instructions for setting up OTRS on an Ubuntu system:
<ulink url="http://wiki.otrs.org/index.php?title=Installation_on_Ubuntu_Lucid_Lynx_(10.4)">
http://wiki.otrs.org/index.php?title=Installation_on_Ubuntu_Lucid_Lynx_(10.4)
</ulink>
.
</para>

</section>

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

<para>
Installing OTRS on a Microsoft Windows system is very easy. Download the latest installer for Win32 from
<ulink url="http://www.otrs.org/downloads/">
	<citetitle>http://www.otrs.org/downloads/</citetitle>
</ulink>
and save the file to your local file system. Then simply double-click on the file to execute the installer, and follow the few installation steps to setup the system. After that you will be able to login as OTRS administrator and
configure the system according to 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>

<important>
<para>
The Win32 installer for OTRS contains all needed components for OTRS, i.e. the <application>Apache</application>
web server, the <application>MySQL</application> database server, <application>Perl</application> (with all needed modules) and <application>Cron</application> for Windows. For that reason you should only install OTRS on Windows systems that don't already have an installation of <application>Apache</application> or another web server, or
<application>MySQL</application>.
</para>
</important>

</section>

</section>

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

<section 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/downloads/">
<citetitle>http://www.otrs.org/downloads/</citetitle>
</ulink>
</para>

<para>
Unpack the archive (for example, using <command>tar</command>) into the directory <filename>/opt</filename>, and rename the directory from otrs-3.1.x to otrs (see Script below).
</para>

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

<para>
<emphasis>Script: First steps to install OTRS.</emphasis>
</para>

<para>
OTRS should NOT be run 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 (see Script below).
</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>
<emphasis>Script: Adding a new user 'otrs', and adding it to a group.</emphasis>
</para>

<para>
Next, 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 (see Script below).
</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>
<emphasis>Script: Copying some sample files.</emphasis>
</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>otrs.SetPermissions.pl</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>otrs.SetPermissions.pl</command>
    <arg choice='req'>
      <replaceable>Home directory of the OTRS user</replaceable>
    </arg>
    <arg choice='req'>
      --otrs-user=
      <replaceable>OTRS user</replaceable>
    </arg>
    <arg choice='req'>
      --web-user=
      <replaceable>Web server user</replaceable>
    </arg>
    <arg choice='opt'>
      --otrs-group=
      <replaceable>Group of the OTRS user</replaceable>
    </arg>
    <arg choice='opt'>
      --web-group=
      <replaceable>Group of the web server user</replaceable>
    </arg>
  </cmdsynopsis>
</para>

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

</section>

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

<para>
OTRS needs some additional Perl modules, as described in Table 3-1. If you install OTRS from source, you will have to install these modules manually. This can be done either with the package manager of your Linux distribution (<application>yast</application>, <application>apt-get</application>) or, as 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. We recommend using your package manager if possible.
</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>
          DBI
        </entry>
        <entry>
          Establishes a connection to the database back-end.
        </entry>
      </row>
      <row>
        <entry>
          DBD::mysql
        </entry>
        <entry>
          Contains special functions to connect to the MySQL
          database back-end (only required if MySQL is used).
        </entry>
      </row>
      <row>
        <entry>
          DBD::pg
        </entry>
        <entry>
          Contains special functions to connect to the PostgreSQL
          database back-end (only required if PostgreSQL is used).
        </entry>
      </row>
      <row>
        <entry>
          Digest::MD5
        </entry>
        <entry>
          Allows the use of the md5 algorithm.
        </entry>
      </row>
      <row>
        <entry>
          CSS::Minifier
        </entry>
        <entry>
          Minifies a CSS file and writes the output directly to another file.
        </entry>
      </row>
      <row>
        <entry>
          Crypt::PasswdMD5
        </entry>
        <entry>
          Provides interoperable MD5-based crypt functions.
        </entry>
      </row>
      <row>
        <entry>
          MIME::Base64
        </entry>
        <entry>
          Encodes / decodes Base64 strings, e.g. for mail attachments.
        </entry>
      </row>
      <row>
        <entry>
          JavaScript:Minifier
        </entry>
        <entry>
          Minifies a JavaScript file and writes the output directly to another file.
        </entry>
      </row>
      <row>
        <entry>
          Net::DNS
        </entry>
        <entry>
          Perl interface to the domain name system.
        </entry>
      </row>
      <row>
        <entry>
          LWP::UserAgent
        </entry>
        <entry>
          Processes HTTP requests.
        </entry>
      </row>
      <row>
        <entry>
          Net::LDAP
        </entry>
        <entry>
          Perl interface to a LDAP directory (only required if an LDAP back-end is used).
        </entry>
      </row>
      <row>
        <entry>
          GD
        </entry>
        <entry>
          Interface to the GD graphics library (only required if the OTRS stats
          module is used).
        </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 (only
          required if the OTRS stats module is used).
        </entry>
      </row>
      <row>
        <entry>
          PDF::API2, Compress::Zlib
        </entry>
        <entry>
          Needed to generate the PDF output for reports, search results and 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.pl</command>. This script is located in the <filename>bin</filename> directory, in the home directory of the 'otrs' user (see Script below).
</para>

<para>
Please note that some modules are optional.
</para>

<para>
<screen>
linux:~# cd /opt/otrs/bin/
linux:/opt/otrs/bin# ./otrs.CheckModules.pl
   o CGI............................ok (v3.49)
   o Crypt::PasswdMD5...............ok (v1.3)
   o CSS::Minifier..................ok (v0.01)
   o Date::Format...................ok (v2.24)
   o Date::Pcalc....................ok (v1.2)
   o DBI............................ok (v1.609)
   o DBD::mysql.....................ok (v4.013)
   o Digest::MD5....................ok (v2.36_01)
   o Encode::HanExtra...............ok (v0.23)
   o GD.............................ok (v2.44)
      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 IO::Scalar.....................ok (v2.110)
   o IO::Wrap.......................ok (v2.110)
   o JavaScript::Minifier...........ok (v1.05)
   o JSON...........................ok (v2.21)
      o JSON::PP....................ok (v2.27003)
      o JSON::XS....................Not installed! (Optional - Install it for faster AJAX/JavaScript handling.)
   o LWP::UserAgent.................ok (v5.829)
   o Mail::Internet.................ok (v2.06)
   o Mail::POP3Client...............ok (v2.18 )
      o IO::Socket::SSL.............ok (v1.31)
   o MIME::Base64...................ok (v3.07_01)
   o MIME::Tools....................ok (v5.428)
   o Net::DNS.......................ok (v0.65)
   o Net::POP3......................ok (v2.29)
   o Net::IMAP::Simple..............ok (v1.1916)
      o Net::IMAP::Simple::SSL......ok (v1.3)
   o Net::SMTP......................ok (v2.31)
      o Authen::SASL................ok (v2.15)
      o Net::SMTP::SSL..............ok (v1.01)
   o Net::LDAP......................ok (v0.4001)
   o PDF::API2......................ok (v0.73)
      o Compress::Zlib..............ok (v2.008)
   o SOAP::Lite.....................ok (v0.712)
   o Text::CSV......................ok (v1.18)
      o Text::CSV_PP................ok (v1.26)
      o Text::CSV_XS................Not installed! (Optional - Optional, install it for faster CSV handling.)
   o XML::Parser....................ok (v2.36)
linux:/opt/otrs/bin#
</screen>
</para>

<para>
<emphasis>Script: Checking needed modules.</emphasis>
</para>

<para>
You should strive to install the missing modules from your Linux distribution's package management system. In that way, the packages will be automatically updated when new versions are available or when security issues are found. Please refer
to your distribution's documentation on how to install additional packages. If the (correct version of) the module is not available from the package repositories, you can also install from CPAN, the Comprehensive Perl Archive Network.
</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 will let you know if other modules are needed.
</para>

<para>
    Execute also the commands
    <command>perl -cw bin/cgi-bin/index.pl</command>
    <command>perl -cw bin/cgi-bin/customer.pl</command>
    and <command>perl -cw bin/otrs.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 (see Script below).
</para>

<para>
<screen>
linux:~# cd /opt/otrs
linux:/opt/otrs# perl -cw bin/cgi-bin/index.pl
cgi-bin/installer.pl syntax OK
linux:/opt/otrs# perl -cw bin/cgi-bin/customer.pl
cgi-bin/customer.pl syntax OK
linux:/opt/otrs# perl -cw bin/otrs.PostMaster.pl
bin/otrs.PostMaster.pl syntax OK
linux:/opt/otrs#
</screen>
</para>
<para>
<emphasis>Script: Syntax check.</emphasis>
</para>

</section>

<section 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 with mod_cgi for OTRS. 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 conveniently via a short address, Alias and ScriptAlias entries are 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 in <filename>/opt/otrs/scripts/apache2-httpd.include.conf</filename> to a file called <filename>otrs.conf</filename> in the Apache configuration directory.
</para>

<para>
Restart your web server to load the new configuration settings. On most systems you can start/restart your web server
with the command <command>/etc/init.d/apache2 restart</command> (see Script below).
</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>
<emphasis>Script: Restarting the web server.</emphasis>
</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 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 for mod_perl.so (see Script below) to see if the module is already loaded.
</para>

<para>
<screen> #:/ grep -Rn mod_perl.so /etc/apache*</screen>
</para>

<para>
<emphasis>Script: Searching for mod_perl.</emphasis>
</para>

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

<section id="database-configuration">
<title>Configuring the database</title>

<section 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 use <application>MySQL</application> as the database back-end, you can use the OTRS web installer:
<ulink url="http://localhost/otrs/installer.pl">
	<citetitle>http://localhost/otrs/installer.pl</citetitle>
</ulink>
.</para>

<para>
When the web installer starts, please follow the next steps to setup your system:
</para>

<para>
1. Check out the information about the OTRS offices and click on next to continue (see Figure below).
</para>

<para>
<screenshot>
<screeninfo>installer.pl screen - Welcome screen</screeninfo>
<graphic srccredit="installer.pl - screenshot" scale="40" fileref="screenshots/installer1.png"></graphic>
</screenshot>
</para>

<para>
<emphasis>Figure: Welcome screen.</emphasis>
</para>

<para>
2. Read the GNU Affero General Public License (see Figure below) and accept it, by clicking the corresponding button at the bottom of the page.
</para>

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

<para>
<emphasis>Figure: GNU Affero General Public License.</emphasis>
</para>

<para>
3. Provide the username and password of the administrator, the DNS name of the computer which hosts OTRS and the type of database system to be used. After that, check the settings (see Figure below).
</para>

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

<para>
<emphasis>Figure: Database initial settings.</emphasis>
</para>

<para>
You will be notified if the check was successful. Press OK to continue (see Figure below).
</para>

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

<para>
<emphasis>Figure: Notification for successful check.</emphasis>
</para>

<para>
4. Create a new database user, choose a name for the database and click on 'Next' (see Figure below).
</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) all settings</screeninfo>
<graphic srccredit="installer.pl - screenshot" scale="40" fileref="screenshots/installer5.png"></graphic>
</screenshot>
</para>

<para>
<emphasis>Figure: Database settings.</emphasis>
</para>

<para>
If the database and its user were successfully created, you will get a setup notification, as shown in Figure. Click 'Next' to go to the next screen.
</para>

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

<para>
<emphasis>Figure: Notification indicating successful database setup.</emphasis>
</para>

<para>
5. Provide all the required system settings and click on 'Next' (see Figure below).
</para>

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

<para>
<emphasis>Figure: System settings.</emphasis>
</para>

<para>
6. If you want, you can provide the needed data to configure your inbound and outbound mail, or skip this step by pressing the right button at the bottom of the screen (see Figure below).
</para>

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

<para>
<emphasis>Figure: Mail configuration.</emphasis>
</para>

<para>
7. Restart the OTRS service now to use the new configuration settings as shown in the script below.
</para>

<para>
<screen>
linux:~ # rcotrs restart-force
Shutting down OTRS
 Disable /opt/otrs/bin/otrs.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/otrs.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>
<emphasis>Script: Restarting the OTRS service.</emphasis>
</para>

<para>
Congratulations! Now the installation of OTRS is finished and you should be able to work with the system (see Figure below). 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>
from your web browser. Log in as OTRS administrator, using the username 'root@localhost' and the password 'root'. After that you can configure the system for your needs.
</para>

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

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

<para>
<emphasis>Figure: Final steps to install OTRS.</emphasis>
</para>

</section>

<section 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 (see Script below).
</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>
<emphasis>Script: Files needed to create and configure the database.</emphasis>
</para>

<para>
To setup the database for the different database back-ends, the .sql files must be processed in a specific 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.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 file to create these (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> located in the home directory of the 'otrs' user, and change the parameters shown in the script below according 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>

<para>
<emphasis>Script: Parameters to be customized.</emphasis>
</para>

</section>

</section>

<section 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 (see Script below).
</para>

<para>
<screen>
linux:~# cd /opt/otrs/var/cron
linux:/opt/otrs/var/cron# ls
aaa_base.dist                generic_agent.dist       rebuild_ticket_index.dist
cache.dist                   pending_jobs.dist        session.dist
fetchmail.dist               postmaster.dist          unlock.dist
generic_agent-database.dist  postmaster_mailbox.dist
linux:/opt/otrs/var/cron#
</screen>
</para>

<para>
<emphasis>Script: Files needed to create the cron jobs.</emphasis>
</para>

<para>
These scripts have a suffix of '.dist'. You should copy them to files with the suffix removed. If you use bash, you might want to use the command listed in Script 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-database.dist  rebuild_ticket_index
aaa_base.dist           generic_agent.dist           rebuild_ticket_index.dist
cache                   pending_jobs                 session
cache.dist              pending_jobs.dist            session.dist
fetchmail               postmaster                   unlock
fetchmail.dist          postmaster.dist              unlock.dist
generic_agent           postmaster_mailbox
generic_agent-database  postmaster_mailbox.dist
linux:/opt/otrs/var/cron#
</screen>
</para>

<para>
<emphasis>Script: Copying and renaming all the files needed to create the cron jobs.</emphasis>
</para>

<para>
Table 3-2 describes the different cron jobs.
</para>

<para>
<table id="table-of-cronjobs-for-otrs">
<title>Description of 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>
          Sets the basics for the crontab of the 'otrs' user.
        </entry>
      </row>
      <row>
        <entry>
          cache
        </entry>
        <entry>
          Removes expired cache entries from disk. Clears the loader cache for CSS and JavaScript files.
        </entry>
      </row>
      <row>
        <entry>
          fetchmail
        </entry>
        <entry>
          Used only if new mails will be fetched with fetchmail into the ticket system.
        </entry>
      </row>
      <row>
        <entry>
          generic_agent
        </entry>
        <entry>
          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>
          Executes the jobs of the GenericAgent that are stored in the database.
        </entry>
      </row>
      <row>
        <entry>
          pending_jobs
        </entry>
        <entry>
          Checks system for pending tickets, and closes them or sends reminders if needed.
        </entry>
      </row>
      <row>
        <entry>
          postmaster
        </entry>
        <entry>
          Checks the message queue of the ticket system, and delivers messages that are still in the queues.
        </entry>
      </row>
      <row>
        <entry>
          postmaster_mailbox
        </entry>
        <entry>
          Fetches the mails from the POP3 accounts that were specified in the admin area, in the section for "PostMaster Mail Accounts".
        </entry>
      </row>
      <row>
        <entry>
          rebuild_ticket_index
        </entry>
        <entry>
          Rebuilds the ticket index, which improves the speed of the QueueView.
        </entry>
      </row>
      <row>
        <entry>
          session
        </entry>
        <entry>
          Removes old and no longer needed session IDs.
        </entry>
      </row>
      <row>
        <entry>
          unlock
        </entry>
        <entry>
          Unlocks tickets in the system.
        </entry>
      </row>
    </tbody>
  </tgroup>
</table>
</para>

<para>
To setup all cron jobs, the script <filename>bin/Cron.sh</filename> located in the home directory of the 'otrs' user can be used. When this script is executed, it needs a parameter to specify whether you want 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'. If you are logged in as root, you can switch to 'otrs' with the command <command>su otrs</command>. Execute the commands specified in Script below to install the cron jobs.
</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 retain other crontab entries as needed.
</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
Copyright (C) 2001-2009 OTRS AG, http://otrs.org/
(using /opt/otrs) done
linux:~/bin$ exit
exit
linux:/opt/otrs/bin#
</screen>
</para>

<para>
<emphasis>Script: Installing the cron jobs.</emphasis>
</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 placed correctly (see Script below).
</para>

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

# --
# cron/cache - delete expired cache
# Copyright (C) 2001-2012 OTRS AG, http://otrs.org/
# This software comes with ABSOLUTELY NO WARRANTY.
# --
# delete expired cache weekly (Sunday mornings)
20 0 * * 0  $HOME/bin/otrs.CacheDelete.pl --expired >> /dev/null
30 0 * * 0  $HOME/bin/otrs.LoaderCache.pl -o delete >> /dev/null

# --
# cron/fetchmail - fetchmail cron of the OTRS
# Copyright (C) 2001-2012 OTRS AG, http://otrs.org/
# --
# 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 - otrs.GenericAgent.pl cron of the OTRS
# Copyright (C) 2001-2012 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/otrs.GenericAgent.pl -c "Kernel::Config::GenericAgentMove" &gt;&gt; /dev/null
# --
# cron/generic_agent - GenericAgent.pl cron of the OTRS
# Copyright (C) 2001-2012 OTRS AG, http://otrs.org/
# --
# This software comes with ABSOLUTELY NO WARRANTY.
# --
# start generic agent every 10 minutes
*/10 * * * * $HOME/bin/otrs.GenericAgent.pl -c db &gt;&gt; /dev/null
# --
# cron/pending_jobs - pending_jobs cron of the OTRS
# Copyright (C) 2001-2012 OTRS AG, http://otrs.org/
# --
# This software comes with ABSOLUTELY NO WARRANTY.
# --
# check every 120 min the pending jobs
45 */2 * * * $HOME/bin/otrs.PendingJobs.pl &gt;&gt; /dev/null
# --
# cron/postmaster - postmaster cron of the OTRS
# Copyright (C) 2001-2012 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.pl &gt;&gt; /dev/null
# --
# cron/postmaster_mailbox - postmaster_mailbox cron of the OTRS
# Copyright (C) 2001-2012 OTRS AG, http://otrs.org/
# --
# This software comes with ABSOLUTELY NO WARRANTY.
# --
# fetch emails every 10 minutes
*/10 * * * * $HOME/bin/otrs.PostMasterMailbox.pl &gt;&gt; /dev/null
# --
# cron/rebuild_ticket_index - rebuild ticket index for OTRS
# Copyright (C) 2001-2012 OTRS AG, http://otrs.org/
# --
# This software comes with ABSOLUTELY NO WARRANTY.
# --
# just every day
01 01 * * * $HOME/bin/otrs.RebuildTicketIndex.pl &gt;&gt; /dev/null

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

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

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

<para>
<emphasis>Script: Crontab file.</emphasis>
</para>

</section>

</section>

<section id="upgrading">
<title>Upgrading the OTRS Framework</title>
<para>
    These instructions are for people upgrading OTRS from version <emphasis>3.0</emphasis> to <emphasis>3.1</emphasis>, and apply both for RPM and source code (tarball) upgrades.
</para>
<para>
    If you are running a lower version of OTRS you have to follow the upgrade path
    to 3.0 first (1.1->1.2->1.3->2.0->2.1->2.2->2.3->2.4->3.0->3.1 ...)!
</para>
<para>
    Please note that if you upgrade from OTRS 2.2 or earlier, you have to take an extra step;
    please read <ulink url="http://bugs.otrs.org/show_bug.cgi?id=6798">http://bugs.otrs.org/show_bug.cgi?id=6798</ulink>.
</para>
<para>
    If you need to do a "patch level upgrade", which is an upgrade for instance from OTRS version 3.1.1 to 3.1.3,
    you should skip steps 8, 10 and 12-19.
</para>
<para>
    Please note that for upgrades from 3.1.beta1 or 3.1.beta2, an additional step 20
    is needed!
</para>
<para>
    If you are using Microsoft SQL Server as the DBMS for OTRS, please refer
    to the manual, chapter "Upgrading Microsoft SQL Server Data Types" for instructions
    how to upgrade the data types used by OTRS
    (<ulink url="http://doc.otrs.org/3.1/en/html/upgrading-mssql-datatypes.html">http://doc.otrs.org/3.1/en/html/upgrading-mssql-datatypes.html</ulink>).
</para>

  <orderedlist>
      <listitem>
        <para>
            Stop all relevant services.
        </para>
        <para>
            e. g. (depends on used services):
            <screen>
shell&gt; /etc/init.d/cron stop
shell&gt; /etc/init.d/postfix stop
shell&gt; /etc/init.d/apache stop
            </screen>
        </para>
      </listitem>
      <listitem>
        <para>
            Backup everything below $OTRS_HOME (default: OTRS_HOME=/opt/otrs):
            <itemizedlist>
                <listitem><para><filename>Kernel/Config.pm</filename></para></listitem>
                <listitem><para><filename>Kernel/Config/GenericAgent.pm</filename></para></listitem>
                <listitem><para><filename>Kernel/Config/Files/ZZZAuto.pm</filename></para></listitem>
                <listitem><para><filename>var/*</filename></para></listitem>
            </itemizedlist>
        </para>
      </listitem>
      <listitem>
        <para>
            Backup the database.
        </para>
      </listitem>
      <listitem>
        <para>
            Make sure that you have backed up everything ;-)
        </para>
      </listitem>
      <listitem>
        <para>
            Setup new system (optional)
        </para>
        <para>
            If possible, try this install on a separate machine for testing first.
        </para>
      </listitem>
      <listitem>
        <para>
            Install the new release (tar or RPM).
        </para>
         <itemizedlist>
          <listitem>
            <para>
                With the tarball:
            </para>
            <para>
                <screen>
shell&gt; cd /opt
shell&gt; tar -xzf otrs-x.x.x.tar.gz
shell&gt; ln -s otrs-x.x.x otrs
                </screen>
            </para>
            <para>
                Restore old configuration files.
                <itemizedlist>
                    <listitem><para><filename>Kernel/Config.pm</filename></para></listitem>
                    <listitem><para><filename>Kernel/Config/GenericAgent.pm</filename></para></listitem>
                    <listitem><para><filename>Kernel/Config/Files/ZZZAuto.pm</filename></para></listitem>
                </itemizedlist>
            </para>
          </listitem>
          <listitem>
            <para>
                With the RPM:
                <screen>
shell&gt; rpm -Uvh otrs-x.x.x.-01.rpm
                </screen>
            </para>
            <para>
                In this case the RPM update automatically restores the old configuration files.
            </para>
          </listitem>
         </itemizedlist>
      </listitem>
      <listitem>
        <para>
            Own themes
        </para>
        <para>
            Note: The OTRS themes between 3.0 and 3.1 are NOT compatible, so don't use your old themes!
        </para>
        <para>
            Themes are located under $OTRS_HOME/Kernel/Output/HTML/*/*.dtl (default: OTRS_HOME=/opt/otrs).
        </para>
      </listitem>
      <listitem>
        <para>
            Set file permissions.
        </para>
        <para>
            If the tarball is used, execute:
            <screen>
shell> cd /opt/otrs/
shell> bin/otrs.SetPermissions.pl
            </screen>
            with the permissions needed for your system setup.
        </para>
      </listitem>
      <listitem>
        <para>
            Apply the database changes (part 1/2):
        </para>
        <para>
            <screen>
shell&gt; cd /opt/otrs/

# MySQL:
shell&gt; cat scripts/DBUpdate-to-3.1.mysql.sql | mysql -p -f -u root otrs
# PostgreSQL 8.2+:
shell&gt; cat scripts/DBUpdate-to-3.1.postgresql.sql | psql otrs
# PostgreSQL, older versions:
shell&gt; cat scripts/DBUpdate-to-3.1.postgresql_before_8_2.sql | psql otrs
            </screen>

            NOTE: If you use PostgreSQL 8.1 or earlier, you need to activate the new legacy driver
            for these older versions. Do this by adding a new line to your <filename>Kernel/Config.pm</filename> like this:

            <screen>
$Self->{DatabasePostgresqlBefore82} = 1;
            </screen>
        </para>
        <para>
            Run the migration script (as user 'otrs', NOT as root):
        </para>
        <para>
            You must execute the migration script to migrate some data from the old database structure to the new one. Please run:
            <screen>
shell&gt; scripts/DBUpdate-to-3.1.pl
            </screen>
        </para>
        <para>
            Apply the database changes (part 2/2):
        </para>
        <para>
            <screen>
# MySQL:
shell&gt; cat scripts/DBUpdate-to-3.1-post.mysql.sql | mysql -p -f -u root otrs
# PostgreSQL 8.2+:
shell&gt; cat scripts/DBUpdate-to-3.1-post.postgresql.sql | psql otrs
# PostgreSQL, older versions:
shell&gt; cat scripts/DBUpdate-to-3.1-post.postgresql_before_8_2.sql | psql otrs
            </screen>
        </para>
      </listitem>
      <listitem>
        <para>
Refresh the configuration and delete caches. Please run:
        </para>
        <para>
            <screen>
shell&gt; bin/otrs.RebuildConfig.pl
shell&gt; bin/otrs.DeleteCache.pl
            </screen>
        </para>
      </listitem>
      <listitem>
            <para>Update your web server configuration</para>
            <para>
            Note: this applies only if you use the Apache web server together with mod_perl2,
            and do not use the configuration file directly from the OTRS installation directory
            (e. g. with a symlink from the Apache configuration directory).
            </para>
            <para>
            Please add a new setting to the Apache configuration file for OTRS:
                <screen>
# set mod_perl2 option for generic interface
&lt;Location /otrs/nph-genericinterface.pl&gt;
  PerlOptions -ParseHeaders
&lt;/Location&gt;
                </screen>
            Please see the file /opt/otrs/scripts/apache2-httpd.include.conf for an example of
            where this new option needs to be added (inside the &lt;IfModule mod_perl.c&gt; block).
            </para>
            <para>
                In this file, you will also note a new section on caching:

                <screen><![CDATA[
<IfModule mod_headers.c>
    <Directory "/opt/otrs/var/httpd/htdocs/skins/*/*/css-cache">
        <FilesMatch "\.(css|CSS)$">
            Header set Cache-Control "max-age=2592000 must-revalidate"
        </FilesMatch>
    </Directory>

    <Directory "/opt/otrs/var/httpd/htdocs/js/js-cache">
        <FilesMatch "\.(js|JS)$">
            Header set Cache-Control "max-age=2592000 must-revalidate"
        </FilesMatch>
    </Directory>
</IfModule>
                ]]></screen>

                Please activate this in your local installation too, and make sure that mod_headers
                is installed and active.
            </para>
      </listitem>
      <listitem>
        <para>
            Restart your services.
        </para>
        <para>
            e. g. (depends on used services):
            <screen>
shell&gt; /etc/init.d/cron start
shell&gt; /etc/init.d/postfix start
shell&gt; /etc/init.d/apache start
            </screen>

            Now you can log into your system.
        </para>
      </listitem>
      <listitem>
        <para>Check installed packages</para>
        <para>
            In the package manager, check if all packages are still marked as
            correctly installed or if any require reinstallation or even a package upgrade.
        </para>
      </listitem>
      <listitem>
        <para>
            Check for encoding issues
        </para>
        <para>
            OTRS 3.1 only allows UTF-8 as internal charset.
            Non-UTF-8 installations of OTRS must switch to UTF-8.
        </para>
      </listitem>
      <listitem>
        <para>Escalation events</para>
        <para>
            If you want to use the new escalation events in your system, you need to activate the
            corresponding GenericAgent job in Kernel/Config/GenericAcent.pm. Please look into
            Kernel/Config/GenericAgent.pm.dist for an example of how to do this.
        </para>
      </listitem>
      <listitem>
        <para>Ticket event handlers</para>
        <para>
            The Event name TicketFreeTextUpdate_$Counter was renamed to TicketDynamicFieldUpdate_$FieldName.
            If you have any custom event handlers for these events, please adapt them.
        </para>
      </listitem>
      <listitem>
        <para>
            DynamicField user preferences module
        </para>
        <para>
            If you had one or more active custom settings for "PreferencesGroups###Freetext",
            you need to adapt them to work with the new DynamicFields engine. The PrefKey
            setting must be changed to "UserDynamicField_DynamicField", where the part after
            the _ is the name of the dynamic field. Existing values would need to be renamed
            in the database as well.
        </para>
      </listitem>
      <listitem>
        <para>
            Custom free field default value event handler
        </para>
        <para>
            If you used the event handler Ticket::EventModulePost###TicketFreeFieldDefault (not active by default),
            you'll need to migrate its configuration to the new setting Ticket::EventModulePost###TicketDynamicFieldDefault.
        </para>
        <para>
            The configuration of this is slightly different; where you had to specify a Counter indicating the TicketFreeText
            number previously, now you need to specify the name of the DynamicField (for migrated fields, this will be
            DynamicField_TicketFreeKey$Counter and DynamicField_TicketFreeText$Counter. You need two separate entries now
            if you want to set both the key and the text field.
        </para>
      </listitem>
      <listitem>
        <para>
            FreeText/Time based ACLs
        </para>
        <para>
            If you have any ACLs defined which involve freetext or freetime fields, you need to adjust these
            ACL definitions.
        </para>
        <para>
            Please have a look at <ulink url="http://doc.otrs.org/3.1/en/html/acl.html">http://doc.otrs.org/3.1/en/html/acl.html</ulink>.
            There you can find a list of all possible ACL
            settings. In general, you need to add the prefix "DynamicField_" to existing free field definitions, and you
            can add a new "DynamicField" section to the "Properties" list for situations when a ticket does not exist yet.
        </para>
      </listitem>
      <listitem>
        <para>
            Database Upgrade During Beta Phase
        </para>
        <para>
            This step is ONLY needed if you upgrade from 3.1.beta1 or 3.1.beta2!
            Please apply the required database changes as follows:
        </para>
        <para>
            <screen>
MySQL:
 shell> cat scripts/DBUpdate-3.1.beta.mysql.sql | mysql -p -f -u root otrs

PostgreSQL 8.2+:
 shell> cat scripts/DBUpdate-3.1.beta.postgresql.sql | psql otrs

PostgreSQL, older versions:
 shell> cat scripts/DBUpdate-3.1.beta.postgresql_before_8_2.sql | psql otrs
            </screen>
        </para>
      </listitem>
      <listitem>
        <para>Well done!</para>
      </listitem>
  </orderedlist>
</section>

<section id="upgrade-windows-installer">
<title>Upgrading Windows Installer</title>
<para>
There is currently no in-place upgrade tool available for OTRS installations that were done with the Windows Installer. The upgrade process basically consists of backing up the database and the filesystem, uninstalling OTRS, installing the new version, restoring the database and running the upgrade procedure if needed.
</para>

<para>Upgrading is described in
<ulink url="http://faq.otrs.org/otrs/public.pl?Action=PublicFAQ;ItemID=351">FAQ# 4200351</ulink>, and
there is also an informative
<ulink url="http://www.youtube.com/watch?v=sf0R-reMTWc">YouTube video</ulink>
available.
</para>
</section>

<section id="upgrading-mssql-datatypes">
<title>Upgrading Microsoft SQL Server Data Types</title>
<para>
Starting OTRS version <emphasis>3.1</emphasis>, OTRS uses the <emphasis>NVARCHAR</emphasis> data type rather
than <emphasis>VARCHAR</emphasis> or <emphasis>TEXT</emphasis>, to store textual data. This is because the
<emphasis>NVARCHAR</emphasis> type has full support for Unicode, whereas the old data types store data in
UCS-2 format, which is a sub-set of Unicode. Also, the <emphasis>TEXT</emphasis> data type is deprecated since
<emphasis>SQL Server 2005</emphasis>. Due to this, starting with OTRS version 3.1, the minimal
SQL Server version required for operation with OTRS is now <emphasis>Microsoft SQL Server 2005</emphasis>.
</para>

<para>
Because dropping and re-creating these indexes is a time-consuming operation, especially on large databases,
please plan enough time for performing the upgrade. We would recommend that you perform the upgrade on a copy
of the database prior to doing the actual conversion to test the upgrade procedure and to time how much time
will be needed on your specific environment.
</para>

<para>
Please make sure that, before you start, there is enough space available on the database server. Make sure
the free space on your database server is at least 2.5x the current size of the database.
</para>

<important>
<para>
This upgrade procedure will upgrade all fields of the mentioned data types to the new types. This procedure
first removes any indexes and constraints in which these fields are referenced, upgrades the fields, and then
adds the indexes and constraints back. It will do so on all tables found in the SQL Server database that OTRS
uses. If you would have stored non-OTRS tables in the OTRS database, and these tables contain columns of the
data types VARCHAR or TEXT, these will also be updated.
</para>
</important>

  <orderedlist>
      <listitem>
        <para>Open a Command Line on the OTRS server.</para>
      </listitem>
      <listitem>
        <para>Change directory to the OTRS root directory.
        If you're using the default OTRS installer this would be C:\Program Files\OTRS\OTRS.</para>
      </listitem>
      <listitem>
        <para>Run the following command:
            <screen>
shell> perl scripts/DUpdate-to-3.1.mssql-datatypes.pl
            </screen>
        </para>
      </listitem>
      <listitem>
        <para>This will generate three scripts in the specified directory scripts\database\update. Run these
        scripts on the SQL Server database, via SQL Server Management Studio or isql.
        </para>
      </listitem>
  </orderedlist>
</section>

</chapter>