Unofficial

LVM Pool Repair: script per riparare i metadati di un thin pool QNAP

Uno script di shell con menu ripara tramite SSH i metadati di un thin pool QNAP su QTS.

La riparazione si svolge in cinque passaggi. Lo script esegue la diagnosi, prepara il pool, crea una copia di backup, ripara i metadati e rimette in servizio il pool e i volumi.

Nel menu, prema Invio per avviare il passaggio successivo consigliato dallo script. Se la sessione SSH si interrompe o il NAS si riavvia, può riprendere la stessa sessione di riparazione.

Versione 1.8 · sul NAS, tramite SSH, come admin · QTS con un thin pool LVM · software gratuito

  • 5passaggi nel menu, nell’ordine di riparazione
  • 3tipi di danni ai metadati, ciascuno con una procedura di riparazione
  • YESla parola da digitare prima che la riparazione sovrascriva i metadati del pool

Registrazioni dello script

Ogni registrazione mostra una sessione SSH reale con la versione 1.7 dello script su un NAS QNAP, in un terminale di 80 per 25 caratteri. La versione 1.8 aggiunge a queste schermate una sezione per la verifica in sola lettura del RAID e dei dischi, prima del menu e all’inizio del passaggio 1. Abbiamo danneggiato intenzionalmente i metadati del pool in punti noti e conservato i blocchi originali. Abbiamo scritto i metadati danneggiati dopo il passaggio 2, mentre il pool era offline. Le registrazioni saltano questa pausa. Dopo il passaggio 2 lo script prosegue con la diagnosi nella stessa sessione. Le registrazioni abbreviano le attese più lunghe. La loro durata effettiva dipende dalle dimensioni del pool e dai suoi snapshot.

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.                                              
La registrazione inizia con i comandi di download, a partire da cd /mnt/HDA_ROOT. Il passaggio 2 mette offline il pool. Mentre lo script attende nel menu, impostiamo una voce della mappa di allocazione dello spazio dei metadati su un valore errato. Poi a avvia l’esecuzione automatica. Lo script esegue la diagnosi, salva un’immagine dei metadati, ripara il pool e rimette in servizio il pool, i volumi e le applicazioni. Si ferma una sola volta per attendere l’immissione di YES prima di scrivere nel pool.Una voce della mappa di allocazione dello spazio dei metadati è errata. Lo script arresta i servizi, salva un’immagine verificata dei metadati, crea una copia riparata e la verifica. Dopo l’immissione di YES, scrive la copia nel pool. Il passaggio 5 rimette in servizio il pool, i volumi e le applicazioni.Il superblocco primario è danneggiato e le sue copie di backup sono valide. Lo script legge i metadati tramite la copia più recente. Dopo l’immissione di YES, lo script ripristina il superblocco da quella copia, controlla i metadati e rimette in servizio il pool.Due foglie dell’albero di mappatura di un volume di prova sono danneggiate. Il pool usa la copia riparata per un montaggio di prova in sola lettura. Durante il montaggio di prova vengono letti i file. Dopo la conferma dei dati e l’immissione di YES, lo script scrive la copia nel pool e controlla il file system del volume di prova prima che QTS lo monti. Il controllo finale dei checksum dei 600 file di prova rileva che 534 sono intatti e 66 sono cambiati.Il danno è lo stesso. Il NAS si riavvia durante il montaggio di prova in sola lettura. Dopo il riavvio il pool resta offline, perché lo script ha impostato il flag skip-activation prima della prova. Dopo un nuovo accesso via SSH, avviamo di nuovo lo script. Trova la sessione incompleta e completa la riparazione.

Scarica lo script

Per scaricare lo script serve un PIN. Digiti il PIN per visualizzare il link per il download.

Avviare lo script

Lo script viene eseguito sul NAS. Richiede l’account admin perché QTS non dispone di sudo.

  1. Acceda al NAS tramite SSH come admin.
  2. Passi alla cartella che contiene lo script. La cartella deve essere fuori dal pool da riparare.
  3. Avvii lo script con il primo comando qui sotto.
  4. Scelga una directory di lavoro fuori dal pool. Senza questa directory lo script può eseguire la diagnosi, ma il passaggio 3 non può salvare l’immagine dei metadati.
# avviare lo script e il relativo menu
sh qnap-pool-repair.sh
# tornare alla sessione dopo un’interruzione della connessione
screen -r qnap-pool-repair

Una riparazione dello storage può essere irreversibile. Prima che lo script scriva dati, verifichi di avere un backup dei dati importanti e che la diagnosi corrisponda al suo NAS.

Opzioni

