lio-utils

lio-utils
	RisingTide Systems; Simple Target Configurator
Original author(s)	Nicholas Bellinger
Developer(s)	RisingTide Systems LLC
Initial release	June 14, 2009
Stable release	3.2 / April 27, 2010; ; 2 years ago
Development status	Deprecated
Written in	Python
Operating system	Linux
Type	Storage target configuration
License	GNU General Public License
Website	risingtidesystems.com

From Linux-iSCSI

Jump to: navigation, search

lio-utils (lio-utils.git) provide a simple low-level configuration tool set for LIO 3 (Target 3 and iSCSI 3).

lio-utils use the configFS kernel API that is available with LIO 3, which provides a clean interface for controlling the kernel level Target engine and its fabric module subsystems. lio-utils require LIO 3 or higher, and provide iSCSI target functionality on a number of Linux baremetal and virtualized systems. Running LIO 3 requires a newer Linux kernel (≥v2.6.29).

The lio-utils HOWTO gives a good idea of how lio-utils (tcm_node and lio_node) CLI operations look like. It is based on the lio-core-2.6.git tree for Linux kernel v2.6.30. 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.

lio-utils are now deprecated and have been superseded by targetcli.

Test and validation

Architectures

lio-utils have been tested with v2.6.31 x86 KVM, x86_64 KVM and PPC64.

Distributions

lio-utils have been tested on the following Linux distributions:

Debian: Tested OK
RHEL/Fedora: Tested OK
SuSE
- SLES11: 64-bit: Tested OK, 32-bit: TODO
- SLES10: x86_64 has problem with python setup.py install (see below)

Setup

Getting the source code

Frozen packages

The links for the frozen lio-utils RPM packages are:

You can also build lio-utils.git in-house as follows. Install rpmbuild and a libsnmp*-dev package, then:

make user_rpms

The 32-bit package should be built in /usr/src/packages/RPMS/.

Source code

For all Target 4 versions, a local git tree can be checked out with:

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

This will checkout the lio-utils.git/master branch, which is currently tracking the Target v4.0 and v4.1 code.

For older Target versions, the follwoing lio-utils versions are available:

lio-3.5: latest stable version for lio-core-backports.git v3.5.x
lio-3.1: older stable version for lio-core-backports.git v3.1.x

To switch to a different branch for the older lio-utils.git code, please use the following:

git fetch origin
git checkout --track -b lio-3.5 origin/lio-3.5

Installation

tcm_node.py and lio_node.py form the simple CLI for creating, modifying and viewing the running configuration of LIO 3 (Target+iSCSI) respectively. They can be installed with:

make install

This uses

python setup.py install

to install lio-utils.git/tcm-py and lio-utils.git/lio-py into /usr/lib/$PYTHON_VER/site-packages (also /usr/lib64).

Note that SLES 10 x86_64 seems to have problems with python setup.py install: it currently requires a manual copy of tcm_*.py and lio_*.py into /usr/lib64/$PYTHON_VER/site-packages to get up and running.

Configuration

Once tcm_node, tcm_dump, lio_node, and lio_dump are installed, the lio-utils HOWTO gives an overview over using them. Here are the basics.

Files

The configuration scripts are in:

Target/configFS: /etc/target/tcm_start.sh
iSCSI/configFS: /etc/target/lio_start.sh

Start

Starting the target:

/etc/init.d/target start

Stop

Stopping the target:

/etc/init.d/target stop

calls:

lio_node --unload
tcm_node --unload

to walk the ConfigFS trees and shutdown the running configure and unload the modules.

Status

Print the status:

/etc/init.d/target status

With the output from:

tcm_node --listhbas
lio_node --listendpoints

Dump

tcm_dump.py: print the running Target/configFS layout to STDOUT.
lio_dump.py: print the running iSCSI/configFS layout to STDOUT.

Documentation

Please see Target for instructions and checking out and building the Linux kernel source and LIO modules from lio-core-2.6.git and the lio-utils HOWTO for LIO 3 CLI userspace usage.

CLI operations

lio-utils is a simple userspace shell for LIO 3 (Target 3 and iSCSI 3 fabric module), see LIO User's Reference Manual. It also describes how to setup a number of different subsystem storage object backstores for LIO LUN endpoints:

Target CLI: basic Target 3 CLI operations using tcm_node.py from lio-utils.
iSCSI CLI: basic iSCSI 3 CLI operations using lio_node.py and lio_dump.py from lio-utils.
HOWTO: starting the Target.

Target

The shell command tcm_node controls the Target/configFS.

