🧰Optionen, Baukasten und Rückgabecodes

rsync hat über 150 Optionen – im Alltag braucht man etwa 25. Klick dir einen Befehl zusammen und sieh für jeden Teil, was er bewirkt. Warnungen erscheinen, sobald eine Kombination gefährlich oder sinnlos ist.

🧱Befehls-Baukasten

Grundlagen
Erhalten
Vergleich
Löschen
Filter
--exclude
--exclude
--exclude
Backup
Übertragung
Ausgabe
Befehl
$ rsync -az --delete --exclude=node_modules --exclude=.git/ --exclude='.env*' ./ deploy@web.example.org:/var/www/site/
⚠️ --delete ohne -n: erst einen Probelauf mit -n -i (bzw. -nv) machen und die „deleting“-Zeilen prüfen.

Was jeder Teil bedeutet

  • -az
    -a (--archive) – Kurz für -rlptgoD: rekursiv, Symlinks als Symlinks, Rechte, Zeiten, Gruppe, Besitzer, Geräte-/Spezialdateien. Nicht enthalten: Hardlinks (-H), ACLs (-A), xattrs (-X).
    -z (--compress) – Daten während der Übertragung komprimieren (rsync ≥ 3.2 handelt z. B. zstd aus). Lohnt nur über langsame Netze, nicht lokal.
  • --delete
    --delete – Dateien beim Ziel löschen, die es in der Quelle nicht (mehr) gibt – macht aus der Kopie einen Spiegel. Ausgeschlossene Dateien bleiben geschützt.
  • --exclude=node_modules
    --exclude – Entspricht der Filterregel - MUSTER. Die erste passende Regel gewinnt – Reihenfolge beachten.
  • --exclude=.git/
    --exclude – Entspricht der Filterregel - MUSTER. Die erste passende Regel gewinnt – Reihenfolge beachten.
  • --exclude='.env*'
    --exclude – Entspricht der Filterregel - MUSTER. Die erste passende Regel gewinnt – Reihenfolge beachten.
  • ./
    Quelle mit Slash: nur der Inhalt wird kopiert.
  • deploy@web.example.org:/var/www/site/
    Entfernt über SSH: Host „web.example.org“, Benutzer „deploy“, Pfad „/var/www/site/“.

➗Der berühmte Slash am Quellpfad

Der häufigste rsync-Fehler überhaupt: ein fehlender oder überzähliger Slash am Ende der Quelle.
$ rsync -a projekt /srv/www/
projekt/
index.html
css/style.css
img/logo.svg
➜
/srv/www/projekt/index.html
/srv/www/projekt/css/style.css
/srv/www/projekt/img/logo.svg
Ohne Slash: „kopiere das Verzeichnis projekt“ → im Ziel entsteht /srv/www/projekt.
Filterregeln sehen css/style.css als /projekt/css/style.css – eine verankerte Regel muss also mit /projekt/ beginnen.

Am Ziel ist der Slash bei Verzeichnissen egal. Nur beim Kopieren einer einzelnen Datei zählt er: rsync a.txt b.txt legt die Datei als b.txt an, rsync a.txt b/ legt b/a.txt an.

🅰️Was -a wirklich bedeutet

-r
rekursiv
-l
Symlinks als Links
-p
Rechte
-t
Zeiten
-g
Gruppe
-o
Besitzer
-D
Geräte + Spezialdateien
⚠️ Nicht in -a enthalten
-H (Hardlinks), -A (ACLs), -X (xattrs),-U (Zugriffszeiten), -N (Erstellzeiten). Für ein vollständiges System-Backup also rsync -aHAX --numeric-ids.

📖Die wichtigsten Optionen

-a--archiveGrundlagen
Archivmodus

Kurz für -rlptgoD: rekursiv, Symlinks als Symlinks, Rechte, Zeiten, Gruppe, Besitzer, Geräte-/Spezialdateien. Nicht enthalten: Hardlinks (-H), ACLs (-A), xattrs (-X).

-r--recursiveGrundlagen
Rekursiv

Verzeichnisse mit allen Unterverzeichnissen kopieren.

-l--linksErhalten
Symlinks

Symbolische Links als Links kopieren (nicht das Ziel des Links).

-p--permsErhalten
Rechte

Zugriffsrechte (rwx) des Senders beim Empfänger setzen.

-t--timesErhalten
Änderungszeit

