LVM Pool Repair: ein Skript zur Reparatur der Metadaten eines QNAP Thin-Pools
Ein Shell-Skript mit Menü repariert über SSH die Metadaten eines QNAP Thin-Pools unter QTS.
Die Reparatur läuft in fünf Schritten ab. Das Skript stellt die Diagnose, bereitet den Pool vor, erstellt eine Sicherung, repariert die Metadaten und nimmt den Pool und die Volumes wieder in Betrieb.
Mit Enter starten Sie im Menü den nächsten empfohlenen Schritt. Wenn die SSH-Sitzung abbricht oder das NAS neu startet, setzen Sie dieselbe Reparatursitzung fort.
- 5Schritte im Menü, in der Reihenfolge der Reparatur
- 3Arten von Metadatenschäden, jeweils mit einem eigenen Reparaturverfahren
- YESdas Wort, das Sie eingeben, bevor die Reparatur die Metadaten des Pools überschreibt
Aufzeichnungen des Skripts
Jede Aufzeichnung zeigt eine echte SSH-Sitzung mit Version 1.7 des Skripts auf einem QNAP NAS in einem Terminal mit 80 mal 25 Zeichen. Version 1.8 ergänzt diese Anzeigen um einen Abschnitt für die Prüfung des RAID und der Laufwerke ohne Schreibzugriff, vor dem Menü und zu Beginn von Schritt 1. Wir haben die Metadaten des Pools absichtlich an bekannten Stellen beschädigt und die ursprünglichen Blöcke aufbewahrt. Wir haben die beschädigten Metadaten nach Schritt 2 geschrieben, als der Pool offline war. Die Aufzeichnungen lassen diese Pause aus. Nach Schritt 2 fährt das Skript in derselben Sitzung mit der Diagnose fort. Die Aufzeichnungen kürzen lange Wartezeiten. Ihre tatsächliche Dauer hängt von der Größe des Pools und seinen Snapshots ab.
░░░ ░░░ ░░░ ░░░ ░░░ ░░░ ░░░ ░░░ ░░░ ░░░ ░░░ ░░░ ░░░ ░░░ ░░░ ░░░ ░░░ ▀▀▀▀▀ ▀▀▀▀▀▀▀ ▀▀▀▀▀▀▀ ▀▀▀ ▀▀▀ ▀▀▀▀▀▀▀ ▀▀▀▀▀▀ ▀▀▀▀▀▀▀ ▀▀▀▀▀▀▀ ▀▀▀▀▀▀ Mounted: /share/CACHEDEV2_DATA /share/CACHEDEV1_DATA /mnt/pool1 (and 12 mounts of apps and containers on these volumes) [auto] Data reachable - finish the repair session? -> y [ OK ] Report: /share/external/DEV3302_1/pool-recovery-NAS-DEMO-vg1-tp1-20261121-010858/report.txt [ OK ] Log package: /share/external/DEV3302_1/pool-recovery-NAS-DEMO-vg1-tp1-20261121-010858/logs-20261121-012354.tgz Look through it before sending: it holds the host name, the device layout, directory listings of the test mount and, in debug mode, the shell trace. The metadata image is not in it. [ OK ] Session finished. Keep the copy of the original metadata: /share/external/DEV3302_1/pool-recovery-NAS-DEMO-vg1-tp1-20261121-010858/tmeta.raw Pool vg1/tp1 is back online with all its volumes mounted. Let's rock. [ OK ] Nothing left to do. Press Enter to return to the menu.
cd /mnt/HDA_ROOT. Schritt 2 nimmt den Pool offline. Während das Skript im Menü wartet, setzen wir einen Eintrag in der Speicherbelegungskarte der Metadaten auf einen falschen Wert. Dann startet a den automatischen Lauf. Das Skript führt die Diagnose durch, speichert ein Abbild der Metadaten und repariert den Pool. Danach nimmt es den Pool, die Volumes und die Apps wieder in Betrieb. Es hält nur einmal an. Bevor es in den Pool schreibt, wartet es auf die Eingabe von YES.Ein Eintrag in der Speicherbelegungskarte der Metadaten ist fehlerhaft. Das Skript stoppt die Dienste, speichert ein geprüftes Abbild der Metadaten, erstellt eine reparierte Kopie und prüft sie. Nach Eingabe von YES schreibt es die Kopie in den Pool. Schritt 5 nimmt den Pool, die Volumes und die Apps wieder in Betrieb.Der primäre Superblock ist beschädigt. Seine Sicherungskopien sind gültig. Das Skript liest die Metadaten über die neueste Kopie. Nach Eingabe von YES stellt das Skript den Superblock aus dieser Kopie wieder her, prüft die Metadaten und nimmt den Pool wieder in Betrieb.Zwei Blätter im Zuordnungsbaum eines Testvolumes sind beschädigt. Der Pool verwendet die reparierte Kopie für das testweise Einhängen ohne Schreibzugriff. Dabei werden die Dateien gelesen. Nach Bestätigung der Daten und Eingabe von YES schreibt das Skript die Kopie in den Pool. Es prüft das Dateisystem des Testvolumes, bevor QTS das Volume einhängt. Die abschließende Prüfsummenprüfung der 600 Testdateien ergibt, dass 534 intakt und 66 verändert sind.Der Schaden ist derselbe. Das NAS startet während des testweisen Einhängens ohne Schreibzugriff neu. Nach dem Neustart bleibt der Pool offline, weil das Skript vor dem Test das Flag skip-activation gesetzt hat. Nach einer neuen Anmeldung per SSH starten wir das Skript erneut. Es findet die nicht abgeschlossene Sitzung und schließt die Reparatur ab.Skript herunterladen
Der Download ist mit einer PIN geschützt. Geben Sie die PIN ein, um den Downloadlink anzuzeigen.
cd /
sudo -i
# quit console if displayed
cd /mnt/HDA_ROOT
wget --no-check-certificate https://pub.qnaputilities.com/pool-repair/qnap-pool-repair-1.8.sh
chmod +x qnap-pool-repair-1.8.sh
sh qnap-pool-repair-1.8.shSkript starten
Das Skript läuft direkt auf dem NAS. Es braucht das Konto admin, weil QTS kein sudo hat.
- Melden Sie sich über SSH als admin am NAS an.
- Wechseln Sie in den Ordner mit dem Skript. Der Ordner muss außerhalb des Pools liegen, den Sie reparieren.
- Starten Sie das Skript mit dem ersten Befehl unten.
- Wählen Sie ein Arbeitsverzeichnis außerhalb des Pools. Ohne Arbeitsverzeichnis ist die Diagnose möglich, aber Schritt 3 kann das Metadatenabbild nicht speichern.
# Skript mit Menü starten sh qnap-pool-repair.sh # nach einem Verbindungsabbruch zur Sitzung zurückkehren screen -r qnap-pool-repair
Eine Speicherreparatur lässt sich unter Umständen nicht rückgängig machen. Bevor das Skript etwas schreibt, stellen Sie sicher, dass Ihre wichtigen Daten gesichert sind und die Diagnose zu Ihrem NAS passt.
Optionen
--auto- Startet den automatischen Lauf, sobald das Skript den Pool erkannt hat. Die Schritte 1 bis 5 laufen nacheinander. Der automatische Lauf braucht ein Arbeitsverzeichnis.
--debug- Zeigt die Aufrufverfolgung und jeden Befehl in einem Rahmen an. Schreibt die vollständige Shell-Ablaufverfolgung in
trace.log. Dafür ist ein Arbeitsverzeichnis nötig. --no-screen- Führt das Skript ohne
screen-Sitzung aus. --selftest- Prüft ohne Schreibzugriff die Befehle, die das Skript verwendet, und beendet sich.
--raid-check- Prüft ohne Schreibzugriff die RAID-Verbünde, ihre Mitglieder und die QNAP-Signaturen auf den Laufwerken und beendet sich. Dazu braucht es keinen Pool.
--allow-no-backup- Nur für den Notfall. Sie können das schnelle oder das vollständige Verfahren ohne Metadatenabbild bestätigen. Geben Sie
NO-BACKUPund danach den Namen des Pools so ein, wie ihn das Skript anzeigt, etwavg1/tp1. Der automatische Lauf verwendet diese Option nicht. --help- Gibt die Optionen aus.
--version- Gibt die Version aus.
Die fünf Schritte
Vor dem Menü zeigt das Skript den roten Hinweis WARNING an und prüft, ob die 79 Befehle, die es verwendet, auf dem NAS verfügbar sind. In einer neuen Sitzung prüft es dann ohne Schreibzugriff die RAID-Verbünde und ihre Laufwerke. Das Menü zeigt die Schritte in der Reihenfolge der Reparatur und den Status jedes Schritts. Enter startet den empfohlenen Schritt. Der automatische Lauf führt alle verbleibenden Schritte nacheinander aus und übernimmt bei Fragen mit sicherer Voreinstellung die Standardantwort. Bei belegten Volumes und bei der Prüfung der Daten nach dem testweisen Einhängen fragt das Skript weiterhin nach. Auch YES müssen Sie eingeben.
Status and diagnosis
Das Skript prüft das RAID und die Hardware. Ist der Pool offline, prüft es dessen Metadaten mit
nur Lesezugriffthin_check. Ist der Pool noch aktiv, bietet es eine vorläufige Prüfung ohne Schreibzugriff an.Prepare
Das Skript hängt die Volumes des Pools aus und deaktiviert die Volume-Gruppe. Im schonenden Modus hängt es nur aus, was zu diesem Pool gehört. Es stoppt Dienste nur, wenn noch etwas in Benutzung ist.
Pool offlineBackup
Das Skript sichert die LVM-Konfiguration und schreibt ein Abbild der Metadaten in das Arbeitsverzeichnis. Es akzeptiert das Abbild erst nach dem Abgleich mit dem Gerät.
geprüftes AbbildRepair the metadata
Das Skript bietet das zur Diagnose passende Reparaturverfahren an. Bevor die Reparatur die ursprünglichen Metadaten überschreibt, geben Sie
Eingabe von YESYESein.Bring the pool and the volumes up
Das Skript aktiviert den Pool. QTS hängt die Volumes ein, und das Skript gleicht jedes Volume mit der zuvor gespeicherten Liste ab. Es bietet an, die zuvor gestoppten Dienste zu starten. Sobald alle Volumes wieder verfügbar sind, zeigt das Skript LOOKS GOOD an, schreibt einen Bericht und packt die Protokolle.
Bericht und Protokolle
Ergebnisse der Diagnose
Schritt 1 zeigt das Ergebnis von thin_check als Meldung des Skripts an. Schritt 4 bietet dann das passende Reparaturverfahren an.
- space map counts only
Nur die Zähler der Speicherbelegungskarte sind fehlerhaft. Die Zuordnungsbäume sind intakt.
Schnelles Verfahren. Das Skript erstellt eine reparierte Kopie auf einem reservierten Volume und prüft sie. Nach Ihrer Eingabe von
YESschreibt es die Kopie in den Pool. - damaged superblock
Der primäre Superblock ist beschädigt. Das Skript findet in den Metadaten gültige Sicherungskopien des Superblocks.
Das Skript liest die Metadaten über die neueste gültige Kopie. Nach Ihrer Eingabe von
YESstellt es den Superblock aus dieser Kopie wieder her und wiederholt die Diagnose. - mapping tree errors
Teile des Baums, der die Blöcke eines Volumes zuordnet, sind beschädigt. Die Reparatur entfernt diese Zuordnungsbereiche. Beim anschließenden Lesen erscheinen ihre Blöcke leer.
Vollständiges Verfahren. Der Pool verwendet die reparierte Kopie für das testweise Einhängen ohne Schreibzugriff. Sie prüfen und bestätigen die Daten. Nach Ihrer Eingabe von
YESschreibt das Skript die Kopie in den Pool. - data NOT OK
Beim testweisen Einhängen geben Sie an, dass die Daten fehlerhaft sind. Das Skript stellt die ursprüngliche LVM-Konfiguration wieder her. Die ursprünglichen Metadaten bleiben unverändert.
Senden Sie den Fall mit dem Protokollpaket aus Menü 7 und dem Paket
tp_collectaus dem Menü Tools an den QNAP Support.
Das Skript behandelt ein unbekanntes Ergebnis wie einen Schaden an den Zuordnungen. Bei Schäden an der Speicherbelegungskarte bietet es zusätzlich zwei Verfahren an, die direkt in die ursprünglichen Metadaten schreiben. Die Verfahren heißen legacy (thin_dump und thin_restore) und rebuild (QNAPs thin_rebuild). Beide brauchen das geprüfte Abbild und Ihre Eingabe von YES. Hat der Pool kein reserviertes Volume für die Kopie, steht bei Schäden an den Zuordnungen nur legacy zur Verfügung. Sie wählen es mit LEGACY.
Sicherheitsregeln
- Die Reparatur schreibt erst in die ursprünglichen Metadaten, wenn Schritt 3 ein geprüftes Abbild bereitstellt. Ein Rohabbild muss so groß sein wie das Gerät und bei
thin_checkdasselbe Ergebnis liefern. Ein komprimiertes Abbild vergleicht das Skript Byte für Byte mit dem Gerät. - Bevor die Reparatur die ursprünglichen Metadaten überschreibt, geben Sie
YESein. Jede andere Antwort bricht den Schreibvorgang ab. - Vor einem Schreibvorgang sucht das Skript im Kernel-Protokoll nach Speicherfehlern und E/A-Fehlern der Laufwerke des Pools. Findet es einen Fehler, fragt es, ob es fortfahren soll. Die Standardantwort lautet Nein.
- Auf einem inaktiven RAID startet das Skript keine Reparatur. Ist das RAID degradiert oder läuft ein Neuaufbau, eine Neusynchronisierung, eine Änderung der RAID-Struktur oder eine Prüfung, fragt das Skript zuerst nach. Die Standardantwort lautet Nein.
- Nach der Reparatur von Schäden an den Zuordnungen bietet Schritt 5 eine Dateisystemprüfung ohne Schreibzugriff (
e2fsck -fn) für die betroffenen Volumes an, bevor er sie einhängt. Findet die Prüfung Fehler, können Siee2fsck -fpodere2fsck -fywählen. Für den zweiten Befehl müssen Sie zuerstFSCKeingeben. Sie können auch später Check File System in QTS verwenden. - Das Arbeitsverzeichnis mit den Protokollen und dem Metadatenabbild liegt außerhalb des Pools, auf einem externen Laufwerk oder einem Volume eines anderen Pools. Das Skript akzeptiert keinen Ordner auf dem Pool, den Sie reparieren.
- Das Skript läuft in
screenund arbeitet weiter, wenn die SSH-Sitzung abbricht. Starten Sie das Skript erneut, um zur Sitzung zurückzukehren. - Der Sitzungsstatus liegt außerhalb des Pools auf der Systempartition des NAS (md9). Nach einem Neustart findet das Skript die offene Sitzung und fragt, ob es sie fortsetzen soll.
- Beim testweisen Einhängen verweist LVM den Pool auf die reparierte Kopie. Solange ist das Flag skip-activation für die Volume-Gruppe gesetzt. Dadurch bleibt der Pool nach einem Neustart des NAS offline.
- Es gibt zwei Ausnahmen. Sind die Metadaten konsistent und ist nur das Flag
needs_checkgesetzt, löscht das Skript das Flag ohne Abbild, ohne Prüfung von Hardware und RAID und ohne Eingabe vonYES. Die Notfalloption--allow-no-backuphebt nur die Pflicht zum Abbild auf. Sie ist bei den Optionen beschrieben. - Wenn ein Volume nicht wieder verfügbar ist, kann QTS seine Speicherkonfiguration mit
init_lvm.shneu aufbauen. Das Skript führt den Befehl erst aus, nachdem SieREBUILDeingegeben haben. Es sichert vorher die Dateien und listet anschließend alle Einstellungen auf, die sich beim Neuaufbau geändert haben.
Einschränkungen
- Die Reparatur kann Daten in beschädigten Zuordnungsbereichen nicht wiederherstellen. In der Aufzeichnung zur Zuordnungsreparatur waren zwei Blätter im Zuordnungsbaum eines Testvolumes mit 600 Dateien zu je 4 MiB beschädigt. Nach der Reparatur stimmten bei 534 Dateien die Prüfsummen mit den gespeicherten Werten überein. 66 Dateien enthielten Daten in den beiden verworfenen Bereichen und waren verändert.
- Das Skript repariert nur die Metadaten des Pools. Es repariert keine Laufwerke, kein RAID und kein fehlendes physisches LVM-Volume.
- Das Skript funktioniert unter QTS mit einem LVM Thin-Pool. Unter QuTS hero, das ZFS verwendet, beendet es sich beim Start.
- Bei einem SSD-Cache mit Lese- und Schreibzugriff oder mit reinem Schreibzugriff sowie bei Daten in zwei oder mehr Qtier-Ebenen hält das Skript vor Schritt 2 und vor der Reparatur an und verweist auf den QNAP-Support. Bei einem SSD-Cache mit reinem Lesezugriff fragt es zuerst, ob der Cache entfernt oder für diesen Pool deaktiviert wurde.
- Für die Reparatur geht der Pool offline. Im schonenden Modus stoppt das Skript den Snapshot-Manager, wenn Snapshots des Pools eingehängt sind. Bleibt ein Volume in Benutzung, wählen Sie, wie weit das Skript geht. Es kann den Snapshot-Manager oder alle QTS-Dienste stoppen, die Prozesse beenden, die das Volume belegen, oder die Volume-Gruppe markieren, damit der Pool nach einem Neustart des NAS offline bleibt. Im vollständigen Modus stoppt das Skript sofort alle QTS-Dienste. Schritt 5 bietet an, sie wieder zu starten.
- Das Skript prüft das Dateisystem eines verschlüsselten Volumes nicht. Hat das NAS ein SSD-Cache-Volume, überspringt es die Dateisystemprüfung.
- Eine fehlerfreie Hardwareprüfung belegt nicht, dass der RAM fehlerfrei ist. MemHound prüft den Arbeitsspeicher.
- Die Meldungen des Skripts sind auf Englisch. Antworten Sie auf jede Abfrage mit einem Buchstaben, einer Ziffer oder einem Wort und drücken Sie Enter. Die Pfeiltasten funktionieren im Menü nicht. Ctrl+C unterbricht das Skript nicht.