X4 Produktdokumentation
X4 Produktdokumentation
Breadcrumbs

Anleitung: systemd-Dienste für X4-Server und X4-Authentication-Provider erstellen und verwalten

In dieser Anleitung erfahren Sie, wie Sie die systemd-Dienste für X4-Server und X4-Authentication-Provider manuell installieren, aktivieren, starten, stoppen und deinstallieren.

Hinweis:

Diese Anleitung ersetzt die frühere automatische Konfiguration, die während der Paketinstallation ausgeführt wurde.

Die Anleitung gilt für zwei Service-Units:

  • X4-Server (erforderlich)

  • X4-Authentication-Provider (optional, nur erforderlich bei Verwendung von Keycloak)

Die beschriebenen Befehle können Sie in der Regel direkt in einem Terminal unter modernen Linux-Distributionen ausführen, die systemd verwenden (z. B. RHEL / CentOS / Alma / Rocky 8+ / 9+, Debian 10+ / 11+ / 12+, Ubuntu 20.04+).

  • Führen Sie alle Befehle als root oder mit sudo aus.

Inhalte des Pakets

Nach dem Entpacken des Installationspakets finden Sie folgende Dateien im Verzeichnis resources/:

  • resources/etc/systemd/system/X4-Server.service

  • resources/etc/default/X4-Server

  • resources/etc/systemd/system/X4-Authentication-Provider.service

  • resources/etc/systemd/system/X4-Authentication-Provider/scripts/preliminary_checks.sh

  • resources/etc/systemd/system/X4-Authentication-Provider/scripts/environment.conf

Hinweis:
Der Dienst X4-Server enthält kein Unterverzeichnis scripts.
Dieses wird nur für den X4-Authentication-Provider benötigt.

Hilfsvariable setzen

Definieren Sie eine Variable, die auf das Verzeichnis zeigt, in dem Sie das Paket entpackt haben: PKG_DIR="/path/to/unpacked/package".
Ersetzen Sie den Platzhalter /path/to/unpacked/package durch den tatsächlichen Pfad.

Beispiel: PKG_DIR="/opt/x4_services"

Dienstdateien installieren

Kopieren Sie die bereitgestellten Unit- und Konfigurationsdateien in die entsprechenden Systemverzeichnisse. Fehlende Verzeichnisse werden automatisch angelegt, und die Berechtigungen werden korrekt gesetzt.

Bash
# --- X4-Server ---
install -D -m 0644 "$PKG_DIR/resources/etc/systemd/system/X4-Server.service" \
  /etc/systemd/system/X4-Server.service
install -D -m 0644 "$PKG_DIR/resources/etc/default/X4-Server" \
  /etc/default/X4-Server
 
# Ensure ownership (normally install sets root:root when run as root)
chown root:root /etc/systemd/system/X4-Server.service /etc/default/X4-Server
 
# --- X4-Authentication-Provider (optional; only if you use Keycloak) ---
# Install the unit file
install -D -m 0644 "$PKG_DIR/resources/etc/systemd/system/X4-Authentication-Provider.service" \
  /etc/systemd/system/X4-Authentication-Provider.service
 
# Create scripts directory and install helper files
install -d -m 0755 /etc/systemd/system/X4-Authentication-Provider/scripts
install -m 0755 "$PKG_DIR/resources/etc/systemd/system/X4-Authentication-Provider/scripts/preliminary_checks.sh" \
  /etc/systemd/system/X4-Authentication-Provider/scripts/preliminary_checks.sh
install -m 0644 "$PKG_DIR/resources/etc/systemd/system/X4-Authentication-Provider/scripts/environment.conf" \
  /etc/systemd/system/X4-Authentication-Provider/scripts/environment.conf
 
# Ensure ownership
chown -R root:root /etc/systemd/system/X4-Authentication-Provider.service \
  /etc/systemd/system/X4-Authentication-Provider

Dienste aktivieren und starten

  1. Laden Sie systemd neu, damit die neuen Unit-Dateien erkannt werden.

  2. Aktivieren Sie anschließend die Dienste, damit sie beim Systemstart automatisch ausgeführt werden. Optional können Sie sie sofort starten.

Bash
# Make systemd aware of new/changed unit files
systemctl daemon-reload
 
# Enable X4-Server to start on boot
systemctl enable X4-Server
 
# Start immediately (optional)
# If you want to mirror the old post-install behavior of auto-start on fresh install:
START_NOW=1  # set to 0 to skip immediate start
if [ "${START_NOW}" = "1" ]; then
  systemctl start X4-Server
fi
 
# Authentication Provider (only if installed/needed)
# Enable and start it if you use Keycloak
if [ -f /etc/systemd/system/X4-Authentication-Provider.service ]; then
  systemctl enable X4-Authentication-Provider
  systemctl start X4-Authentication-Provider
fi

Installation überprüfen

Prüfen Sie den aktuellen Status und die letzten Logeinträge der Services:

