You know, if a normal person wanted a diskless Debian install, they’d use NFS – a widely supported way to have a root filesystem on a network share and therefore reasonably easy to set-up. I however, wanted to have the root filesystem on iSCSI since it’s a nice, fast way of achieving the same thing. I’m now going to document how I achieved this for those who wish to do the same, but first: if you want an easy solution, use NFS. Seriously. You need to have some experience as a Linux sysadmin, developer and Debian user to make this work.
HERE BE DRAGONS
You’re still reading? OK then, here goes.
The first step is to configure your iSCSI target, which I won’t go into here. You may find my previous post, Playing with iSCSI, helpful. Now grab a copy of the Debian netinst CD image, burn it to CD and boot from it on the machine you want to install on. Note: it’s essential that you have another machine already running the version of Debian that you’re installing.
Using another machine, you now need to get a copy of the open-iscsi sources. You should do this on a Debian system running the same version of Debian, with the same kernel on the same architecture as you are installing. Simply run:
You now need to make some modifications to the open-iscsi source to make it work in the Debian Installer environment (and in initramfs, which we’ll come to later). The changes are minimal, but for convenience I’ve produced a patch:
Change into the directory containing the open-iscsi source, and apply the patch as follows:
Now simply type make to build open-iscsi. This will build the open-iscsi userspace applications and the necessary kernel modules. If you find that open-iscsi refuses to build kernel modules with a complaint like the following:
Then don’t worry – this simply means that you can avoid compiling the modules, and will need to copy them from the running kernel instead.
You now need to copy some files, plus a few modules from the running kernel, to a USB pen-drive. From the open-iscsi directory you need the following (ignore the .ko files if the kernel modules didn’t build):
usr/iscsiadm
kernel/libiscsi.ko
kernel/iscsi_tcp.ko
kernel/scsi_transport_iscsi.ko
Plus the following files from your running kernel:
/lib/modules/`uname -r`/kernel/lib/libcrc32c.ko
If the open-iscsi kernel modules didn’t build before, copy the following too:
/lib/modules/`uname -r`/kernel/drivers/scsi/libiscsi.ko
/lib/modules/`uname -r`/kernel/drivers/scsi/scsi_transport_iscsi.ko
Now on the machine you’re installing on, begin the Debian installation and continue normally until after the stage where the network is configured. Now switch to a console (Alt+F2), insert your USB pen-drive and mount it. Copy the files off it and place them in /tmp.
You now need to create /etc/iscsi/initiatorname.iscsi with content like the following:
The actual name isn’t important, just make something up (as long as it’s in the above format).
Now remove your USB pen-drive (important!) and run the following commands to get iSCSI going:
insmod /tmp/scsi_transport_iscsi.ko
insmod /tmp/iscsi-tcp.ko
insmod /tmp/libcrc32c.ko
insmod /tmp/crc32c.ko
/tmp/iscsid
/tmp/iscsiadm -m discovery -t sendtargets -p <iscsi target ip address>:<port>
/tmp/iscsiadm -m node -L all
That will load all the required modules, discover your target and then connect to it. All being well, it will appear as a SCSI disk (check dmesg). Now you can continue the install normally. At the final stage of the install DON’T allow the system to reboot – the installed system can’t boot yet.
I decided that I wanted to boot using BOOTP and TFTP. You might want to boot from USB, a flash card or something else, in which case you’re on your own – I’m going to document how to boot using BOOP and TFTP. On your iSCSI target machine (or any machine, actually) configure the required daemons and drop in the Debian netboot files – you may wish to use Preparing Files for TFTP Net Booting as a guide.
Now that your installation is finished, you need to copy some files off the installed system to your pen drive. You need the initramfs and the kernel from /mnt/target/boot/ directory, named initrd.img-<kernelversion> and ‘vmlinuz-<kernelversion>. You also need the entire /etc/iscsi directory.
Now copy the files onto the machine you configured as your TFTP server, and put the kernel image into your tftp directory (probably /tftpboot). You now need to modify the initramfs image to add the iSCSI bits.
First, decompress the initramfs image into an empty directory:
Now, you need to copy in the contents of the pen drive to the right places. Copy the /etc/iscsi directory from the pen drive to etc/ in the directory containing the decompressed initramfs image. Also copy the iscsid binary to sbin/, and the iscsiadm binary to bin/.
Now you need to add the following to the end of scripts/init-premount/udev (we need to add it to one of the scripts run at the start of the boot process, and this is as good a place as any):
/sbin/iscsid -f &
/bin/iscsiadm -m node -L all
You also need to copy in the kernel modules, into the correct paths:
lib/modules/<kernelversion>/kernel/lib/libcrc32c.ko
lib/modules/<kernelversion>/kernel/drivers/scsi/iscsi_tcp.ko
lib/modules/<kernelversion>/kernel/drivers/scsi/libiscsi.ko
lib/modules/<kernelversion>/kernel/drivers/scsi/scsi_transport_iscsi.ko
And finally, you need to edit the init script to reference the root partition, e.g:
Now re-create the initramfs image by running the following in the root of the directory in which you decompressed the image, and save it to your tftp directory:
That’s it. Ensure your TFTP server is fully configured, modify the PXE configuration to point to your kernel and initramfs image, then you can restart your system and hopefully you’ll get root on iSCSI…
