DOKK / manpages / debian 12 / qemu-guest-agent / qemu-ga.8.en
QEMU-GA(8) QEMU QEMU-GA(8)

qemu-ga - QEMU Guest Agent

qemu-ga [OPTIONS]

The QEMU Guest Agent is a daemon intended to be run within virtual machines. It allows the hypervisor host to perform various operations in the guest, such as:

  • 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
  • ...

qemu-ga will read a system configuration file on startup (located at /etc/qemu/qemu-ga.conf by default), then parse remaining configuration options on the command line. For the same key, the last option wins, but the lists accumulate (see below for configuration file format).

Transport method: one of unix-listen, virtio-serial, or isa-serial, or vsock-listen (virtio-serial is the default).

Device/socket path (the default for virtio-serial is /dev/virtio-ports/org.qemu.guest_agent.0, the default for isa-serial is /dev/ttyS0). Socket addresses for vsock-listen are written as <cid>:<port>.

Set log file path (default is stderr).

Specify pid file (default is /var/run/qemu-ga.pid).

Enable fsfreeze hook. Accepts an optional argument that specifies script to run on freeze/thaw. Script will be called with 'freeze'/'thaw' arguments accordingly (default is /etc/qemu/fsfreeze-hook). If using -F with an argument, do not follow -F with a space (for example: -F/var/run/fsfreezehook.sh).

Specify the directory to store state information (absolute paths only, default is /var/run).

Log extra debugging information.

Print version information and exit.

Daemonize after startup (detach from terminal).

Comma-separated list of RPCs to disable (no spaces, use help to list available RPCs).

Dump the configuration in a format compatible with qemu-ga.conf and exit.

Display this help and exit.

The syntax of the qemu-ga.conf configuration file follows the Desktop Entry Specification, here is a quick summary: it consists of groups of key-value pairs, interspersed with comments.

# 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


The list of keys follows the command line options:

Key Key type
daemon boolean
method string
path string
logfile string
pidfile string
fsfreeze-hook string
statedir string
verbose boolean
block-rpcs string list

qemu(1)

Michael Roth <mdroth@linux.vnet.ibm.com>

2024, The QEMU Project Developers

February 6, 2024 7.2.9