mtime übernehmen. Ohne -t kann der Quick-Check beim nächsten Lauf nicht greifen – dann wird jede Datei erneut geprüft.

-g--groupErhalten
Gruppe

Gruppenzugehörigkeit übernehmen (soweit erlaubt).

-o--ownerErhalten
Besitzer

Besitzer übernehmen – wirkt nur, wenn der Empfänger als root läuft.

-D--devices --specialsErhalten
Geräte & Spezialdateien

Kurz für --devices --specials: Gerätedateien, FIFOs und Sockets übertragen.

-H--hard-linksErhalten
Hardlinks

Hardlinks innerhalb der Quelle erkennen und beim Ziel wieder als Hardlinks anlegen. Kostet Speicher bei vielen Dateien.

-A--aclsErhalten
ACLs

POSIX-ACLs übernehmen (impliziert -p).

-X--xattrsErhalten
Erweiterte Attribute

Extended Attributes (xattrs) übernehmen, z. B. SELinux-Kontexte oder Datei-Metadaten.

--numeric-idsErhalten
Numerische IDs

UID/GID als Zahlen übertragen statt über Benutzernamen abzubilden – wichtig für Server-Backups und Wiederherstellung.

-v--verboseAusgabe
Ausführlich

Übertragene Dateien und eine Zusammenfassung anzeigen.

-h--human-readableAusgabe
Lesbare Zahlen

Größen mit Einheiten (K, M, G) ausgeben.

-i--itemize-changesAusgabe
Änderungsliste

Pro Datei einen Code wie >f.st...... ausgeben: was sich ändert (Größe s, Zeit t, Rechte p …).

-P--partial --progressAusgabe
Fortschritt + Teilübertragung

Kurz für --partial --progress: Fortschrittsanzeige je Datei und abgebrochene Dateien behalten, damit ein neuer Lauf weitermachen kann.

--progressAusgabe
Fortschritt

Fortschritt je Datei anzeigen.

--info=progress2Ausgabe
Gesamtfortschritt

Fortschritt über den ganzen Transfer statt je Datei (gut zusammen ohne -v).

--statsAusgabe
Statistik

Am Ende Statistik ausgeben: u. a. „Literal data“ (gesendete Bytes) und „Matched data“ (vom Ziel wiederverwendete Bytes).

-n--dry-runGrundlagen
Probelauf

Nichts verändern, nur anzeigen, was passieren würde. Zusammen mit -v oder -i vor jedem --delete Pflicht.

-c--checksumVergleich
Prüfsummen-Vergleich

Statt Quick-Check (Größe + mtime) für jede gleich große Datei eine Prüfsumme auf beiden Seiten berechnen. Sehr gründlich, aber liest alle Daten – langsam.

-u--updateVergleich
Nur neuere

Dateien überspringen, die beim Ziel neuer sind als in der Quelle.

--size-onlyVergleich
Nur Größe

Quick-Check nur über die Größe, Zeitstempel ignorieren (z. B. nach einem Umzug ohne erhaltene Zeiten).

--modify-window=SEKVergleich
Zeit-Toleranz

Zeitstempel gelten als gleich, wenn sie höchstens so viele Sekunden abweichen. 1 für FAT-Dateisysteme (2-Sekunden-Auflösung).

-W--whole-fileÜbertragung
Ganze Dateien

Delta-Algorithmus abschalten und geänderte Dateien komplett senden. Standard bei lokalen Kopien; schneller, wenn das Netz schneller ist als die Platte.

--deleteLöschen
Löschen beim Ziel

Dateien beim Ziel löschen, die es in der Quelle nicht (mehr) gibt – macht aus der Kopie einen Spiegel. Ausgeschlossene Dateien bleiben geschützt.

--delete-excludedLöschen
Auch Ausgeschlossenes löschen

Impliziert --delete und löscht beim Ziel zusätzlich alles, was durch Filter ausgeschlossen ist (Regeln wirken dann nur noch beim Sender).

--max-delete=NLöschen
Löschbremse

Höchstens N Dateien/Verzeichnisse löschen; danach Abbruch der Löschungen und Rückgabecode 25.

--exclude=MUSTERFilter
Ausschließen

Entspricht der Filterregel - MUSTER. Die erste passende Regel gewinnt – Reihenfolge beachten.

--include=MUSTERFilter
Einschließen

Entspricht + MUSTER; muss vor dem Exclude stehen, das es aufheben soll.

--filter=REGELFilter
Filterregel

