SMB-Sync: Robocopy-Skripte mit Protokollierung

Disclaimer

Das nachfolgende Skript ist eine konzeptionelle Arbeit.

Das Skript soll als Anschaungsbeispiel dienen, wie eine Datei-Synchronisation mit Robocopy durchgeführt werden kann. Die Quelle wird authentisiert und eingebunden, das Ziel wird nicht authentisiert, es wird angenommen, dass dazu Zugriffsberechtigungen bereits bestehen.

ACHTUNG, WICHTIGER HINWEIS!

Dieses Skript ist Teil der Projekt-Dokumentation. Es ist NICHT zur Verwendung im Betrieb gedacht. Jede Nutzung erfolgt in eigener Verantwortung! Der Verfasser übernimmt dementsprechend keinerlei Verantwortung für Fehlerfreiheit, Vollständigkeit oder Eignung für einen bestimmten Zweck.

Bitte testen Sie ein Skript, das Sie auf der Grundlage der hier dargestellten Konzepte erstellen, gründlich in einer sicheren Umgebung, bevor Sie es in einer Produktionsumgebung verwenden.

Inhaltsverzeichnis

1. Einleitung
2. Was macht dieses Skript?
3. Ablauf & Funktionsweise
4. Konfiguration
5. Beispiel für einen Kopiervorgang
6. Logdateien & Auswertung
7. Tipps & Hinweise
8. Verzeichnisstruktur

---

Einleitung

Dieses kleine Set an PowerShell-Skripten dient dazu, mit Robocopy Daten von einem Ort A zu einem Ort B zu kopieren und dabei die wichtigsten Informationen zum Kopiervorgang in Logdateien zu schreiben. Ziel ist es, nachvollziehen zu können, wann was kopiert wurde, wie Robocopy dabei abgeschnitten hat und ob Fehler aufgetreten sind.

Das Skript ist ein Anschauungsbeispiel für Admins und Power-User, um eigene Skripte zu erstellen.

---

Was macht dieses Skript?

• Startet Robocopy mit den gewünschten Parametern
• Schreibt während des Kopiervorgangs eine Lock-/Statusdatei, damit keine zwei Kopien gleichzeitig laufen
• Protokolliert Start und Ende jedes Kopiervorgangs in CSV und JSONL-Logdateien
• Optional: Schickt Benachrichtigungen per E-Mail (wenn konfiguriert)
• Gibt alle wichtigen Schritte und den Robocopy-Output direkt auf der Konsole aus

---

Ablauf & Funktionsweise

Der Ablauf ist wie folgt:

1. Start

2. Konfigurationsdatei bestimmen:

   • Wenn beim Start ein Parameter -ConfigPath übergeben wird und die Datei existiert, wird diese verwendet.
   • Sonst wird geprüft, ob es eine Datei config/<MASCHINENNAME>.yml gibt (z.B. config/SMB-DESTINATION.yml). Wenn ja, wird diese genutzt.
   • Sonst wird auf config/sync_config.yml zurückgegriffen.
   • Falls keine dieser Dateien existiert oder lesbar ist, bricht das Skript mit einer Fehlermeldung ab.

3. Lock-/Statusdatei anlegen:

   • Im Hauptverzeichnis wird eine Datei wie <MASCHINENNAME>_ROBOCOPY_IN_PROGRESS_<Datum>_<Uhrzeit>.lock erstellt (z.B. SMB-DESTINATION_ROBOCOPY_IN_PROGRESS_0417_181447.lock).
   • Existiert bereits eine solche Datei für den eigenen Rechnernamen, wird der Kopiervorgang abgebrochen und ein entsprechender Logeintrag (Status: LOCKED) in CSV und JSONL geschrieben.
   • LOCK-Dateien anderer Rechner werden ignoriert und blockieren den lokalen Kopiervorgang nicht.

4. (Optional) SMB-Share mounten:

   • Falls in der Konfiguration hinterlegt, wird versucht, das Quellverzeichnis mit angegebenen Zugangsdaten zu mounten.

5. Robocopy-Befehl zusammenbauen und anzeigen:

   • Der komplette Befehl wird auf der Konsole ausgegeben, z.B.:

     About to run: robocopy "\\smb-source\source" "c:\dest" /MIR /Z /FFT /R:3 /W:5 /MT:64 /NFL /NDL
     

6. Robocopy ausführen:

   • Die Ausgabe von Robocopy wird live auf der Konsole angezeigt.

7. Protokollierung:

   • Nach Abschluss (egal ob erfolgreich oder mit Fehler) wird ein Eintrag in die Logdateien geschrieben (siehe unten).

