Check KVM Guest Agent (Linux)

Available in VPC

To use the snapshot service in the KVM environment, KVM Guest Agent must be installed. If you have problems installing the agent or the service is not working properly, check and reinstall with Ncloud Tool Kit (NTK).

Run Linux NTK

To run NTK on a Linux server, follow these steps:

1. Check that the hypervisor hosting the VM is KVM.

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

2. Go to the path where the NTK file is located.

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

3. Unzip the NTK file.

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

4. Run NTK.

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

KVM Guest Agent version recommendations

It is recommended to install KVM Guest Agent version 6.2.0 or later on NAVER Cloud for the best use of storage products in the KVM environment. OSes currently requiring a KVM Guest Agent version upgrade are CentOS 7 and Ubuntu 20.04.
Since some OSes are provided without KVM Guest Agent installed, see Install new KVM Guest Agent.

To check the current KVM Guest Agent version, follow these steps:

• CentOS 7

  # If nothing appears as follows, see "Install new KVM Guest Agent."
  $ rpm -qa | grep qemu-guest-agent
  $
  or
  $ /usr/bin/qemug-ga -V
  -bash: /usr/bin/qemug-ga: No such file or directory
  
  # If 2.12.0 appears as follows, see "Reinstall KVM Guest Agent."
  $ rpm -qa | grep qemu-guest-agent
  qemu-guest-agent-2.12.0-3.el7.x86_64
  or
  $ /usr/bin/qemu-ga -V
  QEMU Guest Agent 2.12.0
  
  # If 6.2.0 appears as follows, reinstallation is not required as it is already upgraded.
  $ rpm -qa | grep qemu-guest-agent
  qemu-guest-agent-6.2.0-0.el7.x86_64
  or
  $ /usr/bin/qemu-ga -V
  QEMU Guest Agent 6.2.0    
  

• Ubuntu 20.04

  # If nothing appears as follows, see "Install new KVM Guest Agent."
  $ dpkg -l qemu-guest-agent
  dpkg-query: no packages found matching qemu-guest-agent
  or
  $ /usr/sbin/qemu-ga -V
  -bash: /usr/sbin/qemu-ga: No such file or directory
  
  
  # If 4.2.0 appears as follows, see "Reinstall 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
  or
  $ /usr/sbin/qemu-ga -V
  QEMU Guest Agent 4.2.1
  
  
  # If 6.2.0 appears as follows, reinstallation is not required as it is already upgraded.
  $ 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
  or
  $ /usr/sbin/qemu-ga -V
  QEMU Guest Agent 6.2.0
  

Install new KVM Guest Agent

If KVM Guest Agent is not present in the VM, install a new agent.

1. Check if KVM Guest Agent is installed in the VM.
   If not installed, proceed with the following steps. If already installed, see Check KVM Guest Agent status or Reinstall KVM Guest Agent.

   # If KVM Guest Agent is installed
   $ systemctl list-unit-files | grep "qemu-guest-agent"
   qemu-guest-agent.service                  enabled
   
   # If KVM Guest Agent is not installed
   $ systemctl list-unit-files | grep "qemu-guest-agent"
   $
   

2. Select (E) EXECUTE - << Run System Apps >>.
   
3. Select (K) KVM GUEST AGENT - KVM AGENT INSTALL >>.
   
4. Select Yes.
   
5. Click Enter to complete the reinstallation.

Check KVM Guest Agent status

Check the status of KVM Guest Agent service.

1. Select (E) EXECUTE - << Run System Apps >>.
   
2. Select (K) KVM GUEST AGENT - KVM AGENT INSTALL >>.
   
3. Select (S) KVM GUEST AGENT STATUS>>.
   
4. Verify that KVM Guest Agent service is in active (running) status.
   

Restart KVM Guest Agent

Restart the KVM Guest Agent process.

1. Select (E) EXECUTE - << Run System Apps >>.
   
2. Select (K) KVM GUEST AGENT - KVM AGENT INSTALL >>.
   
3. Select (T) RE-START KVM GUEST AGENT >>.
   
4. Verify that KVM Guest Agent service is in active (running) status.
   

Reinstall KVM Guest Agent

Delete the existing KVM Guest Agent and perform reinstallation.

1. Select (E) EXECUTE - << Run System Apps >>.
   
2. Select (K) KVM GUEST AGENT - KVM AGENT INSTALL >>.
   
3. Select (R) RE-INSTALL KVM GUEST AGENT >>.
   
4. Select Yes.
   
5. If the installation proceeds successfully, the reinstallation log will display as follows:
   • Stop existing Guest Agent.
   • Remove existing Guest Agent.
   • Update package information.
   • Reinstall Guest Agent.
     
6. Click Enter to complete the reinstallation.

When a virtio-serial device required for KVM Guest Agent startup is missing in OS

If the following message appears in NTK when starting KVM Guest Agent, the issue occurs because the required virtio-serial device does not exist in the OS.
When you can restart the VM, stop and start it again instead of rebooting.

KVM Guest Agent FAQs

Q. An issue occurs in KVM Guest Agent. Can I get technical support?

KVM Guest Agent used in NAVER Cloud Platform is not a guest agent created by NAVER Cloud Platform, but a package provided by an OS vendor.
NAVER Cloud Platform does not provide detailed technical support for Guest Agent. For specific settings or troubleshooting, see your OS provider’s official documentation (such as CentOS, Rocky Linux, and Ubuntu) or contact the support team.

• Is KVM GUEST AGENT a different agent from QEMU GUEST AGENT?

• If I don't install KVM GUEST AGENT (QEMU GUEST AGENT), what issues may occur?

• Is an inquiry or technical support available for KVM GUEST AGENT (QEMU GUEST AGENT)?

Q. On the MC console, I received the notification: "Guest Agent is not installed." What should I do?

The notification occurs when KVM Guest Agent is not installed or when the process is not running even if KVM Guest Agent is installed.
Separate technical support for KVM Guest Agent is not provided. You can check directly based on the following guides:

1. Check if KVM Guest Agent is running properly.
   For more information on the status check, see Check KVM Guest Agent status. If you are accessing a server, check if the status is active (running) using the following commands:

   [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. If Guest Agent is running properly, check the last time it communicated with KVM hypervisor.
   Check the last time the qemu-ga : info : guest-ping log was recorded.

   Note

   KVM hypervisor checks if KVM Guest Agent is running properly at 1-minute intervals.

   [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. If the last communication time is outdated, restart KVM Guest Agent to check if the time is updated.
   For more information on how to restart KVM Guest Agent, see Restart KVM Guest Agent. If you are accessing a server, you can restart and check the status using the following commands:

   [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. If the last communication time is not updated after the restart, check if a KVM response message is received properly at the virtio-serial port using the following way.

   Note

   Because the virtio-serial port is a device that is not shared and used by multiple processes at the same time, you must end the KVM Guest Agent process.

KVM hypervisor checks the operation status of KVM Guest Agent at 1-minute intervals. Therefore, you must wait at least 5 minutes and check if the commands are output properly.

:::

[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. If there is any separate output, this is a situation where an error has occurred on the virtio-serial port due to unknown causes, preventing communication with KVM hypervisor.
   When you can restart the VM, stop and start it instead of rebooting.

6. If the same phenomenon persists even after a restart (stop and start, not rebooting) or reinstallation, ignore the notification.
   The notification has no impact on OS operation. However, use the Agent feature only when you perform snapshot creation (My server image creation) or additional storage tasks.