KVM Guest Agent 점검(Linux)

Prev Next

VPC 환경에서 이용 가능합니다.

KVM 환경에서 스냅샷 서비스를 이용하기 위해서는 KVM Guest Agent가 설치되어야 합니다. 에이전트 설치에 문제가 있거나 서비스가 정상적으로 동작하지 않는 경우, NTK(Ncloud Tool Kit)를 사용하여 점검 및 재설치할 수 있습니다.

참고

이 기능은 KVM 환경의 Linux VM에 한하여 제공됩니다. NTK와 관련하여 자세한 내용은 Ncloud Tool Kit (Linux)을 참조해 주십시오.

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
    Bash
  2. NTK 파일이 위치한 경로로 이동해 주십시오.
    [root@kvm-rockylinux810 ~]# cd /usr/local/etc
    Bash
  3. NTK 파일 압축을 해제해 주십시오.
    [root@kvm-rockylinux810 ~]# tar zxvf ntk-kvm.tar.gz
    Bash
  4. NTK를 실행해 주십시오.
    [root@kvm-rockylinux810 ~]# cd ntk; ./ntk
    Bash

KVM 환경에서 스토리지 상품의 원활한 사용을 위해서 네이버클라우드에서는 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
    Bash
  • 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
    Bash

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"
$
    Bash
  2. (E) EXECUTE - << Run System Apps >> 를 선택해 주십시오.
    kvm-guest-agent-check-01
  3. (K) KVM GUEST AGENT - KVM AGENT INSTALL >> 을 선택해 주십시오.
    kvm-guest-agent-check-02
  4. Yes를 선택해 주십시오.
    kvm-guest-agent-check-03
  5. Enter를 클릭해 주십시오.

KVM Guest Agent 서비스의 상태를 점검합니다.

  1. (E) EXECUTE - << Run System Apps >> 를 선택해 주십시오.
    kvm-guest-agent-check-04
  2. (K) KVM GUEST AGENT - KVM AGENT INSTALL >> 을 선택해 주십시오.
    kvm-guest-agent-check-05
  3. (S) KVM GUEST AGENT STATUS >> 를 선택해 주십시오.
    kvm-guest-agent-check-06
  4. KVM Guest Agent 서비스가 active (running) 상태인지 확인해 주십시오.
    kvm-guest-agent-check-07

KVM Guest Agent 프로세스를 재시작합니다.

  1. (E) EXECUTE - << Run System Apps >> 를 선택해 주십시오.
    kvm-guest-agent-check-08
  2. (K) KVM GUEST AGENT - KVM AGENT INSTALL >> 을 선택해 주십시오.
    kvm-guest-agent-check-09
  3. **(T) RE-START KVM GUEST AGENT >> **를 선택해 주십시오.
    kvm-guest-agent-check-10
  4. KVM Guest Agent 서비스가 active (running) 상태인지 확인해 주십시오.
    kvm-guest-agent-check-11

기존에 설치된 KVM Guest Agent를 삭제하고 재설치를 진행합니다.

  1. (E) EXECUTE - << Run System Apps >> 를 선택해 주십시오.
    kvm-guest-agent-check-12
  2. (K) KVM GUEST AGENT - KVM AGENT INSTALL >> 을 선택해 주십시오.
    kvm-guest-agent-check-13
  3. (R) RE-INSTALL KVM GUEST AGENT >> 를 선택해 주십시오.
    kvm-guest-agent-check-14
  4. Yes 를 선택해 주십시오.
    kvm-guest-agent-check-15
  5. 정상적으로 설치가 진행되는 경우, 아래와 같이 재설치 수행 로그가 출력됩니다.
    • 기존에 설치된 Guest Agent 정지
    • 기존에 설지된 Geust Agent 삭제
    • 패키지 정보 업데이트
    • Guest Agent 재설치
      kvm-guest-agent-check-16
  6. Enter를 클릭해 주십시오.

KVM Guest Agent를 기동할 때 NTK에서 아래와 같은 메시지가 표시되면, OS 내에 필요한 virtio-serial 장치가 존재하지 않아 발생한 문제입니다.
VM을 재시작할 수 있는 시점에 리부팅이 아닌 정지 후 다시 시작해 주십시오.
kvm-guest-agent-check-17

네이버 클라우드 플랫폼에서 사용하는 KVM Guest Agent는 네이버 클라우드 플랫폼에서 자체적으로 생성한 Guest Agent가 아니며, OS 벤더에서 제공하는 패키지입니다.
네이버 클라우드 플랫폼에서 Guest Agent의 세부적인 기술 지원은 어려우며, 구체적인 설정이나 문제 해결에 대해서는 사용 중인 OS 제공 업체(CentOS, Rocky Linux, Ubuntu 등) 공식 문서나 지원팀에 문의를 해주시기 바랍니다.

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
    Bash
  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
    Bash
  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
    Bash
  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 ~]#
    Bash
  5. 별도의 출력이 없는 경우, virtio-serial 포트가 알 수 없는 원인에 의해서 오류가 발생하여 KVM 하이버파이저와의 통신이 이루어지지 않는 상황입니다.
    VM을 재시작할 수 있는 시점에 리부팅이 아닌 정지 후 시작으로 수행해 주십시오.
  6. 재시작(리부팅이 아닌 정지 후 시작) 또는 재설치 후에도 동일한 현상이라면, 해당 알람을 무시하고 사용 부탁드립니다.
    해당 알람이 OS 운영 상 문제는 없습니다. 다만, 스냅샷 생성(내서버 이미지 생성)과 추가 스토리지 작업 시에만 Agent 기능을 사용합니다.