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
This commit is contained in:
Peter Maydell
parent
d2fac5f678
commit
27a296fce9
@ -2040,7 +2040,7 @@ QEMU Guest Agent
|
||||
M: Michael Roth <mdroth@linux.vnet.ibm.com>
|
||||
S: Maintained
|
||||
F: qga/
|
||||
F: qemu-ga.texi
|
||||
F: docs/interop/qemu-ga.rst
|
||||
F: scripts/qemu-guest-agent/
|
||||
F: tests/test-qga.c
|
||||
F: docs/interop/qemu-ga-ref.texi
|
||||
|
||||
24
Makefile
24
Makefile
@ -325,7 +325,7 @@ endif
|
||||
endif
|
||||
|
||||
ifdef BUILD_DOCS
|
||||
DOCS=qemu-doc.html qemu-doc.txt qemu.1 qemu-img.1 qemu-nbd.8 qemu-ga.8
|
||||
DOCS=qemu-doc.html qemu-doc.txt qemu.1 qemu-img.1 qemu-nbd.8 docs/interop/qemu-ga.8
|
||||
DOCS+=docs/interop/qemu-qmp-ref.html docs/interop/qemu-qmp-ref.txt docs/interop/qemu-qmp-ref.7
|
||||
DOCS+=docs/interop/qemu-ga-ref.html docs/interop/qemu-ga-ref.txt docs/interop/qemu-ga-ref.7
|
||||
DOCS+=docs/qemu-block-drivers.7
|
||||
@ -783,10 +783,11 @@ DESCS=
|
||||
endif
|
||||
|
||||
# Note that we manually filter-out the non-Sphinx documentation which
|
||||
# is currently built into the docs/interop directory in the build tree.
|
||||
# is currently built into the docs/interop directory in the build tree,
|
||||
# and also any sphinx-built manpages.
|
||||
define install-manual =
|
||||
for d in $$(cd $(MANUAL_BUILDDIR) && find $1 -type d); do $(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)/$$d"; done
|
||||
for f in $$(cd $(MANUAL_BUILDDIR) && find $1 -type f -a '!' '(' -name 'qemu-*-qapi.*' -o -name 'qemu-*-ref.*' ')' ); do $(INSTALL_DATA) "$(MANUAL_BUILDDIR)/$$f" "$(DESTDIR)$(qemu_docdir)/$$f"; done
|
||||
for f in $$(cd $(MANUAL_BUILDDIR) && find $1 -type f -a '!' '(' -name '*.[0-9]' -o -name 'qemu-*-qapi.*' -o -name 'qemu-*-ref.*' ')' ); do $(INSTALL_DATA) "$(MANUAL_BUILDDIR)/$$f" "$(DESTDIR)$(qemu_docdir)/$$f"; done
|
||||
endef
|
||||
|
||||
# Note that we deliberately do not install the "devel" manual: it is
|
||||
@ -818,7 +819,7 @@ ifdef CONFIG_TRACE_SYSTEMTAP
|
||||
$(INSTALL_DATA) scripts/qemu-trace-stap.1 "$(DESTDIR)$(mandir)/man1"
|
||||
endif
|
||||
ifneq (,$(findstring qemu-ga,$(TOOLS)))
|
||||
$(INSTALL_DATA) qemu-ga.8 "$(DESTDIR)$(mandir)/man8"
|
||||
$(INSTALL_DATA) docs/interop/qemu-ga.8 "$(DESTDIR)$(mandir)/man8"
|
||||
$(INSTALL_DATA) docs/interop/qemu-ga-ref.html "$(DESTDIR)$(qemu_docdir)"
|
||||
$(INSTALL_DATA) docs/interop/qemu-ga-ref.txt "$(DESTDIR)$(qemu_docdir)"
|
||||
$(INSTALL_DATA) docs/interop/qemu-ga-ref.7 "$(DESTDIR)$(mandir)/man7"
|
||||
@ -977,18 +978,22 @@ docs/version.texi: $(SRC_PATH)/VERSION config-host.mak
|
||||
sphinxdocs: $(MANUAL_BUILDDIR)/devel/index.html $(MANUAL_BUILDDIR)/interop/index.html $(MANUAL_BUILDDIR)/specs/index.html
|
||||
|
||||
# Canned command to build a single manual
|
||||
build-manual = $(call quiet-command,sphinx-build $(if $(V),,-q) -W -n -b html -D version=$(VERSION) -D release="$(FULL_VERSION)" -d .doctrees/$1 $(SRC_PATH)/docs/$1 $(MANUAL_BUILDDIR)/$1 ,"SPHINX","$(MANUAL_BUILDDIR)/$1")
|
||||
# Arguments: $1 = manual name, $2 = Sphinx builder ('html' or 'man')
|
||||
build-manual = $(call quiet-command,CONFDIR="$(qemu_confdir)" sphinx-build $(if $(V),,-q) -W -n -b $2 -D version=$(VERSION) -D release="$(FULL_VERSION)" -d .doctrees/$1 $(SRC_PATH)/docs/$1 $(MANUAL_BUILDDIR)/$1 ,"SPHINX","$(MANUAL_BUILDDIR)/$1")
|
||||
# We assume all RST files in the manual's directory are used in it
|
||||
manual-deps = $(wildcard $(SRC_PATH)/docs/$1/*.rst) $(SRC_PATH)/docs/$1/conf.py $(SRC_PATH)/docs/conf.py
|
||||
|
||||
$(MANUAL_BUILDDIR)/devel/index.html: $(call manual-deps,devel)
|
||||
$(call build-manual,devel)
|
||||
$(call build-manual,devel,html)
|
||||
|
||||
$(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop)
|
||||
$(call build-manual,interop)
|
||||
$(call build-manual,interop,html)
|
||||
|
||||
$(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs)
|
||||
$(call build-manual,specs)
|
||||
$(call build-manual,specs,html)
|
||||
|
||||
$(MANUAL_BUILDDIR)/interop/qemu-ga.8: $(call manual-deps,interop)
|
||||
$(call build-manual,interop,man)
|
||||
|
||||
qemu-options.texi: $(SRC_PATH)/qemu-options.hx $(SRC_PATH)/scripts/hxtool
|
||||
$(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > $@,"GEN","$@")
|
||||
@ -1013,7 +1018,6 @@ qemu.1: qemu-option-trace.texi
|
||||
qemu-img.1: qemu-img.texi qemu-option-trace.texi qemu-img-cmds.texi
|
||||
fsdev/virtfs-proxy-helper.1: fsdev/virtfs-proxy-helper.texi
|
||||
qemu-nbd.8: qemu-nbd.texi qemu-option-trace.texi
|
||||
qemu-ga.8: qemu-ga.texi
|
||||
docs/qemu-block-drivers.7: docs/qemu-block-drivers.texi
|
||||
docs/qemu-cpu-models.7: docs/qemu-cpu-models.texi
|
||||
scripts/qemu-trace-stap.1: scripts/qemu-trace-stap.texi
|
||||
@ -1026,7 +1030,7 @@ txt: qemu-doc.txt docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.txt
|
||||
qemu-doc.html qemu-doc.info qemu-doc.pdf qemu-doc.txt: \
|
||||
qemu-img.texi qemu-nbd.texi qemu-options.texi \
|
||||
qemu-tech.texi qemu-option-trace.texi \
|
||||
qemu-deprecated.texi qemu-monitor.texi qemu-img-cmds.texi qemu-ga.texi \
|
||||
qemu-deprecated.texi qemu-monitor.texi qemu-img-cmds.texi \
|
||||
qemu-monitor-info.texi docs/qemu-block-drivers.texi \
|
||||
docs/qemu-cpu-models.texi docs/security.texi
|
||||
|
||||
|
||||
18
docs/conf.py
18
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 -------------------------------------------
|
||||
|
||||
|
||||
@ -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)
|
||||
]
|
||||
|
||||
@ -15,5 +15,6 @@ Contents:
|
||||
bitmaps
|
||||
live-block-operations
|
||||
pr-helper
|
||||
qemu-ga
|
||||
vhost-user
|
||||
vhost-user-gpu
|
||||
|
||||
133
docs/interop/qemu-ga.rst
Normal file
133
docs/interop/qemu-ga.rst
Normal file
@ -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)`
|
||||
@ -2535,11 +2535,6 @@ so should only be used with trusted guest OS.
|
||||
|
||||
@c man end
|
||||
|
||||
@node QEMU Guest Agent
|
||||
@chapter QEMU Guest Agent invocation
|
||||
|
||||
@include qemu-ga.texi
|
||||
|
||||
@node QEMU User space emulator
|
||||
@chapter QEMU User space emulator
|
||||
|
||||
|
||||
137
qemu-ga.texi
137
qemu-ga.texi
@ -1,137 +0,0 @@
|
||||
@example
|
||||
@c man begin SYNOPSIS
|
||||
@command{qemu-ga} [@var{OPTIONS}]
|
||||
@c man end
|
||||
@end example
|
||||
|
||||
@c man begin 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:
|
||||
|
||||
@itemize
|
||||
@item
|
||||
get information from the guest
|
||||
@item
|
||||
set the guest's system time
|
||||
@item
|
||||
read/write a file
|
||||
@item
|
||||
sync and freeze the filesystems
|
||||
@item
|
||||
suspend the guest
|
||||
@item
|
||||
reconfigure guest local processors
|
||||
@item
|
||||
set user's password
|
||||
@item
|
||||
...
|
||||
@end itemize
|
||||
|
||||
qemu-ga will read a system configuration file on startup (located at
|
||||
@file{@value{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).
|
||||
|
||||
@c man end
|
||||
|
||||
@c man begin OPTIONS
|
||||
@table @option
|
||||
@item -m, --method=@var{method}
|
||||
Transport method: one of @samp{unix-listen}, @samp{virtio-serial}, or
|
||||
@samp{isa-serial} (@samp{virtio-serial} is the default).
|
||||
|
||||
@item -p, --path=@var{path}
|
||||
Device/socket path (the default for virtio-serial is
|
||||
@samp{/dev/virtio-ports/org.qemu.guest_agent.0},
|
||||
the default for isa-serial is @samp{/dev/ttyS0})
|
||||
|
||||
@item -l, --logfile=@var{path}
|
||||
Set log file path (default is stderr).
|
||||
|
||||
@item -f, --pidfile=@var{path}
|
||||
Specify pid file (default is @samp{/var/run/qemu-ga.pid}).
|
||||
|
||||
@item -F, --fsfreeze-hook=@var{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
|
||||
@samp{@value{CONFDIR}/fsfreeze-hook}). If using -F with an argument, do
|
||||
not follow -F with a space (for example:
|
||||
@samp{-F/var/run/fsfreezehook.sh}).
|
||||
|
||||
@item -t, --statedir=@var{path}
|
||||
Specify the directory to store state information (absolute paths only,
|
||||
default is @samp{/var/run}).
|
||||
|
||||
@item -v, --verbose
|
||||
Log extra debugging information.
|
||||
|
||||
@item -V, --version
|
||||
Print version information and exit.
|
||||
|
||||
@item -d, --daemon
|
||||
Daemonize after startup (detach from terminal).
|
||||
|
||||
@item -b, --blacklist=@var{list}
|
||||
Comma-separated list of RPCs to disable (no spaces, @samp{?} to list
|
||||
available RPCs).
|
||||
|
||||
@item -D, --dump-conf
|
||||
Dump the configuration in a format compatible with @file{qemu-ga.conf}
|
||||
and exit.
|
||||
|
||||
@item -h, --help
|
||||
Display this help and exit.
|
||||
@end table
|
||||
|
||||
@c man end
|
||||
|
||||
@c man begin FILES
|
||||
|
||||
The syntax of the @file{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.
|
||||
|
||||
@example
|
||||
# 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
|
||||
@end example
|
||||
|
||||
The list of keys follows the command line options:
|
||||
@table @option
|
||||
@item daemon= boolean
|
||||
@item method= string
|
||||
@item path= string
|
||||
@item logfile= string
|
||||
@item pidfile= string
|
||||
@item fsfreeze-hook= string
|
||||
@item statedir= string
|
||||
@item verbose= boolean
|
||||
@item blacklist= string list
|
||||
@end table
|
||||
|
||||
@c man end
|
||||
|
||||
@ignore
|
||||
|
||||
@setfilename qemu-ga
|
||||
@settitle QEMU Guest Agent
|
||||
|
||||
@c man begin AUTHOR
|
||||
Michael Roth <mdroth@linux.vnet.ibm.com>
|
||||
@c man end
|
||||
|
||||
@c man begin SEEALSO
|
||||
qemu(1)
|
||||
@c man end
|
||||
|
||||
@end ignore
|
||||
Loading…
Reference in New Issue
Block a user