KVM Guest Agent の点検(Linux)

VPC環境で利用できます。

KVM環境でスナップショットサービスを利用するためには、KVM Guest Agentをインストールする必要があります。エージェントインストールに問題があるか、サービスが正常に動作しない場合、NTK (Ncloud Tool Kit)を使用して点検および再インストールできます。

Linux NTKの実行

Linuxサーバで NTKを実行する方法は、次の通りです。

1. VMがホスティングされているハイパーバイザが KVMであるか確認します。

   # 方法1
   [root@kvm-rockylinux810 ~]# dmesg | grep "Hypervisor detected" | awk -F': ' '{print $2}'
   KVM
   
   # 方法2
   [root@kvm-rockylinux810 ~]# virt-what
   kvm
   

2. NTKファイルが位置するパスに移動します。

   [root@kvm-rockylinux810 ~]# cd /usr/local/etc
   

3. NTKファイルを解凍します。

   [root@kvm-rockylinux810 ~]# tar zxvf ntk-kvm.tar.gz
   

4. NTKを実行します。

   [root@kvm-rockylinux810 ~]# cd ntk; ./ntk
   

KVM Guest Agentバージョンの推奨事項

KVM環境でストレージサービスを円滑に使用するために、NAVERクラウドでは KVM Guest Agentのバージョンを6.2.0以上でインストールすることを推奨します。KVM Guest Agentのバージョンアップが必要な OSは、現在 CentOS 7と Ubuntu 20.04です。
KVM Guest Agentがインストールされずに提供された一部の OSがあるため、新規 KVM Guest Agentのインストールでご確認ください。

以下のように現在インストールされている KVM Guest Agentのバージョンを確認できます。

• CentOS 7

  # 以下のように何も出力されない場合は、「新規 KVM Guest Agentのインストール」をご参照ください。
  $ rpm -qa | grep qemu-guest-agent
  $
  または
  $ /usr/bin/qemug-ga -V
  -bash: /usr/bin/qemug-ga: No such file or directory
  
  # 以下のように2.12.0が出力された場合は、「KVM Guest Agentの再インストール」をご参照ください。
  $ rpm -qa | grep qemu-guest-agent
  qemu-guest-agent-2.12.0-3.el7.x86_64
  または
  $ /usr/bin/qemu-ga -V
  QEMU Guest Agent 2.12.0
  
  # 以下のように6.2.0が出力された場合は、既にアップグレードされた状態であるため再インストールは必要ありません。
  $ rpm -qa | grep qemu-guest-agent
  qemu-guest-agent-6.2.0-0.el7.x86_64
  または
  $ /usr/bin/qemu-ga -V
  QEMU Guest Agent 6.2.0    
  

• Ubuntu 20.04

  # 以下のように何も出力されない場合は、「新規 KVM Guest Agentのインストール」をご参照ください。
  $ dpkg -l qemu-guest-agent
  dpkg-query: no packages found matching qemu-guest-agent
  または
  $ /usr/sbin/qemu-ga -V
  -bash: /usr/sbin/qemu-ga: No such file or directory
  
  
  # 以下のように4.2.0が出力された場合は、「KVM Guest Agentの再インストール」をご参照ください。
  $ dpkg -l qemu-guest-agent
  ||/ Name             Version           Architecture Description
  +++-================-=================-============-=================================
  ii  qemu-guest-agent 1:4.2-3ubuntu6.30 amd64        Guest-side qemu-system agent
  または
  $ /usr/sbin/qemu-ga -V
  QEMU Guest Agent 4.2.1
  
  
  # 以下のように6.2.0が出力された場合は、既にアップグレードされた状態であるため再インストールは必要ありません。
  $ dpkg -l qemu-guest-agent
  ||/ Name             Version      Architecture Description
  +++-================-============-============-==================================================
  ii  qemu-guest-agent 6.2-ubuntu20 amd64        Guest-side qemu-system agent v6.2 for Ubuntu 20.04
  または
  $ /usr/sbin/qemu-ga -V
  QEMU Guest Agent 6.2.0
  

新規 KVM Guest Agentのインストール

KVM Guest Agentが VM内に存在しない場合、新しい Agentをインストールします。

1. VMに KVM Guest Agentインストール有無を確認します。
   インストールされていない場合は次のステップを行い、インストールされている場合は KVM Guest Agentステータス確認または KVM Guest Agentの再インストールガイドをご参照ください。

   # kvm guest agentインストールされた場合
   $ systemctl list-unit-files | grep "qemu-guest-agent"
   qemu-guest-agent.service                  enabled
   
   # kvm guest agentインストールされていない場合
   $ systemctl list-unit-files | grep "qemu-guest-agent"
   $
   

2. (E) EXECUTE - << Run System Apps >> を選択します。
   
3. (K) KVM GUEST AGENT - KVM AGENT INSTALL >> を選択します。
   
4. Yes を選択します。
   
5. Enter を押して再インストールを終了します。

KVM Guest Agentのステータスチェック

