Posted inVirtualization

libguestfsを使ったKVM/Proxmox仮想マシンのレスキュー：rootパスワードの再設定、起動障害の修復、データ救出を迅速に行う方法

Virtualization tutorial - IT technology blog
Virtualization tutorial - IT technology blog

起動しなくなったKVM/Proxmox仮想マシンをレスキューする3つの方法の比較

KVMやProxmox VEを運用していると、カーネルのアップデート直後にVMがカーネルパニックを起こしたり、/etc/fstabのUUIDを誤設定してemergency modeでスタックしたり、半年前に構築したVMのrootパスワードを忘れてしまったりといったトラブルに直面することがあります。VMのネットワークが不通になりSSH接続できない場合、ディスクイメージに直接アクセスして修復を行う必要があります。

代表的な3つの対処法は以下の通りです：

  • 方法1：レスキュー用ISO（SystemRescueやUbuntu Live CDなど）をアタッチし、VNC/コンソール経由で起動する。 初心者にも馴染みやすい手法ですが、時間がかかります。
  • 方法2：qemu-nbdを使用してディスクイメージ（qcow2/raw）をホストOS上にマウントする。 ホストのターミナルから直接ファイルの読み書きが可能ですが、LVMの競合リスクが潜んでいます。
  • 方法3：libguestfsツール群（guestfish、virt-edit、virt-customize、guestmountなど）を使用する。 隔離されたアプライアンス用カーネルを起動し、仮想ディスクを直接操作します。高速かつ安全です。

メリット・デメリットの詳細比較

1. レスキュー用ISOファイルのアタッチ

最大のメリットは、物理サーバーと同様の慣れ親しんだ操作感でchroot作業を行える点です。

デメリット：

  • ISOのダウンロード、仮想ハードウェアへのアタッチ、起動順序（boot order）の変更に5〜10分程度を要する。
  • noVNCコンソールを開いて手動でコマンドを入力する必要があり、操作の遅延やキー入力の引っかかりが発生しやすい。
  • 20〜30台のVMを一括で処理する際、Bashスクリプトによる自動化が難しい。

2. qemu-nbdによる仮想ディスクのマウント

メリット：VMを起動することなく、ホストのシェルから直接操作できる点です。

デメリット：

  • ホストとゲストの双方がpveやubuntu-vgなどのデフォルト名を使用している場合、LVMボリュームグループ（VG）の競合が発生しやすい。
  • ホスト側のカーネルが非互換なパーティションテーブルを上書きし、ファイルシステム障害を引き起こすリスクがある。
  • nbdの接続、パーティションのマッピング、マウント、ファイル修正、アンマウント、切断といった手順が多く煩雑。

3. libguestfsツールセット

メリット：

  • ホスト上で独立して動作し、VMの起動が不要でハイパーバイザーの状態に依存しない。
  • LVM、ソフトウェアRAID、LUKS暗号化パーティション、および主要なファイルシステム（ext4、XFS、Btrfs、NTFSなど）を自動認識する。
  • 安全性が高い。libguestfsは隔離環境で一時的な軽量QEMUアプライアンスを起動するため、ホストのカーネルに誤って影響を与える心配がない。
  • 圧倒的なスピード：パスワード変更、設定ファイル編集、データコピーなどが1行のコマンドで数秒のうちに完了する。

デメリット：

  • パッケージの依存関係（軽量QEMUカーネル、superminなど）により、約300MB〜500MBのディスク容量を消費する。
  • 対象のVMが完全に停止（STOPPED）している必要がある。稼働中のVMに対して実行するとデータ破損の原因となる。

libguestfsがトラブルシューティングの時間を大幅に削減できる理由

12ノード・約50台のVMで構成されるProxmoxラボ環境では、OSアップグレードの検証やネットワーク設定の変更が日常的に行われます。以前はVMの起動障害が発生するたびに、ISOをマウントしてコンソールから復旧作業を行っており、1台あたり10〜15分程度の時間を要していました。

libguestfsの導入により、一連の作業がホストノード上のCLIコマンド1行に集約され、復旧にかかる時間は30秒未満に短縮されました。複数のVMを一括で修復する際には、その効果が特に顕著になります。

導入手順と実践的なトラブルシューティングシナリオ

ステップ1：libguestfsのインストール

