Re: [Qemu-devel] [PATCH 3/8] qemu-options qemu-doc: Move "Device URL Syntax" to qemu-doc

[Markus Armbruster]

ronnie sahlberg <address@hidden> writes:

> On Wed, Oct 4, 2017 at 8:12 PM, Marc-André Lureau
> <address@hidden> wrote:
>> On Mon, Oct 2, 2017 at 4:03 PM, Markus Armbruster <address@hidden> 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 <address@hidden>
>>> Cc: Kevin Wolf <address@hidden>
>>> Cc: Max Reitz <address@hidden>
>>> Cc: address@hidden
>>> Signed-off-by: Markus Armbruster <address@hidden>
>>
>> Reviewed-by: Marc-André Lureau <address@hidden>
>>
>>
>>> ---
>>>  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
>>>
>>> address@hidden device_url
>>> address@hidden Device URL Syntax
>>> address@hidden TODO merge this with section Disk Images
>>> +
>>> address@hidden 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.
>>> +
>>> address@hidden @option
>>> address@hidden 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):
>>> address@hidden
>>> +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
>>> address@hidden example
>>> +
>>> +Example (CHAP username/password via URL):
>>> address@hidden
>>> +qemu-system-i386 -drive 
>>> file=iscsi://user%password@@192.0.2.1/iqn.2001-04.com.example/1
>>> address@hidden example
>>> +
>>> +Example (CHAP username/password via environment variables):
>>> address@hidden
>>> +LIBISCSI_CHAP_USERNAME="user" \
>>> +LIBISCSI_CHAP_PASSWORD="password" \
>>> +qemu-system-i386 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
>>> address@hidden example
>>> +
>>> address@hidden 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
>>> address@hidden
>>> +qemu-system-i386 --drive file=nbd:192.0.2.1:30000
>>> address@hidden example
>>> +
>>> +Example for Unix Domain Sockets
>>> address@hidden
>>> +qemu-system-i386 --drive file=nbd:unix:/tmp/nbd-socket
>>> address@hidden example
>>> +
>>> address@hidden SSH
>>> +QEMU supports SSH (Secure Shell) access to remote disks.
>>> +
>>> +Examples:
>>> address@hidden
>>> +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
>>> address@hidden example
>>> +
>>> +Currently authentication must be done using ssh-agent.  Other
>>> +authentication methods may be supported in future.
>>> +
>>> address@hidden 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
>>> address@hidden
>>> +sheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag]
>>> address@hidden example
>>> +
>>> +Example
>>> address@hidden
>>> +qemu-system-i386 --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine
>>> address@hidden example
>>> +
>>> +See also @url{https://sheepdog.github.io/sheepdog/}.
>>> +
>>> address@hidden 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
>>> address@hidden
>>> +
>>> +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":address@hidden"type":"tcp","host":"...","port":"..."@},
>>> +@                                           
>>> @{"type":"unix","socket":"..."@address@hidden@}'
>>> address@hidden example
>>> +
>>> +
>>> +Example
>>> address@hidden
>>> +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":address@hidden"type":"tcp","host":"1.2.3.4","port":address@hidden,
>>> +@                                             
>>> @{"type":"unix","socket":"/var/run/glusterd.socket"@address@hidden@}'
>>> +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
>>> address@hidden example
>>> +
>>> +See also @url{http://www.gluster.org}.
>>> +
>>> address@hidden HTTP/HTTPS/FTP/FTPS
>>> +QEMU supports read-only access to files accessed over http(s) and ftp(s).
>>> +
>>> +Syntax using a single filename:
>>> address@hidden
>>> +<protocol>://[<username>[:<password>]@@]<host>/<path>
>>> address@hidden example
>>> +
>>> +where:
>>> address@hidden @option
>>> address@hidden protocol
>>> +'http', 'https', 'ftp', or 'ftps'.
>>> +
>>> address@hidden username
>>> +Optional username for authentication to the remote server.
>>> +
>>> address@hidden password
>>> +Optional password for authentication to the remote server.
>>> +
>>> address@hidden host
>>> +Address of the remote server.
>>> +
>>> address@hidden path
>>> +Path on the remote server, including any query string.
>>> address@hidden table
>>> +
>>> +The following options are also supported:
>>> address@hidden @option
>>> address@hidden url
>>> +The full URL when passing options to the driver explicitly.
>>> +
>>> address@hidden 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.
>>> +
>>> address@hidden 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'.
>>> +
>>> address@hidden 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.
>>> +
>>> address@hidden 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.
>>> address@hidden 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
>>> address@hidden
>>> +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
>>> address@hidden example
>>> +
>>> +Example: boot from a remote Fedora 20 cloud image using a local overlay for
>>> +writes, copy-on-read, and a readahead of 64k
>>> address@hidden
>>> +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
>>> address@hidden 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.
>>> address@hidden
>>> +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":address@hidden' /tmp/test.qcow2
>>> +
>>> +qemu-system-x86_64 -drive file=/tmp/test.qcow2
>>> address@hidden example
>>> +
>>> address@hidden table
>>> +
>>> address@hidden 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.
>>> -
>>> address@hidden @option
>>> address@hidden 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):
>>> address@hidden
>>> -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
>>> address@hidden example
>>> -
>>> -Example (CHAP username/password via URL):
>>> address@hidden
>>> -qemu-system-i386 -drive 
>>> file=iscsi://user%password@@192.0.2.1/iqn.2001-04.com.example/1
>>> address@hidden example
>>> -
>>> -Example (CHAP username/password via environment variables):
>>> address@hidden
>>> -LIBISCSI_CHAP_USERNAME="user" \
>>> -LIBISCSI_CHAP_PASSWORD="password" \
>>> -qemu-system-i386 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
>>> address@hidden example
[...]
>
> Reviewed-by: Ronnie Sahlberg <address@hidden>
>
>
> At some stage maybe getting rid of
> +Example (CHAP username/password via URL):
> address@hidden
> +qemu-system-i386 -drive
> file=iscsi://user%password@@192.0.2.1/iqn.2001-04.com.example/1
> address@hidden 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.