Gentoo Wiki



What is 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[1], 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[2] (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:

iSCSI target installation

Make sure your kernel is ready to run iscsi

Linux Kernel Configuration: make menuconfig
Cryptographic options  --->
 [*] Cryptographic API
 <M>   CRC32c CRC algorithm
echo "crc32c" >> /etc/modules.autoload.d/kernel-2.6

Unmask iscsitarget

echo "sys-block/iscsitarget" >> /etc/portage/package.keywords

Install iscsitarget

emerge iscsitarget

add iscsi_trgt to the modules autoload (if you want it to start at boot)

echo "iscsi_trgt" >> /etc/modules.autoload.d/kernel-2.6

create /etc/ietd.conf

#The part before the colon is a name standard for iscsi with your domain of course. After is your descriptive text 
        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"

to allow Ethernet card transmit Jumbo Frames run ifconfig eth0 mtu 9000 up or add following line into /etc/conf.d/net:


to start the server start the init

/etc/init.d/ietd start

Note: If ietd fails to start and you have the following in /var/log/messages:

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

you might have to edit /etc/conf.d/ietd and specify the IP address of your machine manually in the file such as (even though the ietd manpage specifies that it listens to "any" address):


iSCSI initiator (client)

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


Make sure you have following options compiled into your kernel

Linux Kernel Configuration: make menuconfig
 Device Drivers  --->
   SCSI device support  --->
     [*] SCSI device support
       <*> SCSI disk support
 Cryptographic options  --->
   [*] Cryptographic API
     <M> CRC32c CRC algorithm

iSCSI initiator package is currently masked in portage. To install the package you have to type:

echo sys-block/open-iscsi >> /etc/portage/package.keywords
emerge sys-block/open-iscsi

Set initiator name and alias

File: /etc/initiatorname.iscsi

NOTE: The following issue appears to have been resolved in recent ebuilds. intiatorname.iscsi is now installed in /etc/iscsi by default.

For some unknown reason emerge installs initiatorname.iscsi into /etc though iscsid looks for the file in /etc/iscsi. To create directory and make symlink run following commands
mkdir /etc/iscsi
cd /etc/iscsi
ln -s ../initiatorname.iscsi initiatorname.iscsi

Now you can start iscsid with /etc/init.d/iscsid start

Before attaching iSCSI targets we must tell iscsid what interface in the system should be used. Run ifconfig and obtain MAC address of Ethernet card you wish to use. Please note that Open iSCSI does not set IP address on the interface... you have to do it by ifconfig or /etc/conf.d/net. Let's say eth1 MAC address is AA:BB:CC:DD:EE:FF so you will run:

iscsiadm -m iface -I iface0 --op=new
iscsiadm -m iface -I iface0 --op=update -n iface.hwaddress -v AA:BB:CC:DD:EE:FF

Also allow Ethernet card to transmit Jumbo Frames... run ifconfig eth1 mtu 9000 up or add following line into net configuration:

File: /etc/conf.d/net

To discover targets exported by target with IP address run following command:

iscsiadm -m discovery -t st -p -P 1

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

iscsiadm -m node -T -l

fdisk -l

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

iscsiadm -m node -T -u

In case you do not specify target (-T iqn...) all discovered targets will be attached or disconnected.

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.

File: /etc/udev/rules.d/10-iscsi.rules
BUS=="scsi", SYSFS{vendor}=="IET", SYSFS{model}=="VIRTUAL-DISK", KERNEL=="sd*", NAME="%k", PROGRAM="/lib/udev/ $id", SYMLINK+="iscsi/%c%n"
File: /lib/udev/
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

To get your machine to automatically attach to targets

File: /etc/init.d/iscsid
# Copyright 1999-2005 Gentoo Technologies, Inc.
# Distributed under the terms of the GNU General Public License, v2 or later
# $Header: /var/cvsroot/gentoo-x86/sys-block/open-iscsi/files/iscsid-init.d,v 1.4 2006/03/07 08:26:46 robbat2 Exp $

NAME="iSCSI initiator service"

depend() {
        after modules
        use net

checkconfig() {
        if [ ! -f $CONFIG_FILE ]; then
                eerror "Config file $CONFIG_FILE does not exist!"
                return 1
        if [ ! -f $INITIATORNAME -o -z "$(egrep '^InitiatorName=' "${INITIATORNAME}")" ]; then
                eerror "$INITIATORNAME should contain a string with your initiatior name, eg:"
                eerror "InitiatorName=iqn.2005-09.tld.domainname.hostname:initiator-name"
                eerror "Initiator name file does not exist!"
                return 1

do_modules() {
        for m in ${modules}; do
                ebegin "${msg} - ${m}"
                modprobe ${opts} $m
                eend $ret
                [ $ret -ne 0 ] && return $ret
        return 0

iscsi_login_all_nodes() {
        ebegin "Setting up iSCSI targets: "
        iscsiadm -m node --loginall=automatic
        eend $?

iscsi_logout_all_nodes() {
        ebegin "Deactivating iSCSI targets: "
        # Logout from all active sessions
        iscsiadm -m node --logoutall=all
                eend $ret
        return $ret

start() {
        checkconfig || return 1
        do_modules 'Loading iSCSI modules' 'scsi_transport_iscsi iscsi_tcp'
        [ $ret -ne 0 ] && return 1
        ebegin "Starting ${NAME}"
        start-stop-daemon --start --exec $DAEMON --quiet
        eend $ret
        if [ "$ret" == "0" ]; then
        return $ret

stop() {
        iscsi_logout_all_nodes || return 1
        ebegin "Stopping ${NAME}"
        start-stop-daemon --signal HUP --stop --quiet --exec $DAEMON #--pidfile $PID_FILE
        eend $?

        # ugly, but pid file is not removed by iscsid
        rm -f $PID_FILE

        do_modules 'Removing iSCSI modules' 'iscsi_tcp scsi_transport_iscsi' '-r'
        return $ret

opts="${opts} dump"

dump() {
        einfo "Starting dump of iscsid database (nodes)"
        NODELIST="$(iscsiadm -m node |  awk -F '[\\[\\]]' '{print $2}')"
        [ -f ${DUMP_NODE} ] && mv -f ${DUMP_NODE} ${DUMP_NODE}.old
        for i in $NODELIST ; do
                echo "# $(iscsiadm -m node | egrep "^\[$i\]")" >>${DUMP_NODE}
                iscsiadm -m node --record=$i >>${DUMP_NODE}
                echo >>${DUMP_NODE}
        einfo "Starting dump of iscsid database (discovery)"
        DISCOVERYLIST="$(iscsiadm -m discovery |  awk -F '[\\[\\]]' '{print $2}')"
        [ -f ${DUMP_DISCOVERY} ] && mv -f ${DUMP_DISCOVERY} ${DUMP_DISCOVERY}.old
        for i in $DISCOVERYLIST ; do
                echo "# $(iscsiadm -m discovery | egrep "^\[$i\]")" >>${DUMP_DISCOVERY}
                iscsiadm -m discovery --record=$i >>${DUMP_DISCOVERY}
                echo >>${DUMP_DISCOVERY}

        einfo "Config dumped to ${DUMP_DIR}/"


Download and install Microsoft iSCSI Software Initiator Found here!
Configure the Windows Cilent
General Tab

Discovery Tab

Targets Tab

Under disk management (Right Click on "My Computer"->manage->Disk Management) you should see your new scsi hard drive. Just format and your on your way!


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.


(This wiki page is a modified and augemented version of:

Retrieved from ""

Last modified: Wed, 01 Oct 2008 11:15:00 +0000 Hits: 21,783