Commit 665b5d0d authored by Marc-André Lureau's avatar Marc-André Lureau Committed by Michael Roth

qga: start a man page

Add a simple man page for the qemu agent.
Signed-off-by: 's avatarMarc-André Lureau <>
Reviewed-by: 's avatarMichael Roth <>
*squashed in review comments from Eric Blake <>
Reviewed-by: 's avatarEric Blake <>
Signed-off-by: 's avatarMichael Roth <>
parent aeadcbb6
......@@ -88,7 +88,8 @@ LIBS+=-lz $(LIBS_TOOLS)
HELPERS-$(CONFIG_LINUX) = qemu-bridge-helper$(EXESUF)
DOCS=qemu-doc.html qemu-tech.html qemu.1 qemu-img.1 qemu-nbd.8 qmp-commands.txt
DOCS=qemu-doc.html qemu-tech.html qemu.1 qemu-img.1 qemu-nbd.8 qemu-ga.8
......@@ -400,6 +401,9 @@ ifneq ($(TOOLS),)
$(INSTALL_DIR) "$(DESTDIR)$(mandir)/man8"
$(INSTALL_DATA) qemu-nbd.8 "$(DESTDIR)$(mandir)/man8"
ifneq (,$(findstring qemu-ga,$(TOOLS)))
$(INSTALL_DATA) qemu-ga.8 "$(DESTDIR)$(mandir)/man8"
$(INSTALL_DIR) "$(DESTDIR)$(mandir)/man1"
......@@ -538,6 +542,12 @@ qemu-nbd.8: qemu-nbd.texi
$(POD2MAN) --section=8 --center=" " --release=" " qemu-nbd.pod > $@, \
" GEN $@")
qemu-ga.8: qemu-ga.texi
$(call quiet-command, \
perl -Ww -- $(SRC_PATH)/scripts/ $< qemu-ga.pod && \
$(POD2MAN) --section=8 --center=" " --release=" " qemu-ga.pod > $@, \
" GEN $@")
kvm_stat.1: scripts/kvm/kvm_stat.texi
$(call quiet-command, \
perl -Ww -- $(SRC_PATH)/scripts/ $< kvm_stat.pod && \
......@@ -551,7 +561,7 @@ pdf: qemu-doc.pdf qemu-tech.pdf
qemu-doc.dvi qemu-doc.html qemu-doc.pdf: \
qemu-img.texi qemu-nbd.texi qemu-options.texi \
qemu-monitor.texi qemu-img-cmds.texi
qemu-monitor.texi qemu-img-cmds.texi qemu-ga.texi
ifdef CONFIG_WIN32
......@@ -412,6 +412,7 @@ snapshots.
* vm_snapshots:: VM snapshots
* qemu_img_invocation:: qemu-img Invocation
* qemu_nbd_invocation:: qemu-nbd Invocation
* qemu_ga_invocation:: qemu-ga Invocation
* disk_images_formats:: Disk image file formats
* host_drives:: Using host drives
* disk_images_fat_images:: Virtual FAT disk images
......@@ -505,6 +506,11 @@ state is not saved or restored properly (in particular USB).
@include qemu-nbd.texi
@node qemu_ga_invocation
@subsection @code{qemu-ga} Invocation
@include qemu-ga.texi
@node disk_images_formats
@subsection Disk image file formats
@c man begin SYNOPSIS
usage: qemu-ga [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:
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
@end itemize
qemu-ga will read a system configuration file on startup (located at
q@file{/etc/qemu/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
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/}).
@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{/etc/qemu/fsfreeze-hook}). If using -F with an argument, do
not follow -F with a space (for example:
@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.
# qemu-ga configuration sample
daemonize = 0
pidfile = /var/run/
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
@setfilename qemu-ga
@settitle QEMU Guest Agent
@c man begin AUTHOR
Michael Roth <>
@c man end
@c man begin SEEALSO
@c man end
@end ignore
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment