Documentation: Add section about iSCSI LUNS to qemu-doc

Add a new section about using iSCSI LUNs with qemu
and provide a short example on how to set up a target and access it
using the built-in initiator

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

Hi,

I have only some small remarks, see my inline comments below.

Am 11.11.2011 22:46, schrieb Ronnie Sahlberg:
> Add a new section about using iSCSI LUNs with qemu
> and provide a short example on how to set up a target and access it
> using the built-in initiator
>
> Signed-off-by: Ronnie Sahlberg <ronniesahlberg@gmail.com>
> ---
> qemu-doc.texi | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++
> 1 files changed, 53 insertions(+), 0 deletions(-)
>
> diff --git a/qemu-doc.texi b/qemu-doc.texi
> index 149e9bd..c1b293e 100644
> --- a/qemu-doc.texi
> +++ b/qemu-doc.texi
> @@ -421,6 +421,7 @@ snapshots.
> * disk_images_fat_images:: Virtual FAT disk images
> * disk_images_nbd:: NBD access
> * disk_images_sheepdog:: Sheepdog disk images
> +* disk_images_iscsi:: iSCSI LUNs
> @end menu
>
> @node disk_images_quickstart
> @@ -695,6 +696,58 @@ qemu-img create 
> sheepdog:@var{hostname}:@var{port}:@var{image} @var{size}
> qemu sheepdog:@var{hostname}:@var{port}:@var{image}
> @end example
>
> +@node disk_images_iscsi
> +@subsection iSCSI LUNs
> +
> +iSCSI is a popular protocol used to access SCSI devices across a computer
> +network.
> +
> +There are two different ways iSCSI devices can be used by QEMU.
> +
> +The first method is to mount the iSCSI LUN on the host, and make it 
> appear as
> +any other ordinary SCSI device on the host and then to access this 
> device as a
> +/dev/sd device from QEMU. How to do this differs between host OSes.
> +
> +The second method involves using the iSCSI initiator that is built into
> +QEMU. This provides a mechanism that works the same way regardless of 
> which
> +host OS you are running QEMU on. This section will describe this 
> second method
> +of using iSCSI together with QEMU.
> +
> +In QEMU, iSCSI devices are described using special iSCSI URLs
> +
> +@example
> +URL syntax:
> +iscsi://[<username>[%<password>]@@]<host>[:<port>]/<target-iqn-name>/<lun>
> +@end example
> +
> +Username and password are optional and only used if your taget is set up

taget -> target

> +using CHAP authentication for access control.
> +Alternatively the username and passwords can also be set via environment

password instead of passwords?

> +variables to have these not show up in the process list
> +
> +@example
> +export LIBISCSI_CHAP_USERNAME=<username>
> +export LIBISCSI_CHAP_PASSWORD=<password>
> +iscsi://<host>/<target-iqn-name>/<lun>
> +@end example
> +
> +Howto set up a simple iSCSI target on loopback and accessing it via QEMU:
> +@example
> +Setting up a iSCSI target with one CDROM and one DISK:
> +tgtd --iscsi portal=127.0.0.1:3260
> +tgtadm --lld iscsi --op new --mode target --tid 1 -T iqn.qemu.test
> +tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 1 \
> + -b /IMAGES/disk.img --device-type=disk
> +tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 2 \
> + -b /IMAGES/cd.iso --device-type=cd
> +tgtadm --lld iscsi --op bind --mode target --tid 1 -I ALL
> +
> +qemu -boot d -drive file=iscsi://127.0.0.1/iqn.qemu.test/1 \

There is no qemu executable any longer. You may choose from
a large number of executable names, e.g. qemu-system-i386.

> + -cdrom iscsi://127.0.0.1/iqn.qemu.test/2
> +@end example
> +
> +
> +
> @node pcsys_network
> @section Network emulation

Thanks for providing this documentation.

Kind regards,

Stefan Weil

Hi,

