11. Proxmox cli로 관리하기

Proxmox VE CLI 실전 사용법

Proxmox VE는 Web UI만으로도 많은 작업을 할 수 있습니다. 하지만 실제 운영에서는 CLI가 필요합니다.

CLI는 Web UI 장애 대응, VM·컨테이너 일괄 점검, 반복 작업, 백업·복구, 클러스터 분석, API 탐색, 폐쇄망 운영, 자동화에 특히 유용합니다.

Linux System Commands
├── ip, ss, systemctl, journalctl
├── lsblk, df, findmnt
├── zpool, zfs
├── apt, ssh
└── chronyc

Proxmox VE Commands
├── pveversion
├── qm
├── pct
├── pvesh
├── pveam
├── pvesm
├── pvecm
├── vzdump
├── qmrestore
├── pvenode
└── pve-firewall

운영 명령은 root 권한 또는 적절한 Proxmox 권한이 필요할 수 있습니다. 삭제·복구·스토리지·클러스터 변경 전에는 VM ID, CTID, 노드 이름, 스토리지 이름, 백업·롤백 경로를 반드시 확인합니다.

CLI 접근과 도움말

Web UI에서는 Node → Shell로 접속할 수 있고, SSH로도 접근할 수 있습니다.

ssh infraadmin@pve-01.example.internal

운영 환경에서는 root 직접 SSH보다 개인 계정, SSH Key, VPN, Bastion, 접근 제어 정책을 적용합니다.

도움말과 man page를 먼저 확인합니다.

qm help
qm help create
pct help
pvesm help

man qm
man pct
man pvesm
man pvecm
man vzdump

기본 상태 점검

가장 먼저 Proxmox VE 버전, 노드 상태, 스토리지, VM·컨테이너 상태를 확인합니다.

# Proxmox VE 구성 요소와 커널
pveversion -v
uname -r

# 호스트와 자원 상태
hostnamectl
hostname -f
uptime
free -h
lsblk
df -h

# 네트워크와 시간
ip -br addr
ip route
timedatectl status

# Proxmox 리소스
pvesm status
qm list
pct list

# 서비스 상태
systemctl --no-pager --full status \
  pveproxy \
  pvedaemon \
  pvestatd \
  pve-cluster

# 부팅 후 오류 로그
journalctl -p err..alert -b

pvesh로 Proxmox REST API 기반 상태를 확인할 수도 있습니다.

pvesh get /nodes/$(hostname)/status \
  --output-format json-pretty

pvesh get /nodes

VM 관리: qm

qm은 QEMU/KVM VM 관리 명령입니다.

# 목록, 상태, 설정
qm list
qm status 401
qm config 401

# 시작·정상 종료·재부팅
qm start 401
qm shutdown 401
qm reboot 401

# 긴급 강제 종료·리셋
qm stop 401
qm reset 401

명령	의미	사용 기준
`qm start`	VM 시작	정상 기동
`qm shutdown`	ACPI 또는 Guest Agent 기반 정상 종료 요청	일반 종료
`qm reboot`	정상 재부팅 요청	일반 재부팅
`qm stop`	강제 종료	Guest OS가 멈춘 긴급 상황
`qm reset`	강제 리셋	콘솔·OS가 응답하지 않는 경우

qm stop과 qm reset은 파일시스템 손상과 DB 복구를 유발할 수 있으므로 정상 종료가 불가능한 경우에만 사용합니다.

VM 설정 확인과 변경

# CPU·메모리·디스크·NIC 설정
qm config 401 | grep -E '^(sockets|cores|cpu|memory|balloon|numa|hotplug)'
qm config 401 | grep -E '^(scsi|sata|virtio|ide)'
qm config 401 | grep '^net'

# CPU, 메모리, 자동 시작
qm set 401 --cores 8
qm set 401 --memory 16384
qm set 401 --onboot 1

# QEMU Guest Agent
qm set 401 --agent enabled=1

운영 중 CPU·메모리·NIC·디스크를 변경할 때는 Hotplug 설정과 Guest OS 지원 여부를 먼저 확인합니다.

qm set 401 --hotplug network,disk,usb,cpu,memory

디스크 관리

# 새 데이터 디스크 추가
qm set 401 \
  --scsi1 local-lvm:100,cache=none,discard=on,iothread=1,ssd=1

# 기존 디스크 50GB 확장
qm resize 401 scsi0 +50G

# 디스크를 다른 스토리지로 이동
qm move_disk 401 scsi1 zfs-vm

qm resize는 virtual disk만 확장합니다. Guest OS에서 파티션, LVM, 파일시스템까지 추가 확장해야 실제 사용 가능 용량이 늘어납니다.

Virtual Disk Resize
        │
