scripts/clean-includes: Skip symbolic links
[qemu/armbru.git] / docs / interop / qemu-ga.rst
bloba9183802d107383af8d2cbc8f94059491925af56
1 QEMU Guest Agent
2 ================
4 Synopsis
5 --------
7 **qemu-ga** [*OPTIONS*]
9 Description
10 -----------
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:
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 - ...
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).
31 Options
32 -------
34 .. program:: qemu-ga
36 .. option:: -m, --method=METHOD
38   Transport method: one of ``unix-listen``, ``virtio-serial``, or
39   ``isa-serial``, or ``vsock-listen`` (``virtio-serial`` is the default).
41 .. option:: -p, --path=PATH
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>``.
48 .. option:: -l, --logfile=PATH
50   Set log file path (default is stderr).
52 .. option:: -f, --pidfile=PATH
54   Specify pid file (default is ``/var/run/qemu-ga.pid``).
56 .. option:: -F, --fsfreeze-hook=PATH
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``).
65 .. option:: -t, --statedir=PATH
67   Specify the directory to store state information (absolute paths only,
68   default is ``/var/run``).
70 .. option:: -v, --verbose
72   Log extra debugging information.
74 .. option:: -V, --version
76   Print version information and exit.
78 .. option:: -d, --daemon
80   Daemonize after startup (detach from terminal).
82 .. option:: -b, --block-rpcs=LIST
84   Comma-separated list of RPCs to disable (no spaces, use ``help`` to
85   list available RPCs).
87 .. option:: -D, --dump-conf
89   Dump the configuration in a format compatible with ``qemu-ga.conf``
90   and exit.
92 .. option:: -h, --help
94   Display this help and exit.
96 Files
97 -----
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.
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
115 The list of keys follows the command line options:
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 block-rpcs     string list
129 =============  ===========
131 See also
132 --------
134 :manpage:`qemu(1)`