Proxmox VEまたはDebian/Ubuntuの場合：

apt-get update
apt-get install -y libguestfs-tools

RHEL、Rocky Linux、AlmaLinux 8/9の場合：

dnf install -y libguestfs-tools

Debian/Ubuntu環境でのカーネルエラー対処Tips： カーネルの読み取り権限制限により supermin: error: failed to find a suitable kernel というエラーが表示された場合は、以下のコマンドを実行します：

chmod 0644 /boot/vmlinuz-*

ステップ2：仮想マシンのディスクパスの確認

まず、対象のVMが確実に停止していること（status: stopped）を確認します。Proxmox VEの場合、ディスクイメージは通常以下のいずれかのパスに配置されています：

  • ZFSストレージ：/dev/zvol/rpool/data/vm-100-disk-0
  • LVM-Thinストレージ：/dev/pve/vm-100-disk-0
  • ディレクトリストレージ（Qcow2/Raw）：/var/lib/vz/images/100/vm-100-disk-0.qcow2

ステップ3：代表的な4つのレスキューシナリオ

1. 5秒でrootパスワードを変更する

virt-customizeを使用すると、OSを起動することなくrootユーザーの新しいパスワードを設定できます：

virt-customize -a /var/lib/vz/images/100/vm-100-disk-0.qcow2 --root-password password:MatKhauMoi@2026

sudo権限を持つ予備の管理者ユーザーを追加する場合：

virt-customize -a /var/lib/vz/images/100/vm-100-disk-0.qcow2 \
  --run-command 'useradd -m -s /bin/bash rescueadmin' \
  --password rescueadmin:password:AdminPass@2026 \
  --run-command 'usermod -aG sudo rescueadmin'

2. virt-editで破損した設定ファイルを修正する

よくあるシナリオとして、2台目のハードディスクを追加した際に/etc/fstabのUUID設定を誤り、Linuxが正常に起動しなくなるケースがあります。virt-editコマンドを使用すると、ホスト上のエディタ（nanoまたはvi）で該当ファイルを直接開いて編集できます：

virt-edit -a /var/lib/vz/images/100/vm-100-disk-0.qcow2 /etc/fstab

問題のある行を削除または修正して保存するだけで、仮想ディスク上のデータが即座に同期されます。

3. 起動ログの確認と緊急データ抽出

クラッシュの原因を特定するために、ログの末尾50行を素早く確認します：

virt-cat -a /var/lib/vz/images/100/vm-100-disk-0.qcow2 /var/log/syslog | tail -n 50

OSの損傷が激しく、ソースコードやデータベースを緊急で取り出す必要がある場合は、ホスト上の一時ディレクトリにファイルシステム全体をマウントします：

mkdir -p /mnt/vm_rescue
guestmount -a /var/lib/vz/images/100/vm-100-disk-0.qcow2 -i --ro /mnt/vm_rescue

注記： -i（inspector）フラグによって正しいrootディレクトリ構造が自動マウントされ、--ro（読み取り専用）フラグによって元のデータの完全性が保護されます。これでrsyncやcpを使って安全にデータを退避できます。

バックアップ完了後は、ディレクトリをアンマウントします：

guestunmount /mnt/vm_rescue

4. virt-rescueによる対話型レスキューシェルへのアクセス

initramfsの再構築やGRUBブートローダーの再インストールが必要な場合は、対話型のレスキュー環境を起動します：

virt-rescue -a /var/lib/vz/images/100/vm-100-disk-0.qcow2

レスキューシェルが起動したら、chrootを実行して修復作業を行います：

# virt-rescueシェル内で以下のコマンドを実行:
mount /dev/sda1 /sysroot
chroot /sysroot
update-initramfs -u -k all
update-grub
exit

必ず守るべき2つの安全原則

  • 稼働中のVMに対してlibguestfsを実行しないこと： ハイパーバイザーとlibguestfsが同時に同一イメージファイルへ書き込みを行うと、パーティションテーブルが破損し、回復不能なデータ消失につながります。
  • 作業前にスナップショットを作成すること： CLIでの操作は非常に手軽ですが、重大な変更を加える前には、Proxmox上でスナップショットを作成するか、qcow2ファイルのバックアップコピーを必ず取得してください。
Share:
Tags: