Unofficial

LVM Pool Repair: een script voor het herstellen van de metagegevens van een QNAP thin pool

Dit shellscript met menu herstelt via SSH de metagegevens van een QNAP thin pool op QTS.

Het herstel verloopt in vijf stappen. Het script stelt een diagnose, bereidt de pool voor, maakt een back-up, herstelt de metagegevens en neemt de pool en de volumes weer in gebruik.

Druk in het menu op Enter om de volgende aanbevolen stap uit te voeren. Als de SSH-sessie wegvalt of de NAS opnieuw opstart, ga je verder met dezelfde herstelsessie.

Versie 1.8 · op de NAS, via SSH, als admin · QTS met een LVM thin pool · freeware

  • 5stappen in het menu, in de volgorde van het herstel
  • 3typen schade aan metagegevens, elk met een eigen herstelprocedure
  • YEShet woord dat je typt voordat het herstel de metagegevens van de pool overschrijft

Opnamen van het script

Elke opname toont een echte SSH-sessie met versie 1.7 van het script op een QNAP NAS, in een terminal van 80 bij 25 tekens. Versie 1.8 voegt aan deze schermen een onderdeel toe voor de controle van de RAID en de schijven zonder schrijftoegang, vóór het menu en aan het begin van stap 1. We hebben de metagegevens van de pool opzettelijk op bekende plaatsen beschadigd en de oorspronkelijke blokken bewaard. We hebben de beschadigde metagegevens na stap 2 weggeschreven, toen de pool offline was. De opnamen slaan die pauze over. Na stap 2 gaat het script in dezelfde sessie verder met de diagnose. Lange wachttijden zijn in de opnamen ingekort. De werkelijke wachttijd hangt af van de grootte van de pool en zijn snapshots.

sh qnap-pool-repair-1.7.sh80×25
  ░░░   ░░░ ░░░ ░░░ ░░░ ░░░ ░░░ ░░░ ░░░      ░░░ ░░░ ░░░ ░░░ ░░░ ░░░ ░░░ ░░░      ▀▀▀▀▀ ▀▀▀▀▀▀▀ ▀▀▀▀▀▀▀ ▀▀▀ ▀▀▀ ▀▀▀▀▀▀▀       ▀▀▀▀▀▀ ▀▀▀▀▀▀▀ ▀▀▀▀▀▀▀ ▀▀▀▀▀▀                                                                                     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.                                              
De opname begint met de downloadopdrachten, vanaf cd /mnt/HDA_ROOT. Stap 2 haalt de pool offline. Terwijl het script in het menu wacht, geven we één vermelding in de kaart voor ruimtetoewijzing van de metagegevens een verkeerde waarde. Daarna start a de automatische uitvoering. Het script voert een diagnose uit, slaat een image van de metagegevens op, herstelt de pool en neemt de pool, de volumes en de apps weer in gebruik. Het script pauzeert één keer. Voordat het naar de pool schrijft, wacht het tot de gebruiker YES typt.Een vermelding in de kaart voor ruimtetoewijzing van de metagegevens klopt niet. Het script stopt de services, slaat een geverifieerde image van de metagegevens op, maakt een herstelde kopie en controleert die. Nadat de gebruiker YES typt, schrijft het script de kopie naar de pool. Stap 5 neemt de pool, de volumes en de apps weer in gebruik.Het primaire superblok is beschadigd en de reservekopieën zijn geldig. Het script leest de metagegevens via de nieuwste kopie. Na invoer van YES herstelt het script het superblok uit die kopie, controleert het de metagegevens en neemt het de pool weer in gebruik.Twee bladeren van de toewijzingsboom van een testvolume zijn beschadigd. De pool gebruikt de herstelde kopie voor een test waarbij het volume zonder schrijftoegang wordt aangekoppeld. Tijdens de test worden de bestanden gelezen. Nadat de gebruiker de gegevens heeft bevestigd en YES heeft getypt, schrijft het script de kopie naar de pool. Het controleert het bestandssysteem van het testvolume voordat QTS dit aankoppelt. Uit de eindcontrole van de controlesommen van de 600 testbestanden blijkt dat 534 bestanden intact zijn en 66 zijn gewijzigd.De schade is dezelfde. De NAS start opnieuw op tijdens de aankoppeltest zonder schrijftoegang. Na de herstart blijft de pool offline, omdat het script vóór de test de vlag skip-activation heeft ingesteld. Na een nieuwe aanmelding via SSH starten we het script opnieuw. Het vindt de onafgeronde sessie en voltooit het herstel.

