Lio-utils HOWTO

The Linux SCSI Target Wiki

(Difference between revisions)
Jump to: navigation, search
m (→{{anchor|Start}} Starting the Target)
m
Line 52: Line 52:
Now, it is time to configure the [[Target]] storage objects.  They represent SCSI devices, such as [[Target/PSCSI]], [[Target/IBLOCK]], [[Target/FILEIO]] or [[Target/RAMDISK]] via the different Target subsystem plugins.   
Now, it is time to configure the [[Target]] storage objects.  They represent SCSI devices, such as [[Target/PSCSI]], [[Target/IBLOCK]], [[Target/FILEIO]] or [[Target/RAMDISK]] via the different Target subsystem plugins.   
-
=== [[Target/IBLOCK]] (Linux/BLOCK) ===
+
=== [[IBLOCK]] (Linux BLOCK) ===
Using a <code>struct block_device</code> 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''.
Using a <code>struct block_device</code> 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''.
Line 78: Line 78:
</pre>
</pre>
   
   
-
=== [[Target/PSCSI]] (Linux/SCSI) ===
+
=== [[PSCSI]] (Linux [[SCSI]]) ===
Using a <code>struct scsi_device</code> 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.
Using a <code>struct scsi_device</code> 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.
Line 125: Line 125:
</pre>
</pre>
-
=== [[Target/FILEIO]] (Linux/VFS) ===
+
=== [[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''.
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''.
Line 151: Line 151:
</pre>
</pre>
-
=== [[Target/RAMDISK]] ===
+
=== [[RAMDISK]] ===
Creating a RAMDISK_MCP and RAMDISK_DR storage object is done using ''tcm_node --ramdisk''. This operation requires
Creating a RAMDISK_MCP and RAMDISK_DR storage object is done using ''tcm_node --ramdisk''. This operation requires

Revision as of 07:27, 4 December 2010

Template:AdSense right This lio-utils HOWTO covers getting up and running with the lio-utils CLI for Target+iSCSI.

Contents

Overview

This article needs a review and may need a cleanup or additional content. Please help improve this article to meet our quality standards. (12/3/2010)

This HOWTO covers getting up and running with the lio-utils CLI for Target+iSCSI. It requires either knowledge how to build Linux kernels from the kernel sources, or using a preconfigured LIO-VM Target in a virtual machine.

This manual contains information related to operation of the lio-utils userspace package on v3.0 kernel level Target engine and iSCSI fabric including different Linux subsystem storage object backstore reference to iSCSI Target LUN Endpoints, see also the LIO User's Reference Manual.

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

Setting up the Target

Now, it is time to configure the Target storage objects. They represent SCSI devices, such as Target/PSCSI, Target/IBLOCK, Target/FILEIO or Target/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 Target/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 backstoer subsystem operations (Target/IBLOCK, Target/FILEIO and Target/RAMDISK). pSCSI currently expects the T10 WWN, and ALUA and Persistent Reservations 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.

SCSI-3 emulation on top of Linux SCSI devices can be provided with 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

Setting up 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 TargetName+TargetPortalGroupTag endpoint. It grants read-only access to all iSCSI Initiators that attempt to connect to the specified 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

Disabling CHAP

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

Template:AdSense See also

External links

Retrieved from "http://ns2.linux-iscsi.org/wiki/Lio-utils_HOWTO"
Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox
Google AdSense