LVM Pool Repair: skrypt, który naprawia metadane puli thin w NAS-ie QNAP
Jeden skrypt powłoki z menu naprawia przez SSH metadane puli thin w NAS-ie QNAP z systemem QTS.
Skrypt prowadzi naprawę przez pięć kroków: diagnozę, przygotowanie puli, kopię zapasową, naprawę oraz uruchomienie puli i woluminów.
W menu Enter uruchamia krok, który skrypt zaleca jako następny. Po zerwaniu sesji SSH albo restarcie NAS-a kontynuujesz tę samą sesję naprawy.
- 5kroków w menu, w kolejności naprawy
- 3typy uszkodzeń metadanych, każdy z własną ścieżką naprawy
- YESsłowo, które wpisujesz, zanim naprawa nadpisze metadane puli
Nagrania skryptu
Każde nagranie to prawdziwa sesja SSH ze skryptem w wersji 1.7 na NAS-ie QNAP, w terminalu 80 na 25 znaków. Wersja 1.8 dodaje na tych ekranach jedną sekcję: sprawdzenie RAID i dysków tylko do odczytu, przed menu i na początku kroku 1. Celowo uszkodziliśmy metadane puli w znanych miejscach i zachowaliśmy oryginalne bloki. Uszkodzenie powstało po kroku 2, gdy pula była offline. Nagrania pomijają tę przerwę: po kroku 2 skrypt od razu przechodzi do diagnozy w tej samej sesji. Długie oczekiwania są w nagraniach skrócone. Ich prawdziwa długość zależy od rozmiaru puli i jej migawek.
░░░ ░░░ ░░░ ░░░ ░░░ ░░░ ░░░ ░░░ ░░░ ░░░ ░░░ ░░░ ░░░ ░░░ ░░░ ░░░ ░░░ ▀▀▀▀▀ ▀▀▀▀▀▀▀ ▀▀▀▀▀▀▀ ▀▀▀ ▀▀▀ ▀▀▀▀▀▀▀ ▀▀▀▀▀▀ ▀▀▀▀▀▀▀ ▀▀▀▀▀▀▀ ▀▀▀▀▀▀ 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. Krok 2 wyłącza pulę, a gdy skrypt czeka w menu, jeden wpis mapy zajętości metadanych zostaje ustawiony źle. Potem a uruchamia tryb automatyczny: diagnozę, obraz metadanych, naprawę oraz start puli, woluminów i aplikacji. Skrypt zatrzymuje się raz: przed zapisem do puli czeka na wpisanie YES.Jeden wpis mapy zajętości metadanych jest błędny. Skrypt zatrzymuje usługi, zapisuje sprawdzony obraz metadanych, buduje naprawioną kopię i ją sprawdza. Po wpisaniu YES zapisuje kopię do puli. Krok 5 uruchamia pulę, woluminy i aplikacje.Główny superblok jest uszkodzony, a jego kopie zapasowe są poprawne. Skrypt czyta metadane przez najnowszą kopię. Po wpisaniu YES odtwarza z niej superblok, sprawdza metadane i uruchamia pulę.Uszkodzone są dwa liście drzewa mapowań woluminu testowego. Pula działa na naprawionej kopii podczas montowania testowego tylko do odczytu i tam czytamy pliki. Po potwierdzeniu danych i wpisaniu YES skrypt zapisuje kopię do puli i sprawdza system plików, zanim QTS zamontuje wolumin. Na końcu test sum kontrolnych 600 plików: 534 całe, 66 zmienionych.To samo uszkodzenie. NAS restartuje się w trakcie montowania testowego. Po restarcie pula zostaje offline, bo skrypt przed testem ustawił flagę skip-activation. Po nowym logowaniu przez SSH skrypt zostaje uruchomiony ponownie. Znajduje niedokończoną sesję i kończy naprawę.Pobierz skrypt
Skrypt udostępniamy po podaniu kodu PIN. Wpisz PIN, aby zobaczyć link do pobrania.
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.shUruchom skrypt
Skrypt działa na samym NAS-ie. Wymaga konta admin, bo QTS nie ma sudo.
- Zaloguj się do NAS-a przez SSH jako admin.
- Przejdź do folderu ze skryptem. Folder nie może leżeć na naprawianej puli.
- Uruchom skrypt pierwszym poleceniem poniżej.
- Wybierz katalog roboczy poza pulą. Bez niego skrypt wykona diagnozę, ale krok 3 nie zapisze obrazu metadanych.
# uruchom skrypt i jego menu sh qnap-pool-repair.sh # wróć do sesji po zerwanym połączeniu screen -r qnap-pool-repair
Naprawa pamięci masowej bywa nieodwracalna. Zanim skrypt cokolwiek zapisze, upewnij się, że masz kopię ważnych danych i że diagnoza pasuje do Twojego NAS-a.
Opcje
--auto- Uruchamia przebieg automatyczny, gdy skrypt wykryje pulę: kroki od 1 do 5 po kolei. Przebieg automatyczny wymaga katalogu roboczego.
--debug- Pokazuje ślad wywołań i każde polecenie w ramce. Zapisuje pełny ślad powłoki w
trace.log, do czego potrzebny jest katalog roboczy. --no-screen- Uruchamia skrypt bez sesji
screen. --selftest- Sprawdza polecenia, których skrypt używa, tylko do odczytu, i kończy pracę.
--raid-check- Sprawdza macierze RAID, ich członków i sygnatury QNAP na dyskach, tylko do odczytu, i kończy pracę. Nie potrzebuje puli.
--allow-no-backup- Tylko w sytuacji awaryjnej. Możesz wtedy potwierdzić szybką albo pełną ścieżkę bez obrazu metadanych: wpisujesz
NO-BACKUP, a potem nazwę puli w postaci, którą pokazuje skrypt, na przykładvg1/tp1. Przebieg automatyczny nie używa tej opcji. --help- Wypisuje opcje.
--version- Wypisuje wersję.
Pięć kroków
Przed menu skrypt pokazuje czerwone WARNING i sprawdza, czy NAS ma 79 poleceń, których skrypt używa. W nowej sesji sprawdza potem macierze RAID i ich dyski, tylko do odczytu. Menu pokazuje kroki w kolejności naprawy i stan każdego z nich. Enter uruchamia zalecany krok. Przebieg automatyczny wykonuje po kolei wszystkie pozostałe kroki, a na pytania z bezpieczną odpowiedzią domyślną odpowiada sam. Nadal pyta Cię o zajęte woluminy, o dane na montowaniu testowym i o wpisanie YES.
Status and diagnosis
Stan i diagnoza. Skrypt sprawdza RAID i sprzęt. Gdy pula jest offline, uruchamia
tylko odczytthin_checkna metadanych puli. Gdy pula jest jeszcze aktywna, proponuje wstępne sprawdzenie tylko do odczytu.Prepare
Przygotowanie. Skrypt odmontowuje woluminy puli i dezaktywuje grupę woluminów. W trybie łagodnym odmontowuje tylko to, co należy do tej puli, a usługi zatrzymują się tylko wtedy, gdy coś nadal blokuje pulę.
pula offlineBackup
Kopia zapasowa. Skrypt zapisuje konfigurację LVM i obraz metadanych w katalogu roboczym. Uznaje obraz dopiero wtedy, gdy sprawdzi jego zgodność z urządzeniem.
zweryfikowany obrazRepair the metadata
Naprawa metadanych. Skrypt proponuje ścieżkę naprawy pasującą do diagnozy. Zanim naprawa nadpisze oryginalne metadane, wpisujesz
wpisane YESYES.Bring the pool and the volumes up
Uruchomienie puli i woluminów. Skrypt aktywuje pulę. QTS montuje woluminy, a skrypt sprawdza każdy z nich z listą zapisaną wcześniej. Proponuje uruchomienie usług, które zatrzymał. Gdy wszystkie woluminy wrócą, pokazuje LOOKS GOOD, zapisuje raport i pakuje logi.
raport i logi
Co znajduje diagnoza
Krok 1 podaje wynik thin_check jednym z określeń skryptu. Krok 4 proponuje potem ścieżkę naprawy dla tego wyniku.
- space map counts only
Błędy są tylko w licznikach mapy przestrzeni. Drzewa mapowań są całe.
Szybka ścieżka: skrypt buduje naprawioną kopię na zarezerwowanym woluminie i ją sprawdza. Gdy wpiszesz
YES, zapisuje kopię do puli. - damaged superblock
Główny superblok jest uszkodzony, a skrypt znajduje w metadanych jego poprawne kopie zapasowe.
Skrypt czyta metadane przez najnowszą poprawną kopię. Gdy wpiszesz
YES, odtwarza z niej superblok i powtarza diagnozę. - mapping tree errors
Uszkodzone są części drzewa, które mapuje bloki woluminu. Naprawa usuwa te zakresy, a ich bloki są potem puste przy odczycie.
Pełna ścieżka: pula działa na naprawionej kopii podczas montowania testowego tylko do odczytu. Oglądasz dane i je potwierdzasz. Gdy wpiszesz
YES, skrypt zapisuje kopię do puli. - data NOT OK
Podczas montowania testowego odpowiadasz, że dane nie są w porządku. Skrypt wraca do oryginalnej konfiguracji LVM, a oryginalne metadane zostają bez zmian.
Przekaż sprawę do wsparcia QNAP z pakietem logów z menu 7 i pakietem
tp_collectz menu Tools.
Wynik, którego nie rozpoznaje, skrypt traktuje jak uszkodzenie mapowań. Przy uszkodzeniu mapy przestrzeni proponuje też dwie ścieżki, które zapisują bezpośrednio do oryginalnych metadanych: legacy (thin_dump i thin_restore) oraz rebuild (thin_rebuild firmy QNAP). Obie wymagają zweryfikowanego obrazu i wpisanego YES. W puli bez zarezerwowanego woluminu na kopię legacy jest jedyną ścieżką dla uszkodzenia mapowań, a wybierasz ją, wpisując LEGACY.
Zasady bezpieczeństwa
- Ścieżka naprawy zapisuje do oryginalnych metadanych dopiero wtedy, gdy krok 3 ma ich zweryfikowany obraz. Surowy obraz musi mieć rozmiar urządzenia i ten sam wynik
thin_check. Skompresowany obraz skrypt porównuje z urządzeniem bajt po bajcie. - Zanim naprawa nadpisze oryginalne metadane, wpisujesz
YES. Każda inna odpowiedź anuluje zapis. - Przed zapisem skrypt szuka w logu jądra zgłoszeń błędów pamięci i błędów wejścia-wyjścia dysków, na których leży pula. Gdy je znajdzie, pyta, czy kontynuować, a domyślna odpowiedź to „nie”.
- Skrypt nie zaczyna naprawy na nieaktywnej macierzy RAID. Gdy macierz jest zdegradowana albo trwa na niej odbudowa, synchronizacja, zmiana układu lub sprawdzanie, skrypt najpierw pyta, a domyślna odpowiedź to „nie”.
- Po naprawie uszkodzonych mapowań krok 5 proponuje sprawdzenie systemu plików tylko do odczytu (
e2fsck -fn) na woluminach objętych uszkodzeniem, zanim je zamontuje. Gdy sprawdzenie znajdzie błędy, wybierasz naprawę:e2fsck -fp,e2fsck -fypo wpisaniuFSCKalbo później funkcję Check File System w QTS. - Katalog roboczy z logami i obrazem metadanych leży poza pulą: na dysku zewnętrznym albo na woluminie innej puli. Skrypt nie przyjmuje folderu na naprawianej puli.
- Skrypt działa w
screen, więc zerwanie sesji SSH go nie zatrzymuje. Uruchom skrypt ponownie, aby wrócić do sesji. - Stan sesji leży na partycji systemowej NAS-a (md9), poza pulą. Po restarcie skrypt znajduje niedokończoną sesję i pyta, czy ją kontynuować.
- Podczas montowania testowego LVM kieruje pulę na naprawioną kopię. Grupa woluminów ma wtedy flagę skip-activation, więc po restarcie NAS-a pula zostaje offline.
- Od tych zasad są dwa wyjątki. Gdy metadane są spójne, a ustawiona jest tylko flaga
needs_check, skrypt kasuje flagę bez obrazu, bez sprawdzenia sprzętu i RAID oraz bez wpisywaniaYES. Awaryjna opcja--allow-no-backupznosi tylko zasadę obrazu, a opisują ją opcje poniżej. - Gdy któryś wolumin nie wróci, QTS może odbudować konfigurację pamięci masowej poleceniem
init_lvm.sh. Skrypt uruchamia je dopiero po wpisaniuREBUILD, najpierw zapisuje kopie plików, a potem wypisuje każde ustawienie, które odbudowa zmieniła.
Ograniczenia
- Naprawa nie odzyska danych z uszkodzonych zakresów mapowań. W nagraniu z mapowaniami uszkodziliśmy dwa liście drzewa mapowań woluminu testowego z 600 plikami po 4 MiB. Po naprawie 534 pliki miały zgodne sumy kontrolne. 66 plików miało dane w dwóch usuniętych zakresach i się zmieniło.
- Skrypt naprawia tylko metadane puli. Nie naprawia dysku, macierzy RAID ani brakującego woluminu fizycznego LVM.
- Skrypt działa w QTS z pulą LVM thin. W QuTS hero, który używa ZFS, kończy pracę na starcie.
- Przy pamięci podręcznej SSD do zapisu (read-write albo write-only) albo przy danych w dwóch lub więcej warstwach Qtier skrypt zatrzymuje się przed krokiem 2 i przed naprawą i odsyła do pomocy technicznej QNAP. Przy pamięci podręcznej SSD tylko do odczytu najpierw pyta, czy jest usunięta albo wyłączona dla tej puli.
- Na czas naprawy pula przechodzi w stan offline. W trybie łagodnym skrypt zatrzymuje menedżera migawek, gdy migawki puli są zamontowane. Gdy coś blokuje wolumin, wybierasz, jak daleko skrypt się posunie: zatrzyma menedżera migawek, zatrzyma wszystkie usługi QTS, zakończy procesy, które blokują wolumin, albo oznaczy grupę woluminów flagą, dzięki której pula zostanie offline po restarcie NAS-a. W trybie pełnym skrypt od razu zatrzymuje wszystkie usługi QTS, a krok 5 proponuje ich ponowne uruchomienie.
- Skrypt nie sprawdza systemu plików na zaszyfrowanym woluminie. Gdy NAS ma wolumin pamięci podręcznej SSD, skrypt pomija sprawdzenie systemu plików.
- Czysty wynik sprawdzenia sprzętu nie dowodzi, że pamięć RAM jest sprawna. Testem pamięci jest MemHound.
- Komunikaty skryptu są po angielsku. Na każde pytanie odpowiadasz literą, cyfrą albo słowem i naciskasz Enter. Strzałki w menu nie działają. Ctrl+C nie przerywa skryptu.