Zurück zum Blog

systemd Service erstellen: Anleitung für Linux

systemd Service erstellen: Unit-Datei schreiben, App beim Booten starten, nach Abstürzen neu starten, Logs mit journalctl lesen und 203/EXEC-Fehler lösen.

Nodesty-Team8 Min. LesezeitServer
Der Schriftzug systemd Service mit systemctl, journalctl und Restart auf dunklem Nodesty-Hintergrund

Einen systemd Service zu erstellen ist der übliche Weg, eine Anwendung auf einem Linux-Server rund um die Uhr laufen zu lassen: systemd startet sie beim Booten, startet sie nach einem Absturz neu und sammelt ihre Logs. Statt Ihre Anwendung in einer SSH-Sitzung oder einem screen-Fenster offen zu lassen, beschreiben Sie sie einmal in einer kleinen Unit-Datei, und das System kümmert sich um den Rest.

In dieser Anleitung zeigen wir, wie Sie eine Unit-Datei schreiben, welche Optionen wichtig sind, Beispiele für eine Node.js- und eine Python-Anwendung, wie Sie Logs lesen, häufige Fehler wie 203/EXEC beheben und einige einfache Härtungsoptionen setzen. Die Befehle beziehen sich auf Ubuntu und Debian, funktionieren aber genauso unter AlmaLinux und anderen Distributionen mit systemd.

Was ist ein systemd-Dienst?

systemd ist das Init-System und der Dienstmanager fast aller modernen Linux-Distributionen. Alles, was es verwaltet, wird in einer Unit-Datei beschrieben; Dienste enden auf .service. Pakete legen ihre Units unter /usr/lib/systemd/system/ ab (auf älteren Debian-basierten Systemen auch unter /lib/systemd/system/), Ihre eigenen Dienste gehören nach /etc/systemd/system/, das Vorrang hat.

Im Vergleich zum manuellen Start mit node app.js gilt für einen Dienst:

  • Er startet nach einem Neustart des Servers automatisch.
  • Er kommt nach einem Absturz der Anwendung wieder hoch.
  • Er läuft unter dem Benutzer und mit der Umgebung, die Sie festlegen.
  • Er schreibt seine Ausgabe ins Journal, das Sie mit journalctl durchsuchen.

Schritt 1: Einen Benutzer für die Anwendung anlegen

Es ist sicherer, die Anwendung nicht als root auszuführen. Legen Sie einen Systembenutzer mit eigenem Home-Ordner und ohne Login-Shell an:

sudo useradd --system --create-home --home-dir /opt/myapp --shell /usr/sbin/nologin myapp

Kopieren Sie Ihre Anwendung nach /opt/myapp (zum Beispiel mit git clone, siehe unsere Anleitung Deployment mit Git) und übertragen Sie den Besitz an den Benutzer:

sudo chown -R myapp:myapp /opt/myapp

Schritt 2: Die Unit-Datei schreiben

Legen Sie die Datei /etc/systemd/system/myapp.service an:

sudo nano /etc/systemd/system/myapp.service

Ein vollständiges Beispiel für eine Node.js-Anwendung:

[Unit]
Description=My Node.js app
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=myapp
Group=myapp
WorkingDirectory=/opt/myapp
ExecStart=/usr/bin/node /opt/myapp/app.js
Restart=on-failure
RestartSec=5
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

Der Dateiname (ohne .service) ist der Name, den Sie mit systemctl verwenden, hier myapp.

Was die einzelnen Zeilen bewirken

OptionBedeutung
DescriptionKurzer Name in systemctl status und in den Logs
After / WantsErst nach dem Netzwerk starten und network-online.target mit anfordern
Type=simpleDer Prozess aus ExecStart ist der Dienst selbst und bleibt im Vordergrund
User / GroupUnter welchem Konto die Anwendung läuft
WorkingDirectoryStartordner der Anwendung; relative Pfade im Code beziehen sich darauf
ExecStartDer auszuführende Befehl, mit absoluten Pfaden
Restart / RestartSecWann neu gestartet wird und wie viele Sekunden vorher gewartet wird
Environment / EnvironmentFileUmgebungsvariablen für die Anwendung
WantedBy=multi-user.targetNach dem Aktivieren beim normalen Booten starten

