From 304f1aeb5815bcfb5b5ce8a4c2f7e0da8db3d529 Mon Sep 17 00:00:00 2001
From: Hannes Reinecke <hare@suse.de>
Date: Thu, 4 Oct 2012 15:11:59 +0200
Subject: Add lio-utils HOWTO

Some documentation is always helpful, even though it might be
slightly outdated.

Signed-off-by: Hannes Reinecke <hare@suse.de>
---
 lio-utils.HOWTO |  338 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 338 insertions(+)
 create mode 100644 lio-utils.HOWTO

diff --git a/lio-utils.HOWTO b/lio-utils.HOWTO
new file mode 100644
index 0000000..dba6a4f
--- /dev/null
+++ b/lio-utils.HOWTO
@@ -0,0 +1,338 @@
+lio-utils HOWTO
+
+The lio-utils HOWTO covers getting up and running with the lio-utils
+CLI for Target+iSCSI.
+
+Contents
+    1 Documentation
+    2 Building the Target
+    3 Starting the Target
+    4 Configuring the Target
+        4.1 IBLOCK (Linux BLOCK)
+        4.2 PSCSI (Linux SCSI)
+        4.3 FILEIO (Linux VFS)
+        4.4 RAMDISK
+    5 Displaying the Target status
+    6 Configuring iSCSI
+        6.1 Creating Logical Units and TPGs
+        6.2 Creating Network Portals
+        6.3 Modifying the TPG settings
+            6.3.1 Enabling demo mode
+            6.3.2 Disabling CHAP authentication
+            6.3.3 Setting up ACLs
+        6.4 Enabling the TPG
+    7 See also
+    8 External links
+
+Documentation
+
+The LIO User's Reference Manual contains detailed operating
+instructions. It also describes how to setup a number of different
+subsystem storage object backstores for LIO LUN endpoints.
+
+Warning: Use targetcli instead.
+lio-utils are deprecated and have been superseded by targetcli.
+
+Starting the Target
+
+lio-utils will install an init.d script in /etc/init.d/target. Calling
+/etc/init.d/target start mounts Target/configFS and loads the
+target_core_mod. Upon successfully starting up the first time, you
+should see the following:
+
+target:~# /etc/init.d/target start
+Loading target_core_mod/ConfigFS core:   [OK]
+
+And the following will appear in the kernel ring buffer (dmesg) and
+klogd output in /var/log:
+
+TARGET_CORE[0]: Loading Generic Kernel Storage Engine: v3.0.0 on Linux/i686 on 2.6.30
+TARGET_CORE[0]: Initialized ConfigFS Fabric Infrastructure: v1.0.0 on Linux/i686 on 2.6.30
+SE_PC[0] - Registered Plugin Class: TRANSPORT
+PLUGIN_TRANSPORT[1] - pscsi registered
+PLUGIN_TRANSPORT[2] - stgt registered
+CORE_STGT[0]: Bus Initalization complete
+PLUGIN_TRANSPORT[4] - iblock registered
+PLUGIN_TRANSPORT[5] - rd_mcp registered
+PLUGIN_TRANSPORT[6] - fileio registered
+SE_PC[1] - Registered Plugin Class: OBJ
+PLUGIN_OBJ[1] - dev registered
+
+Configuring the Target
+
+Now, it is time to configure the Target storage objects. They
+represent SCSI devices, such as PSCSI, IBLOCK, FILEIO or RAMDISK via
+the different Target subsystem plugins.
+
+IBLOCK (Linux BLOCK)
+
+Using a struct block_device from Linux/BLOCK requires a udev path from
+/dev/, /dev/mapper/, /dev/$LV_GROUP/ or /dev/disk/. Here is what it
+looks like for an LVM Device + Device-Mapper block device using
+/dev/$VG_GROUP/$LVM_NAME - but the same applies to any block device
+that appears in /dev/. Note that a T10 WWN Unit Serial will be
+generated upon a successful call to --block.
+
+The tcm_node --help entry is:
+
+--block=HBA/DEV <UDEV_PATH>, --iblock=HBA/DEV <UDEV_PATH>
+        Associate TCM/IBLOCK object with Linux/BLOCK device
+
+The live Linux LVM block device looks like:
+
+target:~# tcm_node --block iblock_0/my_linux_lvm2 /dev/lio-test/test0
+ConfigFS HBA: iblock_0
+Successfully added TCM/ConfigFS HBA: iblock_0
+  ConfigFS Device Alias: my_linux_lvm2
+Device Params ['/dev/lio-test/test0']
+Status: DEACTIVATED  Execute/Left/Max Queue Depth: 0/32/32  SectorSize: 512  MaxSectors: 128
+        iBlock device: dm-2
+        Major: 254 Minor: 2  CLAIMED: IBLOCK
+Set T10 WWN Unit Serial for iblock_0/my_linux_lvm2 to: 177086e9-6310-4c7a-9287-d50e06bdf071
+Successfully created TCM/ConfigFS storage object: /sys/kernel/config/target/core/iblock_0/my_linux_lvm2
+
+PSCSI (Linux SCSI)
+
+Using a struct scsi_device from Linux/SCSI requires a SCSI HCTL
+(Host,Channel,Target,LUN) or udev path in /dev/ or /dev/disk/. For the
+HCTL association method tcm_node --scsi is used, and for UDEV path
+association the tcm_node --scsibyudev operation is used.
+
+Warning: Avoid PSCSI.
+Do not use PSCSI unless you know exactly how it will be used. Advanced
+SCSI CDBs such as for Persistent Reservations or ALUAs (used e.g. by
+VMware ESX and vSphere) are typically not implemented in the device
+firmware, and can cause malfunctions or crashes. Instead, use IBLOCK
+for typical production setups.
+
+PSCSI does not generate T10 WWN information automatically upon a
+successful --scsi or --scsibydev operation as it is the default
+behaviour of the other backstore subsystem operations (IBLOCK, FILEIO
+and RAMDISK). pSCSI expects the T10 WWN, Persistent Reservations and
+ALUA information to be provided by the firmware of the underlying
+struct SCSI device and/or Linux/SCSI LLD.
+
+That is, pSCSI does not provide SCSI-3 control path emulation for
+"SCSI passthrough" into Linux/SCSI. SCSI-3 control path emulation on
+top of Linux SCSI devices is provided by tcm_loop.
+
+The tcm_node --help entry is:
+
+--scsi=HBA/DEV <C:T:L>, --pscsi=HBA/DEV <C:T:L>
+        Associate TCM/pSCSI object with Linux/SCSI device by
+        bus location
+--scsibyudev=DEV <UDEV_PATH>, --pscsibyudev=DEV <UDEV_PATH>
+        Associate TCM/pSCSI object with Linux/SCSI device by
+        UDEV Path
+
+The live Linux LVM block device looks like:
+
+target:~# tcm_node --scsi pscsi_0/sdf 0:5:0
+ConfigFS HBA: pscsi_0
+  ConfigFS Device Alias: sdf
+Device Params ['scsi_channel_id=0,scsi_target_id=5,scsi_lun_id=0']
+Status: DEACTIVATED  Execute/Left/Max Queue Depth: 0/32/32  SectorSize: 512  MaxSectors: 1024
+        SCSI Device Bus Location: Channel ID: 0 Target ID: 5 LUN: 0
+        Vendor: VMware,  Model: VMware Virtual S Rev: 1.0    CLAIMED: PSCSI
+Successfully created TCM/ConfigFS storage object: /sys/kernel/config/target/core/pscsi_0/sdf
+
+The other method is to associate a struct scsi_device by udev_path
+using tcm_node --scsibyudev. Note the --scsibyudev operation only
+requires the 'DEV' alias parameter (and not HBA/DEV) and will
+automatically register the referenced struct scsi_host:
+
+target:~# tcm_node --scsibyudev sde /dev/disk/by-path/pci-0000\:00\:10.0-scsi-0\:0\:4\:0
+  ConfigFS Device Alias: sde
+pSCSI: Referencing HCTL 0:0:4:0 for udev_path: /dev/disk/by-path/pci-0000:00:10.0-scsi-0:0:4:0
+pSCSI: Created cfs_path: /sys/kernel/config/target/core/pscsi_0/sde/
+Status: DEACTIVATED  Execute/Left/Max Queue Depth: 0/32/32  SectorSize: 512  MaxSectors: 1024
+        SCSI Device Bus Location: Channel ID: 0 Target ID: 4 LUN: 0
+        Vendor: VMware,  Model: VMware Virtual S Rev: 1.0    CLAIMED: PSCSI
+Successfully created TCM/ConfigFS storage object: /dev/disk/by-path/pci-0000:00:10.0-scsi-0:0:4:0
+
+FILEIO (Linux VFS)
+
+Using a struct file from Linux/VFS requires a filename and size (if it
+is a file on a mounted filesystem) or a filename with size 0 if the
+struct file is referencing an underlying block device (e.g.:
+/dev/sde). Note that a T10 WWN Unit Serial will be generated upon a
+successfully call to --fileio.
+
+The tcm_node --help entry is:
+
+--fileio=HBA/DEV <FILE> <SIZE_IN_BYTES>
+        Associate TCM/FILEIO object with Linux/VFS file or
+        underlying device for buffered FILEIO
+
+The live Linux LVM block device looks like:
+
+target:~# tcm_node --fileio fileio_0/some_file /tmp/some_file 10000000
+  ConfigFS HBA: fileio_0
+Successfully added TCM/ConfigFS HBA: fileio_0
+ConfigFS Device Alias: some_file
+Device Params ['fd_dev_name=/tmp/some_file,fd_dev_size=10000000']
+Status: DEACTIVATED  Execute/Left/Max Queue Depth: 0/32/32  SectorSize: 512  MaxSectors: 1024
+        LIO FILEIO ID: 0        File: /tmp/some_file  Size: 10000000
+Set T10 WWN Unit Serial for fileio_0/some_file to: 1d14c7d4-6b0e-4065-9e25-e379142d319c
+Successfully created TCM/ConfigFS storage object: /sys/kernel/config/target/core/fileio_0/some_file
+
+RAMDISK
+
+Creating a RAMDISK_MCP storage object is done using
+tcm_node --ramdisk. This operation requires a page_count value to be
+supplied to determine the size of the RAMDISK object. Note that a T10
+WWN Unit Serial will be generated upon a successfully call to
+--ramdisk.
+
+The tcm_node --help entry is:
+
+--ramdisk=HBA/DEV <PAGES>
+        Create and associate TCM/RAMDISK object
+
+and the live Linux LVM block device looks like:
+
+target:~# tcm_node --ramdisk rd_mcp_0/some_rd 8192
+  ConfigFS HBA: rd_mcp_0
+Successfully added TCM/ConfigFS HBA: rd_mcp_0
+ConfigFS Device Alias: some_rd
+Device Params ['8192']
+Status: DEACTIVATED  Execute/Left/Max Queue Depth: 0/32/32  SectorSize: 512  MaxSectors: 1024
+        TCM RamDisk ID: 0  RamDisk Makeup: rd_mcp
+        PAGES/PAGE_SIZE: 8192*4096  SG_table_count: 5
+Set T10 WWN Unit Serial for rd_mcp_0/some_rd to: 54bae46a-ea5d-4090-bed0-d8a21f0060e3
+Successfully created TCM/ConfigFS storage object: /sys/kernel/config/target/core/rd_mcp_0/some_rd
+
+Displaying the Target status
+
+The status of the live Target can be displayed with /etc/init.d/target
+status, which calls tcm_node --listhbas to show the current
+Target/configFS storage objects. Here is the target status after
+successfully registering the Linux/BLOCK, Linux/pSCSI, Linux/VFS and
+Target/RAMDISK objects with individual calls to tcm_node --block,
+--scsi, --scsibyudev, --fileio, and --ramdisk:
+
+target:~# /etc/init.d/target status
+[---------------------------] TCM/ConfigFS Status [----------------------------]
+\------> rc_mcp_0
+        HBA Index: 3 plugin: rc_mcp version: v1.0.0
+        \-------> some_rd
+        Status: DEACTIVATED  Execute/Left/Max Queue Depth: 0/32/32  SectorSize: 512  MaxSectors: 1024
+        LIO RamDisk ID: 0  RamDisk Makeup: rd_mcp
+        PAGES/PAGE_SIZE: 8192*4096  SG_table_count: 3
+        udev_path: N/A
+\------> fileio_0
+        HBA Index: 2 plugin: fileio version: v1.0.0
+        \-------> some_file
+        Status: DEACTIVATED  Execute/Left/Max Queue Depth: 0/32/32  SectorSize: 512  MaxSectors: 1024
+        LIO FILEIO ID: 0        File: /tmp/some_file  Size: 10000000
+        udev_path: N/A
+\------> iblock_0
+        HBA Index: 1 plugin: iblock version: v1.0.0
+        \-------> my_linux_lvm2
+        Status: DEACTIVATED  Execute/Left/Max Queue Depth: 0/32/32  SectorSize: 512  MaxSectors: 128
+        iBlock device: dm-2
+        Major: 254 Minor: 2  CLAIMED: IBLOCK
+        udev_path: /dev/lio-test/test0
+\------> pscsi_0
+        HBA Index: 0 plugin: pscsi version: v1.0.0
+        \-------> sdf
+        Status: DEACTIVATED  Execute/Left/Max Queue Depth: 0/32/32  SectorSize: 512  MaxSectors: 1024
+        SCSI Device Bus Location: Channel ID: 0 Target ID: 5 LUN: 0
+        Vendor: VMware,  Model: VMware Virtual S Rev: 1.0    CLAIMED: PSCSI
+        udev_path: N/A
+        \-------> sde
+        Status: DEACTIVATED  Execute/Left/Max Queue Depth: 0/32/32  SectorSize: 512  MaxSectors: 1024
+        SCSI Device Bus Location: Channel ID: 0 Target ID: 4 LUN: 0
+        Vendor: VMware,  Model: VMware Virtual S Rev: 1.0    CLAIMED: PSCSI
+        udev_path: /dev/disk/by-path/pci-0000:00:10.0-scsi-0:0:4:0
+
+Configuring iSCSI
+
+Creating Logical Units and TPGs
+
+Create the first mapping from the Linux LVM storage object
+iblock_0/my_linux_lvm2 to a new iSCSI TargetName +
+TargetPortalGroupTag Endpoint. iscsi-name generates the unique iSCSI
+target name.
+
+target:~# lio_node --addlun `iscsi-name` 1 0 my_lvm_iscsi_port iblock_0/my_linux_lvm2
+Successfully created iSCSI Target Logical Unit
+
+lio_node --listendpoints displays the active iSCSI/configFS symlink back to Target/configFS:
+
+target:~# lio_node --listendpoints
+\------> iqn.2003-01.org.linux-iscsi.target.i686:sn.5837873e417c
+        \-------> tpgt_1  TargetAlias: LIO Target
+         TPG Network Portals:
+         TPG Logical Units:
+                 \-------> lun_0/my_lvm_iscsi_port -> ../../../../../../target/core/iblock_0/my_linux_lvm2
+
+Creating Network Portals
+
+Add the IPv4 or IPv6 addresses + Ports of the iSCSI Network Portals
+accessible from the newly generated iSCSI TargetName +
+TargetPortalGroupTag Endpoint:
+
+target:~# lio_node --addnp iqn.2003-01.org.linux-iscsi.target.i686:sn.5837873e417c 1 172.16.201.128:3260
+Successfully created network portal: 172.16.201.128:3260 created iqn.2003-01.org.linux-iscsi.target.i686:sn.5837873e417c TPGT: 1
+
+And again, check lio_node --listendpoints to see the live iSCSI information:
+
+target:~# lio_node --listendpoints
+\------> iqn.2003-01.org.linux-iscsi.target.i686:sn.5837873e417c
+        \-------> tpgt_1  TargetAlias: LIO Target
+         TPG Network Portals:
+                 \-------> 172.16.201.128:3260
+         TPG Logical Units:
+                 \-------> lun_0/my_lvm_iscsi_port -> ../../../../../../target/core/iblock_0/my_linux_lvm2
+
+Modifying the TPG settings
+
+Enabling demo mode
+
+Demo Mode means disabling authentification for an iSCSI Endpoint, and
+granting read-only access to all iSCSI Initiators that attempt to
+connect to that iSCSI Endpoint
+(iqn.2003-01.org.linux-iscsi.target.i686:sn.5837873e417c + 1):
+
+target:~# lio_node --demomode iqn.2003-01.org.linux-iscsi.target.i686:sn.5837873e417c 1
+Successfully enabled DemoMode on iSCSI Target Portal Group: iqn.2003-01.org.linux-iscsi.target.i686:sn.5837873e417c 1
+
+Warning: Demo mode is dangerous.
+Demo mode exports "open" LUNs with no authentication
+requirements. This creates significant security and data integrity
+hazards. Do not do this for production setups, unless you are certain
+of what you are doing.
+
+Disabling CHAP authentication
+
+CHAP authentication can be disabled for an iSCSI TargetName+TargetPortalGroupTag Endpoint:
+
+target:~# lio_node --disableauth iqn.2003-01.org.linux-iscsi.target.i686:sn.5837873e417c 1
+Successfully disabled iSCSI Authentication on iSCSI Target Portal Group: iqn.2003-01.org.linux-iscsi.target.i686:sn.5837873e417c 1
+
+This is currently required to login in both demo mode and iSCSI ACL mode.
+
+Setting up ACLs
+
+An iSCSI Initiator ACL with an iSCSI TargetName+TargetPortalGroupTag
+can be set up as follows.
+
+This mode will grant read/write access to specifed iSCSI Initiators
+for specific iSCSI Logical Units on the iSCSI Target Endpoint. In this
+example, an iSCSI Initiator iqn.some-iSCSI-InitiatorName is added to
+the iSCSI TargetName+TargetPortalGroupTag
+(iqn.2003-01.org.linux-iscsi.target.i686:sn.5837873e417c + 1) from TPG
+LUN 0 to Mapped LUN 0 for the associated iSCSI Initiator:
+
+target:~# lio_node --addlunacl iqn.2003-01.org.linux-iscsi.target.i686:sn.5837873e417c 1 iqn.some-iSCSI-InitiatorName 0 0
+Successfully added iSCSI Initiator Mapped LUN: 0 ACL iqn.some-iSCSI-InitiatorName for iSCSI Target Portal Group:
+iqn.2003-01.org.linux-iscsi.target.i686:sn.5837873e417c 1
+
+Enabling the TPG
+
+Finally, the iSCSI TargetName+TargetPortalGroupTag can be enabled so
+that iSCSI Initiators can login to it:
+
+target:~# lio_node --enabletpg iqn.2003-01.org.linux-iscsi.target.i686:sn.5837873e417c 1
+Successfully enabled iSCSI Target Portal Group: iqn.2003-01.org.linux-iscsi.target.i686:sn.5837873e417c 1
-- 
1.7.10.4

