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