Guest agent

Servers created from our OS templates run the QEMU guest agent (qemu-guest-agent). It is a small service inside your server that the hypervisor can talk to. We use it to freeze the filesystem during backups, to read disk space and memory for Monitoring, and to grow the filesystem when auto-extend is on.

The agent is on by default, because backups, Monitoring and auto-extend depend on it to work correctly. You can turn it off at any time, see How to turn it off.

This page lists every command we send to it and when. If a command is not on this page, we do not call it.

What it is

It is the stock qemu-guest-agent package from your distribution's own repositories, the same one you get with apt install qemu-guest-agent or dnf install qemu-guest-agent. We do not build it, patch it or ship our own version. It updates with the rest of your system.

There is one change on RHEL-family templates (AlmaLinux, Rocky Linux, CentOS Stream, Oracle Linux). There the package comes with a list of disabled commands in /etc/sysconfig/qemu-ga, and we clear that list with /etc/sysconfig/qemu-ga-scamp so the agent has the same commands as on Debian or Ubuntu. The binary is untouched.

The agent does not listen on the network. It talks over a virtio-serial channel (org.qemu.guest_agent.0) that only the hypervisor your server runs on can open. Nothing on the internet or in your private network can reach it.

The agent and everything on this page that depends on it work only on servers created from our OS templates. A server installed from your own ISO has no agent, so its backups are crash-consistent, Monitoring shows only what the hypervisor sees, and auto-extend is not available.

Why we use it

• Consistent backups. Before a snapshot or backup we ask the guest to flush and freeze its filesystems, so the copy is clean. See Filesystem freeze.
• Monitoring. From outside we only see CPU, disk I/O and network. Disk space, memory and load exist only inside the server.
• Auto-extend. A bigger disk is not enough, the partition and filesystem inside have to grow too.
• Password on a cloned server. A server created from a snapshot or backup carries the old cloud-init state, so cloud-init does not set the new password. The agent does.

Every command we send

With verified backups we also boot a copy of the backup on our side and send guest-ping to the agent in that copy, to confirm the restored system starts. That is a separate throwaway machine, not your running server.

What we do not do

Through the agent's file commands we read only the five /proc files listed above. We do not write files through the agent, list users, processes or network interfaces, or look at logs and shell history. The only thing we ever execute is the grow script, and only on a server where you turned auto-extend on.

The agent itself can do more than we use, for example run any command as root. That is how upstream qemu-guest-agent works. If you want the agent but not those commands, block them as shown in Block some commands.

Filesystem freeze and backups

A disk copy taken from a running server without any help from the guest is crash-consistent. It looks like the disk after a power cut. Data still in the page cache is missing, and the filesystem needs a journal replay at the next boot. Most of the time that works. Sometimes the last seconds of writes are gone or a file is half written.

With the agent we take a filesystem-consistent copy:

1. We send guest-fsfreeze-freeze. The kernel writes all dirty data to disk and holds new writes on every mounted filesystem.
2. We take an instant point-in-time snapshot of the disk in the storage cluster.
3. We send guest-fsfreeze-thaw and writes continue.

Only the instant snapshot happens inside the freeze. The long part (reading, compressing, encrypting and uploading a backup) runs afterwards from that snapshot while your server works normally. Writes pause during the freeze and resume after the thaw.

There are two safety limits. If the freeze does not answer in 20 seconds, we send the thaw anyway. If the agent is off or missing, we skip the freeze and take a crash-consistent copy, and the backup still runs.

Databases survive a crash-consistent copy through their own journal (WAL in PostgreSQL, redo log in InnoDB). Freezing makes the filesystem consistent, but it does not shut the database down, so PostgreSQL still replays WAL when it starts from a restored copy. A checkpoint before the freeze makes that recovery shorter. To run one, the agent can call hook scripts before the freeze and after the thaw (the fsfreeze-hook option of qemu-ga). Where the scripts go and whether the hook is on by default depends on your distribution's package.

How to turn it off

In the Cloud Panel

Server page, Overview, Agent & monitoring. There are three switches and each needs the one above it:

• Guest agent. Off means we send the agent nothing at all, not even guest-info.
• Monitoring. Off means we still check that the agent answers and still freeze for backups, but read no stats from inside. The server leaves the Monitoring page and its alerts close. CPU, disk I/O and network charts on the server's own page stay, we read them from the hypervisor.
• Auto-extend. Off means we never run the grow script.

The switch takes effect within a minute, the agent inside keeps running but gets no calls from us.

Inside the operating system

Stop it and keep it stopped after reboot:

# Debian, Ubuntu, RHEL family, openSUSE, Arch
sudo systemctl disable --now qemu-guest-agent

# Alpine
sudo rc-service qemu-guest-agent stop
sudo rc-update del qemu-guest-agent

Or remove it:

sudo apt remove qemu-guest-agent      # Debian, Ubuntu
sudo dnf remove qemu-guest-agent      # AlmaLinux, Rocky, CentOS Stream, Oracle, Fedora
sudo zypper remove qemu-guest-agent   # openSUSE
sudo apk del qemu-guest-agent         # Alpine

Within a minute the Overview shows the agent as not responding. If you have an alert rule for it, you get one "Guest agent not responding" alert. Turn the Guest agent switch off in the Cloud Panel and that alert closes and does not come back.

Block some commands

You can keep the freeze for backups and block everything that runs commands or reads files. On Debian, Ubuntu, openSUSE, Arch and Alpine add this to /etc/qemu/qemu-ga.conf:

[general]
block-rpcs=guest-exec,guest-exec-status,guest-file-open,guest-file-read,guest-file-write,guest-file-close

On the RHEL family put the same list into /etc/sysconfig/qemu-ga-scamp:

FILTER_RPC_ARGS="--block-rpcs=guest-exec,guest-exec-status,guest-file-open,guest-file-read,guest-file-write,guest-file-close"

Then restart the agent with sudo systemctl restart qemu-guest-agent, or sudo rc-service qemu-guest-agent restart on Alpine. Memory, OOM and pressure charts and alerts stop working, and auto-extend fails once and turns itself off.

What stops working without the agent