Where it lives and who writes it
/etc/pve/qemu-server/111.conf VM 111 on this node
/etc/pve/lxc/201.conf container 201 — built the same way
/etc/pve/nodes/pve1/qemu-server/ the real location; /etc/pve/qemu-server is a link to your node's directory
/etc/pve is the pmxcfs file system, shared by the cluster nodes. You can read the file and edit it in an editor,
but qm set 111 --memory 4096 is simpler and safer: the command validates values and handles a running VM properly.
qm config 111 prints the same as the file, without snapshots. Proxmox keeps the keys in the file in alphabetical
order, so the order below is the same.
Below is the web1 VM from a cloud-init template (VM template with cloud-init) with one snapshot.
The config
agent: enabled=1The link to the guest agent: through it Proxmox shuts the VM down cleanly, sees its addresses and freezes the file system during a backup. The agent itself is installed inside the guest (Guest agent).
boot: order=scsi0Which disk to boot from. A list separated by ;: order=scsi0;ide2;net0 — disk first, then CD, then network.
ciuser: example-userThe user cloud-init creates on the first boot, with passwordless sudo.
cores: 2
cpu: hostCores and CPU type. host — the guest sees the host CPU in full: fastest, but live migration only to an identical CPU. Without a cpu: line the default type is x86-64-v2-AES, which any CPU from the 2010s understands.
default:cpu x86-64-v2-AEScores 1
ide2: local-lvm:vm-111-cloudinit,media=cdrom,size=4M
ipconfig0: ip=10.0.0.11/24,gw=10.0.0.1The cloud-init disk: a 4 MB CD-ROM onto which Proxmox writes the user, keys and network. It’s regenerated on every VM start from the ci*, ipconfig*, nameserver and sshkeys lines.
memory: 2048Memory in MiB — the maximum the guest sees. Without balloon: the minimum equals the maximum, but the balloon driver still works and shows Proxmox how much the guest uses.
default:memory 512
meta: creation-qemu=11.0.3,ctime=1792984476
name: web1
nameserver: 1.1.1.1 9.9.9.9Housekeeping: the QEMU version and the VM’s creation time. From creation-qemu Proxmox picks defaults that can’t be changed on old VMs without risk to the guest.
net0: virtio=BC:24:11:5E:0A:11,bridge=vmbr0The network card: VirtIO model, MAC and bridge. BC:24:11 is the MAC prefix assigned to Proxmox. This is also where tag=20 (VLAN), firewall=1, link_down=1 (cable unplugged) and rate=10 (a limit in MB/s) go.
ostype: l26The guest OS type: l26 — Linux with kernel 2.6 or newer, win11 — Windows 11. Defaults depend on it: clock, drivers, Hyper-V timers for Windows.
parent: cleanThe last snapshot the current state descends from. The snapshots themselves are sections at the end of the file.
scsi0: local-lvm:vm-111-disk-0,discard=on,size=30G
scsihw: virtio-scsi-singleThe disk: volume vm-111-disk-0 on local-lvm, 30 GiB. discard=on — space freed in the guest returns to the thin pool (Disk discard). This is also where iothread=1 (the disk’s own I/O thread), ssd=1 (the guest sees an SSD) and backup=0 (don’t back up) go.
serial0: socketA console over the serial port instead of a screen — that’s what cloud images expect. In the UI it’s the xterm.js console, in the host shell qm terminal 111.
smbios1: uuid=5ade58c1-a526-4307-9df4-63af1ca1579eThe VM’s identifiers: a UUID for SMBIOS — the guest sees it as the board’s serial number — and vmgenid, which changes on a snapshot rollback: it’s how Windows and domain controllers learn they’ve been “sent back in time”.
sshkeys: ssh-ed25519%20AAAAC3Nza…%20example-user%40laptop%0A
vga: serial0
vmgenid: ad11b406-3076-4031-aca6-dda9956c1de8SSH keys for cloud-init — URL-encoded: a space is written as %20, a newline as %0A. Awkward to edit by hand, so use qm set 111 --sshkeys file.pub.
[clean]
agent: enabled=1
boot: order=scsi0
…
description: Ubuntu 24.04 after the first boot
snaptime: 1792985517The clean snapshot: a copy of the config at snapshot time and the time in Unix seconds. The storage holds the snapshot’s disks; the file has only the description. vmstate (if the snapshot includes memory) is a volume with the memory contents.
balloon: 1024The minimum memory for balloon: when idle the guest returns everything above 1024 MiB to the host, and under load takes it back up to memory.
onboot: 1
startup: order=2,up=30Autostart after the host boots, and the order: this VM is 2nd in line, and the next one starts 30 s after it. A router in a VM gets order=1.
bios: ovmf
efidisk0: local-lvm:vm-111-disk-1,efitype=4m,pre-enrolled-keys=1,size=4M
machine: q35
tpmstate0: local-lvm:vm-111-disk-2,size=4M,version=v2.0UEFI instead of SeaBIOS: needed for Windows 11 and GPU passthrough. efidisk0 holds the UEFI variables, tpmstate0 is a virtual TPM 2.0, q35 is a chipset with a PCIe bus.
hostpci0: 0000:01:00.0,pcie=1Passing a whole PCIe device — a GPU or a controller — into the VM. The host no longer sees it; a VM with such a device can’t be live-migrated.
lock: backupA lock marker: while a backup, snapshot or clone is running. Left behind after a failure — qm unlock 111.
If it doesn’t work
Changed the memory or CPU of a running VM — inside everything is as before
- Cause
- Some settings can’t change on the fly. Proxmox writes them to the config’s
[PENDING]section, and they apply on the next start of the VM process. A reboot from inside the guest doesn’t restart the process. - Fix
qm pending 111shows what’s waiting to apply. Apply withqm reboot 111or by shutting down and starting from Proxmox.
A manual edit of the file disappeared, or the VM reports parse error
- Cause
- A typo in a key or value: Proxmox skips a line it doesn’t understand and logs an error.
- Fix
- Edit through
qm set— it validates values. After a manual edit runqm config 111: parse errors show up in the output right away.
The VM can’t be started: VM is locked (snapshot)
- Cause
- The config still has a
lock: snapshot(orbackup,clone) line from an operation that was cut off. - Fix
- Make sure in Tasks that the operation isn’t running, and remove it:
qm unlock 111. Thelock:line goes away from the file.
Linux in the VM says Fatal glibc error: CPU does not support x86-64-v3
- Cause
- There’s no
cpu:line in the config — so the type is the defaultx86-64-v2-AES, without AVX2, and the system is built for x86-64-v3 (RHEL 10 and its clones). - Fix
qm set 111 --cpu x86-64-v3, or--cpu hostif the host CPU supports AVX2 (Hardware for Proxmox).
How to check
qm config 111 # same as the file, without snapshot sections
qm pending 111 # current values and those waiting for a restart
qm showcmd 111 --pretty # the kvm command line Proxmox builds from the config
qm cloudinit dump 111 user # what cloud-init will get: user, keys
qm showcmd is the most honest check: it shows which devices and options the VM will start with in practice. The config
describes what’s wanted; this command shows what QEMU gets.