Network Boot - iSCSI

HOWTO iSCSI boot Openelec

If you have any questions/corrections/contributions about this howto, you're welcome on the following openelec forum topic : http://openelec.tv/forum/12-guides-tips-and-tricks/7636-iscsi-on-boot-support

= Introduction = Warning : « playing » with iSCSI requires some basic knowledge on UNIX/Linux systems and networks. If you have never heard of iSCSI before, or don't really know what it is, chances are that you don't really want to use it.

Goals :


 * Having a diskless (noiseless) HTPC : no drive, so less noise (even SSD can make the device louder, because it will make the whole device warmer, and the fans – if you have fans – will make more noise).
 * On a Gb Ethernet network, iSCSI should be faster than any USB device.
 * To host everything on your lovely network storage device (for your medias, I do not recommend to store them on an iSCSI target, NFS or CIFS shares are far better options in order to share them between several clients).
 * Having some nerdy fun !

What do you need ? :


 * an iSCSI target : it could be an end-user NAS(*) device (Synology, Qnap, Drobo... offers iSCSI on every devices they sell, even the end-user ones, Netgear offers iSCSI on enterprise class models), an home-made server using FreeNAS, OpenFiler, or any GNU/Linux distribution. Windows Server editions probably propose it too, but I have no real knowledge about it (if you do, don't hesitate to contribute to this HowTo !).
 * A little knowledge on how to configure your iSCSI target (creating LUNs, targets, etc.), as it will not be covered in this HowTo.
 * A DHCP/TFTP server or an SD card (or an USB device).
 * An iSCSI initiator capable OS in order to make the initial configuration (it could be the iSCSI target if it is GNU/Linux box). This HowTo will concentrate on Linux Systems. I will call this system the « building system ».

(*) Yeah, iSCSI is more a SAN related technology, but NAS devices nowadays offers it too, and I don't want to speak of them as SAN devices:)

Some questions you need to ask yourself before starting :


 * Do I really need to do that ? Of course not ! But you could, so you should, you know that !
 * Why not using a traditionnal PXE + NFS boot ? You can do that, yes, the goals are exactly the sames. The difference is that NFS is file-oriented, iSCSI is block-oriented. Using iSCSI, you will have access to a standard block device (/dev/sdX), as if it was a local disk, which you could find easier (or not) to use than NFS. ISCSI should be a little faster than NFS, cause there is far less overhead (no lock controls, no FS code on the target side...)
 * Why not using PXE + NBD boot ? You can use that too, yes, the goals are still the sames. But NBD is not an adopted standard, it only exists on UNIX/Linux systems, and you probably won't find it on any commercial NAS/SAN devices...

Ok, so here are the steps :


 * 1) Create the LUN/target on the iSCSI target side
 * 2) Install an iSCSI-aware Openelec system on the iSCSI LUN.
 * 3) Make the HTPC boot on SAN (that will be the more technical/fun part)

= Create the LUN/target on the iSCSI target side = This part is really dependent on your iSCSI target device, so it can't be covered in this HowTo (but contributions are welcome).

The LUN that you create will be used to store the Openelec System and Storage partitions, so size it as you want/need (4GB should be enough for starting, and there are chance that your iSCSI system allows you to resize your LUNs later – that's one good reason to use iSCSI, but you can give your system more or less space if you want).

Note somewhere the information that you will need later :


 * iSCSI target IP address (in my exemple : 192.168.1.14)
 * The target Name (IQN) (in my exemple : iqn.2000-01.com.synology:pandora.openelec)
 * If you have enabled the CHAP authentication : username and password
 * If you have enabled the reverse CHAP authentication : username_in and password_in

Note : Depending on your iSCSI system, you could have to add authorizations (or LUN masquing) for your initiators (your building system and your HTPC).

= Install an iSCSI-aware Openelec system on the iSCSI LUN =

Accessing the LUN
So, your LUN is created, now you have to access it from your building system.

First you need to have iscsi support :

# aptitude install open-iscsi

Now you have to discover your iscsi portal :

# iscsiadm -m discovery -t st -p 192.168.1.14

That should list the available targets. In my exemple :

192.168.1.14:3260,0 iqn.2000-01.com.synology:pandora.openelec

It should have created a config file in /etc/iscsi/nodes/iqn.2000-01.com.synology\:pandora.openelec/192.168.1.14\,3260\,0/default

If you have configured CHAP authentication (and reverse CHAP), you should edit this file (adapt the path to your needs) and add :

node.session.auth.authmethod = CHAP node.session.auth.username = username node.session.auth.password = password node.session.auth.username_in = username_in node.session.auth.password_in = password_in

And finaly, login into the target :


 * 1) iscsiadm -m node -T iqn.2000-01.com.synology:pandora.openelec -p 192.168.1.14:3260 -l

If you have some errors like :

