Debian ProxmoxのVMにQEMUゲストエージェントをインストールする

Debian VMが起動し、ネットワークが機能していますが、Proxmoxは「ゲストエージェントが実行されていません」または情報を表示しません。インターフェースでチェックしたQEMUゲストエージェントのオプションでは、ゲストとの通信を確立するには不十分です。

QEMUゲストエージェントは、Debianにデーモンをインストールし、VMとホストの間に管理チャンネルを作成します。両方の側を確認し、ネットワークを変更せずに、設定、サービス、またはデバイスの故障を特定します。

ProxmoxとDebian VM間のQEMUゲストエージェントによる通信 — ProxmoxホストとDebian VM間のQEMUゲストエージェントによる管理チャンネル。

QEMUゲストエージェントのProxmoxでの目的は何ですか？

VMはエージェントなしで通常通り機能することがあります。この場合、Proxmoxは仮想マシンを認識しますが、その内部で動作しているDebianシステムに関する同じレベルの情報を持っていません。

QEMUゲストエージェントは、ゲスト内でqemu-gaを実行します。デーモンはvirtio-serialデバイスを介してハイパーバイザーと通信します。通常、Debianでは/dev/virtio-ports/org.qemu.guest_agent.0に表示されます。これにより、ProxmoxはVMに情報を要求し、クリーンシャットダウンを行い、特定のバックアップやスナップショット中にファイルシステムのフリーズと解凍を調整できます。

Proxmoxの公式ドキュメントおよびQEMUのドキュメントでは、ホスト、仮想チャンネル、およびゲストデーモンのこのチェーンについて説明しています。エージェントはVirtIOネットワークドライバー、DHCP、ブリッジ、またはファイアウォールのいずれかを置き換えるものではありません。

Debianに触れる前にProxmox側でエージェントを有効にする

ハードウェア構成を変更する予定がある場合は、まずVMを停止してください。ProxmoxのインターフェースでDebian VMを開き、オプションに移動してQEMUゲストエージェントを編集し、そのオプションを有効にします。また、インターフェースに表示されるVMIDも確認してください：これはProxmoxホストでのみ使用されます。

Debianにパッケージをインストールする前に、Proxmox側でこのオプションを確認することをお勧めします。これにより、単にサービスが欠けているのか、仮想チャンネルが存在しないのかを区別できます。

Proxmoxが示すコマンドラインからの同等のコマンドは次のとおりです：

qm set VMID --agent 1

VMIDをVMの数値識別子に置き換えます。この操作はホスト側でオプションを有効にしますが、Debianサービスを起動せず、virtio-serialチャンネルの存在を証明するものではありません。

設定が追加されたばかりで、デバイスがゲストに表示されない場合は、VMをシャットダウンしてから再起動してください。ホットプラグがすべての構成に対して利用可能であるという前提を持たないでください。

Debianにおけるqemu-guest-agentのインストールと開始

Debian VMでターミナルを開きます。APTインデックスの更新を行うことで古いメタデータで作業することを避けられます：

sudo apt-get update
sudo apt-get install qemu-guest-agent

次に、すぐに再起動を行うのではなく、systemdユニットを確認します：

sudo systemctl status qemu-guest-agent --no-pager

既知のサービスとactive (running)の状態が得られるはずです。インストールされているが無効な場合は、開始し、Debianで自動起動を有効にします：

sudo systemctl start qemu-guest-agent
sudo systemctl enable qemu-guest-agent

これらの操作の後にsystemctl statusを再確認してください。エラーメッセージは、同じ試行を繰り返すよりもはるかに有用です。パッケージのインストールはネットワークカード、ブリッジ、またはIP設定には影響しません。

VM内のvirtio-serialチャンネルを確認する

アクティブなサービスは、VMが提示しないデバイスを待機しているかもしれません。QEMUゲストエージェントで使用されるパスを確認します：

ls -l /dev/virtio-ports/org.qemu.guest_agent.0

ファイルが存在する必要があります。欠落している場合、パッケージの再インストールでは解決しません。まず、ProxmoxのQEMUゲストエージェントオプションを確認し、その後VMのハードウェア設定を確認します。変更の後、一定のシャットダウンと再起動が必要です。

