Lio-utils HOWTO

The Linux SCSI Target Wiki

(Difference between revisions)
Jump to: navigation, search
m
m (Redirected page to Lio-utils)
 
Line 1: Line 1:
-
{{DISPLAYTITLE:lio-utils HOWTO}}
+
#REDIRECT [[Lio-utils]]
-
{{Infobox software
+
-
| name                  = lio-utils
+
-
| logo                  = [[Image:Corp_Logo.png|180px|Logo]]
+
-
| screenshot            = Simple Target Configurator
+
-
| caption                =
+
-
| 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 the {{Target}} and [[iSCSI]].
+
-
 
+
-
== Overview ==
+
-
 
+
-
{{Ambox| type=warning| head=Use ''[[targetcli]]'' instead.| text=''lio-utils'' are deprecated and have been superseded by [[targetcli]], please see the {{OS Admin Manual}}.}}
+
-
 
+
-
== {{anchor|Starting|Start}} Starting {{T}} ==
+
-
 
+
-
[[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 {{T}} ==
+
-
 
+
-
Now, it is time to configure {{T}} 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.
+
-
 
+
-
{{Ambox| type=warning| head=Avoid PSCSI.| text=Do not use PSCSI unless you know exactly how it will be used. Advanced SCSI CDBs such as for [[Persistent Reservations]] or [[Asymmetric Logical Unit Assignment|ALUA]]s (used e.g. by [[VMware ESX]] and [[VMware vSphere|vSphere]]) are typically not implemented in the device firmware, and can cause malfunctions or crashes. Instead, use IBLOCK for typical production setups.}}
+
-
 
+
-
[[PSCSI]] 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''.
+
-
 
+
-
{{Ambox| type=warning| head=Avoid Direct Mapped RAMDISKs.| text=Do not use direct mapped RAM disks for production setups. They don't have multi-session capabilities, and can cause malfunctions are crashes. Instead, use Memory Copy RAMDISKs (''rd_mcp'') for production setups.}}
+
-
 
+
-
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 {{T}} status ==
+
-
 
+
-
The status of a live {{T}} 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>
+
-
 
+
-
{{Ambox| type=warning| head=Demo mode is dangerous.| text=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 authentication ====
+
-
 
+
-
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 ==
+
-
* [[targetcli]]
+
-
* [[{{OS}}]], {{Target}}
+
-
* Fabric modules: [[FCoE]], [[Fibre Channel]], [[iSCSI]], [[iSER]], [[SRP]], [[tcm_loop]] and [[vHost]]
+
-
* [[lio-utils]]
+
-
 
+
-
== External links ==
+
-
* {{OS Admin Manual}}
+
[[Category:Management]]
[[Category:Management]]

Latest revision as of 01:00, 19 October 2013

  1. REDIRECT Lio-utils
Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox
Google AdSense