###############################################################################
# This page describes how to install RHEL4 U3 onto a hard drive so that the 
# disk is bootable using an Intel iSCSI Boot-capable adapter. There are two 
# methods to accomplish this: 

# Installing directly to a hard drive in an iSCSI storage array (Remote 
# Install). 
# Installing to a local disk drive and then transferring this disk drive or OS
# image to an iSCSI Target (Local Install). 

# For more information on SCSI device enumeration, refer to Appendix A at the 
# end of this document.               
###############################################################################

This process has two phases.
1) Creating the Driver Update Media (DUM)   
	This involves copying the iSCSI module, its dependencies and the 
        utilities needed for installation onto an update disk. The disk can be 
        an IDE floppy, USB floppy or USB flash drive.

2) Installation to the iSCSI target LU
	This consists of two parts; pre-install and post-install.

NOTE: Some newer network device drivers are not included in RHEL4. To enable 
these devices, the user will need to get the correct driver and load the driver
before discovery is attempted when following the preinstall instructions.

###############################################################################
Prerequisites
###############################################################################
NOTE: Users who wish to have the easiest experience when installing Linux onto 
an iSCSI target should use Red Hat 5.1 or greater. Red hat 5.1 provides native 
support for iSCSI booting and installing. This means that there are no 
additional steps outside of the installer that are necessary to install to an 
iSCSI target using an Intel Gigabit PCI-Express Server Adapter. Please refer 
to the Red Hat 5.1 documentation for instructions on how to install to an iSCSI
LU.

These instructions explain how to install using source and tools provided on 
the RHEL4 U3 or U4 CDs. If the user wants to use newer code (kernel src, 
development packages, initiator source, kernel modules, etc...) it is the 
user's responsibility to obtain the newer code and alter this process 
accordingly. A user with the following prerequisites can install and boot 
RHEL4 U3 or U4 on an iSCSI Target LU.

1) A RHEL4 U3 or U4 build machine
	To ensure module compatibility the architecture of the build machine 
        should match both the install media and the diskless system with which
        you intend to connect to the iSCSI Target LU. This means that if you 
        will be doing a diskless boot on an x86_86 system your build machine 
        will need be have an x86_64 architecture. The install CDs will also 
        need to be for the x86_64 architecture.

2) iSCSIBoot.tar.gz
	Provided by Intel.

3) Install Media
	A blank 3.5' floppy disk, or a USB flash drive.

4) The iSCSI Target LUN (Boot LUN) 
        This information is important to know in advance so that grub can be
        configured correctly.

###############################################################################
Phase I  - Creating the Drivers and Utilities Media (DUM)
###############################################################################
1) Copy and untar iSCSIBoot.tar.gz on the build machine.
	a) cp iSCSIBoot.tar.gz /home
        b) cd /home
        c) tar -zxvf iSCSIBoot.tar.gz

2) Compile iscsiboot/iscsi_boot_util.c statically.
        a) cd iSCSIBoot
        b) gcc -static -Wall iscsi_boot_util.c -o iscsi_boot_util

3) Install the following RPM and copy modules to preinstall directory.
	a) rpm -ivh kernel-2.6.9-34.EL.i686.rpm, from the RHEL4 U3 or U4 CD2
        b) cp -f \
            /lib/modules/2.6.9-34.EL/kernel/drivers/scsi/
             scsi_transport_iscsi.ko \
	    /lib/modules/2.6.9-34.EL/kernel/drivers/scsi/
             iscsi_sfnet/iscsi_sfnet.ko \
	    /lib/modules/2.6.9-34.EL/kernel/crypto/crc32c.ko \
	    /lib/modules/2.6.9-34.EL/kernel/crypto/md5.ko \
	    /lib/modules/2.6.9-34.EL/kernel/lib/libcrc32c.ko  \
            /home/iSCSIBoot/preinstall/

4) Copy media onto the DUM
	a) Attach the DUM and mount it if necessary.
	b) cp -fr /home/iSCSIBoot/iscsi_boot_util /home/iSCSIBoot/preinstall  \
	    /home/iSCSIBoot/postinstall  <DUM mount point>
	c) Unmount if necessary and remove the DUM

###############################################################################
Phase II - Installation to the iSCSI disk
###############################################################################
NOTE: This assumes you have flashed and configured the iSCSI firmware to 
connect to the target and iSCSI firmware was able to connect to the iSCSI 
target.

NOTE: If you are using USB flash drive/USB floppy as DUM, it must be attached 
prior to this step. If you're performing a Local Install, make sure the local 
disk is connected. 

1) Begin installation with the option "linux updates".

