# virsh를 이용한 KVM/QEMU VM 관리 가이드

## 현재 환경 상태

| 항목 | 값 |
|------|-----|
| libvirt | 10.0.0 |
| QEMU | 8.2.2 |
| 연결 URI | `qemu:///session` (사용자 세션 모드) |
| 사용자 그룹 | `kvm`, `libvirt` 포함 |
| 스토리지 풀 | `default` → `~/.local/share/libvirt/images/` |
| OS | Ubuntu 24.04.4 LTS (Kernel 6.17) |
| CPU | AMD Ryzen 9 5900X (12c/24t) |
| RAM | 40 GB |

> **session vs system 모드**: `qemu:///session`은 일반 사용자 권한으로 동작하며 네트워크 기능이 제한됩니다.
> 브릿지 네트워크 등 고급 네트워킹이 필요하면 `qemu:///system`을 사용해야 합니다.

```bash
# system 모드로 연결
virsh -c qemu:///system list --all

# 환경변수로 기본 URI 변경
export LIBVIRT_DEFAULT_URI="qemu:///system"
```

---

## 1. ISO 다운로드 & 디스크 이미지 생성

```bash
# ISO 다운로드 (예: Ubuntu 24.04 Server)
wget -P ~/.local/share/libvirt/images/ \
  https://releases.ubuntu.com/24.04/ubuntu-24.04-live-server-amd64.iso

# qcow2 디스크 이미지 생성 (씬 프로비저닝)
qemu-img create -f qcow2 ~/.local/share/libvirt/images/myvm.qcow2 20G

# 디스크 이미지 정보 확인
qemu-img info ~/.local/share/libvirt/images/myvm.qcow2
```

---

## 2. VM 생성 — `virt-install`

virsh 자체는 이미 정의된 VM을 관리하는 도구이고, **최초 생성**은 `virt-install`이 편합니다.

### 기본 VM 생성 (GUI 콘솔)

```bash
virt-install \
  --name ubuntu-lab01 \
  --ram 4096 \
  --vcpus 2 \
  --disk path=~/.local/share/libvirt/images/ubuntu-lab01.qcow2,size=20,format=qcow2 \
  --cdrom ~/.local/share/libvirt/images/ubuntu-24.04-live-server-amd64.iso \
  --os-variant ubuntu24.04 \
  --network default \
  --graphics vnc,listen=0.0.0.0 \
  --noautoconsole
```

### 헤드리스 (시리얼 콘솔만)

SSH 접근용으로 가볍게 사용할 때 적합합니다.

```bash
virt-install \
  --name ubuntu-lab01 \
  --ram 4096 \
  --vcpus 2 \
  --disk path=~/.local/share/libvirt/images/ubuntu-lab01.qcow2,size=20,format=qcow2 \
  --cdrom ~/.local/share/libvirt/images/ubuntu-24.04-live-server-amd64.iso \
  --os-variant ubuntu24.04 \
  --network default \
  --graphics none \
  --console pty,target_type=serial \
  --extra-args 'console=ttyS0,115200n8'
```

### system 모드 + 브릿지 네트워크

```bash
sudo virt-install \
  --connect qemu:///system \
  --name ubuntu-lab01 \
  --ram 4096 \
  --vcpus 4 \
  --cpu host-passthrough \
  --disk path=/var/lib/libvirt/images/ubuntu-lab01.qcow2,size=30,format=qcow2 \
  --cdrom /var/lib/libvirt/images/ubuntu-24.04-live-server-amd64.iso \
  --os-variant ubuntu24.04 \
  --network bridge=virbr0 \
  --graphics vnc \
  --noautoconsole
```

### os-variant 확인

```bash
osinfo-query os | grep ubuntu
```

---

## 3. VM 라이프사이클 관리

### 상태 조회

```bash
virsh list                    # 실행 중인 VM만
virsh list --all              # 모든 VM (정지 포함)
virsh dominfo ubuntu-lab01    # VM 상세 정보
virsh domstate ubuntu-lab01   # 상태만 (running/shut off 등)
virsh vcpuinfo ubuntu-lab01   # vCPU 배치 정보
virsh domifaddr ubuntu-lab01  # VM IP 주소 확인
virsh dumpxml ubuntu-lab01    # 전체 XML 설정 덤프
```

### 시작 / 종료 / 재부팅

```bash
virsh start ubuntu-lab01         # 시작
virsh shutdown ubuntu-lab01      # 정상 종료 (ACPI shutdown)
virsh reboot ubuntu-lab01        # 정상 재부팅
virsh destroy ubuntu-lab01       # 강제 종료 (= 전원 뽑기)
virsh reset ubuntu-lab01         # 강제 리셋
virsh suspend ubuntu-lab01       # 일시정지 (메모리 유지)
virsh resume ubuntu-lab01        # 일시정지 해제
```