Einige Punkte, an denen viele hängen bleiben:

  • ExecStart läuft nicht über eine Shell. Pipes, &&, >-Umleitungen und ~ funktionieren nicht. Brauchen Sie wirklich Shell-Funktionen, nutzen Sie ExecStart=/bin/bash -c '...'; ein kleines Skript ist aber meist sauberer.
  • Lassen Sie die Anwendung nicht in den Hintergrund wechseln (etwa mit pm2 start oder nohup ... &). Bei Type=simple erwartet systemd, dass der Prozess im Vordergrund bleibt.
  • Restart=on-failure startet die Anwendung nach einem Absturz oder einem Exit-Code ungleich null neu; Restart=always auch nach einem sauberen Ende. Ein Stopp mit systemctl stop löst nie einen Neustart aus.

Schritt 3: Dienst starten und aktivieren

Machen Sie systemd die neue Datei bekannt, starten Sie dann den Dienst und aktivieren Sie ihn in einem Schritt für den Systemstart:

sudo systemctl daemon-reload
sudo systemctl enable --now myapp
sudo systemctl status myapp

Zeigt die Statusausgabe active (running), funktioniert alles. Die Befehle für den Alltag:

sudo systemctl restart myapp     # nach einem Deployment neu starten
sudo systemctl stop myapp        # stoppen
sudo systemctl disable myapp     # nicht mehr beim Booten starten
systemctl is-enabled myapp       # aktiviert oder nicht?

Führen Sie nach jeder Änderung an der Unit-Datei sudo systemctl daemon-reload aus und starten Sie den Dienst danach neu.

Eine Python-Anwendung mit virtueller Umgebung

Bei Python lassen Sie ExecStart auf das Python in Ihrer virtuellen Umgebung zeigen; so müssen Sie nichts „aktivieren“:

[Unit]
Description=My Python app
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=myapp
WorkingDirectory=/opt/myapp
ExecStart=/opt/myapp/venv/bin/python /opt/myapp/main.py
Restart=always
RestartSec=5
Environment=PYTHONUNBUFFERED=1
EnvironmentFile=/opt/myapp/.env

[Install]
WantedBy=multi-user.target

PYTHONUNBUFFERED=1 sorgt dafür, dass die Ausgabe von print() sofort im Log erscheint, statt gepuffert zu werden. Ein vollständiges Bot-Beispiel mit diesem Aufbau finden Sie in unserer Anleitung Discord-Bot hosten.

Umgebungsvariablen und Geheimnisse

Kurze Werte können Sie mit Environment= direkt in die Unit schreiben. Tokens und Passwörter gehören in eine eigene Datei, die Sie mit EnvironmentFile= laden. Die Datei enthält pro Zeile ein SCHLÜSSEL=Wert, ohne export:

DATABASE_URL=postgres://myapp:secret@localhost/myapp
API_TOKEN=change-me

Machen Sie die Datei nur für ihren Besitzer lesbar:

sudo chown myapp:myapp /opt/myapp/.env
sudo chmod 600 /opt/myapp/.env

Die Datei liest systemd selbst; die Variablen kommen also auch dann bei der Anwendung an, wenn diese die .env nicht selbst einliest. Mehr zu Berechtigungen lesen Sie in unserer Anleitung Linux Dateirechte.

Logs mit journalctl lesen

Alles, was die Anwendung auf die Standardausgabe und den Standardfehler schreibt, landet im Journal:

journalctl -u myapp -f                  # live verfolgen
journalctl -u myapp -n 100              # letzte 100 Zeilen
journalctl -u myapp --since "1 hour ago"
journalctl -u myapp -b                  # seit dem letzten Booten

Sehen Sie keine Ausgabe, stellen Sie sudo voran oder nehmen Sie Ihren Benutzer in die Gruppe adm oder systemd-journal auf. Weitere nützliche Befehle finden Sie in unserer Anleitung Linux Befehle.

Häufige Fehler und ihre Lösung

