Skip to contentSkip to conversation

docs: Update preferred NBD device syntax

PATCH In review Eric Blake 3 participants 6 messages Sep 3, 2019 – Sep 4, 2019

lore
Share & tools
lore

Eric Blake

author
#0 lore raw

PATCH 1/1 docs: Update preferred NBD device syntax

Mention the preferred URI form, especially since NBD is trying to standardize that form: https://lists.debian.org/nbd/2019/06/msg00012.html

---
 qemu-doc.texi | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)
qemu-doc.texi +9 -2
index 577d1e837640..c83fb347d77e 100644
@@ -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

Signature · 1 line
2.21.0
Reviewed-by on v1 1/1
#1 lore raw
Quoted 18 lines · Eric Blake

Mention the preferred URI form, especially since NBD is trying to standardize that form: https://lists.debian.org/nbd/2019/06/msg00012.html

---
 qemu-doc.texi | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)
qemu-doc.texi +1 -1
index 577d1e837640..c83fb347d77e 100644
@@ -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.

qemu-doc.texi qemu-system-i386 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1 · line 309

Quoted 10 lines
qemu-doc.texi +8 -1
 
-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?

Quoted 9 lines
qemu-doc.texi +0 -2
 ``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-doc.texi qemu-system-i386 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1

Quoted 10 lines
qemu-doc.texi +2 -1
+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
author
#2 lore raw

[adding libvirt list]

Quoted 22 lines · John Snow
Quoted 19 lines · Eric Blake

Mention the preferred URI form, especially since NBD is trying to standardize that form: https://lists.debian.org/nbd/2019/06/msg00012.html

---
 qemu-doc.texi | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)
qemu-doc.texi +1 -1
index 577d1e837640..c83fb347d77e 100644
@@ -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.
 
Quoted 16 lines

qemu-doc.texi qemu-system-i386 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1 · line 309

Quoted 9 lines
qemu-doc.texi +8 -1
-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?

Quoted 4 lines
qemu-doc.texi +0 -1
 ``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?

Quoted 13 lines
Quoted 13 lines

Example for TCP
@example

qemu-doc.texi +2 -2
-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
Quoted 4 lines
Quoted 2 lines

@item SSH

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

Signature · 3 lines
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3226
Virtualization:  qemu.org | libvirt.org
#3 lore raw
Quoted 39 lines · Eric Blake

[adding libvirt list]

Quoted 36 lines · John Snow
Quoted 18 lines · Eric Blake

Mention the preferred URI form, especially since NBD is trying to standardize that form: https://lists.debian.org/nbd/2019/06/msg00012.html

---
 qemu-doc.texi | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)
qemu-doc.texi +1 -1
index 577d1e837640..c83fb347d77e 100644
@@ -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.

qemu-doc.texi qemu-system-i386 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1 · line 309

Quoted 10 lines
qemu-doc.texi +8 -1
 
-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?

Quoted 2 lines
qemu-doc.texi +0 -0
 ``nbd:<server-ip>:<port>[:exportname=<export>]''
Quoted 9 lines
Quoted 2 lines
Quoted 2 lines

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

Quoted 21 lines
Quoted 13 lines
Quoted 13 lines

Example for TCP
@example

qemu-doc.texi +2 -2
-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
Quoted 4 lines
Quoted 2 lines

@item SSH

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

#4 lore raw
Quoted 52 lines · John Snow
Quoted 39 lines · Eric Blake

[adding libvirt list]

Quoted 36 lines · John Snow
Quoted 18 lines · Eric Blake

Mention the preferred URI form, especially since NBD is trying to standardize that form: https://lists.debian.org/nbd/2019/06/msg00012.html

---
 qemu-doc.texi | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)
qemu-doc.texi +1 -1
index 577d1e837640..c83fb347d77e 100644
@@ -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.

qemu-doc.texi qemu-system-i386 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1 · line 309

Quoted 10 lines
qemu-doc.texi +8 -1
 
-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?

Quoted 2 lines
qemu-doc.texi +0 -0
 ``nbd:<server-ip>:<port>[:exportname=<export>]''
Quoted 9 lines
Quoted 2 lines
Quoted 2 lines

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

Quoted 8 lines

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.

Quoted 27 lines

If you don't have motivation for doing it unprompted I have little reason to coerce you into it.

Quoted 21 lines
Quoted 13 lines
Quoted 13 lines

Example for TCP
@example

qemu-doc.texi +2 -2
-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
Quoted 4 lines
Quoted 2 lines

@item SSH

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

Regards,
Daniel

Signature · 3 lines
|: 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 :|
author
#5 lore raw
Quoted 5 lines · Daniel P. Berrangé
Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
qemu-doc.texi +3 -1
-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>]''
+
Quoted 7 lines
Quoted 2 lines
Quoted 2 lines
Quoted 2 lines
Quoted 2 lines

``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.

Quoted 8 lines

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.

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