configure: move accelerator logic to meson
[qemu.git] / docs / interop / qemu-ga.rst
1 QEMU Guest Agent
2 ================
3
4 Synopsis
5 --------
6
7 **qemu-ga** [*OPTIONS*]
8
9 Description
10 -----------
11
12 The QEMU Guest Agent is a daemon intended to be run within virtual
13 machines. It allows the hypervisor host to perform various operations
14 in 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
25 qemu-ga will read a system configuration file on startup (located at
26 |CONFDIR|\ ``/qemu-ga.conf`` by default), then parse remaining
27 configuration options on the command line. For the same key, the last
28 option wins, but the lists accumulate (see below for configuration
29 file format).
30
31 Options
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
96 Files
97 -----
98
99
100 The syntax of the ``qemu-ga.conf`` configuration file follows the
101 Desktop Entry Specification, here is a quick summary: it consists of
102 groups 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
115 The list of keys follows the command line options:
116
117 =============  ===========
118 Key             Key type
119 =============  ===========
120 daemon         boolean
121 method         string
122 path           string
123 logfile        string
124 pidfile        string
125 fsfreeze-hook  string
126 statedir       string
127 verbose        boolean
128 blacklist      string list
129 =============  ===========
130
131 See also
132 --------
133
134 :manpage:`qemu(1)`