Installation From Source (Linux, Unix)

Preparation: Disable SELinux

Note

If your system uses SELinux, you should disable it, otherwise OTRS will not work correctly.

Here's how to disable SELinux for RHEL/CentOS/Fedora:

  • Configure SELINUX=disabled in the /etc/selinux/config file:

    # This file controls the state of SELinux on the system.
    # SELINUX= can take one of these three values:
    #       enforcing - SELinux security policy is enforced.
    #       permissive - SELinux prints warnings instead of enforcing.
    #       disabled - No SELinux policy is loaded.
    SELINUX=disabled
    # SELINUXTYPE= can take one of these two values:
    #       targeted - Targeted processes are protected,
    #       mls - Multi Level Security protection.
    SELINUXTYPE=targeted
                            

  • Reboot your system. After reboot, confirm that the getenforce command returns Disabled:

    shell> getenforce
    Disabled
                            

Step 1: Install .tar.gz

If you want to install OTRS from source, first download the source archive as .tar.gz, .tar.bz2, or .zip file from https://www.otrs.com/download-open-source-help-desk-software-otrs-free/

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

shell> tar xzf /tmp/otrs-x.x.x.tar.gz
shell> mv otrs-x.x.x /opt/otrs
        

Step 2: Install Additional Perl Modules

Use the following script to get an overview of all installed and required CPAN modules.

shell> perl /opt/otrs/bin/otrs.CheckModules.pl
o CGI..............................ok (v3.60)
o Crypt::PasswdMD5.................ok (v1.3)
o Crypt::SSLeay....................Not installed! (Optional - Required for Generic Interface SOAP SSL connections.)
o CSS::Minifier....................ok (v0.01)
o Date::Format.....................ok (v2.22)
o Date::Pcalc......................ok (v1.2)
...
            

Note

Please note that OTRS requires a working Perl installation with all "core" modules such as the module version. These modules are not explicitly checked by the script. You may need to install a perl-core package on some systems like RHEL that do not install the Perl core packages by default.

To install missing Perl modules, you can:

a) Install the packages via the package manager of your Linux distribution

  • For Red Hat, CentOS, Fedora or compatible systems:

    shell> yum install "perl(Digest::MD5)"
                            

  • For SUSE Linux Enterprise Server, openSUSE or compatible systems: first determine the name of the package the module is shipped in. Usually the package for My::Module would be called "perl-My-Module".

    shell> zypper search Digest::MD5
                            

    Then install:

    shell> zypper install perl-Digest-MD5
                            

  • For Debian, Ubuntu or compatible systems first determine the name of the package the module is shipped in. Usually the package for My::Module would be called "libmy-module-perl".

    shell> apt-cache search Digest::MD5
                            

    Then install:

    shell> apt-get install libdigest-md5-perl
                            

    Please note that it might be that you can't find all modules or their required versions in your distribution repository, in that case you might choose to install those modules via CPAN (see below).

b) Install the required modules via the CPAN shell

Note that when you're on Linux you should run CPAN as your superuser account because the modules should be accessible both by the OTRS account and the account under which the web server is running.

shell> perl -MCPAN -e shell;
...
install Digest::MD5
install Crypt::PasswdMD5
...
                

Any optional modules listed by the script should be installed depending on the special requirements of the target system.

Step 3: Create OTRS User

Create user:

shell> useradd -d /opt/otrs -c 'OTRS user' otrs
            

Add user to webserver group (if the webserver is not running as the OTRS user):

shell> usermod -G www otrs
(SUSE=www, Red Hat/CentOS/Fedora=apache, Debian/Ubuntu=www-data)
            

Step 4: Activate Default Config Files

