ronnie sahlberg <ronniesahlb...@gmail.com> writes: > On Wed, Oct 4, 2017 at 8:12 PM, Marc-André Lureau > <marcandre.lur...@gmail.com> wrote: >> On Mon, Oct 2, 2017 at 4:03 PM, Markus Armbruster <arm...@redhat.com> wrote: >>> Commit 0f5314a (v1.0) added section "Device URL Syntax" to >>> qemu-options.hx. It's enclosed in STEXI..ETEXI, thus affects only >>> qemu-options.texi, not --help. It appears as a subsection under >>> section "Invocation". Similarly, qemu.1 has it as a subsection under >>> "OPTIONS". >>> >>> Commit f9dadc9 (v1.1.0) dropped new option -iscsi into the middle of >>> this section. No effect on qemu-options.texi. It appears in --help >>> run together with the "Bluetooth(R) options:" header. >>> >>> Commit c70a01e (v1.5.0) gives it is own heading in --help by moving >>> commit 0f5314a's DEFHEADING(Device URL Syntax:) outside STEXI..ETEXI. >>> Trouble is the heading makes no sense for -iscsi. >>> >>> Move all of the "Device URL Syntax" Texinfo to qemu-doc.texi. Mark it >>> for inclusion in qemu.1 with '@c man begin NOTES'. This turns it into >>> a separate section outside the list of options both in qemu-doc and in >>> qemu.1. >>> >>> There's substantial overlap with the existing qemu-doc section "Disk >>> Images". Mark with a TODO comment. >>> >>> Output of --help will be fixed next. >>> >>> Cc: Ronnie Sahlberg <ronniesahlb...@gmail.com> >>> Cc: Kevin Wolf <kw...@redhat.com> >>> Cc: Max Reitz <mre...@redhat.com> >>> Cc: qemu-bl...@nongnu.org >>> Signed-off-by: Markus Armbruster <arm...@redhat.com> >> >> Reviewed-by: Marc-André Lureau <marcandre.lur...@redhat.com> >> >> >>> --- >>> qemu-doc.texi | 217 >>> ++++++++++++++++++++++++++++++++++++++++++++++++++++++ >>> qemu-options.hx | 222 >>> -------------------------------------------------------- >>> 2 files changed, 217 insertions(+), 222 deletions(-) >>> >>> diff --git a/qemu-doc.texi b/qemu-doc.texi >>> index ecd186a159..848e49966a 100644 >>> --- a/qemu-doc.texi >>> +++ b/qemu-doc.texi >>> @@ -245,6 +245,223 @@ targets do not need a disk image. >>> >>> @c man end >>> >>> +@node device_url >>> +@subsection Device URL Syntax >>> +@c TODO merge this with section Disk Images >>> + >>> +@c man begin NOTES >>> + >>> +In addition to using normal file images for the emulated storage devices, >>> +QEMU can also use networked resources such as iSCSI devices. These are >>> +specified using a special URL syntax. >>> + >>> +@table @option >>> +@item iSCSI >>> +iSCSI support allows QEMU to access iSCSI resources directly and use as >>> +images for the guest storage. Both disk and cdrom images are supported. >>> + >>> +Syntax for specifying iSCSI LUNs is >>> +``iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>'' >>> + >>> +By default qemu will use the iSCSI initiator-name >>> +'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set from the >>> command >>> +line or a configuration file. >>> + >>> +Since version Qemu 2.4 it is possible to specify a iSCSI request timeout >>> to detect >>> +stalled requests and force a reestablishment of the session. The timeout >>> +is specified in seconds. The default is 0 which means no timeout. Libiscsi >>> +1.15.0 or greater is required for this feature. >>> + >>> +Example (without authentication): >>> +@example >>> +qemu-system-i386 -iscsi >>> initiator-name=iqn.2001-04.com.example:my-initiator \ >>> + -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \ >>> + -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1 >>> +@end example >>> + >>> +Example (CHAP username/password via URL): >>> +@example >>> +qemu-system-i386 -drive >>> file=iscsi://user%password@@192.0.2.1/iqn.2001-04.com.example/1 >>> +@end example >>> + >>> +Example (CHAP username/password via environment variables): >>> +@example >>> +LIBISCSI_CHAP_USERNAME="user" \ >>> +LIBISCSI_CHAP_PASSWORD="password" \ >>> +qemu-system-i386 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1 >>> +@end example >>> + >>> +@item NBD >>> +QEMU supports NBD (Network Block Devices) both using TCP protocol as well >>> +as Unix Domain Sockets. >>> + >>> +Syntax for specifying a NBD device using TCP >>> +``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 >>> +@end example >>> + >>> +Example for Unix Domain Sockets >>> +@example >>> +qemu-system-i386 --drive file=nbd:unix:/tmp/nbd-socket >>> +@end example >>> + >>> +@item SSH >>> +QEMU supports SSH (Secure Shell) access to remote disks. >>> + >>> +Examples: >>> +@example >>> +qemu-system-i386 -drive file=ssh://user@@host/path/to/disk.img >>> +qemu-system-i386 -drive >>> file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img >>> +@end example >>> + >>> +Currently authentication must be done using ssh-agent. Other >>> +authentication methods may be supported in future. >>> + >>> +@item Sheepdog >>> +Sheepdog is a distributed storage system for QEMU. >>> +QEMU supports using either local sheepdog devices or remote networked >>> +devices. >>> + >>> +Syntax for specifying a sheepdog device >>> +@example >>> +sheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag] >>> +@end example >>> + >>> +Example >>> +@example >>> +qemu-system-i386 --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine >>> +@end example >>> + >>> +See also @url{https://sheepdog.github.io/sheepdog/}. >>> + >>> +@item GlusterFS >>> +GlusterFS is a user space distributed file system. >>> +QEMU supports the use of GlusterFS volumes for hosting VM disk images using >>> +TCP, Unix Domain Sockets and RDMA transport protocols. >>> + >>> +Syntax for specifying a VM disk image on GlusterFS volume is >>> +@example >>> + >>> +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 >>> +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}. >>> + >>> +@item HTTP/HTTPS/FTP/FTPS >>> +QEMU supports read-only access to files accessed over http(s) and ftp(s). >>> + >>> +Syntax using a single filename: >>> +@example >>> +<protocol>://[<username>[:<password>]@@]<host>/<path> >>> +@end example >>> + >>> +where: >>> +@table @option >>> +@item protocol >>> +'http', 'https', 'ftp', or 'ftps'. >>> + >>> +@item username >>> +Optional username for authentication to the remote server. >>> + >>> +@item password >>> +Optional password for authentication to the remote server. >>> + >>> +@item host >>> +Address of the remote server. >>> + >>> +@item path >>> +Path on the remote server, including any query string. >>> +@end table >>> + >>> +The following options are also supported: >>> +@table @option >>> +@item url >>> +The full URL when passing options to the driver explicitly. >>> + >>> +@item readahead >>> +The amount of data to read ahead with each range request to the remote >>> server. >>> +This value may optionally have the suffix 'T', 'G', 'M', 'K', 'k' or 'b'. >>> If it >>> +does not have a suffix, it will be assumed to be in bytes. The value must >>> be a >>> +multiple of 512 bytes. It defaults to 256k. >>> + >>> +@item sslverify >>> +Whether to verify the remote server's certificate when connecting over >>> SSL. It >>> +can have the value 'on' or 'off'. It defaults to 'on'. >>> + >>> +@item cookie >>> +Send this cookie (it can also be a list of cookies separated by ';') with >>> +each outgoing request. Only supported when using protocols such as HTTP >>> +which support cookies, otherwise ignored. >>> + >>> +@item timeout >>> +Set the timeout in seconds of the CURL connection. This timeout is the time >>> +that CURL waits for a response from the remote server to get the size of >>> the >>> +image to be downloaded. If not set, the default timeout of 5 seconds is >>> used. >>> +@end table >>> + >>> +Note that when passing options to qemu explicitly, @option{driver} is the >>> value >>> +of <protocol>. >>> + >>> +Example: boot from a remote Fedora 20 live ISO image >>> +@example >>> +qemu-system-x86_64 --drive >>> media=cdrom,file=http://dl.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly >>> + >>> +qemu-system-x86_64 --drive >>> media=cdrom,file.driver=http,file.url=http://dl.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly >>> +@end example >>> + >>> +Example: boot from a remote Fedora 20 cloud image using a local overlay for >>> +writes, copy-on-read, and a readahead of 64k >>> +@example >>> +qemu-img create -f qcow2 -o backing_file='json:@{"file.driver":"http",, >>> "file.url":"https://dl.fedoraproject.org/pub/fedora/linux/releases/20/Images/x86_64/Fedora-x86_64-20-20131211.1-sda.qcow2",, >>> "file.readahead":"64k"@}' /tmp/Fedora-x86_64-20-20131211.1-sda.qcow2 >>> + >>> +qemu-system-x86_64 -drive >>> file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on >>> +@end example >>> + >>> +Example: boot from an image stored on a VMware vSphere server with a >>> self-signed >>> +certificate using a local overlay for writes, a readahead of 64k and a >>> timeout >>> +of 10 seconds. >>> +@example >>> +qemu-img create -f qcow2 -o backing_file='json:@{"file.driver":"https",, >>> "file.url":"https://user:password@@vsphere.example.com/folder/test/test-flat.vmdk?dcPath=Datacenter&dsName=datastore1",, >>> "file.sslverify":"off",, "file.readahead":"64k",, "file.timeout":10@}' >>> /tmp/test.qcow2 >>> + >>> +qemu-system-x86_64 -drive file=/tmp/test.qcow2 >>> +@end example >>> + >>> +@end table >>> + >>> +@c man end >>> + >>> @node pcsys_keys >>> @section Keys in the graphical frontends >>> >>> diff --git a/qemu-options.hx b/qemu-options.hx >>> index 39f0e1b990..f112281d37 100644 >>> --- a/qemu-options.hx >>> +++ b/qemu-options.hx >>> @@ -2812,234 +2812,12 @@ ETEXI >>> DEFHEADING() >>> >>> DEFHEADING(Device URL Syntax:) >>> -STEXI >>> - >>> -In addition to using normal file images for the emulated storage devices, >>> -QEMU can also use networked resources such as iSCSI devices. These are >>> -specified using a special URL syntax. >>> - >>> -@table @option >>> -@item iSCSI >>> -iSCSI support allows QEMU to access iSCSI resources directly and use as >>> -images for the guest storage. Both disk and cdrom images are supported. >>> - >>> -Syntax for specifying iSCSI LUNs is >>> -``iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>'' >>> - >>> -By default qemu will use the iSCSI initiator-name >>> -'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set from the >>> command >>> -line or a configuration file. >>> - >>> -Since version Qemu 2.4 it is possible to specify a iSCSI request timeout >>> to detect >>> -stalled requests and force a reestablishment of the session. The timeout >>> -is specified in seconds. The default is 0 which means no timeout. Libiscsi >>> -1.15.0 or greater is required for this feature. >>> - >>> -Example (without authentication): >>> -@example >>> -qemu-system-i386 -iscsi >>> initiator-name=iqn.2001-04.com.example:my-initiator \ >>> - -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \ >>> - -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1 >>> -@end example >>> - >>> -Example (CHAP username/password via URL): >>> -@example >>> -qemu-system-i386 -drive >>> file=iscsi://user%password@@192.0.2.1/iqn.2001-04.com.example/1 >>> -@end example >>> - >>> -Example (CHAP username/password via environment variables): >>> -@example >>> -LIBISCSI_CHAP_USERNAME="user" \ >>> -LIBISCSI_CHAP_PASSWORD="password" \ >>> -qemu-system-i386 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1 >>> -@end example [...] > > Reviewed-by: Ronnie Sahlberg <ronniesahlb...@gmail.com> > > > At some stage maybe getting rid of > +Example (CHAP username/password via URL): > +@example > +qemu-system-i386 -drive > file=iscsi://user%password@@192.0.2.1/iqn.2001-04.com.example/1 > +@end example > + > > and only document the "set user/password via ENV" > as it was probably a mistake to allow setting these via the URL in the > first place. > > Possibly consider not document that it is possible to use the URL for > user/password > as to discourage its use?
I think the appropriate way to do that would be deprecating the feature in a separate patch, in accordance with the policy laid down in qemu-doc's appendix "Deprecated features". I think backing out any documentation added in the current development cycle in such a patch would be just fine.