From patchwork Tue Sep 1 17:01:01 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Michael Roth X-Patchwork-Id: 512969 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from lists.gnu.org (lists.gnu.org [IPv6:2001:4830:134:3::11]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 31FCA1401DA for ; Wed, 2 Sep 2015 03:09:54 +1000 (AEST) Received: from localhost ([::1]:56097 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZWp4B-0002Fu-NN for incoming@patchwork.ozlabs.org; Tue, 01 Sep 2015 13:09:51 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:59682) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZWp0d-0003zY-MP for qemu-devel@nongnu.org; Tue, 01 Sep 2015 13:06:13 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ZWp0a-0002mU-KD for qemu-devel@nongnu.org; Tue, 01 Sep 2015 13:06:11 -0400 Received: from e35.co.us.ibm.com ([32.97.110.153]:43481) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZWp0a-0002m7-6m for qemu-devel@nongnu.org; Tue, 01 Sep 2015 13:06:08 -0400 Received: from /spool/local by e35.co.us.ibm.com with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted for from ; Tue, 1 Sep 2015 11:06:02 -0600 Received: from d03dlp02.boulder.ibm.com (9.17.202.178) by e35.co.us.ibm.com (192.168.1.135) with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted; Tue, 1 Sep 2015 11:04:58 -0600 X-Helo: d03dlp02.boulder.ibm.com X-MailFrom: mdroth@linux.vnet.ibm.com X-RcptTo: qemu-devel@nongnu.org Received: from b03cxnp08026.gho.boulder.ibm.com (b03cxnp08026.gho.boulder.ibm.com [9.17.130.18]) by d03dlp02.boulder.ibm.com (Postfix) with ESMTP id 6F2A93E40041 for ; Tue, 1 Sep 2015 11:04:57 -0600 (MDT) Received: from d03av01.boulder.ibm.com (d03av01.boulder.ibm.com [9.17.195.167]) by b03cxnp08026.gho.boulder.ibm.com (8.14.9/8.14.9/NCO v10.0) with ESMTP id t81H43a238666492 for ; Tue, 1 Sep 2015 10:04:11 -0700 Received: from d03av01.boulder.ibm.com (localhost [127.0.0.1]) by d03av01.boulder.ibm.com (8.14.4/8.14.4/NCO v10.0 AVout) with ESMTP id t81H4OqI006113 for ; Tue, 1 Sep 2015 11:04:24 -0600 Received: from localhost ([9.41.105.109]) by d03av01.boulder.ibm.com (8.14.4/8.14.4/NCO v10.0 AVin) with ESMTP id t81H4NPZ005167; Tue, 1 Sep 2015 11:04:23 -0600 From: Michael Roth To: qemu-devel@nongnu.org Date: Tue, 1 Sep 2015 12:01:01 -0500 Message-Id: <1441126866-17199-22-git-send-email-mdroth@linux.vnet.ibm.com> X-Mailer: git-send-email 1.9.1 In-Reply-To: <1441126866-17199-1-git-send-email-mdroth@linux.vnet.ibm.com> References: <1441126866-17199-1-git-send-email-mdroth@linux.vnet.ibm.com> MIME-Version: 1.0 X-TM-AS-MML: disable X-Content-Scanned: Fidelis XPS MAILER x-cbid: 15090117-0013-0000-0000-000017E18E01 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-Received-From: 32.97.110.153 Cc: peter.maydell@linaro.org, Michael Roth , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= Subject: [Qemu-devel] [PATCH 21/26] qga: start a man page X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org From: Marc-André Lureau Add a simple man page for the qemu agent. Signed-off-by: Marc-André Lureau Reviewed-by: Michael Roth *squashed in review comments from Eric Blake Reviewed-by: Eric Blake Signed-off-by: Michael Roth --- Makefile | 14 +++++- qemu-doc.texi | 6 +++ qemu-ga.texi | 137 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 155 insertions(+), 2 deletions(-) create mode 100644 qemu-ga.texi diff --git a/Makefile b/Makefile index f98a554..c13a83d 100644 --- a/Makefile +++ b/Makefile @@ -88,7 +88,8 @@ LIBS+=-lz $(LIBS_TOOLS) HELPERS-$(CONFIG_LINUX) = qemu-bridge-helper$(EXESUF) ifdef BUILD_DOCS -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 +DOCS+=qmp-commands.txt ifdef CONFIG_LINUX DOCS+=kvm_stat.1 endif @@ -400,6 +401,9 @@ ifneq ($(TOOLS),) $(INSTALL_DIR) "$(DESTDIR)$(mandir)/man8" $(INSTALL_DATA) qemu-nbd.8 "$(DESTDIR)$(mandir)/man8" endif +ifneq (,$(findstring qemu-ga,$(TOOLS))) + $(INSTALL_DATA) qemu-ga.8 "$(DESTDIR)$(mandir)/man8" +endif endif ifdef CONFIG_VIRTFS $(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/texi2pod.pl $< 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/texi2pod.pl $< kvm_stat.pod && \ @@ -551,7 +561,7 @@ pdf: qemu-doc.pdf qemu-tech.pdf qemu-doc.dvi qemu-doc.html qemu-doc.info 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 diff --git a/qemu-doc.texi b/qemu-doc.texi index f1c38b6..ea9b3fb 100644 --- a/qemu-doc.texi +++ b/qemu-doc.texi @@ -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 diff --git a/qemu-ga.texi b/qemu-ga.texi new file mode 100644 index 0000000..536a9b5 --- /dev/null +++ b/qemu-ga.texi @@ -0,0 +1,137 @@ +@example +@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: + +@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 +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 + @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{/etc/qemu/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 +@c man end + +@c man begin SEEALSO +qemu(1) +@c man end + +@end ignore