Het script downloaden

Je hebt een PIN nodig om het script te downloaden. Typ de PIN om de downloadlink te zien.

Het script starten

Het script draait op de NAS zelf. Het heeft het account admin nodig omdat QTS geen sudo heeft.

  1. Meld je via SSH als admin aan bij de NAS.
  2. Ga naar de map met het script. Die map moet buiten de pool staan die je herstelt.
  3. Start het script met de eerste opdracht hieronder.
  4. Kies een werkmap buiten de pool. Zonder werkmap kan het script een diagnose stellen, maar kan stap 3 de image van de metagegevens niet opslaan.
# het script en het menu starten
sh qnap-pool-repair.sh
# na een verbroken verbinding terugkeren naar de sessie
screen -r qnap-pool-repair

Een herstel van de opslag kan onomkeerbaar zijn. Controleer voordat het script iets schrijft of je een back-up van je belangrijke gegevens hebt en of de diagnose bij je NAS past.

Opties

--auto
Start de automatische uitvoering zodra het script de pool detecteert. De stappen 1 tot en met 5 volgen elkaar op. Voor de automatische uitvoering is een werkmap nodig.
--debug
Toont de aanroeptrace en zet elke opdracht in een kader. Schrijft de volledige shelltrace naar trace.log. Daarvoor is een werkmap nodig.
--no-screen
Voert het script uit zonder screen-sessie.
--selftest
Controleert zonder schrijftoegang de opdrachten die het script gebruikt en sluit daarna af.
--raid-check
Controleert zonder schrijftoegang de RAID-arrays, hun leden en de QNAP-handtekeningen op de schijven en sluit daarna af. Er is geen pool nodig.
--allow-no-backup
Alleen voor noodgevallen. Je kunt de snelle of volledige procedure dan bevestigen zonder image van de metagegevens. Typ NO-BACKUP en vervolgens de naam van de pool zoals het script die toont, bijvoorbeeld vg1/tp1. De automatische uitvoering gebruikt deze optie niet.
--help
Toont de opties.
--version
Toont de versie.

De vijf stappen

Voordat het script het menu toont, geeft het de melding WARNING in rood weer en controleert het of de 79 opdrachten die het gebruikt op de NAS beschikbaar zijn. In een nieuwe sessie controleert het script daarna zonder schrijftoegang de RAID-arrays en hun schijven. Het menu toont de stappen in de volgorde van het herstel en geeft de status van elke stap aan. Met Enter start je de aanbevolen stap. De automatische uitvoering doorloopt alle resterende stappen en gebruikt het standaardantwoord als dat veilig is. Het script stelt je nog steeds vragen over volumes die in gebruik zijn en over de gegevens tijdens de aankoppeltest. Het vraagt je ook om YES te typen.

  1. Status and diagnosis

    Het script controleert de RAID en de hardware. Als de pool offline is, voert het thin_check uit op de metagegevens van de pool. Als de pool nog actief is, biedt het een voorlopige controle zonder schrijftoegang aan.

    alleen-lezen
  2. Prepare

    Het script koppelt de volumes van de pool af en deactiveert de volumegroep. In de voorzichtige modus koppelt het alleen af wat bij deze pool hoort. Het stopt alleen services als er nog iets in gebruik is.

    pool offline
  3. Backup

    Het script slaat de LVM-configuratie op en schrijft een image van de metagegevens naar de werkmap. Het accepteert de image pas nadat het die met het apparaat heeft vergeleken.

    geverifieerde image
  4. Repair the metadata

    Het script biedt de herstelprocedure aan die bij de diagnose past. Voordat het herstel de oorspronkelijke metagegevens overschrijft, typ je YES.

    invoer van YES
  5. Bring the pool and the volumes up

    Het script activeert de pool. QTS koppelt de volumes aan en het script vergelijkt elk volume met de eerder opgeslagen lijst. Het biedt aan de gestopte services te starten. Zodra alle volumes weer beschikbaar zijn, toont het LOOKS GOOD, schrijft het een rapport en bundelt het de logbestanden.

    rapport en logbestanden