Logging in to [iface: default, target: iqn.2000-01.com.synology:pandora.openelec, portal: 192.168.1.14,3260] iscsiadm: Could not login to [iface: default, target: iqn.2000-01.com.synology:pandora.openelec, portal: 192.168.1.14,3260]. iscsiadm: initiator reported error (19 - encountered non-retryable iSCSI login failure)

Then, you should review your authentication configuration.

If everything went fine, you should see some logs on the terminal :

Logging in to [iface: default, target: iqn.2000-01.com.synology:pandora.openelec, portal: 192.168.1.14,3260] Login to [iface: default, target: iqn.2000-01.com.synology:pandora.openelec, portal: 192.168.1.14,3260] successful.

Cool, now you have a new block device on your system. To know which one it is :

[ 9648.232779] scsi4 : iSCSI Initiator over TCP/IP [ 9649.246417] scsi 4:0:0:0: Direct-Access   SYNOLOGY iSCSI Storage    3.1  PQ: 0 ANSI: 5 [ 9649.247062] sd 4:0:0:0: [sdc] 16777216 512-byte logical blocks: (8.58 GB/8.00 GiB) [ 9649.248907] sd 4:0:0:0: [sdc] Write Protect is off [ 9649.248915] sd 4:0:0:0: [sdc] Mode Sense: 3b 00 00 00 [ 9649.249371] sd 4:0:0:0: [sdc] Write cache: disabled, read cache: enabled, doesn't support DPO or FUA [ 9649.251819] sdc: sdc1 sdc2 [ 9649.253767] sd 4:0:0:0: [sdc] Attached SCSI disk
 * 1) dmesg | tail -n 8

So for me it's /dev/sdc (there are already partitions on it, with a brand new LUN, that should of course not be the case). Remember what device it is for the next step (I will use /dev/sdX to refer to it, so people who does copy/paste will not destroy any existing data in the next steps).

Partitionning
First you have to create a partition table on your device.

You can use your preferred tool for that (fdisk, cfdisk, parted, …).

My favourite tool is cfdisk :

# cfdisk /dev/sdX


 * Create two partitions («New») :
 * a 200MB (or more) one, that will hold the Openelec KERNEL and SYSTEM. Partition type should be Linux (83, which is the default). Make it bootable.
 * all the remaining space will be used as storage. Partition type should be Linux (83, which is the default)
 * «Write» the partition to the device (Are you sure... ? Yes!)
 * «Quit»

Check that the partition table is fine :

Disk /dev/sdX: 8589 MB, 8589934592 bytes 133 heads, 62 sectors/track, 2034 cylinders, total 16777216 sectors Units = sectors of 1 * 512 = 512 bytes Sector size (logical/physical): 512 bytes / 512 bytes I/O size (minimum/optimal): 512 bytes / 512 bytes Disk identifier: 0x000eece8 Device Boot     Start         End      Blocks   Id  System /dev/sdX1  *         62      503005      251472   83  Linux /dev/sdX2         503006    16777215     8137105   83  Linux
 * 1) fdisk -l /dev/sdX

Formatting
Now you have to create the two filesystems, System and Storage (the labels are important to have Openelec booting fine, if you want/need to change them, you'll have to adapt the extlinux.conf file later) :

# mkfs.ext4 -L System /dev/sdX1 # mkfs.ext4 -L Storage /dev/sdX2

Install Openelec
Mount the System partition on your system :

# mkdir -p /mnt/openelec/system # mount LABEL=System /mnt/openelec/system

Copy the Openelec « iSCSI compatible » (devel version >= r10332 or stable > 2.0 version) KERNEL and SYSTEM files in it :

# cp /path/to/Openelec.tv/SYSTEM /mnt/openelec/system # cp /path/to/Openelec.tv/KERNEL /mnt/openelec/system

Install the extlinux bootloader
First, create the extlinux.conf file (/mnt/openelec/system/extlinux.conf) :

DEFAULT linux PROMPT 0 LABEL linux KERNEL /KERNEL APPEND boot=ISCSI=ISCSI_OPTIONS,LABEL=System disk=LABEL=Storage quiet

The ISCSI_OPTIONS will depend on how you will boot. You could edit it later.

Basically, there will be two options :

auto
 * you will use an iBFT capable boot rom (ipxe), ISCSI_OPTIONS will be :

iscsi_initiator=iqn.2010-04.org.whatever:mybox,iscsi_target_name=iqn.2000-01.com.synology,iscsi_target_ip=192.168.1.14,iscsi_target_port=3260,iscsi_target_group=pandora.openelec iscsi_username=username,iscsi_password=password,iscsi_in_username=username_in,iscsi_in_password=password_in and you will have to append ip=dhcp to your kernel command line in order to have network.
 * you will not use an iBFT capable boot rom, ISCSI_OPTIONS will be something like :

If you are a sane person, you probably already know that you will use an iBFT capable ROM like ipxe ;-)

IMPORTANT Note : you don't have to specify the ISCSI=ISCSI_OPTIONS for every device, even if you both have System and Storage on iSCSI. Just use it on the boot= definition, as in the example.

