qemu-ga.rst (3215B)
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:: -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 block-rpcs string list 129 ============= =========== 130 131 See also 132 -------- 133 134 :manpage:`qemu(1)`