Cheatsheet Tagesbetrieb

Cheatsheet Tagesbetrieb

← Home

Kompakte Alltags-Befehlsseite für den B42-Dedicated-Server dieses Repos. Alles, was beim Betrieb täglich gebraucht wird, in Tabellenform — Befehle, Wirkung und Pfade jeweils 1:1 aus dem Repo-Klon.

Vertieft in Repo: Makefile, scripts/, systemd/; Detailseiten Makefile-Referenz, Skripte-Referenz, systemd-Referenz, Monitoring-und-Alerts, Backup-und-Restore, Admin-Befehle.

Voraussetzungen und Stolperfallen (vor dem ersten Aufruf)

• Alle Befehle aus dem Repo-Root aufrufen, nicht aus scripts/ (Repo-Default; Makefile-Pfade sind relativ).
• .env muss im Repo-Root existieren und ausführbar gelesen werden können (Repo-Default; sonst brechen Skripte mit „.env fehlt. Erst: cp .env.example .env und Werte setzen." ab).
• Shell-Skripte brauchen Exec-Bits (Repo-Default); nach einem git clone ohne gesetzte Bits zuerst chmod +x scripts/*.sh scripts/lib/*.sh ausführen.
• sudo wird für make start/stop/restart/logs/status und für monitor.sh-Cron-Aufrufe gebraucht (Repo-Default, Makefile 1:1).

make-Cheatsheet (alle 16 Targets)

Reihenfolge und Wirkung: Repo-Default (1:1 aus projectzomboid-repo/Makefile).

Befehl	Wirkung	Detail
make / make help	Alle Targets mit Kurzbeschreibung anzeigen (Default-Ziel)	Makefile-Referenz
make install	Erstinstallation (SteamCMD, App 380870, Verzeichnisse)	Quickstart-Linux
make render	Configs aus Templates + .env generieren (envsubst)	Server-Konfiguration
make mods	Modliste aus mods.yaml validieren + generieren	Mods-Referenz
make spawns	Spawn-Configs aus spawns.yaml generieren	Spawn-System
make validate	mods.yaml + Shell-Skripte prüfen (shellcheck, falls vorhanden)	Mods-Referenz
make start	Server starten (sudo systemctl start zomboid)	systemd-Referenz
make stop	Server stoppen (sudo systemctl stop zomboid)	systemd-Referenz
make restart	Server neustarten (sudo systemctl restart zomboid)	systemd-Referenz
make status	Service-Status + Healthcheck (systemctl status + healthcheck.sh)	Monitoring-und-Alerts
make logs	Live-Logs anzeigen (sudo journalctl -u zomboid -f)	Monitoring-und-Alerts
make update	Sicheres Update (Backup -> Update -> Healthcheck -> Rollback)	Updates-und-Rollback
make backup	Manuelles Backup (backup.sh)	Backup-und-Restore
make restore	Backup wiederherstellen, interaktiv (restore.sh)	Backup-und-Restore
make healthcheck	Healthcheck einzeln ausführen (healthcheck.sh)	Monitoring-und-Alerts
make failover-sync	Backups in GCP-Bucket spiegeln (gcp/sync-backups.sh)	GCP-Failover

Anzahl der Targets: 16 (Repo-Default, 1:1 aus .PHONY-Zeile im Makefile). Die Hilfe zeigt jederzeit make ohne Argument; das Default-Ziel ist help durch .DEFAULT_GOAL := help (Repo-Default).

Die 11 automatischen Discord-Events

Aus den Repo-Skripten (1:1 gelistet in Monitoring-und-Alerts). Farbcodes dezimal aus den Skripten.

Ereignis	Quelle	Farbe (dezimal)
Update-Zyklus gestartet (Server geht gleich offline)	update.sh	15105570
Update erfolgreich, Server läuft	update.sh	3066993
FEHLER — Rollback auf Pre-Update-Backup	update.sh	15158332
Rollback erfolgreich, alter Stand läuft	update.sh	3066993
KRITISCH: Rollback-Healthcheck fehlgeschlagen	update.sh	15158332
Backup FEHLGESCHLAGEN	backup.sh	15158332
Naechtliches Backup OK (nur bei Label daily)	backup.sh	3066993
Restore erfolgreich (mit Backup-Dateiname)	restore.sh	3066993
Server war abgestürzt und neu gestartet (Watchdog)	monitor.sh	15105570
KRITISCH: Watchdog-Neustart fehlgeschlagen	monitor.sh	15158332
Installation abgeschlossen (Erstinstallation)	install.sh	3066993

Hex-Umrechnung zur Orientierung: 15105570 = #E67E22 (Orange/Warnung), 3066993 = #2ECC71 (Grün/OK), 15158332 = #E74C3C (Rot/Kritisch) (Heuristik). Ein normaler make start/make stop sendet kein Discord-Event (Repo-Stand).

Backup-Verzeichnis lesen

restore.sh zeigt die verfügbaren Backups automatisch nummeriert an (1:1 aus scripts/restore.sh). Wer die Liste vorher sehen will, ohne den Restore zu starten:

ls -1t "${BACKUP_DIR}"/*.tar.gz 2>/dev/null | head -20

BACKUP_DIR per Repo-Default /opt/pzserver/backups (Repo-Default). Backups tragen das Schema <label>-<datum>-<uhrzeit>.tar.gz, z. B. daily-20260816-040001.tar.gz oder pre-restore-20260816-153022.tar.gz (Repo-Default aus scripts/backup.sh).

Healthcheck-Schnellinterpretation

make healthcheck läuft drei Prüfungen (1:1 aus scripts/healthcheck.sh):

Ausgabe	Bedeutung	Exit-Code
OK: Server-Prozess aktiv	Java-Prozess läuft ODER Service aktiv	0
OK: UDP <GAME_PORT> gebunden	UDP-Port sichtbar (16261 per Repo-Default)	0
WARN: Port <GAME_PORT> nicht sichtbar (Server evtl. noch am Starten)	Port fehlt — typisch direkt nach start	0 (zählt nicht als Fehler, Repo-Default)
FAIL: Kein Server-Prozess gefunden	Weder pgrep noch systemctl sehen den Server	1
FAIL: Kritische Fehler im Log (letzte 5 Min)	OutOfMemory/Exception in thread/FATAL im Journal	1

Detaillierte Deutung: Monitoring-und-Alerts.

Performance-Stichproben (einzeilig)

Wer kurz prüfen will, ob die Kiste noch ausreicht (alle Befehle Heuristik/Standard-Linux, nicht im Repo selbst verankert):

Frage	Befehl
Welcher Kern ist heiß?	pidstat -t -p $(pgrep -fi zomboid) 2
Warten auf Storage?	vmstat 2 (Spalte wa)
Gerätelatenz?	iostat -x 2 (Spalte await)
Aktuelle Spielerzahl?	In-Game via /players (siehe Admin-Befehle)
RAM-Heap des Servers?	ps -o rss= -p $(pgrep -fi zomboid)

Vertiefung: Performance-Guide und docs/09-performance.md.

systemctl — die wichtigsten Operationen

Unit-Name zomboid ist Repo-Default (1:1 aus systemd/zomboid.service).

Befehl	Wirkung	Anmerkung
sudo systemctl start zomboid	Server starten	Entspricht make start (Repo-Default)
sudo systemctl stop zomboid	Server stoppen	Vor manuellen Stopps touch .planned-stop (Heuristik; siehe Wartung-und-Automatik)
sudo systemctl restart zomboid	Server neustarten	Hart-Neustart — sauberer Weg: /quit als Admin
sudo systemctl status zomboid --no-pager	Status inkl. Neustart-Historie	Entspricht make status (Repo-Default)
sudo systemctl enable zomboid	Autostart nach Boot aktivieren	systemd-Referenz
sudo systemctl daemon-reload	Unit-Files neu einlesen	Nach jeder Änderung an Unit-Dateien nötig
`sudo systemctl list-timers --all	grep zomboid`	Backup- und Update-Timer anzeigen

journalctl-Rezepte

Detailseiten: Monitoring-und-Alerts.

Frage	Befehl
Was passiert gerade? (live folgen)	sudo journalctl -u zomboid -f (= make logs, Repo-Default)
Die letzten 100 Zeilen ansehen	sudo journalctl -u zomboid -n 100 --no-pager
Nur Fehler (wie der Healthcheck sie sucht)	sudo journalctl -u zomboid --no-pager | grep -iE "OutOfMemory|Exception in thread|FATAL"
Fehler der letzten 5 Minuten	sudo journalctl -u zomboid --since "5 min ago" --no-pager
Seit einem Zeitpunkt (z. B. nach Update)	sudo journalctl -u zomboid --since "2026-08-15 03:00" --no-pager

Die Schlüsselwörter OutOfMemory, Exception in thread, FATAL stammen 1:1 aus scripts/healthcheck.sh (Repo-Default); alles, was dort in den letzten 5 Minuten matcht, lässt den Healthcheck rot werden.

Skript-Direktaufrufe (ohne make)

Aufruf immer aus dem Repo-Root (Repo-Default). bash davor ist nötig, falls die Exec-Bits nach dem Klon fehlen.

Befehl	Wirkung
bash scripts/announce.sh	RCON-Countdown an Spieler (15/5/1 Min) vor Neustart
bash scripts/announce.sh && sleep 30 && sudo systemctl stop zomboid	Manueller Warn-Countdown + Stop
bash scripts/healthcheck.sh	Prozess + UDP-Port + Log-Fehler prüfen
bash scripts/backup.sh	tar.gz-Backup mit Rotation (Label daily)
bash scripts/backup.sh pre-update	Benanntes Backup (z. B. vor Wartung)
bash scripts/restore.sh	Interaktives Wiederherstellen aus Backup-Verzeichnis
bash scripts/update.sh	Sicherer Update-Zyklus (Backups vor Update, Auto-Rollback)
bash scripts/notify.sh "Titel" "Text" [color]	Manueller Discord-Ping (Color dezimal, Default 3447003 blau)
bash scripts/monitor.sh	Watchdog (Cron, normalerweise nie manuell)

backup.sh akzeptiert ein optionales Label als Argument (1:1 aus dem Skript: LABEL="${1:-daily}"); daily triggert zusätzlich die Discord- „Naechtliches Backup OK"-Notification. restore.sh ist interaktiv — Auswahl per Nummer, dann j/n zur Bestätigung (1:1 aus scripts/restore.sh).

Log- und State-Dateien

Pfade 1:1 aus dem Repo-Setup (Repo-Default).

Pfad	Inhalt
${PZ_DATA_DIR}/Saves/	Weltspeicher-Daten (/opt/pzserver/Zomboid/Saves per Repo-Default)
${PZ_DATA_DIR}/Server/	servertest.ini, Sandbox-Lua, Spawn-Lua (Repo-Default)
${PZ_DATA_DIR}/Server/servertest.ini	Hauptkonfig des Default-Servers (Repo-Default; entsteht nach make render)
${PZ_DATA_DIR}/Saves/Multiplayer/<world>/	Welt + Cell-Daten, Hauptziel jedes Backups (Repo-Default)
${PZ_DATA_DIR}/db/	Datenbankdateien des Servers (Community-Quelle: pzwiki)
${BACKUP_DIR}/	Backup-Archive (/opt/pzserver/backups per Repo-Default)
${REPO_ROOT}/logs/server.log	Skript-Logs aller Repo-Skripte (Repo-Default; Logging aus lib/common.sh)
${REPO_ROOT}/config/generated/workshop-items.txt	Generierte Workshop-/Mod-Liste aus mods.yaml (Repo-Default)
${REPO_ROOT}/.planned-stop	Lockfile: geplanter Stopp, kein Watchdog-Neustart (Repo-Default)
sudo journalctl -u zomboid	Unit-Journal (Repo-Default)

RCON-Kurzzeile

Für einmalige In-Game-Ansagen via RCON (Host im Repo hardkodiert auf 127.0.0.1 — siehe Admin-Befehle):

mcrcon -H 127.0.0.1 -P "${RCON_PORT}" -p "${RCON_PASSWORD}" \
  'servermsg "Hallo, Welt!"'

Werte aus .env (Repo-Defaults: RCON_PORT=27015, RCON_PASSWORD=CHANGE_ME). Der Verbindungsaufruf ist 1:1 aus scripts/announce.sh. Guard dort: RCON_ENABLED muss true sein, sonst macht das Skript still exit 0.

Notfall in 3 Schritten

Wenn der Server nicht mehr reagiert und Backups altern:

1. Stop: sudo systemctl stop zomboid (vorher touch .planned-stop, falls der Watchdog läuft — siehe Wartung-und-Automatik).
2. Aktuellen Stand sichern: bash scripts/backup.sh pre-restore (schreibt ein Label-Backup vor jedem Restore; 1:1 aus scripts/restore.sh).
3. Restore: bash scripts/restore.sh (interaktiv, wählt Backup aus Liste, fragt j/N ab; startet danach den Server wieder und ruft nach 45 s den Healthcheck auf, 1:1 aus scripts/restore.sh).

Details: Backup-und-Restore.

Stolperfallen

• Aus falschem Verzeichnis aufgerufen: make-Targets und Skripte gehen von Pfaden relativ zum Repo-Root aus. Wer cd scripts && bash healthcheck.sh startet, verliert u. a. den REPO_ROOT-Pfad aus lib/common.sh (Heuristik).
• Exec-Bits fehlen nach git clone: Symptom ist Permission denied direkt auf dem Skript. Fix einmalig: chmod +x scripts/*.sh scripts/lib/*.sh (Heuristik; Symptom im Repo nicht dokumentiert).
• .env fehlt: Skripte brechen mit „.env fehlt. Erst: cp .env.example .env und Werte setzen." ab (1:1 aus lib/common.sh); kein Fallback auf .env.example.
• touch .planned-stop vergessen: Watchdog startet den bewusst gestoppten Server sofort wieder hoch (1:1 aus scripts/monitor.sh; siehe Monitoring-und-Alerts).
• sudo systemctl stop ohne Vorlauf: Hart-Stop schreibt das Journal mit unsauberem Shutdown — sauberer Pfad ist /quit als Admin im Chat, dann Stop (Community-Quelle: pzwiki-Doku, Hinweis im Storage-Guide).
• make update ohne Timer-Aktivierung: Funktioniert ad hoc, aber wer die Automatik will, braucht zomboid-update.timer aktiv (siehe systemd-Referenz).

Siehe auch

Weiter: Makefile-Referenz · Monitoring-und-Alerts · Backup-und-Restore · Admin-Befehle · systemd-Referenz