With the VM powered off:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

modprobe nbd max_part=16
qemu-nbd --connect=/dev/nbd0 /var/lib/vz/images/100/vm-100-disk-0.qcow2   # add -r for read-only
partprobe /dev/nbd0
lsblk /dev/nbd0                                  # nbd0p1, nbd0p2…
mount /dev/nbd0p2 /mnt/vm

# ... read, copy, or repair ...

umount /mnt/vm
qemu-nbd --disconnect /dev/nbd0

Without the --disconnect the VM will not start again: QEMU finds the image locked.

Why nbd

A .qcow2 is not a dump of the disk: it has a header, a cluster table, internal snapshots, and sometimes a backing file behind it. losetup does not understand it. qemu-nbd does, and publishes it as a block device through the kernel’s NBD client; from there on it is one more disk for lsblk, mount, fsck, or dd.

max_part matters: without it the kernel does not create the nbd0p1, nbd0p2… nodes. partprobe forces them if they do not show up after --connect.

If the VM disk carries LVM

The norm on Ubuntu Server, RHEL, and Fedora: inside the partition there is a VG. Activate it, mount the LV, and when done deactivate it before disconnecting:

1
2
3
4
5
6
7
8

vgscan
vgchange -ay                                   # activates whatever it finds on nbd0
lvs                                            # ubuntu-vg/ubuntu-lv, rhel/root…
mount /dev/ubuntu-vg/ubuntu-lv /mnt/vm

umount /mnt/vm
vgchange -an ubuntu-vg
qemu-nbd --disconnect /dev/nbd0

Classic trap: the host has a VG with the same name as the VM’s (ubuntu-vg vs ubuntu-vg, pve vs pve). LVM refuses to activate two alike. The tool for that is vgimportclone, which renames the VG on the imported disk without touching the host’s:

1
2

vgimportclone -n vm100-vg /dev/nbd0p3
vgchange -ay vm100-vg

If you would rather change nothing inside the VM, guestmount (below) resolves the LVM on its own and does not touch the host’s LVM.

Windows, NTFS, and internal snapshots

• NTFS: mount -t ntfs3 /dev/nbd0p3 /mnt/vm (kernel 5.15+) or ntfs-3g. If Windows was left hibernated or with Fast Startup, NTFS only mounts read-only; shut it down properly from inside before writing.
• qcow2 internal snapshot (qemu-img snapshot -l vm.qcow2): qemu-nbd -r -l before-the-change --connect=/dev/nbd0 vm.qcow2 mounts the state of that snapshot, read-only, without touching the current disk.
• Other formats: qemu-nbd also speaks vmdk, vhdx, and vdi (-f vhdx if it does not detect it); qemu-img convert -O raw is the alternative if you are going to work on the image for a long time.

guestmount: the same without nbd or root

libguestfs mounts the image over FUSE, detects partitions and LVM on its own, and does not interfere with the host:

1
2
3
4

apt install libguestfs-tools          # dnf install guestfs-tools on Fedora/RHEL
virt-filesystems --long -h --all -a vm.qcow2      # what is inside
guestmount -a vm.qcow2 -i --ro /mnt/vm            # -i: mount the operating system it finds
guestunmount /mnt/vm

Slower than nbd for copying gigabytes, but impossible to leave half closed.

Traps

• Never with the VM running. Read-write you will corrupt the filesystem for sure; with -r you see an inconsistent state (what the guest holds in cache is not on disk). If you need to look at a live VM, take a snapshot and mount the snapshot.
• The image stays locked while qemu-nbd is connected: qm start 100 fails with Failed to get "write" lock. qemu-nbd -d /dev/nbd0 releases it; ls /sys/block/nbd*/pid tells which ones are still in use.
• --disconnect with “device busy”: something is still mounted or a VG is active (vgchange -an). lsof /dev/nbd0* finds it.
• Proxmox with LVM-thin or ZFS needs no nbd: the VM disk is already a block device (/dev/pve/vm-100-disk-0, /dev/zvol/rpool/data/vm-100-disk-0); kpartx -av on it exposes the partitions. qemu-nbd is for qcow2 on directory and NFS storages.
• Backing files: an image with a backing file mounts the same; whatever you write goes to the top layer. Do not move the base while it is connected.