systemctl status X4-Server --no-pager
journalctl -u X4-Server -b --no-pager | tail -n 50
 
# If installed
systemctl status X4-Authentication-Provider --no-pager || true
journalctl -u X4-Authentication-Provider -b --no-pager | tail -n 50 || true

Hinweis:

Wenn der Dienst nicht startet, prüfen Sie die Logs und die in der Unit referenzierten Environment-Dateien:

  • /etc/systemd/system/X4-Authentication-Provider/scripts/environment.conf

  • /etc/systemd/system/X4-Authentication-Provider/scripts/preliminary_checks.sh

Services deinstallieren

Führen Sie folgende Schritte aus, um die Dienste und alle Dienstdateien vollständig zu entfernen.

Bash
# Stop and disable X4-Server
systemctl stop X4-Server || true
systemctl disable X4-Server || true
 
# Remove unit and any legacy directory if present
rm -f /etc/systemd/system/X4-Server.service
rm -rf /etc/systemd/system/X4-Server  # legacy path; safe if it does not exist
 
# Authentication Provider (only if installed)
if [ -f /etc/systemd/system/X4-Authentication-Provider.service ]; then
  systemctl stop X4-Authentication-Provider || true
  systemctl disable X4-Authentication-Provider || true
  rm -f /etc/systemd/system/X4-Authentication-Provider.service
  rm -rf /etc/systemd/system/X4-Authentication-Provider
fi
 
# Make systemd forget removed units and clear failures
systemctl daemon-reload
systemctl reset-failed

Hinweis:
Entfernen Sie /etc/default/X4-Server nur, wenn Sie sicher sind, dass keine anderen Prozesse diese Datei verwenden: rm -f /etc/default/X4-Server

Tipps zur Fehlerbehebung

Aktion

Befehl

Reload nach jeder Änderung an Unit-Dateien

systemctl daemon-reload

Zusammengeführte Unit-Definition anzeigen

systemctl cat X4-Server

Letzte Logeinträge anzeigen

journalctl -u X4-Server -b --no-pager

Service neu starten und Status anzeigen

systemctl restart X4-Server && systemctl status X4-Server --no-pager

Dateiberechtigungen prüfen:
Unit-Dateien sollten root:root gehören (Skripte in der Regel 0755, Konfigurationsdateien 0644).

Bei aktivem SELinux ggf. Labels anpassen (z. B. mit restorecon) oder Skripte in Standardpfade verschieben.

Netzwerkzugriff prüfen: erforderliche Ports müssen in der Firewall (firewalld / ufw / iptables) freigeschaltet sein.

Unterschiede zur früheren automatischen Installation

In früheren Versionen wurden die Dienstdateien während der Paketinstallation automatisch installiert, Berechtigungen gesetzt, daemon-reload wurde ausgeführt, und die Dienste wurden aktiviert (teilweise auch gestartet).
Die hier beschriebenen Schritte bilden dieses Verhalten nun manuell nach und eignen sich auch für automatisierte Skriptinstallationen.

Anhang: Schneller Installationsblock

Wenn Sie sich im entpackten Wurzelverzeichnis des Pakets befinden, können Sie alle Schritte mit folgendem Block ausführen (der Authentication Provider ist optional):

set -euo pipefail
PKG_DIR="$(pwd)"

install -D -m 0644 "$PKG_DIR/resources/etc/systemd/system/X4-Server.service" /etc/systemd/system/X4-Server.service
install -D -m 0644 "$PKG_DIR/resources/etc/default/X4-Server" /etc/default/X4-Server
chown root:root /etc/systemd/system/X4-Server.service /etc/default/X4-Server

Optional: Keycloak Authentication Provider

if [ -f "$PKG_DIR/resources/etc/systemd/system/X4-Authentication-Provider.service" ]; then
  install -D -m 0644 "$PKG_DIR/resources/etc/systemd/system/X4-Authentication-Provider.service" /etc/systemd/system/X4-Authentication-Provider.service
  install -d -m 0755 /etc/systemd/system/X4-Authentication-Provider/scripts
  install -m 0755 "$PKG_DIR/resources/etc/systemd/system/X4-Authentication-Provider/scripts/preliminary_checks.sh" \
    /etc/systemd/system/X4-Authentication-Provider/scripts/preliminary_checks.sh
  install -m 0644 "$PKG_DIR/resources/etc/systemd/system/X4-Authentication-Provider/scripts/environment.conf" \
    /etc/systemd/system/X4-Authentication-Provider/scripts/environment.conf
  chown -R root:root /etc/systemd/system/X4-Authentication-Provider.service /etc/systemd/system/X4-Authentication-Provider
fi

systemctl daemon-reload
systemctl enable X4-Server
systemctl start X4-Server

if [ -f /etc/systemd/system/X4-Authentication-Provider.service ]; then
  systemctl enable X4-Authentication-Provider
  systemctl start X4-Authentication-Provider
fi