인프라/가상화

Proxmox QEMU Guest Agent 설치와 점검: IP 조회·종료·백업 연동 이해

8월 18, 2026 · 다알이 · 6분 읽기

Proxmox VM이 정상적으로 부팅됐는데도 요약 화면에 IP가 보이지 않거나 qm agent 명령이 실패한다면, 먼저 QEMU Guest Agent의 설치 상태와 Proxmox 측 Agent 옵션을 나눠서 확인해야 합니다. 이 글은 Agent가 실제로 담당하는 기능, 템플릿에 넣는 방법, 정상 동작 확인, 자주 생기는 연결 실패를 하나의 주제로 정리합니다.

Guest Agent가 하는 일과 하지 않는 일

QEMU Guest Agent는 VM 안에서 실행되는 서비스입니다. Proxmox 호스트는 가상 직렬 채널을 통해 Agent와 통신해 게스트 내부 정보를 조회하거나 일부 작업을 요청합니다.

Proxmox 호스트와 가상머신 내부 QEMU Guest Agent 사이의 통신 구조
Proxmox의 Agent 옵션과 게스트 내부 서비스가 모두 준비되어야 통신할 수 있습니다.
기능 Agent의 역할 주의할 점
IP 주소 표시 게스트 인터페이스 정보를 Proxmox에 전달 Agent가 없어도 네트워크 자체가 동작하지 않는 것은 아님
정상 종료 게스트 내부 종료 명령을 요청할 수 있음 Agent가 없을 때는 ACPI 종료가 동작할 수도 있으므로 곧바로 강제 종료로 단정하면 안 됨
파일시스템 freeze 지원되는 백업 작업에서 freeze/thaw 요청 수행 VM의 Agent 백업 옵션과 게스트 파일시스템 지원 여부에 따라 달라짐
TRIM 클론 후 게스트 파일시스템에 TRIM 요청 스토리지와 게스트 파일시스템이 discard/TRIM을 지원해야 함
게스트 명령 실행 qm guest exec 같은 작업을 전달 Agent 채널을 강한 관리 권한으로 취급해야 함

Agent는 Cloud-Init을 대신하지 않습니다. Cloud-Init은 첫 부팅 설정을 적용하고, Guest Agent는 부팅한 게스트와 Proxmox 사이의 관리 통신을 담당합니다.

Agent가 없을 때 달라지는 점

$ qm agent 101 ping
QEMU guest agent is not running

이 메시지는 “VM이 고장 났다”는 뜻이 아니라 Proxmox가 Agent 채널을 통해 게스트와 통신하지 못한다는 뜻입니다. 다음 상황을 구분해야 합니다.

  • 게스트에 qemu-guest-agent 패키지가 설치되지 않음
  • 패키지는 있지만 서비스가 중지되어 있음
  • 게스트 서비스는 실행 중이지만 Proxmox VM 옵션에서 Agent가 비활성화됨
  • VM을 재부팅하지 않아 virtio-serial Agent 채널이 아직 연결되지 않음
  • 첫 부팅 패키지 설치가 진행 중이어서 Agent가 아직 시작되지 않음

템플릿과 기존 VM에 설치하기

Cloud-Init 템플릿에서 설치

템플릿의 사용자 정의 Cloud-Init 파일에 패키지와 서비스 시작 명령을 함께 넣습니다. packages만 적으면 설치는 되더라도 원하는 시점에 서비스가 활성화됐는지 확인하기 어려우므로 runcmd까지 명시합니다.

#cloud-config
packages:
  - qemu-guest-agent

runcmd:
  - [systemctl, enable, --now, qemu-guest-agent]

Proxmox 측 VM 옵션도 활성화합니다.

qm set 9000 --agent enabled=1,fstrim_cloned_disks=1

이 방법은 각 클론의 첫 부팅에서 패키지를 설치합니다. “이미지 안에 미리 설치된 템플릿”이 필요한 경우에는 템플릿을 변환하기 전에 VM을 한 번 부팅해 패키지 설치와 서비스 활성화를 끝내고, Cloud-Init 상태를 정리한 뒤 템플릿으로 변환해야 합니다.

