Re: [Qemu-devel] [PATCH v1 1/1] qemu-doc: update gluster protocol usage guide

[Eric Blake <eblake@redhat.com>]

[-- Attachment #1: Type: text/plain, Size: 6928 bytes --]

On 11/01/2016 07:29 AM, Prasanna Kumar Kalever wrote:
> Document:
> 1. The new debug and logfile options with their usages and
> 2. New json format and its usage.
> 
> Signed-off-by: Prasanna Kumar Kalever <prasanna.kalever@redhat.com>
> ---
>  qemu-doc.texi   | 46 ++++++++++++++++++++++++++++++++--------------
>  qemu-options.hx | 14 ++++++++++++--
>  2 files changed, 44 insertions(+), 16 deletions(-)
> 
> diff --git a/qemu-doc.texi b/qemu-doc.texi
> index 023c140..a7c5722 100644
> --- a/qemu-doc.texi
> +++ b/qemu-doc.texi
> @@ -1041,35 +1041,50 @@ GlusterFS is an user space distributed file system.
>  
>  You can boot from the GlusterFS disk image with the command:
>  @example
> -qemu-system-x86_64 -drive file=gluster[+@var{transport}]://[@var{server}[:@var{port}]]/@var{volname}/@var{image}[?socket=...]
> +URI:
> +qemu-system-x86_64 -drive file=gluster[+@var{type}]://[@var{host}[:@var{port}]]/@var{volume}/@var{path}[?socket=...]
> +
> +JSON:
> +qemu-system-x86_64 'json:@{"driver":"qcow2","file":@{"driver":"gluster","volume":"testvol","path":"a.img","debug":"N","logfile":"...","server":[@{"type":"tcp","host":"...","port":"..."@},@{"type":"unix","socket":"..."@}]@}@}'

"debug":"N" does not match the schema; the parameter is named
"debug-level", and it is an integer not a string.  The parameter is
optional; you could just omit it. But if you are going to include it,
give a reasonable example like "debug-level":0.

Can you break up this long line for legibility?

>  @end example
>  
>  @var{gluster} is the protocol.
>  
> -@var{transport} specifies the transport type used to connect to gluster
> +@var{type} specifies the transport type used to connect to gluster
>  management daemon (glusterd). Valid transport types are
> -tcp, unix and rdma. If a transport type isn't specified, then tcp
> -type is assumed.
> +tcp, unix. Incase of URI, if a transport type isn't specified,

s/tcp, unix/tcp and unix/

s/Incase of URI/In the URI form/

> +then tcp type is assumed.
>  
> -@var{server} specifies the server where the volume file specification for
> -the given volume resides. This can be either hostname, ipv4 address
> -or ipv6 address. ipv6 address needs to be within square brackets [ ].
> -If transport type is unix, then @var{server} field should not be specified.
> +@var{host} specifies the server where the volume file specification for
> +the given volume resides. This can be either hostname, ipv4 address.

s/hostname, ipv4/a hostname or an ipv4/

> +If transport type is unix, then @var{host} field should not be specified.
>  Instead @var{socket} field needs to be populated with the path to unix domain
>  socket.
>  
>  @var{port} is the port number on which glusterd is listening. This is optional
> -and if not specified, QEMU will send 0 which will make gluster to use the
> -default port. If the transport type is unix, then @var{port} should not be
> -specified.
> +and if not specified, it default to port 24007. If the transport type is unix,

s/default/defaults/

> +then @var{port} should not be specified.
> +
> +@var{volume} is the name of the gluster volume which contains the disk image.
> +
> +@var{path} is the path to the actual disk image that resides on gluster volume.
> +
> +@var{debug} is the logging level of the gluster protocol driver. Debug levels

Again, the schema for BlockdevOptionsGluster spells this debug-level, so
you need to fix this paragraph.

> +are 0-9, with 9 being the most verbose, and 0 representing no debugging output.
> +Default is level of 4.  The current logging levels defined in the gluster source

s/Default is level of 4/The default level is 4/

> +are 0 - None, 1 - Emergency, 2 - Alert, 3 - Critical, 4 - Error, 5 - Warning,
> +6 - Notice, 7 - Info, 8 - Debug, 9 - Trace
> +
> +@var{logfile} is a commandline option to mention log file path which helps in
> +logging to the specified file and also help in persisting the gfapi logs. The
> +default is stderr.
> +
>  
> @@ -1082,6 +1097,9 @@ qemu-system-x86_64 -drive file=gluster+tcp://[1:2:3:4:5:6:7:8]:24007/testvol/dir
>  qemu-system-x86_64 -drive file=gluster+tcp://server.domain.com:24007/testvol/dir/a.img
>  qemu-system-x86_64 -drive file=gluster+unix:///testvol/dir/a.img?socket=/tmp/glusterd.socket
>  qemu-system-x86_64 -drive file=gluster+rdma://1.2.3.4:24007/testvol/a.img
> +qemu-system-x86_64 -drive file=gluster://1.2.3.4/testvol/a.img,file.debug=9,file.logfile=/var/log/qemu-gluster.log

Should be file.debug-level

> +qemu-system-x86_64 'json:@{"driver":"qcow2","file":@{"driver":"gluster","volume":"testvol","path":"a.img","debug":"9","logfile":"/var/log/qemu-gluster.log","server":[@{"type":"tcp","host":"1.2.3.4","port":24007@},@{"type":"unix","socket":"/var/run/glusterd.socket"@}]@}@}'
> +qemu-system-x86_64 -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img,file.debug=9,file.logfile=/var/log/qemu-gluster.log,file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007,file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket

Two more incorrect uses of debug.

> +++ b/qemu-options.hx
> @@ -2595,13 +2595,23 @@ TCP, Unix Domain Sockets and RDMA transport protocols.
>  
>  Syntax for specifying a VM disk image on GlusterFS volume is
>  @example
> -gluster[+transport]://[server[:port]]/volname/image[?socket=...]
> +
> +URI:
> +gluster[+type]://[host[:port]]/volume/path[?socket=...][,debug=N][,logfile=...]

Again, isn't this debug-level?

> +
> +JSON:
> +'json:@{"driver":"qcow2","file":@{"driver":"gluster","volume":"testvol","path":"a.img","debug":"N","logfile":"...","server":[@{"type":"tcp","host":"...","port":"..."@},@{"type":"unix","socket":"..."@}]@}@}'

and this example matches the incorrect commit message

>  @end example
>  
>  
>  Example
>  @example
> -qemu-system-x86_64 --drive file=gluster://192.0.2.1/testvol/a.img
> +URI:
> +qemu-system-x86_64 --drive file=gluster://192.0.2.1/testvol/a.img,file.debug=9,file.logfile=/var/log/qemu-gluster.log
> +
> +JSON:
> +qemu-system-x86_64 'json:@{"driver":"qcow2","file":@{"driver":"gluster","volume":"testvol","path":"a.img","debug":"9","logfile":"/var/log/qemu-gluster.log","server":[@{"type":"tcp","host":"1.2.3.4","port":24007@},@{"type":"unix","socket":"/var/run/glusterd.socket"@}]@}@}'
> +qemu-system-x86_64 -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img,file.debug=9,file.logfile=/var/log/qemu-gluster.log,file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007,file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket

More uses of debug

>  @end example
>  
>  See also @url{http://www.gluster.org}.
> 

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 604 bytes --]