targetcli (Source Origin)

targetcli is the community edition single-node Unified Target management shell by RisingTide Systems (RTS). RTSadmin is the commercial version of targetcli.

Overview

targetcli comprises a shell that uses the RTS library through a well-defined API. Thus targetcli can easily be replaced or complemented by a UI with other metaphors, such as a GUI, to provide the same functionality by different means.

targetcli was released on October 14, 2009 (2009-10-14), and supports all fabric modules, including iSCSI, Fibre Channel, FCoE, InfiniBand, IBM vSCSI and tcm_loop. 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). 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.

targetcli consists of three main Python modules:

• the underlying rtslib with the API [HTML] (RTSlib)
• the configshell that provides extensibility (configshell)
• the targetcli user shell itself (targetcli)

Linux distributions

targetcli and LIO Target are included in most Linux distributions per default. Here is an overview over the most popular distributions:

1. The distribution release in which the LIO Target kernel modules were included first.
2. Technical support, and qualified backports to other kernels and distributions are available from RTS.

targetcli also has a complementary open-source SCSI test suite (scsi-testuite).

Quick start guide

The quick start guide provides simple examples of basic target setups that export one block device residing in a file backstore (FILEIO).

targetcli can creates a comprehensive configuration of storage objects with only a few commands by using smart default settings that auto-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.

Startup

Invoke targetcli as root from the command prompt of the underlying OS shell:

# targetcli
Welcome to targetcli:
 Copyright (c) 2012 by RisingTide Systems LLC.
 All rights reserved.
Visit us at http://www.risingtidesystems.com.
Using ib_srpt fabric module.
Using qla2xxx fabric module.
Using iscsi fabric module.
Using loopback fabric module.
/>

Upon targetcli initialization, the underlying RTSlib loads the installed fabric modules, and creates the corresponding ConfigFS mount points (at /sys/kernel/config/target/<fabric>), as specified by the associated spec files (located in /var/target/fabric/fabric.spec).

Navigate the object tree

targetcli groups the target stack objects into an hierarchical tree of context objects, and allows navigating them correspondingly. Context objects are named by their full path.

cd navigates the object tree. Without parameters, cd presents the full objects tree. The destination path can also be selected via cursor keys.

pwd displays the complete current path (the prompt may display an abbreviated path).

Per default, auto_cd_after_create is set to true, which automatically enters an object context (or working directory) after its creation. The examples here are modeled after this behavior.

Optionally, set auto_cd_after_create=false to prevent targetcli from automatically entering new object contexts after their creation:

/> set global auto_cd_after_create=false
Parameter auto_cd_after_create is now 'false'.
/>

Display the object tree

Use ls to list the object hierarchy, which is initially empty:

/> 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]
/>

Display help

Use help to get context-sensitive help corresponding to the current or selected object context:

/> help
GENERALITIES
  This is an interactive shell in which you can create, delete and configure
  configuration objects.
  [...]
COMMAND SYNTAX
  Commands are built using the following syntax:
  [TARGET_PATH] COMMAND_NAME [OPTIONS]
  [...]
AVAILABLE COMMANDS
  The following commands are available in the current path:
    - bookmarks action [bookmark]
    - cd [path]
    - create [wwn]
    - delete wwn
    - exit
    - get [group] [parameter...]
    - help [topic]
    - info
    - ls [path] [depth]
    - pwd
    - refresh
    - set [group] [parameter=value...]
    - status
    - version
/> backstores/iblock help create
SYNTAX
  create name dev [generate_wwn]
DESCRIPTION
  Creates an IBlock Storage object. dev is the path to the TYPE_DISK block
  device to use and the optional generate_wwn parameter is a boolean specifying
  whether or not we should generate a T10 wwn Serial for the unit (by default,
  yes).
/> iscsi/ help create
SYNTAX
  create [wwn]
DESCRIPTION
  Creates a new target. The wwn format depends on the transport(s) supported by
  the fabric module. If the wwn is ommited, then a target will be created using
  either a randomly generated WWN of the proper type, or the first unused WWN in
  the list of possible WWNs if one is available. If WWNs are constrained to a
  list (i.e. for hardware targets addresses) and all WWNs are in use, the target
  creation will fail. Use the info command to get more information abour WWN
  type and possible values.