Uitkomsten van de diagnose

Stap 1 toont het resultaat van thin_check in een melding van het script. Stap 4 biedt vervolgens de herstelprocedure voor die uitkomst aan.

  • space map counts only

    Alleen de tellers van de kaart voor ruimtetoewijzing bevatten fouten. De toewijzingsbomen zijn intact.

    Snelle procedure. Het script maakt een herstelde kopie op een gereserveerd volume en controleert die. Nadat je YES hebt getypt, schrijft het de kopie naar de pool.

  • damaged superblock

    Het primaire superblok is beschadigd. Het script vindt geldige reservekopieën van het superblok in de metagegevens.

    Het script leest de metagegevens via de nieuwste geldige kopie. Nadat je YES hebt getypt, herstelt het het superblok uit die kopie en voert het de diagnose opnieuw uit.

  • mapping tree errors

    Delen van de boom die de blokken van een volume toewijst, zijn beschadigd. Het herstel verwijdert de betreffende bereiken uit de toewijzing. Als je de blokken daarna leest, lijken ze leeg.

    Volledige procedure. De pool gebruikt de herstelde kopie om de volumes voor een test zonder schrijftoegang aan te koppelen. Bekijk de gegevens en bevestig dat ze kloppen. Nadat je YES hebt getypt, schrijft het script de kopie naar de pool.

  • data NOT OK

    Tijdens de test geef je aan dat de gegevens niet kloppen. Het script herstelt de oorspronkelijke LVM-configuratie. De oorspronkelijke metagegevens blijven ongewijzigd.

    Meld het probleem bij QNAP-ondersteuning en stuur het logarchief uit menu 7 en het pakket tp_collect uit het menu Tools mee.

Het script behandelt een onbekend resultaat als schade aan de toewijzing. Bij schade aan de kaart voor ruimtetoewijzing biedt het ook twee procedures aan die rechtstreeks naar de oorspronkelijke metagegevens schrijven. Dit zijn legacy (thin_dump en thin_restore) en rebuild (QNAP’s thin_rebuild). Beide vereisen de geverifieerde image en invoer van YES. Heeft de pool geen gereserveerd volume voor de kopie, dan kun je schade aan de toewijzing alleen met legacy herstellen. Typ LEGACY om die procedure te kiezen.