Here are the Python "optparsed" arguments for the different v3.x CLI operations, which can also be accessed directly at /sys/kernel/config/target/core. The complete functionality for full SPC-4 Persistent Reservations and ALUA support has been added to lio-utils.

usage: tcm_node [options]
options:
 -h, --help            show this help message and exit
 --addlungp=LU_GP_NAME
                       Add ALUA Logical Unit Group
 --addtgptgp=HBA/DEV <TG_PT_GP_NAME>, --addaluatpg=HBA/DEV <TG_PT_GP_NAME>
                       Add ALUA Target Port Group to Storage Object
 --addtgptgpwithmd=HBA/DEV <TG_PT_GP_NAME> <TG_PT_GP_ID>, --addaluatpgwithmd=HBA/DEV <TG_PT_GP_NAME> <TG_PT_GP_ID>
                       Add ALUA Target Port Group to Storage Object with ID
                       and process ALUA metadata
 --block=HBA/DEV <UDEV_PATH>, --iblock=HBA/DEV <UDEV_PATH>
                       Associate TCM/IBLOCK object with Linux/BLOCK device
 --clearaluapref=HBA/DEV <TG_PT_GP_NAME>
                       Clear ALUA Target Port Group Preferred Bit
 --delhba=HBA          Delete TCM Host Bus Adapter (HBA)
 --dellungp=LU_GP_NAME
                       Delete ALUA Logical Unit Group
 --deltgptgp=HBA/DEV TG_PT_GP_NAME, --delaluatpg=HBA/DEV TG_PT_GP_NAME
                       Delete ALUA Target Port Group from Storage Object
 --createdev=HBA/DEV <SUBSYSTEM_PARAMS>
                       Create TCM Storage Object using subsystem dependent
                       parameters, and generate new T10 Unit Serial for
                       IBLOCK,FILEIO,RAMDISK
 --establishdev=HBA/DEV <SUBSYSTEM_PARAMS>
                       Create TCM Storage Object using subsystem dependent
                       parameters, do not generate new T10 Unit Serial
 --fileio=HBA/DEV <FILE> <SIZE_IN_BYTES>
                       Associate TCM/FILEIO object with Linux/VFS file or
                       underlying device for buffered FILEIO
 --freedev=HBA/DEV     Free TCM Storage Object
 --listdevattr=HBA/DEV
                       List TCM storage object device attributes
 --listhbas            List TCM Host Bus Adapters (HBAs)
 --listlugps           List ALUA Logical Unit Groups
 --listtgptgp=HBA/DEV <TG_PT_GP_NAME>, --listaluatpg=HBA/DEV <TG_PT_GP_NAME>
                       List specific ALUA Target Port Group for Storage
                       Object
 --listtgptgps=HBA/DEV, --listaluatpgs=HBA/DEV
                       List all ALUA Target Port Groups for Storage Object
 --lvsnapattrset=HBA/DEV ATTR=VALUE
                       Set LV snapshot configfs attributes for TCM/IBLOCK
                       storage object
 --lvsnapattrshow=HBA/DEV
                       Show LV snapshot configfs attributes for TCM/IBLOCK
                       storage object
 --lvsnapinit=HBA/DEV MAX_SNAPSHOTS SNAP_SIZE_STR SNAP_INTERVAL_STR
                       Initialize snapshot with default attributes
 --lvsnapstart=HBA/DEV
                       Enable snapshot daemon for TCM/IBLOCK LVM storage
                       object
 --lvsnapstat=HBA/DEV  Display LV snapshot status for TCM/IBLOCK LVM storage
                       object
 --lvsnapstop=HBA/DEV  Disable snapshot daemon for TCM/IBLOCK LVM storage
                       object
 --pr=HBA/DEV          Show Persistent Reservation info
 --praptpl=HBA/DEV     Process PR APTPL metadata from file
 --prshowmd=HBA/DEV    Show APTPL metadata file
 --ramdisk=HBA/DEV <PAGES>
                       Create and associate TCM/RAMDISK object
 --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
 --setaluadelay=HBA/DEV <TG_PT_GP_NAME> <NON_OP_DELAY_IN_MSECS>
                       Set ALUA Target Port Group delay for
                       Active/NonOptimized in milliseconds
 --setaluapref=HBA/DEV <TG_PT_GP_NAME>
                       Set ALUA Target Port Group Preferred Bit
 --setaluastate=HBA/DEV <TG_PT_GP_NAME> <ALUA_ACCESS_STATE>
                       Set ALUA access state for TG_PT_GP_NAME on Storage
                       Object.  The value access states are "o" =
                       active/optimized, "a" = active/nonoptimized, "s" =
                       standby, "u" = unavailable
 --setaluatransdelay=HBA/DEV <TG_PT_GP_NAME> <TRANS_DELAY_IN_MSECS>
                       Set ALUA Target Port Group Transition delay
 --setaluatype=HBA/DEV <TG_PT_GP_NAME> <ALUA_ACCESS_TYPE>
                       Set ALUA access type for TG_PT_GP_NAME on Storage
                       Object.  The value type states are "both" =
                       implict/explict, "explict", "implict", or "none"
 --setdevattr=HBA/DEV <ATTRIB> <VALUE>
                       Set new value for TCM storage object device attribute
 --setlugp=HBA/DEV LU_GP_NAME
                       Set ALUA Logical Unit Group
 --setudevpath=HBA/DEV <UDEV_PATH>
                       Set UDEV Path Information, only used when --createdev
                       did not contain <udev_path> as parameter
 --setunitserial=HBA/DEV <UNIT_SERIAL>
                       Set T10 EVPD Unit Serial Information
 --setunitserialwithmd=HBA/DEV <UNIT_SERIAL>
                       Set T10 EVPD Unit Serial Information and process PR
                       APTPL metadata
 --udevpath=HBA/DEV    Show UDEV Path Information for TCM storage object
 --unload              Unload target_core_mod
 --version             Display target_core_mod version information
 --wwn=HBA/DEV         Show WWN info