2) Continue until the "Update Disk Source" screen.
        a) Press Ctrl+Alt+f2 to switch to command line mode.
        b) Make a mount point directory and mount the DUM. (The mount point can
           be anywhere but /mnt). Depending on the DUM media type, these are the 
 	   instructions:
             IDE floppy
               mkdir /mnt/floppy /tmp/iscsi
               mount /dev/fd0 /mnt/floppy
               cp -fr /mnt/floppy/* /tmp/iscsi
               umount /dev/fd0

             USB Floppy/USB flash drive
	       To mount a USB device you must understand which /dev node the 
               kernel will use to represent the DUM. To do this run "dmesg" and 
               examine the output. Look for the text which shows your USB 
               device's registration with the system. Determine which sdX 
               device is associated with your device.

               Next run "cat /proc/partitions", the output should look similar 
               to this,

		Major    Minor    #blocks    Name
                7        0        <x>        loop0
                8        0        <x>        sda

	        Using the /dev node determine the minor number for your USB 
                device.

                Mount the USB device.

		mkdir /mnt/usb /tmp/iscsi
		mknod /dev/sdX b 8 <minor#>
                mount /dev/sdX /mnt/usb
                cp -fr /mnt/usb/* /tmp/iscsi

                DO NOT unmout/remove USB floppy/USB flash drive at this point.

        c) Run the iscsipreinstall script from the mount point.
               /tmp/iscsi/preinstall/iscsipreinstall
        d) Run "dmesg" again to verify that discovery occurred correctly. It 
           should show that drives were recently discovered. Note the LUNs and 
           discovered SCSI device nodes. This information needed to set grub 
           configuration files.
        e) Press Ctrl+Alt+F1 and select "Back".
        f) Continue with the installation.

NOTE: When partitioning the iSCSI LUs, ensure that the boot partition is not
distributed across physical partitions on different iSCSI LUs. The Intel iSCSI 
Option ROM will only access one iSCSI LU and if /boot is distributed across 
multiple LUs, it will not be visible during the boot process.

3) Configure the boot order
        a) On the "Boot Loader Configuration" screen, select "Configure 
           advanced boot loader options".
        b) Change the drive order so that the target disk is on the top of the 
           list.
        c) Continue with the remainder of the installation.
        d) When the installation is complete DO NOT press "Reboot".

4) Make some final post install changes
        a) Press Ctrl-Alt-F2 to switch back to the console.
        b) Alter grub settings
           Modify the device.map and grub.conf files so that they have the 
           correct device node listed. Refer to Appendix A for more information 
           on SCSI device enumeration. 
            /mnt/sysimage/boot/grub/device.map
                (hd0)   <SCSI device node for Boot LUN>
            /mnt/sysimage/boot/grub/grub.conf
                #boot=<SCSI device node for Boot LUN>
        c) Run the post install script and unmount the DUM.
                /tmp/iscsi/postinstall/iscsipostinstall

5) Ensure the network is not shutdown during halt
        a) Edit the /mnt/sysimage/etc/init.d/halt and scroll to the bottom.
        b) Change the line stating HALTARGS="-i -d" to HALTARGS="-d"

6) Return to the GUI and reboot
   NOTE: If you are using a bootable USB or Flash drive, remove it, otherwise 
   the system will try to boot off that drive.
        a) Press Ctrl+Alt+F7 and then select "Reboot"
        b) Remove the installation media and DUM

7) On your first boot, if Kudzu asks you if you'd like to configure your 
   adapters, please select to "ignore" the device.


Appendix A
==========
The iSCSI LUs are discovered as SCSI device nodes. The enumeration of SCSI 
devices is dynamic. The SCSI subsystem creates device nodes in the order that
they are discovered, starting with /dev/sda and incrementing alphabetically. 
In the case of iSCSI LU enumeration, local SCSI devices such as disks or USB 
devices affect this process. If a device node is created for a USB device 
before iSCSI discovery occurs the USB device will be represented by /dev/sda 
and the iSCSI LUs will begin with /dev/sdb. However, if you were to reboot this
system without the USB device the iSCSI LUs will begin with /dev/sda. It is 
important to configure grub correctly to point to the correct device node in 
order to boot from an iSCSI hard drive.

It is often the case when installing to an iSCSI LU that a device driven by the
SCSI subsystem is used for the install media. For example, using a USB flash 
drive for the DUM. As stated above this will affect how grub should be 
configured when installing.

Here is an example of how iSCSI device node mappings might differ between
installation and booting.

In this example the user is using a USB flash drive as a DUM. Since this device
is being used to copy files onto the system it is present before iSCSI 
discovery occurs. However, when booting from the iSCSI Boot Disk no USB flash 
drive is necessary and therefore it isn't attached.

Remote Installation:
USB flash drive or USB floppy                         /dev/sda
LUN 0                                                 /dev/sdb
LUN 1                                                 /dev/sdc

Booting:
LUN 0                                                 /dev/sda
LUN 1                                                 /dev/sdb

If the USB device is attached after booting, it will be enumerated as such,
USB flash drive or USB floppy                         /dev/sdc

It is also possible that there are other USB devices on the system, it is
users responsibility to find out if these will interfere with the device node 
mapping during boot.

Appendix B
==========
After performing a Local Install on an IDE device the user will need to modify
grub so that when booting the root partition is identified as a SCSI device. 
When installing to a local IDE disk drive the device node used will be of the 
form /dev/hdX, but when this volume is exposed by the iSCSI target the initator 
will see the hard drive as a SCSI device and it will be represented as 
/dev/sdX. This change must be made in the grub configuration file. This type of
problem exposes the necessity that the user fully understand the concepts 
described in this document as specifics may vary greatly.

Appendix C
==========
In some cases, if booting the system takes an unusually long time, you may try 
commenting the following line in the file /etc/init.d/iptables:

    $IPTABLES-restore $OPT $IPTABLES_DATA
    if [ $? -eq 0 ]; then
        success; echo
    else
        failure; echo; return 1
    fi

This may be required as the command may be resetting the connection.

Appendix D
==========
Crash Dump for Linux:

Red Hat Enterprise Linux 4: Netdump utility can be used to dump the disk image
when the system crashes. 

Support
=======

For general information, go to the Intel support website at:

    http://support.intel.com

or the Intel Wired Networking project hosted by Sourceforge at:

    http://sourceforge.net/projects/e1000
