This HOWTO will initially cover getting up and running with v3.0 configfs+python CLI interface and scripts for Target_Core_Mod/ConfigFS and LIO-Target/ConfigFS. Knowledge of building from linux kernel source is currently required for interested folks to get up and running. This will be changing in the future as demo VM images for popular virtualization hypervisors are released.
The users reference manual for the lio-utils.git 3.0 CLI is now available! LIO-3.0-Users_Reference_Manual.pdf
This manual contains information related to operation of the lio-utils userspace package on v3.0 kernel level Target_Core_Mod/ConfigFS core and LIO-Target/ConfigFS fabric including different Linux subsystem storage object backstore reference to iSCSI Target LUN Endpoints.
git clone git://git.kernel.org/pub/scm/linux/kernel/git/nab/lio-core-2.6.git lio-core-2.6.git
Please see LIO-Target for information
git clone git://git.kernel.org/pub/scm/linux/storage/lio/lio-utils.git lio-utils.git
Please see lio-utils for more information
lio-utils.git will install an init.d script in /etc/init.d/target. Calling /etc/init.d/target start will mount configfs and load target_core_mod.
Upon a successful start 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_dr registered PLUGIN_TRANSPORT[6] - rd_mcp registered PLUGIN_TRANSPORT[7] - fileio registered SE_PC[1] - Registered Plugin Class: OBJ PLUGIN_OBJ[1] - dev registered
Now, it is time to configure some target_core_mod storage objects. These storage objects represent devices from Linux/SCSI, Linux/BLOCK and Linux/VFS subsystems as well as TCM/RAMDISK_DR and TCM/RAMDISK_MCP storage objects via supported the different target_core_mod subsystem plugins.
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 a 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, here is the tcm_node --help entry:
--block=HBA/DEV <UDEV_PATH>, --iblock=HBA/DEV <UDEV_PATH>
Associate TCM/IBLOCK object with Linux/BLOCK device
Here is what it looks like in action with the Linux LVM block device:
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
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 op is called.
Note that TCM/pSCSI currently does NOT generate T10 WWN information automatically upon a successful --scsi or --scsibydev op as is default behaviour of the subsystem (--block, --fileio, and --ramdisk) OPs. pSCSI currently expects the T10 WWN, ALUA and PR information to be provided by the firmware of the underlying struct scsi_device and/or Linux/SCSI LLD, and currently does not provide SCSI-3 control path emulation for 'SCSI passthrough' into Linux/SCSI. Providing support of TCM/LIO SCSI-3 emulation on top of Linux/SCSI devices are future TODO items for TCM 3.x. Here is the entry from tcm_node --help:
--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
Here is what it looks like in action for tcm_node --scsi:
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 op only requires the 'DEV' alias parameter (and not HBA/DEV) and will automatically register the referenced struct scsi_host, here is what it looks like:
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
Using a struct file from Linux/VFS requires a filename and size (if it is a file on a mounted filesystem) or filename with size 0 if the struct file is referencing an underlying block device (eg: /dev/sde). Note that a T10 WWN Unit Serial will be generated upon a successfully call to --fileio, here is the entry from tcm_node --help:
--fileio=HBA/DEV <FILE> <SIZE_IN_BYTES>
Associate TCM/FILEIO object with Linux/VFS file or
underlying device for buffered FILEIO
Here is what it looks like in action:
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
Creating a TCM/RAMDISK_MCP and TCM/RAMDISK_DR storage object is done using tcm_node --ramdisk, this op 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, here is entry from tcm_node --help:
--ramdisk=HBA/DEV <PAGES>
Create and associate TCM/RAMDISK object
and what it looks like in action:
target:~# tcm_node --ramdisk rd_dr_0/some_rd 8192
ConfigFS HBA: rd_dr_0
Successfully added TCM/ConfigFS HBA: rd_dr_0
ConfigFS Device Alias: some_rd
Device Params ['8192']
Status: DEACTIVATED Execute/Left/Max Queue Depth: 0/32/32 SectorSize: 512 MaxSectors: 1024
LIO RamDisk ID: 0 RamDisk Makeup: rd_direct
PAGES/PAGE_SIZE: 8192*4096 SG_table_count: 3
Set T10 WWN Unit Serial for rd_dr_0/some_rd to: 54bae46a-ea5d-4090-bed0-d8a21f0060e3
Successfully created TCM/ConfigFS storage object: /sys/kernel/config/target/core/rd_dr_0/some_rd
Calling /etc/init.d/target status will call tcm_node --listhbas to show the current target_core_mod/ConfigFS storage objects. Here is what it looks like after successfully registering the Linux/BLOCK, Linux/pSCSI, Linux/VFS and TCM/RAMDISK objects with individual calls to tcm_node --block, --scsi, --scsibyudev, --fileio, and --ramdisk:
target:~# /etc/init.d/target status
[---------------------------] TCM/ConfigFS Status [----------------------------]
\------> rd_dr_0
HBA Index: 3 plugin: rd_dr 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_direct
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
Now, we will create the first mapping from the Linux/LVM storage object (iblock_0/my_linux_lvm2) to a new iSCSI TargetName + TargetPortalGroupTag endpoint: The 'iscsi-name' will generate 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
Now, call 'lio_node --listendpoints' to see the active ConfigFS symlink back to target_core_mod:
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
Now, add the IPv4 or IPV6 addresses + Ports of the iSCSI Network Portals accessable 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 active 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
This mode will allow read-only access for all iSCSI Initiators that attempt to connect to the specified (iqn.2003-01.org.linux-iscsi.target.i686:sn.5837873e417c + 1 in the example) iSCSI Target Endpoint:
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
This is currently required to login in both demo mode and iSCSI ACL mode listed below.
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 mode will allow for write-read access for specifed iSCSI Initiators to specific iSCSI Logical Units on the iSCSI Target Endpoint. In this example, a iSCSI Initiator iqn.some-iSCSI-InitiatorName is added to 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
Finally, enable the iSCSI TargetName+TargetPortalGroupTag so that iSCSI Initiators may login:
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