Lio-utils HOWTO

The Linux SCSI Target Wiki

(Difference between revisions)
Jump to: navigation, search
m (→FILEIO (Linux VFS))
m (Redirected page to Lio-utils)
 
(41 intermediate revisions not shown)
Line 1: Line 1:
-
{{AdSense right}}
+
#REDIRECT [[Lio-utils]]
-
This '''[[lio-utils]] HOWTO''' covers getting up and running with the [[lio-utils]] CLI for [[Target]]+[[iSCSI]].
+
-
== Overview ==
+
[[Category:Management]]
-
{{Review | date=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 [http://linux-iscsi.org/builds/docs/LIO-3.0-Users_Reference_Manual.pdf LIO User's Reference Manual].
+
-
 
+
-
== 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 [[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 backstore subsystem operations ([[IBLOCK]], [[FILEIO]] and [[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:
+
-
 
+
-
<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 struct <code>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 ''TargetName''+''TargetPortalGroupTag'' endpoint. It grants read-only access to all iSCSI [[Initiator]]s that attempt to connect to the specified 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]]
+
-
* [[RTSadmin]] and [[RTS Director]]
+
-
{{AdSense See also}}
+
-
 
+
-
== External links ==
+
-
* [http://linux-iscsi.org/builds/docs/LIO-3.0-Users_Reference_Manual.pdf LIO User's Reference Manual].
+

Latest revision as of 01:00, 19 October 2013

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