diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/conf.py | 18 | ||||
| -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 |
4 files changed, 151 insertions, 8 deletions
diff --git a/docs/conf.py b/docs/conf.py index e46b299b71..b7edb0666b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -115,6 +115,14 @@ todo_include_todos = False # with "option::" in the document being processed. Turn that off. suppress_warnings = ["ref.option"] +# The rst_epilog fragment is effectively included in every rST file. +# We use it to define substitutions based on build config that +# can then be used in the documentation. The fallback if the +# environment variable is not set is for the benefit of readthedocs +# style document building; our Makefile always sets the variable. +confdir = os.getenv('CONFDIR', "/etc/qemu") +rst_epilog = ".. |CONFDIR| replace:: ``" + confdir + "``\n" + # -- Options for HTML output ---------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for @@ -192,14 +200,8 @@ latex_documents = [ # -- Options for manual page output --------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - (master_doc, 'qemu', u'QEMU Documentation', - [author], 1) -] - +# Individual manual/conf.py can override this to create man pages +man_pages = [] # -- Options for Texinfo output ------------------------------------------- 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)` |