Guest Partition Resize
        │
LVM PV / LV Resize
        │
Filesystem Resize

디스크 제거는 바로 삭제하지 않습니다.

1. Guest OS에서 애플리케이션·마운트·LVM 사용 해제
2. 데이터 백업과 이전 확인
3. Proxmox에서 디스크 Detach
4. orphaned volume 확인
5. 실제 storage volume 삭제 여부 결정

qm destroy와 --destroy-unreferenced-disks 1은 매우 위험합니다. orphan volume까지 삭제할 수 있으므로 운영 환경에서는 대상 volume을 qm config와 pvesm list로 확인한 뒤에만 사용합니다.

스냅샷과 템플릿

# 스냅샷 생성·조회·롤백·삭제
qm snapshot 401 before-upgrade --description "Before application upgrade"
qm listsnapshot 401
qm rollback 401 before-upgrade
qm delsnapshot 401 before-upgrade

# 템플릿 전환
qm template 801

# Full Clone
qm clone 801 401 \
  --name k8s-cp-prod-01 \
  --full 1 \
  --storage local-lvm

# Linked Clone 지원 스토리지에서만 사용
qm clone 801 701 \
  --name k8s-test-01 \
  --full 0

스냅샷은 단기 rollback 수단이며 독립 백업을 대체하지 않습니다. Linked Clone은 Base Template 의존성이 있으므로 스토리지·백업·마이그레이션·템플릿 폐기 정책을 검증한 뒤 사용합니다.

Guest Agent

qm agent 401 ping
qm guest cmd 401 network-get-interfaces
qm guest cmd 401 get-osinfo

Guest Agent는 Guest IP와 OS 정보 조회, 정상 종료, backup freeze/thaw 같은 기능에 도움을 줍니다.

컨테이너 관리: pct와 pveam

pct는 LXC 컨테이너, pveam은 컨테이너 템플릿 관리에 사용합니다.

# 컨테이너 상태
pct list
pct status 201
pct config 201

# 시작·정상 종료·강제 종료·재부팅
pct start 201
pct shutdown 201
pct stop 201
pct reboot 201

# 컨테이너 접속과 명령 실행
pct enter 201
pct exec 201 -- hostnamectl
pct exec 201 -- ip -br addr

# 리소스 변경
pct set 201 --cores 4
pct set 201 --memory 4096
pct resize 201 rootfs +10G

온라인 환경에서는 pveam으로 LXC 템플릿을 조회·다운로드합니다.

pveam update
pveam available | grep -i debian
pveam list local

pveam download local \
  debian-12-standard_<version>_amd64.tar.zst

폐쇄망에서는 pveam update 대신 외부에서 검증·승인한 템플릿을 내부 vztmpl 스토리지에 반입합니다.

스토리지 관리: pvesm

# 스토리지 상태
pvesm status

# 스토리지 콘텐츠
pvesm list local
pvesm list local-lvm

# 특정 VM volume 확인
pvesm list local-lvm | grep 'vm-401'

# Volume ID 정보 확인
pvesm path local:iso/Rocky-9.x-x86_64-dvd.iso

NFS를 백업 전용으로 추가하는 예시입니다.

pvesm add nfs backup-nfs \
  --server 10.10.60.10 \
  --export /exports/proxmox-backup \
  --content backup \
  --options vers=4.1

ISO·LXC Template·Snippet도 저장할 계획이면 --content backup,iso,vztmpl,snippets처럼 명시합니다.

NFS 추가 전에는 export 권한, 네트워크, MTU, 용량, 성능, 장애 시 접근성, 복구 테스트를 확인합니다.

클러스터 관리: pvecm

# 클러스터 Quorum과 상태
pvecm status
pvecm nodes

# REST API 관점의 상태
pvesh get /cluster/status
pvesh get /cluster/resources --output-format json-pretty

# Corosync·HA 서비스
systemctl status corosync pve-cluster pve-ha-lrm pve-ha-crm
journalctl -u corosync -n 100 --no-pager

pvecm status에서는 Quorate: Yes를 우선 확인합니다. Quorum이 없으면 클러스터 설정 변경, HA, 일부 VM 관리에 문제가 생길 수 있습니다.

새 노드에서 기존 클러스터에 참여할 때는 아래와 같이 실행합니다.

# 새로 설치한 합류 노드에서 실행
pvecm add 10.10.40.11

클러스터 합류 전에는 Proxmox VE 메이저 버전, Debian 코드명, Repository 정책, DNS·FQDN, NTP, Corosync 네트워크, 방화벽, 스토리지 정책을 확인합니다.

백업과 복구

vzdump는 VM·컨테이너 전체 백업을 생성합니다.

