Debian etch

Preparing an existing installation for iSCSI

This howto is based on the following assumptions:

  • a base debian etch with all the security updates
  • the system is installed on a single partition “/” on /dev/sda1
  • there is an already done iscsi target on an iscsi server
  • there is a working dhcp server

Compile iscsistart and fwparam_ibft

Since two fundamental tools from open-iscsi are not included in the debian package, they have to be compiled from the sources with the following steps (i have used a different machine for all the compilation stuff).

Install the appropriate devel packages:

 apt-get build-dep open-iscsi
 apt-get install libdb4.3-dev

Download the sources and compile them:

 wget (this is the latest tarball at this time)
 tar xzf open-iscsi-2.0-865.13.tar.gz
 cd open-iscsi-2.0-865.13
 make -C usr
 make -C utils/fwparam_ibft

The two files needed are usr/iscsistart and utils/fwparam_ibft/fwparam_ibft so they have to be copied in /usr/sbin.

Install the needed packages

 apt-get install iproute

Disable networking scripts

The file /etc/network/interfaces must contain only the information needed to setup the loopback adapter or some additional network cards not used in the iSCSI boot process. If you have only one interface (in example eth0), be sure to have a stanza like this in /etc/network/interfaces

auto eth0
iface eth0 inet manual

So ifupdown will report the network card as “up”, otherwise some script will not work well (in exemple the nfs mount).

Create the initramfs scripts

Create two scripts shown below. These scripts have to be executable.

  • /etc/initramfs-tools/hooks/iscsi_tcp will copy the iscsi_tcp, ib_iser kernel modules followed by their dependancies, /usr/sbin/iscsistart and /usr/sbin/fwparam_ibft to the initial ramdisk.
  • /etc/initramfs-tools/scripts/local-top/iscsi_tcp is copied to the ram disk and run at boot-time, just before the root filesystem is mounted. If the root device string looks like a SCSI device it brings up the appropriate Ethernet device, sets up the ip address passed through dhcp and connects the root file system on the iSCSI target.

After you have made sure that /etc/initramfs-tools/initramfs.conf contains the line


you can update the initial ramdisk:

 dpkg-reconfigure linux-image-$(uname -r)

If the modifications were applied to a physical disk on the client machine, you can now transfer the contents of your physical disk to the SAN target.

If the image you wish to export to client systems was modified directly,, you can now make the contents of that image available via iSCSI.


  • If the system hangs before the root device has been mounted, passing break=mount on the command line will spawn a shell before scripts/local-top/iscsi_tcp is run. This should allow for further debugging.



set  -e
        echo "$PREREQ"
case $1 in
        exit 0
. /usr/share/initramfs-tools/hook-functions
[ -x /usr/sbin/iscsistart ] && copy_exec /usr/sbin/iscsistart /sbin
[ -x /usr/sbin/fwparam_ibft ] && copy_exec /usr/sbin/fwparam_ibft /sbin
[ -x /sbin/ip ] && copy_exec /sbin/ip /sbin
manual_add_modules iscsi_tcp
manual_add_modules ib_iser


set -e
        echo "$PREREQ"
case $1 in
        exit 0
case $ROOT in
        # Evaluate IBFT parameters
        for i in $(fwparam_ibft -b); do export $i; done
        #Bring up the interface used to boot
        for i in $(ls /sys/class/net); do
                IFADDR=$(cat /sys/class/net/$i/address)
                if [ $IFADDR = $iSCSI_INITIATOR_HWADDR ]; then
                        echo "Using $i with MAC $IFADDR"
                        export iSCSI_INITIATOR_IF=$i
        modprobe -q iscsi_tcp
        modprobe -q ib_iser
        echo "Bringing up $iSCSI_INITIATOR_IF for iSCSI..."
        ip link set $iSCSI_INITIATOR_IF up
        echo "Setting up networking on $iSCSI_INITIATOR_IF..."
        ip route add default via $iSCSI_INITIATOR_GATEWAY
        echo "Connecting to iSCSI target $iSCSI_TARGET_NAME on $iSCSI_TARGET_IPADDR..."
        iscsistart -i $iSCSI_INITIATOR_NAME -t $iSCSI_TARGET_NAME -g 1 -a $iSCSI_TARGET_IPADDR
        sleep 5

Using gPXE to boot over iSCSI

Since my network cards don't support booting via iSCSI, I've used the great gPXE, loading it after a “standard” PXE request. This is called PXE Chainloading

A separate stanza containing the right root-path option should be created for each host in /etc/dhcp3/dhcpd.conf, like in the example.

host iscsi-test {
                hardware ethernet 00:0C:29:5C:53:C2;
                filename "";
                option root-path "";

QR Code
QR Code sanboot:debian_etch_iscsi (generated for current page)