lio-utils

The Linux SCSI Target Wiki

Revision as of 03:03, 12 March 2011 by Admin (Talk | contribs)
Jump to: navigation, search
lio-utils
Logo
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;
10 years ago
 (2010-04-27)
Development status Production
Written in Python
Operating system Linux
Type Storage target configuration
License GNU General Public License
Website datera.io

lio-utils (lio-utils.git) provide a simple low-level configuration tool set for LIO, including Target and its backstores including tcm_loop, and the iSCSI, FCoE and Fibre Channel fabric modules.

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 and the LIO User's Reference Manual contain detailed operating instructions.

Contents

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:

Setup

Getting the source code

The lio-utils sources can be accessed via gitweb at lio-utils.git. 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

Note this will checkout the 'lio-utils.git/master' branch, which is currently tracking the v4.1 and v4.0 target code. Please use the 'master' branch with all v4.x kernel code.

The following older lio-utils versions are available:

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:

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

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

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

See also

External links

Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox
Google AdSense