8. Lock-/Statusdatei löschen:

   • Am Ende wird die Lockdatei entfernt.

---

Konfiguration

Die Konfiguration erfolgt über YAML-Dateien im config/-Verzeichnis. Die wichtigsten Felder:

job:
  source: "\\\\smb-source\\source"
  destination: "c:\\dest"
  robocopy_flags: "/MIR /Z /FFT /R:3 /W:5 /MT:64 /NFL /NDL"
  max_runtime_minutes: 60

auth:
  use_kerberos: false
  remote_domain_user: ""
  password_env_var: ""

logging:
  log_dir: "logs"
  machine_log_format: "csv,json"
  enable_rotation: true
  retention_days: 30

alerts:
  enabled: false
  smtp_server: ""
  from: ""
  to: []
  on_start: false
  on_abort: false
  on_complete: false

Hinweis:
Die Datei kann z.B. sync_config.yml heißen oder <MASCHINENNAME>.yml (z.B. SMB-DESTINATION.yml).

---

Beispiel für einen Kopiervorgang

Konsolenausgabe:

Remote Fileshare as configured: \\smb-source\source
Connecting to Remote Host \\smb-source\source using user account SMB-Source\transfer to mount data source.
LOCK file created: C:\Users\timw\Documents\SMB-Sync\SMB-DESTINATION_ROBOCOPY_IN_PROGRESS_0417_181447.lock
About to run: robocopy "\\smb-source\source" "c:\dest" /MIR /Z /FFT /R:3 /W:5 /MT:64 /NFL /NDL
Robocopy output:
-------------------------------------------------------------------------------
   ROBOCOPY     ::     Robust File Copy for Windows
-------------------------------------------------------------------------------
... (Robocopy-Ausgabe) ...
Robocopy completed successfully. Exit code: 1
Logs written to: logs
LOCK file removed: C:\Users\timw\Documents\SMB-Sync\SMB-DESTINATION_ROBOCOPY_IN_PROGRESS_0417_181447.lock

Beispiel für einen abgelehnten Kopiervorgang wegen LOCK-Datei:

Lock file exists for this host: C:\Users\timw\Documents\SMB-Sync\SMB-DESTINATION_ROBOCOPY_IN_PROGRESS_0417_181447.lock. Exiting.

Beispiel für einen JSONL-Eintrag bei LOCK:

{"timestamp_start":"2025-04-17 18:37:49","timestamp_end":"2025-04-17 18:37:49","duration_seconds":0,"hostname":"SMB-DESTINATION","status":"LOCKED","exit_code":100,"event_type":"END","command":"","summary":"Kopiervorgang abgebrochen: Bereits laufender Kopiervorgang auf diesem Host (SMB-DESTINATION)."}

---

Logdateien & Auswertung

• CSV-Log:
  Jede Maschine schreibt ihr eigenes Log, z.B. logs/SMB-DESTINATION_log.csv
• JSONL-Log:
  Für maschinelle Auswertung, z.B. logs/SMB-DESTINATION_log.jsonl

Beispiel für einen JSONL-Eintrag:

{"timestamp_start":"2025-04-17 18:37:49","timestamp_end":"2025-04-17 18:37:54","duration_seconds":5,"hostname":"SMB-DESTINATION","status":"COMPLETED","exit_code":1,"event_type":"END","command":"robocopy \"\\\\smb-source\\source\" \"c:\\dest\" /MIR /Z /FFT /R:3 /W:5 /MT:64 /NFL /NDL","summary":"Robocopy exit code: 1","robocopy_stats":{"files_failed":0,"files_extras":0,"files_total":25,"files_copied":25,"files_skipped":0}}

---

Tipps & Hinweise

• Die Skripte sind für PowerShell unter Windows gedacht.
• Die Lockdatei verhindert Doppelstarts – bei Problemen ggf. manuell löschen.
• Sie signaliert aber auch anderen, dass aktuell noch ein Kopiervorgang läuft, und die Daten evtl. für eine weitere Übernahme noch nicht vollständig sind.
• Für die E-Mail-Benachrichtigung müssen SMTP-Parameter korrekt gesetzt sein.

---

Verzeichnisstruktur

SMB-Sync/
├── config/
│   ├── <MASCHINENNAME>.yml
│   └── sync_config.yml
├── logs/
│   ├── <MASCHINENNAME>_log.csv
│   ├── <MASCHINENNAME>_log.jsonl
├── scripts/
│   ├── Utils.ps1
│   ├── Log-Handler.ps1
│   ├── Alert-Handler.ps1
├── run_sync.ps1
└── README.md

---