<chapter id="troubleshooting">
<title>Troubleshooting</title>
<para>
We split this section into different parts per distribution. Of course you can set up your own system with your own linux system. But please understand that we can not provide any support for that. OTRS is much too complicated and has to many links to other components of the system that we are lucky to have access to mechanisms like RPM. We will try to support as many platforms as possible but time is a valuable resource. ;-)
</para>
<sect1 id="problems-with-suse">
<title>General problems with OTRS on SuSE Linux</title>
<para>
The very first step should be a visit to <ulink url="http://www.suse.de/de/support/download/updates/"><citetitle>http://www.suse.de/de/support/download/updates/</citetitle></ulink> which is the page where you can find the latest patches and updates for your SuSE Linux. Please check especialy for fixes about Apache, MySQL, Perl and of course OTRS. YaST2 users should be able to use the Yast Online Update mechanism. Otherwise download the rpm files and deinstall the old package with "rpm --nodeps -e otrs" and install the new one with "rpm -i foo.rpm"
</para>
<para>
The second step should be a visit to the <ulink url="http://www.otrs.org/"><citetitle>OTRS Homepage</citetitle></ulink>. We will provide the very latest fixes and howtos there.
</para>
<para>
The third step is writting an e-mail to the developer team of OTRS. We will be more than happy to provide you with any support you need.
</para>

<sect2>
<title>SuSE Linux 8.0</title>
<para>
Unfortantely the otrs.rpm which is on the SuSE 8.0 distribution is a buggy one (it was not a SuSE mistake). Please download the newest version from our <ulink url="http://www.otrs.org/">Homepage</ulink> and install it with YaST or manually by 
<screen>
# deinstall old package
shell> rpm --nodeps -e otrs
# install new package
shell> rpm -i new-otrs.rpm 
</screen>
</para>

</sect2>

<sect2>
<title>SuSE Linux and Postfix</title>
<para>
Postfix isn't configured with Procmail out of the box. You have to enable Procmail in /etc/postfix/main.cf:
<screen>
[...]
mailbox_command = /usr/bin/procmail
[...]
</screen>
Restart the Postfix daemon afterwards via 'rcpostfix restart'.
</para>

</sect2>

</sect1>

<sect1 id="problems-with-mandrake">
<title>General problems with OTRS on Mandrake</title>
<para>
OTRS works as expected on a Mandrake system, at least when using release 9.1 or 9.2. As we do not provide a ready-to-use RPM right now, you will have to follow the documentational steps for a manual installation using the tarball.
</para>
<sect2>
<title>Updating Your System</title>
<para>
Before considering installing OTRS on a Mandrake system, you are strongly encouraged to use Mandrake's software package management to update your system to the most recent available version. You may find a convenient GUI in Mandrake's Control Center, or issue these commands as the superuser via the command line:
<programlisting>
shell:~ # urpmi.update --update --auto --auto-select
shell:~ # urpmi --update --auto-select
</programlisting>
This requires you have your update_source set up properly. To use GWDG.de as your standard update_source, issue s.th. like the following, substituting &lt;rel&gt; with your release version:
<programlisting>
shell:~ # urpmi.addmedia update_source ftp://ftp.gwdg.de/pub/linux/mandrake/updates/&lt;rel&gt;/RPMS 
</programlisting>
</para>
</sect2>
</sect1>

<sect1 id="problems-with-redhat">
<title>General problems with OTRS on other distributions (e.g. Redhat)</title>
<para>
Frankly we have not tried to install it on a Redhat yet. It should not be a problem but there is no ready to use RPM. We are working on it. Same for other distributions not mentioned.
</para>
</sect1>

<sect1 id="problems-with-apache">
<title>Problems with Apache</title>
<para>
Most people who have problems with the Apache did build their own very special Apache. Of course you are welcome to do so but in case you run into trouble we suggest to your the vanilla version which is provided by your favorite distribution.
</para>

<sect2>
<title>Internal Server Error</title>
<para>
In this case check the syntax of the index.pl file to find the error:
<programlisting>
shell:~ # cd ~otrs
</programlisting>
It's important to be in the $HOME of the otrs user.
<programlisting>
shell:/opt/otrs # perl -cw bin/cgi-bin/index.pl 
bin/cgi-bin/index.pl syntax OK
shell:/opt/otrs #
</programlisting>
If you get an error message, in most cases you have to install missing perl modules from <ulink url="http://www.cpan.org/">CPAN</ulink>.
</para>
<para>
Install CPAN modules via cpan shell:
<programlisting>
shell:~ # perl -MCPAN -e shell;
 -- (you may have to configure cpan first) --

cpan shell -- CPAN exploration and modules installation (v1.59_54)
ReadLine support enabled

cpan> install Digest::MD5
[installing Digest::MD5 module]
cpan> 
</programlisting>
Check the perl syntax again (perl -cw bin/cgi-bin/index.pl) and install further missing modules if necessary.
</para>
</sect2>

<sect2>
<title>Error: Can't connect to database!</title>
<para>
If your browser get the message "Error: Can't connect to database!" after you changed the database settings, restart the webserver. mod_perl reads the ~otrs/Kernel/Config.pm only on startup. 
</para>
<para>
If the "Error: Can't connect to database!" message is still there, check the error log of your webserver (e. g. /var/log/httpd/error_log).
</para>
</sect2>

