Runbook — preparing and passing a disk through

Extracted from the master document on 2026-09-04. The §N numbering is kept so cross-references are not broken.

12. Physical HDD and passthrough

Proxmox
  │
  └── /dev/disk/by-id/ata-WDC_WD10EZEX-22MFCA0_WD-WCC6Y1HHEPN4
          │  (qm set 100 -scsi1 ...)
          ▼
       VM 100
          │
        ext4  (UUID 90134202-42d5-485a-8e13-3d87cd82a753)
          │
    /mnt/storage

Critical rule: the same ext4 filesystem must not be mounted for writing in Proxmox and in the VM at the same time.

Why passthrough and not NFS/SMB: it avoids putting a file server between Proxmox and the VM for something that is a local disk. Why /dev/disk/by-id: /dev/sdb can change between boots or when hardware is touched; the by-id name does not.

Reusable disk preparation procedure

# 1. identify without destroying anything
lsblk -o NAME,SIZE,MODEL,FSTYPE,MOUNTPOINTS
sudo wipefs -n /dev/sdb

# 2. GPT + one partition
sudo apt install parted
sudo parted /dev/sdb --script mklabel gpt
sudo parted /dev/sdb --script mkpart primary ext4 0% 100%

# 3. filesystem + label
sudo mkfs.ext4 -L homelab-storage /dev/sdb1

# 4. UUID (never mount by /dev/sdX in fstab)
sudo blkid /dev/sdb1

# 5. unmount in Proxmox BEFORE the passthrough
sudo umount /mnt/homelab-storage
findmnt /mnt/homelab-storage

# 6. hand it over to the VM
sudo /usr/sbin/qm set 100 -scsi1 /dev/disk/by-id/ata-WDC_WD10EZEX-...
sudo /usr/sbin/qm config 100 | grep scsi

# 7. inside the VM: fstab + validate
sudo mkdir -p /mnt/storage
echo 'UUID=<uuid> /mnt/storage ext4 defaults 0 2' | sudo tee -a /etc/fstab
sudo systemctl daemon-reload
sudo mount -a
findmnt /mnt/storage

Structure inside VM 100:

/mnt/storage/
├── lost+found/
├── nextcloud/
│   └── data/                   ← NEXTCLOUD_DATADIR (bind mount, not a volume)
├── nextcloud-aio-backup/
│   └── borg/                   ← AIO's native backup (§41)
└── backups/
    ├── vaultwarden/
    └── nextcloud/