Voraussetzungen für den Betrieb eines FirstSpirit-Servers sind Java, der Java Service Wrapper und die entsprechenden Steuerungsdateien zum Starten und Stoppen des FirstSpirit-Servers (bzw. der Java JVM).

Die gewünschten Aktionen, u.a.:

Start des FirstSpirit-Servers,
Stopp des FirstSpirit-Servers,
Neustart des FirstSpirit-Servers,
Erzeugen von Thread Dumps, ...

werden über die Steuerungsdatei fs-server an die JVM weitergegeben. Die Steuerung erfolgt über ein Shell-Skript bzw. einen Systemdienst.

Bereitstellung der Steuerungsdateien

Bereitstellung über das Aktualisierungsarchiv fs-update-[version].tar.gz

Der Java Service Wrapper und die zugehörige, aktuelle Version der Steuerungsdateien werden von Crownpeak über das Aktualisierungsarchiv (für bestehende Installationen) bereitgestellt.

Das Archiv ist per Download erhältlich (für Zugangsdaten wenden Sie sich bitte an den Technical Support).

Die Steuerungsdateien (fs-server und fs-server.bat) dürfen nicht verändert werden.

Entpacken des Archivs im Installationsverzeichnis

Das Archiv muss zunächst dekomprimiert (G(un)zip) und im vorhandenen FirstSpirit-Server-Installationsverzeichnis ausgepackt werden.

Exemplarischer Aufruf unter Linux für das Aktualisierungsarchiv:

~/firstspirit5$ tar xvfz fs-update-[version].tar.gz

Mit der tar-Option xvfz wird das gezippte tar-Archiv ( *.tar.gz ) entpackt.

Nach dem Auspacken sollten die Benutzer- und Gruppenrechte der ausgepackten Dateien betrachtet und ggfs. angepasst werden.

Schritt 1) Benutzer anlegen

Wir empfehlen, einen eigenen Systembenutzer für den FirstSpirit-Server anzulegen und den FirstSpirit-Server nicht als root zu starten.

Im Beispiel wird der Systembenutzer fs angelegt:

useradd fs

Der FirstSpirit-Server muss an mehreren Stellen in seinem Installations-Verzeichnis Dateien anpassen können. Am einfachsten ist es, ihn sein Installationsverzeichnis komplett schreiben zu lassen:

chown -R fs:fs ~FS

~FS dient hier als Platzhalter für das Server-Installationsverzeichnis.

Schritt 2) Wartungsmodus aktivieren

Alle Clients sollten vor Beginn der Aktionen abgemeldet sein.

Vor dem Starten und Stoppen des FirstSpirit-Servers kann der Wartungsmodus aktiviert werden.

Schritt 3) Die Steuerungsdatei fs-server

Im Installations- bzw. Aktualisierungsarchiv ist aktuell jeweils eine Steuerungsdatei für Linux und Windows enthalten.

(Die Steuerungsdatei fs-server.bat wird ausschließlich für Windows-Betriebssysteme benötigt - siehe Steuerung unter Windows)

Der Funktionsumfang der Steuerungsdatei fs-server kann in der Kommandozeile über die integrierte Hilfe (Usage, Command syntax, Commands) aufgerufen werden, beispielsweise über den Aufruf fs-server:

fs@fs_example:~$ fs-server 
Usage: /home/fs_example/firstspirit/bin/fs-server [ console | start | stop | restart | condrestart | status | install | installstart | remove | dump ] 
Commands: 
console Launch in the current console. 
start Start in the background as a daemon process. 
stop Stop if running as a daemon or in another console. 
restart Stop if running and then start. 
condrestart Restart only if already running. 
status Query the current status. 
install Install to start automatically when system boots. 
installstart Install and start running as a daemon process. 
remove Uninstall. 
dump Request a Java thread dump if running.

Für die Verwendung der Steuerungsdatei fs-server ist ein Java Service Wrapper ab Version 3.5.42 notwendig:

Mit dem FirstSpirit Aktualisierungsverzeichnis erhalten sie immer eine aktuelle Version des Wrappers sowie die dazu passenden Steuerungsdateien.
Die Version des Java Service Wrappers, die auf dem Server aktuell verwendet wird, kann über das FirstSpirit ServerMonitoring ermittelt werden. Unter ServerMonitoring - Übersicht - Status wird unter „Grundinformationen (System)“ die „Wrapper-Version“ eingeblendet.
Entspricht die verwendete Wrapper-Version nicht der vom FirstSpirit-Server empfohlenen, wird dies durch rote Schrift und den Zusatz veraltet angezeigt. In der Datei fs-wrapper.log wird dies ebenfalls festgehalten.
In diesem Fall sollte der Java Service Wrapper zeitnah aktualisiert werden (siehe dazu Das FirstSpirit-Backend aktualisieren).

Optionale Konfigurationsdatei fs-server-custom.shconf

Über die Datei fs-server-custom.shconf kann

