# pve-vm-ops-guide

Proxmox VE에서 Windows/Linux VM을 **원격으로 다루는 실전 가이드** + **SATA → VirtIO-SCSI 디스크 컨트롤러 마이그레이션 함정** 분석.

## ⭐ 이 리포의 핵심 발견

Windows VM의 디스크 컨트롤러를 SATA에서 VirtIO-SCSI로 옮길 때 흔히 부딪치는 BSOD (`0xc0000017` / `0xc0000225`)의 진짜 원인:

```cmd
sc qc vioscsi
> START_TYPE: 3 DEMAND_START     ← 이게 문제. boot critical 아님.
```

해결:

```cmd
sc config vioscsi start= boot
```

`pnputil /add-driver`로 드라이버 등록만으로는 **부족**. 서비스를 BOOT_START(0)로 명시 승격해야 winload가 부팅 시점에 vioscsi.sys를 로드한다.

자세한 진단 과정과 다른 잘못된 해결책들의 기록은 [JOURNEY.md](JOURNEY.md) 참조.

---

## 📁 구성

| 파일 | 내용 |
|---|---|
| [GUIDE.ko.md](GUIDE.ko.md) | **본 가이드** — VM 화면 캡처, QGA, qm sendkey, vhd 임포트, virtio-scsi 마이그레이션, DR 이전 |
| [JOURNEY.md](JOURNEY.md) | **실패의 연대기** — 진짜 원인 찾기까지 거친 15단계 |
| [screenshots/](screenshots/) | 부팅 검증 화면 캡처 |

---

## 🎯 가이드가 다루는 것

1. **VM 원격 제어** (Proxmox 호스트 SSH + QEMU monitor + QGA)
   - 화면 캡처 (PPM → PNG)
   - 게스트 안에서 명령 실행 (`qm guest exec`)
   - GUI 키 입력 (`qm sendkey`)
   - 사용자 세션 컨텍스트 실행 (QGA + schtasks)
2. **VHD → ZFS raw zvol 변환 + attach**
3. **VirtIO 드라이버 사전 설치 + SATA→SCSI 인터페이스 전환**
4. **VM DR (Disaster Recovery) 이전** — PBS 백업 + 다른 노드 restore
5. **트러블슈팅**
   - `WARN: no efidisk configured`
   - `GPT PMBR size mismatch`
   - BSOD `0xc0000017` / `0xc0000225` (vioscsi boot critical 미설정)

---

## 🛠 검증 환경

- Proxmox VE 8.1.3
- ZFS pool 기반 storage (raw zvol)
- Windows 10 Pro (build 19045)
- virtio-win-0.1.285
- OVMF (UEFI) + machine: pc-i440fx-7.1

---

## 📋 표기 규약

가이드 안 placeholder:

- `<PVE_HOST>` `<PVE_PASSWORD>`: Proxmox 노드 root 접속
- `<SMB_HOST>` `<SMB_USER>` `<SMB_PASSWORD>`: SMB/CIFS 파일 서버
- `<windows_user>`: Windows 게스트 사용자
- VMID 예시는 `101`, zvol 예시는 `vm-101-disk-N` — 본인 환경 값으로 치환

---

## 🤝 기여

같은 함정에 빠진 적 있거나 다른 환경(machine: q35, viostor 기반 부팅, sysprep 이미지 등)에서의 케이스를 추가하고 싶다면 PR/issue 환영.

---

## 📄 라이선스

CC BY 4.0