basforge

Search titles, text and the “If it doesn’t work” cases.

    RU

    A Proxmox virtual machine config line by line: /etc/pve/qemu-server/111.conf

    A VM in Proxmox is a text file /etc/pve/qemu-server/<number>.conf: CPU, memory, disks, network, cloud-init and snapshots, one line per setting. The UI and qm set write it, but it pays to read it yourself: it shows what the VM will get on its next start, where its disks are and what goes into the backup.

    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

    /etc/pve/qemu-server/111.conf
    agent: enabled=1

    The 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=scsi0

    Which disk to boot from. A list separated by ;: order=scsi0;ide2;net0 — disk first, then CD, then network.

    ciuser: example-user

    The user cloud-init creates on the first boot, with passwordless sudo.

    cores: 2
    cpu: host
    Key part

    Cores 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.1

    The 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: 2048

    Memory 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.9

    Housekeeping: 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=vmbr0

    The 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: l26

    The 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: clean

    The 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-single
    Key part

    The 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: socket

    A 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-63af1ca1579e

    The 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-dda9956c1de8

    SSH 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: 1792985517

    The 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: 1024

    The 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=30

    Autostart 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.0

    UEFI 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=1

    Passing 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: backup

    A 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 111 shows what’s waiting to apply. Apply with qm reboot 111 or 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 run qm 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 (or backup, 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. The lock: 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 default x86-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 host if 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.