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)`