OTOBO Installation

Dieses Kapitel beschreibt die Installation und grundlegende Konfiguration des zentralen OTOBO Frameworks.

Dieses Kapitel führt Sie Schritt für Schritt durch die Installation von OTOBO auf Ihrem Server. Anschließend können Sie sich über die Weboberfläche am System anmelden, um es zu konfigurieren und zu administrieren.

Bemerkung

We recommend Docker and Docker Compose for the OTOBO installation. By using the provided Docker images, all recommended dependencies (such as Elasticsearch, Redis Cache, etc.) are installed and configured automatically. Updates are thus greatly simplified and the performance has been improved. You can find the instructions for Docker-based installation at https://doc.otobo.org/manual/installation/10.1/en/content/installation-docker.html .

Vorbereitung: Deaktivieren Sie SELinux (sofern aktiv)

Bemerkung

Ist SELinux auf Ihrem System installiert und aktiv, deaktivieren Sie es vor der Installation. Anderenfalls wird OTOBO nicht korrekt funktionieren.

Wenn Sie nicht sicher sind, ob SELinux installiert und aktiv ist, geben Sie die Befehle sestatus und getenforce ein.

Der Befehl sestatus gibt den SELinux-Status aus und informiert darüber, welche SELinux Policy angewendet wird. SELinux Status: Ist SELinux aktiv, wird als Status enabled angezeigt. Aktueller Betriebsmodus: wird hier enforcing ausgegeben, läuft SELinux im Enforcing-Modus. Policy aus der Config-Datei: wird hier targeted ausgegeben, kommt die Targeted Policy zum Einsatz.

So deaktivieren Sie SELinux unter RHEL/CentOS/Fedora.

  1. Wählen Sie in der Datei /etc/selinux/config die Konfiguration SELINUX=disabled:

    # 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

  2. Starten Sie Ihr System neu. Versichern Sie sich nach dem Neustart, dass der Befehl getenforce Disabled zurückgibt:

    root> getenforce
Disabled

Schritt 1: OTOBO entpacken und installieren

Laden Sie das neueste OTOBO-Release von https://ftp.otobo.org/pub/otobo/ herunter. Entpacken Sie das Quell-Archiv (zum Beispiel mit tar) in das Verzeichnis /opt/otobo-install:

