ISCSI

iSCSI is a protocol that uses the TCP/IP stack to transport scsi calls over a network, it uses "Initiators" on the client to connect to the "Targets" (data server). The purpose of iSCSI is to use existing Gigabit Ethernet networks to make SANs, reducing the costs of implementation compared to fibre-channel or other I/O protocol. This is actually possible by the large adoption and low cost of Gigabit Ethernet in comparison with another protocols like Infiniband and Fibre-Channel. When choosing Ethernet switches and NICs for iSCSI make sure they support Jumbo Frames (MTU 9000). It uses a method called "Discovery" once you input the IP of the server in the initiator it looks for all the targets on that server. It treats these targets as block devices that you can appear as local disks. You can then have your way with it! The local server will still be read as a raw disk.

iSCSI uses IQN (iSCSI qualified name) for target and initiator identification. IQN format is specified by IETF RFC 3721. For example: iqn.2001-04.org.gentoo:iSCSI.test.disk1

• iqn - type (always "iqn")
• 2001-01 - year and month on which the domain has been registered
• org.gentoo - reversed domain (naming authority)
• iSCSI.test.disk1 - unique identifier (i.e. hostname and disk for targets)

[edit] Configuring iSCSI target (server)

[edit] Kernel Configuration

Make sure your kernel is ready to run iSCSI, activate the following options:

Cryptographic options  --->
 [*] Cryptographic API
 <*>   CRC32c CRC algorithm

[edit] Emerging iSCSI-target

Emerge iSCSI-target:

And then add the iscsi_trgt to the modules autoload (if you want to start it at boot time):

[edit] Configuration for the iSCSI-target

Create the configuration file for the iSCSI-target /etc/ietd.conf.

#The part before the colon is a name standard for iscsi with your domain of course. After is your descriptive text 
Target iqn.2001-04.org.gentoo:iSCSI.test.disk1
        Lun 0 Path=/dev/hda5,Type=fileio
        MaxConnections          1
        #InitialR2T              Yes
        #ImmediateData           No
        #MaxRecvDataSegmentLength 8192
        #MaxXmitDataSegmentLength 8192
        #MaxBurstLength          262144
        #FirstBurstLength        65536
        #DataPDUInOrder          Yes
        #DataSequenceInOrder     Yes
        #ErrorRecoveryLevel      0
        #HeaderDigest            CRC32C
        #DataDigest              CRC32C
        #Wthreads                8

#You can have multiple targets in the conf file. The different settings are optional and you can read about them in "man ietd.conf"

In order to allow an Ethernet card transmit Jumbo Frames run

or add the following line to /etc/conf.d/net:

mtu_eth0="9000"

where eth0 is the network device you want to use to expose the iSCSI target over. Note that not all NIC support 9000 as a value for MTU. Work your way down by 1000 to find a value that works, then work up to find the maximum. To start the server, start the init:

Feb 14 03:46:26 GentooNAS ietd: unable to create server socket (Address family not supported by protocol) 10 1 6!

ADDRESS="192.168.1.100"

[edit] Configuring the iSCSI initiator (client)

Connect to the target with a iSCSI initiator from a different machine on the network.

[edit] Kernel Configuration

Make sure you have the following options:

Device Drivers  --->
  SCSI device support  --->
    [*] SCSI device support
      <*> SCSI disk support
    SCSI Transports --->
      {M} iSCSI Transports Attributes
    [*] SCSI low-level drivers --->
      <M> iSCSI Initiator over TCP/IP
Cryptographic options  --->
  [*] Cryptographic API
    <*> CRC32c CRC algorithm

[...]
#
# SCSI Transports
#
CONFIG_SCSI_SPI_ATTRS=y
# CONFIG_SCSI_FC_ATTRS is not set
CONFIG_SCSI_ISCSI_ATTRS=m
# CONFIG_SCSI_SAS_ATTRS is not set
# CONFIG_SCSI_SAS_LIBSAS is not set
# CONFIG_SCSI_SRP_ATTRS is not set
CONFIG_SCSI_LOWLEVEL=y
CONFIG_ISCSI_TCP=m
[...]

[edit] Emerging iSCSI initiator

The iSCSI initiator package may be masked in portage. If so, add it to the keywords list first.

Then emerge it.

[edit] Configuration for the iSCSI initiator

Set the initiator name and alias in /etc/iscsi/initiatorname.iscsi.

InitiatorName=iqn.2001-04.org.gentoo:initiator-test
InitiatorAlias=initiator-test

Now you can start the iscsid with:

Before attaching iSCSI targets we must tell iscsid what interface in the system should be used. The interface is specified by the MAC address and can be obtained by running:

