X4 Produktdokumentation
X4 Produktdokumentation
Breadcrumbs

Instructions: Creating and Managing systemd Services for X4-Server and X4-Authentication-Provider

These instructions explain how to manually install, enable, start, stop, and uninstall systemd services for X4-Server and X4-Authentication-Provider.

Note:

These instructions replace the previous automatic configuration that was performed during the package installation.

The instructions apply to two service units:

  • X4-Server (erforderlich)

  • X4 Authentication-Provider (optional, only required when using Keycloak)

The described commands can usually be executed directly in a terminal under modern Linux distributions that use systemd (e.g. RHEL / CentOS / Alma / Rocky 8+ / 9+, Debian 10+ / 11+ / 12+, Ubuntu 20.04+).

  • Run all commands as root or with sudo.

Contents of the package

After unpacking the installation package, you will find the following files in the resources/ directory:

  • 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

Note:
The X4-Server service does not contain a scripts subdirectory.
This is only required for the X4-Authentication-Provider.

Setting an auxiliary variable

Define a variable that points to the directory where you extracted the package: PKG_DIR="/path/to/unpacked/package".
Replace the placeholder /path/to/unpacked/package with the actual path.

Example: PKG_DIR="/opt/x4_services"

Installing service files

Copy the supplied unit and configuration files to the appropriate system directories. Missing directories are created automatically and the permissions are set correctly.

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

Activating and starting services

  1. Reload systemd to recognize the new unit files.

  2. Then enable the services to run automatically when the system starts. Optionally, you can start it immediately.

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

Checking the installation

Check the current status and the last log entries of the 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

Note:

If the service does not start, check the logs and the environment files referenced in the unit:

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

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

Deinstalling services

Complete the following steps to completely remove the services and all service files.

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

Note:
Remove /etc/default/x4-server only if you are sure that no other processes are using this file: rm -f /etc/default/x4-server

Troubleshooting tips

Action

Command

Reload after each change to unit files

systemctl daemon-reload

View the merged unit definition

systemctl cat X4-Server

Display the last log entries

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

Restart the service and view the status

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

Check file permissions:
Unit files should belong to root:root (scripts usually 0755, configuration files 0644).

activeIf SELinux is , if necessary Customize labels (for example, with restorecon) or move scripts to default paths.

Check network access: Required ports must be enabled in the firewall (firewalld / ufw / iptables).

Differences from the previous automatic installation

In previous versions, the service files were automatically installed during package installation, permissions were set, daemon-reload was executed, and the services were enabled (some of them started).
The steps described here now manually replicate this behavior and are also suitable for automated scripting installations.

Appendix: Fast installation block

If you are in the unzipped root directory of the package, you can perform all the steps using the following block (the authentication provider is 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