der Benutzer festgelegt werden, mit dem der FirstSpirit-Server gestartet werden soll
der Pfad zur Java-Version definiert werden.

Bei einem Update des FirstSpirit Backends wird die Datei nicht automatisch aktualisiert und ist daher nicht in der Datei fs-update-[Version].tar.gz enthalten. Für bereits installierte Server kann die Datei aus der Datei fs-install-[Version]*.tar.gz extrahiert werden.

Anschließend müssen in der Datei die entsprechenden Zeilen einkommentiert (führendes # entfernt) und mit den gewünschten Werten versehen werden.

RUN_AS_USER=<Username>
export FS_JAVA_HOME=<path to java>

Schritt 4) Server steuern

Die Steuerungsdateien unterstützen die Steuerung des FirstSpirit-Servers auf unterschiedlichen Init-Systemen.

Aktuell werden unterstützt:

systemd
Upstart
System-V-Init

Nachfolgend wird die Installation des Systemdienstes und die Steuerung des FirstSpirit-Servers am Beispiel des Init-Systems systemd gezeigt.

Für die anderen Init-Systeme ist die Installation des Systemdienstes und die Steuerung des FirstSpirit-Servers analog zum Vorgehen unter systemd möglich. Die einzelnen Kommandos, der Installationsort und die Konfiguration können aber, abhängig vom eingesetzten Init-System, abweichen.

Eine vollständige Dokumentation ist an dieser Stelle nicht möglich. Bitte konsultieren Sie hierfür die Dokumentation von systemd, Upstart und System-V-Init, insbesondere die Hinweise zur Härtung und Absicherung.

Beispiel: systemd

Alle größeren Linux-Distributionen verwenden systemd zur Steuerung von Systemdiensten. systemd ist im Vergleich zur Alternative SysVinit schneller und flexibler und ermöglicht beispielsweise den gleichzeitigen Start von Systemdiensten.

systemd: Voraussetzungen

Für die Verwendung mit der Steuerungsdatei fs-server sollte:

Das Programm pidof installiert sein:
Die Steuerungsdateien fs-server verwenden intern das Programm pidof. Damit die Steuerungsdateien funktionieren, sollte das Programm auf dem System installiert sein.
Das Modul systemd PAM (Pluggable Authentication Modules) installiert und für die FirstSpirit-Benutzersitzung registriert sein (z. B. libpam-systemd unter Debian). (Das Modul wird zur Identifikation des systemd-Prozesses benötigt.)

Crownpeak empfiehlt, für die Steuerung des FirstSpirit-Servers ausschließlich die regulären systemctl-Dienste zu verwenden. Die Verwendung von systemd- und sysctl-Ersetzungen (wie z. B. „Fake Systemd“ oder „docker systemctl replacement“) wird nicht unterstützt und kann zu Problemen führen.

systemd: Dienst installieren und Server starten (unter eigenem System-Benutzerkonto)

Der Dienst wird über die Kommandozeile installiert, für die Steuerungsdatei fs-server über den Befehl:

~FS/bin/fs-server install

oder alternativ über den Befehl:

~FS/bin/fs-server installrun

Nur bei einer Installation über systemd relevant:
Bei der Verwendung von installrun müssen die systemd-Overwrites vor der Ausführung unter /etc/systemd/system/fs-server.service.d/override.conf vorhanden sein
(siehe auch systemd: Konfiguration über Unitfiles).

Unter eigenem System-Benutzerkonto: Unter Linux sollten Prozesse aus Sicherheitsgründen nicht mit root-Rechten, sondern in einem abgesicherten Benutzerkontext ausgeführt werden. Die Ausführung des Kontrollskriptes setzt zwar root-Rechte voraus, der eigentliche Prozess wird aber in einem Benutzerkontext ausgeführt.

Um den Benutzer anzugeben, der für den Prozess genutzt werden soll, kann die optionale Konfigurationsdatei fs-server-custom.shconf verwendet werden (siehe Abschnitt Benutzer anlegen).

Nach der Installation des systemd-Dienstes wird ausschließlich systemd zur Steuerung verwendet, d. h. auch bei einem Aufruf von fs-server im Benutzerkonto wird systemctl verwendet (bei der Verwendung eines anderen Init-Systems kann das Kommando abweichen).

Der Benutzer muss zum Starten und Stoppen des systemd-Dienstes über ausreichende Berechtigungen in systemd verfügen, ansonsten wird der Benutzer nach dem root-Passwort gefragt. Für die Konfiguration der Benutzerberechtigung (z. B. mithilfe von polkitd) ist eine vollständige Dokumentation an dieser Stelle nicht möglich. Bitte konsultieren Sie hierfür die Dokumentation von systemd.

Alle Subkommandos können anschließend über systemd nach der folgenden Syntax ausgeführt werden:

systemctl [reload|restart|start|status|stop|...] fs-server

oder alternativ über:

~FS/bin/fs-server [reload|restart|start|status|stop|...]

