LVM Pool Repair:QNAPのシンプールのメタデータを修復するスクリプト
メニュー形式のシェルスクリプトです。SSH経由で、QTS上のQNAPのシンプールのメタデータを修復します。
修復は五つの手順で進みます。スクリプトは診断、プールの準備、バックアップ、修復を行い、最後にプールとボリュームを再稼働させます。
メニューでEnterキーを押すと、スクリプトが次に推奨する手順を実行します。SSHセッションが切断されたりNASが再起動したりしても、同じ修復セッションを再開できます。
- 5修復順にメニューに並ぶ手順
- 3メタデータの破損の種類。それぞれ修復方法が異なります
- YESプールのメタデータを上書きする前に入力する語
スクリプトの実行録画
各録画は、QNAP NAS上でバージョン1.7のスクリプトを実行した実際のSSHセッションです。端末のサイズは横80文字、縦25文字です。バージョン1.8では、これらの画面に、メニューの表示前と手順1の開始時に書き込みを行わずにRAIDとディスクを確認するセクションが追加されます。プールのメタデータをあらかじめ決めた箇所で意図的に破損させ、元のブロックを保存しておきました。破損させたメタデータは、手順2の後、プールがオフラインの間に書き込みました。録画ではこの中断を省いています。手順2の後、スクリプトは同じセッションで診断に進みます。録画では長い待ち時間を短縮しています。実際の待ち時間はプールのサイズとスナップショットによって変わります。
░░░ ░░░ ░░░ ░░░ ░░░ ░░░ ░░░ ░░░ ░░░ ░░░ ░░░ ░░░ ░░░ ░░░ ░░░ ░░░ ░░░ ▀▀▀▀▀ ▀▀▀▀▀▀▀ ▀▀▀▀▀▀▀ ▀▀▀ ▀▀▀ ▀▀▀▀▀▀▀ ▀▀▀▀▀▀ ▀▀▀▀▀▀▀ ▀▀▀▀▀▀▀ ▀▀▀▀▀▀ 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から始まります。手順2でプールをオフラインにします。スクリプトがメニューで入力を待つ間に、メタデータのスペースマップの項目を一つ誤った値に設定します。続いてaで自動実行を開始します。スクリプトは診断を行い、メタデータのイメージを保存し、修復してからプール、ボリューム、アプリを再稼働させます。スクリプトが停止するのは一度だけです。プールに書き込む前に、操作者がYESと入力するのを待ちます。メタデータのスペースマップで、項目が一つ誤っています。スクリプトはサービスを停止し、検証済みのメタデータのイメージを保存してから、修復済みのコピーを作成して検証します。操作者がYESと入力すると、コピーをプールに書き込みます。手順5でプール、ボリューム、アプリを再稼働させます。プライマリスーパーブロックが破損していますが、バックアップコピーは正常です。スクリプトは最新のコピーを使ってメタデータを読み取ります。操作者がYESと入力すると、スクリプトはそのコピーからスーパーブロックを復元し、メタデータを確認してプールを再稼働させます。テスト用ボリュームのマッピングツリーで、二つのリーフが破損しています。プールは修復済みのコピーを使い、読み取り専用でテストマウントを行います。このテストマウントでファイルを読み取ります。操作者がデータを確認してYESと入力すると、スクリプトはコピーをプールに書き込みます。QTSがボリュームをマウントする前に、スクリプトはそのファイルシステムを確認します。最後にテスト用ファイル600個のチェックサムを照合した結果、534個は正常で、66個は変化していました。破損の内容は同じです。読み取り専用のテストマウント中にNASが再起動します。スクリプトがテストの前にskip-activationフラグを設定していたため、再起動後もプールはオフラインのままです。SSHで再ログインし、スクリプトをもう一度実行します。スクリプトは未完了のセッションを見つけ、修復を完了します。スクリプトのダウンロード
スクリプトのダウンロードにはPINが必要です。PINを入力すると、ダウンロードリンクが表示されます。
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.shスクリプトの起動
スクリプトはNAS上で直接実行します。QTSにはsudoがないため、adminアカウントが必要です。
- SSH経由でNASにadminとしてログインしてください。
- スクリプトがあるフォルダーに移動してください。フォルダーは修復対象のプールの外にある必要があります。
- 下の最初のコマンドでスクリプトを起動してください。
- プールの外にある作業ディレクトリを選んでください。作業ディレクトリがなくても診断はできますが、手順3でメタデータのイメージを保存できません。
# スクリプトを起動してメニューを表示 sh qnap-pool-repair.sh # 接続が切断された後にセッションへ戻る screen -r qnap-pool-repair
ストレージの修復は元に戻せない場合があります。スクリプトが書き込む前に、大切なデータのバックアップがあり、診断結果がNASの状態に合っていることを確認してください。
オプション
--auto- スクリプトがプールを検出すると自動実行を開始します。手順1から5までを順に実行します。自動実行には作業ディレクトリが必要です。
--debug- 呼び出しのトレースを表示し、各コマンドを枠で囲んで表示します。シェルの完全なトレースを
trace.logに書き込みます。書き込みには作業ディレクトリが必要です。 --no-screenscreenセッションを使わずにスクリプトを実行します。--selftest- 書き込みを行わずに、スクリプトが使用するコマンドを確認して終了します。
--raid-check- 書き込みを行わずに、RAIDアレイ、そのメンバー、ディスク上のQNAPシグネチャを確認して終了します。プールは必要ありません。
--allow-no-backup- 緊急時に限って使用してください。このオプションを使うと、メタデータのイメージがなくても簡易修復または完全修復を承認できます。
NO-BACKUPと入力し、続けてスクリプトに表示されたプール名を入力してください。プール名の例はvg1/tp1です。自動実行ではこのオプションを使いません。 --help- オプションを表示します。
--version- バージョンを表示します。
五つの手順
メニューを表示する前に、スクリプトはWARNINGを赤字で表示し、使用する79個のコマンドがNASにそろっているか確認します。新しいセッションでは、その後、書き込みを行わずにRAIDアレイとそのディスクを確認します。メニューは修復順に手順を並べ、各手順の状態を表示します。Enterキーを押すと、推奨された手順を実行します。自動実行では、残りの手順を順に実行し、安全な既定の回答がある質問にはその回答を使います。使用中のボリュームとテストマウントで確認するデータについては、引き続き回答が必要です。YESの入力も必要です。
Status and diagnosis
スクリプトはRAIDとハードウェアを確認します。プールがオフラインの場合は、プールのメタデータに対して
読み取り専用thin_checkを実行します。プールがまだ稼働中の場合は、読み取り専用の予備チェックを提案します。Prepare
スクリプトはプールのボリュームをアンマウントし、ボリュームグループを非アクティブ化します。影響を抑えるモードでは、このプールに属するものだけをアンマウントします。使用中のリソースが残る場合に限り、サービスを停止します。
プールはオフラインBackup
スクリプトはLVMの構成を保存し、メタデータのイメージを作業ディレクトリに書き込みます。イメージがデバイスと一致することを確認してから、そのイメージを受け入れます。
検証済みイメージRepair the metadata
スクリプトは診断結果に合った修復方法を提示します。元のメタデータを上書きする前に、
YESの入力YESと入力してください。Bring the pool and the volumes up
スクリプトはプールを有効にします。QTSがボリュームをマウントし、スクリプトは各ボリュームを事前に保存した一覧と照合します。停止したサービスがあれば、その起動を提案します。すべてのボリュームが再び利用可能になると、LOOKS GOODを表示し、レポートを書き出し、ログをまとめます。
レポートとログ
診断で分かること
手順1では、thin_checkの結果をスクリプト固有のメッセージで表示します。手順4では、その結果に応じた修復方法を提示します。
- space map counts only
エラーがあるのはスペースマップのカウントだけです。マッピングツリーに破損はありません。
簡易修復では、スクリプトが予約済みボリュームに修復済みのコピーを作成して検証します。
YESと入力すると、そのコピーをプールに書き込みます。 - damaged superblock
プライマリスーパーブロックが破損しています。スクリプトはメタデータ内に正常なバックアップコピーを見つけます。
スクリプトは正常なコピーのうち最新のものを使ってメタデータを読み取ります。
YESと入力すると、そのコピーからスーパーブロックを復元し、診断をやり直します。 - mapping tree errors
ボリュームのブロックを対応付けるツリーの一部が破損しています。修復では、該当する範囲をマッピングから除外します。その範囲のブロックを読み取ると、空として扱われます。
完全修復では、プールが修復済みのコピーを使い、読み取り専用でテストマウントを行います。データを調べ、正しいことを確認してください。
YESと入力すると、スクリプトがコピーをプールに書き込みます。 - data NOT OK
テストマウント中にデータが正しくないと回答すると、スクリプトは元のLVM構成に戻します。元のメタデータは変更されません。
メニュー7のログ一式とToolsメニューの
tp_collectパッケージを添えて、QNAPのサポートにお問い合わせください。
スクリプトは、判別できない結果をマッピングの破損として扱います。スペースマップが破損している場合は、元のメタデータに直接書き込む方法も二つ提示します。legacy(thin_dumpとthin_restore)とrebuild(QNAPのthin_rebuild)です。どちらも検証済みのイメージとYESの入力が必要です。コピー用の予約済みボリュームがプールにない場合、マッピングの破損を修復できるのはlegacyだけです。選択するにはLEGACYと入力してください。
安全上のルール
- 修復処理が元のメタデータに書き込むのは、手順3で検証済みのイメージが用意できた後です。未圧縮の生イメージは、デバイスと同じサイズで、
thin_checkの結果も一致する必要があります。圧縮イメージは、スクリプトがデバイスとバイト単位で比較します。 - 元のメタデータを上書きする前に、
YESと入力してください。それ以外の回答では書き込みを中止します。 - 書き込む前に、スクリプトはカーネルログを調べ、メモリエラーの報告や、プールを構成するディスクのI/Oエラーを探します。エラーが見つかると、続行するかどうかを尋ねます。既定の回答は「いいえ」です。
- スクリプトは、非アクティブなRAIDでは修復を開始しません。RAIDがデグレード状態の場合や、再構築、再同期、構成変更、チェックのいずれかを実行中の場合は、先に確認を求めます。既定の回答は「いいえ」です。
- マッピングの破損を修復した後、手順5では対象ボリュームをマウントする前に、読み取り専用でファイルシステムをチェックする方法(
e2fsck -fn)を提示します。エラーが見つかった場合は、e2fsck -fpを選ぶか、e2fsck -fyを選んでFSCKと入力してください。後でQTSのCheck File Systemを使用することもできます。 - ログとメタデータのイメージを保存する作業ディレクトリは、プールの外に置いてください。外付けディスクか別のプールのボリュームを使います。修復対象のプールにあるフォルダーは指定できません。
- スクリプトは
screen内で動作するため、SSHセッションが切断されても実行を続けます。セッションに戻るには、スクリプトをもう一度実行してください。 - セッションの状態はプールの外にあるNASのシステムパーティション(md9)に保存します。再起動後、スクリプトは未完了のセッションを検出し、再開するかどうかを尋ねます。
- テストマウント中、LVMはプールの参照先を修復済みのコピーに切り替えます。その間はボリュームグループにskip-activationフラグが設定されます。NASを再起動してもプールはオフラインのままです。
- これらのルールには二つの例外があります。メタデータに整合性があり、
needs_checkフラグだけが設定されている場合、スクリプトはイメージの作成、ハードウェアとRAIDのチェック、YESの入力を省略してフラグを解除します。緊急用の--allow-no-backupはイメージの要件だけを解除します。詳しくはオプションの説明をご覧ください。 - ボリュームが再び利用可能にならない場合は、QTSが
init_lvm.shを使ってそのボリュームのストレージ構成を再構築できます。スクリプトはREBUILDと入力された場合にのみ実行します。実行前にファイルを保存し、再構築で変更された設定をすべて表示します。
制限事項
- マッピングの破損範囲にあるデータは修復では復元できません。マッピングの録画では、4 MiBのファイル600個が入ったテスト用ボリュームのマッピングツリーで、二つのリーフが破損していました。修復後、534個のファイルのチェックサムが保存済みの値と一致しました。除外された二つの範囲にデータがあった66個のファイルは変化していました。
- スクリプトが修復するのは、プールのメタデータだけです。ディスクやRAIDの修復、欠落したLVM物理ボリュームの復元はできません。
- スクリプトはLVMシンプールを持つQTSで動作します。ZFSを使うQuTS heroでは、起動時に終了します。
- 読み書き可能または書き込み専用のSSDキャッシュがある場合や、データが二つ以上のQtier階層にある場合は、スクリプトは手順2や修復に進む前に停止し、QNAPサポートへの問い合わせを案内します。読み取り専用のSSDキャッシュの場合は、キャッシュを削除済みか、このプールで無効にしているかを最初に尋ねます。
- 修復のため、プールはオフラインになります。影響を抑えるモードでは、プールのスナップショットがマウントされている場合、スクリプトはスナップショットマネージャーを停止します。使用中のボリュームが残る場合は、どこまで処理を進めるかを選んでください。スナップショットマネージャーの停止、QTSの全サービスの停止、ボリュームを使用中のプロセスの終了、またはNASの再起動後もプールをオフラインに保つためのボリュームグループへのフラグ設定を選べます。完全モードではQTSの全サービスを一度に停止し、手順5で停止したサービスの起動を提案します。
- スクリプトは暗号化ボリュームのファイルシステムをチェックしません。NASにSSDキャッシュボリュームがある場合は、ファイルシステムのチェックを省略します。
- ハードウェアチェックでエラーがなくても、RAMが正常とは限りません。メモリのテストにはMemHoundを使います。
- スクリプトのメッセージは英語です。各質問には文字、数字、または語を入力し、Enterキーを押して回答してください。メニューでは矢印キーは使えません。Ctrl+Cではスクリプトを中断できません。