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, --block-rpcs=LIST
  83
  84   Comma-separated list of RPCs to disable (no spaces, use ``help`` to
  85   list available RPCs).
  86
  87 .. option:: -a, --allow-rpcs=LIST
  88
  89   Comma-separated list of RPCs to enable (no spaces, use ``help`` to
  90   list available RPCs).
  91
  92 .. option:: -D, --dump-conf
  93
  94   Dump the configuration in a format compatible with ``qemu-ga.conf``
  95   and exit.
  96
  97 .. option:: -h, --help
  98
  99   Display this help and exit.
 100
 101 Files
 102 -----
 103
 104
 105 The syntax of the ``qemu-ga.conf`` configuration file follows the
 106 Desktop Entry Specification, here is a quick summary: it consists of
 107 groups of key-value pairs, interspersed with comments.
 108
 109 ::
 110
 111     # qemu-ga configuration sample
 112     [general]
 113     daemonize = 0
 114     pidfile = /var/run/qemu-ga.pid
 115     verbose = 0
 116     method = virtio-serial
 117     path = /dev/virtio-ports/org.qemu.guest_agent.0
 118     statedir = /var/run
 119
 120 The list of keys follows the command line options:
 121
 122 =============  ===========
 123 Key             Key type
 124 =============  ===========
 125 daemon         boolean
 126 method         string
 127 path           string
 128 logfile        string
 129 pidfile        string
 130 fsfreeze-hook  string
 131 statedir       string
 132 verbose        boolean
 133 block-rpcs     string list
 134 =============  ===========
 135
 136 See also
 137 --------
 138
 139 :manpage:`qemu(1)`