targetcli

The Linux SCSI Target Wiki

(Difference between revisions)
Jump to: navigation, search
m
m (Contact)
 
(235 intermediate revisions not shown)
Line 2: Line 2:
{{Infobox software
{{Infobox software
| name                  = targetcli
| name                  = targetcli
-
| logo                  = [[Image:RisingTide_Logo_small.png|180px|Logo]]
+
| logo                  = [[Image:Corp_Logo.png|180px|Logo]]
| screenshot            = {{RTS screenshot|targetcli}}
| screenshot            = {{RTS screenshot|targetcli}}
| caption                = Storage Manager
| caption                = Storage Manager
| collapsible            =
| collapsible            =
-
| author                = {{Jerome Martin}}
+
| author                = {{Jerome Martin}}<br/>{{Michael Kromer}}<br/>{{Nicholas Bellinger}}
| developer              = {{RTS legal}}
| developer              = {{RTS legal}}
| released              = {{RTS releases|RTSadmin|initial_date}}
| released              = {{RTS releases|RTSadmin|initial_date}}
Line 22: Line 22:
| language              =
| language              =
| genre                  = Storage management
| genre                  = Storage management
-
| license                = Proprietary
+
| license                = AGPLv3
| website                = {{RTS website}}
| website                = {{RTS website}}
}}
}}
Line 28: Line 28:
{{Image|Rtsadmin-v1.99-beta-04292011.png|targetcli running with mixed-mode iSCSI, SCSI virtualziation, FCoE, Fibre Channel and IB/SRP.}}
{{Image|Rtsadmin-v1.99-beta-04292011.png|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 {{RTS full}} (RTS) (at [http://www.risingtidesystems.com/git risingtidesystems.com/git]). RTSadmin is the commercial version of targetcli.
+
'''targetcli''' is the single-node {{Target}} management shell by {{RTS full}}.
== Overview ==
== 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]]'' is the general management platform for the {{Target}}. It comprises a shell that uses the {{T}} library through a well-defined API, and is available under the {{Apache 2}}. 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. Everyone is welcome to [[Contributing|contribute]].
-
targetcli was released in May 2011, and it supports all fabric modules, currently including [[iSCSI]], [[Fibre Channel]], [[Fibre Channel over Ethernet|FCoE]], [[InfiniBand]], [[IBM vSCSI]] and [[tcm_loop]], see also [[Target#Fabric modules|Target]]. It is is based on a modular, extensible architecture, with plug-in modules for additional functionality.  
+
''targetcli'' was released on {{RTS releases|RTSadmin|initial_date}}, and supports all fabric modules, including [[FCoE]], [[Fibre Channel]], [[IBM vSCSI]], [[iSCSI]], [[iSER]], [[SRP]], [[tcm_loop]], and [[vHost]]. It is is based on a modular, extensible architecture, with plug-in modules for additional functionality.  
-
targetcli is available under dual licensing:
+
''targetcli'' consists of three Python modules:
-
* The ''targetcli'' Community Edition is released under the [http://www.gnu.org/licenses/agpl.html GNU Affero General Public License] (AGPLv3), and the corresponding source code resides in a public git repository at [http://www.risingtidesystems.com/git risingtidesystems.com/git]. The Community Edition supports only the configuration of the [[Target]]. Everyone is welcome to [[Contributing|contribute]] to the Community Edition.
+
* the ''targetcli'' user shell itself ({{RTS releases|RTSadmin|module_cli}})
-
* The ''rtsadmin'' Enterprise Edition is released under the commercial RTS license, and allows the management of complex full storage systems.
+
* the underlying ''rtslib'' ({{RTS releases|RTSadmin|module_lib}}) and API {{Lib Ref Guide HTML}}{{Lib Ref Guide PDF}}
 +
* the ''configshell'' that provides extensibility ({{RTS releases|RTSadmin|module_cfg}})
-
Full [[Asymmetric Logical Unit Assignment|ALUA]] configuration still requires [[lio-utils]] for now.
+
{{Ambox| type=note| head=Asymmetric Logical Unit Assignment (ALUA)| text=Full [[Asymmetric Logical Unit Assignment]] ALUA configuration still requires [[lio-utils]] for the time being.}}
-
== Download ==
+
Download and build instructions for ''targetcli'' are on the [[Downloads#targetcli|download]] page.
-
''targetcli'' consists of three Python modules:
+
== Linux distributions ==
-
* the underlying ''rtslib'' with the API ([http://www.risingtidesystems.com/doc/rtslib-gpl/html HTML documentation])
+
''targetcli'' and {{T}} are included in most Linux distributions per default. Here is an overview over the most popular distributions:
-
* the ''configshell'' that provides extensibility
+
-
* the ''targetcli'' user shell itself
+
-
''targetcli'' is available for the most popular Linux distributions as follows:
+
{{Linux Inclusion}}
-
{| <table class="features" border="1" cellpadding="5" cellspacing="1">
+
''targetcli'' also has a complementary open-source SCSI test suite ({{RTS releases|RTSadmin|module_test}}).
-
|-
+
-
! Distribution
+
-
! Versions
+
-
! Archive
+
-
! Install
+
-
! Source git
+
-
! Documentation
+
-
|-
+
-
! align="left" | [http://www.centos.org/ CentOS]
+
-
| v6.2+
+
-
| [http://mirror.centos.org/centos/6.2/os/x86_64/Packages/ CentOS mirror]
+
-
| ''su -c 'yum install fcoe-target-utils' ''
+
-
| [https://github.com/agrover/targetcli-fb targetcli-fb.git]
+
-
! [http://docs.redhat.com/docs/en-US/Red_Hat_Enterprise_Linux/6/html/6.2_Technical_Notes/kernel_tp.html Tech Notes]
+
-
|-
+
-
! align="left" | [http://www.debian.org/ Debian]
+
-
| [http://packages.debian.org/wheezy/targetcli wheezy], [http://packages.debian.org/sid/targetcli sid]
+
-
| [http://ftp.debian.org/debian/pool/main/ Debian pool]
+
-
| ''su -c 'apt-get install targetcli' ''
+
-
| [http://www.risingtidesystems.com/git/?p=targetcli.git;a=summary targetcli.git]
+
-
| -
+
-
|-
+
-
! align="left" | [http://fedoraproject.org/ Fedora]
+
-
| [http://rpm.pbone.net/index.php3/stat/4/idpl/17799714/dir/fedora_16/com/targetcli-2.0rc1.fb6-1.fc16.noarch.rpm.html 16], [http://rpm.pbone.net/index.php3/stat/4/idpl/17772505/dir/fedora_1/com/targetcli-2.0rc1.fb6-1.fc17.noarch.rpm.html 17/18]
+
-
| [http://dl.fedoraproject.org/pub/fedora/linux/development/rawhide/x86_64/os/Packages/ Fedora Rawhide]
+
-
| ''su -c 'yum install targetcli' ''
+
-
| [https://github.com/agrover/targetcli-fb targetcli-fb.git]
+
-
! [https://fedoraproject.org/wiki/Features/KernelTarget Target Wiki]
+
-
|-
+
-
! align="left" | [http://www.opensuse.org/ OpenSuse]
+
-
! colspan="5" | Not yet available
+
-
|-
+
-
! align="left" | [http://www.redhat.com/products/enterprise-linux/ RHEL]
+
-
| RHEL v6.2+
+
-
| [http://dl.fedoraproject.org/pub/fedora/linux/development/rawhide/x86_64/os/Packages/ Fedora Rawhide]
+
-
| ''su -c 'yum install fcoe-target-utils' ''
+
-
| [https://github.com/agrover/targetcli-fb targetcli-fb.git]
+
-
! [http://docs.redhat.com/docs/en-US/Red_Hat_Enterprise_Linux/6/html/6.2_Technical_Notes/kernel_tp.html Tech Notes]
+
-
|-
+
-
! align="left" | [http://www.scientificlinux.org/ Scientific Linux]
+
-
| [http://www.scientificlinux.org/distributions/6x/62/ SL v6.2+]
+
-
| [http://mirror.mcs.anl.gov/pub/scientific-linux/6.2/x86_64/os/Packages/ SL Mirror]
+
-
| ''su -c 'yum install fcoe-target-utils' ''
+
-
| [https://github.com/agrover/targetcli-fb targetcli-fb.git]
+
-
! [http://docs.redhat.com/docs/en-US/Red_Hat_Enterprise_Linux/6/html/6.2_Technical_Notes/kernel_tp.html Tech Notes]
+
-
|-
+
-
! align="left" | [http://www.suse.com/products/server/ SLES]
+
-
| SLES11 SP2
+
-
! colspan="4" | TBD
+
-
|-
+
-
! align="left" | [http://www.ubuntu.com/ Ubuntu]
+
-
| [http://packages.ubuntu.com/source/precise/targetcli PrecisePangolin v12]
+
-
| [http://archive.ubuntu.com/ubuntu/pool/universe/ Ubuntu universe]
+
-
| ''su -c 'apt-get install targetcli' ''
+
-
| [http://www.risingtidesystems.com/git/?p=targetcli.git;a=summary targetcli.git]
+
-
| -
+
-
|-
+
-
|}
+
-
== Quick start ==
+
{{T}} is also natively supported in OpenStack ([https://wiki.openstack.org/wiki/Cinder/LIO-Grizzly setup], [https://review.openstack.org/#/c/18274/ code]) via rtslib, starting with the Grizzly release.
-
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]]).
+
Download and build instructions for ''targetcli'' are on the [[Downloads#targetcli|download]] page.
-
''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.
+
== Quick start guide ==
-
The [http://www.risingtidesystems.com/doc/RTS%20Admin%20Manual%20Community.pdf RTS Admin Manual] provides comprehensive background and numerous detailed examples, including programming the RTS library.
+
The quick start guide provides simple examples of basic target setups that export one block device residing in a file backstore ([[FILEIO]]).
-
=== Empty tree ===
+
''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.
-
Start ''targetcli'' and use ''ls'' to list the initial object tree:
+
{{Ambox| type=info| head=[[LIO]] Admin Manual| text=The {{LIO Admin Manual}} provides comprehensive background and many examples on using ''targetcli'' and on programming the target library.}}
 +
 
 +
=== Mounting configFS ===
 +
 
 +
{{T}} and targetcli uses [[configFS]] for its configuration. All storage objects can be accessed and exported, so the configFS module must be loaded and configFS must be mounted. Mount configFS at <code>/sys/kernel/config</code>:
<pre>
<pre>
-
$ targetcli
+
mount -t configfs configfs /sys/kernel/config
-
Welcome to the targetcli shell:
+
</pre>
-
  Copyright (c) 2012 by RisingTide Systems LLC.
+
This can also be added to <code>/etc/fstab</code> to automatically mount at boot:
 +
 
 +
<pre>
 +
configfs /sys/kernel/config configfs defaults 1 1
 +
</pre>
 +
 
 +
Note that /etc/init.d/target will automatically mount [[configFS]] if it's not already been mounted by /etc/fstab or manually by user.
 +
 
 +
=== Startup ===
 +
 
 +
Invoke ''targetcli'' as root from the command prompt of the underlying OS shell:
 +
 
 +
<pre>
 +
# targetcli
 +
Welcome to targetcli:
 +
 
 +
  Copyright (c) 2013 by Datera, Inc.
  All rights reserved.
  All rights reserved.
-
Visit us at http://www.risingtidesystems.com.
+
Visit us at http://www.daterainc.com.
-
Using loopback fabric module.
 
-
Using iscsi fabric module.
 
Using ib_srpt fabric module.
Using ib_srpt fabric module.
Using qla2xxx fabric module.
Using qla2xxx fabric module.
-
 
+
Using iscsi fabric module.
-
/> ls
+
Using loopback fabric module.
-
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]
+
/>
/>
</pre>
</pre>
-
'''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.
+
Upon ''targetcli'' initialization, the underlying RTSlib loads the installed fabric modules, as specified by the associated spec files (located in ''/var/target/fabric/fabric.spec'').
 +
 
 +
=== Display help ===
 +
 
 +
Use ''help'' to get context-sensitive help, depending on the current or selected object context:
<pre>
<pre>
-
/> set global auto_cd_after_create=false
+
/> help
-
Parameter auto_cd_after_create is now 'false'.
+
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
/>
/>
</pre>
</pre>
-
=== Create a FILEIO backstore ===
+
=== Navigate the object tree ===
-
Create a 1MB file 'file1' to provide a physical backstore for the block device:
+
''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).
 +
 
 +
The global parameter ''auto_cd_after_create'' controls if ''targetcli'' automatically enters new object contexts after the creation of the corresponding new object.
 +
 
 +
{{Ambox| type=info| head=''auto_cd_after_create'' = ''false''| text=The following examples assume that ''auto_cd_after_create'' is set to ''false''.}}
 +
 
 +
* Per default, ''auto_cd_after_create'' is ''true'', which automatically enters a new object context (or working directory) after the creation of its associated object.
 +
* Optionally, set ''auto_cd_after_create'' to ''false'' to prevent ''targetcli'' from automatically changing object contexts after the creation of a new object:
<pre>
<pre>
-
/> cd backstores/fileio
+
/> set global auto_cd_after_create=false
-
/backstores/fileio> create file_backstore file1 1M
+
Parameter auto_cd_after_create is now 'false'.
-
Generating a wwn serial.
+
/>
-
Not using buffered mode.
+
-
Created fileio file_backstore.
+
-
/backstores/fileio>
+
</pre>
</pre>
-
List the resulting object tree:
+
=== Display the object tree ===
 +
 
 +
Use ''ls'' to list the object hierarchy, which is initially empty:
<pre>
<pre>
-
/backstores/fileio> ls /
+
/> ls
o- / ..................................................................... [...]
o- / ..................................................................... [...]
   o- backstores .......................................................... [...]
   o- backstores .......................................................... [...]
-
   | o- fileio ............................................... [1 Storage Object]
+
   | o- fileio ............................................... [0 Storage Object]
-
  | | o- file_backstore .................................... [file1 deactivated]
+
   | o- iblock ............................................... [0 Storage Object]
   | o- iblock ............................................... [0 Storage Object]
   | o- pscsi ................................................ [0 Storage Object]
   | o- pscsi ................................................ [0 Storage Object]
Line 191: Line 205:
   o- loopback ....................................................... [0 Target]
   o- loopback ....................................................... [0 Target]
   o- qla2xxx ........................................................ [0 Target]
   o- qla2xxx ........................................................ [0 Target]
-
/backstores/fileio>
+
/>
</pre>
</pre>
-
=== Create an iSCSI Target ===
+
=== Create a backstore ===
-
Create an iSCSI Target with a default TPG and the default TPG tag of '1':
+
Enter the top-level backstore object, and create storage objects using IBLOCK, FILEIO or PSCSI type devices.
 +
 
 +
==== IBLOCK ====
 +
 
 +
Create an IBLOCK backstore, which can be any <code>TYPE_DISK</code> block-device, including LVM logical volumes and ''/dev/disk/by-id/'' symlinks.
 +
 
 +
{{Ambox| type=info| head=Recommended for performance| text=IBLOCK backstores usually provide the best performance.}}
 +
 
 +
For instance, use the ''/dev/sdb'' block device:
<pre>
<pre>
-
/> cd /iscsi
+
/> cd backstores/
-
/iscsi> create
+
/backstores> iblock/ create name=block_backend dev=/dev/sdb
-
Created target iqn.2003-01.org.linux-iscsi.rtsnode1.x8664:sn.83a8cde7aca8.
+
Generating a wwn serial.
-
Selected TPG Tag 1.
+
Created iblock storage object block_backend using /dev/sdb.
-
Successfully created TPG 1.
+
/backstores>
-
/iscsi>
+
</pre>
</pre>
-
'''Note:''' ''create target'' without arguments creates an iSCSI Target with an auto-generated [[IQN]].
+
Alternatively, any LVM logical volume can be used as a backstore, please refer to the {{LIO Admin Manual}} on how to create them properly.
-
=== Create a LUN ===
+
For instance, create an IBLOCK backstore on a logical volume (under ''/dev/<volume_group_name>/<logical_volume_name>''):
-
Create an iSCSI LUN by binding the iSCSI target to the file backstore:
+
<pre>
 +
/backstores> iblock/ create name=block_backend_lvm lvm dev=/dev/vg0/lv1
 +
Generating a wwn serial.
 +
Created iblock storage object block_backend_lvm using /dev/vg0/lv1.
 +
/backstores>
 +
</pre>
 +
 
 +
In both cases, ''targetcli'' automatically creates a WWN serial ID for the new backstore devices.
 +
 
 +
==== FILEIO ====
 +
 
 +
Create an FILEIO backstore with the underlying file ''/usr/src/fileio'' and size of 2&nbsp;GB:
<pre>
<pre>
-
/iscsi> cd iqn.2003-01.org.linux-iscsi.rtsnode1.x8664:sn.83a8cde7aca8/tpgt1/luns
+
/> cd backstores/
-
/iscsi/iqn.20...a8/tpgt1/luns> create lun=0 storage_object=/backstores/fileio/file_backstore
+
/backstores> fileio/ create name=file_backend file_or_dev=/usr/src/fileio size=2G
-
Successfully created LUN 0.
+
Generating a wwn serial.
-
/iscsi/iqn.20...a8/tpgt1/luns> cd ..
+
Not using buffered mode.
-
/iscsi/iqn.20...196ff4e/tpgt1>  
+
Created fileio file_backend.
 +
/backstores>
</pre>
</pre>
-
=== Disable authentication ===
+
''targetcli'' automatically creates a WWN serial ID for the backstore device.
-
Disable authentication on all LUNs on the TPG, and allow any initiator to connect:
+
By default, [[FILEIO]] uses non-buffered mode (i.e. <code>O_SYNC</code> is set).
 +
 
 +
{{Ambox| type=warning| head=Do not use buffered FILEIO| text=Creating a FILEIO backend with ''buffered=True'' enables the buffer cache. While this can provide a significant performance increase, it also creates a serious data integrity hazard: If the system crashes for any reason, an unflushed buffer cache can cause the entire backstore to be irrecoverably corrupted.}}
 +
 
 +
==== PSCSI ====
 +
 
 +
Create a PSCSI (SCSI pass-through) backstore for a physical SCSI device, in this case a <code>TYPE_ROM</code> device using ''/dev/sr0'':
<pre>
<pre>
-
/iscsi/iqn.20...de7aca8/tpgt1> set attribute authentication=0
+
/backstores> pscsi/ create name=pscsi_backend dev=/dev/sr0
-
Parameter authentication is now '0'.
+
Generating a wwn serial.
-
/iscsi/iqn.20...de7aca8/tpgt1> set attribute generate_node_acls=1
+
Created pscsi storage object pscsi_backend using /dev/sr0.
-
Parameter generate_node_acls is now '1'.
+
/backstores>
-
/iscsi/iqn.20...de7aca8/tpgt1>
+
</pre>
</pre>
-
'''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:
+
''targetcli'' automatically creates a WWN serial ID for the backstore device.
-
* Physical security has been established through a closed, controlled environment.
+
{{Ambox| type=warning| head=Do not use PSCSI| text=Do not use PSCSI unless you know exactly how it will be used. Advanced SCSI CDBs such as for [[Persistent Reservations]] or [[Asymmetric Logical Unit Assignment|ALUA]]s (used e.g. by [[VMware ESX]] and [[VMware vSphere|vSphere]]) are typically not implemented in the device firmware, and can cause malfunctions or crashes. Use IBLOCK for production setups instead.}}
-
* The LUNs are used in conjunction with a clustered filesystem that guarantees coherence across multiple initiators, typically via distributed locking.
+
-
=== Create a Network Portal ===
+
==== Ramdisk ====
-
Make the LUN accessible via iSCSI by binding it to an IP address:
+
Create a RAM disk backstore with a size of 1&nbsp;GB:
<pre>
<pre>
-
/iscsi/iqn.20...de7aca8/tpgt1> cd portals
+
/backstores> rd_mcp/ create name=rd_backend size=1GB
-
/iscsi/iqn.20...tpgt1/portals> create ip_address=192.168.1.26
+
Generating a wwn serial.
-
Using default IP port 3260
+
Created rd_mcp ramdisk rd_backend with size 1GB.
-
Successfully created network portal 192.168.1.26:3260.
+
/backstores>
-
/iscsi/iqn.20...tpgt1/portals> cd /
+
-
/>
+
</pre>
</pre>
-
The LUN is now ready for logins from iSCSI initiators.
+
''targetcli'' automatically creates a WWN serial ID for the backstore device.
-
=== List the object tree ===
+
=== Display the resulting object tree ===
-
Verify the resulting target configuration and its object tree:
+
Use ''ls'' to list the resulting object hierarchy (displayed from the root object):
<pre>
<pre>
/> ls
/> ls
-
o- / ................................................................... [...]
+
o- / ..................................................................... [...]
-
o- backstores .......................................................... [...]
+
  o- backstores .......................................................... [...]
-
| o- fileio ............................................... [1 Storage Object]
+
  | o- fileio ............................................... [1 Storage Object]
-
| | o- file_backstore ...................................... [file1 activated]
+
  |   o- file_backend ............................ [/usr/src/fileio deactivated]
-
| o- rd_dr ................................................ [0 Storage Object]
+
  | o- iblock .............................................. [2 Storage Objects]
-
| o- rd_mcp ............................................... [0 Storage Object]
+
  | | o- block_backend .................................. [/dev/sdb deactivated]
-
o- ib_srpt ........................................................ [0 Target]
+
  | | o- block_backend_lvm .......................... [/dev/vg0/lv1 deactivated]
-
o- iscsi ......................................................... [2 Targets]
+
  | o- pscsi ................................................ [1 Storage Object]
-
| o- iqn.2003-01.org.linux-iscsi.rtsnode1.x8664:sn.83a8cde7aca8 ...... [1 TPG]
+
  |   o- pscsi_backend .................................. [/dev/sr0 deactivated]
-
| | o- tpgt1 ....................................................... [enabled]
+
  | o- rd_dr ................................................ [0 Storage Object]
-
| | o- acls .......................................................... [0 ACL]
+
  | o- rd_mcp ............................................... [1 Storage Object]
-
| | o- luns .......................................................... [1 LUN]
+
  |   o- rd_backend ...................................... [ramdisk deactivated]
-
| | | o- lun0 ................................ [fileio/file_backstore (file1)]
+
  o- ib_srpt ........................................................ [0 Target]
-
| | o- portals .................................................... [1 Portal]
+
  o- iscsi .......................................................... [0 Target]
-
| | o- 192.168.1.26:3260 ................................................ [OK]
+
  o- loopback ....................................................... [0 Target]
-
o- loopback ....................................................... [0 Target]
+
  o- qla2xxx ........................................................ [0 Target]
-
o- qla2xxx ........................................................ [0 Target]
+
/>
/>
</pre>
</pre>
-
=== Save the configuration ===
+
=== Create a target ===
-
''saveconfig'' makes the current configuration persistent across reboots:
+
{{Target}}s can now be instantiated as described for the fabrics, respectively:
 +
 
 +
* [[Fibre Channel]] on QLogic
 +
* [[Fibre Channel over Ethernet]] (FCoE)
 +
* IEEE 1394 / FireWire
 +
* [[iSCSI]]
 +
* [[iSER]] ([[InfiniBand]]) on Mellanox
 +
* [[SRP]] (InfiniBand) on Mellanox
 +
* [[tcm_loop]] (local loopback)
 +
* USB Gadget
 +
* [[vHost]] (QEMU virtio with virtio-scsi paravirtualized guests)
 +
 
 +
=== Persist the configuration ===
 +
 
 +
{{Ambox| type=warning| head=Don't forget to use ''saveconfig''!| text=Without ''saveconfig'', the target configuration will be lost upon rebooting or unloading the target service, as the target configuration will roll back to the last saved configuration.}}
 +
 
 +
The target configuration can be persisted across reboots by using ''saveconfig'' from the root context:
<pre>
<pre>
Line 301: Line 351:
Successfully updated default config /etc/target/lio_start.sh
Successfully updated default config /etc/target/lio_start.sh
Successfully updated default config /etc/target/tcm_start.sh
Successfully updated default config /etc/target/tcm_start.sh
-
/>
+
/> exit
 +
#
</pre>
</pre>
-
 
-
'''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 ==
== Basic concepts ==
Line 331: Line 370:
''pwd'' alternatively displays the complete current path (e.g., if the prompt displays an abbreviated path for space efficiency).
''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.
+
''cd'' navigates the object tree. Without parameters, ''cd'' presents the full objects tree. The destination path can be selected via cursor keys.
-
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]]).
+
''help cd'' lists context-sensitive navigation tips.
 +
 
 +
Due to the hierarchical structure of an {{T}} 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 ===
=== Working with contexts ===
Line 345: Line 389:
=== Command completion ===
=== Command completion ===
-
At any time in the shell, <TAB> triggers command auto-completion.
+
{{Ambox| type=info| head=TAB completion| text=At any time in the shell, <TAB> triggers command auto-completion. You can use it to display all available commands and options, depending on the current context.}}
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.
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.
Line 354: Line 398:
=== Command syntax ===
=== Command syntax ===
 +
 +
Use ''<verb>'' on ''<object type>'' and ''<object specifiers>''.
<pre>
<pre>
Line 359: Line 405:
</pre>
</pre>
-
Use ''<verb>'' on ''<object type>'' and ''<object specifiers>''. Example: ''create target'' creates a Target for a 'transport' ([[iSCSI]], [[Fibre Channel over Ethernet|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''.
+
Example: ''create target'' creates a target for a 'transport' ([[FCoE]], [[Fibre Channel]], [[iSCSI]], [[iSER]], [[SRP]], 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''.
<pre>
<pre>
Line 368: Line 414:
=== Command chains ===
=== 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:
<pre>
<pre>
Line 373: Line 421:
</pre>
</pre>
-
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.
+
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 {{T}} 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 ==
== Object tree ==
-
The Target objects encompass both the fabric implementations ([[iSCSI]], [[Fibre Channel over Ethernet|FCoE]], [[Fibre Channel]], [[InfiniBand]], etc.) and the low-level objects used to map the underlying storage ([[Target]] core).
+
The {{T}} object hierarchy encompasses both the fabric modules ([[FCoE]], [[Fibre Channel]], [[iSCSI]], [[iSER]], [[SRP]], etc.) and the low-level objects used to map the underlying storage objects.
=== Fabric objects ===
=== Fabric objects ===
-
Here is a summary of the iSCSI fabric objects hierarchy (see also the underlying [[configFS#Layout|configFS]] layout]]):
+
Here is a summary of the [[iSCSI]] fabric objects hierarchy (see also the underlying [[configFS#Layout|configFS]] layout):
<pre>
<pre>
Line 387: Line 444:
   |
   |
   +-Targets
   +-Targets
-
     | Identified by their IQN, targets identify a group of TPGs.
+
     | Identified by their WWNs or IQN (for iSCSI).
 +
    | Targets identify a group of Endpoints.
     |
     |
-
     +-TPGs (Target Portal Groups)
+
     +-TPGs (Target Portal Groups, iSCSI only)
       | The TPG is identified by its numerical Tag, starting at 1. It
       | The TPG is identified by its numerical Tag, starting at 1. It
       | groups several Network Portals, and caps LUNs and Node ACLs.
       | groups several Network Portals, and caps LUNs and Node ACLs.
 +
      | For fabrics other than iSCSI, targetcli masks the TPG level.
       |
       |
-
       +-Portals
+
       +-Network Portals (iSCSI only)
-
       |  A Network Portal adds an IP address and a port to a TPG.
+
       |  A Network Portal adds an IP address and a port. Without at
-
       |  Without at least one Network Portal, you will not be able
+
       |  least one Network Portal, the Target remains disabled.
-
      |  to enable the TPG.
+
       |
       |
       +-LUNs
       +-LUNs
-
       |  Numbered 0-255 in a TPG, they point at your Storage Objects.
+
       |  LUNs point at the Storage Objects, and are numbered 0-255.
       |
       |
       +-ACLs
       +-ACLs
-
         | Identified by initiator IQNs, they group the permissions for
+
         | Identified by initiator WWNs/IQNs, ACLs group permissions
-
         | this specific initiator when accessing the TPG. If ACLs
+
         | for that specific initiator. If ACLs are enabled, one
-
        | are enabled, you need one NodeACL per authorized initiator.
+
        | NodeACL is required per authorized initiator.
         |
         |
         + Mapped LUNs
         + Mapped LUNs
-
             They determine which TPG LUNs an initiator will see. For
+
             Determine which LUNs an initiator will see. E.g., if
-
            instance, if Mapped LUN 1 points at TPG LUN 0, the initiator
+
            Mapped LUN 1 points at LUN 0, the initiator referenced
-
             referenced by the NodeACL will see TPG LUN 0 as LUN 1.
+
             by the NodeACL will see LUN 0 as LUN 1.
</pre>
</pre>
-
=== Target core objects ===
+
=== Storage objects ===
-
Here is a summary of the [[Target]] core objects hierarchy:
+
Here is a summary of the {{T}} storage object hierarchy:
<pre>
<pre>
Line 422: Line 480:
     | These are the emulated Host Bus Adapters of the TCM layer.
     | These are the emulated Host Bus Adapters of the TCM layer.
     | They are identified by their HBA number and their backstore type:
     | 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.
     |  . iblock - emulates SCSI on top of any TYPE_DISK block device.
-
     |  . rd_dr  - ramdisk drive-based SCSI emulation, faster ramdisk,
+
     |  . fileio - emulates SCSI on top of the local filessystem.
-
    |              using direct memory mapping.
+
     |  . rd_mcp - ramdisk drive-based SCSI emulation, a bit slower
     |  . rd_mcp - ramdisk drive-based SCSI emulation, a bit slower
     |              ramdisk, but more robust with multiple initiators,
     |              ramdisk, but more robust with multiple initiators,
     |              with a separate memory mapping using memory copy.
     |              with a separate memory mapping using memory copy.
-
     |  . fileio - emulates SCSI on top of files in your system.
+
     |  . rd_dr  - ramdisk drive-based SCSI emulation, faster ramdisk,
 +
    |              using direct memory mapping (use sagaciously).
     |
     |
     + Storage Objects
     + Storage Objects
         The actual Storage Objects that will be exported via iSCSI LUNS.
         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.
         . 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.
         . fileio objects need a name, the path to a file and a size.
Line 440: Line 495:
</pre>
</pre>
-
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:
+
The {{T}} object hierarchy can be populated either manually by using the HBA and storage contexts of ''targetcli'', or by directly referencing disks or files when creating LUNs. The latter requires less commands, but is not as flexible as manually creating the underlying storage objects.
-
* [[RAMDISK]]s
+
Manual storage object creation should, however, only be necessary for:
-
* Block-IO storage objects ([[IBLOCK]])
+
-
* Non-standard [[WWN]]
+
-
* Creating a [[FILEIO]] object in asynchronous (write-back cached) mode
+
-
=== Clone GIT repositories ===
+
* Creating [[FILEIO]] objects in asynchronous (write-back cached) mode
 +
* Using non-standard [[WWN]]s
-
The source code of the three ''tragetcli'' components is available for downloaded from their GIT repositories as follows.
+
== Contact ==
-
<pre>
+
Please direct all technical discussion on ''targetcli'' to the [http://www.spinics.net/lists/target-devel/ target-devel] mailing list ([mailto:target-devel@vger.kernel.org post], [mailto:majordomo@vger.kernel.org&body=subscribe%20target-devel subscribe], [http://vger.kernel.org/vger-lists.html#target-devel list info], [http://dir.gmane.org/gmane.linux.scsi.target.devel gmane archive]). For more information, please see [[Support]].
-
git clone git://risingtidesystems.com/rtslib.git
+
-
git clone git://risingtidesystems.com/configshell.git
+
-
git clone git://risingtidesystems.com/targetcli.git
+
-
</pre>
+
-
 
+
-
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'' ====
+
-
 
+
-
<pre>
+
-
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 ..
+
-
</pre>
+
-
 
+
-
==== ''RTSlib'' ====
+
-
 
+
-
<pre>
+
-
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 ..
+
-
</pre>
+
-
 
+
-
==== ''targetcli'' ====
+
-
 
+
-
<pre>
+
-
apt-get install python-dev
+
-
 
+
-
cd targetcli
+
-
make deb
+
-
sudo dpkg -i dist/python-rtslib_2.1.9.g7076acf_all.deb
+
-
cd ..
+
-
</pre>
+
-
 
+
-
=== Run ===
+
-
 
+
-
Run the ''targetcli'' community edition from the ''targetcli'' directory as 'root' as follows:
+
-
 
+
-
<pre>
+
-
PYTHONPATH=. ./scripts/targetcli
+
-
</pre>
+
-
 
+
-
== 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:
+
-
 
+
-
<pre>
+
-
cd configshell/configshell
+
-
git checkout -t -b configshell_branch origin/master
+
-
<edit file.py>
+
-
git commit <file.py>
+
-
cd ..
+
-
make deb
+
-
</pre>
+
== See also ==
== See also ==
 +
* {{Target}}
 +
* [[{{OS}}]]
 +
* [[Support]]
* [[Contributing]]
* [[Contributing]]
-
* [[Support]]
+
* Fabric modules: [[FCoE]], [[Fibre Channel]], [[IBM vSCSI]], [[iSCSI]], [[iSER]], [[SRP]], [[tcm_loop]], [[vHost]]
-
* Fabric modules: [[iSCSI]], [[Fibre Channel]], [[Fibre Channel over Ethernet|FCoE]], [[InfiniBand]], [[IBM vSCSI]], [[tcm_loop]]
+
-
* Configuration: [[QLogic/targetcli]], [[Fibre Channel over Ethernet/targetcli|FCoE/targetcli]], [[SCSI RDMA Protocol/targetcli|SRP/targetcli]], [[tcm_loop/targetcli]]
+
-
* Distributions: [[RTS OS]]
+
-
* [[Target]]
+
== External links ==
== External links ==
-
* [http://www.gnu.org/licenses/agpl.html GNU Affero General Public License] (AGPL)
+
* {{LIO Admin Manual}}
-
* RTSadmin Administrator's Manual [[http://www.risingtidesystems.com/doc/RTS%20Admin%20Manual%20Community.pdf PDF]]
+
* RTSlib API Reference Guide {{Lib Ref Guide HTML}}{{Lib Ref Guide PDF}}
-
* RTSlib Library Reference Guide [[http://www.risingtidesystems.com/doc/rtslib-gpl/html HTML]][[http://www.risingtidesystems.com/doc/rtslib-gpl/pdf/rtslib-API-reference.pdf PDF]]
+
* {{Apache 2}}
[[Category:Management]]
[[Category:Management]]
[[Category:Target]]
[[Category:Target]]

Latest revision as of 02:14, 12 March 2016

targetcli
Logo
LIO 150513.png
Storage Manager
Original author(s) Jerome Martin
Michael Kromer
Nicholas Bellinger
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 AGPLv3
Website datera.io
targetcli running with mixed-mode iSCSI, SCSI virtualziation, FCoE, Fibre Channel and IB/SRP.

targetcli is the single-node LinuxIO management shell by Datera, Inc..

Contents

Overview

targetcli is the general management platform for the LinuxIO. It comprises a shell that uses the LIO library through a well-defined API, and is available under the Apache License, version 2.0 (Apache License). 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. Everyone is welcome to contribute.

targetcli was released on October 14, 2009 (2009-10-14), and supports all fabric modules, including FCoE, Fibre Channel, IBM vSCSI, iSCSI, iSER, SRP, tcm_loop, and vHost. It is is based on a modular, extensible architecture, with plug-in modules for additional functionality.

targetcli consists of three Python modules:

Download and build instructions for targetcli are on the download page.

Linux distributions

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

Distribution Version[Linux 1] Release Archive Install Source git[Linux 2] Documentation
CentOS 6.2 2011-12-20 CentOS mirror su -c 'yum install fcoe-target-utils' targetcli-fb.git Tech Notes
Debian 7.0 ("wheezy") TBA Debian pool su -c 'apt-get install targetcli' targetcli
Fedora 16, 17/18 2011-11-08 Fedora Rawhide su -c 'yum install targetcli' targetcli-fb.git Target Wiki
openSUSE 12.1 2011-11-08 Requires manual installation from targetcli.
RHEL 6.2 2011-11-16 Fedora Rawhide su -c 'yum install fcoe-target-utils' targetcli-fb.git Tech Notes
Scientific Linux 6.2 2012-02-16 SL Mirror su -c 'yum install fcoe-target-utils' targetcli-fb.git Tech Notes
SLES SP2 2012-02-15 Requires manual installation from targetcli.
Ubuntu PrecisePangolin v12 2012-04-26 Ubuntu universe su -c 'apt-get install targetcli' targetcli
  1. The distribution release where LIO was included first.
  2. Technical support, and qualified backports to other kernels and distributions are available from Datera.

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

LIO is also natively supported in OpenStack (setup, code) via rtslib, starting with the Grizzly release.

Download and build instructions for targetcli are on the download page.

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.

Mounting configFS

LIO and targetcli uses configFS for its configuration. All storage objects can be accessed and exported, so the configFS module must be loaded and configFS must be mounted. Mount configFS at /sys/kernel/config:

mount -t configfs configfs /sys/kernel/config

This can also be added to /etc/fstab to automatically mount at boot:

configfs /sys/kernel/config configfs defaults 1 1

Note that /etc/init.d/target will automatically mount configFS if it's not already been mounted by /etc/fstab or manually by user.

Startup

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

# targetcli
Welcome to targetcli:

 Copyright (c) 2013 by Datera, Inc.
 All rights reserved.

Visit us at http://www.daterainc.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, as specified by the associated spec files (located in /var/target/fabric/fabric.spec).

Display help

Use help to get context-sensitive help, depending on 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
/>

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).

The global parameter auto_cd_after_create controls if targetcli automatically enters new object contexts after the creation of the corresponding new object.

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

Create a backstore

Enter the top-level backstore object, and create storage objects using IBLOCK, FILEIO or PSCSI type devices.

IBLOCK

Create an IBLOCK backstore, which can be any TYPE_DISK block-device, including LVM logical volumes and /dev/disk/by-id/ symlinks.

For instance, use the /dev/sdb block device:

/> cd backstores/
/backstores> iblock/ create name=block_backend dev=/dev/sdb
Generating a wwn serial.
Created iblock storage object block_backend using /dev/sdb.
/backstores>

Alternatively, any LVM logical volume can be used as a backstore, please refer to the LIO Admin Manual on how to create them properly.

For instance, create an IBLOCK backstore on a logical volume (under /dev/<volume_group_name>/<logical_volume_name>):

/backstores> iblock/ create name=block_backend_lvm lvm dev=/dev/vg0/lv1
Generating a wwn serial.
Created iblock storage object block_backend_lvm using /dev/vg0/lv1.
/backstores>

In both cases, targetcli automatically creates a WWN serial ID for the new backstore devices.

FILEIO

Create an FILEIO backstore with the underlying file /usr/src/fileio and size of 2 GB:

/> cd backstores/
/backstores> fileio/ create name=file_backend file_or_dev=/usr/src/fileio size=2G
Generating a wwn serial.
Not using buffered mode.
Created fileio file_backend.
/backstores>

targetcli automatically creates a WWN serial ID for the backstore device.

By default, FILEIO uses non-buffered mode (i.e. O_SYNC is set).

PSCSI

Create a PSCSI (SCSI pass-through) backstore for a physical SCSI device, in this case a TYPE_ROM device using /dev/sr0:

/backstores> pscsi/ create name=pscsi_backend dev=/dev/sr0
Generating a wwn serial.
Created pscsi storage object pscsi_backend using /dev/sr0.
/backstores>

targetcli automatically creates a WWN serial ID for the backstore device.

Ramdisk

Create a RAM disk backstore with a size of 1 GB:

/backstores> rd_mcp/ create name=rd_backend size=1GB
Generating a wwn serial.
Created rd_mcp ramdisk rd_backend with size 1GB.
/backstores>

targetcli automatically creates a WWN serial ID for the backstore device.

Display the resulting object tree

Use ls to list the resulting object hierarchy (displayed from the root object):

/> ls
o- / ..................................................................... [...]
  o- backstores .......................................................... [...]
  | o- fileio ............................................... [1 Storage Object]
  |   o- file_backend ............................ [/usr/src/fileio deactivated]
  | o- iblock .............................................. [2 Storage Objects]
  | | o- block_backend .................................. [/dev/sdb deactivated]
  | | o- block_backend_lvm .......................... [/dev/vg0/lv1 deactivated]
  | o- pscsi ................................................ [1 Storage Object]
  |   o- pscsi_backend .................................. [/dev/sr0 deactivated]
  | o- rd_dr ................................................ [0 Storage Object]
  | o- rd_mcp ............................................... [1 Storage Object]
  |   o- rd_backend ...................................... [ramdisk deactivated]
  o- ib_srpt ........................................................ [0 Target]
  o- iscsi .......................................................... [0 Target]
  o- loopback ....................................................... [0 Target]
  o- qla2xxx ........................................................ [0 Target]
/>

Create a target

LinuxIOs can now be instantiated as described for the fabrics, respectively:

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:

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 an LIO object tree, multiple context changes might be required to reach and enter a particular object. For instance:

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' (FCoE, Fibre Channel, iSCSI, iSER, SRP, 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 LIO object tree.

Global parameters

There are numerous global and context-sensitive parameters that modify the behavior of targetcli.

Here are two particularly important ones:

Object tree

The LIO object hierarchy encompasses both the fabric modules (FCoE, Fibre Channel, iSCSI, iSER, SRP, 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 LIO 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 LIO object hierarchy can be populated either manually by using the HBA and storage contexts of targetcli, or by directly referencing disks or files when creating LUNs. The latter requires less commands, but is not as flexible as manually creating the underlying storage objects.

Manual storage object creation should, however, only be necessary for:

Contact

Please direct all technical discussion on targetcli to the target-devel mailing list (post, subscribe, list info, gmane archive). For more information, please see Support.

See also

External links

Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox
Google AdSense