====== ISCSI ======

===== Overview =====
===== Server =====
==== Installation ====
The following kernel options are required:
{{Kernel|2.6.29-gentoo-r1|<code>0@@</code>}}

Now install the iSCSI Enterprise Target packages:
  * {{Package|direct=yes|sys-block/iscsitarget}}

Load the necessary modules, and make sure they are automatically loaded on boot:
{{Root|<source lang="bash">
modprobe crc32c
modprobe iscsi_trgt
</source>}}
{{File|/etc/conf.d/modules|<syntax lang="sh">
modules_2_6="${modules_2_6} crc32c iscsi_trgt"
module_crc32c_2_6=""
module_iscsi_trgt_2_6=""
</syntax>}}

==== Configuration ====
Create an LVM partition to share, for example, a 10Gb partition named <tt>data</tt> from the <tt>pool</tt> volume group. This partition will not be mounted on the local machine.
{{Root|<source lang="bash">
lvcreate -L10G -n data pool
</source>}}

Edit <tt>ietd.conf</tt> to mark this partition as an iSCSI target. The target specification contains the date the domain was registered in YYYY-MM format, followed by the hostname of the server, and finally an identifier. In this case, we've used the convention <tt>//vgname//.//lvname//</tt> for the target identifier.
{{File|/etc/ietd.conf|<syntax lang="conf">
Target iqn.2006-06.net.sihnon.jellybean.badger:pool.saffron
    Lun 0 Path=/dev/mapper/pool-saffron
</syntax>}}

Now start <tt>ietd</tt> and ensure it auto-starts on boot.
{{Root|<source lang="bash">
/etc/init.d/ietd start
rc-update add ietd default
</source>}}

===== Client =====
==== Installation ====
We will be using <tt>open-iscsi</tt> to attach the iscsi targets on the clients. This is fussy about certain iscsi kernel options being built as modules, so ensure that the following options are modules and not built in directly.
{{Kernel|2.6.29-gentoo-r1|<code>1@@</code>}}

Install the client software:
  * {{Package|direct=yes|sys-block/open-iscsi}}

==== Configuration ====
Configure the targets, and have them loaded automatically:
{{File|/etc/iscsid/initiatorname.iscsi|<syntax lang="conf">
InitiatorName=iqn.2006-06.net.sihnon.jellybean.badger:pool.saffron
</syntax>}}
{{File|/etc/iscsid/iscsid.conf|<syntax lang="conf">
  - node.startup = manual
node.startup = automatic
</syntax>}}

Configure the networking for open-iscsi. Find the MAC address for the network interface you'd like to use using <tt>ifconfig</tt> or similar, and then run the following commands.
{{Root|<source lang="bash">
iscsiadm -m iface -I iface0 --op=new
iscsiadm -m iface -I iface0 --op=update -n iface.hwaddress -v AA:BB:CC:DD:EE:FF
</source>}}

Now start iscsid, and have it autostart on boot.
{{Root|<source lang="bash">
/etc/init.d/iscsid start
rc-update add iscsid default
</source>}}

When iscsi targets are attached, a corresponding block device will be created in <tt>/dev</tt>, for example <tt>/dev/sdb</tt>. If the device contains a partition table, the corresponding partition nodes will be created as well. As this is a new target, we will need to create the partition table now, and format the partitions with a filesystem. Create a single partition the full size of the device, and format it with an <tt>ext3</tt> filesystem.
{{Root|<source lang="bash">
fdisk /dev/sdb
mke2fs -j /dev/sdb1
</source>}}

=== Renaming targets ===
The device node that's created for a particular iscsi target is volatile, and depends on the state of the system when the target is first attached. We can use <tt>udev</tt> to stabilise this situation, with a bit of black magic. Create the following script, and then configure udev to exectute the script to determine a suitable symlink for the newly attached target.
{{File|/lib/udev/iscsi_tgt.sh|<source lang="bash">
#!/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
</source>}}
{{File|/etc/udev/rules.d/10-iscsi.rules|<syntax lang="udevrules">
BUS=="scsi", SYSFS{vendor}=="IET", SYSFS{model}=="VIRTUAL-DISK", KERNEL=="sd*", NAME="%k", PROGRAM="/lib/udev/iscsi_tgt.sh $id", SYMLINK+="iscsi/%c%n"
</syntax>}}

Now that devices nodes are accessible at known locations, we can add an entry to fstab to make the partition mountable. The entry //must// have the <tt>noauto</tt> option set, as the device will not exist at boot time, and cannot be mounted until after <tt>iscsid</tt> has started and the target has been attached.
{{File|/etc/fstab|<syntax lang="fstab">
/dev/iscsi/iqn.2006-06.net.sihnon.jellybean.badger:pool.saffron:lun0:1  /mnt/badger/saffron ext3    acl,noatime,noauto    0 0
</syntax>}}

=== Automatically mounting volumes ===
If we want to automatically mount these filesystems after iscsid has started, we will need to use a custom init script as there does not appear to be any exiting way to do this. Add the following scripts. The latest version of the init script is held in subversion, under [[https://dev.sihnon.net/svn/configs/iscsi/|configs:/iscsi/]].
{{File|/etc/conf.d/iscsi-volumes|<syntax lang="sh">
  - List of volumes to mount

VOLUMES=(
    "/dev/iscsi/iqn.2006-06.net.sihnon.jellybean.badger:pool.saffron:lun0:1"
)

  - Amount of time to sleep before mounting volumes, so that iscsid has time to
  - create any device nodes after connecting.

SLEEP="2"
</syntax>}}
{{File|/etc/init.d/iscsi-volumes|<syntax lang="sh">
#!/sbin/runscript
  - Copyright 1999-2009 Gentoo Foundation
  - Distributed under the terms of the GNU General Public License v2
  - $Header: $

depend() {
    need iscsid
}

start() {
    STATUS=0
    ebegin "Automounting iscsi volumes"
    eindent

    einfo "Sleeping for ${SLEEP} seconds to allow device nodes to be created"
    sleep ${SLEEP}

    for v in ${VOLUMES[[@]]}; do
        RESULT=`mount $v`
        if [[|$? ]]; then
            einfo "Mounted $v"
        else
            ewarn "Failed to mount $v: $RESULT"
            STATUS=1
        fi
    done

    eoutdent
    eend $STATUS
}

stop() {
    ebegin "Unmounting automounted iscsi volumes"
    eindent

    for v in ${VOLUMES[[@]]}; do
        RESULT=`umount $v`
        if [[|$? ]]; then
            einfo "Unmounted $v"
        else
            ewarn "Failed to unmount $v: $RESULT"
        fi
    done

    eoutdent
    eend 0
}
</syntax>}}

Finally, add the <tt>iscsi-volumes</tt> script to start on boot, then restart iscsid to have the volume properly mounted.
{{Root|<source lang="bash">
/etc/init.d/iscsid restart
/etc/init.d/iscsi-volumes start
rc-update add iscsi-volumes default
</source>}}

===== See Also =====
  * [[ISCSI Enterprise Target]] - Guide to installing IET on ubuntu, and sharing a virtual disk to a windows machine.
  * http://en.gentoo-wiki.com/wiki/ISCSI - Original article on which this is based.