diff options
author | Peter Maydell <peter.maydell@linaro.org> | 2019-09-05 14:10:40 +0100 |
---|---|---|
committer | Peter Maydell <peter.maydell@linaro.org> | 2019-09-13 16:05:01 +0100 |
commit | 27a296fce9821e3608d537756cffa6e43a46df3b (patch) | |
tree | 94d994cf59d73fbaed5a6dab26d4f751b0355fc4 /docs/interop | |
parent | d2fac5f678559474134bf1f5915a0bb58d946433 (diff) |
qemu-ga: Convert invocation documentation to rST
The qemu-ga documentation is currently in qemu-ga.texi in
Texinfo format, which we present to the user as:
* a qemu-ga manpage
* a section of the main qemu-doc HTML documentation
Convert the documentation to rST format, and present it to
the user as:
* a qemu-ga manpage
* part of the interop/ Sphinx manual
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Michael Roth <mdroth@linux.vnet.ibm.com>
Tested-by: Michael Roth <mdroth@linux.vnet.ibm.com>
Message-id: 20190905131040.8350-1-peter.maydell@linaro.org
Diffstat (limited to 'docs/interop')
-rw-r--r-- | docs/interop/conf.py | 7 | ||||
-rw-r--r-- | docs/interop/index.rst | 1 | ||||
-rw-r--r-- | docs/interop/qemu-ga.rst | 133 |
3 files changed, 141 insertions, 0 deletions
diff --git a/docs/interop/conf.py b/docs/interop/conf.py index cf3c69d4a7..e87b8c22be 100644 --- a/docs/interop/conf.py +++ b/docs/interop/conf.py @@ -13,3 +13,10 @@ exec(compile(open(parent_config, "rb").read(), parent_config, 'exec')) # This slightly misuses the 'description', but is the best way to get # the manual title to appear in the sidebar. html_theme_options['description'] = u'System Emulation Management and Interoperability Guide' + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('qemu-ga', 'qemu-ga', u'QEMU Guest Agent', + ['Michael Roth <mdroth@linux.vnet.ibm.com>'], 8) +] diff --git a/docs/interop/index.rst b/docs/interop/index.rst index b4bfcab417..3e33fb5933 100644 --- a/docs/interop/index.rst +++ b/docs/interop/index.rst @@ -15,5 +15,6 @@ Contents: bitmaps live-block-operations pr-helper + qemu-ga vhost-user vhost-user-gpu diff --git a/docs/interop/qemu-ga.rst b/docs/interop/qemu-ga.rst new file mode 100644 index 0000000000..1313a4ae1c --- /dev/null +++ b/docs/interop/qemu-ga.rst @@ -0,0 +1,133 @@ +QEMU Guest Agent +================ + +Synopsis +-------- + +**qemu-ga** [*OPTIONS*] + +Description +----------- + +The QEMU Guest Agent is a daemon intended to be run within virtual +machines. It allows the hypervisor host to perform various operations +in the guest, such as: + +- get information from the guest +- set the guest's system time +- read/write a file +- sync and freeze the filesystems +- suspend the guest +- reconfigure guest local processors +- set user's password +- ... + +qemu-ga will read a system configuration file on startup (located at +|CONFDIR|\ ``/qemu-ga.conf`` by default), then parse remaining +configuration options on the command line. For the same key, the last +option wins, but the lists accumulate (see below for configuration +file format). + +Options +------- + +.. program:: qemu-ga + +.. option:: -m, --method=METHOD + + Transport method: one of ``unix-listen``, ``virtio-serial``, or + ``isa-serial`` (``virtio-serial`` is the default). + +.. option:: -p, --path=PATH + + Device/socket path (the default for virtio-serial is + ``/dev/virtio-ports/org.qemu.guest_agent.0``, + the default for isa-serial is ``/dev/ttyS0``) + +.. option:: -l, --logfile=PATH + + Set log file path (default is stderr). + +.. option:: -f, --pidfile=PATH + + Specify pid file (default is ``/var/run/qemu-ga.pid``). + +.. option:: -F, --fsfreeze-hook=PATH + + Enable fsfreeze hook. Accepts an optional argument that specifies + script to run on freeze/thaw. Script will be called with + 'freeze'/'thaw' arguments accordingly (default is + |CONFDIR|\ ``/fsfreeze-hook``). If using -F with an argument, do + not follow -F with a space (for example: + ``-F/var/run/fsfreezehook.sh``). + +.. option:: -t, --statedir=PATH + + Specify the directory to store state information (absolute paths only, + default is ``/var/run``). + +.. option:: -v, --verbose + + Log extra debugging information. + +.. option:: -V, --version + + Print version information and exit. + +.. option:: -d, --daemon + + Daemonize after startup (detach from terminal). + +.. option:: -b, --blacklist=LIST + + Comma-separated list of RPCs to disable (no spaces, ``?`` to list + available RPCs). + +.. option:: -D, --dump-conf + + Dump the configuration in a format compatible with ``qemu-ga.conf`` + and exit. + +.. option:: -h, --help + + Display this help and exit. + +Files +----- + + +The syntax of the ``qemu-ga.conf`` configuration file follows the +Desktop Entry Specification, here is a quick summary: it consists of +groups of key-value pairs, interspersed with comments. + +:: + + # qemu-ga configuration sample + [general] + daemonize = 0 + pidfile = /var/run/qemu-ga.pid + verbose = 0 + method = virtio-serial + path = /dev/virtio-ports/org.qemu.guest_agent.0 + statedir = /var/run + +The list of keys follows the command line options: + +============= =========== +Key Key type +============= =========== +daemon boolean +method string +path string +logfile string +pidfile string +fsfreeze-hook string +statedir string +verbose boolean +blacklist string list +============= =========== + +See also +-------- + +:manpage:`qemu(1)` |