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

12.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 8.5.7, Using the YaST 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. If a iSNS server should manage the discovery and access control, activate iSNS Access Control and enter the IP address of your iSNS Server. Note, that you cannot use even valid hostnames, but must use the IP address. For more about iSNS, read Section 13.0, iSNS for Linux Overview.

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. To do this, select a target in the Targets tab then click Edit. There, add new LUNs to an existing target.

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.

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

If you have access to an iSNS server, the first thing to configure is telling the target about this server. Note, that the address of the iSNS server must always be given as IP address. A normal domain name is not sufficient. The configuration for this functionality looks like the following:

iSNSServer 192.168.1.111
iSNSAccessControl no

This configuration makes the iSCSI target register itself with the iSNS server, which in turn provides the discovery for initiators. For more about iSNS read Section 13.0, iSNS for Linux Overview. Note that the access control for the iSNS discovery is not supported. Just keep iSNSAccessControl no.

All direct 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 7.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 rcopen-iscsi 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

12.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:

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

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

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

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