File 0008-Add-lio-utils-HOWTO.patch of Package lio-utils.216
From a4002b00852370ce535050f8fd8c6f9ea3cdd9c8 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.8.1.4