See also: convert a physical machine to VHDX and disk import on Proxmox. Reference: qemu-nbd in the QEMU documentation.

1
2
3

rw
kvmd-edidconf --import-preset=v3.1080p-by-default --apply    # V3, and DIY V0–V2 with their preset (v0, v1, v2)
ro

Then reboot the host or unplug and replug the HDMI: the EDID is only read when the host detects the monitor. On V4 Mini and V4 Plus none of this is needed: they capture 1080p at 60 Hz out of the box.

Why

The PiKVM presents itself to the host as a monitor, and what that monitor “can do” lives in the EDID: resolutions, refresh rates, and which one is preferred. The host picks from that.

The V3 (and DIY builds with the TC358743 CSI capture chip) has a hardware limit: 1080p only at 50 Hz. Since 50 Hz is an unusual rate, the default EDID marks 720p60 as the preferred mode and many hosts stay there. That is right for most, but some systems look bad at 720p: the Proxmox console, some BIOS screens, desktops that scale oddly. The v3.1080p-by-default preset keeps the same modes but makes 1080p50 the preferred one.

Checking

1

kvmd-edidconf                 # no arguments: manufacturer, product, serial, name and audio of the current EDID

In the web UI, the video indicator shows the resolution and fps being captured; after the host reboot it should read 1920x1080 and 50. If the host has a display tool (xrandr, Windows Settings), the “monitor” shows up with the EDID’s name.

Other EDID settings

Windows stores per-monitor settings keyed by manufacturer, product, and serial. If the host stays in an old mode after changing the EDID, change its identity so it treats it as a new monitor:

1
2
3

rw
kvmd-edidconf --set-monitor-name=PIKVM --set-mfc-id=PKV --set-product-id=34953 --set-serial=1234567890 --apply
ro

• --set-audio=1 advertises audio over HDMI (to capture sound on models that support it).
• On the V4 Plus, with a real monitor connected to the OUT2 output, --import-display-ids copies its identity into the PiKVM’s EDID.
• Back to the original: kvmd-edidconf --import-preset=v3 --apply (or v4mini, v4plus depending on the model).

Traps

• rw before, ro after. The PiKVM filesystem is read-only; without rw the change is not saved and without ro it nags you on every login.
• The host must re-read the EDID. --apply takes effect on the PiKVM instantly, but the host does not notice until a reboot, a cable replug, or on some BIOSes only at POST.
• 50 Hz on the V3 is not a bug, it is the capture chip’s limit. For 60 Hz, V4.
• Black screen after a hand-made EDID: import the model’s preset again and apply.
• Proxmox and other framebuffer consoles fix the mode at boot; after changing the EDID you have to reboot the node, not just the session.

Reference: EDID in the PiKVM documentation.

1
2

qm set 102 --cpu x86-64-v2-AES    # or x86-64-v3 if every host is Haswell / EPYC or newer
qm stop 102 && qm start 102       # a reboot from inside Windows does NOT apply the change

Symptoms

Windows 10, 11, or Server with cpu: host: slow boot, stuttering desktop, multi-second freezes, anything that touches memory is bad. The same VM with x86-64-v2-AES responds normally. A Linux VM with host on the same node notices nothing.

Why it happens

host passes the VM every flag of the physical CPU, including two that exist for Intel vulnerability mitigations:

Inside a VM those operations are extremely expensive. The measurements from the original Proxmox forum thread: on a Xeon E5-2667 v2 the RAM read latency goes from ~100 ns to ~2000 ns; on an i9-13900K, from 30 to 90 ns. Windows, which touches kernel memory all the time, crawls.

The generic types (x86-64-v2-AES, x86-64-v3, IvyBridge-IBRS, …) do not expose those two flags, so Windows neither sees the vulnerability nor turns on the mitigation.

Which type to pick

Pick the highest one that every node in the cluster supports:

1

grep -o -w -E 'avx2|avx512f' /proc/cpuinfo | sort -u   # avx2 → v3 ok; avx512f → v4 ok

That is the Proxmox staff recommendation in that same thread: use the x86-64-v* matching the hardware instead of blindly turning security flags off.

If you insist on host