--auto
Avvia l’esecuzione automatica quando lo script rileva il pool. I passaggi da 1 a 5 si susseguono. L’esecuzione automatica richiede una directory di lavoro.
--debug
Mostra la traccia delle chiamate e racchiude ogni comando in un riquadro. Scrive la traccia completa della shell in trace.log. Per farlo serve una directory di lavoro.
--no-screen
Esegue lo script senza una sessione screen.
--selftest
Verifica in sola lettura i comandi usati dallo script, poi termina.
--raid-check
Verifica in sola lettura gli array RAID, i loro membri e le firme QNAP sui dischi, poi termina. Non serve alcun pool.
--allow-no-backup
Solo per le emergenze. Può confermare la procedura rapida o completa senza un’immagine dei metadati. Digiti NO-BACKUP e poi il nome del pool così come lo mostra lo script, ad esempio vg1/tp1. L’esecuzione automatica non usa questa opzione.
--help
Mostra le opzioni.
--version
Mostra la versione.

I cinque passaggi

Prima di mostrare il menu, lo script visualizza la scritta WARNING in rosso e verifica che sul NAS siano disponibili i 79 comandi che usa. In una nuova sessione, lo script verifica poi in sola lettura gli array RAID e i loro dischi. Il menu elenca i passaggi nell’ordine di riparazione e mostra lo stato di ciascuno. Il tasto Invio avvia il passaggio consigliato. L’esecuzione automatica svolge tutti i passaggi rimanenti in sequenza e usa la risposta predefinita quando è sicura. Lo script chiede comunque conferma per i volumi in uso e per i dati del montaggio di prova. Chiede anche di digitare YES.

  1. Status and diagnosis

    Lo script controlla il RAID e l’hardware. Con il pool offline esegue thin_check sui metadati del pool. Se il pool è ancora attivo, propone un controllo preliminare in sola lettura.

    sola lettura
  2. Prepare

    Lo script smonta i volumi del pool e disattiva il gruppo di volumi. In modalità graduale smonta solo ciò che appartiene a questo pool. Arresta i servizi solo se qualche risorsa è ancora in uso.

    pool offline
  3. Backup

    Lo script salva la configurazione LVM e scrive un’immagine dei metadati nella directory di lavoro. Accetta l’immagine solo dopo aver verificato che corrisponda al dispositivo.

    immagine verificata
  4. Repair the metadata

    Lo script propone la procedura di riparazione adatta alla diagnosi. Prima che la riparazione sovrascriva i metadati originali, digiti YES.

    immissione di YES
  5. Bring the pool and the volumes up

    Lo script attiva il pool. QTS monta i volumi e lo script confronta ciascun volume con l’elenco salvato in precedenza. Lo script propone di riavviare i servizi che ha arrestato. Quando tutti i volumi sono di nuovo disponibili, mostra LOOKS GOOD, scrive un rapporto e archivia i registri.

    rapporto e registri

Risultati della diagnosi

Al passaggio 1 lo script comunica il risultato di thin_check con uno dei suoi messaggi. Al passaggio 4 propone la procedura di riparazione adatta al risultato.

  • space map counts only

    Gli errori riguardano solo i contatori della mappa di allocazione dello spazio. Gli alberi di mappatura sono intatti.

    Procedura rapida. Lo script crea una copia riparata su un volume riservato e la verifica. Dopo l’immissione di YES, lo script scrive la copia nel pool.

  • damaged superblock

    Il superblocco primario è danneggiato. Lo script trova nei metadati copie di backup valide del superblocco.

    Lo script legge i metadati tramite la copia valida più recente. Dopo l’immissione di YES, lo script ripristina il superblocco da quella copia e ripete la diagnosi.

  • mapping tree errors

    Alcune parti dell’albero che mappa i blocchi di un volume sono danneggiate. La riparazione elimina gli intervalli interessati dalla mappatura. Quando si leggono i blocchi di quegli intervalli, risultano vuoti.

    Procedura completa. Il pool usa la copia riparata per un montaggio di prova in sola lettura. Controlli i dati e ne confermi la correttezza. Dopo l’immissione di YES, lo script scrive la copia nel pool.

  • data NOT OK

    Se durante il montaggio di prova segnala che i dati non sono corretti, lo script ripristina la configurazione LVM originale. I metadati originali restano invariati.

    Invii il caso all’assistenza QNAP con l’archivio dei registri del menu 7 e il pacchetto tp_collect del menu Tools.

Lo script tratta un risultato sconosciuto come un danno alla mappatura. Se la mappa di allocazione dello spazio è danneggiata, propone anche due procedure che scrivono direttamente nei metadati originali. Le procedure sono legacy (thin_dump e thin_restore) e rebuild (thin_rebuild di QNAP). Entrambe richiedono l’immagine verificata e l’immissione di YES. Se il pool non ha un volume riservato alla copia, legacy è l’unica procedura per riparare la mappatura. Per sceglierla, digiti LEGACY.

