[v3,01/38] Documentation: Add section about iSCSI LUNS to qemu-doc

Message ID 1322048728-26061-2-git-send-email-stefanha@linux.vnet.ibm.com
State New
Headers show

Commit Message

Stefan Hajnoczi Nov. 23, 2011, 11:44 a.m.
From: Ronnie Sahlberg <ronniesahlberg@gmail.com>

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>
Signed-off-by: Kevin Wolf <kwolf@redhat.com>
 qemu-doc.texi |   56 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 56 insertions(+), 0 deletions(-)


diff --git a/qemu-doc.texi b/qemu-doc.texi
index 149e9bd..1abba98 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,61 @@  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
+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
+URL syntax:
+@end example
+Username and password are optional and only used if your target is set up
+using CHAP authentication for access control.
+Alternatively the username and password can also be set via environment
+variables to have these not show up in the process list
+export LIBISCSI_CHAP_USERNAME=<username>
+export LIBISCSI_CHAP_PASSWORD=<password>
+@end example
+Howto set up a simple iSCSI target on loopback and accessing it via QEMU:
+This example shows how to set up an iSCSI target with one CDROM and one DISK
+using the Linux STGT software target. This target is available on Red Hat based
+systems as the package 'scsi-target-utils'.
+tgtd --iscsi portal=
+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-system-i386 -boot d -drive file=iscsi:// \
+    -cdrom iscsi://
+@end example
 @node pcsys_network
 @section Network emulation