Unofficial

LVM Pool Repair : script de réparation des métadonnées d’un pool à provisionnement fin QNAP

Ce script shell à menu répare par SSH les métadonnées d’un pool de stockage léger QNAP sous QTS.

La réparation se déroule en cinq étapes. Le script établit le diagnostic, prépare le pool, crée une sauvegarde, répare les métadonnées, puis remet en service le pool et les volumes.

Dans le menu, appuyez sur Entrée pour lancer l’étape suivante recommandée par le script. Si la session SSH est interrompue ou si le NAS redémarre, vous reprenez la même session de réparation.

Version 1.8 · sur le NAS, par SSH, avec le compte admin · QTS avec un pool léger LVM · logiciel gratuit

  • 5étapes dans le menu, dans l’ordre de la réparation
  • 3types de corruption des métadonnées, chacun avec sa procédure de réparation
  • YESle mot à saisir avant que la réparation écrase les métadonnées du pool

Enregistrements du script

Chaque enregistrement montre une véritable session SSH avec la version 1.7 du script sur un NAS QNAP, dans un terminal de 80 par 25 caractères. La version 1.8 ajoute à ces écrans une section consacrée à la vérification en lecture seule du RAID et des disques, avant le menu et au début de l’étape 1. Nous avons volontairement endommagé les métadonnées du pool à des emplacements connus et conservé les blocs d’origine. Nous avons écrit les métadonnées endommagées après l’étape 2, alors que le pool était hors ligne. Les enregistrements sautent cette pause. Après l’étape 2, le script poursuit le diagnostic dans la même session. Les enregistrements raccourcissent les longues attentes. Leur durée réelle dépend de la taille du pool et de ses 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.                                              
L’enregistrement commence par les commandes de téléchargement, à partir de cd /mnt/HDA_ROOT. L’étape 2 met le pool hors ligne. Pendant que le script attend dans le menu, nous donnons une valeur incorrecte à une entrée de la carte d’allocation de l’espace des métadonnées. Ensuite, a lance l’exécution automatique. Le script établit le diagnostic, enregistre une image des métadonnées, effectue la réparation et remet en service le pool, les volumes et les applications. Il ne s’arrête qu’une fois, pour attendre la saisie de YES avant d’écrire dans le pool.Une entrée de la carte d’allocation de l’espace des métadonnées est incorrecte. Le script arrête les services, enregistre une image vérifiée des métadonnées, crée une copie réparée et la vérifie. Après la saisie de YES, il écrit la copie dans le pool. L’étape 5 remet en service le pool, les volumes et les applications.Le superbloc principal est endommagé et ses copies de sauvegarde sont valides. Le script lit les métadonnées à partir de la copie la plus récente. Après la saisie de YES, le script restaure le superbloc à partir de cette copie, vérifie les métadonnées et remet le pool en service.Deux feuilles de l’arbre de mappage d’un volume de test sont endommagées. Le pool utilise la copie réparée pour un montage de test en lecture seule. Les fichiers sont lus lors de ce montage. Après validation des données et saisie de YES, le script écrit la copie dans le pool et vérifie le système de fichiers du volume de test avant que QTS ne le monte. À la fin, la vérification des sommes de contrôle des 600 fichiers de test donne 534 fichiers intacts et 66 modifiés.Les dommages sont les mêmes. Le NAS redémarre pendant le montage de test en lecture seule. Après le redémarrage, le pool reste hors ligne, car le script a activé l’indicateur skip-activation avant le test. Après une nouvelle connexion SSH, nous relançons le script. Il retrouve la session inachevée et termine la réparation.

Télécharger le script

Le téléchargement est protégé par un code PIN. Saisissez le code PIN pour afficher le lien de téléchargement.

Lancer le script

Le script s’exécute directement sur le NAS. Il nécessite le compte admin, car QTS ne fournit pas sudo.

  1. Connectez-vous au NAS par SSH avec le compte admin.
  2. Accédez au dossier qui contient le script. Ce dossier doit se trouver hors du pool à réparer.
  3. Lancez le script avec la première commande ci-dessous.
  4. Choisissez un répertoire de travail hors du pool. Sans ce répertoire, le script peut établir un diagnostic, mais l’étape 3 ne peut pas enregistrer l’image des métadonnées.
# lancer le script et afficher son menu
sh qnap-pool-repair.sh
# revenir à la session après une interruption de la connexion
screen -r qnap-pool-repair

Une réparation du stockage peut être irréversible. Avant toute écriture du script, vérifiez que vos données importantes sont sauvegardées et que le diagnostic correspond à votre NAS.

Options

