RTSadmin

From Linux-iSCSI

Jump to: navigation, search
RTSadmin
Logo
RisingTide Systems
Storage Manager
Original author(s) Jerome Martin
Developer(s) RisingTide Systems LLC
Initial release October 14, 2009 (2009-10-14)
Stable release 1.26 / March 2, 2011;
11 months ago (2011-03-02)
Preview release 1.99-BETA / May 5, 2011;
9 months ago (2011-05-05)
Development status Production
Written in Python
Operating system Linux
Type Storage management
License Proprietary
Website risingtidesystems.com
RTSadmin running with mixed-mode iSCSI, SCSI virtualziation, FCoE, Fibre Channel and IB/SRP.

RTSadmin is the single-node Target management tool by RisingTide Systems (RTS) (at risingtidesystems.com/git).

Contents

Architecture

RTSadmin comprises a shell that uses the RTS library (RTSlib) through a well-defined API. This means that the RTS shell 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.

Version 1

RTSadmin version 1 was initially released in October 2009, replacing lio-utils, and it only directly supported iSCSI. It has been widely available only under a commercial RTS license. The links for the RPM packages are:

RTSadmin version 1 has been replaced by RTSadmin version 2.

Version 2

RTSadmin version 2 was initially 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.

RTSadmin v2 is available under dual licensing:

Full ALUA configuration still requires lio-utils at the present time.

Concepts

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

General

The fundamental metaphor of RTSadmin 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 RTSadmin 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]]): 

+-rtsadmin
  |
  +-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.
      |
      +-Network 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.
      |
      +-Node 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.

You can either manually populate the Target core objects tree using the HBA and storage contexts of RTSadmin, or directly reference disks and files when creating LUNs in the TPG context. The latter method requires less commands, but despite RTSadmin 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:

Quick start

The following section illustrates a simple example how to export two hard drives to specific initiators.

An empty tree

First, let's take a look at the current object tree just after startup. The ls command used here is a shortcut to the list command: 

$ rtsadmin
Welcome to rtsadmin version 0.92.
A command-line interface to RisingTide Systems Target.

Copyright (c) 2009-2010 by RisingTide Systems LLC.

Type 'help' to list command objects
     'help <topic>' for help on that topic
     'help concepts' and 'help objects' for reference.
     'help quickstart' to get you started.

rtsadmin> ls

+-rtsadmin
 +-VirtualHBAs
 +-Targets

The object tree is currently empty, so only the parent nodes appear above.

Creating an iSCSI Target and TPG

Let's create a Target and a default TPG. Note that in RTSadmin you can use the [TAB] key for easy command and parameter completion: 

rtsadmin> create target
Generated iqn iqn.2003-01.org.linux-iscsi.jeos.i686:sn.7e001b58acce
Successfully created Target iqn.2003-01.org.linux-iscsi.jeos.i686:sn.7e001b58acce
Selected TPG Tag 1.
Successfully created TPG 1.
Set TPG authentication to False.
Using default port 3260
Automatically chose IP address 192.168.100.99, configure global parameter default_ip to override.
Successfully created network portal 192.168.100.99:3260.
Successfully enabled TPG.
...s.i686:sn.7e001b58acce/TPGT1>

The command above, create target without argument, created an iSCSI Target with a generated IQN. Also, thanks to the global parameters autoadd_tpg_on_create_target, autoadd_portal_on_create_tpg and auto_enable_tpg being set by default, a TPG has been automaticaly created, as well as a Network Portal, and the TPG was also enabled. Notice how the prompt only displays part of the full context name. This true is because the global parameter prompt_maxlen is set to 30 by default. You could unset it in order to view the full context name: 

...s.i686:sn.7e001b58acce> unset global prompt_maxlen
Global parameter 'prompt_maxlen' is now set to '0'
iqn.2003-01.org.linux-iscsi.jeos.i686:sn.7e001b58acce> set global prompt_maxlen 30
Global parameter 'prompt_maxlen' is now set to '30'
...s.i686:sn.7e001b58acce>

Creating iSCSI LUNs

Now, you have a Target, a TPG in that Target and a Network Portal attached to your TPG. Everything is set so that Initiators can connect to that Target using the default TPG Tag. Let's create a LUN pointing at two hard drives, /dev/sdb and /dev/sdc. In production, it is strongly recommended to reference the disks from /dev/disk/by-id/ instead, as those are persistent names accross changes to your SCSI installation: 

...s.i686:sn.7e001b58acce/TPGT1> create lun /dev/sdb
Selected LUN 0 for /dev/sdb.
Created storage object pscsi0/7178a8b03220.
Successfully created LUN 0 attached to storage object pscsi0/7178a8b03220 (/dev/sdb).
...6:sn.7e001b58acce/TPGT1/LUN0> cd ..
...s.i686:sn.7e001b58acce/TPGT1> create lun /dev/sdc
Selected LUN 1 for /dev/sdc.
Created storage object pscsi0/41759822c078.
Successfully created LUN 1 attached to storage object pscsi0/41759822c078 (/dev/sdc).
...6:sn.7e001b58acce/TPGT1/LUN1> cd ..
...s.i686:sn.7e001b58acce/TPGT1>

