targetcli
The Linux SCSI Target Wiki
![]() | |
---|---|
![]() Storage Manager | |
Original author(s) | Jerome Martin |
Developer(s) | Datera, Inc. |
Initial release | October 14, 2009 |
Stable release | 2.00 / March 1, 2012 |
Development status | Production |
Written in | Python |
Operating system | Linux |
Type | Storage management |
License | Proprietary |
Website | datera.io |
targetcli is the community edition single-node Target management tool by Datera, Inc. (RTS) (at risingtidesystems.com/git). RTSadmin is the commercial version of targetcli.
Contents |
Overview
targetcli comprises a shell that uses the RTS library (rtslib) through a well-defined API. Thus the targetcli can be easily replaced or complemented by a UI with other semantics or metaphors, such as a GUI, to provide the same functionality by different means.
targetcli was released in May 2011, and it supports all fabric modules, currently including iSCSI, Fibre Channel, FCoE, InfiniBand, IBM vSCSI and tcm_loop, see also Target. It is is based on a modular, extensible architecture, with plug-in modules for additional functionality.
targetcli is available under dual licensing:
- The targetcli Community Edition is released under the GNU Affero General Public License (AGPLv3), and the corresponding source code resides in a public in a public git repository at risingtidesystems.com/git. The Community Edition supports only the configuration of the Target. Everyone is welcome to contribute to the Community Edition.
- The rtsadmin Enterprise Edition is released under the commercial RTS license, and allows the management of complex full storage systems.
Full ALUA configuration still requires lio-utils for now.
Download
targetcli consists of three Python modules:
- the underlying rtslib with the API (HTML documentation)
- the configshell that provides extensibility
- the targetcli user shell itself
targetcli is available for the most popular Linux distributions as follows:
Distribution | Versions | Archive | Install | Source git | Documentation |
---|---|---|---|---|---|
CentOS | v6.2+ | CentOS mirror | su -c 'yum install fcoe-targetutils' | targetcli-fb.git | Tech Notes |
Debian | wheezy, sid | Debian pool | su -c 'apt-get install targetcli' | targetcli.git | - |
Fedora | 16, 17/18 | Fedora Rawhide | su -c 'yum install targetcli' | targetcli-fb.git | Target Wiki |
OpenSuse | Not yet available | ||||
RHEL | RHEL v6.2+ | Fedora Rawhide | su -c 'yum install fcoe-targetutils' | targetcli-fb.git | Tech Notes |
Scientific Linux | SL v6.2+ | SL Mirror | su -c 'yum install fcoe-targetutils' | targetcli-fb.git | Tech Notes |
SLES | SLES11 SP2 | TBD | |||
Ubuntu | PrecisePangolin v12 | Ubuntu universe | su -c 'apt-get install targetcli' | targetcli.git | - |
Quick start
The quick start guide provides a simple example of a basic iSCSI target setup that exports one block device residing in a file backstore (FILEIO).
targetcli creates a comprehensive configuration of storage objects with only a few commands by using smart default settings that automatically complete most of the work. targetcli also supports command and parameter completion via <TAB>, so all available commands and parameters can be listed from all contexts.
The RTS Admin Manual provides comprehensive background and numerous detailed examples, including programming the RTS library.
Empty tree
Start targetcli and use ls to list the initial object tree:
$ targetcli Welcome to the targetcli shell: Copyright (c) 2012 by RisingTide Systems LLC. All rights reserved. Visit us at http://www.risingtidesystems.com. Using loopback fabric module. Using iscsi fabric module. Using ib_srpt fabric module. Using qla2xxx fabric module. /> ls o- / ..................................................................... [...] o- backstores .......................................................... [...] | o- fileio ............................................... [0 Storage Object] | o- iblock ............................................... [0 Storage Object] | o- pscsi ................................................ [0 Storage Object] | o- rd_dr ................................................ [0 Storage Object] | o- rd_mcp ............................................... [0 Storage Object] o- ib_srpt ........................................................ [0 Target] o- iscsi .......................................................... [0 Target] o- loopback ....................................................... [0 Target] o- qla2xxx ........................................................ [0 Target] />
Note: The following examples assume auto_cd_after_create=false to better demonstrate how object paths (i.e. execution contexts) function, including the different context and command use scenarios. The default of auto_cd_after_create=true automatically changes to the new object context upon creation of the associated object.
/> set global auto_cd_after_create=false Parameter auto_cd_after_create is now 'false'. />
Create a FILEIO backstore
Create a 1MB file 'file1' to provide a physical backstore for the block device:
/> cd backstores/fileio /backstores/fileio> create file_backstore file1 1M Generating a wwn serial. Not using buffered mode. Created fileio file_backstore. /backstores/fileio>
List the resulting object tree:
/backstores/fileio> ls / o- / ..................................................................... [...] o- backstores .......................................................... [...] | o- fileio ............................................... [1 Storage Object] | | o- file_backstore .................................... [file1 deactivated] | o- iblock ............................................... [0 Storage Object] | o- pscsi ................................................ [0 Storage Object] | o- rd_dr ................................................ [0 Storage Object] | o- rd_mcp ............................................... [0 Storage Object] o- ib_srpt ........................................................ [0 Target] o- iscsi .......................................................... [0 Target] o- loopback ....................................................... [0 Target] o- qla2xxx ........................................................ [0 Target] /backstores/fileio>
Create an iSCSI Target
Create an iSCSI Target with a default TPG and the default TPG tag of '1':
/> cd /iscsi /iscsi> create Created target iqn.2003-01.org.linux-iscsi.rtsnode1.x8664:sn.83a8cde7aca8. Selected TPG Tag 1. Successfully created TPG 1. /iscsi>
Note: create target without arguments creates an iSCSI Target with an auto-generated IQN.
Create a LUN
Create an iSCSI LUN by binding the iSCSI target to the file backstore:
/iscsi> cd iqn.2003-01.org.linux-iscsi.rtsnode1.x8664:sn.83a8cde7aca8/tpgt1/luns /iscsi/iqn.20...a8/tpgt1/luns> create lun=0 storage_object=/backstores/fileio/file_backstore Successfully created LUN 0. /iscsi/iqn.20...a8/tpgt1/luns> cd .. /iscsi/iqn.20...196ff4e/tpgt1>
Disable authentication
Disable authentication on all LUNs on the TPG, and allow any initiator to connect:
/iscsi/iqn.20...de7aca8/tpgt1> set attribute authentication=0 Parameter authentication is now '0'. /iscsi/iqn.20...de7aca8/tpgt1> set attribute generate_node_acls=1 Parameter generate_node_acls is now '1'. /iscsi/iqn.20...de7aca8/tpgt1>
Warning: Exporting “open” LUNs with no authentication requirements create a significant security and data integrity hazards. Don’t do this for production setups, unless you know exactly what you are doing. We recommend this only under the following circumstances:
- Physical security has been established through a closed, controlled environment.
- The LUNs are used in conjunction with a clustered filesystem that guarantees coherence across multiple initiators, typically via distributed locking.
Create a Network Portal
Make the LUN accessible via iSCSI by binding it to an IP address:
/iscsi/iqn.20...de7aca8/tpgt1> cd portals /iscsi/iqn.20...tpgt1/portals> create ip_address=192.168.1.26 Using default IP port 3260 Successfully created network portal 192.168.1.26:3260. /iscsi/iqn.20...tpgt1/portals> cd / />
The LUN is now ready for logins from iSCSI initiators.
List the object tree
Verify the resulting target configuration and its object tree:
/> ls o- / ................................................................... [...] o- backstores .......................................................... [...] | o- fileio ............................................... [1 Storage Object] | | o- file_backstore ...................................... [file1 activated] | o- rd_dr ................................................ [0 Storage Object] | o- rd_mcp ............................................... [0 Storage Object] o- ib_srpt ........................................................ [0 Target] o- iscsi ......................................................... [2 Targets] | o- iqn.2003-01.org.linux-iscsi.rtsnode1.x8664:sn.83a8cde7aca8 ...... [1 TPG] | | o- tpgt1 ....................................................... [enabled] | | o- acls .......................................................... [0 ACL] | | o- luns .......................................................... [1 LUN] | | | o- lun0 ................................ [fileio/file_backstore (file1)] | | o- portals .................................................... [1 Portal] | | o- 192.168.1.26:3260 ................................................ [OK] o- loopback ....................................................... [0 Target] o- qla2xxx ........................................................ [0 Target] />
Save the configuration
saveconfig makes the current configuration persistent across reboots:
/> saveconfig WARNING: Saving rtsnode1 current configuration to disk will overwrite your boot settings. The current target configuration will become the default boot config. Are you sure? Type 'yes': yes Making backup of srpt/ConfigFS with timestamp: 2012-02-27_23:19:37.660264 Successfully updated default config /etc/target/srpt_start.sh Making backup of qla2xxx/ConfigFS with timestamp: 2012-02-27_23:19:37.660264 Successfully updated default config /etc/target/qla2xxx_start.sh Making backup of loopback/ConfigFS with timestamp: 2012-02-27_23:19:37.660264 Successfully updated default config /etc/target/loopback_start.sh Making backup of LIO-Target/ConfigFS with timestamp: 2012-02-27_23:19:37.660264 Successfully updated default config /etc/target/lio_backup-2012-02-27_23:19:37.660264.sh Making backup of Target_Core_Mod/ConfigFS with timestamp: 2012-02-27_23:19:37.660264 Successfully updated default config /etc/target/tcm_backup-2012-02-27_23:19:37.660264.sh Generated Target_Core_Mod config: /etc/target/backup/tcm_backup-2012-02-27_23:19:37.660264.sh Successfully updated default config /etc/target/lio_start.sh Successfully updated default config /etc/target/tcm_start.sh />
Warning: Without saveconfig, the target configuration will be lost upon rebooting or unloading the target service.
Global parameters
There are numerous global and context-sensitive parameters that modify the behavior of targetcli.
Here are two particularly important ones:
- auto_cd_after_create {TRUE|FALSE}: If TRUE, changes current path to the new object that was just created.
- auto_cd_after_create {TRUE|FALSE}: Automatically enter into the contect of new objects upon their creation.
- auto_enable_tpgt {TRUE|FAlSE}: If TRUE, automatically enables TPGTs upon creation.
- parameter prompt_maxlen: length of context (30 by default, unset to view full context)
Basic concepts
There are two complementary key concepts that are fundamental to understanding how to use targetcli:
- Context sensitivity: The available command-set and options depend on the current context (which is determined by the current working directory).
- TAB completion: The full context-sensitive list of commands and their options is available by pressing TAB.
General
The fundamental metaphor of targetcli are context objects, which represent the target stack objects. Context objects are unified in a single hierarchical object tree that reflects their logical structure and relations. Context objects are named by their full path in the hierarchical object tree, which allows addressing and navigating them.
'Entering' an object changes the current object context, corresponding to its current working path, which is depicted in the command prompt.
pwd alternatively displays the complete current path (e.g., if the prompt displays an abbreviated path for space efficiency).
cd navigates the object tree. Without parameters, cd presents the full objects tree. The destination path can be selected via cursor keys. help cd lists context-sensitive navigation tips.
Due to the hierarchical structure of a Target object tree, multiple context changes might be required to reach and enter a particular object (for instance, enter an iSCSI Target, from there a specific TPG and then a Network Portal attached to that TPG).
Working with contexts
create context <context_name>, or short #<context_name>, saves the current context under 'name', which simplifies traversal of the object tree. Saved contexts can be restored at any time and remain persistent across sessions.
enter context <context_name>, or short @<context_name>, restores the corresponding saved context 'name' and immediately enters it. Saved contexts allow both naming and bookmarking available transport objects.
Each context objects provides context-sensitive operations, i.e. different context objects (or paths) provide different command sets. For instnace, a path pointing at an iSCSI target provides different commands than a path pointing at a storage object.
Command completion
At any time in the shell, <TAB> triggers command auto-completion.
With a unique option, pressing <TAB> once auto-completes the current command being edited. With multiple options, hitting <TAB> twice produces a list of available command completions, if any, and a quick syntax help on the command currently being edited. This is useful when the exact next parameters available for the current command are not known.
Each command parameter can be passed either as a positional parameter, following the order of the command syntax, or as a key=value pair, in any order. Command auto-completion will reflect and present all available options.
help followed by any command name lists the full command syntax and description.
Command syntax
[<verb>] <object_type> [<object specifier>...]
Use <verb> on <object type> and <object specifiers>. Example: create target creates a Target for a 'transport' (iSCSI, FCoE, Fibre Channel, etc.) in the root context. If the verb is omitted, the default is to use the first available implicit action verb for the object, in that order: enter, list and get.
<command> [<argument>] [<argument>]
Apart from generic verbs, there are also global commands, like help or exit. They take optional arguments and do not work on transport context objects or info objects.
Command chains
command1, command2 [,command...]
A powerful feature of targetcli is the ability to chain commands. Command chains are constructed by chaining several commands together, separated by a comma. When a command results in a context change (i.e. enter target iqn.1999-03.org.foobar:1234 enters this target's context), the next command in the chain executes in that new context. In addition, create context and enter context can be used in command chains, enabling easy scripting of creation, deletion and query operations of objects embedded deeply in the Target object tree.
Object tree
The Target objects encompass both the fabric implementations (iSCSI, FCoE, Fibre Channel, InfiniBand, etc.) and the low-level objects used to map the underlying storage (Target core).
Fabric objects
Here is a summary of the iSCSI fabric objects hierarchy (see also the underlying configFS layout]]):
+-targetcli | +-Targets | Identified by their IQN, targets identify a group of TPGs. | +-TPGs (Target Portal Groups) | The TPG is identified by its numerical Tag, starting at 1. It | groups several Network Portals, and caps LUNs and Node ACLs. | +-Portals | A Network Portal adds an IP address and a port to a TPG. | Without at least one Network Portal, you will not be able | to enable the TPG. | +-LUNs | Numbered 0-255 in a TPG, they point at your Storage Objects. | +-ACLs | Identified by initiator IQNs, they group the permissions for | this specific initiator when accessing the TPG. If ACLs | are enabled, you need one NodeACL per authorized initiator. | + Mapped LUNs They determine which TPG LUNs an initiator will see. For instance, if Mapped LUN 1 points at TPG LUN 0, the initiator referenced by the NodeACL will see TPG LUN 0 as LUN 1.
Target core objects
Here is a summary of the Target core objects hierarchy:
+-Root | +-VirtualHBAs | These are the emulated Host Bus Adapters of the TCM layer. | They are identified by their HBA number and their backstore type: | . pscsi - pass-through SCSI for native performance SCSI device | export. | . iblock - emulates SCSI on top of any TYPE_DISK block device. | . rd_dr - ramdisk drive-based SCSI emulation, faster ramdisk, | using direct memory mapping. | . rd_mcp - ramdisk drive-based SCSI emulation, a bit slower | ramdisk, but more robust with multiple initiators, | with a separate memory mapping using memory copy. | . fileio - emulates SCSI on top of files in your system. | + Storage Objects The actual Storage Objects that will be exported via iSCSI LUNS. . pscsi objects need a name, and the path to the SCSI device. . iblock objects need a name, and the path to a disk device. . fileio objects need a name, the path to a file and a size. . rd_dr and rd_mcp objects only need a name and a size.
The Target core objects tree can either be populated manually by using the HBA and storage contexts of targetcli, or directly reference disks and files when creating LUNs in the TPG context. The latter method requires less commands, but despite targetcli trying its best to optimize the underlying storage objects, is not as flexible as manually creating them. Manual storage object creation is typically necessary for:
- RAMDISKs
- Block-IO storage objects (IBLOCK)
- Non-standard WWN
- Creating a FILEIO object in asynchronous (write-back cached) mode
Clone GIT repositories
The source code of the three tragetcli components is available for downloaded from their GIT repositories as follows.
git clone git://risingtidesystems.com/rtslib.git git clone git://risingtidesystems.com/configshell.git git clone git://risingtidesystems.com/targetcli.git
The targetcli components depend on a number of other Python packages. They can be installed as part of the build process descibed as follows.
Build for Debian
Configshell
sudo apt-get install python-urwid sudo apt-get install python-epydoc sudo apt-get install python-simpleparse cd configshell make deb sudo dpkg -i dist/python-configshell_1.1.5.gd866b24_all.deb cd ..
RTSlib
apt-get install python-ipaddr apt-get install python-netifaces apt-get install python-configobj cd rtslib make deb sudo dpkg -i dist/python-rtslib_2.1.9.g7076acf_all.deb cd ..
targetcli
apt-get install python-dev cd targetcli make deb sudo dpkg -i dist/python-rtslib_2.1.9.g7076acf_all.deb cd ..
Run
Run the targetcli community edition from the targetcli directory as 'root' as follows:
PYTHONPATH=. ./scripts/targetcli
Developing
In order to change the code, it needs to be checked out via git checkout and the modified files need to be checked in again.
E.g., on Debian, the respective the module can then be rebuilt via make deb as follows:
cd configshell/configshell git checkout -t -b configshell_branch origin/master <edit file.py> git commit <file.py> cd .. make deb
See also
- Contributing
- Support
- Fabric modules: iSCSI, Fibre Channel, FCoE, InfiniBand, IBM vSCSI, tcm_loop
- Configuration: QLogic/targetcli, FCoE/targetcli, SRP/targetcli, tcm_loop/targetcli
- Distributions: RTS OS
- Target
External links
- GNU Affero General Public License (AGPL)
- RTSadmin Administrator's Manual [PDF]
- RTSlib Library Reference Guide [HTML][PDF]