basforge

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

    RU

    qemu-guest-agent in every Proxmox VM, plus the Guest Agent option on the VM

    The guest agent is a service inside the VM that Proxmox talks to: it shuts the VM down cleanly, sees its addresses and freezes the file system for the second of the snapshot, so the backup is consistent. Without the agent Proxmox shuts the VM down with an ACPI button the guest may ignore, and the backup looks like a sudden power loss. Install the package in the guest and enable the option on the VM — you need both.

    The agent works over its own channel — a virtual virtio-serial port — not over the network. So it takes two parts: the port on the Proxmox side (the VM option) and the service on the guest side (the package).

    What the agent gives you:

    Without the agent With the agent
    shutdown is an ACPI button; a guest without acpid or with a hung process doesn’t hear it shutdown is a command to the agent, like poweroff from inside
    the backup captures the disk mid-write, as in a sudden power loss the file system is frozen for the snapshot: fs-freeze, snapshot, fs-thaw
    the VM’s address isn’t shown in the UI the VM’s Summary shows its addresses; qm guest cmd 101 network-get-interfaces
    a command in the guest — over SSH only qm guest exec 101 -- systemctl status nginx from the host

    How to turn it on

    In the guest (Ubuntu and Debian):

    sudo apt install -y qemu-guest-agent
    sudo systemctl start qemu-guest-agent

    On the VM — Options › QEMU Guest Agent › Use QEMU Guest Agent, or:

    qm set 101 --agent enabled=1

    If the option was enabled on a running VM, the channel appears only after its process restarts: qm reboot 101 or power off and on from Proxmox — a reboot from inside the guest won’t do. In the cloud-init template the agent and the option are on from the start, once for all clones (VM template with cloud-init).

    On Windows the agent comes from the VirtIO driver disk (virtio-win.iso): the qemu-ga-x86_64.msi installer in the guest-agent directory, along with the VirtIO drivers.

    If it doesn’t work

    qm shutdown 101 fails: QEMU guest agent is not running

    Cause
    The agent option is on for the VM, but the agent isn’t installed or running in the guest. Proxmox shuts down through the agent and waits for an answer.
    Fix
    Install and start the agent in the guest. If the VM has to be off right now, shut it down from inside, sudo poweroff over SSH, or qm stop 101 if nothing is writing in the guest.

    The backup log says: skipping guest-agent 'fs-freeze', agent configured but not running?

    Cause
    The agent option is on, but the agent in the guest doesn’t answer: the backup runs without a freeze, and a database inside may be caught mid-write.
    Fix
    systemctl status qemu-guest-agent in the guest; after installing the package on an older guest, restart the VM from Proxmox so the agent channel appears.

    How to check

    qm guest cmd 101 ping                     # empty output and exit code 0
    qm guest cmd 101 get-osinfo               # name and version of the guest OS
    qm guest cmd 101 fsfreeze-status          # thawed — the file system isn't frozen

    The VM’s next backup log shows issuing guest-agent 'fs-freeze' command followed by fs-thaw (Backups in Proxmox).