Veiligheidsregels

  • Een herstelprocedure schrijft pas naar de oorspronkelijke metagegevens als stap 3 een geverifieerde image heeft. Een ruwe image moet even groot zijn als het apparaat en hetzelfde resultaat geven bij thin_check. Het script vergelijkt een gecomprimeerde image byte voor byte met het apparaat.
  • Voordat het herstel de oorspronkelijke metagegevens overschrijft, typ je YES. Elk ander antwoord annuleert het schrijven.
  • Voordat het script schrijft, zoekt het in het kernellog naar meldingen van geheugenfouten en naar I/O-fouten van de schijven van de pool. Als het een fout vindt, vraagt het of je wilt doorgaan. Het standaardantwoord is nee.
  • Het script start geen herstel op een inactieve RAID. Als de RAID gedegradeerd is of als een heropbouw, hersynchronisatie, wijziging van de indeling of controle loopt, vraagt het script eerst om bevestiging. Het standaardantwoord is nee.
  • Na herstel van de toewijzing biedt stap 5 aan het bestandssysteem van de betrokken volumes zonder schrijftoegang te controleren (e2fsck -fn) voordat de volumes worden aangekoppeld. Vindt de controle fouten, kies dan e2fsck -fp of kies e2fsck -fy en typ daarvoor FSCK. Je kunt ook later Check File System in QTS gebruiken.
  • De werkmap met de logbestanden en de image van de metagegevens staat buiten de pool, op een externe schijf of op een volume van een andere pool. Het script accepteert geen map op de pool die je herstelt.
  • Het script draait in screen en blijft draaien als de SSH-sessie wegvalt. Start het script opnieuw om terug te keren naar de sessie.
  • De sessiestatus staat buiten de pool op de systeempartitie van de NAS (md9). Na een herstart vindt het script de onafgeronde sessie en vraagt het of je wilt doorgaan.
  • Tijdens de test gebruikt LVM de herstelde kopie voor de pool. De volumegroep heeft tijdens de test de vlag skip-activation. Daardoor blijft de pool offline als de NAS opnieuw opstart.
  • Er zijn twee uitzonderingen. Als de metagegevens consistent zijn en alleen de vlag needs_check is ingesteld, wist het script de vlag zonder image, zonder hardware- en RAID-controle en zonder invoer van YES. Met de noodoptie --allow-no-backup vervalt alleen de verplichting om een image te maken. Zie de beschrijving onder Opties.
  • Als een volume niet terugkomt, kan QTS de opslagconfiguratie ervan opnieuw opbouwen met init_lvm.sh. Het script voert de opdracht pas uit nadat je REBUILD hebt getypt. Het slaat eerst de bestanden op en toont daarna alle instellingen die bij het opnieuw opbouwen zijn gewijzigd.

Beperkingen

  • Het herstel kan gegevens in beschadigde toewijzingsbereiken niet terughalen. In de opname over de toewijzing waren twee bladeren van de toewijzingsboom van een testvolume met 600 bestanden van elk 4 MiB beschadigd. Na het herstel kwamen de controlesommen van 534 bestanden overeen met de opgeslagen waarden. De 66 bestanden met gegevens in de twee verwijderde bereiken waren gewijzigd.
  • Het script herstelt alleen de metagegevens van de pool. Het herstelt geen schijven, RAID of ontbrekend fysiek LVM-volume.
  • Het script werkt op QTS met een LVM thin pool. Op QuTS hero, dat ZFS gebruikt, stopt het bij het starten.
  • Bij een SSD-cache voor lezen en schrijven of alleen voor schrijven, of bij gegevens op twee of meer Qtier-niveaus, stopt het script vóór stap 2 en vóór het herstel en verwijst het je naar de ondersteuning van QNAP. Bij een SSD-cache voor alleen lezen vraagt het script eerst of de cache is verwijderd of voor deze pool is uitgeschakeld.
  • De pool gaat offline voor het herstel. In de voorzichtige modus stopt het script het snapshotbeheer als snapshots van de pool zijn aangekoppeld. Blijft een volume in gebruik, dan kies je hoe ver het script gaat. Het kan het snapshotbeheer of alle QTS-services stoppen, de processen beëindigen die het volume gebruiken, of de volumegroep markeren zodat de pool na een herstart van de NAS offline blijft. In de volledige modus stopt het script alle QTS-services meteen. Stap 5 biedt aan om ze weer te starten.
  • Het script controleert het bestandssysteem van een versleuteld volume niet. Als de NAS een SSD-cachevolume heeft, slaat het script de bestandssysteemcontrole over.
  • Een hardwarecontrole zonder fouten bewijst niet dat het RAM goed werkt. MemHound test het geheugen.
  • De meldingen van het script zijn in het Engels. Beantwoord elke vraag met een letter, cijfer of woord en druk op Enter. De pijltjestoetsen werken niet in het menu. Ctrl+C onderbreekt het script niet.