### 자동 시작 설정

```bash
virsh autostart ubuntu-lab01            # 호스트 부팅 시 자동 시작
virsh autostart --disable ubuntu-lab01  # 자동 시작 해제
```

---

## 4. VM 설정 변경

### CPU / 메모리

```bash
# VM 정지 상태에서 변경 (다음 부팅 시 적용)
virsh setvcpus ubuntu-lab01 4 --config
virsh setmaxmem ubuntu-lab01 8G --config
virsh setmem ubuntu-lab01 8G --config

# 라이브 변경 (핫플러그 — 게스트 지원 필요)
virsh setvcpus ubuntu-lab01 4 --live
virsh setmem ubuntu-lab01 6G --live
```

### XML 직접 편집

```bash
virsh edit ubuntu-lab01    # $EDITOR로 XML 설정 편집 (검증 후 적용)
```

### 디스크 추가 / 제거

```bash
# 새 디스크 이미지 생성
qemu-img create -f qcow2 ~/.local/share/libvirt/images/data-disk.qcow2 50G

# VM에 디스크 연결
virsh attach-disk ubuntu-lab01 \
  ~/.local/share/libvirt/images/data-disk.qcow2 \
  vdb \
  --driver qemu --subdriver qcow2 --persistent

# 디스크 분리
virsh detach-disk ubuntu-lab01 vdb --persistent
```

### 네트워크 인터페이스 추가 / 제거

```bash
# 네트워크 인터페이스 추가
virsh attach-interface ubuntu-lab01 \
  --type network --source default --model virtio --persistent

# 인터페이스 제거 (MAC 주소 지정)
virsh detach-interface ubuntu-lab01 network --mac 52:54:00:xx:xx:xx --persistent
```

---

## 5. 스냅샷 관리

커널 실험 등 위험한 작업 전에 필수.

```bash
# 스냅샷 생성
virsh snapshot-create-as ubuntu-lab01 \
  --name "before-kernel-experiment" \
  --description "커널 모듈 테스트 전 상태"

# 라이브 스냅샷 (VM 실행 중, 디스크만)
virsh snapshot-create-as ubuntu-lab01 \
  --name "live-snap-01" \
  --disk-only

# 스냅샷 목록
virsh snapshot-list ubuntu-lab01
virsh snapshot-list ubuntu-lab01 --tree   # 트리 형태

# 스냅샷 정보
virsh snapshot-info ubuntu-lab01 before-kernel-experiment

# 스냅샷으로 복원 (revert)
virsh snapshot-revert ubuntu-lab01 before-kernel-experiment

# 스냅샷 삭제
virsh snapshot-delete ubuntu-lab01 before-kernel-experiment
```

---

## 6. 클론 & Export/Import

### VM 클론

```bash
# 원본 정지 상태 필요
virt-clone \
  --original ubuntu-lab01 \
  --name ubuntu-lab02 \
  --auto-clone
```

### XML 기반 Export / Import

```bash
# 내보내기
virsh dumpxml ubuntu-lab01 > ubuntu-lab01.xml

# XML 편집 (이름, UUID, MAC, 디스크 경로 변경 후)
virsh define ubuntu-lab01-modified.xml
```

---

## 7. VM 삭제

```bash
# 정의만 제거 (디스크 파일은 유지)
virsh undefine ubuntu-lab01

# 정의 + 디스크 파일도 함께 삭제
virsh undefine ubuntu-lab01 --remove-all-storage

# UEFI/NVRAM이 있는 VM 삭제
virsh undefine ubuntu-lab01 --nvram --remove-all-storage
```

---

## 8. 콘솔 접속

```bash
# 시리얼 콘솔 접속 (Ctrl+] 로 탈출)
virsh console ubuntu-lab01

# VNC 접속 포트 확인
virsh vncdisplay ubuntu-lab01
# 출력 예: :0  → localhost:5900 으로 VNC 클라이언트 접속

# VNC 뷰어 실행
virt-viewer ubuntu-lab01
```

---

## 9. 네트워크 관리

### 기본 조회 및 시작

```bash
virsh net-list --all                 # 네트워크 목록
virsh net-start default              # 기본 NAT 네트워크 시작
virsh net-autostart default          # 자동 시작 설정
virsh net-info default               # 네트워크 정보
virsh net-dhcp-leases default        # DHCP 임대 목록 → VM IP 확인
```

### 커스텀 네트워크 생성

```bash
cat > /tmp/isolated-net.xml << 'EOF'
<network>
  <name>isolated</name>
  <bridge name="virbr1"/>
  <ip address="10.10.10.1" netmask="255.255.255.0">
    <dhcp>
      <range start="10.10.10.100" end="10.10.10.200"/>
    </dhcp>
  </ip>
</network>
EOF

virsh net-define /tmp/isolated-net.xml
virsh net-start isolated
virsh net-autostart isolated
```