Now install extlinux on the device :

# extlinux --install /mnt/openelec/system

Ok, you're done, now unmount the device :

# umount /mnt/openelec/system

And log out from the target :

# iscsiadm -m node -T iqn.2000-01.com.synology:pandora.openelec -p 192.168.1.14:3260 -u

(The disk needs a correct MBR to boot up the System disk, therefor you might need to use "cat /usr/lib/extlinux/mbr.bin > /dev/sdX")

'''IMPORTANT WARNING : there are chances that your target will allow you to access to your device from several computers at the same time. YOU SHOULD NEVER MOUNT IT FROM MORE THAN ONE COMPUTER AT A TIME. Writing on a filesystem from more than one computer at the same time will corrupt your filesystem, you don't want to do that. NEVER !'''

= Configure the iSCSI boot = Ok, so now you have your LUN, an iSCSI-aware Openelec is installed on it, but how will you make your HTPC boot from it. That's a very good question, Thanks for asking it.

There is several answers to that question.

If you have the chance to have an HTPC which have an iSCSI compatible network adapter (Note : I don't know of any low-end devices which do, please let me know if that is your case!), it will be really easy : just go into your network card BIOS/ROM, and configure the iSCSI target, and tell it to boot from it. You should be done !

You probably don't have such a network adapter (it's more an entreprise-class feature), but no problem, IPXE (http://ipxe.org) is there for you !

IPXE is an OpenSource Boot Firmware, it's a maintained fork of Etherboot/GPXE. It does PXE, is capable to access files from TFTP, FTP, HTTP servers, and more important it is also capable to boot from iSCSI (it also supports san boot on AoE and FCoE) !

All you need to use it is :


 * a PXE capable network adapter (most of them are nowadays) + a DHCP/TFTP server
 * Pros :
 * You will have a totally storage-free HTPC
 * Changes will be more easy to do
 * Cons :
 * It is more difficult to setup if you don't already have knowledge on DHCP/PXE/TFTP
 * or you can load it from an SD card, or an USB key.
 * Pros :
 * Really easy to setup
 * No need to have access or knowledge on DHCP/TFTP servers
 * Cons :
 * Only about 100KB will be really used on the storage device... what a waste ! (but if you have an old and slow SD card lying somewhere, it will be perfect for that job !)

The Hard and Techy Way : Go DHCP !
Installing a DHCP and/or a TFTP server is out of the scope of this howto. You'll find good tutorials about that on the Net.

There are some good docs on the IPXE homepage about that :

http://ipxe.org/howto/dhcpd

http://ipxe.org/howto/msdhcp

If you don't already have a DHCP server nor a TFTP server, I recommend you to look at dnsmasq, which is a lightweight DHCP/TFTP server ;-)

So basically, you just have to make the ipxe ROM available on your TFTP server, and configure the DHCP server to make your box boot on it (next-server...). Than, configure a DHCP chainloader (http://ipxe.org/howto/chainloading) to boot a script like :

echo Ready for iscsi boot ! set username username set password password set reverse-username username_in set reverse-password password_in :retry_sanboot sanboot iscsi:192.168.1.14::::iqn.2000-01.com.synology:pandora.openelec || goto retry_sanboot

Of course you will have to adapt it to your needs (ip address, target name, usernames and passwords).

You can also embed the script in the ROM file, so your device won't have to make 2 DHCP queries. Look at the next section to see how to do that.

The Lazy Way : Install the ROM code on a removable device
You don't want to (or you can't) install and configure a DHCP server and a TFTP server.

And you have that old SD card of 128MB that you earned with your first digital camera years ago, that is of no use now... great ! It's a perfect candidate for becoming a booting ROM device ! (of course, if your HTPC doesn't allow you to boot from SD card, you'll need to find something else, like an old USB key (the smallest/slowest, the better)).

First, you have to checkout the ipxe source code :

$ git clone git://git.ipxe.org/ipxe.git

Then, create a new text file, that will be your ipxe embeded boot script :

$ vi ~/my_script.ipxe :retry_dhcp dhcp || goto retry_dhcp echo Ready for iscsi boot ! set username username set password password set reverse-username username_in set reverse-password password_in :retry_sanboot sanboot iscsi:192.168.1.14::::iqn.2000-01.com.synology:pandora.openelec || goto retry_sanboot
 * 1) !ipxe

Once again, adapt the values to your needs !

Build the rom :

$ cd ipxe/src $ make bin/ipxe.usb EMBED=~/my_script.ipxe

Note : The ipxe.usb file will work with any iPXE-supported network adapter.

Ok, now you've got your boot rom.

Just put it on your SD card/USB device (plug it on your building system, look at dmesg to find on which /dev/sdX it is available). As root :

Don't miss this one, you don't want to blow up your other disks !
 * 1) cat bin/ipxe.usb > /dev/sdX

you're done !

Just put the SD card/USB key in your HTPC box, configure it to boot from it, and enjoy !