systemctl status myapp zeigt den Grund für das Beenden in der Zeile Main PID oder Process. Die häufigsten Fälle:

  • status=203/EXEC: systemd konnte das Programm aus ExecStart nicht ausführen. Der Pfad ist falsch oder relativ, die Datei ist nicht ausführbar oder dem Skript fehlt die Shebang-Zeile (#!/usr/bin/env bash). Den echten Pfad ermitteln Sie mit which node oder which python3. Wurde Node.js mit nvm installiert, liegt es im Home-Ordner des Benutzers, zum Beispiel unter /home/user/.nvm/versions/node/<version>/bin/node; verwenden Sie diesen vollständigen Pfad.
  • status=217/USER: Der Benutzer aus User= existiert nicht. Prüfen Sie die Schreibweise oder legen Sie ihn mit useradd an.
  • status=200/CHDIR: Der Ordner aus WorkingDirectory existiert nicht oder der Benutzer hat keinen Zugriff darauf.
  • start-limit-hit: Die Anwendung ist in kurzer Zeit zu oft abgestürzt, deshalb hat systemd aufgegeben. Standardmäßig passiert das nach 5 Starts innerhalb von 10 Sekunden. Beheben Sie zuerst den Absturz (die Ursache steht in journalctl -u myapp) und setzen Sie den Zähler dann mit sudo systemctl reset-failed myapp zurück.

Das Startlimit können Sie im Abschnitt [Unit] anpassen; mit diesen Werten erlaubt systemd 5 Starts innerhalb von 5 Minuten:

[Unit]
StartLimitIntervalSec=300
StartLimitBurst=5

Um eine Unit-Datei vor dem Start auf Tippfehler zu prüfen, führen Sie systemd-analyze verify /etc/systemd/system/myapp.service aus.

Dienste mit systemctl edit anpassen

Möchten Sie einen Dienst ändern, der aus einem Paket stammt, etwa nginx, bearbeiten Sie nicht seine Datei unter /usr/lib/systemd/system/; ein Paket-Update würde sie überschreiben. Legen Sie stattdessen ein Override an:

sudo systemctl edit nginx

Der Befehl öffnet einen Editor und speichert Ihre Zeilen in /etc/systemd/system/nginx.service.d/override.conf. Schreiben Sie nur das hinein, was Sie ändern möchten:

[Service]
Restart=on-failure
RestartSec=5

Beim Schließen des Editors lädt systemd seine Konfiguration neu; starten Sie den Dienst neu, damit die Änderung greift. Wollen Sie ExecStart ersetzen, leeren Sie es zuerst mit einer leeren Zeile ExecStart= und fügen darunter die neue ein. systemctl cat nginx zeigt die Originaldatei zusammen mit Ihren Overrides.

Einfache Härtung

Einige Optionen begrenzen, was die Anwendung anrichten kann, falls sie einmal kompromittiert wird, und machen dabei nur selten etwas kaputt:

[Service]
NoNewPrivileges=true
ProtectSystem=full
PrivateTmp=true
  • NoNewPrivileges=true: Der Prozess und seine Kindprozesse können keine zusätzlichen Rechte erlangen, etwa über sudo oder setuid-Programme.
  • ProtectSystem=full: /usr, /boot und /etc sind für den Dienst schreibgeschützt.
  • PrivateTmp=true: Der Dienst erhält eigene, von anderen Benutzern getrennte Ordner /tmp und /var/tmp.

systemd-analyze security myapp bewertet einen Dienst und listet weitere Optionen auf. Fügen Sie diese einzeln hinzu und testen Sie nach jeder Änderung; allgemeine Serversicherheit behandeln wir in unserer Anleitung Linux Server absichern.

systemd-Timer oder Cron?

systemd kann Aufgaben mit einem Timer auch nach Zeitplan ausführen: Eine .timer-Unit mit demselben Namen wie eine .service-Unit startet diesen Dienst zu festgelegten Zeiten. Ein minimaler /etc/systemd/system/backup.timer, der backup.service jede Nacht ausführt:

[Unit]
Description=Nightly backup

[Timer]
OnCalendar=*-*-* 03:00:00
Persistent=true

[Install]
WantedBy=timers.target

Aktivieren Sie ihn mit sudo systemctl enable --now backup.timer und listen Sie alle Timer mit systemctl list-timers auf. Der gestartete Dienst ist meist vom Type=oneshot. Timer protokollieren ins Journal und holen mit Persistent=true Läufe nach, die verpasst wurden, während der Server aus war. Für einfache Aufgaben ist Cron weiterhin eine gute Wahl; mehr dazu in unserer Anleitung Cronjob einrichten.

systemd-Dienste bei Nodesty

Die Nodesty-Pakete AMD Ryzen 9 9950X vServer und AMD EPYC 7763 vServer kommen mit NVMe-Speicher und vollem Root-Zugriff; so können Sie eigene systemd-Dienste anlegen und Ihre Anwendungen, Bots und APIs rund um die Uhr betreiben. Bei den vServer-Paketen sind tägliche Backups kostenlos und werden 7 Tage aufbewahrt. Was einen Dienst dauerhaft erreichbar hält, erklären wir in unserer Anleitung Was ist Uptime?

Häufig gestellte Fragen

Was ist der Unterschied zwischen Restart=always und Restart=on-failure?

Mit on-failure startet systemd die Anwendung nur neu, wenn sie mit einem Fehlercode endet, durch ein Signal abstürzt oder in ein Timeout läuft; bei einem sauberen Ende mit Code 0 bleibt sie gestoppt. Mit always wird sie auch nach einem sauberen Ende neu gestartet. In beiden Fällen löst ein Stopp mit systemctl stop keinen Neustart aus.

Muss ich nach jeder Änderung daemon-reload ausführen?

Ja. Sobald Sie eine Unit-Datei von Hand anlegen oder bearbeiten, führen Sie sudo systemctl daemon-reload aus, damit systemd die neue Fassung einliest, und starten den Dienst anschließend neu. systemctl edit erledigt das Neuladen beim Speichern und Schließen des Editors selbst, den Dienst müssen Sie aber trotzdem neu starten.

Warum scheitert mein Dienst mit status=203/EXEC?

systemd konnte das Programm aus ExecStart nicht ausführen. Meist ist der Pfad falsch oder relativ, die Datei nicht ausführbar oder einem Skript fehlt die Shebang-Zeile. Ermitteln Sie den vollständigen Pfad mit which node oder which python3, tragen Sie ihn in ExecStart ein und prüfen Sie die Datei mit ls -l.

Wo sehe ich die Ausgabe meiner Anwendung?

Alles, was die Anwendung auf die Standardausgabe und den Standardfehler schreibt, landet im systemd-Journal. Sie lesen es mit journalctl -u myapp, mit -f verfolgen Sie neue Zeilen live und mit -n 100 sehen Sie die letzten 100 Zeilen. Setzen Sie bei Python-Anwendungen PYTHONUNBUFFERED=1, damit die Zeilen sofort erscheinen.

Sollte ich für eine Node.js-Anwendung systemd oder pm2 verwenden?

Beide halten die Anwendung am Laufen und starten sie beim Booten. pm2 bietet Node.js-spezifische Extras wie den Cluster-Modus und eine eigene Log-Ansicht, während systemd bereits Teil des Systems ist, keine zusätzliche Installation braucht und für Node.js, Python, Go oder jedes andere Programm gleich funktioniert.

Kann ein systemd-Dienst einen Cronjob ersetzen?

Ja, ein systemd-Timer kann einen Dienst ähnlich wie Cron nach Zeitplan ausführen. Timer protokollieren ins Journal und holen mit Persistent=true verpasste Läufe nach. Für einfache geplante Aufgaben ist Cron aber weiterhin völlig in Ordnung; wählen Sie die Variante, die Sie leichter pflegen können.

Nodesty

Über den Autor

Nodesty-Team · Infrastruktur und Support

Das Nodesty-Team betreibt unsere Server, unser Netzwerk und unseren DDoS-Schutz im Alltag und beantwortet Support-Anfragen rund um die Uhr. Diese Ratgeber entstehen aus dieser Arbeit.

Verwandte Artikel

Starte deinen Server jetzt.

Erstellen, wachsen und skalieren Sie Ihre Projekte grenzenlos auf der Premium-Infrastruktur von Nodesty.

                                                                                                                                                                                                                            
                                                                                                                                                                                                                            
                                                                                                                                                                                                                            
                                                                                                                             ············································                                                   
                                                ··································································································..........···························                                     
                                       ················..........................................................................................................................··············                             
                                  ·············.................::::::::::::::::::::::::::::::::::::::::::::::....................:::::::::::::::::::::::::::::::::::::::................···········                        
                             ············................:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::............·········                     
                         ············.................:::::::::::::::::::::::::::::::::::::::::::::::::::------------::::::::::::::::::::::::::::::----------------:::::::::::::::::::::..........········                  
                    ············......................::::::::::::::::::::::::::::::::::::------------------------------------------------------------------------------------:::::::::::::.........········                
                ··········.............................................::::::::::::::::::-------------==========================================-----------------------------------:::::::::::........·······               
             ········..................:.....................................::::::::::--------=======+++++++++++++++++++++++++++++++++++++=========================------------------::::::::::.......·······              
           ······.........::::::::::::::::::::................................:::::::-----=====++++xxxxxx**************************xxxxxxxxx++++++++++++++===================------------::::::::.......·······             
          ·····.......:::::::::::::::::::::::::::.............................:::::----===+++xxx****%%%%&&&&&&#############&&&&&&&%%%%%*******xxxxxxxx++++++++++++++==============----------:::::::......······             
         ····......::::::::-------------:::::::::::..........................::::---===+++xx***%%%&&&####@@@@@@@@@@@@@@@@@@@@@@@@####&&&&&%%%%*******xxxxxxxxx+++++++++++++===========--------::::::......·····             
        ····.....:::::::--------------------:::::::::.......................::::---===++xxx**%%&&&###@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@###&&&&%%%%%********xxxxxxxxxxx++++++++++++========------::::::.....······            
        ····.....:::::--------------------------::::::::....................::::---===++xx***%%&&&####@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@###&&&&&%%%%%**********xxxxxxxxxxxxx+++++++++=======------:::::.....·····            
        ····....::::::-------=============---------:::::::::................:::::---===+++xx***%%%&&&#####@@@@@@@@@@@@@@@@@@@@@@@@@#####&&&&&%%%%%%*************xxxxxxxxxxxxxx+++++++++======-----:::::....·····            
         ····....:::::-------================---------:::::::::...............:::::----===++++xxx***%%%%&&&&&&#################&&&&&&%%%%%%%*******************xxxxxxxxxxxxxxxxx++++++++======----:::::....·····            
         ·····....:::::--------=================---------::::::::::..............:::::::-----====+++++xxxxxx**************************xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx++++++++=====-----::::....·····            
          ·····.....:::::--------=================----------:::::::::::.................:::::::::-------=============++++++++++++++++++++++++++++++++++++xxxxxxxxxxxxxxxxxxxxxxx++++++++======-----::::....·····            
            ·····.....:::::::----------===========-------------::::::::::::.........................::::::::::::::::::------------------=============+++++++++++++++++++++++++++++++++=======-----::::.....·····            
              ······......:::::::---------------------------------:::::::::::::........................................:::::::::::::::-----------============+++++++++++++++++++++========------:::::.....·····             
                 ······........:::::::::---------------------------:::::::::::::::::...........................................:::::::::::::------------=============================--------::::::.....······              
                    ·········.........:::::::::::::::-------------::::::::::::::::::::::::.......................................::::::::::::::::--------------------------------------::::::::......·······                
                          ··········............::::::::::::::::::::::::::::::::::::::::::::::::::................................::::::::::::::::::::::::::-------------:::::::::::::::.........········                   
                                  ············..................:::::::::::::::::::::::::::::::::::::::::::.........................:::::::::::::::::::::::::::::::::::::................···········                        
                                             ················.............................................................................................................·················                                 
                                                           ······················................................................................···························                                                
                                                                               ·········································································