Please note that iSCSI does not set an IP address on the interface... you have to do it by running ifconfig or through /etc/conf.d/net. Let us assume that eth1 MAC address is AA:BB:CC:DD:EE:FF, and we want to use this interface, we type:

mtu_eth1="9000"

Note that not all NIC support 9000 as a value for MTU. Work your way down by 1000 to find a value that works, then work up to find the maximum.

To discover targets exported by the iSCSI-target with IP address 192.168.1.100 run the following command:

Finally you can attach some of the exported targets with and display partitions on them:

To disconnect the target from the system type the following (after you unmount it :)

[edit] udev creating useful symlinks

If you need consistent device naming for your iSCSI targets then you can use udev rules to generate these. The following example will create a /dev/iscsi/iqn... link to the device allocated by the kernel.

BUS=="scsi", SYSFS{vendor}=="IET", SYSFS{model}=="VIRTUAL-DISK", KERNEL=="sd*", NAME="%k", PROGRAM="/lib/udev/iscsi_tgt.sh $id", SYMLINK+="iscsi/%c%n"

#!/bin/bash
DEV=`echo $1 | /bin/awk -F":" '{print $1":"$2":"$3}'`
LUN=`echo $1 | /bin/awk -F":" '{print $NF}'`

for i in /sys/class/iscsi_session/session* ; do
        test -d "${i}/device/target${DEV}/${DEV}:${LUN}" && echo `/bin/cat ${i}/targetname`:lun${LUN}: && exit 0
done

This will create a devicenode for every LUN you defined in the schema "/dev/iscsi/<TARGETNAME>/<SCSI_SERIAL_NAME>[-partX]" or if you did not specify a ScsiSN in the schema "/dev/iscsi/<TARGETNAME>/lunX[-partX]". Define the serial name in your ietd.conf. This will lead to no /dev/sda or something, beware!

SUBSYSTEM=="block", ATTRS{vendor}=="IET*", ATTRS{model}=="VIRTUAL-DISK*", PROGRAM="/etc/udev/scripts/iscsidev.sh %b %n", NAME="iscsi/%c"

This script will generate the appropriate device name. Don't forget to make it executable!

#!/bin/sh

# FILE: /etc/udev/scripts/iscsidev.sh

BUS=${1}
HOST=${BUS%%:*}
PART=${2}

#if the iscsi_host doesn't exist, this is no iscsi-node to be looked at ;) 
[ -e /sys/class/iscsi_host ] || exit 1

#getting the name of our iscsi target host
file="/sys/class/iscsi_host/host${HOST}/device/session*/iscsi_session/session*/targetname"
target_name=$(cat ${file})

# This is not an open-scsi drive
if [ -z "${target_name}" ]; then
   exit 1
fi

# Check if QNAP drive
check_qnap_target_name=${target_name%%:*}
if [ $check_qnap_target_name = "iqn.2004-04.com.qnap" ]; then
    target_name=`echo "${target_name%.*}"`
fi

#if there is no ID_SCSI_SERIAL (not set on target host), take the lun-x part from the ID_PATH instead
NAME=${ID_SCSI_SERIAL}
if [ -z "${NAME}" ]; then
    NAME=${ID_PATH}
    NAME="lun${NAME##*lun-}"
fi

#if this device is a subdevice (e.g. part-X), add this to the name in any case
if [ ! -z "${PART}" ]; then
    NAME="$NAME-part${PART}"
fi

echo "${target_name##*.}/${NAME}"

[edit] Iscsi targets autologin / Autostart

Find your target:

Login to your target:

Register your target to autostart:

Test:

[edit] Windows Client

You can also use a windows machine as an iSCSI initiator, of which the software is found here.

• General Tab
  • Change -> Choose a name for your initiator
• Discovery Tab
  • Add -> Enter the ip address for your target
• Targets Tab
  • Log On -> Choose "Automatically restore this connection when the system boots"

Under disk management (Right Click on "My Computer" -> Manage -> Disk Management) you should see your new SCSI hard drive.

[edit] Authentication

This is a basic setup with no authentication. CHAP is the name of the Authentication used in iSCSI read more about that in the ietd.conf manual.

[edit] Credits

(This wiki page is a modified and augemented version of: http://forums.gentoo.org/viewtopic-t-469920.html)

[edit] References

• http://en.wikipedia.org/wiki/Storage_Area_Network
• http://en.wikipedia.org/wiki/Jumbo_Frames
• http://tools.ietf.org/html/rfc3721
• http://www.open-iscsi.org/docs/README