KVM Guest Agentサービスのステータスをチェックします。

1. (E) EXECUTE - << Run System Apps >> を選択します。
   
2. (K) KVM GUEST AGENT - KVM AGENT INSTALL >> を選択します。
   
3. (S) KVM GUEST AGENT STATUS>> を選択します。
   
4. KVM Guest Agentサービスが active(running) ステータスであるか確認します。
   

KVM Guest Agentの再起動

KVM Guest Agentプロセスを再起動します。

1. (E) EXECUTE - << Run System Apps >> を選択します。
   
2. (K) KVM GUEST AGENT - KVM AGENT INSTALL >> を選択します。
   
3. (T) RE-START KVM GUEST AGENT >> を選択します。
   
4. KVM Guest Agentサービスが active(running) ステータスであるか確認します。
   

KVM Guest Agentの再インストール

既存のインストールされた KVM Guest Agentを削除して再インストールします。

1. (E) EXECUTE - << Run System Apps >> を選択します。
   
2. (K) KVM GUEST AGENT - KVM AGENT INSTALL >> を選択します。
   
3. (R) RE-INSTALL KVM GUEST AGENT >> を選択します。
   
4. Yes を選択します。
   
5. インストールが正常に実行される場合、以下のように再インストール実行ログが出力されます。
   • 既存のインストールされた Guest Agentを停止
   • 既存のインストールされた Guest Agentを削除
   • パッケージ情報のアップデート
   • Guest Agent 再インストール
     
6. Enter を押して再インストールを終了します。

KVM Guest Agentの起動時、OS内に必要な virtio-serialデバイスがない場合

KVM Guest Agentを起動する際に、NTKで以下のようなメッセージが表示される場合、OS内に必要な virtio-serialデバイスが存在しないために発生した問題です。
VMを再起動できるタイミングに、再起動ではなく停止した後に再起動します。

KVM Guest Agentに関するよくあるご質問

Q. KVM Guest Agentに問題があります。テクニカルサポートは提供しますか?

NAVERクラウドプラットフォームで使用する KVM Guest Agentは、NAVERクラウドプラットフォームが独自に作成した Guest Agentではなく、OSベンダーが提供するパッケージです。
NAVERクラウドプラットフォームでは Guest Agentに関する詳細なテクニカルサポートは困難です。具体的な設定や問題解決については、ご利用中の OS提供会社(CentOS、Rocky Linux、Ubuntuなど)の公式ドキュメントまたはサポートチームにお問い合わせください。

• KVM GUEST AGENTと QEMU GUEST AGENTは他のエージェントですか?

• KVM GUEST AGENT(QEMU GUEST AGENT)をインストールしない場合、どのような問題がありますか?

• KVM GUEST AGENT(QEMU GUEST AGENT)に関するお問い合わせやテクニカルサポートは可能ですか?

Q. MCコンソールで Guest Agentがインストールされていませんという通知が発生しました。どうすればいいですか?

KVM Guest Agentがインストールされていないか、インストールされていてもプロセスが実行中でない場合に発生するアラームです。
KVM Guest Agentに関しては別途のテクニカルサポートを提供しません。以下のガイドに従って、お客様ご自身でチェックできます。

1. KVM Guest Agentが正常に実行中であるか確認します。
   ヘルスチェックは、KVM Guest Agentのヘルスチェック項目をご参照ください。サーバに接続されている状態の場合、以下のコマンドで active(running) ステータスであるか確認できます。

   [root@kvm-rockylinux810 ~]# systemctl status qemu-guest-agent.service
   ● qemu-guest-agent.service - QEMU Guest Agent
      Loaded: loaded (/usr/lib/systemd/system/qemu-guest-agent.service; enabled; vendor preset: enabled)
      Active: active (running) since Fri 2025-06-13 18:27:04 KST; 4min 12s ago
    Main PID: 616 (qemu-ga)
       Tasks: 2 (limit: 23226)
      Memory: 1.8M
      CGroup: /system.slice/qemu-guest-agent.service
              └─616 /usr/bin/qemu-ga --method=virtio-serial --path=/dev/virtio-ports/org.qemu.guest_agent.0 --blacklist=guest-file-open,guest-file-close,guest-file-read,guest-file-write,guest-file>
   
   Jun 13 18:27:04 kvm-rockylinux810 systemd[1]: Started QEMU Guest Agent.
   Jun 13 18:28:00 kvm-rockylinux810 qemu-ga[616]: info: guest-ping called
   Jun 13 18:29:00 kvm-rockylinux810 qemu-ga[616]: info: guest-ping called
   Jun 13 18:30:00 kvm-rockylinux810 qemu-ga[616]: info: guest-ping called
   Jun 13 18:31:00 kvm-rockylinux810 qemu-ga[616]: info: guest-ping called
   

