HOTO Config Mass Storage over IP Networks—iSCSI

One of the central tasks in computer centers and when operating servers is providing hard disk capacity for server systems. Fiber channel is often used for this purpose in the mainframe sector. So far, UNIX computers and the majority of servers are not connected to central storage solutions.

linux-iSCSI provides an easy and reasonably inexpensive solution for connecting Linux computers to central storage systems. In principle, iSCSI represents a transfer of SCSI commands on the IP level. If a program starts an inquiry for such a device, the operating system produces the necessary SCSI commands. These are then embedded in IP packages and encrypted as necessary by software that is commonly known as an iSCSI initiator. The packages are then transferred to the corresponding iSCSI remote station, also called iSCSI target.

Many storage solutions provide access over iSCSI, but it is also possible to run a Linux server that provides an iSCSI target. In this case, it is important to set up the Linux server optimized for file system services. The iSCSI target just accesses block devices in Linux. Therefore it is possible to use RAID solutions to increase disk space as well as a lot of memory to improve data caching. For more information about RAID, also see  Section 6.2, Soft RAID Configuration .

11.1 Setting Up an iSCSI Target

SUSE® Linux Enterprise Server comes with an open source iSCSI target solution that evolved from the Ardis iSCSI target. A basic setup can be done with YaST, but to take full advantage of iSCSI, a manual setup is required.

11.1.1 Creating iSCSI Targets with YaST

The iSCSI target configuration exports existing block devices or file system images to iSCSI initiators. First create the needed block devices with YaST or create file system images. For an overview of partitioning, see  Section 7.5.8, Partitioner . File system images must be created manually. For example, if you want to create the image /var/lib/xen/images/xen-0 with the size 4GB, first make sure that the directory is there then create the image itself:

mkdir -p /var/lib/xen/images

dd if=/dev/zero of=/var/lib/xen/images/xen-0 seek=1M bs=4096 count=1

To configure the iSCSI target, run the iSCSI Target module in YaST. The configuration is split into three tabs. In the Service tab, select the start mode and the firewall settings. If you want to access the iSCSI target from a remote machine, select Open Port in Firewall.

The Global tab provides settings for the iSCSI server. The authentication set here is used for the discovery of services, not for accessing the targets. If you do not want to restrict the access to the discovery, use No Authentication.