root> mkdir /opt/otobo-install && mkdir /opt/otobo                      # Create a temporary install directory
root> cd /opt/otobo-install                                             # Change into the update directory
root> wget https://ftp.otobo.org/pub/otobo/otobo-latest-10.1.tar.gz     # Download he latest OTOBO 10 release
root> tar -xzf otobo-latest-10.1.tar.gz                                 # Unzip OTOBO
root> cp -r otobo-10.x.x/* /opt/otobo                                     # Copy the new otobo directory to /opt/otobo

Schritt 2: Ergänzende Programme und Perl-Module installieren

Verwenden Sie das folgende Skript, um eine Übersicht über alle installierten und erforderlichen CPAN-Module sowie andere externe Abhängigkeiten zu erhalten.

Bemerkung

Auf Debian-Systemen müssen Sie möglicherweise einige perl-Pakete manuell installieren:

apt-get install -y libarchive-zip-perl libtimedate-perl libdatetime-perl libconvert-binhex-perl libcgi-psgi-perl libdbi-perl libdbix-connector-perl libfile-chmod-perl liblist-allutils-perl libmoo-perl libnamespace-autoclean-perl libnet-dns-perl libnet-smtp-ssl-perl libpath-class-perl libsub-exporter-perl libtemplate-perl libtext-trim-perl libtry-tiny-perl libxml-libxml-perl libyaml-libyaml-perl libdbd-mysql-perl libapache2-mod-perl2 libmail-imapclient-perl libauthen-sasl-perl libauthen-ntlm-perl libjson-xs-perl libtext-csv-xs-perl libpath-class-perl libplack-perl libplack-middleware-header-perl libplack-middleware-reverseproxy-perl libencode-hanextra-perl libio-socket-ssl-perl libnet-ldap-perl libcrypt-eksblowfish-perl libxml-libxslt-perl libxml-parser-perl libconst-fast-perl

root> perl /opt/otobo/bin/otobo.CheckModules.pl -list
Checking for Perl Modules:
  o Archive::Tar.....................ok (v1.90)
  o Archive::Zip.....................ok (v1.37)
  o Crypt::Eksblowfish::Bcrypt.......ok (v0.009)
...

Bemerkung

Bitte beachten Sie, dass OTOBO eine funktionierende Perl-Installation mit allen Core-Modulen wie dem Modul version voraussetzt. Diese Module werden nicht explizit vom Skript überprüft. Auf einigen Systemen, wie z. B. RHEL, sind nicht alle Core-Pakete standardmäßig installiert. Hier kann es erforderlich sein, ein perl-core-Paket von Hand zu installieren.

Zur Installation der erforderlichen und optionalen Pakete können Sie wahlweise CPAN oder die Paketverwaltung Ihrer Linux-Distribution verwenden.

Dieses Kommando gibt einen Installationsbefehl zum Installieren der fehlenden Abhängigkeiten aus:

root> /opt/otobo/bin/otobo.CheckModules.pl --inst

Bemerkung

Es gibt eine Reihe optionaler oder alternativer Module, die insbesondere in individualisierten OTOBO Systemen zum Einsatz kommen. Ein Aufruf von CheckModules.pl ohne jedes Argument gibt Aufschluss über den vollen Funktionsumfang des Systems.

Schritt 3: OTOBO-Benutzer anlegen

Legen Sie einen dedizierten Benutzer für OTOBO in einer eigenen Gruppe an:

root> useradd -r -U -d /opt/otobo -c 'OTOBO user' otobo -s /bin/bash

Fügen Sie den Benutzer zur Gruppe Webserver hinzu (wenn der Webserver nicht als OTOBO-Benutzer ausgeführt wird):

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

Schritt 4: Standard-Konfigurationsdatei aktivieren

Die Datei $OTOBO_HOME/Kernel/Config.pm.dist wird mit OTOBO ausgeliefert. Sie enthält Konfigurationsdaten für OTOBO. Aktivieren Sie die Konfiguration, indem Sie die Datei ohne die Dateinamenerweiterung .dist kopieren.

root> cp /opt/otobo/Kernel/Config.pm.dist /opt/otobo/Kernel/Config.pm

Schritt 5: Apache-Webserver konfigurieren

Installieren Sie zunächst den Apache2-Webserver und mod_perl. In der Regel nutzen Sie hierzu die Paketverwaltung Ihres Systems. Nachstehend finden Sie alle Befehle, die Sie benötigen, um Apache in den gängigsten Linux-Distributionen aufzusetzen.

# RHEL / CentOS:
root> yum install httpd mod_perl

# SuSE:
root> zypper install apache2-mod_perl

# Debian/Ubuntu:
root> apt-get install apache2 libapache2-mod-perl2

Zentrale Bedeutung hat die Auswahl des Multi-Processing-Modules (MPM). Für den OTOBO-Betrieb empfehlen wir das Modul mpm_prefork. Wie andere Apache-Module kann auch das MPM-Modul mit den Tools a2dismod und a2enmod verwaltet werden.

root> # check which MPM is active
root> apache2ctl -M | grep mpm_

Möglicherweise ist mpm_prefork bereits vorausgewählt. Dann kann dieser Schritt übersprungen werden.

Deaktivieren Sie mpm_event, falls das Modul aktiv ist.

root> a2dismod mpm_event

Deaktivieren Sie mpm.worker, falls dieses MPM aktiv ist.

root> a2dismod mpm_worker

Und aktivieren Sie schließlich mpm_prefork.

root> a2enmod mpm_prefork

Damit OTOBO optimal funktioniert, müssen weitere Apache-Module aktiv sein. Auch deren Status können Sie auf den meisten Systemen mit dem Tool a2enmod prüfen.

root> a2enmod perl
root> a2enmod deflate
root> a2enmod filter
root> a2enmod headers

Bemerkung

Auf manchen Systemen sind nicht alle Apache-Module vorhanden, dann wird während der Installation eine Fehlermeldung ausgegeben. Fahren Sie einfach mit der Installation fort. In den meisten Fällen werden die fehlenden Module nicht benötigt.

In den meisten Apache-Installationen findet sich ein Verzeichnis conf.d. Auf Linux-Systemen finden Sie es in aller Regel unter /etc/apache oder /etc/apache2.

Apache ohne SSL-Unterstützung konfigurieren

Kopieren Sie die Vorlage /opt/otobo/scripts/apache2-httpd.include.conf in das Apache-Verzeichnis sites-available. In den meisten Fällen muss die Vorlage nicht weiter angepasst werden. Aktivieren Sie die neue Konfiguration.

# Debian/Ubuntu:
root> cp /opt/otobo/scripts/apache2-httpd.include.conf /etc/apache2/sites-available/zzz_otobo.conf
root> a2ensite zzz_otobo.conf
root> systemctl restart apache2

Apache mit SSL-Unterstützung kofigurieren

Kopieren Sie die Vorlagen /opt/otobo/scripts/apache2-httpd-vhost-80.include.conf und /opt/otobo/scripts/apache2-httpd-vhost-443.include.conf in das Apache-Verzeichnis sites-availible.

# Debian/Ubuntu:
root> cp /opt/otobo/scripts/apache2-httpd-vhost-80.include.conf /etc/apache2/sites-available/zzz_otobo-80.conf
root> cp /opt/otobo/scripts/apache2-httpd-vhost-443.include.conf /etc/apache2/sites-available/zzz_otobo-443.conf

Bearbeiten Sie die Dateien und ergänzen Sie die benötigten Informationen wie den Pfad zum SSL-Zertifikat. Anschließend aktivieren Sie die OTOBO-Apache-Konfiguration:

root> a2ensite zzz_otobo-80.conf
root> a2ensite zzz_otobo-443.conf

Jetzt können Sie Ihren Webserver neu starten und die neuen Konfigurationseinstellungen laden. Auf den meisten Systemen gelingt dies mit folgendem Befehl:

root> systemctl restart apache2

Schritt 6: Dateiberechtigungen anpassen

Führen Sie folgenden Befehl aus, um die Datei- und Verzeichnis-Berechtigungen für OTOBO zu definieren. Es wird versucht, die passenden Benutzer- und Gruppeneinstellungen für Ihr Setup zu ermitteln.

root> /opt/otobo/bin/otobo.SetPermissions.pl

Schritt 7: Datenbank anlegen

Installieren Sie zuerst das Datenbank-Paket. Wir empfehlen, das mit Ihrem Linuxsystem zur Verfügung gestellte MySQL- oder MariaDB-Paket zu verwenden. Sie können aber auch PostgreSQL oder Oracle nutzen.

In aller Regel erfolgt die Installation wieder über die Paketverwaltung Ihres Systems. Nachstehend finden Sie die zum Aufsetzen von MySQL in den gängigsten Linux-Distributionen benötigten Befehle.

# RHEL / CentOS:
root> yum install mysql-server

# SuSE:
root> zypper install mysql-community-server

# Debian/Ubuntu:
root> apt-get install mysql-server

Nach der Installation muss der MySQL-Server konfiguriert werden.

In MySQL ab Version 5.7 ist ein neues Authentifizierungsmodul aktiv, das ein Anlegen der Datenbank durch den OTOBO Web Installer verhindert. Bitte loggen Sie sich in diesem Fall in die MySQL-Konsole ein und definieren Sie ein anderes Authentifizierungsmodul und ein Passwort für den root-Benutzer:

root> mysql -u root
root> ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY 'NewRootPassword';

Für MariaDB > 10.1 verwenden Sie stattdessen folgenden Befehl:

root> mysql -u root
root> update mysql.user set authentication_string=password('NewRootPassword') plugin='mysql_native_password' where user='root';

Funktioniert dieser Befehl nicht, versuchen Sie es mit folgenden Kommandos:

root> mysql -u root
root> UPDATE mysql.user SET password = PASSWORD('NewRootPassword') WHERE user = 'root';
root> UPDATE mysql.user SET authentication_string = '' WHERE user = 'root';
root> UPDATE mysql.user SET plugin = 'mysql_native_password' WHERE user = 'root';

Sofern nötig, können Sie das Authentifizierungsmodul nach der OTOBO-Installation wieder ändern.

Bemerkung

Folgende Konfigurationseinstellungen beschreiben die Minimalanforderungen für MySQL. Bitte ergänzen Sie die MySQL-Server-Konfigurationsdatei unter /etc/my.cnf, /etc/mysql/my.cnf oder /etc/mysql/mysql.conf.d/mysqld.cnf im Abschnitt [mysqld] um diese Zeilen:

max_allowed_packet   = 64M
innodb_log_file_size = 256M

Für MySQL-Versionen vor MySQL 8.0 sollten Sie außerdem den Query-Cache definieren:

query_cache_size     = 32M

Bitte ergänzen Sie die MySQL-Server-Konfigurationsdatei unter /etc/my.cnf, /etc/mysql/my.cnf oder /etc/mysql/mysql.conf.d/mysqldump.cnf im Abschnitt [mysqldump] um diese Zeilen:

max_allowed_packet   = 64M

Für den Produktivbetrieb empfehlen wir die Nutzung des Tools mysqltuner, mit dem Sie die bestmöglichen Einstellungen für Ihr System ermitteln können. Sie können das Skript unter https://github.com/major/MySQLTuner-perl aus GitHub herunterladen. In Debian- und Ubuntu-Systemen finden Sie es über die Paketverwaltung:

root> apt-get install mysqltuner

Ist die Installation abgeschlossen, führen Sie das Skript aus:

root> mysqltuner --user root --pass NewRootPassword

Schritt 8: Elasticsearch-Cluster aufsetzen

Für schnelle Suchen in OTOBO empfehlen wir ein aktives Elasticsearch-Cluster. Am einfachsten setzen Sie Elasticsearch auf dem gleichen Host wie OTOBO auf und lassen es den Standardport nutzen.

Beispiel für eine Elasticsearch-Installation unter Ubuntu 18.04 LTS

JDK-Installation

root> apt update
root> apt install openjdk-8-jdk

Elasticsearch-Installation

root> wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch | sudo apt-key add -
root> echo "deb https://artifacts.elastic.co/packages/7.x/apt stable main" | sudo tee /etc/apt/sources.list.d/elastic-7.x.list
root> apt update
root> apt -y install elasticsearch

Elasticsearch-Installation auf anderen Linux-Distributionen

Bitte nutzen Sie das Installations-Tutorial unter https://www.elastic.co/guide/en/elasticsearch/reference/current/setup.html.

Elasticsearch-Modul installieren

Außerdem erfordert OTOBO die Installation von Plugins in Elasticsearch:

root> /usr/share/elasticsearch/bin/elasticsearch-plugin install --batch ingest-attachment
root> /usr/share/elasticsearch/bin/elasticsearch-plugin install --batch analysis-icu

Elasticsearch konfigurieren

Elasticsearch bietet viele unterschiedliche Konfigurationsoptionen und -möglichkeiten.

In größeren OTOBO-Systemen sollten Sie für einen fehlerfreien Betrieb den JVM Heap Space anpassen. Diese Einstellungen finden Sie in der Datei /etc/elasticsearch/jvm.options. Achten Sie darauf, dass Mindest- und Maximalwert für die JVM Heap Size übereinstimmen. Um den Heap auf 4 GB zu setzen, nehmen Sie folgende Einstellung vor:

-Xms4g
-Xmx4g

In unseren Tests hat sich ein Wert zwischen 4 und 10 GB für mittlere Systeme als optimal erwiesen.

Bemerkung

Bitte nutzen Sie das Installations-Tutorial unter https://www.elastic.co/guide/en/elasticsearch/reference/current/setup.html.

Jetzt können Sie Ihren Elasticsearch-Server neu starten, um die neuen Konfigurationseinstellungen zu laden. Auf den meisten Systemen gelingt dies mit folgendem Befehl:

root> systemctl restart elasticsearch

Schritt 9: Grundlegende Systemkonfiguration

Bitte verwenden Sie den Web Installer unter http://localhost/otobo/installer.pl (ersetzen Sie „localhost“ durch den Namen Ihres OTOBO-Hosts), um die Datenbank zu konfigurieren und grundlegende Systemeinstellungen wie die der E-Mail-Konten vorzunehmen.

Schritt 10: Erste Anmeldung

Geschafft! Jetzt können Sie sich mit dem zuvor generierten Passwort (s. o.) über http://localhost/otobo/index.pl als Benutzer root@localhost anmelden.

Schritt 11: OTOBO Daemon starten

Der OTOBO Daemon übernimmt asynchrone und wiederkehrende Aufgaben in OTOBO. Was früher in CronFile-Definitionen hinterlegt wurde, wird jetzt durch den OTOBO Daemon erledigt. Er ist deshalb für den OTOBO-Betrieb unerlässlich. Außerdem übernimmt der Daemon alle GenericAgent Jobs. Er muss vom OTOBO-Benutzer gestartet werden.

otobo> /opt/otobo/bin/otobo.Daemon.pl start

Schritt 12: CronJobs für den OTOBO-Benutzer

In /opt/otobo/var/cron/\*.dist liegen standardmäßig zwei OTOBO Cron-Dateien, die sicherstellen sollen, dass der OTOBO Daemon läuft. Aktivieren Sie diese, indem Sie die Dateien ohne die Dateinamenerweiterung „.dist“ kopieren.

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

root> cd /opt/otobo/
root> bin/Cron.sh start

Mit diesem Schritt ist die Grundeinrichtung des Systems abgeschlossen.

Schritt 13: Bash Auto-Completion einrichten (optional)

Alle regulären Befehlszeilenoptionen in OTOBO werden über die OTOBO-Konsolenschnittstelle ausgeführt. Damit wird eine Autovervollständigung für Eingaben in die Bash-Shell angeboten, die das Finden geeigneter Befehle und Optionen erheblich erleichtert.

Zum Aktivieren der Bash Auto-Completion installieren Sie das Paket bash-completion. Damit wird automatisch die Datei /opt/otobo/.bash_completion für den Benutzer otobo gesucht und geladen.

Sobald Sie Ihre Konsole neu gestartet haben, können Sie dann folgenden Befehl eingeben und durch TAB ergänzen, um alle verfügbaren Befehle anzuzeigen:

otobo> /opt/otobo/bin/otobo.Console.pl

Geben Sie einige Zeichen und lassen ein TAB folgen, werden alle auf der eingegebenen Zeichenfolge basierenden Befehle angezeigt. Geben Sie einen Befehl vollständig ein und drücken dann TAB, werden alle möglichen Optionen und Argumente angezeigt.

Bemerkung

Sollten Sie Probleme haben, können Sie folgende Zeile als otobo-Benutzer ausführen und zu Ihrem ~/.bashrc hinzufügen, um die Befehle aus der Datei heraus auszuführen.

source /opt/otobo/.bash_completion

Schritt 14: Weiterführende Informationen

Wir empfehlen, das Kapitel OTOBO Performance Tuning zu lesen.