target/ppc: Fix slbia TLB invalidation gap
[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`` (``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``)
46
47 .. option:: -l, --logfile=PATH
48
49   Set log file path (default is stderr).
50
51 .. option:: -f, --pidfile=PATH
52
53   Specify pid file (default is ``/var/run/qemu-ga.pid``).
54
55 .. option:: -F, --fsfreeze-hook=PATH
56
57   Enable fsfreeze hook. Accepts an optional argument that specifies
58   script to run on freeze/thaw. Script will be called with
59   'freeze'/'thaw' arguments accordingly (default is
60   |CONFDIR|\ ``/fsfreeze-hook``). If using -F with an argument, do
61   not follow -F with a space (for example:
62   ``-F/var/run/fsfreezehook.sh``).
63
64 .. option:: -t, --statedir=PATH
65
66   Specify the directory to store state information (absolute paths only,
67   default is ``/var/run``).
68
69 .. option:: -v, --verbose
70
71   Log extra debugging information.
72
73 .. option:: -V, --version
74
75   Print version information and exit.
76
77 .. option:: -d, --daemon
78
79   Daemonize after startup (detach from terminal).
80
81 .. option:: -b, --blacklist=LIST
82
83   Comma-separated list of RPCs to disable (no spaces, ``?`` to list
84   available RPCs).
85
86 .. option:: -D, --dump-conf
87
88   Dump the configuration in a format compatible with ``qemu-ga.conf``
89   and exit.
90
91 .. option:: -h, --help
92
93   Display this help and exit.
94
95 Files
96 -----
97
98
99 The syntax of the ``qemu-ga.conf`` configuration file follows the
100 Desktop Entry Specification, here is a quick summary: it consists of
101 groups of key-value pairs, interspersed with comments.
102
103 ::
104
105     # qemu-ga configuration sample
106     [general]
107     daemonize = 0
108     pidfile = /var/run/qemu-ga.pid
109     verbose = 0
110     method = virtio-serial
111     path = /dev/virtio-ports/org.qemu.guest_agent.0
112     statedir = /var/run
113
114 The list of keys follows the command line options:
115
116 =============  ===========
117 Key             Key type
118 =============  ===========
119 daemon         boolean
120 method         string
121 path           string
122 logfile        string
123 pidfile        string
124 fsfreeze-hook  string
125 statedir       string
126 verbose        boolean
127 blacklist      string list
128 =============  ===========
129
130 See also
131 --------
132
133 :manpage:`qemu(1)`