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

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

[Prasanna Kumar Kalever]

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":"..."@}]@}@}'
 @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,
+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.
+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,
+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
+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
+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.
+
 
-@var{volname} is the name of the gluster volume which contains the disk image.
 
-@var{image} is the path to the actual disk image that resides on gluster volume.
 
 You can create a GlusterFS disk image with the command:
 @example
-qemu-img create gluster://@var{server}/@var{volname}/@var{image} @var{size}
+qemu-img create gluster://@var{host}/@var{volume}/@var{path} @var{size}
 @end example
 
 Examples
@@ -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
+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
 @end example
 
 @node disk_images_ssh
diff --git a/qemu-options.hx b/qemu-options.hx
index b1fbdb0..f5e8ccc 100644
--- a/qemu-options.hx
+++ 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=...]
+
+JSON:
+'json:@{"driver":"qcow2","file":@{"driver":"gluster","volume":"testvol","path":"a.img","debug":"N","logfile":"...","server":[@{"type":"tcp","host":"...","port":"..."@},@{"type":"unix","socket":"..."@}]@}@}'
 @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
 @end example
 
 See also @url{http://www.gluster.org}.
-- 
2.7.4

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

[Eric Blake]

[-- 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 --]

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

[Prasanna Kalever]

On Tue, Nov 1, 2016 at 11:32 PM, Eric Blake <eblake@redhat.com> wrote:
> 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.

Eric,

>From the code I can see
#define GLUSTER_OPT_DEBUG           "debug"

And even tried this, there is no option 'debug-level'.
And yes, I should admit it is 'int' not a 'string'

Thanks, rest of the comments seems convincing to me, will make the
changes and spin them soon.

--
Prasanna

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

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

[Eric Blake]

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

On 11/02/2016 07:03 AM, Prasanna Kalever wrote:

>> "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.
> 
> Eric,
> 
>>From the code I can see
> #define GLUSTER_OPT_DEBUG           "debug"
> 
> And even tried this, there is no option 'debug-level'.
> And yes, I should admit it is 'int' not a 'string'

Uggh. We were under so much pressure to try and get GlusterServer into
2.7 that we really botched it.

The QMP definition is:

{ 'struct': 'BlockdevOptionsGluster',
  'data': { 'volume': 'str',
            'path': 'str',
            'server': ['GlusterServer'],
            '*debug-level': 'int',
            '*logfile': 'str' } }

and what's more, we've copied that string elsewhere for 2.8:

{ 'struct': 'BlockdevOptionsNfs',
  'data': { 'server': 'NFSServer',
            'path': 'str',
            '*user': 'int',
            '*group': 'int',
            '*tcp-syn-count': 'int',
            '*readahead-size': 'int',
            '*page-cache-size': 'int',
            '*debug-level': 'int' } }

So either we need to fix the QMP to spell it 'debug' (to match the
documentation you gave); or fix the docs to match the QMP and add some
back-compat glue into the gluster code to manage both spellings rather
than just the QMP spelling.

Since blockdev-add is still experimental, I'm leaning towards changing
the QMP for both gluster and NFS.  But we need to get it done before
2.8.  Looks like I have some patches to propose.

-- 
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 --]

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

[Prasanna Kalever]

On Wed, Nov 2, 2016 at 9:02 PM, Eric Blake <eblake@redhat.com> wrote:
> On 11/02/2016 07:03 AM, Prasanna Kalever wrote:
>
>>> "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.
>>
>> Eric,
>>
>>>From the code I can see
>> #define GLUSTER_OPT_DEBUG           "debug"
>>
>> And even tried this, there is no option 'debug-level'.
>> And yes, I should admit it is 'int' not a 'string'
>
> Uggh. We were under so much pressure to try and get GlusterServer into
> 2.7 that we really botched it.

That's a great catch.

>
> The QMP definition is:
>
> { 'struct': 'BlockdevOptionsGluster',
>   'data': { 'volume': 'str',
>             'path': 'str',
>             'server': ['GlusterServer'],
>             '*debug-level': 'int',
>             '*logfile': 'str' } }
>
> and what's more, we've copied that string elsewhere for 2.8:
>
> { 'struct': 'BlockdevOptionsNfs',
>   'data': { 'server': 'NFSServer',
>             'path': 'str',
>             '*user': 'int',
>             '*group': 'int',
>             '*tcp-syn-count': 'int',
>             '*readahead-size': 'int',
>             '*page-cache-size': 'int',
>             '*debug-level': 'int' } }
>
> So either we need to fix the QMP to spell it 'debug' (to match the
> documentation you gave); or fix the docs to match the QMP and add some
> back-compat glue into the gluster code to manage both spellings rather
> than just the QMP spelling.
>
> Since blockdev-add is still experimental, I'm leaning towards changing
> the QMP for both gluster and NFS.  But we need to get it done before
> 2.8.  Looks like I have some patches to propose.

Agree!
Lets fix it in QMP definitions, since we have 'debug' option out in 2.7.
There could be people using this option now, changing the option may
break something out.

I have made the changes, will send them out.

Thanks for the suggest Eric.

--
Prasanna

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