rsync richtig nutzen — Deployments, Mirror, Excludes und Dry-Runs

1. rsync verstehen: Delta-Transfer und Checksummen

rsync überträgt nicht einfach Dateien — es berechnet Deltas. Das rsync-Protokoll teilt Dateien in Blöcke auf, berechnet Checksummen für jeden Block und überträgt nur die Blöcke, die sich geändert haben. Bei großen Dateien, die nur partiell geändert wurden, ist das der entscheidende Performancevorteil gegenüber scp oder cp. Wer rsync richtig nutzen will, muss zunächst verstehen, wann rsync diesen Delta-Algorithmus anwendet und wann es auf den schnelleren Metadaten-Vergleich zurückfällt.

Standardmäßig vergleicht rsync Dateien anhand von Größe und Änderungszeit. Wenn beides übereinstimmt, gilt die Datei als identisch — ohne Inhaltsvergleich. Das ist für die meisten Deployments ausreichend und deutlich schneller als ein vollständiger Checksummen-Abgleich. Für kritische Szenarien — Backup-Verifikation, Migration nach einem Dateiserver-Crash — ist der reine Metadaten-Vergleich jedoch nicht sicher genug. Das --checksum-Flag erzwingt dann den vollständigen Inhaltsvergleich. Wer rsync richtig nutzen möchte, wählt die passende Vergleichsstrategie bewusst für jeden Anwendungsfall.

Das Protokoll hat auch eine wichtige Besonderheit bei Pfadangaben: Ein abschließender Schrägstrich am Quellpfad ändert die Semantik erheblich. rsync src/ dst/ kopiert den Inhalt von src nach dst — ohne ein zusätzliches src-Verzeichnis zu erstellen. rsync src dst/ hingegen erstellt dst/src/. Dieser Unterschied ist bei rsync richtig nutzen für Deployments einer der häufigsten Fehler — ein versehentlich fehlender Schrägstrich ändert die gesamte Verzeichnisstruktur auf dem Ziel.

2. Die wichtigsten rsync-Flags für Deployments

Die Kombination rsync -avz --progress ist der meistverwendete rsync-Aufruf und für viele Fälle ausreichend. Das Flag -a (Archive-Modus) aktiviert rekursives Kopieren, erhält Symlinks, Berechtigungen, Zeitstempel, Besitzer und Gruppen — es ist die Kurzform für -rlptgoD. Das Flag -v gibt jede übertragene Datei aus. Das Flag -z komprimiert den Transfer — sinnvoll über langsame Netzwerke, aber über lokale Netzwerke oder schnelle Leitungen oft kontraproduktiv, weil die CPU-Last die Netzwerkgeschwindigkeit übersteigt.

Für Deployments auf Webserver ist --no-perms --no-owner --no-group oft wichtig: Der Webserver auf dem Ziel läuft unter einem anderen Benutzer als der Deploy-Prozess, und rsync soll keine Berechtigungen übertragen, die der Zielserver-Benutzer dann nicht lesen kann. Das Flag -u (Update-Modus) überspringt Dateien auf dem Ziel, die neuer sind als die Quelle — nützlich für Situationen, wo der Zielserver Dateien lokal modifiziert hat (z.B. uploaded user content). Beim rsync richtig nutzen im Deployment-Kontext kommt fast immer noch --delete und eine --exclude-from-Datei hinzu.

#!/usr/bin/env bash
# deploy-rsync.sh — Production deployment via rsync with full error handling
set -euo pipefail
IFS=$'\n\t'

readonly REMOTE_HOST="${REMOTE_HOST:?Set REMOTE_HOST}"
readonly REMOTE_USER="${REMOTE_USER:-deploy}"
readonly REMOTE_PATH="${REMOTE_PATH:?Set REMOTE_PATH (e.g. /var/www/myapp)}"
readonly LOCAL_SOURCE="${LOCAL_SOURCE:-./dist/}"
readonly EXCLUDE_FILE="${EXCLUDE_FILE:-./rsync-excludes.txt}"
readonly SSH_KEY="${SSH_KEY:-$HOME/.ssh/id_ed25519}"

# Validate source directory exists and has trailing slash
[[ -d "$LOCAL_SOURCE" ]] || { echo "[ERROR] Source directory not found: $LOCAL_SOURCE" >&2; exit 1; }

rsync \
  --archive \
  --verbose \
  --compress \
  --delete \
  --exclude-from="$EXCLUDE_FILE" \
  --checksum \
  --human-readable \
  --progress \
  --stats \
  --rsh="ssh -i $SSH_KEY -o StrictHostKeyChecking=yes" \
  "$LOCAL_SOURCE" \
  "${REMOTE_USER}@${REMOTE_HOST}:${REMOTE_PATH}/"

