[12/12] qga: start a man page

Add a simple man page for the qemu agent.

Signed-off-by: Marc-André Lureau <marcandre.lureau@gmail.com>
---
 Makefile      |  14 +++++-
 qemu-doc.texi |   6 +++
 qemu-ga.texi  | 135 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 153 insertions(+), 2 deletions(-)
 create mode 100644 qemu-ga.texi

Quoting Marc-André Lureau (2015-07-01 06:47:47)
> Add a simple man page for the qemu agent.
> 
> Signed-off-by: Marc-André Lureau <marcandre.lureau@gmail.com>
> ---
>  Makefile      |  14 +++++-
>  qemu-doc.texi |   6 +++
>  qemu-ga.texi  | 135 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  3 files changed, 153 insertions(+), 2 deletions(-)
>  create mode 100644 qemu-ga.texi
> 
> diff --git a/Makefile b/Makefile
> index c9be643..45b1a12 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 0125bc7..aa3d165 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..a5e8002
> --- /dev/null
> +++ b/qemu-ga.texi
> @@ -0,0 +1,135 @@
> +@example
> +@c man begin SYNOPSIS
> +usage: qemu-ga [-m <method> -p <path>] [OPTION]...
> +@c man end
> +@end example
> +
> +@c man begin DESCRIPTION
> +
> +The QEMU Guest Agent is a deamon that allows the host to perform
> +various operations in the guest.

Maybe:

 "various operations in the guest, such as:"

Makes it clearer it's not an exhaustive list.

> +
> +@itemize
> +@item
> +get information from the guest
> +@item
> +set the guest's system time
> +@item
> +read/write a file
> +@item
> +sync an freeze the filesystems

*and freeze

> +@item
> +suspend the guest
> +@item
> +reconfigugre guest local processors

*reconfigure

> +@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

, then parse remaining

> +configuration options on the command line. For the same key, the last
> +option wins, but the lists accumulate.

Maybe an added:

"(see below for configuration file format)"

would be useful. Might lose less thorough readers (such as myself) here
(initially I assumed there wouldn't be examples below and starting
writing a comment about it).

> +
> +@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})

I'm not sure if it's possible, but would be nice if we could use the
#defines from QGA to grab these values. Would help keep things in sync.
Not a huge deal if there's no simple method.

> +
> +@item -l, --logfile=@var{path}
> +  Set log file path, logs to stderr by default.
> +
> +@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 <mdroth@linux.vnet.ibm.com>
> +@c man end
> +
> +@c man begin SEEALSO
> +qemu(1)
> +@c man end
> +
> +@end ignore
> -- 
> 2.4.3
>

On Tue, Aug 25, 2015 at 7:43 PM, Michael Roth <mdroth@linux.vnet.ibm.com> wrote:
> Quoting Marc-André Lureau (2015-07-01 06:47:47)
>> Add a simple man page for the qemu agent.
>>
>> Signed-off-by: Marc-André Lureau <marcandre.lureau@gmail.com>
>> ---
>>  Makefile      |  14 +++++-
>>  qemu-doc.texi |   6 +++
>>  qemu-ga.texi  | 135 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>>  3 files changed, 153 insertions(+), 2 deletions(-)
>>  create mode 100644 qemu-ga.texi
>>
>> diff --git a/Makefile b/Makefile
>> index c9be643..45b1a12 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 0125bc7..aa3d165 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..a5e8002
>> --- /dev/null
>> +++ b/qemu-ga.texi
>> @@ -0,0 +1,135 @@
>> +@example
>> +@c man begin SYNOPSIS
>> +usage: qemu-ga [-m <method> -p <path>] [OPTION]...
>> +@c man end
>> +@end example
>> +
>> +@c man begin DESCRIPTION
>> +
>> +The QEMU Guest Agent is a deamon that allows the host to perform
>> +various operations in the guest.
>
> Maybe:
>
>  "various operations in the guest, such as:"
>
> Makes it clearer it's not an exhaustive list.

ok

>
>> +
>> +@itemize
>> +@item
>> +get information from the guest
>> +@item
>> +set the guest's system time
>> +@item
>> +read/write a file
>> +@item
>> +sync an freeze the filesystems
>
> *and freeze

yep

>
>> +@item
>> +suspend the guest
>> +@item
>> +reconfigugre guest local processors
>
> *reconfigure
>

yep

>> +@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
>
> , then parse remaining
>
>> +configuration options on the command line. For the same key, the last
>> +option wins, but the lists accumulate.
>
> Maybe an added:
>
> "(see below for configuration file format)"

ok

>
> would be useful. Might lose less thorough readers (such as myself) here
> (initially I assumed there wouldn't be examples below and starting
> writing a comment about it).
>
>> +
>> +@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})
>
> I'm not sure if it's possible, but would be nice if we could use the
> #defines from QGA to grab these values. Would help keep things in sync.
> Not a huge deal if there's no simple method.

looks like it is a bit tricky, I left this

thanks

>
>> +
>> +@item -l, --logfile=@var{path}
>> +  Set log file path, logs to stderr by default.
>> +
>> +@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 <mdroth@linux.vnet.ibm.com>
>> +@c man end
>> +
>> +@c man begin SEEALSO
>> +qemu(1)
>> +@c man end
>> +
>> +@end ignore
>> --
>> 2.4.3
>>
>