Vollständige Regel, z. B. - *.tmp, + */, P geschützt.txt oder . regeln.txt (Merge-Datei). Kurzform -f.

--exclude-from=DATEIFilter
Ausschlussliste

Muster zeilenweise aus einer Datei lesen.

-C--cvs-excludeFilter
CVS-Ausschlüsse

Typische Build-/VCS-Dateien auslassen (*.o, .git/, core …) – Regeln sind „perishable“.

-b--backupBackup
Backup vor Überschreiben

Dateien, die überschrieben oder gelöscht würden, vorher umbenennen (Endung ~).

--backup-dir=DIRBackup
Backup-Verzeichnis

Impliziert -b: ersetzte/gelöschte Dateien in dieses Verzeichnis verschieben (relativ zum Ziel!).

--link-dest=DIRBackup
Hardlink-Snapshots

Unveränderte Dateien nicht kopieren, sondern als Hardlink auf DIR anlegen. Jeder Snapshot wirkt vollständig, belegt aber nur Platz für Änderungen. Relative Pfade gelten ab dem Ziel.

-z--compressÜbertragung
Komprimieren

Daten während der Übertragung komprimieren (rsync ≥ 3.2 handelt z. B. zstd aus). Lohnt nur über langsame Netze, nicht lokal.

--partialÜbertragung
Teildateien behalten

Bei Abbruch die halb übertragene Datei behalten, damit der nächste Lauf sie als Basis nutzt.

--bwlimit=RATEÜbertragung
Bandbreite begrenzen

Maximale Rate; ohne Einheit in KiB/s (5000 = 5000 KiB/s), mit Suffix z. B. 5m = 5 MiB/s.

-e--rsh=BEFEHLÜbertragung
Remote-Shell

Transport wählen, z. B. SSH auf anderem Port oder mit Schlüsseldatei: -e "ssh -i ~/.ssh/backup_ed25519".

-x--one-file-systemÜbertragung
Ein Dateisystem

Keine Grenzen von Dateisystemen überschreiten (z. B. /proc, eingehängte Laufwerke bei /-Backups).

--inplaceÜbertragung
Direkt schreiben

Zieldatei direkt überschreiben statt Temp-Datei + Umbenennen. Spart Platz bei riesigen Dateien, aber bei Abbruch ist die Datei inkonsistent.

🔣--itemize-changes lesen

Mit -i schreibt rsync vor jede Datei einen 11-stelligen Code YXcstpoguax. Beispiel anklicken oder eigene Zeile einfügen:
<f.st......bericht.txt
  • Y = < wird zur Gegenseite gesendet
  • X = f Datei
  • s Größe anders
  • t Änderungszeit anders (T = wird auf Übertragungszeit gesetzt)

🚦Rückgabecodes

In Skripten immer $? auswerten. Besonders 23 und 24 sind im Backup-Alltag häufig und nicht immer ein Drama.
0Erfolg
1Syntax- oder Bedienfehler
2Protokoll-Inkompatibilität
3Fehler bei der Auswahl von Ein-/Ausgabedateien oder -verzeichnissen
4Aktion nicht unterstützt (z. B. Option nur beim Client bekannt, nicht beim Server)
5Fehler beim Start des Client-Server-Protokolls
10Fehler bei Socket-Ein-/Ausgabe
11Fehler bei Datei-Ein-/Ausgabe
12Fehler im rsync-Protokoll-Datenstrom (oft: Gegenseite abgebrochen, rsync fehlt dort)
13Fehler bei der Programmdiagnose
14Fehler im IPC-Code
15Geschwisterprozess abgestürzt (z. B. Core-Dump)
16Geschwisterprozess durch ein Signal beendet
19SIGUSR1 empfangen
20SIGINT, SIGTERM oder SIGHUP empfangen (z. B. Strg+C)
21Fehler von waitpid()
22Speicher für Puffer konnte nicht reserviert werden
23Teilweise übertragen wegen Fehlern (z. B. fehlende Rechte bei einzelnen Dateien)
24Teilweise übertragen, weil Quelldateien verschwunden sind (typisch bei laufenden Systemen)
25--max-delete-Grenze hat Löschungen gestoppt
30Zeitüberschreitung beim Senden/Empfangen
35Zeitüberschreitung beim Warten auf die Daemon-Verbindung

Quelle: man rsync, Abschnitt „EXIT VALUES“ (rsync 3.4/3.5).