Regole di sicurezza

  • Una procedura di riparazione scrive nei metadati originali solo quando al passaggio 3 è disponibile un’immagine verificata. Un’immagine grezza deve avere le stesse dimensioni del dispositivo e produrre lo stesso risultato con thin_check. Lo script confronta un’immagine compressa con il dispositivo byte per byte.
  • Prima che la riparazione sovrascriva i metadati originali, digiti YES. Qualsiasi altra risposta annulla la scrittura.
  • Prima di scrivere, lo script cerca nel registro del kernel le segnalazioni di errori di memoria e gli errori di I/O dei dischi del pool. Se trova un errore, chiede se continuare. La risposta predefinita è «no».
  • Lo script non avvia una riparazione su un RAID inattivo. Se il RAID è degradato o è in corso una ricostruzione, una risincronizzazione, una modifica della struttura o un controllo, lo script chiede prima conferma. La risposta predefinita è «no».
  • Dopo aver riparato la mappatura, il passaggio 5 propone un controllo del file system in sola lettura (e2fsck -fn) sui volumi interessati prima di montarli. Se il controllo rileva errori, scelga e2fsck -fp o scelga e2fsck -fy e digiti FSCK per avviarlo. Può anche usare più tardi Check File System in QTS.
  • La directory di lavoro con i registri e l’immagine dei metadati si trova fuori dal pool, su un disco esterno o su un volume di un altro pool. Lo script non accetta cartelle del pool da riparare.
  • Lo script viene eseguito in screen e continua a funzionare se la sessione SSH si interrompe. Avvii di nuovo lo script per tornare alla sessione.
  • Lo stato della sessione si trova sulla partizione di sistema del NAS (md9), fuori dal pool. Dopo un riavvio, lo script trova la sessione incompleta e chiede se riprenderla.
  • Durante il montaggio di prova, LVM fa puntare il pool alla copia riparata. Durante la prova il gruppo di volumi ha il flag skip-activation. Se il NAS si riavvia, il pool resta offline.
  • Ci sono due eccezioni. Se i metadati sono coerenti ed è impostato solo il flag needs_check, lo script rimuove il flag senza un’immagine, senza controllare l’hardware e il RAID e senza chiedere di digitare YES. L’opzione di emergenza --allow-no-backup elimina solo l’obbligo dell’immagine. La descrizione è nella sezione delle opzioni.
  • Se un volume non torna disponibile, QTS può ricostruirne la configurazione di archiviazione con init_lvm.sh. Lo script esegue il comando solo dopo che avrà digitato REBUILD. Prima salva i file, poi elenca tutte le impostazioni modificate dalla ricostruzione.

Limiti

  • La riparazione non può recuperare i dati negli intervalli di mappatura danneggiati. Nella registrazione sulla mappatura erano danneggiate due foglie dell’albero di mappatura di un volume di prova con 600 file da 4 MiB. Dopo la riparazione, i checksum di 534 file corrispondevano ai valori salvati. I 66 file che contenevano dati nei due intervalli scartati risultavano modificati.
  • Lo script ripara solo i metadati del pool. Non ripara dischi, RAID o volumi fisici LVM mancanti.
  • Lo script funziona su QTS con un thin pool LVM. Su QuTS hero, che usa ZFS, si arresta all’avvio.
  • Con una cache SSD in lettura e scrittura o in sola scrittura, oppure con dati su due o più livelli Qtier, lo script si ferma prima del passaggio 2 e prima della riparazione e rimanda all’assistenza QNAP. Con una cache SSD in sola lettura, chiede prima se la cache è stata rimossa o disattivata per questo pool.
  • Il pool passa offline per la riparazione. In modalità graduale lo script arresta il gestore snapshot se gli snapshot del pool sono montati. Se un volume resta in uso, può scegliere fino a che punto procedere. Lo script può arrestare il gestore snapshot o tutti i servizi QTS, terminare i processi che usano il volume o contrassegnare il gruppo di volumi affinché il pool resti offline dopo il riavvio del NAS. In modalità completa lo script arresta subito tutti i servizi QTS. Il passaggio 5 propone di riavviarli.
  • Lo script non controlla il file system di un volume crittografato. Se sul NAS è presente un volume di cache SSD, lo script salta il controllo del file system.
  • Un controllo dell’hardware senza errori non garantisce che la RAM funzioni correttamente. MemHound verifica la memoria.
  • I messaggi dello script sono in inglese. Risponda a ogni richiesta con una lettera, una cifra o una parola, poi prema Invio. I tasti freccia non funzionano nel menu. Ctrl+C non interrompe lo script.