Note how the storage objects have been automatically created, and the LUN indexes automatically assigned. You could of course have been more specific and passed parameters to change the default values. An important thing to note here is navigating context. When you created the first LUN, upon creation, you were automatically placed into that LUN's context. Notice how the prompt changed to reflect that. Then, in order to create the second LUN, as we do not have any more business to do in that first LUN's context for our simple quickstart configuration, we navigated to the parent context of the LUN (the TPG with Tag 1) using cd .., from where we then created the second LUN. There are many ways to navigate between contexts, save bookmarks and restore them, reference the last created object of a certain type, etc. Please refer to the cd command and common usage of context (help cd and help context), or to the corresponding chapters of the RTSadmin Reference Guide.

Making the LUNs available to initiators

All that remains now, is to collect the IQNs of the Initiators you want to allow connecting to those LUNs and add the corresponding node ACLs to your TPG. By default, because the global parameters autoadd_mappedluns_on_create_acl and autoadd_mappedluns_on_create_lun are set, whenever you create a LUN, it will be mapped to all existing node ACLs, and whenever you create a new node ACL, mappings will be generated for the existing LUNs: 

...s.i686:sn.7e001b58acce/TPGT1> create nodeacl iqn.initiator1
Successfully created Node ACL for initiator iqn.initiator1
Auto added mapped lun 1 to iqn.initiator1.
Auto added mapped lun 0 to iqn.initiator1.
...b58acce/TPGT1/iqn.initiator1> cd ..
...s.i686:sn.7e001b58acce/TPGT1> create nodeacl iqn.initiator2
Successfully created Node ACL for initiator iqn.initiator2
Auto added mapped lun 1 to iqn.initiator2.
Auto added mapped lun 0 to iqn.initiator2.
...b58acce/TPGT1/iqn.initiator2> cd ..
...s.i686:sn.7e001b58acce/TPGT1>

And voila, you should now be able to connect from the two initiators and use the disks you just exported. Of course many other parameters you might want to ajust, sophisticated authentication schemes you can use, and different ways of configuring the storage objects attached to your disks. To learn more, pleae use the inline help system. For instance, if you do not like the default behavior that causes automatic entry into a newly-created object's context, you could unset the global parameter named enter_context_on_create. For more information, see help global_parameters or the corresponding chapter in the RTSadmin Reference Guide.

Looking at the resulting tree

You can look at the object tree you just created by returning to the rtsadmin root context using the cd / command, and listing the tree again (see also the underlying configFS layout): 

...s.i686:sn.7e001b58acce/TPGT1> cd /
Back to root context...
rtsadmin> ls

+-rtsadmin
 +-VirtualHBAs
 | +-VirtualHBA pscsi 0 (v3.1.2)
 |   +-StorageObject '41759822c078' (/dev/sdc) activated
 |   +-StorageObject '7178a8b03220' (/dev/sdb) activated
 +-Targets
   +-Target iqn.2003-01.org.linux-iscsi.jeos.i686:sn.7e001b58acce
     +-TPG 1 (enabled)
       +-LUNs
       | +-LUN 1 -> pscsi0 '41759822c078' (/dev/sdc)
       | | +-Node iqn.initiator2 MappedLUN1 (wp=False)
       | | +-Node iqn.initiator1 MappedLUN1 (wp=False)
       | +-LUN 0 -> pscsi0 '7178a8b03220' (/dev/sdb)
       |   +-Node iqn.initiator2 MappedLUN0 (wp=False)
       |   +-Node iqn.initiator1 MappedLUN0 (wp=False)
       +-Network Portals
       | +-NetworkPortal 192.168.100.99:3260
       +-Node ACLs
         +-NodeACL iqn.initiator2
         | +-Mapped0->LUN0 (wp=False)
         | +-Mapped1->LUN1 (wp=False)
         +-NodeACL iqn.initiator1
           +-Mapped0->LUN0 (wp=False)
           +-Mapped1->LUN1 (wp=False)

As you can see, you created a pretty impressive tree of storage objects with only a few commands, thanks to the default settings that automatically complete most of the work. Refer to help objects or the corresponding chapter in the rtsadmin reference guide to get more information about the object tree.

Saving the configuration

In order to make the current configuration available next time you reboot the server, use the saveconfig command. If you don't use this command, the configuration will be ephemeral and only last until you reboot the machine or unload the target service: 

rtsadmin> saveconfig

WARNING: Saving the current configuration to disk will overwrite your boot settings.
         The current target configuration will become the default boot config.

Are you sure you want to overwrite the default configuration? Type 'yes': yes
Making backup of Target/ConfigFS with timestamp: 2009-11-05_05:52:09.448701
Generated Target config: /etc/target/backup/backup-2009-11-05_05:52:09.448701.sh
Making backup of Target_Core_Mod/ConfigFS with timestamp: 2009-11-05_05:52:09.448701
Generated Target_Core_Mod config: /etc/target/backup/tcm_backup-2009-11-05_05:52:09.448701.sh
Successfully updated default config /etc/target/lio_start.sh
Successfully updated default config /etc/target/tcm_start.sh

See also

External links

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