If authentication is needed, there are two possibilities to consider. One is that an initiator must prove that it has the permissions to run a discovery on the iSCSI target. This is done with Incoming Authentication. The other is that the iSCSI target must prove to the initiator that it is the expected target. Therefore, the iSCSI target can also provide a username and password. This is done with Outgoing Authentication. Find more information about authentication in RFC 3720 (see  http://www.ietf.org/rfc/rfc3720.txt ).

The targets are defined in the Targets tab. Use Add to create a new iSCSI target. The first dialog asks for information about the device to export.

Target

The Target line has a fixed syntax that looks like the following:

iqn.yyyy-mm.<reversed domain name>

It always starts with iqn. yyyy-mm is the format of the date when this target is activated. Find more about naming conventions in RFC 3722 (see  http://www.ietf.org/rfc/rfc3722.txt ).

Identifier

The Identifier is freely selectable. It should follow some scheme to make the whole system more structured.

LUN

It is possible to assign several LUNs to a target. However, this is not supported with YaST. Therefore, this should always be the number 0.

Path

Add the path to the block device or file system image to export.

The next menu configures the access restrictions of the target. The configuration is very similar to the configuration of the discovery authentication. In this case, at least an incoming authentication should be setup.

Next finishes the configuration of the new target, and brings you back to the overview page of the Target tab. Activate your changes by clicking on Finish.

11.1.2 Configuring an iSCSI Target Manually

Configure an iSCSI target in /etc/ietd.conf. All parameters in this file before the first Target declaration are global for the file. Authentication information in this portion has a special meaning—it is not global, but is used for the discovery of the iSCSI target.

All iSCSI authentication may be done in two directions. The iSCSI target can require the iSCSI initiator to authenticate with the IncomingUser, which can be added multiple times. The iSCSI initiator may also require the iSCSI target to authenticate. Use OutgoingUser for this. Both have the same syntax:

IncomingUser <username> <password>

OutgoingUser <username> <password>

The authentication is followed by one or several target definitions. For each target, add a Target section. This section always starts with a Target identifier followed by definitions of logical unit numbers:

Target iqn.yyyy-mm.<reversed domain name>[:identifier]

          Lun 0 Path=/dev/mapper/system-v3

          Lun 1 Path=/dev/hda4

          Lun 2 Path=/var/lib/xen/images/xen-1,Type=fileio

In the Target line, yyyy-mm is the date when this target is activated, and identifier is freely selectable. Find more about naming conventions in RFC 3722 (see  http://www.ietf.org/rfc/rfc3722.txt ). Three different block devices are exported in this example. The first one is a logical volume (see also  Section 6.1, LVM Configuration ), the second is an IDE partition, and the third is an image available in the local file system. All these look like block devices to an iSCSI initiator.

Before activating the iSCSI target, add at least one IncomingUser after the Lun definitions. It does the authentication for the use of this target.

To activate all your changes, restart the iscsitarget daemon with rciscsi restart. Check your configuration in the /proc file system:

cat /proc/net/iet/volume

tid:1 name:iqn.2006-02.com.example.iserv:systems

        lun:0 state:0 iotype:fileio path:/dev/mapper/system-v3

        lun:1 state:0 iotype:fileio path:/dev/hda4

        lun:2 state:0 iotype:fileio path:/var/lib/xen/images/xen-1

There are many more options that control the behavior of the iSCSI target. Find them in the manual page of ietd.conf.

Active sessions are also displayed in the /proc file system. For each connected initiator, an extra entry is added to /proc/net/iet/session:

cat /proc/net/iet/session

tid:1 name:iqn.2006-02.com.example.iserv:system-v3

   sid:562949957419520 initiator:iqn.2005-11.de.suse:cn=rome.example.com,01.9ff842f5645

      cid:0 ip:192.168.178.42 state:active hd:none dd:none

   sid:281474980708864 initiator:iqn.2006-02.de.suse:01.6f7259c88b70

      cid:0 ip:192.168.178.72 state:active hd:none dd:none

11.1.3 Configuring Online Targets with ietadm

When changes to the iSCSI target configuration are necessary, you always must restart the target to activate changes that are done in the configuration file. Unfortunately, all active sessions are interrupted in this process. To maintain an undisturbed operation, the changes should be done in the main configuration file /etc/ietd.conf, but also made manually to the current configuration with the administration utility ietadm.

To create a new iSCSI target with a LUN, first update your configuration file. The additional entry could be:

Target iqn.2006-02.com.example.iserv:system2

          Lun 0 Path=/dev/mapper/system-swap2

          IncomingUser joe secret

To set up this configuration manually, proceed as follows:

Create a new target with the  command  ietadm --op new --tid=2 --params Name=iqn.2006-02.com.example.iserv:system2.

Add a logical unit with ietadm --op new --tid=2 --lun=0 --params Path=/dev/mapper/system-swap2.

Set the username and password combination on this target with ietadm --op new --tid=2 --user --params=IncomingUser=joe,Password=secret.

Check the configuration with cat /proc/net/iet/volume.

It is also possible to delete active connections. First, check all active connections with the command cat /proc/net/iet/session. This may look like:

cat /proc/net/iet/session

tid:1 name:iqn.2006-03.com.example.iserv:system

        sid:281474980708864 initiator:iqn.1996-04.com.example:01.82725735af5

                cid:0 ip:192.168.178.72 state:active hd:none dd:none

To delete the session with the session ID 281474980708864, use the command ietadm --op delete --tid=1 --sid=281474980708864 --cid=0. Be aware that this makes the device unaccessible on the client system and processes accessing this device are likely to hang.

ietadm can also be used to change various configuration parameters. Obtain a list of the global variables with ietadm --op show --tid=1 --sid=0. The output looks like:

InitialR2T=Yes

ImmediateData=Yes

MaxConnections=1

MaxRecvDataSegmentLength=8192

MaxXmitDataSegmentLength=8192

MaxBurstLength=262144

FirstBurstLength=65536

DefaultTime2Wait=2

DefaultTime2Retain=20

MaxOutstandingR2T=1

DataPDUInOrder=Yes

DataSequenceInOrder=Yes

ErrorRecoveryLevel=0

HeaderDigest=None

DataDigest=None

OFMarker=No

IFMarker=No

OFMarkInt=Reject

IFMarkInt=Reject

All of these parameters may be changed easily. For example, if you want to change the maximum number of connections to two, use ietadm --op update --tid=1 --params=MaxConnections=2. In the file /etc/ietd.conf, the associated line should look like MaxConnections 2.

WARNING:  Update ietd.conf According to Changes with ietadm

The changes that you make with the command ietadm are not permanent for the system. These changes are lost at the next reboot if they are not added to the configuration file /etc/ietd.conf. Depending on the usage of iSCSI in your network, this may lead to severe problems.

There are several more options available for the command ietadm. Find an overview with ietadm -h. The abbreviations there are target ID (tid), session ID (sid), and connection ID (cid). They can also be found in /proc/net/iet/session.

11.2 Configuring iSCSI Initiator

iSCSI initiator, also called  client , can be used to connect to any iSCSI target. This is not restricted to the iSCSI target solution explained above. The configuration of iSCSI initiator involves two major steps—the discovery of available iSCSI targets and the setup of an iSCSI session. Both can be done with YaST.

11.2.1 Using YaST for the iSCSI Initiator Configuration

The configuration is divided into three tabs. The Service tab may be used to enable the iSCSI initiator at boot time. The Connected Targets tab gives an overview of the currently connected iSCSI targets. Like the Discovered Targets tab, it gives the option to add new targets to the system. Discovered Targets is the tab to start with. It provides the possibility of discovering iSCSI targets in the network.

Use Discovery to open the discovery dialog.

Enter the IP address and change the port if necessary.

If necessary, add the Incoming or Outgoing  authentication .

Use Next to start the discovery.

After a successful discovery, use Login to activate the target. You will be asked for authentication information to use the selected iSCSI target. Next finishes the configuration. If everything went well, the target now appears in Connected Targets.

The virtual iSCSI device is now available. Find the actual device with lsscsi:

lsscsi

[1:0:0:0]   disk    IET      VIRTUAL-DISK     0     /dev/sda

11.2.2 Setting Up the iSCSI Initiator Manually

Both the discovery and the configuration of iSCSI connections require a running iscsid. When running the discovery the first time, the internal database of the iSCSI initiator is created in the directory /var/lib/open-iscsi.

If your discovery is password protected, provide the authentication information to iscsid. Because the internal database does not exist when doing the first discovery, it cannot be used at this time. Instead, the configuration file /etc/iscsid.conf must be edited to provide the information. To add your password information for the discovery, add the following lines to the end of /etc/iscsid.conf:

discovery.sendtargets.auth.authmethod = CHAP

discovery.sendtargets.auth.username = <username>

discovery.sendtargets.auth.password = <password>

The discovery stores all received values in an internal persistent database. In addition, it displays all detected targets. Run this discovery with the  command  iscsiadm -m discovery --type=st --portal=<targetip>. The output should look like:

[bd0ac2] 149.44.171.99:3260,1 iqn.2006-02.com.example.iserv:systems

For each target defined on the iSCSI target, one line appears. In the previous example, the ID of the target is bd0ac2. This ID is used to access the target. Learn how to obtain more information about the stored data in  Section 11.2.3, The iSCSI Client Databases . For now, just modify the authentication credentials in this database to be able to access target bd0ac2. Assume that you access a target with incoming user <username> and password <password>:

iscsiadm -m node --record=bd0ac2 --op=update /

    --name=node.session.auth.authmethod --value=CHAP

iscsiadm -m node --record=bd0ac2 --op=update /

    --name=node.session.auth.username --value=<username>

iscsiadm -m node --record=bd0ac2 --op=update /

    --name=node.session.auth.password --value=<password>

Now, the initiator is prepared for its activation. The special --login option of iscsiadm creates all needed devices:

iscsiadm -m node --record=bd0ac2 --login

The newly generated devices show up in the output of lsscsi and can now be accessed by mount.

11.2.3 The iSCSI Client Databases

All information that was discovered by the iSCSI initiator is stored in two database files that reside in /var/lib/open-iscsi. There is one database for the discovery of targets and one for the discovered nodes. When accessing a database, you first must select if you want to get your data from the discovery or from the node database. Do this with the -m discovery and -m node parameters of iscsiadm. Using iscsiadm just with one of these parameters gives an overview of the stored records:

iscsiadm -m discovery

[bd0ac2] 149.44.171.99:3260,1 iqn.2006-02.com.example.iserv:systems

The record ID in this example is bd0ac2. This ID is needed for all actions that relate to this special data set. To examine the content of the data record with the ID bd0c2, use the following command:

iscsiadm -m node --record=bd0ac2

node.name = iqn.2006-02.com.example.iserv:systems

node.transport_name = tcp

node.tpgt = 1

node.active_conn = 1

node.startup = manual

node.session.initial_cmdsn = 0

node.session.reopen_max = 32

node.session.auth.authmethod = CHAP

node.session.auth.username = joe

node.session.auth.password = ********

node.session.auth.username_in = <empty>

node.session.auth.password_in = <empty>

node.session.timeo.replacement_timeout = 0

node.session.err_timeo.abort_timeout = 10

node.session.err_timeo.reset_timeout = 30

node.session.iscsi.InitialR2T = No

node.session.iscsi.ImmediateData = Yes

....

To edit the value of one of these variables, use the command iscsiadm with the update operation. For example, if you want iscsid to log in to the iSCSI target when it initializes, set the variable node.startup to the value automatic:

iscsiadm -m node --record=bd0ac2 --op=update --name=node.startup --value=automatic

Remove obsolete data sets with the operation delete. If the record bd0ac2 is no longer a valid record, delete this record with the command iscsiadm -m node --record=bd0ac2 --op=delete. Use caution because this deletes the record without any additional confirmation prompt.

11.2.4 For More Information

The iSCSI protocol has been available for several years. There are many reviews and additional documentation comparing iSCSI with SAN solutions, doing performance benchmarks, or just describing hardware solutions. Important pages for more information about open-iscsi are:

http://www.open-iscsi.org/

http://www.open-iscsi.org/cgi-bin/wiki.pl

http://www.novell.com/coolsolutions/appnote/15394.html

There is also some online documentation available. See the manual pages of iscsiadm, iscsid, ietd.conf, and ietd and the example