Re: [Qemu-devel] [Qemu-block] [PATCH] docs: Update preferred NBD device syntax

[Eric Blake <eblake@redhat.com>]

[-- Attachment #1.1: Type: text/plain, Size: 2549 bytes --]

[adding libvirt list]

On 9/3/19 1:50 PM, John Snow wrote:
> 
> 
> On 9/3/19 10:56 AM, Eric Blake wrote:
>> Mention the preferred URI form, especially since NBD is trying to
>> standardize that form: https://lists.debian.org/nbd/2019/06/msg00012.html
>>
>> Signed-off-by: Eric Blake <eblake@redhat.com>
>> ---
>>  qemu-doc.texi | 16 +++++++++++-----
>>  1 file changed, 11 insertions(+), 5 deletions(-)
>>
>> diff --git a/qemu-doc.texi b/qemu-doc.texi
>> index 577d1e837640..c83fb347d77e 100644
>> --- a/qemu-doc.texi
>> +++ b/qemu-doc.texi
>> @@ -297,7 +297,14 @@ qemu-system-i386 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
>>
>>  @item NBD
>>  QEMU supports NBD (Network Block Devices) both using TCP protocol as well
>> -as Unix Domain Sockets.
>> +as Unix Domain Sockets.  With TCP, the default port is 10809.
>>
>> -Syntax for specifying a NBD device using TCP
>> +Syntax for specifying a NBD device using TCP, in preferred URI form:
>> +``nbd://<server-ip>[:<port>]/[<export>]''
>> +
>> +Syntax for specifying a NBD device using Unix Domain Sockets; remember
>> +that '?' is a shell glob character and may need quoting:
>> +``nbd+unix:///[<export>]?socket=<domain-socket>''
>> +
>> +Older syntax that is also recognized:
> 
> Deprecated officially, or no?
> 
>>  ``nbd:<server-ip>:<port>[:exportname=<export>]''
>>
>> -Syntax for specifying a NBD device using Unix Domain Sockets
>>  ``nbd:unix:<domain-socket>[:exportname=<export>]''

I didn't feel like starting a deprecation clock, in part because libvirt
is still using nbd:host:port:exportname during migration, similarly code
in virstoragefile.c is using only the old form.  Do we want to start a
deprecation (as a separate patch), to prod faster changes in libvirt in
switching to the newer form where sensible?

>>
>>  Example for TCP
>>  @example
>> -qemu-system-i386 --drive file=nbd:192.0.2.1:30000
>> +qemu-system-i386 --drive file=nbd://192.0.2.1:30000
>>  @end example
>>
>>  Example for Unix Domain Sockets
>>  @example
>> -qemu-system-i386 --drive file=nbd:unix:/tmp/nbd-socket
>> +qemu-system-i386 --drive "file=nbd+unix:///?socket=/tmp/nbd-socket"
>>  @end example
>>
>>  @item SSH
>>
> 
> Reviewed-by: John Snow <jsnow@redhat.com>

Thanks; will queue through my NBD tree (regardless of whether we decide
I should add more patches to start a deprecation cycle).

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3226
Virtualization:  qemu.org | libvirt.org


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