lio-utils HOWTO

The Linux SCSI Target Wiki

(Difference between revisions)
Jump to: navigation, search
m (Enabling demo mode)
m (Disabling CHAP)
Line 298: Line 298:
{{Message/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.}}
{{Message/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 ====
+
==== Disabling CHAP Authentication ====
CHAP authentication can be disabled for an iSCSI ''TargetName''+''TargetPortalGroupTag'' [[Endpoint]]:
CHAP authentication can be disabled for an iSCSI ''TargetName''+''TargetPortalGroupTag'' [[Endpoint]]:

Revision as of 00:57, 7 July 2012

lio-utils
Logo
Datera, Inc.
Simple Target Configurator
Original author(s) Nicholas Bellinger
Developer(s) Datera, Inc.
Initial release June 14, 2009 (2009-06-14)
Stable release 3.2 / April 27, 2010;
12 years ago
 (2010-04-27)
Development status Deprecated
Written in Python
Operating system Linux
Type Storage target configuration
License GNU General Public License
Website datera.io

The lio-utils HOWTO covers getting up and running with the lio-utils CLI for Target+iSCSI.

Template:Message/warning

Contents

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.

Building the Target

Build a Linux kernel with LIO from the sources (in lio-core-2.6.git). This requires knowledge of configuring and building a Linux kernel on your Linux installation (see Target for information):

git clone git://git.kernel.org/pub/scm/linux/kernel/git/nab/lio-core-2.6.git lio-core-2.6.git

Build and install the lio-utils CLI (from lio-utils.git):

git clone git://git.kernel.org/pub/scm/linux/storage/lio/lio-utils.git lio-utils.git

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_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

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.

Note that PSCSI currently 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 and RAMDISK_DR 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_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

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 [----------------------------]
\------> 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

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

Template:Message/warning

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

See also

External links

Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox
Google AdSense