docs/interop/qemu-ga.rst

1 .. _qemu-ga:
3 QEMU Guest Agent
7 --------
9 **qemu-ga** [*OPTIONS*]
12 -----------
14 The QEMU Guest Agent is a daemon intended to be run within virtual
16 in the guest, such as:
18 - get information from the guest
19 - set the guest's system time
20 - read/write a file
21 - sync and freeze the filesystems
22 - suspend the guest
23 - reconfigure guest local processors
24 - set user's password
25 - ...
27 qemu-ga will read a system configuration file on startup (located at
28 |CONFDIR|\ ``/qemu-ga.conf`` by default), then parse remaining
48 -------
50 .. program:: qemu-ga
52 .. option:: -c, --config=PATH
54   Configuration file path (the default is |CONFDIR|\ ``/qemu-ga.conf``,
57 .. option:: -m, --method=METHOD
59   Transport method: one of ``unix-listen``, ``virtio-serial``, or
60   ``isa-serial``, or ``vsock-listen`` (``virtio-serial`` is the default).
62 .. option:: -p, --path=PATH
64   Device/socket path (the default for virtio-serial is
65   ``/dev/virtio-ports/org.qemu.guest_agent.0``,
66   the default for isa-serial is ``/dev/ttyS0``). Socket addresses for
67   vsock-listen are written as ``<cid>:<port>``.
69 .. option:: -l, --logfile=PATH
73 .. option:: -f, --pidfile=PATH
75   Specify pid file (default is ``/var/run/qemu-ga.pid``).
77 .. option:: -F, --fsfreeze-hook=PATH
82   |CONFDIR|\ ``/fsfreeze-hook``). If using -F with an argument, do
83   not follow -F with a space (for example:
84   ``-F/var/run/fsfreezehook.sh``).
86 .. option:: -t, --statedir=PATH
91 .. option:: -v, --verbose
95 .. option:: -V, --version
99 .. option:: -d, --daemon
103 .. option:: -b, --block-rpcs=LIST
105   Comma-separated list of RPCs to disable (no spaces, use ``--block-rpcs=help``
108 .. option:: -a, --allow-rpcs=LIST
110   Comma-separated list of RPCs to enable (no spaces, use ``--allow-rpcs=help``
113 .. option:: -D, --dump-conf
115   Dump the configuration in a format compatible with ``qemu-ga.conf``
118 .. option:: -h, --help
123 -----
126 The syntax of the ``qemu-ga.conf`` configuration file follows the
128 groups of key-value pairs, interspersed with comments.
132     # qemu-ga configuration sample
135     pidfile = /var/run/qemu-ga.pid
137     method = virtio-serial
138     path = /dev/virtio-ports/org.qemu.guest_agent.0
151 fsfreeze-hook  string
154 block-rpcs     string list
155 allow-rpcs     string list
159 --------