There are two OTRS config files bundled in $OTRS_HOME/Kernel/*.dist and $OTRS_HOME/Kernel/Config/*.dist. You must activate them by copying them without the ".dist" filename extension.

shell> cd /opt/otrs/
shell> cp Kernel/Config.pm.dist Kernel/Config.pm
    

Step 5: Check if all needed modules are installed

shell> perl -cw /opt/otrs/bin/cgi-bin/index.pl
/opt/otrs/bin/cgi-bin/index.pl syntax OK

shell> perl -cw /opt/otrs/bin/cgi-bin/customer.pl
/opt/otrs/bin/cgi-bin/customer.pl syntax OK

shell> perl -cw /opt/otrs/bin/otrs.Console.pl
/opt/otrs/bin/otrs.Console.pl syntax OK
            

"syntax OK" tells you all mandatory Perl modules are installed.

Step 6: Configuring the Apache web server

First of all, you should install the Apache2 web server and mod_perl; you'd typically do this from your systems package manager. Below you'll find the commands needed to set up Apache on the most popular Linux distributions.

# rhel / centos:
shell> yum install httpd mod_perl

# suse:
shell> zypper install apache2-mod_perl

# debian/ubuntu:
shell> apt-get install apache2 libapache2-mod-perl2
        

Most Apache installations have a conf.d directory included. On Linux systems you can usually find this directory under /etc/apache or /etc/apache2. Log in as root, change to the conf.d directory and link the appropriate template in /opt/otrs/scripts/apache2-httpd.include.conf to a file called zzz_otrs.conf in the Apache configuration directory (to make sure it is loaded after the other configurations).

OTRS requires a few Apache modules to be active for optimal operation. On most platforms you can make sure they are active via the tool a2enmod.

shell> a2enmod perl
shell> a2enmod version
shell> a2enmod deflate
shell> a2enmod filter
shell> a2enmod headers
        

Now you can restart your web server to load the new configuration settings. On most systems you can do that with the command systemctl restart apache2.service.

Step 7: File Permissions

File permissions need to be adjusted to allow OTRS to read and write files:

otrs.SetPermissions.pl [ --otrs-user= OTRS user, defaults to 'otrs' ] { --web-group= group of the web server user }

For example:

  • Web server which runs as the OTRS user:

    shell> bin/otrs.SetPermissions.pl --web-user=otrs
                    

  • Webserver with wwwrun user (e. g. SUSE):

    shell> bin/otrs.SetPermissions.pl --web-group=wwwrun
                    

  • Webserver with apache user (e. g. Red Hat, CentOS):

    shell> bin/otrs.SetPermissions.pl --web-group=apache
                    

  • Webserver with www-data user (e. g. Debian, Ubuntu):

    shell> bin/otrs.SetPermissions.pl --web-group=www-data
                    

Step 8: Database Setup and Basic System Configuration

Please use the web installer at http://localhost/otrs/installer.pl (replace "localhost" with your OTRS hostname) to setup your database and basic system settings such as email accounts.

Note

The following configuration settings are recommended for MySQL setups. Please add the following lines to /etc/my.cnf under the [mysqld] section:

max_allowed_packet   = 20M
query_cache_size     = 32M
innodb_log_file_size = 256M
                

Step 9: First login

Now you are ready to login to your system at http://localhost/otrs/index.pl with the credentials you configured in the web installer (User: root@localhost).

With this step, the basic system setup is finished.

Step 10: Start the OTRS Daemon

The new OTRS daemon is responsible for handling any asynchronous and recurring tasks in OTRS. What has been in cron file definitions previously is now handled by the OTRS daemon, which is now required to operate OTRS. The daemon also handles all GenericAgent jobs and must be started from the otrs user.

shell> /opt/otrs/bin/otrs.Daemon.pl start
            

Step 11: Cron jobs for the OTRS user

There are two default OTRS cron files in /opt/otrs/var/cron/*.dist, and their purpose is to make sure that the OTRS Daemon is running. They need to be be activated by copying them without the ".dist" filename extension.

shell> cd /opt/otrs/var/cron
shell> for foo in *.dist; do cp $foo `basename $foo .dist`; done
            

To schedule these cron jobs on your system, you can use the script Cron.sh with the otrs user.

shell> /opt/otrs/bin/Cron.sh start
            

Stopping the cron jobs is also possible (useful for maintenance):

shell> /opt/otrs/bin/Cron.sh stop
    

Step 12: Setup bash autocompletion (optional)

All regular OTRS commandline operations happen via the otrs Console interface bin/otrs.Console.pl. This provides an auto completion for the bash shell which makes finding the right command and options much easier.

You can activate the bash autocompletion by installing the package bash-completion. It will automatically detect and load the file /opt/otrs/.bash_completion for the otrs user.

After restarting your shell, you can just type bin/otrs.Console.pl followed by TAB, and it will list all available commands. If you type a few characters of the command name, TAB will show all matching commands. After typing a complete command, all possible options and arguments will be shown by pressing TAB.

Step 13: Further Information

We advise you to read the OTRS performance tuning chapter.

If you encounter problems with the installation, you can send a message to our mailing list otrs@otrs.org (http://lists.otrs.org/).

You can also ask the OTRS Group to either help you in planning or deploying OTRS, or review your installed OTRS system. Our professional services are designed to help you deploy OTRS faster and to get the most benefit out of OTRS.