### 네트워크 삭제

```bash
virsh net-destroy isolated     # 중지
virsh net-undefine isolated    # 정의 제거
```

---

## 10. 스토리지 풀 관리

### 풀 조회

```bash
virsh pool-list --all
virsh pool-info default
```

### 새 풀 생성

```bash
# 예: HDD에 별도 풀 생성
virsh pool-define-as hdd-pool dir - - - - /mnt/data/libvirt-images
virsh pool-build hdd-pool
virsh pool-start hdd-pool
virsh pool-autostart hdd-pool
```

### 볼륨 관리

```bash
virsh vol-list default                                      # 볼륨 목록
virsh vol-create-as default myvm.qcow2 20G --format qcow2  # 볼륨 생성
virsh vol-delete myvm.qcow2 --pool default                  # 볼륨 삭제
virsh vol-info myvm.qcow2 --pool default                    # 볼륨 정보
```

---

## 11. 워크플로우 패턴

### 빠른 실험 VM 만들고 날리기

```bash
# 1) 디스크 + VM 생성
qemu-img create -f qcow2 ~/.local/share/libvirt/images/test01.qcow2 15G
virt-install --name test01 --ram 2048 --vcpus 2 \
  --disk ~/.local/share/libvirt/images/test01.qcow2 \
  --cdrom ~/isos/ubuntu-24.04-server.iso \
  --os-variant ubuntu24.04 --noautoconsole

# 2) 설치 완료 후 스냅샷 (클린 상태 저장)
virsh snapshot-create-as test01 --name clean-install

# 3) 실험 진행 → 문제 시 롤백
virsh snapshot-revert test01 clean-install

# 4) 실험 완료 → VM 완전 삭제
virsh destroy test01
virsh undefine test01 --remove-all-storage --snapshots-metadata
```

### Cloud-Init으로 무인 설치 (ISO 설치 없이)

```bash
# 1) cloud image 다운로드
wget -O ~/.local/share/libvirt/images/ubuntu-24.04-cloud.img \
  https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img

# 2) 백킹 이미지로 씬 디스크 생성 (원본 보존)
qemu-img create -f qcow2 \
  -b ~/.local/share/libvirt/images/ubuntu-24.04-cloud.img \
  -F qcow2 \
  ~/.local/share/libvirt/images/lab01.qcow2 20G

# 3) cloud-init 설정 파일 생성
cat > /tmp/user-data << 'EOF'
#cloud-config
hostname: lab01
users:
  - name: jinsoo
    sudo: ALL=(ALL) NOPASSWD:ALL
    ssh_authorized_keys:
      - ssh-rsa YOUR_PUBLIC_KEY_HERE
    shell: /bin/bash
password: changeme
chpasswd: { expire: false }
ssh_pwauth: true
EOF

cat > /tmp/meta-data << 'EOF'
instance-id: lab01
local-hostname: lab01
EOF

# 4) cloud-init ISO 생성
genisoimage -output /tmp/cloud-init.iso -volid cidata -joliet -rock \
  /tmp/user-data /tmp/meta-data

# 5) VM 생성 (설치 과정 없이 바로 부팅)
virt-install --name lab01 --ram 4096 --vcpus 2 \
  --disk ~/.local/share/libvirt/images/lab01.qcow2 \
  --disk /tmp/cloud-init.iso,device=cdrom \
  --os-variant ubuntu24.04 \
  --network default \
  --import --noautoconsole
```

---

## 12. 유용한 팁

```bash
# 모든 VM 한번에 종료
for vm in $(virsh list --name); do virsh shutdown "$vm"; done

# VM 리소스 모니터링
virt-top

# 게스트 에이전트 통해 정보 조회 (qemu-guest-agent 설치 필요)
virsh qemu-agent-command ubuntu-lab01 '{"execute":"guest-info"}'

# 도움말
virsh help              # 전체 명령어 목록
virsh help snapshot     # snapshot 관련 명령어만
virsh help start        # 특정 명령어 상세
```

---

## 환경별 주의사항

1. **session vs system 모드** — 현재 `qemu:///session`으로 동작 중이므로 `virbr0` 등 system 네트워크를 쓸 수 없습니다. 브릿지 네트워크가 필요하면 `sudo virsh -c qemu:///system` 또는 `LIBVIRT_DEFAULT_URI=qemu:///system`으로 전환하세요.
2. **스토리지 경로** — 기본 풀이 SSD(`~/.local/share/libvirt/images/`)에 있습니다. 큰 VM은 `/mnt/data/`에 별도 풀을 만들어 사용하는 것을 권장합니다.
3. **GPU passthrough** — RTX 3090은 LLM 서빙 전용이므로 VM에 패스스루하지 않도록 주의하세요.