QEMU Guest Agent：Linux/Windowsへのインストールと設定 — 一貫性のあるスナップショットとVM監視 – ITFROMZERO

去年の初め、ぐっすり眠っていたところ、夜中の2時に警告通知が届いた。本番VMのスナップショットが失敗したというのだ。ストレージの問題でも、KVMの問題でもなかった。PostgreSQLがWALログを書き込んでいるまさにそのタイミングでスナップショットが実行され、リストア時にデータが破損していた。そのVMにはお客様の数十GBのデータが入っていた。前日のバックアップからリストアして差分を埋め直すのに、4時間近くかかった。

そのインシデントをきっかけに、QEMU Guest Agentについて真剣に調べることにした。それまでは「VMが動けば十分」と思って放置していたものだ。実際には、これがないとどんなバックアップ戦略にも潜在的な穴があることがわかった。

Table of Contents

QEMU Guest Agentとは何か、なぜ重要なのか？

QEMU Guest Agent（qemu-ga）はVM内で動作するデーモンで、仮想チャンネル経由でハイパーバイザー（KVM/QEMU）と通信する。ネットワーク経由ではない。このチャンネルはvirtio-serialまたはISA serialを使用するため、VMがネットワーク接続を完全に失った場合でも動作し続ける。

qemu-gaが解決する課題は3つある。他のコンポーネントでは代替できないものだ：

Quiesced snapshot（整合性スナップショット）：Agentがスナップショット実行前にディスクバッファをフラッシュし、ファイルシステムをフリーズする。データベースにとってこれが核心だ。PostgreSQL、MySQL、あるいはWALログを継続的に書き込んでいるアプリケーションは、ディスクがキャプチャされる前にすべてフラッシュされる。
SSHなしでのゲスト情報取得：実際のIP、ホスト名、OSバージョン、メモリ使用量を、VMのネットワークスタックに依存せず仮想チャンネル経由で直接取得できる。
ホストからのゲスト制御：ゲスト内でのコマンド実行、時刻同期、グレースフルシャットダウン — コンソールを開いたりSSH接続したりせずに、ホストからすべて操作できる。

筆者はProxmox VEで12台のVMとコンテナを管理するホームラボを運用している。あの夜中の2時の教訓：データベースやステートフルなアプリケーションを実行するVMには、例外なくqemu-gaをインストールすること。

LinuxへのQEMU Guest Agentのインストール

手順は多くない。ほとんどのディストリビューションにパッケージが用意されているので、3コマンドで完了する。

Ubuntu / Debian

sudo apt update
sudo apt install -y qemu-guest-agent
sudo systemctl enable --now qemu-guest-agent

CentOS / RHEL / Rocky Linux / AlmaLinux

sudo dnf install -y qemu-guest-agent
sudo systemctl enable --now qemu-guest-agent

Arch Linux

sudo pacman -S qemu-guest-agent
sudo systemctl enable --now qemu-guest-agent

インストール後、サービスを確認する：

systemctl status qemu-guest-agent

active (running)と表示されれば正常だ。手動でstartしてもinactiveの場合は、99%の確率でVMにvirtio-serialデバイスが存在しない。次のセクションで対処法を説明する。

KVM/libvirtのホスト側の設定

まず、VMにchannelデバイスが設定されているか確認する：

virsh dumpxml ten-vm | grep -A5 "channel"

出力が空の場合は、XMLを編集してchannelを追加する必要がある：

virsh edit ten-vm

<devices>タグ内に以下を追加する：

<channel type='unix'>
  <target type='virtio' name='org.qemu.guest_agent.0'/>
</channel>

その後、VMを完全にシャットダウンする必要がある。再起動ではなく、電源オフだ。libvirtは新しいvirtioデバイスを初期化するためにコールドブートが必要となる：

virsh shutdown ten-vm
virsh start ten-vm

ホストからの接続テスト

# ゲストエージェントにpingを送信
virsh qemu-agent-command ten-vm '{"execute": "guest-ping"}'

# VMのOS情報を取得
virsh qemu-agent-command ten-vm '{"execute": "guest-get-osinfo"}'

# SSHなしでIPリストを取得
virsh domifaddr ten-vm --source agent

virsh domifaddr --source agentは、VMが起動直後でIPがわからない場合に特に便利だ。コンソールを開いて目視確認したり、SSHが準備できるまで待ったりする必要がない。

WindowsへのQEMU Guest Agentのインストール