이미 실행 중인 VM에 설치

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

Proxmox에서 Agent 옵션을 새로 켰다면 VM을 정상 종료한 뒤 다시 시작해 채널이 연결되는지 확인합니다. 단순 서비스 재시작만으로 해결되지 않는 경우가 있습니다.

Proxmox와 게스트 양쪽에서 확인

한쪽 상태만 보고 정상이라고 판단하지 않습니다.

# Proxmox 호스트
qm config 101 | grep '^agent:'
qm agent 101 ping
qm agent 101 network-get-interfaces
# VM 내부
systemctl is-enabled qemu-guest-agent
systemctl is-active qemu-guest-agent
systemctl status qemu-guest-agent --no-pager
ls -l /dev/virtio-ports/org.qemu.guest_agent.0

Proxmox의 agent: 설정, 게스트 서비스, virtio 포트가 모두 확인되어야 합니다.

Agent 응답과 Cloud-Init 완료 구분

qm agent 101 ping이 성공해도 사용자 생성, 패키지 설치, runcmd가 모두 끝났다고 볼 수는 없습니다. Agent가 먼저 실행되고 Cloud-Init의 final 단계가 계속 진행될 수 있기 때문입니다.

# VM 내부에서 첫 부팅 초기화가 끝날 때까지 대기
cloud-init status --wait

# 실패 여부와 단계별 상태 확인
cloud-init status --long
sudo journalctl -u cloud-final --no-pager

자동 프로비저닝의 완료 기준은 Agent 응답과 Cloud-Init 완료를 따로 확인해 정의하는 것이 안전합니다.

응답하지 않을 때 확인 순서

  1. qm status 101로 VM이 실제로 실행 중인지 확인합니다.
  2. qm config 101에서 Agent 옵션을 확인합니다.
  3. VM 콘솔이나 SSH로 들어가 systemctl status qemu-guest-agent를 확인합니다.
  4. /dev/virtio-ports/org.qemu.guest_agent.0 장치가 없으면 VM 옵션 적용과 재부팅 여부를 확인합니다.
  5. Cloud-Init으로 설치했다면 /var/log/cloud-init-output.log와 패키지 저장소 연결 상태를 확인합니다.

Agent 문제와 네트워크 문제를 한꺼번에 추측하지 않는 것이 중요합니다. Agent가 응답하지 않더라도 VM 콘솔에서 IP와 라우팅을 직접 확인할 수 있습니다.

템플릿 패키지는 어디까지 넣을까

분류 예시 권장 판단
관리 기능 qemu-guest-agent, cloud-guest-utils 템플릿 목적과 이미지 포함 여부를 확인해 결정
기본 진단 curl, dnsutils 초기 장애 대응에 필요한 최소 도구만 선택
개인 편의 vim, tree, zip 범용 템플릿보다 Ansible 역할에서 설치하는 편이 관리하기 쉬울 수 있음

패키지를 많이 넣을수록 첫 부팅은 길어지고 범용성은 떨어집니다. “없으면 VM 관리가 어려운 항목”과 “있으면 편한 항목”을 분리해 템플릿을 가볍게 유지합니다.

정리

QEMU Guest Agent는 Proxmox가 게스트 내부 상태를 확인하고 관리 요청을 전달하기 위한 통신 구성요소입니다. 설치 여부, 서비스 상태, Proxmox Agent 옵션을 각각 확인해야 하며, Agent 응답을 Cloud-Init 완료와 같은 의미로 사용해서는 안 됩니다.

Agent가 준비된 템플릿을 실제 VM으로 복제하고 이름·IP·첫 부팅 완료까지 확인하는 과정은 Proxmox VM 프로비저닝 자동화에서 정리합니다.

#cloud-init #homelab #proxmox #qemu-guest-agent