echo "[OK] Deployment complete: $LOCAL_SOURCE -> ${REMOTE_USER}@${REMOTE_HOST}:${REMOTE_PATH}"

3. --delete: Exakte Spiegel ohne verwaiste Dateien

Das Flag --delete ist das entscheidende Werkzeug, um rsync richtig nutzen als echter Spiegel zu betreiben. Ohne --delete werden Dateien auf dem Ziel, die in der Quelle nicht mehr existieren, niemals entfernt. Das Ziel wächst monoton — gelöschte Konfigurationsdateien, alte Asset-Versionen, entfernte PHP-Dateien bleiben auf dem Produktionsserver liegen. Mit --delete ist das Ziel nach dem Transfer eine exakte Kopie der Quelle.

Die Variante --delete-after entfernt verwaiste Dateien erst nach dem Transfer aller neuen Dateien — wichtig für Webserver, bei denen ein kurzzeitiger Zustand mit fehlenden Dateien 404-Fehler verursachen würde. Die noch sicherere Variante ist --delete-delay, die gelöschte Dateien in einer Liste sammelt und erst am Ende des Transfers auf einmal entfernt. Für rsync richtig nutzen in Hochverfügbarkeits-Setups ist die Reihenfolge von Übertragung und Löschung kein Detail, sondern geschäftskritisch. Das verbreitete Muster ist: --delete-after kombiniert mit einem serverseitigen Reload-Hook, der erst nach dem vollständigen Transfer ausgelöst wird.

Vorsicht bei der Kombination von --delete mit --filter und --exclude: Ausgeschlossene Dateien im Ziel werden durch --delete ebenfalls gelöscht, wenn sie nicht auch explizit mit --filter "protect ..." geschützt werden. Das führt in der Praxis regelmäßig zu unerwünschten Löschungen von Upload-Verzeichnissen, lokalen Konfigurationsdateien oder Cache-Dateien, die auf dem Ziel existieren sollen, aber nicht in der Quelle liegen. Beim rsync richtig nutzen mit --delete ist deshalb immer ein vollständiges Dry-Run vor dem ersten produktiven Einsatz Pflicht.

4. --exclude-from: Saubere Ausschlüsse für Deployments

Die Option --exclude-from=datei.txt liest Ausschlussmuster aus einer Datei — eine Muster pro Zeile. Das ist die skalierbare Alternative zu mehreren --exclude-Flags auf der Kommandozeile, die bei wachsenden Projekten schnell unübersichtlich werden. Eine zentrale rsync-excludes.txt kann in der Versionskontrolle verwaltet, von allen Team-Mitgliedern konsistent genutzt und in CI/CD-Pipelines eingebunden werden. Wer rsync richtig nutzen im Teamumfeld will, zentralisiert Ausschlussmuster immer in einer Datei.

