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, --blacklist=LIST
  83
  84   Comma-separated list of RPCs to disable (no spaces, ``?`` to list
  85   available RPCs).
  86
  87 .. option:: -D, --dump-conf
  88
  89   Dump the configuration in a format compatible with ``qemu-ga.conf``
  90   and exit.
  91
  92 .. option:: -h, --help
  93
  94   Display this help and exit.
  95
  96 Files
  97 -----
  98
  99
 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.
 103
 104 ::
 105
 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
 114
 115 The list of keys follows the command line options:
 116
 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 blacklist      string list
 129 =============  ===========
 130
 131 See also
 132 --------
 133
 134 :manpage:`qemu(1)`