Lio-utils HOWTO

{{DISPLAYTITLE:lio-utils HOWTO}}
{{Infobox software
| name                   = lio-utils
| logo                   = [[Image:RisingTide_Logo_small.png|180px|Logo]]
| screenshot             = {{RTS full}}
| caption                = Simple Target Configurator
| collapsible            =
| author                 = {{Nicholas Bellinger}}
| developer              = {{RTS legal}}
| released               = {{RTS releases|lio-utils|initial_date}}
| discontinued           = {{RTS releases|lio-utils|eol_date}}
| latest release version = {{RTS releases|lio-utils|release_ver}}
| latest release date    = {{RTS releases|lio-utils|release_date}}
| latest preview version = {{RTS releases|lio-utils|preview_ver}}
| latest preview date    = {{RTS releases|lio-utils|preview_date}}
| status                 = {{RTS releases|lio-utils|status}}
| frequently updated     =
| programming language   = Python
| operating system       = Linux
| platform               =
| size                   =
| language               =
| genre                  = Storage target configuration
| license                = GNU General Public License
| website                = {{RTS website}}
}}
The '''[[lio-utils]] HOWTO''' covers getting up and running with the [[lio-utils]] CLI for [[Target]]+[[iSCSI]].

{{Message/warning|Use ''[[targetcli]]'' instead.|''lio-utils'' are deprecated and have been superseded by [[targetcli]].}}

== Documentation ==

The [http://linux-iscsi.org/builds/docs/LIO-3.0-Users_Reference_Manual.pdf 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 <code>lio-core-2.6.git</code>).  This requires knowledge of configuring and building a Linux kernel on your Linux installation (see [[Target]] for information):

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

Build and install the [[lio-utils]] CLI (from <code>lio-utils.git</code>):

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

== {{anchor|Starting|Start}} 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 <code>target_core_mod</code>. Upon successfully starting up the first time, you should see the following:

<pre>
target:~# /etc/init.d/target start
Loading target_core_mod/ConfigFS core:   [OK]
</pre>

And the following will appear in the kernel ring buffer (''dmesg'') and klogd output in <code>/var/log</code>:

<pre>
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
</pre>

== 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 <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''.

The ''tcm_node --help'' entry is:

<pre>
--block=HBA/DEV <UDEV_PATH>, --iblock=HBA/DEV <UDEV_PATH>
        Associate TCM/IBLOCK object with Linux/BLOCK device
</pre>

The live Linux LVM block device looks like:

<pre>
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
</pre>

=== [[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.

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 [[Asymmetric Logical Unit Assignment|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:

<pre>
--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
</pre>

The live Linux LVM block device looks like:

<pre>
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
</pre>

The other method is to associate a struct <code>scsi_device</code> 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 <code>struct scsi_host</code>:

<pre>
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
</pre>

=== [[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:

<pre>
--fileio=HBA/DEV <FILE> <SIZE_IN_BYTES>
        Associate TCM/FILEIO object with Linux/VFS file or
        underlying device for buffered FILEIO
</pre>

The live Linux LVM block device looks like:

<pre>
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
</pre>

=== [[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:

<pre>
--ramdisk=HBA/DEV <PAGES>
        Create and associate TCM/RAMDISK object
</pre>

and the live Linux LVM block device looks like:

<pre>
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
</pre>

== 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'':

<pre>
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
</pre>

== Configuring [[iSCSI]] ==

=== Creating Logical Units and [[TPG]]s ===

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.

<pre>
target:~# lio_node --addlun `iscsi-name` 1 0 my_lvm_iscsi_port iblock_0/my_linux_lvm2
Successfully created iSCSI Target Logical Unit
</pre>

''lio_node --listendpoints'' displays the active [[iSCSI/configFS]] symlink back to [[Target/configFS]]:

<pre>
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
</pre>

=== Creating [[Network Portal]]s ===

Add the IPv4 or IPv6 addresses + Ports of the iSCSI [[Network Portal]]s accessible from the newly generated iSCSI ''TargetName'' + ''TargetPortalGroupTag'' [[Endpoint]]:

<pre>
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
</pre>

And again, check ''lio_node --listendpoints'' to see the live iSCSI information:

<pre>
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
</pre>

=== Modifying the [[TPG]] settings ===

==== Enabling demo mode ====

[[Demo Mode]] means disabling authentification for an iSCSI [[Endpoint]], and granting read-only access to all iSCSI [[Initiator]]s that attempt to connect to that iSCSI Endpoint (iqn.2003-01.org.linux-iscsi.target.i686:sn.5837873e417c + 1):

<pre>
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
</pre>

==== Disabling CHAP ====

CHAP authentication can be disabled for an iSCSI ''TargetName''+''TargetPortalGroupTag'' [[Endpoint]]:

<pre>
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
</pre>

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:

<pre>
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
</pre>

=== Enabling the [[TPG]] ===

Finally, the iSCSI ''TargetName''+''TargetPortalGroupTag'' can be enabled so that iSCSI Initiators can login to it:

<pre>
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
</pre>

== See also ==
* [[lio-utils]]
* [[Target]] and [[Target/configFS]]
* [[iSCSI]] and [[iSCSI/configFS]]
* [[targetcli]]

== External links ==
* [http://linux-iscsi.org/builds/docs/LIO-3.0-Users_Reference_Manual.pdf LIO User's Reference Manual].

[[Category:Management]]