iSCSI

The shell command lio_node controls iSCSI/configFS.

These are the Python "optparsed" arguements for the different LIO 3 CLI operations, which can also be accessed directly at /sys/kernel/config/target/iscsi.

usage: lio_node [options]
options:
 -h, --help            show this help message and exit
 --addlunacl=TARGET_IQN TPGT INITIATOR_IQN TPG_LUN MAPPED_LUN
                       Add iSCSI Initiator LUN ACL to LIO-Target Portal Group
                       LUN
 --addnodeacl=TARGET_IQN TPGT INITIATOR_IQN
                       Add iSCSI Initiator ACL to LIO-Target Portal Group
 --addnp=TARGET_IQN TPGT IP:PORT
                       Add LIO-Target IPv6 or IPv4 network portal
 --addlun=TARGET_IQN TPGT LUN PORT_ALIAS TCM_HBA/DEV 
                       Create LIO-Target Logical Unit
 --addtpg=TARGET_IQN TPGT
                       Create LIO-Target portal group
 --aluasecmd=TARGET_IQN TPGT LUN
                       Process ALUA secondary metadata for Port/LUN
 --cleartgptoff=TARGET_IQN TPGT LUN, --clearaluaoff=TARGET_IQN TPGT LUN
                       Clear ALUA Target Port Secondary State OFFLINE
 --dellunacl=TARGET_IQN TPGT INITIATOR_IQN MAPPED_LUN
                       Delete iSCSI Initiator LUN ACL from LIO-Target Portal
                       Group LUN
 --delnodeacl=TARGET_IQN TPGT INITIATOR_IQN
                       Delete iSCSI Initiator ACL from LIO-Target Portal
                       Group
 --delnp=TARGET_IQN TPGT IP:PORT
                       Delete LIO-Target IPv6 or IPv4 network portal
 --deliqn=TARGET_IQN   Delete LIO-Target IQN Endpoint
 --dellun=TARGET_IQN TPGT LUN
                       Delete LIO-Target Logical Unit
 --deltpg=TARGET_IQN TPGT
                       Delete LIO-Target Portal Group
 --demomode=TARGET_IQN TPGT, --permissive=TARGET_IQN TPGT
                       Disable all iSCSI Initiator ACL requirements (enable
                       DemoMode) for LIO-Target Portal Group (Disabled by
                       default)
 --disableauth=TARGET_IQN TPGT
                       Disable iSCSI Authentication for LIO-Target Portal
                       Group (Enabled by default)
 --disablelunwp=TARGET_IQN TPGT INITIATOR_IQN MAPPED_LUN
                       Clear Write Protect bit for iSCSI Initiator LUN ACL
 --disabletpg=TARGET_IQN TPGT
                       Disable LIO-Target Portal Group
 --enableaclmode=TARGET_IQN TPGT
                       Enable iSCSI Initiator ACL requirement mode for LIO-
                       Target Portal Group (Enabled by default)
 --enableauth=TARGET_IQN TPGT
                       Enable iSCSI Authentication for LIO-Target Portal
                       Group (Enabled by default)
 --enablelunwp=TARGET_IQN TPGT INITIATOR_IQN MAPPED_LUN
                       Set Write Protect bit for iSCSI Initiator LUN ACL
 --enabletpg=TARGET_IQN TPGT
                       Enable LIO-Target Portal Group
 --listendpoints       List iSCSI Target Endpoints
 --listlunacls=TARGET_IQN TPGT
                       List iSCSI Initiator LUN ACLs for LIO-Target Portal
                       Group
 --listnodeacls=TARGET_IQN TPGT
                       List iSCSI Initiator ACLs for LIO-Target Portal Group
 --listnodeattr=TARGET_IQN TPGT INITIATOR_IQN
                       List iSCSI Initiator ACL attributes for LIO-Target
                       Portal Group
 --listnodeparam=TARGET_IQN TPGT INITIATOR_IQN
                       List iSCSI Initiator ACL RFC-3720 parameters for LIO-
                       Target Portal Group
 --listnps=TARGET_IQN TPGT
                       List LIO-Target Portal Group Network Portals
 --listtargetnames     List iSCSI Target Names
 --listtpgattr=TARGET_IQN TPGT
                       List LIO-Target Portal Group attributes
 --listtpgparam=TARGET_IQN TPGT
                       List LIO-Target Portal Group RFC-3720 parameters
 --setchapauth=TARGET_IQN TPGT INITIATOR_IQN USER PASS
                       Set CHAP authentication information for iSCSI
                       Initiator Node ACL
 --setchapmutualauth=TARGET_IQN TPGT INITIATOR_IQN USER_IN PASS_IN
                       Set CHAP mutual authentication information for iSCSI
                       Initiator Node ACL
 --setchapdiscenforce=ENFORCE=1, NOENFORCEMENT=0
                       Set CHAP authentication enforcement for iSCSI
                       Discovery Sessions
 --setchapdiscauth=USER PASS
                       Set CHAP authentication information for iSCSI
                       Discovery Authentication
 --setchapdiscmutualauth=USER PASS
                       Set CHAP mutual authentication information for iSCSI
                       Discovery Authentication
 --setnodeattr=TARGET_IQN TPGT INITIATOR_IQN <ATTRIBUTE> <VALUE>
                       Set iSCSI Initiator ACL Attribute
 --setnodetcq=TARGET_IQN TPGT INITIATOR_IQN DEPTH
                       Set iSCSI Initiator ACL TCQ Depth for LIO-Target
                       Portal Group
 --settpgattr=TARGET_IQN TPGT <ATTRIB> <VALUE>
                       Set LIO-Target Port Group Attribute
 --settpgparam=TARGET_IQN TPGT <PARAMETER> <VALUE>
                       Set LIO-Target Port Group RFC-3720 parameter
 --settgptgp=TARGET_IQN TPGT LUN TG_PT_GP_NAME, --setaluatpg=TARGET_IQN TPGT LUN TG_PT_GP_NAME
                       Set ALUA Target Port Group for LIO-Target Port/LUN
 --settgptoff=TARGET_IQN TPGT LUN, --setaluaoff=TARGET_IQN TPGT LUN
                       Set ALUA Target Port Secondary State OFFLINE
 --showchapauth=TARGET_IQN TPGT INITIATOR_IQN
                       Show CHAP authentication information for iSCSI
                       Initiator Node ACL
 --showchapdiscauth    Show CHAP authentication information for iSCSI
                       Discovery portal
 --shownodetcq=TARGET_IQN TPGT INITIATOR_IQN
                       Show iSCSI Initiator ACL TCQ Depth for LIO-Target
                       Portal Group
 --showtgptgp=TARGET_IQN TPGT LUN
                       Show ALUA Target Port Group for LIO-Target Port/LUN
 --unload              Unload LIO-Target
 --version             Display LIO-Target version information

External links

LIO User's Reference Manual

lio-utils

From Linux-iSCSI

Contents

Test and validation

Architectures

Distributions

Setup

Getting the source code

Frozen packages

Source code

Installation

Configuration

Files

Start

Stop

Status

Dump

Documentation

CLI operations

Target

iSCSI

See also

External links

Personal tools

Namespaces

Variants

Views

Actions

Search

Navigation

Toolbox

Google AdSense


RisingTide Systems Simple Target Configurator
Original author(s)	Nicholas Bellinger
Developer(s)	RisingTide Systems LLC
Initial release	June 14, 2009 (2009-06-14)
Stable release	3.2 / April 27, 2010; 2 years ago (2010-04-27)
Development status	Deprecated
Written in	Python
Operating system	Linux
Type	Storage target configuration
License	GNU General Public License
Website	risingtidesystems.com