2. Guest Agentが正常に起動中の場合、KVMハイパーバイザとの最後の通信時間を確認します。
   最後の qemu-ga : info : guest-ping calledログが記録された時間を確認します。

   参考

   KVMハイパーバイザでは、1分間隔で KVM Guest Agentが正常に動作するか確認しています。

   [root@kvm-rockylinux810 ~]# systemctl status qemu-guest-agent.service
   ● qemu-guest-agent.service - QEMU Guest Agent
      Loaded: loaded (/usr/lib/systemd/system/qemu-guest-agent.service; enabled; vendor preset: enabled)
      Active: active (running) since Fri 2025-06-13 18:27:04 KST; 4min 12s ago
    Main PID: 616 (qemu-ga)
       Tasks: 2 (limit: 23226)
      Memory: 1.8M
      CGroup: /system.slice/qemu-guest-agent.service
              └─616 /usr/bin/qemu-ga --method=virtio-serial --path=/dev/virtio-ports/org.qemu.guest_agent.0 --blacklist=guest-file-open,guest-file-close,guest-file-read,guest-file-write,guest-file>
   
   Jun 13 18:27:04 kvm-rockylinux810 systemd[1]: Started QEMU Guest Agent.
   Jun 13 18:28:00 kvm-rockylinux810 qemu-ga[616]: info: guest-ping called
   Jun 13 18:29:00 kvm-rockylinux810 qemu-ga[616]: info: guest-ping called
   Jun 13 18:30:00 kvm-rockylinux810 qemu-ga[616]: info: guest-ping called
   Jun 13 18:31:00 kvm-rockylinux810 qemu-ga[616]: info: guest-ping called    
   

3. 最後の通信時間が最近でない場合は、KVM Guest Agentを再起動して時間がアップデートされるか確認します。
   KVM Guest Agentの再起動方法は、KVM Guest Agentの再起動項目をご参照ください。サーバに接続されているステータスであれば、以下のコマンドで再起動およびステータス確認できます。

   [root@kvm-rockylinux810 ~]# systemctl restart qemu-guest-agent.service
   [root@kvm-rockylinux810 ~]# systemctl status qemu-guest-agent.service
   ● qemu-guest-agent.service - QEMU Guest Agent
      Loaded: loaded (/usr/lib/systemd/system/qemu-guest-agent.service; enabled; vendor preset: enabled)
      Active: active (running) since Fri 2025-06-13 18:39:56 KST; 5s ago
    Main PID: 7091 (qemu-ga)
       Tasks: 2 (limit: 23226)
      Memory: 1.1M
      CGroup: /system.slice/qemu-guest-agent.service
              └─7091 /usr/bin/qemu-ga --method=virtio-serial --path=/dev/virtio-ports/org.qemu.guest_agent.0 --blacklist=guest-file-open,guest-file-close,guest-file-read,guest-file-write,guest-fil>
   
   Jun 13 18:39:56 kvm-rockylinux810 systemd[1]: qemu-guest-agent.service: Succeeded.
   Jun 13 18:39:56 kvm-rockylinux810 systemd[1]: Stopped QEMU Guest Agent.
   Jun 13 18:39:56 kvm-rockylinux810 systemd[1]: Started QEMU Guest Agent.
   Jun 13 18:40:00 kvm-rockylinux810 qemu-ga[7091]: info: guest-ping called
   

4. 再起動後も最後の通信時間がアップデートされない場合、以下の方法で Virtio-serialポートで KVMレスポンスメッセージが正常に受信されるか確認します。

   参考

   virtio-serialポートは、複数のプロセスが同時に共有して使用できないデバイスであるため、KVM Guest Agentプロセスを終了する必要があります。

KVMハイパーバイザでは、1分間隔で KVM Guest Agentの動作ステータスをチェックします。したがって、少なくとも5分以上待機してからコマンドが正常に出力されるか確認します。

:::

[root@kvm-rockylinux810 ~]# systemctl stop qemu-guest-agent
[root@kvm-rockylinux810 ~]# timeout 300 tail -f /dev/virtio-ports/org.qemu.guest_agent.0
{"execute":"guest-ping"}{"execute":"guest-ping"}{"execute":"guest-ping"}{"execute":"guest-ping"}{"execute":"guest-ping"}{"execute":"guest-ping"}{"execute":"guest-ping"}{"execute":"guest-ping"}{"execute":"guest-ping"}{"execute":"guest-ping"}{"execute":"guest-ping"}{"execute":"guest-ping"}{"execute":"guest-ping"}{"execute":"guest-ping"}{"execute":"guest-ping"}[root@kvm-rockylinux810 ~]#

5. 別途の出力がない場合、virtio-serialポートが不明な原因によりエラーが発生し、KVMハイパーバイザとの通信が行われない状況です。
   VMを再起動できる時点で、再起動ではなく停止後に起動を実行します。

6. 再起動(再起動ではなく停止後に起動)または再インストール後も同じ現象が発生する場合は、当該アラームを無視して使用してください。
   当該アラームは OS運用上の問題はありません。ただし、スナップショットの作成(マイサーバイメージの作成)と追加ストレージのタスク時のみ Agent機能を使用します。