There are cases where host is needed: nested virtualization (Hyper-V, WSL2 inside the VM, an ESXi lab), because the x86-64-v* types do not expose vmx/svm. You can drop md_clear with the flags option:

1

qm set 102 --cpu host,flags=-md-clear

But flush_l1d is not in the list of flags Proxmox lets you touch, so you keep half of the problem. And hiding mitigations from the guest is a security decision: reasonable on a single-owner node, not on one with tenants you do not control.

Checking from inside Windows

Microsoft’s official module shows which mitigations the guest has active:

1
2

Install-Module SpeculationControl -Scope CurrentUser
Get-SpeculationControlSettings

With host, MDSWindowsSupportEnabled and L1TFWindowsSupportEnabled come out True; with x86-64-v2-AES, False. It is the quick way to confirm the change applied.

Traps

• The change needs stop/start. The CPU type is fixed when the QEMU process launches; a reboot from inside the guest does not touch it.
• It is an Intel thing. md_clear and flush_l1d do not exist on AMD; with host on EPYC/Ryzen you will not see this drop (though host still blocks migration across different CPUs).
• It applies to new VMs too. Templates created with host inherit the problem; change it in the template.
• Windows stays safe against what matters inside a VM with either type: the mitigations that count (Spectre v2, etc.) remain active; what goes away is the double mitigation of vulnerabilities the host already mitigates.

References: Proxmox forum thread and the CPU section of the admin guide.

System → Advanced → Networking → Disable hardware checksum offload ✔ → Save → reboot the VM. The GUI does not say so, but the change does not apply to vtnet interfaces until the reboot.

To test without rebooting (lost at boot):

1
2

ifconfig vtnet0 -rxcsum -txcsum -tso -lro
ifconfig vtnet1 -rxcsum -txcsum -tso -lro

On OPNsense: Interfaces → Settings → Hardware CRC → Disable hardware checksum offload, and the same reboot.

Symptoms

The VM boots, the interfaces are UP, LAN DHCP hands out addresses, and still:

• Hosts behind the firewall cannot reach the Internet, or connections stall halfway (ping passes, TCP hangs).
• From the virtualization host itself or from other VMs on the same host nothing protected by pfSense is reachable, not even the GUI.
• Switching the VM’s NIC to e1000 fixes it on the spot, which confirms the diagnosis.

Why it happens

FreeBSD’s vtnet driver, with checksum offload enabled, hands the network stack packets whose checksum never got computed: between VMs on the same host, and between the host and the VM, traffic never crosses a physical NIC that would do it. FreeBSD sees invalid checksums and drops them (FreeBSD bug 165059). Netgate documents it under VirtIO Driver Support.

pfSense tries to tick the option only when it detects vtnet interfaces at install time. If the VirtIO NIC was added later, if you restored the config.xml from a physical firewall, or if you migrated the VM from another hypervisor with a different NIC type, the option stays off.

Procedure

1. System → Advanced → Networking, Network Interfaces section:

   • Disable hardware checksum offload: tick it.
   • Disable hardware TCP segmentation offload and Disable hardware large receive offload: already ticked by default; leave them.

2. Save.

3. Reboot from Diagnostics → Reboot. Without this step nothing changes on vtnet.

4. Check:

   1	ifconfig vtnet0 | grep options

   Neither RXCSUM nor TXCSUM (nor TSO4, LRO) should show up.

If it is still the same

• All of the VM’s NICs must be the same kind. A vtnet with offload and an e1000 behave differently; check every ifconfig.
• Offload on the host. Netgate notes that sometimes checksums and TSO must also be turned off on the hypervisor. On Proxmox/KVM, on the VM’s tap interface: ethtool -K tap100i0 tx off (the number is the VMID and i0 the NIC). Rarely needed; try it last.
• Plan B: e1000 NIC model on the VM. Less throughput than VirtIO without offload, but none of this bug.

Traps

• The reboot is not optional and the GUI does not ask for it. It is the number one cause of “I ticked it and it still does not work”.
• It is not a rules problem. With offload on, packets are dropped before reaching pf; the firewall log shows nothing.
• e1000 on OPNsense too as plan B; the equivalent setting lives under Interfaces → Settings.
• Multiqueue (queues=N on Proxmox) works fine with vtnet once offload is off; do not mistake it for the cause.