# VM 백업
vzdump 401 \
  --storage backup-nfs \
  --mode snapshot \
  --compress zstd

# 여러 VM 백업
vzdump 401 402 403 \
  --storage backup-nfs \
  --mode snapshot \
  --compress zstd

모드	설명
`snapshot`	지원 스토리지에서 실행 중 VM의 live backup 수행. 일반적으로 우선 검토
`suspend`	호환성 목적. VM 일시 정지로 중단이 생기며 정합성이 반드시 더 좋아지지는 않음
`stop`	VM·컨테이너를 중지한 뒤 백업. 서비스 중단 발생

Guest Agent가 활성화된 VM은 backup 중 filesystem freeze/thaw로 일관성 향상에 도움을 줄 수 있습니다.

VM은 qmrestore, LXC 컨테이너는 pct restore로 새 ID에 복구합니다.

qmrestore \
  /mnt/pve/backup-nfs/dump/vzdump-qemu-401-<timestamp>.vma.zst \
  901 \
  --storage local-lvm

pct restore \
  902 \
  /mnt/pve/backup-nfs/dump/vzdump-lxc-201-<timestamp>.tar.zst \
  --storage local-lvm

복구된 VM·컨테이너는 먼저 격리 VLAN 또는 테스트 네트워크에서 부팅·파일시스템·애플리케이션·Guest Agent·데이터 정합성을 검증한 뒤 운영망으로 전환합니다.

작업 이력은 CLI에서도 확인할 수 있습니다.

pvenode task list
pvenode task log <UPID>

API 탐색: pvesh

pvesh는 REST API 경로를 CLI에서 탐색하고 조회할 수 있는 도구입니다.

pvesh ls /
pvesh ls /nodes
pvesh ls /nodes/$(hostname)/qemu

pvesh get /nodes/$(hostname)/qemu \
  --output-format json-pretty

pvesh get /nodes/$(hostname)/qemu/401/status/current \
  --output-format json-pretty

pvesh는 API 변경 작업도 수행할 수 있습니다. VM 생성·삭제, 스토리지·네트워크 변경 같은 쓰기 요청은 테스트 환경에서 API 경로와 파라미터를 검증한 뒤 적용합니다.

빠른 점검 명령

단일 노드

pveversion -v
pvesm status
qm list
pct list

ip -br addr
ip route
free -h
df -h

systemctl --no-pager --full status \
  pveproxy pvedaemon pvestatd pve-cluster

journalctl -p err..alert -b

클러스터

pvecm status
pvecm nodes
pvesm status

systemctl --no-pager --full status \
  corosync pve-cluster pve-ha-lrm pve-ha-crm

journalctl -u corosync -n 100 --no-pager

특정 VM

VMID=401

qm status "${VMID}"
qm config "${VMID}"
qm agent "${VMID}" ping
qm guest cmd "${VMID}" network-get-interfaces

tail -n 100 "/var/log/pve/qemu-server/${VMID}.log"

CLI 운영 원칙

실행 전 VM ID, CTID, 노드, storage ID를 먼저 확인합니다.
삭제·복구·스토리지 제거·ZFS·클러스터 변경은 백업과 롤백 경로를 먼저 준비합니다.
Web UI의 Task History와 CLI 결과를 교차 검증합니다.
VM·CT·스토리지·네트워크·백업 설정을 Git 문서 또는 IaC 코드로 관리합니다.
자동화는 명시적 대상 목록과 dry-run·검증 단계를 사용합니다.
/etc/pve 구성 파일 백업은 유용하지만, pmxcfs·Corosync·스토리지·백업 전략을 포함한 전체 클러스터 DR을 대체하지 않습니다.

핵심 정리

qm은 VM, pct는 LXC, pvesm은 storage, pvecm은 cluster, vzdump는 backup, pvesh는 REST API CLI 도구입니다.
pveversion -v, pvesm status, qm list, pct list, pvecm status, journalctl은 기본 운영 점검 명령입니다.
qm resize 후에는 Guest OS의 파티션·LVM·파일시스템 확장이 필요합니다.
스냅샷은 단기 rollback 수단이며 백업·복구 테스트를 대체하지 않습니다.
pvecm status에서 Quorum과 Quorate: Yes를 우선 확인합니다.
삭제·복구·스토리지 변경 명령은 대상 검증, 백업, 복구 절차를 먼저 확인해야 합니다.
CLI 자동화는 편리하지만, 명시적 대상·예외·의존성·dry-run·로그를 포함한 안전장치가 필요합니다.

참고 자료

cli pct proxmox proxmox-ve pvecm pvesh pvesm qm virtualization vzdump

작성일: 2026년 9월 10일 , 마지막 업데이트: 2026년 9월 10일