Torsten Werner, Berlin, 2006-08-20, http://www.twerner42.de/

OTRS on Debian systems

1   Introduction

This document describes how to install, configure and use OTRS on Debian systems. The official OTRS documentation is available from http://www.otrs.org/ . Contrary to the official documentation I do not plan to translate this file to the german language. I am using http://www.writely.com/ to write the document which make collaborative documentation possible. If you have a writely account and want to get full access to this document, please tell me you email address you have used to subscribe to writely. Every help is very welcome!

2   Licensing

The document is dual licensed: you can choose between either the GNU Free Documentation license or Creative Commons Attribution-Share Alike license.

2.1    GNU FDL

Copyright (c) 2006 Torsten Werner, twerner at debian dot org

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. The full text of the FDL can be found at http://www.gnu.org/licenses/fdl.html .

2.2    CC Attribution-ShareAlike 2.5

You are free:

Under the following conditions:

byAttribution. You must attribute the work in the manner specified by the author or licensor.
saShare Alike. If you alter, transform, or build upon this work, you may distribute the resulting work only under a license identical to this one.


Your fair use and other rights are in no way affected by the above.

This is a human-readable summary of the Legal Code (the full license).

Disclaimer disclaimer

2.3    Support

There is a mailing list pkg-otrs-devel@lists.alioth.debian.org, you can subscribe it at http://lists.alioth.debian.org/mailman/listinfo/pkg-otrs-devel and ask any questions there. If you want to report a bug, please use the reportbug tool because it includes some extra information in the report like your database settings (without passwords of course) and the versions of all packages that OTRS depends on.

3    The installation process

3.1    The first installation of the package

The actual package name is otrs2 for OTRS version >= 2.0. The old otrs package ships version 1.3 and is intended only for people that want to stay with this version for a while. It is not recommended to use version 1.3 for new OTRS installations. The preferred way to install OTRS is by using aptitude:
aptitude install --with-recommends otrs2
or simply use the GUI. If you want to use other tools like apt-get make sure that all Recommends get installed. They are not strictly needed but recommended --- hence the name. There are even some Suggests that might be useful to you. The screenshot below show the otrs2 package in aptitude. The otrs2 package now implicitely depends on Apache version 2.2. That means it is not easy to install it on sarge system any more as long nobody backports either otrs2 or apache2.2 to sarge.

You can choose between PostgreSQL or MySQL if you want an automatic database setup. Any other database type can be setup manually but that is not the scope of the current document. If you want to use a remote database than you do not need to install postgresql-8.1 or mysql-server locally. The database setup is done by the package dbconfig-common, which supports automatic setup, upgrades and removal of SQL databases. How it does look like depends on the database type, on your debconf priority, your preferred language and if the database is installed locally or not. Here is an example how it might look like:

We are using PostgreSQL in our example:


The authentication method "ident" is the most easiest one for local databases:

A random password will be chosen if you do not specify one for your database:

If there are any errors you can try editing the file /etc/dbconfig-common/otrs2 and run
dpkg-reconfigure otrs2
after saving the file. That should regenerate the perl code in /etc/otrs/database.pm which is read by /etc/otrs/Kernel/Config.pm. If that does not help either or you do not wish to use dbconfig-common for any other reasons you have to hardcode the database settings in /etc/otrs/Kernel/Config.pm, but you will lose the advantage of automatic upgrades (and removal) of the database when the otrs2 package gets upgraded (or removed respectively).

4    Architecture

4.1    The UNIX user otrs and the directory hierarch

Overview
User name otrs
User group www-data  (apache usergroup)
User home /usr/share/otrs
Otrs config files
/etc/otrs
Variable files /var/lib/otrs
Otrs startup scripts
/etc/init.d/

The package creates an UNIX user called otrs. Its home directory is /usr/share/otrs/ where the OTRS files are installed. Any variable files are located below /var/lib/otrs/ and most configuration files are below /etc/otrs/ .
Currently there are issues with the package manager built into OTRS. See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=383776 for more information. Please avoid using the package manager if you can as long as it is not fully supported by the Debian package.

4.2    The directory /etc/otrs/

This directory contains some configuration files that are handled by the package ucf (update configuration file). Most notably these are:
If both you and the package maintainer changes the same file than ucf will ask you what to do:

You have different options to solve that conflict. In every case the rejected file will be saved with an extra suffix.

4.3    The init script /etc/init.d/otrs2

Strictly speaking this is a conffile too but not handled by ucf but by dpkg directly, because I don't think you need to edit this file yourself. It handles two symlinks:
  • /etc/cron.d/otrs -> /etc/otrs/cron
  • /var/lib/otrs/httpd/htdocs/maintainance.html -> /etc/otrs/maintainance.html
If you stop OTRS via
/etc/init.d/otrs2 stop
than all cron jobs of OTRS are disabled, the PostMaster.pl will fail temporarily (exit code 75) which leads to delayed email delivery and your users will see a configurable maintainance screen instead of the application:


You can use this mode to maintain your database or your MTA, do backups or whatever else needs OTRS switched off. Note: the init script does not start or stop any daemons.

5    Administrative things

5.1    Important: backup and restore

OTRS provides two scripts: backup.pl and restore.pl. These commands do not backup everything you might expect and there is no warranty that they work at all with Debian's infrastructure. Do not use them except when you have no other options! Nevertheless I will assume that you have a working backup and restore on your machine especially before you are doing upgrades! But the details are out of the scope of this document. Don't blame me for not having a well tested backup and restore procedure!

5.2    Upgrading the package

There is no automatic upgrade of the oldotrs package (version 1.3) to the new otrs2 package. Both packages conflict toeach other and cannot be installed simultaneously. But automatic upgrades fromversion 2.0 to version 2.1 are already supported. If you install version 2.1from Debian's experimental archive than dbconfig-common will ask you toautomatically ugrade the database schema. You should choose this optionnaturally. Just in case something is broken: dbconfig-common will always make abackup of your database in the directory /var/tmp/ . Note: 2.1 isnot yet recommended for productionmachines but that will change after the etch release. If you are upgrading froman older version of the package that did not use dbconfig-common or where someconfig files were located at different locations then the old settings should beautomatically imported. Just carefully answer the ucf questions in such a case.

5.3    Removing the package

If you purge otrs2 with
aptitude purge otrs2
or any similiar command than dbconfig-common will ask you to removethe database. A backup will be written in the directory /var/tmp/ if you choosethat option.

Changelog