targetcli

The Linux SCSI Target Wiki

Revision as of 07:56, 10 April 2012 by Admin (Talk | contribs)
Jump to: navigation, search
targetcli
Logo
LIO 150513.png
Storage Manager
Original author(s) Jerome Martin
Developer(s) Datera, Inc.
Initial release October 14, 2009 (2009-10-14)
Stable release 2.00 / March 1, 2012;
8 years ago (2012-03-01)
Development status Production
Written in Python
Operating system Linux
Type Storage management
License Proprietary
Website datera.io
targetcli running with mixed-mode iSCSI, SCSI virtualziation, FCoE, Fibre Channel and IB/SRP.

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:

Full ALUA configuration still requires lio-utils for now.

Download

targetcli consists of three Python modules:

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:

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:

Basic concepts

There are two complementary key concepts that are fundamental to understanding how to use targetcli:

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:

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

External links

Retrieved from "http://ns2.linux-iscsi.org/wiki/Targetcli"
Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox
Google AdSense