xref: /openbmc/qemu/docs/interop/qemu-ga.rst (revision 38472890)
1QEMU Guest Agent
2================
3
4Synopsis
5--------
6
7**qemu-ga** [*OPTIONS*]
8
9Description
10-----------
11
12The QEMU Guest Agent is a daemon intended to be run within virtual
13machines. It allows the hypervisor host to perform various operations
14in the guest, such as:
15
16- get information from the guest
17- set the guest's system time
18- read/write a file
19- sync and freeze the filesystems
20- suspend the guest
21- reconfigure guest local processors
22- set user's password
23- ...
24
25qemu-ga will read a system configuration file on startup (located at
26|CONFDIR|\ ``/qemu-ga.conf`` by default), then parse remaining
27configuration options on the command line. For the same key, the last
28option wins, but the lists accumulate (see below for configuration
29file format).
30
31Options
32-------
33
34.. program:: qemu-ga
35
36.. option:: -m, --method=METHOD
37
38  Transport method: one of ``unix-listen``, ``virtio-serial``, or
39  ``isa-serial``, or ``vsock-listen`` (``virtio-serial`` is the default).
40
41.. option:: -p, --path=PATH
42
43  Device/socket path (the default for virtio-serial is
44  ``/dev/virtio-ports/org.qemu.guest_agent.0``,
45  the default for isa-serial is ``/dev/ttyS0``). Socket addresses for
46  vsock-listen are written as ``<cid>:<port>``.
47
48.. option:: -l, --logfile=PATH
49
50  Set log file path (default is stderr).
51
52.. option:: -f, --pidfile=PATH
53
54  Specify pid file (default is ``/var/run/qemu-ga.pid``).
55
56.. option:: -F, --fsfreeze-hook=PATH
57
58  Enable fsfreeze hook. Accepts an optional argument that specifies
59  script to run on freeze/thaw. Script will be called with
60  'freeze'/'thaw' arguments accordingly (default is
61  |CONFDIR|\ ``/fsfreeze-hook``). If using -F with an argument, do
62  not follow -F with a space (for example:
63  ``-F/var/run/fsfreezehook.sh``).
64
65.. option:: -t, --statedir=PATH
66
67  Specify the directory to store state information (absolute paths only,
68  default is ``/var/run``).
69
70.. option:: -v, --verbose
71
72  Log extra debugging information.
73
74.. option:: -V, --version
75
76  Print version information and exit.
77
78.. option:: -d, --daemon
79
80  Daemonize after startup (detach from terminal).
81
82.. option:: -b, --blacklist=LIST
83
84  Comma-separated list of RPCs to disable (no spaces, ``?`` to list
85  available RPCs).
86
87.. option:: -D, --dump-conf
88
89  Dump the configuration in a format compatible with ``qemu-ga.conf``
90  and exit.
91
92.. option:: -h, --help
93
94  Display this help and exit.
95
96Files
97-----
98
99
100The syntax of the ``qemu-ga.conf`` configuration file follows the
101Desktop Entry Specification, here is a quick summary: it consists of
102groups of key-value pairs, interspersed with comments.
103
104::
105
106    # qemu-ga configuration sample
107    [general]
108    daemonize = 0
109    pidfile = /var/run/qemu-ga.pid
110    verbose = 0
111    method = virtio-serial
112    path = /dev/virtio-ports/org.qemu.guest_agent.0
113    statedir = /var/run
114
115The list of keys follows the command line options:
116
117=============  ===========
118Key             Key type
119=============  ===========
120daemon         boolean
121method         string
122path           string
123logfile        string
124pidfile        string
125fsfreeze-hook  string
126statedir       string
127verbose        boolean
128blacklist      string list
129=============  ===========
130
131See also
132--------
133
134:manpage:`qemu(1)`
135