* [Qemu-devel] [PATCH] docs: Update preferred NBD device syntax
@ 2019-09-03 14:56 Eric Blake
2019-09-03 18:50 ` [Qemu-devel] [Qemu-block] " John Snow
0 siblings, 1 reply; 6+ messages in thread
From: Eric Blake @ 2019-09-03 14:56 UTC (permalink / raw)
To: qemu-devel; +Cc: vsementsov, rjones, qemu-block
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:
``nbd:<server-ip>:<port>[:exportname=<export>]''
-Syntax for specifying a NBD device using Unix Domain Sockets
``nbd:unix:<domain-socket>[:exportname=<export>]''
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
--
2.21.0
^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: [Qemu-devel] [Qemu-block] [PATCH] docs: Update preferred NBD device syntax
2019-09-03 14:56 [Qemu-devel] [PATCH] docs: Update preferred NBD device syntax Eric Blake
@ 2019-09-03 18:50 ` John Snow
2019-09-03 19:02 ` Eric Blake
0 siblings, 1 reply; 6+ messages in thread
From: John Snow @ 2019-09-03 18:50 UTC (permalink / raw)
To: Eric Blake, qemu-devel; +Cc: vsementsov, qemu-block
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>]''
>
> 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>
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [Qemu-devel] [Qemu-block] [PATCH] docs: Update preferred NBD device syntax
2019-09-03 18:50 ` [Qemu-devel] [Qemu-block] " John Snow
@ 2019-09-03 19:02 ` Eric Blake
2019-09-03 19:06 ` John Snow
0 siblings, 1 reply; 6+ messages in thread
From: Eric Blake @ 2019-09-03 19:02 UTC (permalink / raw)
To: John Snow, qemu-devel; +Cc: vsementsov, libvirt-list, qemu-block
[-- 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 --]
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [Qemu-devel] [Qemu-block] [PATCH] docs: Update preferred NBD device syntax
2019-09-03 19:02 ` Eric Blake
@ 2019-09-03 19:06 ` John Snow
2019-09-04 8:18 ` Daniel P. Berrangé
0 siblings, 1 reply; 6+ messages in thread
From: John Snow @ 2019-09-03 19:06 UTC (permalink / raw)
To: Eric Blake, qemu-devel; +Cc: vsementsov, libvirt-list, qemu-block
On 9/3/19 3:02 PM, Eric Blake wrote:
> [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?
>
Yeah, understood -- I was merely curious for wording purposes. Some
people might wonder what "Older syntax" means and perhaps why they
shouldn't use it. It sounds like we do want to wander away from it
eventually but aren't prepared to do that yet.
I think largely such a deprecation clock is up to the workload of
whoever would have to update the libvirt workflow (You, Peter?) and how
much benefit we'd gain by dropping it in QEMU (little?)
If you don't have motivation for doing it unprompted I have little
reason to coerce you into it.
>>>
>>> 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).
>
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [Qemu-devel] [Qemu-block] [PATCH] docs: Update preferred NBD device syntax
2019-09-03 19:06 ` John Snow
@ 2019-09-04 8:18 ` Daniel P. Berrangé
2019-09-04 12:50 ` Eric Blake
0 siblings, 1 reply; 6+ messages in thread
From: Daniel P. Berrangé @ 2019-09-04 8:18 UTC (permalink / raw)
To: John Snow; +Cc: vsementsov, qemu-devel, qemu-block, libvirt-list
On Tue, Sep 03, 2019 at 03:06:24PM -0400, John Snow wrote:
>
>
> On 9/3/19 3:02 PM, Eric Blake wrote:
> > [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?
> >
>
> Yeah, understood -- I was merely curious for wording purposes. Some
> people might wonder what "Older syntax" means and perhaps why they
> shouldn't use it. It sounds like we do want to wander away from it
> eventually but aren't prepared to do that yet.
>
> I think largely such a deprecation clock is up to the workload of
> whoever would have to update the libvirt workflow (You, Peter?) and how
> much benefit we'd gain by dropping it in QEMU (little?)
In general libvirt should never use the psuedo-URI/URI syntax for
anything. We're moving towards use of blockdev, so will have the
dot separated key syntax on the cli and equiv in QMP.
I hope this means we'll stop using the URIs in migration, but will
defer to peter for specifics.
I always think it is a shame that QEMU has done so much work on
blockdev, but all QEMU's docs still largely use the many legacy
syntaxes. IOW, we should make these NBD examples use the modern
non-URI syntax too.
> If you don't have motivation for doing it unprompted I have little
> reason to coerce you into it.
>
> >>>
> >>> 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).
> >
>
>
>
Regards,
Daniel
--
|: https://berrange.com -o- https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org -o- https://fstop138.berrange.com :|
|: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [Qemu-devel] [Qemu-block] [PATCH] docs: Update preferred NBD device syntax
2019-09-04 8:18 ` Daniel P. Berrangé
@ 2019-09-04 12:50 ` Eric Blake
0 siblings, 0 replies; 6+ messages in thread
From: Eric Blake @ 2019-09-04 12:50 UTC (permalink / raw)
To: Daniel P. Berrangé, John Snow
Cc: vsementsov, qemu-devel, qemu-block, libvirt-list
[-- Attachment #1.1: Type: text/plain, Size: 1567 bytes --]
On 9/4/19 3:18 AM, Daniel P. Berrangé wrote:
>>>>> -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>]''
>>>>> +
>>>>> ``nbd:<server-ip>:<port>[:exportname=<export>]''
>>>>>
>
> In general libvirt should never use the psuedo-URI/URI syntax for
> anything. We're moving towards use of blockdev, so will have the
> dot separated key syntax on the cli and equiv in QMP.
There's a difference between '-drive' (which sort of implies the
file=URI... syntax) and '-blockdev + -device' (where you use the
dot-separated syntax). Yes, we should document and encourage the use of
-blockdev even more (at which point URIs are not needed, whether or not
they are the preferred URI or the old form); but as long as -drive can
only take a non-dotted representation, we should still be choosing the
non-dotted representation that is at least reusable among other projects
that also use URI syntax for NBD drives.
>
> I hope this means we'll stop using the URIs in migration, but will
> defer to peter for specifics.
>
> I always think it is a shame that QEMU has done so much work on
> blockdev, but all QEMU's docs still largely use the many legacy
> syntaxes. IOW, we should make these NBD examples use the modern
> non-URI syntax too.
Agreed, but that is separate patches to this one.
--
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 --]
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2019-09-04 12:54 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-09-03 14:56 [Qemu-devel] [PATCH] docs: Update preferred NBD device syntax Eric Blake
2019-09-03 18:50 ` [Qemu-devel] [Qemu-block] " John Snow
2019-09-03 19:02 ` Eric Blake
2019-09-03 19:06 ` John Snow
2019-09-04 8:18 ` Daniel P. Berrangé
2019-09-04 12:50 ` Eric Blake
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.