パスが存在するが、Proxmoxがまだ応答を受け取っていない場合は、サービスの最新のメッセージを確認します：

sudo journalctl -u qemu-guest-agent --no-pager -n 50

Debianの公式マニュアルqemu-gaでは、/etc/qemu/qemu-ga.confとvirtio-serialの輸送についても文書化されています。この手がかりは、デーモンまたはそのチャンネルに明確に関係するエラーに役立ちますが、IPアドレスの障害には適用されません。

Proxmoxホストからの応答をテストする

注意：Debianのactive (running)ステータスはサービスを確認するものであり、ホストからの応答を確認するものではありません。Proxmoxのバージョンに利用可能な構文を確認するには、ホスト側で次のプリフライトを開始します：

qm help agent

このヘルプは、インストールで期待される正確な形式を確認する必要があります。その後、このプリフライトで表示された形式qm agentのみを、関係するVMIDを使って実行します。ここで想定されるサブコマンドは示しません：これはツールのバージョンによって異なる可能性があり、考案されたコマンドはテストにはなりません。

期待される結果は、Proxmoxに表示されるVMと一致する情報の応答です。それをインターフェースのエージェントの状態と比較してください。可視のIPアドレスは役立ちますが、管理チャンネルの完全な機能を証明するには十分ではありません。

正しいレイヤーで障害を修正する

いくつかの症状が似ている場合、この表は、VM側でデバイスが欠けている際にDebianを再インストールすることを避けます。

症状	疑わしいレイヤー	コマンドまたは確認	最小限のアクション
オプションが無効	Proxmox	VMのオプション	QEMUゲストエージェントを有効にし、チャンネルが現れない場合はVMを再起動します。
不明なユニット	Debian	`systemctl status qemu-guest-agent`	APTでパッケージをインストールし、サービスの状態を再確認します。
エラーのあるサービス	Debian	`systemctl status`および`journalctl`	新しい再起動の前に最初のエラーを確認してください。
デバイスが欠落	virtio-serial	`ls -l /dev/virtio-ports/org.qemu.guest_agent.0`	Proxmox側でオプションまたは仮想ハードウェアを修正し、その後シャットダウンと再起動を行います。

エージェントがホストから応答しているがVMにネットワークがない場合、ここでのQEMUゲストエージェントの診断を中止してください。接続性はブリッジ、仮想インターフェース、またはDebianの問題です。ポストProxmoxのVMのネットワークを復元する、ブリッジからゲストへでは、これらの問題を混同せずにこのチェーンをカバーしています。

ホスト上のブリッジの故障を示す制御が表示された場合は、代わりにサーバーへのアクセスを失うことなくProxmoxブリッジを作成するを使用してください。検出されていないエージェントを修正するためにブリッジを変更しないでください：両方のレイヤーが通信しますが、同じ役割を果たしているわけではありません。

過剰な約束をせずにシャットダウンとバックアップを検証する

ホストからの有効な応答により、期待される利益を確認できます。Proxmoxからのゲストシャットダウンを制御し、その後、ホストのタスクとログを確認します。VMは強制終了ではなく、クリーンにシャットダウンする必要があります。

ファイルシステムのフリーズを利用するバックアップまたはスナップショットに対しては、タスクメッセージも確認してください。フリーズと解凍はファイルシステムの整合性を向上させますが、すべてのデータベースのアプリケーション整合性を保証するものではありません：それぞれのデータベースは自らのバックアップ手続きに従うべきです。

インストールが完了したと見なす前に、次の4つの証拠を集めてください：

Proxmox側でQEMUゲストエージェントのオプションが有効になっている；
Debianにパッケージとサービスが存在する；
期待されるパスにvirtio-serialデバイスが存在する；
ホストがqm help agentプリフライト後に応答を受け取り、適切なバージョンに応じたテストを行う。

これらの4つの確認が一致した際にチャンネルが検証されます。応答があれば、ネットワークには手を加えないでください：ブリッジを修復するためのエージェントが不足しているわけではありません。