--auto
Lance le mode automatique dès que le script détecte le pool. Les étapes 1 à 5 s’enchaînent. Le mode automatique exige un répertoire de travail.
--debug
Affiche la trace des appels et encadre chaque commande. Écrit la trace complète du shell dans trace.log. Cette opération exige un répertoire de travail.
--no-screen
Exécute le script sans session screen.
--selftest
Vérifie en lecture seule les commandes utilisées par le script, puis se termine.
--raid-check
Vérifie en lecture seule les ensembles RAID, leurs membres et les signatures QNAP sur les disques, puis se termine. Aucun pool n’est nécessaire.
--allow-no-backup
À utiliser uniquement en cas d’urgence. Vous pouvez confirmer la procédure rapide ou complète sans image des métadonnées. Saisissez NO-BACKUP, puis le nom du pool tel que le script l’affiche, par exemple vg1/tp1. Le mode automatique n’utilise pas cette option.
--help
Affiche les options.
--version
Affiche la version.

Les cinq étapes

Avant le menu, le script affiche le message WARNING en rouge et vérifie que les 79 commandes qu’il utilise sont disponibles sur le NAS. Dans une nouvelle session, le script vérifie ensuite en lecture seule les ensembles RAID et leurs disques. Le menu affiche les étapes dans l’ordre de la réparation et indique l’état de chacune. La touche Entrée lance l’étape recommandée. Le mode automatique enchaîne les étapes restantes et utilise la réponse par défaut lorsqu’elle est sûre. Le script vous interroge encore sur les volumes en cours d’utilisation et sur les données du montage de test. Il vous demande aussi de saisir YES.

  1. Status and diagnosis

    Le script vérifie le RAID et le matériel. Si le pool est hors ligne, il lance thin_check sur ses métadonnées. Si le pool est encore actif, il propose une vérification préliminaire en lecture seule.

    lecture seule
  2. Prepare

    Le script démonte les volumes du pool et désactive le groupe de volumes. En mode progressif, il démonte uniquement ce qui appartient à ce pool. Il arrête des services uniquement si des ressources restent en cours d’utilisation.

    pool hors ligne
  3. Backup

    Le script sauvegarde la configuration LVM et écrit une image des métadonnées dans le répertoire de travail. Il accepte l’image seulement après avoir vérifié qu’elle correspond au périphérique.

    image vérifiée
  4. Repair the metadata

    Le script propose la procédure de réparation adaptée au diagnostic. Avant que la réparation écrase les métadonnées d’origine, saisissez YES.

    saisie de YES
  5. Bring the pool and the volumes up

    Le script active le pool. QTS monte les volumes et le script vérifie chacun d’eux en le comparant à la liste enregistrée auparavant. Il propose de redémarrer les services qu’il a arrêtés. Lorsque tous les volumes sont de nouveau disponibles, il affiche LOOKS GOOD, écrit un rapport et archive les journaux.

    rapport et journaux

Résultats du diagnostic

À l’étape 1, le script affiche le résultat de thin_check sous la forme d’un de ses propres messages. À l’étape 4, il propose la procédure de réparation correspondant à ce résultat.

  • space map counts only

    Seuls les compteurs de la carte d’allocation de l’espace présentent des erreurs. Les arbres de mappage sont intacts.

    Procédure rapide. Le script crée une copie réparée sur un volume réservé et la vérifie. Une fois que vous avez saisi YES, il écrit la copie dans le pool.

  • damaged superblock

    Le superbloc principal est endommagé. Le script trouve des copies de sauvegarde valides dans les métadonnées.

    Le script lit les métadonnées à l’aide de la copie valide la plus récente. Une fois que vous avez saisi YES, il restaure le superbloc à partir de cette copie et relance le diagnostic.

  • mapping tree errors

    Certaines parties de l’arbre qui mappe les blocs d’un volume sont endommagées. La réparation supprime les plages concernées du mappage. À la lecture, leurs blocs apparaissent ensuite vides.

    Procédure complète. Le pool utilise la copie réparée pour un montage de test en lecture seule. Examinez les données et confirmez qu’elles sont correctes. Une fois que vous avez saisi YES, le script écrit la copie dans le pool.

  • data NOT OK

    Pendant le montage de test, vous indiquez que les données sont incorrectes. Le script rétablit la configuration LVM d’origine. Les métadonnées d’origine restent intactes.

    Transmettez le dossier à l’assistance QNAP avec l’archive des journaux du menu 7 et le paquet tp_collect du menu Tools.

Le script traite un résultat inconnu comme une corruption du mappage. Si la carte d’allocation de l’espace est endommagée, il propose aussi deux procédures qui écrivent directement dans les métadonnées d’origine. Il s’agit de legacy (thin_dump et thin_restore) et de rebuild (thin_rebuild de QNAP). Les deux exigent une image vérifiée et la saisie de YES. Pour réparer un mappage endommagé sans volume réservé à la copie, seule la procédure legacy est disponible. Pour la choisir, saisissez LEGACY.

