QEMU-GA(8)

💅 qemu-ga — the QEMU Guest Agent, explained by your favorite Unix bestie

okay so this is page qemu-ga(8) from the QEMU manual set, and honestly? it's kind of a baddie. let's get into it ✨

---

🌸 NAME 🌸

qemu-ga — the QEMU Guest Agent. that's it, that's the whole name, and she ate 💅

---

🎀 SYNOPSIS 🎀

qemu-ga [OPTIONS]

that's literally it. options in, daemon out. no cap ✨

---

🦋 DESCRIPTION 🦋

so the QEMU Guest Agent is a daemon — like, a little background bestie — that's intended to be run within virtual machines. and the whole point of her existence is that she lets the hypervisor host do a bunch of operations inside the guest. the guest and the host are in a long-distance relationship and qemu-ga is the group chat 🫶

here's the vibe of what the host can do through her:

• get information from the guest
• set the guest's system time
• read/write a file
• sync and freeze the filesystems
• suspend the guest
• reconfigure guest local processors
• set user's password
• … and like, more. the "…" is doing a lot of work here and honestly? iconic. 👑

on startup, qemu-ga will read a system configuration file — the default lives at /etc/qemu/qemu-ga.conf — and then she parses the remaining configuration options on the command line. so it's conf file first, then CLI. and here's the rule for conflicts, bestie, write it down:

For the same key, the last option wins, but the lists accumulate. (there's a config file format section down in FILES, keep scrolling 💖)

now the RPC permission drama, which is genuinely the most main-character part of this whole page 🎭:

• If an allowed RPCs list is defined in the configuration, then all RPCs will be blocked by default, except for the allowed list. so it's a velvet rope situation — nope by default, yes only for the list 💅
• If a blocked RPCs list is defined in the configuration, then all RPCs will be allowed by default, except for the blocked list. opposite energy — everyone welcome except these people 🙈
• If both allowed and blocked RPCs lists are defined in the configuration, then all RPCs will be blocked by default, then the allowed list will be applied, followed by the blocked list. yes, order matters. blocked has the final say. she gets the last word, periodt 🔥

and one more thing, super important, not a drill:

While filesystems are frozen, all except for a designated safe set of RPCs will be blocked, regardless of what the general configuration declares. so the frozen state overrides your config, no exceptions, don't argue with her 💀

---

✨ OPTIONS ✨

okay bestie, here's the full roster. every single one. no skipping 🫶

• -c, --config=PATH — configuration file path. the default is /etc/qemu/qemu-ga.conf, unless it's overridden by the QGA_CONF environment variable 🌸
• -m, --method=METHOD — the transport method. one of unix-listen, virtio-serial, or isa-serial, or vsock-listen. virtio-serial is the default ⭐
• -p, --path=PATH — device/socket path. the default for virtio-serial is /dev/virtio-ports/org.qemu.guest_agent.0, and the default for isa-serial is /dev/ttyS0. and for vsock-listen, socket addresses are written as <cid>:<port> 🎀
• -l, --logfile=PATH — set the log file path. the default is stderr 💖
• -f, --pidfile=PATH — specify the pid file. the default is /var/run/qemu-ga.pid 🦋
• -F, --fsfreeze-hook=PATH — enable the fsfreeze hook. she accepts an optional argument that specifies the script to run on freeze/thaw. the script will be called with 'freeze'/'thaw' arguments accordingly. the default is /etc/qemu/fsfreeze-hook.

⚠️ real talk: if you're using -F with an argument, do not follow -F with a space. like literally do it like this: -F/var/run/fsfreezehook.sh. no space. i'm serious. 🙈

• -t, --statedir=PATH — specify the directory to store state information. absolute paths only, bestie. the default is /var/run 🌈
• -v, --verbose — log extra debugging information. she gets chatty. love that for her 💜
• -V, --version — print version information and exit 👋
• -d, --daemon — daemonize after startup, aka detach from the terminal. she's leaving the group chat to go be mysterious 🧚
• -b, --block-rpcs=LIST — comma-separated list of RPCs to disable. no spaces, and use --block-rpcs=help to list the available RPCs. very demure, very "here's the menu" 💅
• -a, --allow-rpcs=LIST — comma-separated list of RPCs to enable. again, no spaces, and use --allow-rpcs=help to list the available RPCs 🌸
• -D, --dump-conf — dump the configuration in a format compatible with qemu-ga.conf and exit. she's showing you her whole outfit and then leaving 🔥
• -h, --help — display this help and exit. the classic. the icon 👑

---

🌟 FILES 🌟

so the syntax of the qemu-ga.conf configuration file follows the Desktop Entry Specification. here's the quick summary, bestie: it consists of groups of key-value pairs, interspersed with comments. that's it, that's the whole format 🎀

# qemu-ga configuration sample
[general]
daemonize = 0
pidfile = /var/run/qemu-ga.pid
verbose = 0
method = virtio-serial
path = /dev/virtio-ports/org.qemu.guest_agent.0
statedir = /var/run

(copy that sample exactly btw, it's literally the one from the page — don't freestyle it 💖)

and the list of keys follows the command line options. here's the key + key type lineup, translated from the little box-table situation into a list so it reads pretty on your terminal 🦋

• daemon — key type: boolean
• method — key type: string
• path — key type: string
• logfile — key type: string
• pidfile — key type: string
• fsfreeze-hook — key type: string
• statedir — key type: string
• verbose — key type: boolean
• block-rpcs — key type: string list
• allow-rpcs — key type: string list

---

👀 SEE ALSO 👀

• qemu(1) — go read that one next, i'm obsessed with her 💜

---

🫶 Author 🫶

Michael Roth <mdroth@linux.vnet.ibm.com> — thank you for your service, king 👑

---

💖 Copyright 💖

2026, The QEMU Project Developers 🌈

---

okay that's the whole page, you're officially educated 💅 now go forth and freeze some filesystems (responsibly, bestie, and remember there's a safe set of RPCs while frozen whether you like it or not 😭).

this was qemu-ga out of version 11.1.3, dated Oct 29, 2026 — mwah, go slay ✨🍓