Am 11.11.2011 22:46, schrieb Ronnie Sahlberg:
> Add a new section about using iSCSI LUNs with qemu
> and provide a short example on how to set up a target and access it
> using the built-in initiator
> 
> Signed-off-by: Ronnie Sahlberg <ronniesahlberg@gmail.com>
> ---
>  qemu-doc.texi |   53 +++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 files changed, 53 insertions(+), 0 deletions(-)
> 
> diff --git a/qemu-doc.texi b/qemu-doc.texi
> index 149e9bd..c1b293e 100644
> --- a/qemu-doc.texi
> +++ b/qemu-doc.texi

> +Howto set up a simple iSCSI target on loopback and accessing it via QEMU:
> +@example
> +Setting up a iSCSI target with one CDROM and one DISK:
> +tgtd --iscsi portal=127.0.0.1:3260
> +tgtadm --lld iscsi --op new --mode target --tid 1 -T iqn.qemu.test
> +tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 1 \
> +    -b /IMAGES/disk.img --device-type=disk
> +tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 2 \
> +    -b /IMAGES/cd.iso --device-type=cd
> +tgtadm --lld iscsi --op bind --mode target --tid 1 -I ALL

Having an example is always good.

These commands and parameters don't seem familiar to me, having worked
with iSCSI on Solaris, so this part of the example seems
platform-specific. Could you mention that this example is for Linux? Or
what specific upstream project these tools can be obtained from?

Please also remember to choose a subject, a recurring fault. ;)

Thanks,

Andreas

Hi,

On Sat, Nov 12, 2011 at 10:11 AM, Andreas Färber <andreas.faerber@web.de> wrote:
> Hi,
>
> Am 11.11.2011 22:46, schrieb Ronnie Sahlberg:
>> Add a new section about using iSCSI LUNs with qemu
>> and provide a short example on how to set up a target and access it
>> using the built-in initiator
>>
>> Signed-off-by: Ronnie Sahlberg <ronniesahlberg@gmail.com>
>> ---
>>  qemu-doc.texi |   53 +++++++++++++++++++++++++++++++++++++++++++++++++++++
>>  1 files changed, 53 insertions(+), 0 deletions(-)
>>
>> diff --git a/qemu-doc.texi b/qemu-doc.texi
>> index 149e9bd..c1b293e 100644
>> --- a/qemu-doc.texi
>> +++ b/qemu-doc.texi
>
>> +Howto set up a simple iSCSI target on loopback and accessing it via QEMU:
>> +@example
>> +Setting up a iSCSI target with one CDROM and one DISK:
>> +tgtd --iscsi portal=127.0.0.1:3260
>> +tgtadm --lld iscsi --op new --mode target --tid 1 -T iqn.qemu.test
>> +tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 1 \
>> +    -b /IMAGES/disk.img --device-type=disk
>> +tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 2 \
>> +    -b /IMAGES/cd.iso --device-type=cd
>> +tgtadm --lld iscsi --op bind --mode target --tid 1 -I ALL
>
> Having an example is always good.
>
> These commands and parameters don't seem familiar to me, having worked
> with iSCSI on Solaris, so this part of the example seems
> platform-specific. Could you mention that this example is for Linux? Or
> what specific upstream project these tools can be obtained from?
>

I have mentioned now that this is Linux STGT target and that it comes
in the scsi-target-utils package.

Maybe add an example for Solaris too?
I don't use Solaris myself so I dont know how to configure iSCSI
target on Solaris.

Does OpenSolaris come with the same iSCSI target as Real-Solaris? If
so I could set it up in a VM and
try to figure out what a Solaris example could look like.


IMHO, examples are useful to get people up and running real quick to
get to a point where one they start experimenting.
straight away without having to search/learn lots of stuff first.



> Please also remember to choose a subject, a recurring fault. ;)

I know, I am completely hopless with 'git-send-email' :-)

regards
ronnie sahlberg