Règles de sécurité

  • Une procédure de réparation écrit dans les métadonnées d’origine seulement après vérification de l’image à l’étape 3. Une image brute doit avoir la même taille que le périphérique et donner le même résultat avec thin_check. Le script compare une image compressée au périphérique, octet par octet.
  • Avant que la réparation écrase les métadonnées d’origine, saisissez YES. Toute autre réponse annule l’écriture.
  • Avant une écriture, le script recherche dans le journal du noyau les signalements d’erreurs de mémoire et les erreurs d’E/S des disques du pool. S’il trouve une erreur, il demande s’il doit continuer. La réponse par défaut est « non ».
  • Le script ne lance aucune réparation sur un RAID inactif. Si le RAID est dégradé ou si une reconstruction, une resynchronisation, une modification de sa structure ou une vérification est en cours, le script demande confirmation. La réponse par défaut est « non ».
  • Après la réparation du mappage, l’étape 5 propose une vérification en lecture seule du système de fichiers (e2fsck -fn) des volumes concernés avant de les monter. Si la vérification trouve des erreurs, choisissez e2fsck -fp ou e2fsck -fy et saisissez FSCK pour lancer cette seconde commande. Vous pouvez aussi utiliser plus tard Check File System dans QTS.
  • Le répertoire de travail qui contient les journaux et l’image des métadonnées doit se trouver hors du pool, sur un disque externe ou sur un volume d’un autre pool. Le script refuse les dossiers du pool en cours de réparation.
  • Le script s’exécute dans screen. Il continue donc de fonctionner si la session SSH est interrompue. Relancez le script pour revenir à la session.
  • L’état de la session est enregistré hors du pool, sur la partition système du NAS (md9). Après un redémarrage, le script retrouve la session inachevée et demande s’il doit la reprendre.
  • Pendant le montage de test, LVM fait pointer le pool vers la copie réparée. Le groupe de volumes porte alors l’indicateur skip-activation. Si le NAS redémarre, le pool reste hors ligne.
  • Il y a deux exceptions. Si les métadonnées sont cohérentes et que seul l’indicateur needs_check est défini, le script efface cet indicateur sans image, sans vérification du matériel ni du RAID et sans saisie de YES. L’option d’urgence --allow-no-backup dispense uniquement de l’image. Elle est décrite dans la section des options.
  • Si un volume ne redevient pas disponible, QTS peut reconstruire sa configuration de stockage avec init_lvm.sh. Le script exécute cette commande seulement après que vous avez saisi REBUILD. Il sauvegarde d’abord les fichiers, puis répertorie tous les paramètres modifiés par la reconstruction.

Limites

  • La réparation ne récupère pas les données des plages de mappage endommagées. Dans l’enregistrement consacré au mappage, deux feuilles de l’arbre de mappage d’un volume de test contenant 600 fichiers de 4 MiB étaient endommagées. Après la réparation, les sommes de contrôle de 534 fichiers correspondaient aux valeurs enregistrées. Les 66 fichiers qui contenaient des données dans les deux plages écartées avaient changé.
  • Le script répare uniquement les métadonnées du pool. Il ne répare ni les disques, ni le RAID, ni un volume physique LVM manquant.
  • Le script fonctionne sous QTS avec un pool léger LVM. Sous QuTS hero, qui utilise ZFS, il s’arrête au démarrage.
  • Avec un cache SSD en lecture et écriture ou en écriture seule, ou avec des données réparties sur deux niveaux Qtier ou plus, le script s’arrête avant l’étape 2 et avant la réparation, et vous renvoie vers l’assistance QNAP. Avec un cache SSD en lecture seule, il vous demande d’abord si le cache a été supprimé ou désactivé pour ce pool.
  • Le pool passe hors ligne pour la réparation. En mode progressif, le script arrête le gestionnaire de snapshots si des snapshots du pool sont montés. Si un volume reste en cours d’utilisation, vous choisissez jusqu’où aller. Le script peut arrêter le gestionnaire de snapshots ou tous les services QTS, mettre fin aux processus qui utilisent le volume ou marquer le groupe de volumes pour maintenir le pool hors ligne après le redémarrage du NAS. En mode complet, le script arrête tous les services QTS d’emblée. L’étape 5 propose de les redémarrer.
  • Le script ne vérifie pas le système de fichiers d’un volume chiffré. Si le NAS contient un volume de cache SSD, le script ignore la vérification du système de fichiers.
  • Une vérification du matériel sans erreur ne garantit pas que la RAM fonctionne correctement. MemHound teste la mémoire.
  • Le script affiche ses messages en anglais. Répondez à chaque question par une lettre, un chiffre ou un mot, puis appuyez sur Entrée. Les touches fléchées ne fonctionnent pas dans le menu. Ctrl+C n’interrompt pas le script.