Die Syntax in der Exclude-Datei unterstützt Wildcards (* für beliebige Zeichen außer /, ** für Pfade über Verzeichnisgrenzen), Anker (/ am Anfang für absolute Muster relativ zur Quelle, / am Ende für Verzeichnisse), Kommentare (#) und Negation (! für Include-Ausnahmen innerhalb einer Exclude-Regel). Das Verarbeitungsmodell ist wichtig: rsync prüft jede Datei gegen die Regeln in der Reihenfolge, in der sie in der Datei stehen — die erste passende Regel gewinnt. Ausnahmen müssen also vor den allgemeineren Ausschlussregeln stehen.

# rsync-excludes.txt — Deployment exclude patterns for rsync --exclude-from
# Syntax: one pattern per line, # for comments, / prefix = anchored to root, ! = include exception

# --- Version control ---
/.git/
/.gitignore
/.gitattributes

# --- Development tools ---
/node_modules/
/.npm/
/vendor/           # Composer vendor — deploy pre-built assets, not sources

# --- Build artifacts to INCLUDE (exception before broader rule) ---
!/dist/
!/build/

# --- Local config files (kept on server, not overwritten) ---
/config/local.php
/config/env.php
/.env
/.env.local

# --- Upload directories — protect from --delete ---
/pub/media/
/var/

# --- Logs, cache, temp ---
/var/cache/
/var/log/
*.log
*.tmp
*.swp
.DS_Store
Thumbs.db

5. --dry-run: Deployments sicher vorab simulieren

Das Flag --dry-run (Kurzform: -n) ist bei rsync richtig nutzen das wichtigste Sicherheitsnetz vor dem ersten produktiven Einsatz eines neuen Deployment-Skripts. Ein Dry-Run führt alle rsync-Berechnungen durch — Checksummen, Exclude-Matching, Delete-Ermittlung — und gibt aus, was übertragen und gelöscht würde, ohne dabei eine einzige Datei zu verändern. Die Ausgabe eines Dry-Runs mit --verbose zeigt exakt, welche Dateien neu übertragen, welche überschrieben und welche auf dem Ziel gelöscht würden.

Ein professionelles Deployment-Skript implementiert rsync richtig nutzen mit einem eingebauten Dry-Run-Modus: DRY_RUN="${DRY_RUN:-1}" als Standard — d.h. der Dry-Run ist standardmäßig aktiv, und der produktive Transfer muss explizit mit DRY_RUN=0 aktiviert werden. Das verhindert, dass ein neues oder geändertes Skript versehentlich ohne vorherige Simulation in der Produktion landet. In CI/CD-Pipelines wird der Dry-Run als separater Pipeline-Step ausgeführt, dessen Ausgabe als Artefakt gespeichert und vor dem eigentlichen Deploy-Step manuell genehmigt oder automatisch auf kritische Löschmuster geprüft wird.

6. --checksum: Integrität statt Metadaten-Vergleich

Das Flag --checksum ändert die Vergleichsstrategie fundamental: rsync berechnet MD4-Checksummen für jede Datei und überträgt nur Dateien mit abweichender Checksumme — unabhängig von Größe und Zeitstempel. Das ist deutlich langsamer als der Standard-Metadaten-Vergleich, aber die einzig zuverlässige Methode zum Erkennen stiller Dateikorruptionen. Nach dem rsync richtig nutzen für reguläre Deployments ist --checksum der richtige Modus für Backup-Verifikationen, Migrationen nach Hardware-Ausfällen und die erste Synchronisation nach längerer Unterbrechung.

In der Praxis wird --checksum selten für jedes Deployment verwendet, weil der erhöhte CPU- und I/O-Aufwand auf beiden Seiten bei großen Dateimengen die Transfer-Zeit vervielfachen kann. Das sinnvolle Muster beim rsync richtig nutzen: reguläre Deployments ohne --checksum, aber periodische Verifikations-Runs (z.B. wöchentlich) mit --checksum --dry-run, die abweichende Dateien protokollieren, ohne zu übertragen. Dieser Verifikations-Lauf funktioniert auch zwischen zwei lokalen Verzeichnissen und ist damit ideal für RAID-Konsistenzprüfungen.

7. --link-dest: Atomare Deployments mit Snapshot-History

Das Flag --link-dest=verzeichnis ist das Werkzeug für atomare Deployments mit Versionshistorie — ein Muster, das mit rsync richtig nutzen möglich ist, ohne zusätzliche Tools wie Capistrano oder Deployer zu benötigen. rsync erstellt ein neues Deployment-Verzeichnis und erstellt Hard-Links für Dateien, die sich gegenüber dem referenzierten Vorversionsverzeichnis nicht geändert haben. Nur neue oder geänderte Dateien werden übertragen. Das Ergebnis: Ein vollständiges Deployment-Verzeichnis, das nur die tatsächlich geänderten Dateien an Speicherplatz benötigt.

Das atomare Umschalten erfolgt dann mit einem einzigen Symlink-Tausch: ln -sfn /deployments/release-20260509 /var/www/current. Dieser Symlink-Tausch ist atomar auf Unix-Dateisystemen — der Webserver sieht zu keinem Zeitpunkt einen inkonsistenten Zustand. Rollbacks sind trivial: Den Symlink auf ein früheres Release-Verzeichnis zeigen lassen. Bei rsync richtig nutzen mit --link-dest ist die Aufräumlogik für alte Release-Verzeichnisse Teil des Deployment-Skripts — typischerweise werden die letzten 5–10 Releases behalten, ältere werden gelöscht.

#!/usr/bin/env bash
# atomic-deploy.sh — Atomic deployment with rsync --link-dest and symlink swap
set -euo pipefail
IFS=$'\n\t'

readonly REMOTE_HOST="${REMOTE_HOST:?}"
readonly REMOTE_USER="${REMOTE_USER:-deploy}"
readonly DEPLOY_BASE="/var/www/releases"
readonly CURRENT_LINK="/var/www/current"
readonly KEEP_RELEASES=5

RELEASE_DIR="${DEPLOY_BASE}/$(date +%Y%m%d-%H%M%S)"
PREVIOUS_LINK="${CURRENT_LINK}"

log() { printf "[%s] %s\n" "$(date +%T)" "$*"; }

log "Starting atomic deployment -> $RELEASE_DIR"

# Step 1: Transfer to new release directory, hardlink unchanged files from current
rsync \
  --archive \
  --compress \
  --delete \
  --exclude-from=./rsync-excludes.txt \
  --link-dest="${PREVIOUS_LINK}" \
  --rsh="ssh -o StrictHostKeyChecking=yes" \
  ./dist/ \
  "${REMOTE_USER}@${REMOTE_HOST}:${RELEASE_DIR}/"

log "Transfer complete. Swapping symlink..."

# Step 2: Atomic symlink swap (single syscall, no downtime window)
ssh "${REMOTE_USER}@${REMOTE_HOST}" \
  "ln -sfn '${RELEASE_DIR}' '${CURRENT_LINK}' && echo 'Symlink: ${CURRENT_LINK} -> ${RELEASE_DIR}'"

# Step 3: Prune old releases — keep only KEEP_RELEASES most recent
ssh "${REMOTE_USER}@${REMOTE_HOST}" "
  ls -1dt '${DEPLOY_BASE}'/* | tail -n +$((KEEP_RELEASES + 1)) | xargs -r rm -rf
  echo 'Pruned old releases, kept last $KEEP_RELEASES'
"

log "Deployment complete."

8. --bwlimit: Bandbreitenlimit für Produktionsserver

Das Flag --bwlimit=KBPS begrenzt die Übertragungsrate von rsync auf den angegebenen Wert in Kilobytes pro Sekunde. Beim rsync richtig nutzen auf Produktionsservern ist dieses Flag unverzichtbar für Deployments während der Produktionszeit: Ein unkontrollierter rsync-Transfer kann die gesamte verfügbare Netzwerkbandbreite beanspruchen und gleichzeitig laufende HTTP-Requests, Datenbankoperationen oder andere produktive Übertragungen beeinträchtigen. Mit --bwlimit=10240 (10 MB/s) bleibt ausreichend Bandbreite für den laufenden Betrieb.

Das Bandbreitenlimit ist keine exakte Obergrenze, sondern ein Durchschnittswert über kurze Zeitintervalle — rsync reguliert die Übertragung in Bursts. Für nächtliche Backups und Synchronisierungen außerhalb der Stoßzeiten kann --bwlimit weggelassen werden, um maximale Transfer-Geschwindigkeit zu nutzen. Das professionelle Muster beim rsync richtig nutzen in Produktionsumgebungen: Das Bandbreitenlimit als Umgebungsvariable konfigurierbar machen und im Deployment-Skript abhängig vom Zeitfenster (Nacht vs. Tag, Wochentag vs. Wochenende) dynamisch setzen. So kann dasselbe Skript in unterschiedlichen Kontexten optimal konfiguriert werden.

Ergänzend zu --bwlimit lohnt die Option --timeout=60, die rsync beendet, wenn 60 Sekunden keine Daten übertragen wurden. Ohne Timeout hängt rsync bei Netzwerkproblemen unbegrenzt — was in cron-Jobs zu Zombie-Prozessen führt, die sich gegenseitig blockieren. Das Deployment-Skript sollte zusätzlich eine externe Timeout-Kontrolle mit dem timeout-Builtin haben: timeout 3600 rsync ... begrenzt den gesamten Transfer auf eine Stunde, unabhängig von der rsync-internen Timeout-Logik.

9. rsync-Flags im Vergleich

Die Wahl der richtigen rsync-Flags hängt stark vom Anwendungsfall ab. Diese Übersicht zeigt die wichtigsten Optionen beim rsync richtig nutzen für verschiedene Szenarien.

Für ein vollständiges Produktions-Deployment kombiniert man diese Flags: --archive --compress --delete-after --exclude-from --link-dest --bwlimit --timeout --stats. Das Ergebnis ist ein Deployment, das den Zielserver exakt spiegelt, Bandbreite kontrolliert, eine atomare Umschaltung ermöglicht und detaillierte Statistiken für das Deployment-Log liefert. Das rsync richtig nutzen in der Praxis bedeutet, diese Flags situationsgerecht zu kombinieren — nicht alle für jeden Anwendungsfall zu verwenden.

10. Zusammenfassung

rsync richtig nutzen bedeutet, die richtigen Flags für den jeweiligen Anwendungsfall zu kombinieren. --delete macht rsync zum echten Spiegel, der verwaiste Dateien auf dem Ziel entfernt — immer mit Dry-Run und einer durchdachten --exclude-from-Datei, um ungewollte Löschungen zu verhindern. --checksum erzwingt vollständige Integrätsprüfung für kritische Transfers. --link-dest ermöglicht atomare Deployments mit Zero-Downtime und Versionshistorie für Rollbacks. --bwlimit schützt den Produktionsbetrieb vor Bandbreitenengpässen während laufender Deployments.

Die wichtigste Praxisregel beim rsync richtig nutzen: Jedes neue Deployment-Skript mit --dry-run gegen die Produktionsumgebung testen, bevor es scharf geschaltet wird. Die Kombination aus atomarem --link-dest-Deployment, einer gepflegten rsync-excludes.txt in der Versionskontrolle und einem Dry-Run-Gate in der CI/CD-Pipeline ist der vollständige Ansatz für professionelle rsync-Deployments.

11. FAQ: rsync richtig nutzen