WindowsはVirtIOドライバが必要なため、Linuxより手順が多い。KVM上でWindows VMを構築してこのステップを省略してしまう人が多く、パフォーマンスが低下したりバックアップが失敗したりする原因の多くがVirtIOの欠如だ。なお、VirtIOドライバはファイル共有のパフォーマンス最適化にも活用できるため、一度ISOを入手しておけば複数の用途で役立つ。

ステップ1：VirtIO Drivers ISOのダウンロード

# ホスト上でFedoraプロジェクトからISOをダウンロード（公式ソース、Red Hatメンテナンス）
wget https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/stable-virtio/virtio-win.iso

ステップ2：ISOをアタッチしてGuest Agentをインストール

VMにISOをアタッチする（virt-manager：Add Hardware → CDROM → ISOファイルを選択）。Windows VM内でCDROMドライブを開き、インストーラーを実行する：

D:\guest-agent\qemu-ga-x86_64.msi

インストール後、services.mscを開いてQEMU Guest Agentを探す。Running状態でStartup typeがAutomaticになっていれば正常だ。

ステップ3：VirtIO Serialドライバのインストール

インストール後にホストがAgentを検出できない場合、VirtIO Serialコントローラの欠如が最も一般的な原因だ。ISOからインストールする：

# Windows 10/11
D:\vioserial\w10\amd64\vioser.inf

# Windows Server 2022
D:\vioserial\2k22\amd64\vioser.inf

.infファイルを右クリック → Install → Windowsを再起動する。

ProxmoxでのQEMU Agentの有効化

ProxmoxにはUIが用意されているため、XMLの手動編集は不要だ。

Web UI経由：VMを選択 → Options → QEMU Guest Agentをダブルクリック → Enabledにチェック → Freeze/thaw guest filesystems on backup for consistent snapshotsも有効にする。

ProxmoxホストのCLI経由：

# VM ID 101のQEMU Agentを有効化
qm set 101 --agent enabled=1,fstrim_cloned_disks=1

# 設定を確認
qm config 101 | grep agent

一貫性のあるスナップショットの動作確認

# vzdump（Proxmox）でバックアップ
vzdump 101 --mode snapshot --compress zstd

バックアップのログで以下の行を確認する：

INFO: sending freeze command to agent
INFO: agent started fsfreeze
INFO: creating snapshot ...
INFO: sending thaw command to agent

この4行がすべて揃っていれば、Agentが正しく機能している証拠だ。スナップショット前にファイルシステムがフリーズされ、完了後に解除される。

よくあるエラーのトラブルシューティング

“QEMU guest agent is not running”

ゲスト内からホスト外に向かって、以下の順序で確認する：

ゲスト内のサービス：systemctl status qemu-guest-agent
VM設定内のchannelデバイス：virsh dumpxml vm-name | grep channel
ホスト上のソケットファイル：ls /var/lib/libvirt/qemu/channel/target/

channelはあるがagentが接続しない

# ホスト上のソケットを確認
ls -la /var/lib/libvirt/qemu/channel/target/domain-*/org.qemu.guest_agent.0

# Linuxゲスト内でデバイスを確認
ls /dev/virtio-ports/
# 以下が表示されるはず: org.qemu.guest_agent.0

XMLにchannelを追加済みなのにゲスト内にデバイスが現れない場合、コールドブートが唯一の解決策だ。完全にシャットダウンしてから起動し直す必要がある。再起動では不十分だ。

Windows：インストール済みだがホストが認識しない

Device Manager → System Devicesを開き、黄色の警告アイコンを探す。ほぼ確実にVirtIO Serialドライバの欠如が原因だ。上記の手順に従ってISOからvioserialをインストールし、再起動すれば解決する。

まとめ

あの夜中の2時以来、筆者には固定ルールがある。作成するVMには必ず本番投入前にQEMU Guest Agentをインストールすること。オプションではなく必須要件だ。特にデータベース、メッセージキュー、ディスクへの継続的な書き込みが発生するアプリケーションを実行するVMには欠かせない。

Agentなしのスナップショットは、走っている人を撮影するようなものだ。ブレてしまい、信頼できない。Agentありのスナップショットは、ちょうどよいタイミングでファイルシステムがフリーズされた状態だ。データの一貫性が確保され、クリーンにリストアでき、夜中の2時にサプライズが起きることもない。

Linuxなら3コマンドで完了する。WindowsはVirtIOのインストールに追加の手順が必要だが、10分もかからない。小さな投資だが、実際にリストアが必要な場面に直面して初めて、その価値の大きさを実感するはずだ。