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

[Markus Armbruster]

ronnie sahlberg  writes:

> On Wed, Oct 4, 2017 at 8:12 PM, Marc-André Lureau
>  wrote:
>> On Mon, Oct 2, 2017 at 4:03 PM, Markus Armbruster  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 
>>> Cc: Kevin Wolf 
>>> Cc: Max Reitz 
>>> Cc: qemu-bl...@nongnu.org
>>> Signed-off-by: Markus Armbruster 
>>
>> Reviewed-by: Marc-André Lureau 
>>
>>
>>> ---
>>>  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://[:]//''
>>> +
>>> +By default qemu will use the iSCSI initiator-name
>>> +'iqn.2008-11.org.linux-kvm[:]' 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::[:exportname=]''
>>> +
>>> +Syntax for specifying a NBD device using Unix Domain Sockets
>>> +``nbd:unix:[:exportname=]''
>>> +
>>> +Example for TCP
>>> +@example
>>> +qemu-system-i386 --drive file=nbd:192.0.2.1:3
>>> +@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
>>> 

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

[ronnie sahlberg]

On Wed, Oct 4, 2017 at 8:12 PM, Marc-André Lureau
 wrote:
> On Mon, Oct 2, 2017 at 4:03 PM, Markus Armbruster  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 
>> Cc: Kevin Wolf 
>> Cc: Max Reitz 
>> Cc: qemu-bl...@nongnu.org
>> Signed-off-by: Markus Armbruster 
>
> Reviewed-by: Marc-André Lureau 
>
>
>> ---
>>  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://[:]//''
>> +
>> +By default qemu will use the iSCSI initiator-name
>> +'iqn.2008-11.org.linux-kvm[:]' 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::[:exportname=]''
>> +
>> +Syntax for specifying a NBD device using Unix Domain Sockets
>> +``nbd:unix:[:exportname=]''
>> +
>> +Example for TCP
>> +@example
>> +qemu-system-i386 --drive file=nbd:192.0.2.1:3
>> +@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
>> 

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

[Marc-André Lureau]

On Mon, Oct 2, 2017 at 4:03 PM, Markus Armbruster  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 
> Cc: Kevin Wolf 
> Cc: Max Reitz 
> Cc: qemu-bl...@nongnu.org
> Signed-off-by: Markus Armbruster 

Reviewed-by: Marc-André Lureau 


> ---
>  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://[:]//''
> +
> +By default qemu will use the iSCSI initiator-name
> +'iqn.2008-11.org.linux-kvm[:]' 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::[:exportname=]''
> +
> +Syntax for specifying a NBD device using Unix Domain Sockets
> +``nbd:unix:[:exportname=]''
> +
> +Example for TCP
> +@example
> +qemu-system-i386 --drive file=nbd:192.0.2.1:3
> +@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:3/MyVirtualMachine
> +@end example
> +
> +See also