# 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.

Wersja 1.8 · na NAS-ie, przez SSH, jako admin · QTS z pulą LVM thin · freeware. https://www.qnaputilities.com/pool-repair-pl.html

- **5**: kroków w menu, w kolejności naprawy
- **3**: typy uszkodzeń metadanych, każdy z własną ścieżką naprawy
- **YES**: słowo, które wpisujesz, zanim naprawa nadpisze metadane puli

## 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`.

1. **Status and diagnosis.** Stan i diagnoza. Skrypt sprawdza RAID i sprzęt. Gdy pula jest offline, uruchamia `thin_check` na metadanych puli. Gdy pula jest jeszcze aktywna, proponuje wstępne sprawdzenie tylko do odczytu. (`tylko odczyt`)
2. **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 offline`)
3. **Backup.** Kopia zapasowa. Skrypt zapisuje konfigurację LVM i obraz metadanych w katalogu roboczym. Uznaje obraz dopiero wtedy, gdy sprawdzi jego zgodność z urządzeniem. (`zweryfikowany obraz`)
4. **Repair the metadata.** Naprawa metadanych. Skrypt proponuje ścieżkę naprawy pasującą do diagnozy. Zanim naprawa nadpisze oryginalne metadane, wpisujesz `YES`. (`wpisane YES`)
5. **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_collect` z 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`.

## 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.

- **Tryb automatyczny**: Nagranie zaczyna się od poleceń pobierania, od `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`.
- **Mapa przestrzeni**: 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.
- **Superblok**: 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 mapowania**: 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.
- **Restart w trakcie naprawy**: 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ę.

## 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 -fy` po wpisaniu `FSCK` albo 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 wpisywania `YES`. Awaryjna opcja `--allow-no-backup` znosi 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 wpisaniu `REBUILD`, 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.

## Pobierz skrypt

Skrypt udostępniamy po podaniu kodu PIN. Wpisz PIN, aby zobaczyć link do pobrania.


## Uruchom skrypt

Skrypt działa na samym NAS-ie. Wymaga konta admin, bo QTS nie ma `sudo`.

1. Zaloguj się do NAS-a przez SSH jako admin.
2. Przejdź do folderu ze skryptem. Folder nie może leżeć na naprawianej puli.
3. Uruchom skrypt pierwszym poleceniem poniżej.
4. Wybierz katalog roboczy poza pulą. Bez niego skrypt wykona diagnozę, ale krok 3 nie zapisze obrazu metadanych.

```sh
# 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ład `vg1/tp1`. Przebieg automatyczny nie używa tej opcji.
- `--help`: Wypisuje opcje.
- `--version`: Wypisuje wersję.

## Powiązane strony

- [Pula lub wolumin QNAP nieaktywne: co sprawdzić najpierw](https://www.qnaputilities.com/qnap-pool-not-active-pl.html)
- [StorageDiag: diagnostyka, która działa na NAS-ie](https://www.qnaputilities.com/storagediag-pl.html)
- [DriveTime: test powierzchni dysku w NAS-ie QNAP](https://www.qnaputilities.com/drivetime-pl.html)
- [MemHound: test pamięci RAM w działającym NAS-ie](https://www.qnaputilities.com/memhound-pl.html)
- [Poradniki](https://www.qnaputilities.com/howto-pl.html)