z. B. Starten des FirstSpirit-Servers:

systemctl start fs-server

bzw.:

~FS/bin/fs-server start

Zur Installation und Konfiguration siehe auch Betriebssystem vorbereiten (Unix) (→Installationsanleitung).

systemd: Konfiguration über Unitfiles

systemd verwaltet seine Dienste über Units. Die Dateien, die eine solche Unit (hier den FirstSpirit-Server) während des Bootens initialisieren und starten, heißen Unitfiles. Unitfiles sind keine ausführbaren Dateien mehr, sondern Konfigurationsfiles vergleichbar mit den Ini-Dateien von Windows.

Durch den Befehl ~FS/bin/fs-server install wird die systemd-Service-Datei automatisch erzeugt und üblicherweise unter /etc/systemd/system abgelegt.

Bestehende Unitfiles können mit dem Befehl edit erweitert werden - dazu ist die entsprechende die systemd-Service-Datei anzugeben, z. B.:

systemctl edit fs-server.service

Ein einfaches Beispiel einer Konfiguration (fs-server) sieht wie folgt aus:

[Service]
Group=fs
UMask=0027
LimitNOFILE=10000
Environment="FS_JAVA_HOME=/opt/openjdk/lts"

Im Abschnitt [Service] werden Umgebungsvariablen definiert:

UMask: Der hier konfigurierte Wert sollte sich an der Standardeinstellung der Konfigurationsdatei fs-wrapper.conf orientieren (siehe wrapper.umask). Standardmäßig ist der Wert für diesen Parameter 0027. Das bedeutet, dass die Benutzerklasse „Gruppe“ (engl. group) über Lese- und die Benutzerklasse „Sonstige“ (engl. others) über keinerlei Rechte verfügt.
LimitNOFILE: Über diese Variable können die Ressourcenlimits, also die maximal mögliche Anzahl gleichzeitig geöffneter Filehandles unter dem Benutzerkonto des FirstSpirit-Servers definiert werden (siehe hierzu Betriebssystem vorbereiten (Unix) (→Installationsanleitung)).
Environment: Innerhalb des Service-Blocks kann die Direktive Environment= eingefügt werden, um z. B. die Variable FS_JAVA_HOME in der systemd-Servicedatei zu deklarieren.

Schritt 5) Fehlerdiagnose und Monitoring

Protokollierung / Logdateien

Falls während bzw. nach dem Start des FirstSpirit-Servers Probleme auftreten, liefern die Logdateien fs-server.log und fs-wrapper.log unter ~FS/log detaillierte Hinweise zur Problemursache.

Kann die Java VM nicht gestartet werden, wird nur die fs-wrapper.log aktualisiert.

Für eine weiterführende Analyse und Auswertung der Logdateien können sie sich auch an den Technical Support wenden.

Stackdump erzeugen

Über den Befehl:

fs-server dump

wird ein aktueller Thread Dump erstellt und nach ~FS/log/fs-dump-DATUM-UHRZEIT.log geschrieben.

Eine weitere Analysemöglichkeit bietet das FirstSpirit ServerMonitoring. Die über die Funktionalität Threads erstellten Thread Dumps können hier analysiert und in einer aufbereiteten Ansicht angezeigt werden.

Status des Dienstes ausgeben

Statusinformationen zum Dienst können über den Befehl:

fs-server status

ausgegeben werden.

Runlevel

Beim Start eines FirstSpirit-Servers stehen Informationen über den aktuellen Runlevel zur Verfügung.

Die Runlevel werden an verschiedenen Stellen ausgegeben:

als Logausgabe in der Datei fs-server.log bzw. fs-wrapper.log
als Wert [Zahl] in der Datei ~FS/.fs.lock

Anhand dieser Runlevels kann abgelesen werden, ob bzw. wann welche Server-Funktionalität zur Verfügung steht:

SHUTDOWN (RunLevel 0)
Der Server ist heruntergefahren.
Hinweis: Die Datei ~FS/.fs.lock ist in diesem Runlevel nicht vorhanden.
IN_PROGRESS (RunLevel 20)
Der Server startet bzw. wird beendet, es sind keine Funktionalitäten sicher verfügbar.
CORE_STARTED (RunLevel 40)
Die Grundfunktionalitäten stehen zur Verfügung, der Server kann über den SOCKET-Port erreicht werden.
ROOT_WEBAPP_STARTED (RunLevel 60)
Der Server kann nun auch über den HTTP-Port erreicht werden.
CORE_WEBAPPS_STARTED (RunLevel 80)
Die globalen Web-Anwendungen stehen zur Verfügung.
STARTED (RunLevel 100)
Alle FirstSpirit-Funktionalitäten stehen zur Verfügung.

Auf diese Runlevel kann beispielweise per API reagiert werden (Interface RunLevelAgent, Package de.espirit.firstspirit.agency, FirstSpirit Access-API).

Druckversion | Seitenanfang