<sect2>
<title>FreeBSD, PostgeSQL and Apache (install_driver(Pg) failed)</title>
<para>
Everything is working fine just if I want to use the web interface I get always: 
[...]
Software error:
install_driver(Pg) failed: [Thu Sep 19 16:52:18 2002] index.pl: [Thu Sep 19
16:52:18 2002] index.pl: Can't load
'/usr/local/lib/perl5/site_perl/5.005/i386-freebsd/auto/DBD/Pg/Pg.so' for
module DBD::Pg: Shared object "libpq.so.2" not found at
/usr/libdata/perl/5.00503/DynaLoader.pm line 169. [Thu Sep 19 16:52:18 2002]
index.pl: [Thu Sep 19 16:52:18 2002] index.pl: [Thu Sep 19 16:52:18 2002]
index.pl: [Thu Sep 19 16:52:18 2002] index.pl: at (eval 124) line 3 Perhaps
a required shared library or dll isn't installed where expected at   
/usr/local/otrs/bin/cgi-bin/../../Kernel/System/DB.pm line 67
[...]
</para>
<para>
To solve this problem, you can tell the Apache httpd.conf to include the
environmental variable LD_LIBRARY_PATH= /usr/local/pgsql/lib. Put the following line into httpd.conf "SetEnv LD_LIBRARY_PATH usr/local/pgsql/lib". Now restart your webserver (see <ulink url="http://lists.otrs.org/pipermail/otrs/2002-September/000248.html">http://lists.otrs.org/pipermail/otrs/2002-September/000248.html</ulink>).
</para>
</sect2>

</sect1>

<sect1 id="problems-with-mysql">
<title>Problems with MySQL</title>
<para>
Please doublecheck all passwords. Mostly people setup the system with a wrong password. In this case it is the easiest way to re-setup the system. 
</para>

<sect2>
<title>Check the database connection</title>
<para>
To check the database connection use '~otrs/bin/CheckDB.pl'. Is the output "It looks Ok!", you don't have problems connecting to your database. If not, read the error message.
</para>
</sect2>

<sect2>
<title>Access denied for user: 'otrs@localhost'</title>
<para>
Check the password for the database user in Kernel/Config.pm. If you don't know the database password for the database otrs user (any more), set it new:
<programlisting>
shell> mysql -u root -p
Reading table information for completion of table and column names
You can turn off this feature to get a quicker startup with -A

Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 37 to server version: 3.23.48-log

Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

mysql> GRANT ALL PRIVILEGES ON otrs.* TO otrs@localhost IDENTIFIED BY "yourpw" WITH GRANT OPTION;
mysql> 
</programlisting>
Reload the grant tables of your mysql-daemon:
<programlisting>
$shell> mysqladmin -u root -p reload
</programlisting>
(or restart your mysql-daemon) and change the new otrs password in Kernel/Config.pm.
</para>
<para>
Note: If you use mod_perl, restart the webserver, because mod_perl is reading the perlcode
(incl. Kernel/Config.pm) on startup.
</para>
</sect2>

<sect2 id="problems-lost-mysql-root-pw">
<title>Lost root password of MySQL</title>
<para>
Follow: <ulink url="http://www.mysql.com/documentation/mysql/bychapter/manual_Problems.html#Resetting_permissions">http://www.mysql.com/documentation/mysql/bychapter/manual_Problems.html#Resetting_permissions</ulink>
</para>
</sect2>

<sect2>
<title>http://localhost/otrs/installer.pl</title>
<para> 
If you want to set up the otrs database again, you can call the setup program by browsing to <ulink url="http://localhost/otrs/installer.pl"><citetitle>http://localhost/otrs/installer.pl</citetitle></ulink>.
</para>
<para>
Note: Just for SuSE Linux RPMs.
</para>
</sect2>

</sect1>

<sect1 id="problems-misc">
<title>Problems - misc</title>

<sect2 id="problems-with-receiving-emails">
<title>Problems with receiving emails</title>
<para>
If everything is working, but you can't see the incoming emails, check if the ~otrs/bin/PostMaster.pl program is working correctly. Pipe an example email through the PostMaster.pl. There are two example emails in the default OTRS package (~otrs/doc/test-email-*.box or /usr/share/doc/packages/otrs/test-email-*.box).   
</para>
<para>
Example:
<programlisting>
shell:~ # cat /usr/share/doc/packages/otrs/test-email-1.box | /opt/otrs/bin/PostMaster.pl 
shell:~ #
</programlisting>
If there is an error message, then you will have to fix it. If not and you see this email in the postmaster queue, the procmail program isn't configured with your MTA (check the MTA log file, e. .g /var/log/mail) or the $HOME of the otrs user isn't correct (check $HOME and $HOME/.procmailrc).
</para>
</sect2>

<sect2 id="problems-lost-otrs-root-pw">
<title>Lost root password of OTRS</title>
<para>
I lost the root password of OTRS ("Login failed! Your username or password was entered incorrectly."). 
</para>
<para>
Reset of the OTRS root password:
<programlisting>
shell:~ # mysql -u root -p otrs
mysql> UPDATE system_user SET pw='roK20XGbWEsSM' where login='root@localhost';
mysql>
</programlisting>
And the password of user 'root@localhost' will be 'root'. The password is crypted like 'man 3 crypt' with crypt().
</para>
</sect2>

</sect1>

</chapter>