SEE ALSO
  info
/>

Create a backstore

Enter the top-level backstore object, and create one (storage object) using IBLOCK or FILEIO type devices.

For instance, create an IBLOCK backstore from a /dev/sdb block device. Note that this device can be any TYPE_DISK block-device, and it can also use /dev/disk/by-id/ symlinks:

/> cd backstores/
/backstores> iblock/ create name=my_disk dev=/dev/sdb
Generating a wwn serial.
Created iblock storage object my_disk using /dev/sdb.
Entering new node /backstores/iblock/my_disk.
/backstores/iblock/my_disk>

targetcli automatically creates a WWN serial ID for the backstore device and then changes the working context to it.

The resulting object hierarchy looks as follows (displayed from the root object):

/> ls
o- / ..................................................................... [...]
  o- backstores .......................................................... [...]
  | o- fileio ............................................... [0 Storage Object]
  | o- iblock ............................................... [1 Storage Object]
  | | o- my_disk .......................................... [/dev/sdb activated]
  | 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]
/>

Create an iSCSI target

Persist the configuration

The target configuration can be persisted across reboots by using saveconfig from the root context:

/> 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
/> exit
#

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).
• Enter an Fibre Channel Target, and from there directly an Endpoint.

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

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

Use <verb> on <object type> and <object specifiers>.

[<verb>] <object_type> [<object specifier>...]

Example: create target creates a Target for a 'transport' (iSCSI, FCoE, Fibre Channel, InfiniBand, 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

targetcli has the ability to chain commands, which provides powerful semantics for creating complex command sequences. Command chains are constructed by chaining multiple single commands together, separated by a comma:

command1, command2 [,command...]

When a command results in a context change (i.e. enter target iqn.1999-03.org.foobar:1234 enters that 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.

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, automatically enter into the context 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)

Object tree

The Target object hierarchy encompasses both the fabric modules (iSCSI, FCoE, Fibre Channel, InfiniBand, etc.) and the low-level objects used to map the underlying storage objects.

Fabric objects

Here is a summary of the iSCSI fabric objects hierarchy (see also the underlying configFS layout]]):

+-targetcli
  |
  +-Targets
    | Identified by their WWNs or IQN (for iSCSI).
    | Targets identify a group of Endpoints.
    |
    +-TPGs (Target Portal Groups, iSCSI only)
      | The TPG is identified by its numerical Tag, starting at 1. It
      | groups several Network Portals, and caps LUNs and Node ACLs.
      | For fabrics other than iSCSI, targetcli masks the TPG level.
      |
      +-Network Portals (iSCSI only)
      |   A Network Portal adds an IP address and a port. Without at
      |   least one Network Portal, the Target remains disabled.
      |
      +-LUNs
      |   LUNs point at the Storage Objects, and are numbered 0-255.
      |
      +-ACLs
        | Identified by initiator WWNs/IQNs, ACLs group permissions
        | for that specific initiator. If ACLs are enabled, one
        | NodeACL is required per authorized initiator.
        |
        + Mapped LUNs
            Determine which LUNs an initiator will see. E.g., if
            Mapped LUN 1 points at LUN 0, the initiator referenced
            by the NodeACL will see LUN 0 as LUN 1.

Storage objects

Here is a summary of the Target storage object 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:
    |   . iblock - emulates SCSI on top of any TYPE_DISK block device.
    |   . fileio - emulates SCSI on top of the local filessystem.
    |   . 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.
    |   . rd_dr  - ramdisk drive-based SCSI emulation, faster ramdisk,
    |              using direct memory mapping (use sagaciously).
    |
    + Storage Objects
        The actual Storage Objects that will be exported via iSCSI LUNS.
        . 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 object hierarchy can be populated either manually by using the HBA and storage contexts of targetcli, or directly reference disks and files when creating LUNs. 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:

• Creating a FILEIO object in asynchronous (write-back cached) mode
• Block-IO storage objects (IBLOCK)
• RAMDISKs
• Non-standard WWN