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 If an allowed RPCs list is defined in the configuration, then all
  32 RPCs will be blocked by default, except for the allowed list.
  33
  34 If a blocked RPCs list is defined in the configuration, then all
  35 RPCs will be allowed by default, except for the blocked list.
  36
  37 If both allowed and blocked RPCs lists are defined in the configuration,
  38 then all RPCs will be blocked by default, then the allowed list will
  39 be applied, followed by the blocked list.
  40
  41 While filesystems are frozen, all except for a designated safe set
  42 of RPCs will blocked, regardless of what the general configuration
  43 declares.
  44
  45 Options
  46 -------
  47
  48 .. program:: qemu-ga
  49
  50 .. option:: -c, --config=PATH
  51
  52   Configuration file path (the default is |CONFDIR|\ ``/qemu-ga.conf``,
  53   unless overridden by the QGA_CONF environment variable)
  54
  55 .. option:: -m, --method=METHOD
  56
  57   Transport method: one of ``unix-listen``, ``virtio-serial``, or
  58   ``isa-serial``, or ``vsock-listen`` (``virtio-serial`` is the default).
  59
  60 .. option:: -p, --path=PATH
  61
  62   Device/socket path (the default for virtio-serial is
  63   ``/dev/virtio-ports/org.qemu.guest_agent.0``,
  64   the default for isa-serial is ``/dev/ttyS0``). Socket addresses for
  65   vsock-listen are written as ``<cid>:<port>``.
  66
  67 .. option:: -l, --logfile=PATH
  68
  69   Set log file path (default is stderr).
  70
  71 .. option:: -f, --pidfile=PATH
  72
  73   Specify pid file (default is ``/var/run/qemu-ga.pid``).
  74
  75 .. option:: -F, --fsfreeze-hook=PATH
  76
  77   Enable fsfreeze hook. Accepts an optional argument that specifies
  78   script to run on freeze/thaw. Script will be called with
  79   'freeze'/'thaw' arguments accordingly (default is
  80   |CONFDIR|\ ``/fsfreeze-hook``). If using -F with an argument, do
  81   not follow -F with a space (for example:
  82   ``-F/var/run/fsfreezehook.sh``).
  83
  84 .. option:: -t, --statedir=PATH
  85
  86   Specify the directory to store state information (absolute paths only,
  87   default is ``/var/run``).
  88
  89 .. option:: -v, --verbose
  90
  91   Log extra debugging information.
  92
  93 .. option:: -V, --version
  94
  95   Print version information and exit.
  96
  97 .. option:: -d, --daemon
  98
  99   Daemonize after startup (detach from terminal).
 100
 101 .. option:: -b, --block-rpcs=LIST
 102
 103   Comma-separated list of RPCs to disable (no spaces, use ``--block-rpcs=help``
 104   to list available RPCs).
 105
 106 .. option:: -a, --allow-rpcs=LIST
 107
 108   Comma-separated list of RPCs to enable (no spaces, use ``--allow-rpcs=help``
 109   to list available RPCs).
 110
 111 .. option:: -D, --dump-conf
 112
 113   Dump the configuration in a format compatible with ``qemu-ga.conf``
 114   and exit.
 115
 116 .. option:: -h, --help
 117
 118   Display this help and exit.
 119
 120 Files
 121 -----
 122
 123
 124 The syntax of the ``qemu-ga.conf`` configuration file follows the
 125 Desktop Entry Specification, here is a quick summary: it consists of
 126 groups of key-value pairs, interspersed with comments.
 127
 128 ::
 129
 130     # qemu-ga configuration sample
 131     [general]
 132     daemonize = 0
 133     pidfile = /var/run/qemu-ga.pid
 134     verbose = 0
 135     method = virtio-serial
 136     path = /dev/virtio-ports/org.qemu.guest_agent.0
 137     statedir = /var/run
 138
 139 The list of keys follows the command line options:
 140
 141 =============  ===========
 142 Key             Key type
 143 =============  ===========
 144 daemon         boolean
 145 method         string
 146 path           string
 147 logfile        string
 148 pidfile        string
 149 fsfreeze-hook  string
 150 statedir       string
 151 verbose        boolean
 152 block-rpcs     string list
 153 allow-rpcs     string list
 154 =============  ===========
 155
 156 See also
 157 --------
 158
 159 :manpage:`qemu(1)`