[Qemu-devel] [PATCH 0/0] Add mention of iSCSI devices to manpage

[Qemu-devel] [PATCH 0/0] Add mention of iSCSI devices to manpage

[Ronnie Sahlberg]

List

Following patch adds a new section to the manpage to describe the special URL syntax used for various block backends.
It adds a subsection with examples on the newly added iSCSI backend.

Perhaps all other backeds can be added with examples to this section as well?
In which case I add patches for some of them if examples on how to use them can be provided.


Please comment on the idea of a new section to describe all different backends and URLs, and/or merge


(if it is not in the manpage it does not exist)

[Qemu-devel] [PATCH] Documentation: add new section for device URL syntax for special files and describe the iSCSI URL with examples

[Ronnie Sahlberg]

Signed-off-by: Ronnie Sahlberg <ronniesahlberg@gmail.com>
---
 qemu-options.hx |   42 ++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 42 insertions(+), 0 deletions(-)

diff --git a/qemu-options.hx b/qemu-options.hx
index 5d2a776..7c434f8 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -148,6 +148,9 @@ Define a new drive. Valid options are:
 This option defines which disk image (@pxref{disk_images}) to use with
 this drive. If the filename contains comma, you must double it
 (for instance, "file=my,,file" to use file "my,file").
+
+Special files such as iSCSI devices can be specified using protocol
+specific URLs. See the section for "Device URL Syntax" for more information.
 @item if=@var{interface}
 This option defines on which type on interface the drive is connected.
 Available types are: ide, scsi, sd, mtd, floppy, pflash, virtio.
@@ -1718,6 +1721,45 @@ ETEXI
 
 DEFHEADING()
 
+DEFHEADING(Device URL Syntax:)
+
+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.
+
+STEXI
+@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>''
+
+Example (without authentication):
+@example
+qemu -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 --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 --drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
+@end example
+
+iSCSI support is an optional feature of QEMU and only available when
+compiled and linked against libiscsi.
+
+@end table
+ETEXI
+
 DEFHEADING(Bluetooth(R) options:)
 
 DEF("bt", HAS_ARG, QEMU_OPTION_bt, \
-- 
1.7.3.1

Re: [Qemu-devel] [PATCH] Documentation: add new section for device URL syntax for special files and describe the iSCSI URL with examples

[Stefan Hajnoczi]

On Wed, Oct 26, 2011 at 11:51:37PM +1100, Ronnie Sahlberg wrote:
> 
> Signed-off-by: Ronnie Sahlberg <ronniesahlberg@gmail.com>
> ---
>  qemu-options.hx |   42 ++++++++++++++++++++++++++++++++++++++++++
>  1 files changed, 42 insertions(+), 0 deletions(-)

Good idea, thanks for adding documentation.

Reviewed-by: Stefan Hajnoczi <stefanha@linux.vnet.ibm.com>

Re: [Qemu-devel] [PATCH] Documentation: add new section for device URL syntax for special files and describe the iSCSI URL with examples

[Kevin Wolf]

Am 26.10.2011 14:51, schrieb Ronnie Sahlberg:
> Signed-off-by: Ronnie Sahlberg <ronniesahlberg@gmail.com>
> ---
>  qemu-options.hx |   42 ++++++++++++++++++++++++++++++++++++++++++
>  1 files changed, 42 insertions(+), 0 deletions(-)

Thanks, applied to the block branch.

For future patches, please keep the subject lines short and place the
longer text in the body (first line in the git commit message is the
subject, the second one should stay empty, and the body starts at the
third line)

Kevin

Re: [Qemu-devel] [PATCH] Documentation: add new section for device URL syntax for special files and describe the iSCSI URL with examples

[Kevin Wolf]

Am 27.10.2011 09:14, schrieb Stefan Hajnoczi:
> On Wed, Oct 26, 2011 at 11:51:37PM +1100, Ronnie Sahlberg wrote:
>>
>> Signed-off-by: Ronnie Sahlberg <ronniesahlberg@gmail.com>
>> ---
>>  qemu-options.hx |   42 ++++++++++++++++++++++++++++++++++++++++++
>>  1 files changed, 42 insertions(+), 0 deletions(-)
> 
> Good idea, thanks for adding documentation.
> 
> Reviewed-by: Stefan Hajnoczi <stefanha@linux.vnet.ibm.com>

Breaks the build. I'll amend the commit with the following changes:

diff --git a/qemu-options.hx b/qemu-options.hx
index 7c434f8..f967fb9 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -1719,6 +1719,7 @@ Connect to a spice virtual machine channel, such
as vdiport.
 @end table
 ETEXI

+STEXI
 DEFHEADING()

 DEFHEADING(Device URL Syntax:)
@@ -1727,7 +1728,6 @@ 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.

-STEXI
 @table @option
 @item iSCSI
 iSCSI support allows QEMU to access iSCSI resources directly and use as
@@ -1744,7 +1744,7 @@ qemu -cdrom
iscsi://192.0.2.1/iqn.2001-04.com.example/2 \

 Example (CHAP username/password via URL):
 @example
-qemu --drive file=iscsi://user%password@192.0.2.1/iqn.2001-04.com.example/1
+qemu --drive
file=iscsi://user%password@@192.0.2.1/iqn.2001-04.com.example/1
 @end example

 Example (CHAP username/password via environment variables):