iSCSI

The Linux SCSI Target Wiki

(Difference between revisions)
Jump to: navigation, search
m (Create a backstore)
 
(111 intermediate revisions not shown)
Line 1: Line 1:
{{DISPLAYTITLE:iSCSI}}
{{DISPLAYTITLE:iSCSI}}
{{Infobox software
{{Infobox software
-
| name                  = LIO Target
+
| name                  = {{Target}}
-
| logo                  = [[Image:RisingTide_Logo_small.png|180px|Logo]]
+
| logo                  = [[Image:Corp_Logo.png|180px|Logo]]
| screenshot            = {{RTS screenshot|iSCSI}}
| screenshot            = {{RTS screenshot|iSCSI}}
| caption                = iSCSI fabric module
| caption                = iSCSI fabric module
Line 22: Line 22:
| language              =
| language              =
| genre                  = Fabric module
| genre                  = Fabric module
-
| license                = GNU General Public License
+
| license                = {{GPLv2}}
| website                = {{RTS website}}
| website                = {{RTS website}}
}}
}}
-
:''See [[Target]] for a complete overview over all fabric modules.''
+
:''See [[LIO]] for a complete overview over all fabric modules.''
{{Image|Compingles.gif|Architecture diagram of network storage types.}}
{{Image|Compingles.gif|Architecture diagram of network storage types.}}
{{Image|ISCSI_Login_CHAP.jpg|iSCSI login flow with [[CHAP]] authentication.}}
{{Image|ISCSI_Login_CHAP.jpg|iSCSI login flow with [[CHAP]] authentication.}}
-
'''iSCSI''' ('''Internet Small Computer System Interface''') provides SCSI access over IP networks.
+
'''iSCSI''' ('''Internet Small Computer System Interface''') provides [[SCSI]] access over IP networks.
== Overview ==
== Overview ==
-
iSCSI is an Internet Protocol (IP)-based storage networking standard for linking data storage facilities. By carrying [http://en.wikipedia.org/wiki/SCSI SCSI] commands over IP networks, iSCSI is used to facilitate data transfers over intranets and to manage storage over long distances. iSCSI can be used to transmit data over local area networks (LANs), wide area networks (WANs), or the Internet, and can enable location-independent data storage and retrieval.
+
iSCSI is an Internet Protocol (IP)-based storage networking standard for linking data storage facilities. By carrying [[SCSI]] commands over IP networks, iSCSI is used to facilitate data transfers over intranets and to manage storage over long distances. iSCSI can be used to transmit data over local area networks (LANs), wide area networks (WANs), or the Internet, and can enable location-independent data storage and retrieval.
-
iSCSI allows clients (called ''[[Core-iSCSI|Initiators]]'') to send SCSI commands (''[[CDB]]s'') to SCSI storage devices (''[[Target]]s'') on remote servers. It is a popular [http://en.wikipedia.org/wiki/Storage_area_network SAN] protocol, allowing organizations to consolidate storage into data center storage arrays while providing hosts (such as database and web servers) with the illusion of locally-attached disks. Unlike traditional [[Fibre Channel]], which requires special-purpose cabling, iSCSI can be run over long distances using existing network infrastructure.
+
iSCSI allows clients (called ''[[Core-iSCSI|Initiators]]'') to send SCSI commands (''[[CDB]]s'') to SCSI storage devices (''{{Target}}s'') on remote servers. It is a popular [http://en.wikipedia.org/wiki/Storage_area_network SAN] protocol, allowing organizations to consolidate storage into data center storage arrays while providing hosts (such as database and web servers) with the illusion of locally-attached disks. Unlike traditional [[Fibre Channel]], which requires special-purpose cabling, iSCSI can be run over long distances using existing network infrastructure.
-
iSCSI is the fabric module ([http://git.kernel.org/?p=linux/kernel/git/nab/target-pending.git;a=tree;f=drivers/target/iscsi;hb=HEAD iscsi_target_mod.ko]) for the Unified [[Target]] engine. It went upstream into the Linux 3.1 kernel on 7/27/2011.<ref>{{cite web| url=http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h=91d41fdf31f74e6e2e5f3cb018eca4200e36e202| title=iSCSI merge| author=Linus Torvalds| date=7/27/2011| publisher=lkml.org}}</ref>
+
== Hardware support ==
 +
 
 +
The following Ethernet NICs are supported:
 +
 
 +
* 1 GbE: all usual on-board or PCI NICs are supported.
 +
* 10 GbE: the [http://www.intel.com/ Intel] Ethernet [http://www.intel.com/content/www/us/en/network-adapters/gigabit-network-adapters/ethernet-x520.html X520 Adapters] are recommended.
 +
 
 +
The {{T}} iSCSI fabric module ({{RTS releases|iSCSI|module_repo}}, {{RTS releases|iSCSI|module_info}}) was released with Linux kernel {{RTS releases|iSCSI|kernel_ver}} on {{RTS releases|iSCSI|initial_date}}.<ref>{{RTS releases|iSCSI|kernel_rel}}</ref>
== targetcli ==
== targetcli ==
-
''[[targetcli]]'' from {{RTS full}} is used to configure iSCSI targets. ''targetcli'' aggregates service modules via a core library, and exports them through an API to the Unified [[Target]], to provide a unified single-node SAN configuration shell, independently of the underlying fabric(s).
+
''[[targetcli]]'' from {{RTS full}} is used to configure {{T}}. ''targetcli'' aggregates {{T}} service modules via a core library, and exports them through an API, to provide a unified single-node {{T}} SAN configuration shell, independently of the underlying fabric(s).
 +
 
 +
{{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 {{RTS short}} library.}}
 +
 
 +
=== Cheat sheet ===
 +
 
 +
{| class="table-left"
 +
|- bgcolor=#a0c0f0
 +
! Command
 +
! Comment
 +
|-
 +
| ''/backstores/iblock create my_disk /dev/sdb''
 +
| Create the LUN ''my_disk'' on the device ''/dev/sdb''
 +
|-
 +
| ''/iscsi create''
 +
| Create an iSCSI target
 +
|-
 +
| In /iscsi/<IQN>/tpgt1:<br/>''portals/ create <IP_address>''
 +
| Associate an ''<IP_address>''
 +
|-
 +
| In /iscsi/<IQN>/tpgt1:<br/>''luns/ create /backstores/iblock/my_disk''
 +
| Export the LUN ''my_disk''
 +
|-
 +
| In /iscsi/<IQN>/tpgt1:<br/>''set attribute authentication=0''<br/>''demo_mode_write_protect=0''<br/>''generate_node_acls=1''<br/>''cache_dynamic_acls=1''
 +
| Enable Demo Mode.<br/>'''Beware!'''
 +
|-
 +
| ''/saveconfig''
 +
| Commit the configuration
 +
|-
 +
|}
=== Startup ===
=== Startup ===
Line 52: Line 88:
Welcome to targetcli:
Welcome to targetcli:
-
  Copyright (c) 2012 by RisingTide Systems LLC.
+
  Copyright (c) 2014 by Datera, Inc.
  All rights reserved.
  All rights reserved.
-
Visit us at http://www.risingtidesystems.com.
+
Visit us at http://www.datera.io.
Using ib_srpt fabric module.
Using ib_srpt fabric module.
Line 74: Line 110:
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'').
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'').
-
=== Display the object hierarchy ===
+
=== Display the object tree ===
Use ''ls'' to list the object hierarchy, which is initially empty:
Use ''ls'' to list the object hierarchy, which is initially empty:
Line 94: Line 130:
</pre>
</pre>
-
'''Note:''' Per default, ''auto_cd_after_create=true'', which automatically changes the object context (or working directory) to new objects after their creation.
+
{{Ambox| type=info| head=Global parameter ''auto_cd_after_create''| text=After the creation of a new object, automatically enter its object context.}}
-
Set ''auto_cd_after_create=false'' to prevent RTSadmin from automatically changing the object context to new objects after their creation:
+
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 context after their their creation:
<pre>
<pre>
Line 106: Line 144:
=== Create a backstore ===
=== Create a backstore ===
-
Enter the top-level backstore object, and create one (storage object) using IBLOCK or FILEIO type devices.
+
Create a backstore using the 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:
+
For instance, enter the top-level ''backstore'' context and create an IBLOCK backstore from a ''/dev/sdb'' block device:
<pre>
<pre>
Line 119: Line 157:
</pre>
</pre>
-
Note that RTSadmin automatically creates a WWN serial ID for the backstore device and then changes the working context to it.
+
''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):
The resulting object hierarchy looks as follows (displayed from the root object):
Line 134: Line 172:
   | o- rd_mcp ............................................... [0 Storage Object]
   | o- rd_mcp ............................................... [0 Storage Object]
   o- ib_srpt ........................................................ [0 Target]
   o- ib_srpt ........................................................ [0 Target]
-
   o- iscsi .......................................................... [1 Target]
+
   o- iscsi .......................................................... [0 Target]
   o- loopback ....................................................... [0 Target]
   o- loopback ....................................................... [0 Target]
   o- qla2xxx ........................................................ [0 Target]
   o- qla2xxx ........................................................ [0 Target]
/>
/>
</pre>
</pre>
 +
 +
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>''):
 +
 +
<pre>
 +
/backstores> iblock/ create name=my_disk dev=/dev/vg0/lv1
 +
Generating a wwn serial.
 +
Created iblock storage object my_disk using /dev/vg0/lv1.
 +
Entering new node /backstores/iblock/my_disk.
 +
/backstores/iblock/my_disk>
 +
</pre>
 +
 +
Again, ''targetcli'' automatically creates a WWN serial ID for the backstore device and then changes the working context to it.
 +
 +
{{Ambox| type=info| head=More backstore examples| text=More examples on creating backstores can be found in ''[[targetcli#Create a backstore|targetcli]]''.}}
=== Instantiate a target ===
=== Instantiate a target ===
Line 203: Line 257:
<pre>
<pre>
-
/iscsi/iqn.20...a0e4a11/tpgt1> set attribute authentication=0
+
/iscsi/iqn.20...a0e4a11/tpgt1> set attribute authentication=0 demo_mode_write_protect=0
-
demo_mode_write_protect=0 generate_node_acls=1 cache_dynamic_acls=1.
+
generate_node_acls=1 cache_dynamic_acls=1.
Parameter demo_mode_write_protect is now '0'.
Parameter demo_mode_write_protect is now '0'.
Parameter authentication is now '0'.
Parameter authentication is now '0'.
Line 215: Line 269:
This exports the IBLOCK backstore as LUN0 to initiators without any access restrictions.
This exports the IBLOCK backstore as LUN0 to initiators without any access restrictions.
-
'''Warning''': Exporting "open" LUNs with no authentication requirements create significant security and data integrity hazards. Do not do this for production setups, unless you are certain of what you are doing.
+
{{Ambox| type=warning| head=Demo mode puts your data at risk!| text=Demo mode exports "open" LUNs with no authentication requirements. This creates significant security and data integrity hazards. Do not do this for production setups, unless you are certain of what you are doing.}}
-
Only use "demo mode" under the following circumstances:
+
Use "demo mode" only under the following conditions:
* You have established physical security through a closed, controlled SAN environment.
* You have established physical security through a closed, controlled SAN environment.
Line 223: Line 277:
* You have carefully analyzed your ACL setup with regard to its security and data integrity requirements and risks.
* You have carefully analyzed your ACL setup with regard to its security and data integrity requirements and risks.
-
==== CHAP Initiator Authentication ====
+
==== CHAP initiator authentication ====
Enable secure sessions for the initiator with the IQN "iqn.1991-05.com.microsoft:ibm-t410s":
Enable secure sessions for the initiator with the IQN "iqn.1991-05.com.microsoft:ibm-t410s":
<pre>
<pre>
-
/iscsi/iqn.20...70c82fb/tpgt1> acls/ create iqn.1991-05.com.microsoft:ibm-t410s
+
/iscsi/iqn.20...a0e4a11/tpgt1> acls/ create iqn.1991-05.com.microsoft:ibm-t410s
Successfully created Node ACL for iqn.1991-05.com.microsoft:ibm-t410s
Successfully created Node ACL for iqn.1991-05.com.microsoft:ibm-t410s
Created mapped LUN 0.
Created mapped LUN 0.
Line 244: Line 298:
<pre>
<pre>
-
/iscsi/iqn.20...70c82fb/tpgt1> cd acls/iqn.1991-05.com.microsoft:ibm-t410s
+
/iscsi/iqn.20...a0e4a11/tpgt1> cd acls/iqn.1991-05.com.microsoft:ibm-t410s
/iscsi/iqn.20...oft:ibm-t410s> set auth userid=iqn.1991-05.com.microsoft:ibm-t410s
/iscsi/iqn.20...oft:ibm-t410s> set auth userid=iqn.1991-05.com.microsoft:ibm-t410s
Parameter userid is now 'iqn.1991-05.com.microsoft:ibm-t410s'.
Parameter userid is now 'iqn.1991-05.com.microsoft:ibm-t410s'.
Line 251: Line 305:
/iscsi/iqn.20...oft:ibm-t410s> get auth
/iscsi/iqn.20...oft:ibm-t410s> get auth
AUTH CONFIG GROUP
AUTH CONFIG GROUP
-
   mutual_password=
+
   password_mutual=
-
     The mutual_password auth parameter.
+
     The password_mutual auth parameter.
-
   mutual_userid=
+
   userid_mutual=
-
     The mutual_userid auth parameter.
+
     The userid_mutual auth parameter.
   password=mytargetsecret
   password=mytargetsecret
Line 268: Line 322:
The iSCSI Endpoint is now ready for secure logins from the specified iSCSI initiator.
The iSCSI Endpoint is now ready for secure logins from the specified iSCSI initiator.
-
'''Note''': The Microsoft Windows iSCSI Initiator uses its IQN as a default login name. For CHAP Initiator Authentication, it requires the password length to be at least 12&nbsp;bytes (96&nbsp;bits), and it rejects passwords that are too simple. It allows changing the default login name through the ''Targets'' tab &rarr; ''Connect'' button &rarr; ''Connect To Target'' dialog &rarr; ''Advanced…'' button &rarr; ''Advanced Settings'' dialog &rarr; ''Enable CHAP log on'' checkbox.
+
{{Ambox| type=note| head=Microsoft Windows iSCSI Initiator| text=The Windows iSCSI Initiator uses its IQN as a default login name. For CHAP Initiator Authentication, it requires the password length to be at least 12&nbsp;bytes (96&nbsp;bits), and it rejects passwords that are too simple. The Windows iSCSI Initiator allows changing the default login name through the ''Targets'' tab &rarr; ''Connect'' button &rarr; ''Connect To Target'' dialog &rarr; ''Advanced…'' button &rarr; ''Advanced Settings'' dialog &rarr; ''Enable CHAP log on'' checkbox.}}
-
==== Mutual CHAP Authentication ====
+
==== Mutual CHAP authentication ====
Enable secure sessions for the initiator with the IQN "iqn.1991-05.com.microsoft:ibm-t410s":
Enable secure sessions for the initiator with the IQN "iqn.1991-05.com.microsoft:ibm-t410s":
<pre>
<pre>
-
/iscsi/iqn.20...70c82fb/tpgt1> acls/ create iqn.1991-05.com.microsoft:ibm-t410s
+
/iscsi/iqn.20...a0e4a11/tpgt1> acls/ create iqn.1991-05.com.microsoft:ibm-t410s
Successfully created Node ACL for iqn.1991-05.com.microsoft:ibm-t410s
Successfully created Node ACL for iqn.1991-05.com.microsoft:ibm-t410s
Created mapped LUN 0.
Created mapped LUN 0.
Line 291: Line 345:
* The ''userid'' (login name) and ''password'' (target secret) for the target.
* The ''userid'' (login name) and ''password'' (target secret) for the target.
-
* The ''mutual_userid'' (login name) and ''mutual_password'' (initiatir secret) for the initiator.
+
* The ''userid_mutual'' (login name) and ''password_mutual'' (initiator secret) for the initiator.
<pre>
<pre>
-
/iscsi/iqn.20...70c82fb/tpgt1> cd acls/iqn.1991-05.com.microsoft:ibm-t410s
+
/iscsi/iqn.20...a0e4a11/tpgt1> cd acls/iqn.1991-05.com.microsoft:ibm-t410s
-
/iscsi/iqn.20...oft:ibm-t410s> set auth userid=iqn.1991-05.com.microsoft:ibm-t410s password=mytargetsecret mutual_userid=iqn.2003-01.org.linux-iscsi.san01.x8664:sn.05135a0e4a11 mutual_password=mymutualsecret
+
/iscsi/iqn.20...oft:ibm-t410s> set auth userid=iqn.1991-05.com.microsoft:ibm-t410s password=mytargetsecret userid_mutual=iqn.2003-01.org.linux-iscsi.san01.x8664:sn.05135a0e4a11 password_mutual=mymutualsecret
Parameter userid is now 'iqn.1991-05.com.microsoft:ibm-t410s'.
Parameter userid is now 'iqn.1991-05.com.microsoft:ibm-t410s'.
Parameter password is now 'mytargetsecret'.
Parameter password is now 'mytargetsecret'.
-
Parameter mutual_userid is now 'iqn.2003-01.org.linux-iscsi.san01.x8664:sn.05135a0e4a11'.
+
Parameter userid_mutual is now 'iqn.2003-01.org.linux-iscsi.san01.x8664:sn.05135a0e4a11'.
Parameter password is now 'mymutualsecret'.
Parameter password is now 'mymutualsecret'.
/iscsi/iqn.20...oft:ibm-t410s> get auth
/iscsi/iqn.20...oft:ibm-t410s> get auth
AUTH CONFIG GROUP
AUTH CONFIG GROUP
-
   mutual_password=mymutualsecret
+
   password_mutual=mymutualsecret
-
     The mutual_password auth parameter.
+
     The password_mutual auth parameter.
-
   mutual_userid=iqn.2003-01.org.linux-iscsi.san01.x8664:sn.05135a0e4a11
+
   userid_mutual=iqn.2003-01.org.linux-iscsi.san01.x8664:sn.05135a0e4a11
-
     The mutual_userid auth parameter.
+
     The userid_mutual auth parameter.
   password=mytargetsecret
   password=mytargetsecret
Line 319: Line 373:
The iSCSI Endpoint is now ready for secure logins from the specified iSCSI initiator.
The iSCSI Endpoint is now ready for secure logins from the specified iSCSI initiator.
-
'''Note''': The Microsoft Windows iSCSI Initiator uses its IQN as the default login name. For Mutual CHAP Authentication, it requires the password length to be between 12&nbsp;bytes (96&nbsp;bits) and 16&nbsp;bytes (128&nbsp;bits), and it rejects passwords that are too simple. It allows changing the default login name through the ''Targets'' tab &rarr; ''Connect'' button &rarr; ''Connect To Target'' dialog &rarr; ''Advanced…'' button &rarr; ''Advanced Settings'' dialog &rarr; ''Enable CHAP log on'' checkbox.
+
{{Ambox| type=note| head=Microsoft Windows iSCSI Initiator| text=The Windows iSCSI Initiator uses its IQN as the default login name. For Mutual CHAP Authentication, it requires the password length to be between 12&nbsp;bytes (96&nbsp;bits) and 16&nbsp;bytes (128&nbsp;bits), and it rejects passwords that are too simple. The Windows iSCSI Initiator allows changing the default login name through the ''Targets'' tab &rarr; ''Connect'' button &rarr; ''Connect To Target'' dialog &rarr; ''Advanced…'' button &rarr; ''Advanced Settings'' dialog &rarr; ''Enable CHAP log on'' checkbox.}}
 +
 
 +
==== TPG authentication ====
 +
 
 +
Setting up authentication information for every single initiator separately can be cumbersome, so ''targetcli'' provides the capability to define common login information for all Endpoints in a TPG. As a result, all initiators connecting to that TPG can use the same login credentials.
 +
 
 +
Enable TPG Authentication for all Endpoints in a TPG:
 +
 
 +
<pre>
 +
/iscsi/iqn.20...a0e4a11/tpgt1> /iscsi/iqn.2003-01.org.linuxiscsi.
 +
san01.x8664:sn.bf919196ff4e/tgpt1/ set attribute demo_mode_write_protect=0 generate_node_acls=1
 +
cache_dynamic_acls=1
 +
Parameter demo_mode_write_protect is now '0'.
 +
Parameter generate_node_acls is now '1'.
 +
Parameter cache_dynamic_acls is now '1'.
 +
/iscsi/iqn.20...a0e4a11/tpgt1>
 +
</pre>
 +
 
 +
Setup the the common TPG Authentication credentials for all Endpoints in a TPG, which consists of:
 +
 
 +
* The ''userid'' (login name) and ''password'' (target secret) for the target.
 +
* The ''userid_mutual'' (login name) and ''password_mutual'' (initiator secret) for the initiator.
 +
 
 +
<pre>
 +
/iscsi/iqn.20...a0e4a11/tpgt1> set auth userid=rts-user
 +
Parameter userid is now 'rts-user'.
 +
/iscsi/iqn.20...a0e4a11/tpgt1> set auth password=b492785e-bc91-4710
 +
Parameter password is now 'b492785e-bc91-4710'.
 +
/iscsi/iqn.20...a0e4a11/tpgt1> set auth userid_mutual=mutual-rts-user
 +
Parameter userid_mutual is now 'mutual-rts-user'.
 +
/iscsi/iqn.20...a0e4a11/tpgt1> set auth password_mutual=aeae2e26-f043-42a7
 +
Parameter password_mutual is now 'aeae2e26-f043-42a7'.
 +
/iscsi/iqn.20...a0e4a11/tpgt1> get auth
 +
AUTH CONFIG GROUP
 +
  authenticate_target=0 [ro]
 +
    The authenticate_target auth_attr.
 +
 
 +
  password=b492785e-bc91-4710
 +
    The password auth_attr.
 +
 
 +
  password_mutual=aeae2e26-f043-42a7
 +
    The password_mutual auth_attr.
 +
 
 +
  userid=rts-user
 +
    The userid auth_attr.
 +
 
 +
  userid_mutual=mutual-rts-user
 +
    The userid_mutual auth_attr.
 +
/iscsi/iqn.20...a0e4a11/tpgt1>
 +
</pre>
 +
 
 +
{{Ambox| type=info| head=Individual ACLs| text=Login credentials for specific initiators can be created by adding corresponding ACL entries, as individual ACL entries override common TPG Authentication information.}}
 +
 
 +
{{Ambox| type=note| head=Microsoft Windows iSCSI Initiator| text=The Windows iSCSI Initiator uses its IQN as the default login name. For Mutual CHAP Authentication, it requires the password length to be between 12&nbsp;bytes (96&nbsp;bits) and 16&nbsp;bytes (128&nbsp;bits), and it rejects passwords that are too simple. The Windows iSCSI Initiator allows changing the default login name through the ''Targets'' tab &rarr; ''Connect'' button &rarr; ''Connect To Target'' dialog &rarr; ''Advanced…'' button &rarr; ''Advanced Settings'' dialog &rarr; ''Enable CHAP log on'' checkbox.}}
=== Enable discovery control ===
=== Enable discovery control ===
Line 325: Line 432:
Optionally, the iSCSI protocol can also control the visibility of iSCSI targets for discovery by iSCSI initiators.
Optionally, the iSCSI protocol can also control the visibility of iSCSI targets for discovery by iSCSI initiators.
-
==== CHAP Initiator Discovery Authentication ====
+
==== CHAP initiator discovery authentication ====
Enable CHAP initiator discovery authentication for all initiators by setting up a CHAP ''userid'' (login name) and ''password'' (target secret) in the global ''discovery_auth group'':
Enable CHAP initiator discovery authentication for all initiators by setting up a CHAP ''userid'' (login name) and ''password'' (target secret) in the global ''discovery_auth group'':
Line 339: Line 446:
Only iSCSI initiators that can authenticate themselves with a user id of "mytargetuid" and a password of "mytargetsecret" can now discover this iSCSI target.
Only iSCSI initiators that can authenticate themselves with a user id of "mytargetuid" and a password of "mytargetsecret" can now discover this iSCSI target.
-
==== Mutual CHAP Discovery Authentication ====
+
==== Mutual CHAP discovery authentication ====
Enable Mutual CHAP discovery authentication for all initiators by setting up Mutual CHAP information in the global ''discovery_auth'' group:
Enable Mutual CHAP discovery authentication for all initiators by setting up Mutual CHAP information in the global ''discovery_auth'' group:
Line 375: Line 482:
Only iSCSI initiators that can authenticate themselves with a user id of "mytargetuid" and a password of "mytargetsecret" can now discover this iSCSI target, and conversely, the iSCSI target can only discover iSCSI initiators that can authenticate themselves with a user id of "mymutualuid" and a password of "mymutualsecret".
Only iSCSI initiators that can authenticate themselves with a user id of "mytargetuid" and a password of "mytargetsecret" can now discover this iSCSI target, and conversely, the iSCSI target can only discover iSCSI initiators that can authenticate themselves with a user id of "mymutualuid" and a password of "mymutualsecret".
-
=== Display the object hierarchy ===
+
=== Display the object tree ===
The resulting iSCSI object hierarchy with CHAP Authentication (initiator or mutual) for one initiator looks as follows (displayed from the root object):
The resulting iSCSI object hierarchy with CHAP Authentication (initiator or mutual) for one initiator looks as follows (displayed from the root object):
Line 407: Line 514:
=== Persist the configuration ===
=== Persist the configuration ===
-
The target configuration can be persisted across OS reboots by using ''saveconfig'' from the root context:
+
{{Ambox| type=warning| head=Don't forget to use ''saveconfig''!| text=Without ''saveconfig'', the {{T}} configuration will be lost upon rebooting or unloading the target service, as the target configuration will revert back to the last saved one.}}
 +
 
 +
Use ''saveconfig'' from the root context to persist the target configuration across OS reboots:
<pre>
<pre>
Line 429: Line 538:
/>
/>
</pre>
</pre>
-
 
-
'''Warning:''' Without ''saveconfig'', the target configuration is ephemeral and will be lost upon rebooting or unloading the target service.
 
=== Spec file ===
=== Spec file ===
Line 436: Line 543:
RTS spec files define the fabric-dependent feature set, capabilities and available target ports of the specific underlying fabric.
RTS spec files define the fabric-dependent feature set, capabilities and available target ports of the specific underlying fabric.
-
In particular, the [[iSCSI]] spec file ''/var/target/fabric/iscsi.spec'' is included via RTSlib.
+
In particular, the iSCSI spec file ''/var/target/fabric/iscsi.spec'' is included via RTSlib.
<pre>
<pre>
Line 452: Line 559:
# The configfs group name is default
# The configfs group name is default
# configfs_group = iscsi
# configfs_group = iscsi
 +
</pre>
 +
 +
== Scripting with RTSlib ==
 +
 +
=== Setup script ===
 +
 +
The following Python code illustrates how to setup a basic iSCSI target and export a mapped LUN:
 +
 +
<pre>
 +
#!/usr/bin/python
 +
# iSCSI setup script example with RTSlib
 +
from rtslib import *
 +
 +
# Setup an IBLOCK backstore
 +
backstore = IBlockBackstore(3, mode='create')
 +
try:
 +
    so = IBlockStorageObject(backstore, "sdb", "/dev/sdb", gen_wwn=True)
 +
except:
 +
    backstore.delete()
 +
    raise
 +
 +
# Create an iSCSI target endpoint using an iSCSI IQN
 +
fabric = FabricModule('iscsi')
 +
target = Target(fabric, "iqn.2003-01.org.linux-iscsi.x.x8664:sn.d3d8b0500fde")
 +
tpg = TPG(target, 1)
 +
 +
# Setup a network portal in the iSCSI TPG
 +
# The IP address must already be active on the system
 +
portal = NetworkPortal(tpg, "192.168.1.128", "5060")
 +
 +
# Export LUN 0 via the 'so' StorageObject class
 +
lun0 = tpg.lun(0, so, "my_lun")
 +
 +
# Setup the NodeACL for an iSCSI initiator, and create MappedLUN 0
 +
node_acl = tpg.node_acl("iqn.2003-01.org.linux-iscsi.y.x8664:sn.abcdefghijkl")
 +
mapped_lun = node_acl.mapped_lun(0, 0, False)
 +
</pre>
 +
 +
=== Object tree ===
 +
 +
The resulting object tree looks as follows:
 +
 +
<pre>
 +
o- / ..................................................................... [...]
 +
  o- backstores .......................................................... [...]
 +
  | o- fileio ............................................... [0 Storage Object]
 +
  | o- iblock ............................................... [1 Storage Object]
 +
  | | o- sdb .............................................. [/dev/sdb activated]
 +
  | o- pscsi ................................................ [0 Storage Object]
 +
  | o- rd_dr ................................................ [0 Storage Object]
 +
  | o- rd_mcp ............................................... [0 Storage Object]
 +
  o- iscsi .......................................................... [1 Target]
 +
    o- iqn.2003-01.org.linux-iscsi.x.x8664:sn.d3d8b0500fde ............. [1 TPG]
 +
      o- tpgt1 ....................................................... [enabled]
 +
        o- acls ........................................................ [1 ACL]
 +
        | o- iqn.2003-01.org.linux-iscsi.y.x8664:sn.abcdefghijkl. [1 Mapped LUN]
 +
        |  o- mapped_lun0 ......................................... [lun0 (rw)]
 +
        o- luns ........................................................ [1 LUN]
 +
        | o- lun0 ...................................... [iblock/sdb (/dev/sdb)]
 +
        o- portals .................................................. [1 Portal]
 +
          o- 192.168.1.128:5060 ........................................... [OK]
</pre>
</pre>
Line 471: Line 639:
* {{RFC|5047|DA: Datamover Architecture for the Internet Small Computer System Interface (iSCSI)}}
* {{RFC|5047|DA: Datamover Architecture for the Internet Small Computer System Interface (iSCSI)}}
* {{RFC|5046|Internet Small Computer System Interface (iSCSI) Extensions for Remote Direct Memory Access (RDMA)}}
* {{RFC|5046|Internet Small Computer System Interface (iSCSI) Extensions for Remote Direct Memory Access (RDMA)}}
-
 
-
== Timeline ==
 
-
{{LIO Timeline}}
 
== See also ==
== See also ==
-
* [[RTS OS]], [[targetcli]]
+
* [[{{OS}}]]
-
* [[Target]]
+
* {{Target}}, [[targetcli]]
-
* [[Fibre Channel]], [[Fibre Channel over Ethernet|FCoE]], [[InfiniBand]], [[IBM vSCSI]], [[tcm_loop]]
+
* [[FCoE]], [[Fibre Channel]], [[iSER]], [[SRP]], [[tcm_loop]], [[vHost]]
-
* [[ConfigFS]]: [[iSCSI/configFS]] (low level kernel API)
+
* [[ConfigFS]] (low level kernel API)
== Notes ==
== Notes ==
Line 485: Line 650:
== External links ==
== External links ==
-
* [[RTS OS]] [http://www.risingtidesystems.com/doc/RTS%20OS%20Admin%20Manual%20CE.pdf Admin Manual]
+
* {{LIO Admin Manual}}
-
* RTSlib Reference Guide [[http://www.risingtidesystems.com/doc/rtslib-gpl/html/ HTML]][[http://www.risingtidesystems.com/doc/rtslib-gpl/pdf/rtslib-API-reference.pdf PDF]]
+
* RTSlib Reference Guide {{Lib Ref Guide HTML}}{{Lib Ref Guide PDF}}
* [http://en.wikipedia.org/wiki/ISCSI iSCSI] Wikipedia entry
* [http://en.wikipedia.org/wiki/ISCSI iSCSI] Wikipedia entry
* [http://blackmagic02881.wetpaint.com wetpaint.com] Fun storage stuff (Ming Zhang)
* [http://blackmagic02881.wetpaint.com wetpaint.com] Fun storage stuff (Ming Zhang)
 +
 +
{{LIO Timeline}}
[[Category:Fabric modules]]
[[Category:Fabric modules]]

Latest revision as of 02:33, 7 August 2015

LinuxIO
Logo
LIO 150513.png
iSCSI fabric module
Original author(s) Nicholas Bellinger
Developer(s) Datera, Inc.
Initial release October 24, 2011 (2011-10-24)
Stable release 4.1.0 / June 20, 2012;
8 years ago
 (2012-06-20)
Preview release 4.2.0-rc5 / June 28, 2012;
8 years ago
 (2012-06-28)
Development status Production
Written in C
Operating system Linux
Type Fabric module
License GNU General Public License, version 2 (GPLv2)
Website datera.io
See LIO for a complete overview over all fabric modules.
Architecture diagram of network storage types.
iSCSI login flow with CHAP authentication.

iSCSI (Internet Small Computer System Interface) provides SCSI access over IP networks.

Contents

Overview

iSCSI is an Internet Protocol (IP)-based storage networking standard for linking data storage facilities. By carrying SCSI commands over IP networks, iSCSI is used to facilitate data transfers over intranets and to manage storage over long distances. iSCSI can be used to transmit data over local area networks (LANs), wide area networks (WANs), or the Internet, and can enable location-independent data storage and retrieval.

iSCSI allows clients (called Initiators) to send SCSI commands (CDBs) to SCSI storage devices (LinuxIOs) on remote servers. It is a popular SAN protocol, allowing organizations to consolidate storage into data center storage arrays while providing hosts (such as database and web servers) with the illusion of locally-attached disks. Unlike traditional Fibre Channel, which requires special-purpose cabling, iSCSI can be run over long distances using existing network infrastructure.

Hardware support

The following Ethernet NICs are supported:

The LIO iSCSI fabric module (iscsi.ko, Linux kernel driver database) was released with Linux kernel 3.1 on October 24, 2011 (2011-10-24).[1]

targetcli

targetcli from Datera, Inc. is used to configure LIO. targetcli aggregates LIO service modules via a core library, and exports them through an API, to provide a unified single-node LIO SAN configuration shell, independently of the underlying fabric(s).

Cheat sheet

Command Comment
/backstores/iblock create my_disk /dev/sdb Create the LUN my_disk on the device /dev/sdb
/iscsi create Create an iSCSI target
In /iscsi/<IQN>/tpgt1:
portals/ create <IP_address>
Associate an <IP_address>
In /iscsi/<IQN>/tpgt1:
luns/ create /backstores/iblock/my_disk
Export the LUN my_disk
In /iscsi/<IQN>/tpgt1:
set attribute authentication=0
demo_mode_write_protect=0
generate_node_acls=1
cache_dynamic_acls=1
Enable Demo Mode.
Beware!
/saveconfig Commit the configuration

Startup

targetcli is invoked by running targetcli as root from the command prompt of the underlying OS shell.

# targetcli
Welcome to targetcli:

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

Visit us at http://www.datera.io.

Using ib_srpt fabric module.
Using qla2xxx fabric module.
Using iscsi fabric module.
Using loopback fabric module.

/> iscsi/ info
Fabric module name: iscsi
ConfigFS path: /sys/kernel/config/target/iscsi
Allowed WWNs list type: iqn
Fabric module specfile: /var/target/fabric/iscsi.spec
Fabric module features: discovery_auth, acls, acls_auth, nps, tpgts
Corresponding kernel module: iscsi_target_mod
/>

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

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

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 context after their their creation:

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

Create a backstore

Create a backstore using the IBLOCK or FILEIO type devices.

For instance, enter the top-level backstore context and create an IBLOCK backstore from a /dev/sdb block device:

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

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=my_disk dev=/dev/vg0/lv1
Generating a wwn serial.
Created iblock storage object my_disk using /dev/vg0/lv1.
Entering new node /backstores/iblock/my_disk.
/backstores/iblock/my_disk>

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

Instantiate a target

Instantiate an iSCSI target on the existing backstore my_disk:

/backstores/iblock/my_disk> /iscsi create
Created target iqn.2003-01.org.linux-iscsi.san01.x8664:sn.05135a0e4a11.
Selected TPG Tag 1.
Successfully created TPG 1.
Entering new node /iscsi/iqn.2003-01.org.linux-iscsi.san01.x8664:sn.05135a0e4a11/tpgt1.
/iscsi/iqn.20...a0e4a11/tpgt1>

targetcli automatically creates the Target Portal Group (TPG) and per default assigns a sequentially increasing TPG tag, starting from '1', thereby creating a TPG1.

Export LUNs

Add LUNs to the iSCSI target:

/iscsi/iqn.20...a0e4a11/tpgt1> luns/ create /backstores/iblock/my_disk
Selected LUN 0.
Successfully created LUN 0.
Entering new node /iscsi/iqn.2003-01.org.linux-iscsi.san01.x8664:sn.05135a0e4a11/tpgt1/luns/lun0.
/iscsi/iqn.20...gt1/luns/lun0>

targetcli per default automatically assigns sequentially increasing LUN IDs, starting from '0', thereby exporting /dev/sdb as LUN 0 in the example above.

Return to the underlying TPG as the working context, as no attributes need to be set or modified for standard LUNs:

/iscsi/iqn.20...gt1/luns/lun0> cd <
Taking you back to /iscsi/iqn.2003-01.org.linux-iscsi.san01.x8664:sn.05135a0e4a11/tpgt1.
/iscsi/iqn.20...a0e4a11/tpgt1>

Create a network portal

Assign an active IP address (here the IPv4 address 192.168.1.139) to the iSCSI TPG to form a valid iSCSI Endpoint:

/iscsi/iqn.20...a0e4a11/tpgt1> portals/ create 192.168.1.139
Using default IP port 3260
Successfully created network portal 192.168.1.139:3260.
Entering new node /iscsi/iqn.2003-01.org.linux-iscsi.san01.x8664:sn.05135a0e4a11/tpgt1/portals/192.168.1.139:3260.
/iscsi/iqn.20...68.1.139:3260>
/iscsi/iqn.20...68.1.139:3260> cd <
Taking you back to /iscsi/iqn.2003-01.org.linux-iscsi.san01.x8664:sn.05135a0e4a11/tpgt1.
/iscsi/iqn.20...a0e4a11/tpgt1>

For iSCSI Network Portals, targetcli automatically uses the iSCSI default port number of '3260', thereby forming a valid new iSCSI Endpoint. The iSCSI Endpoint makes the TPG discoverable by iSCSI initiators.

Define access rights

Configure the access rights to allow logins from initiators. The three basic setups for LUN authentication are discussed below.

Demo mode

For simple demo setups, "open" access can be granted to all initiators so that they can access all LUNs in the TPG without further authentication. To enable that so-called "demo mode" TPG operation, disable all authentication for the corresponding Endpoint:

/iscsi/iqn.20...a0e4a11/tpgt1> set attribute authentication=0 demo_mode_write_protect=0
generate_node_acls=1 cache_dynamic_acls=1.
Parameter demo_mode_write_protect is now '0'.
Parameter authentication is now '0'.
Parameter generate_node_acls is now '1'.
Parameter cache_dynamic_acls is now '1'.
/iscsi/iqn.20...a0e4a11/tpgt1> cd /
/>

This exports the IBLOCK backstore as LUN0 to initiators without any access restrictions.

Use "demo mode" only under the following conditions:

CHAP initiator authentication

Enable secure sessions for the initiator with the IQN "iqn.1991-05.com.microsoft:ibm-t410s":

/iscsi/iqn.20...a0e4a11/tpgt1> acls/ create iqn.1991-05.com.microsoft:ibm-t410s
Successfully created Node ACL for iqn.1991-05.com.microsoft:ibm-t410s
Created mapped LUN 0.
Entering new node /iscsi/iqn.2003-01.org.linux-iscsi.san01.x8664:sn.05135a0e4a11/tpgt1/acls/iqn.1991-05.com.microsoft:ibm-t410s/mapped_lun0.
/iscsi/iqn.20...s/mapped_lun0> cd <
Taking you back to /iscsi/iqn.2003-01.org.linux-iscsi.san01.x8664:sn.05135a0e4a11/tpgt1.
/iscsi/iqn.20...a0e4a11/tpgt1>

This creates an iSCSI Node ACL with a mapped LUN0.

Node ACLs allow mappings of actual LUN IDs onto arbitrary Mapped_LUN IDs, which are the LUN IDs presented to initiators. These mappings can match preferred LUN IDs for particular initiators, so for instance, a LUN1 can be mapped onto Mapped_LUN0 to make LUN1 appear as iSCSI LUN0 on the initiator. Usually, LUNs are identically mapped, however.

Setup the CHAP logon information for an initiator, which consists of the userid (login name) and password (target secret) from the initiator:

/iscsi/iqn.20...a0e4a11/tpgt1> cd acls/iqn.1991-05.com.microsoft:ibm-t410s
/iscsi/iqn.20...oft:ibm-t410s> set auth userid=iqn.1991-05.com.microsoft:ibm-t410s
Parameter userid is now 'iqn.1991-05.com.microsoft:ibm-t410s'.
/iscsi/iqn.20...oft:ibm-t410s> set auth password=mytargetsecret
Parameter password is now 'mytargetsecret'.
/iscsi/iqn.20...oft:ibm-t410s> get auth
AUTH CONFIG GROUP
  password_mutual=
    The password_mutual auth parameter.

  userid_mutual=
    The userid_mutual auth parameter.

  password=mytargetsecret
    The password auth parameter.

  userid=iqn.1991-05.com.microsoft:ibm-t410
    The userid auth parameter.
/iscsi/iqn.20...oft:ibm-t410s> cd /iscsi
/iscsi>

The iSCSI Endpoint is now ready for secure logins from the specified iSCSI initiator.

Mutual CHAP authentication

Enable secure sessions for the initiator with the IQN "iqn.1991-05.com.microsoft:ibm-t410s":

/iscsi/iqn.20...a0e4a11/tpgt1> acls/ create iqn.1991-05.com.microsoft:ibm-t410s
Successfully created Node ACL for iqn.1991-05.com.microsoft:ibm-t410s
Created mapped LUN 0.
Entering new node /iscsi/iqn.2003-01.org.linux-iscsi.san01.x8664:sn.05135a0e4a11/tpgt1/acls/iqn.1991-05.com.microsoft:ibm-t410s/mapped_lun0.
/iscsi/iqn.20...s/mapped_lun0> cd <
Taking you back to /iscsi/iqn.2003-01.org.linux-iscsi.san01.x8664:sn.05135a0e4a11/tpgt1.
/iscsi/iqn.20...a0e4a11/tpgt1>

This creates an iSCSI Node ACL with a mapped LUN0.

Node ACLs allow mappings of actual LUN IDs onto arbitrary Mapped_LUN IDs, which are the LUN IDs presented to initiators. These mappings can match preferred LUN IDs for particular initiators, so for instance, a LUN1 can be mapped onto Mapped_LUN0 to make LUN1 appear as iSCSI LUN0 on the initiator. Usually, LUNs are identically mapped, however.

Setup the mutual CHAP logon information for an initiator, which consists of:

/iscsi/iqn.20...a0e4a11/tpgt1> cd acls/iqn.1991-05.com.microsoft:ibm-t410s
/iscsi/iqn.20...oft:ibm-t410s> set auth userid=iqn.1991-05.com.microsoft:ibm-t410s password=mytargetsecret userid_mutual=iqn.2003-01.org.linux-iscsi.san01.x8664:sn.05135a0e4a11 password_mutual=mymutualsecret
Parameter userid is now 'iqn.1991-05.com.microsoft:ibm-t410s'.
Parameter password is now 'mytargetsecret'.
Parameter userid_mutual is now 'iqn.2003-01.org.linux-iscsi.san01.x8664:sn.05135a0e4a11'.
Parameter password is now 'mymutualsecret'.
/iscsi/iqn.20...oft:ibm-t410s> get auth
AUTH CONFIG GROUP
  password_mutual=mymutualsecret
    The password_mutual auth parameter.

  userid_mutual=iqn.2003-01.org.linux-iscsi.san01.x8664:sn.05135a0e4a11
    The userid_mutual auth parameter.

  password=mytargetsecret
    The password auth parameter.

  userid=iqn.1991-05.com.microsoft:ibm-t410
    The userid auth parameter.
/iscsi/iqn.20...oft:ibm-t410s> cd /iscsi
/iscsi>

The iSCSI Endpoint is now ready for secure logins from the specified iSCSI initiator.

TPG authentication

Setting up authentication information for every single initiator separately can be cumbersome, so targetcli provides the capability to define common login information for all Endpoints in a TPG. As a result, all initiators connecting to that TPG can use the same login credentials.

Enable TPG Authentication for all Endpoints in a TPG:

/iscsi/iqn.20...a0e4a11/tpgt1> /iscsi/iqn.2003-01.org.linuxiscsi.
san01.x8664:sn.bf919196ff4e/tgpt1/ set attribute demo_mode_write_protect=0 generate_node_acls=1
cache_dynamic_acls=1
Parameter demo_mode_write_protect is now '0'.
Parameter generate_node_acls is now '1'.
Parameter cache_dynamic_acls is now '1'.
/iscsi/iqn.20...a0e4a11/tpgt1>

Setup the the common TPG Authentication credentials for all Endpoints in a TPG, which consists of:

/iscsi/iqn.20...a0e4a11/tpgt1> set auth userid=rts-user
Parameter userid is now 'rts-user'.
/iscsi/iqn.20...a0e4a11/tpgt1> set auth password=b492785e-bc91-4710
Parameter password is now 'b492785e-bc91-4710'.
/iscsi/iqn.20...a0e4a11/tpgt1> set auth userid_mutual=mutual-rts-user
Parameter userid_mutual is now 'mutual-rts-user'.
/iscsi/iqn.20...a0e4a11/tpgt1> set auth password_mutual=aeae2e26-f043-42a7
Parameter password_mutual is now 'aeae2e26-f043-42a7'.
/iscsi/iqn.20...a0e4a11/tpgt1> get auth
AUTH CONFIG GROUP
  authenticate_target=0 [ro]
    The authenticate_target auth_attr.

  password=b492785e-bc91-4710
    The password auth_attr.

  password_mutual=aeae2e26-f043-42a7
    The password_mutual auth_attr.

  userid=rts-user
    The userid auth_attr.

  userid_mutual=mutual-rts-user
    The userid_mutual auth_attr.
/iscsi/iqn.20...a0e4a11/tpgt1>

Enable discovery control

Optionally, the iSCSI protocol can also control the visibility of iSCSI targets for discovery by iSCSI initiators.

CHAP initiator discovery authentication

Enable CHAP initiator discovery authentication for all initiators by setting up a CHAP userid (login name) and password (target secret) in the global discovery_auth group:

/iscsi> set discovery_auth enable=1 userid=mytargetuid password=mytargetsecret
Parameter enable is now '1'.
Parameter password is now 'mytargetsecret'.
Parameter userid is now 'mytargetuid'.
/iscsi>

Only iSCSI initiators that can authenticate themselves with a user id of "mytargetuid" and a password of "mytargetsecret" can now discover this iSCSI target.

Mutual CHAP discovery authentication

Enable Mutual CHAP discovery authentication for all initiators by setting up Mutual CHAP information in the global discovery_auth group:

/iscsi> set discovery_auth enable=1 userid=mytargetuid password=mytargetsecret
mutual_userid=mymutualuid mutual_password=mymutualsecret
Parameter password is now 'mytargetsecret'.
Parameter userid is now 'mytargetuid'.
Parameter mutual_password is now 'mymutualsecret'.
Parameter mutual_userid is now 'mymutualuid'.
Parameter enable is now '1'.
/iscsi> get discovery_auth
DISCOVERY_AUTH CONFIG GROUP
  enable=1
    The enable discovery_auth parameter.

  mutual_password=mymutualsecret
    The mutual_password discovery_auth parameter.

  mutual_userid=mymutualuid
    The mutual_userid discovery_auth parameter.

  password=mytargetsecret
    The password discovery_auth parameter.

  userid=mytargetuid
    The userid discovery_auth parameter.
/iscsi>

Only iSCSI initiators that can authenticate themselves with a user id of "mytargetuid" and a password of "mytargetsecret" can now discover this iSCSI target, and conversely, the iSCSI target can only discover iSCSI initiators that can authenticate themselves with a user id of "mymutualuid" and a password of "mymutualsecret".

Display the object tree

The resulting iSCSI object hierarchy with CHAP Authentication (initiator or mutual) for one initiator 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 .......................................................... [1 Target]
  | o- iqn.2003-01.org.linux-iscsi.san01.x8664:sn.05135a0e4a11 ......... [1 TPG]
  |   o- tpgt1 ....................................................... [enabled]
  |     o- acls ........................................................ [1 ACL]
  |     | o- iqn.1991-05.com.microsoft:ibm-t410s ................ [1 Mapped LUN]
  |     |   o- mapped_lun0 ......................................... [lun0 (rw)]
  |     o- luns ........................................................ [1 LUN]
  |     | o- lun0 .................................. [iblock/my_disk (/dev/sdb)]
  |     o- portals .................................................. [1 Portal]
  |       o- 192.168.1.139:3260 ........................................... [OK]
  o- loopback ....................................................... [0 Target]
  o- qla2xxx ........................................................ [0 Target]
/>

Persist the configuration

Use saveconfig from the root context to persist the target configuration across OS reboots:

/> saveconfig
WARNING: Saving rtsnode1 current configuration to disk will overwrite your boot settings.
The current target configuration will become the default boot config.
Are you sure? Type 'yes': yes
Making backup of srpt/ConfigFS with timestamp: 2012-02-27_23:19:37.660264
Successfully updated default config /etc/target/srpt_start.sh
Making backup of qla2xxx/ConfigFS with timestamp: 2012-02-27_23:19:37.660264
Successfully updated default config /etc/target/qla2xxx_start.sh
Making backup of loopback/ConfigFS with timestamp: 2012-02-27_23:19:37.660264
Successfully updated default config /etc/target/loopback_start.sh
Making backup of LIO-Target/ConfigFS with timestamp: 2012-02-27_23:19:37.660264
Successfully updated default config /etc/target/lio_backup-2012-02-27_23:19:37.660264.sh
Making backup of Target_Core_Mod/ConfigFS with timestamp: 2012-02-27_23:19:37.660264
Successfully updated default config /etc/target/tcm_backup-2012-02-27_23:19:37.660264.sh
Generated Target_Core_Mod config: /etc/target/backup/tcm_backup-2012-02-27_23:19:37.660264.sh
Successfully updated default config /etc/target/lio_start.sh
Successfully updated default config /etc/target/tcm_start.sh
/>

Spec file

RTS spec files define the fabric-dependent feature set, capabilities and available target ports of the specific underlying fabric.

In particular, the iSCSI spec file /var/target/fabric/iscsi.spec is included via RTSlib.

# WARNING: This is a draft specfile supplied for demo purposes only.

# The iSCSI fabric module uses the default feature set.
features = acls, acls_auth, discovery_auth, nps, tpgts

# Obviously, this module uses IQN strings as WWNs
wwn_type = iqn

# The kernel module is default
# kernel_module = iscsi_target_mod

# The configfs group name is default
# configfs_group = iscsi

Scripting with RTSlib

Setup script

The following Python code illustrates how to setup a basic iSCSI target and export a mapped LUN:

#!/usr/bin/python
# iSCSI setup script example with RTSlib
from rtslib import *

# Setup an IBLOCK backstore
backstore = IBlockBackstore(3, mode='create')
try:
    so = IBlockStorageObject(backstore, "sdb", "/dev/sdb", gen_wwn=True)
except:
    backstore.delete()
    raise

# Create an iSCSI target endpoint using an iSCSI IQN
fabric = FabricModule('iscsi')
target = Target(fabric, "iqn.2003-01.org.linux-iscsi.x.x8664:sn.d3d8b0500fde")
tpg = TPG(target, 1)

# Setup a network portal in the iSCSI TPG
# The IP address must already be active on the system
portal = NetworkPortal(tpg, "192.168.1.128", "5060")

# Export LUN 0 via the 'so' StorageObject class
lun0 = tpg.lun(0, so, "my_lun")

# Setup the NodeACL for an iSCSI initiator, and create MappedLUN 0
node_acl = tpg.node_acl("iqn.2003-01.org.linux-iscsi.y.x8664:sn.abcdefghijkl")
mapped_lun = node_acl.mapped_lun(0, 0, False)

Object tree

The resulting object tree looks as follows:

o- / ..................................................................... [...]
  o- backstores .......................................................... [...]
  | o- fileio ............................................... [0 Storage Object]
  | o- iblock ............................................... [1 Storage Object]
  | | o- sdb .............................................. [/dev/sdb activated]
  | o- pscsi ................................................ [0 Storage Object]
  | o- rd_dr ................................................ [0 Storage Object]
  | o- rd_mcp ............................................... [0 Storage Object]
  o- iscsi .......................................................... [1 Target]
    o- iqn.2003-01.org.linux-iscsi.x.x8664:sn.d3d8b0500fde ............. [1 TPG]
      o- tpgt1 ....................................................... [enabled]
        o- acls ........................................................ [1 ACL]
        | o- iqn.2003-01.org.linux-iscsi.y.x8664:sn.abcdefghijkl. [1 Mapped LUN]
        |   o- mapped_lun0 ......................................... [lun0 (rw)]
        o- luns ........................................................ [1 LUN]
        | o- lun0 ...................................... [iblock/sdb (/dev/sdb)]
        o- portals .................................................. [1 Portal]
          o- 192.168.1.128:5060 ........................................... [OK]

RFCs

See also

Notes

  1. Linus Torvalds (2011-10-24). "Linux 3.1". lkml.org. 

External links

Timeline of the LinuxIO
Release Details 2011 2012 2013 2014 2015
123456789101112 123456789101112 123456789101112 123456789101112 123456789101112
4.x Version 4.0 4.1
Feature LIO Core Loop back FCoE iSCSI Perf SRP
CM WQ FC
USB
1394
vHost Perf Misc 16 GFC iSER Misc VAAI Misc DIF Core
NPIV
DIF iSER DIF FC vhost TCMU Xen Misc Misc virtio 1.0 Misc NVMe OF
Linux 2.6.38 2.6.39 3.0 3.1 3.2 3.3 3.4 3.5 3.6 3.7 3.8 3.9 3.10 3.11 3.12 3.13 3.14 3.15 3.16 3.17 3.18 3.19 3.20 3.21 3.22
Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox
Google AdSense