****************************************************************
            Dell, Inc.
            RDAC Multi-Path Proxy Driver for Linux
            Build and Installation Instructions
            MD3000 and MD3000i
****************************************************************
Updated: 8/2/2010                            Copyright 2006-2010
================================================================

NOTE: This version of the RDAC readme has been deprecated and is
no longer supported by Dell.  Please refer to the updated 
RDACReadme.txt file located on the Dell PowerVault MD3000/MD3000i Resource
CD for installing the Multi-Path Proxy Driver for Linux.


Contents
================================================================
 1. OS Support
 2. HBA Support
 3. Co-existence with QLogic and LSI Logic failover drivers
 4. Unpacking the driver source code
 5. Building and Installation
 6. Package Uninstall and Reinstall
 7. Kernel Update
 8. Restrictions
 9. Proc Entries
 10. Man Pages
 11. GPL License


1. OS Support
================================================================

   The RDAC Multi-Path Proxy driver for Linux is supported 
   on the following Linux distributions for kernels 2.4 and 2.6:
    RedHat Enterprise Linux 4 Updates 7 & 8 (x86, x86_64)
    RedHat Enterprise Linux 5 Updates 2-5 (x86, x86_64)
    SUSE SLES 9 SP4 (x86_64)
    SUSE SLES 10 SP2 & SP3 (x86_64)
    SUSE SLES 11 Gold & SP1 (x86_64)


2. HBA Support (MD3000 only)
================================================================
    The RDAC driver is supported on the following host 
    bus adapter:
      Dell SAS 5/E Adapter


3. Co-existence with QLogic and LSI failover drivers
================================================================
    The RDAC driver cannot co-exist with an HBA-level failover
    driver such as the Emulex, QLogic or LSI Logic HBA failover 
    drivers.


4. Unpacking the driver source code
================================================================

    To unpack the source package, type the following command and 
    press Enter:

        tar -zxvf  rdac-LINUX-xx.xx.xx.xx-source.tar.gz

    where xx.xx.xx.xx is the release version of the RDAC driver.

    The source files will uncompress to the "linuxrdac-xx.xx.xx.xx" 
    directory. 


5. Building and Installation
================================================================

    5.1. Requirements before RDAC driver package installation
    ------------------------------------------------------------
      a. The kernel header files for the kernel version to be 
         built against should already be installed before  
         RDAC driver package installation. For RHEL it is
         "kernel-devel" and for SLES it is "kernel-source".

      b. The gcc package must be installed so the gcc compiler
         is available.

    MD3000i Only
    ------------
         a.  For iSCSI software Initiator, the host driver is named "iscsi_sfnet"
             on RedHat 4.0 and named "iscsi" on SLES 9 SP3.
             Both of these drivers also use the scsi_transport_iscsi module provided
             by the kernel. On SuSE, the driver names should be in INITRD_MODULES
             in /etc/sysconfig/kernel

    MD3000 Only
    -----------
        a. A Dell SAS 5/E Adapter is required.

        b. The Dell SAS 5/E driver must be installed prior to 
           RDAC driver installation.

        c. The computer must be restarted after installing the 
           Dell SAS 5/E driver.

           Ensure that the following modules are loaded before 
           installing:

           RHEL4/RHEL5/SLES9/SLES10/SLES11:
           mptsas

        d. Ensure the Dell SAS 5/E has an entry for loading at 
           startup in the kernel module configuration file.  
           Also, ensure there are no duplicate aliases for 
           scsi_hostadapterX entries:

           RHEL4/RHEL5 /etc/modprobe.conf:
           alias scsi_hostadapterx mptsas

           SLES 9/SLES 10/SLES11
             Ensure that mptsas is included in INITRD_MODULE list in
             /etc/sysconfig/kernel.


    5.2. RDAC Driver Building Instructions
    -----------------------------------------------------------
        a. Change the directory to the ~/linuxrdac-xx.xx.xx.xx 
           directory.

        b. To remove the old driver modules in that directory, 
           type the following and press Enter:

                make clean

        c. To compile all driver modules and utilities, type 
           the following and press Enter:

                make


    5.3. RDAC Driver Installation
    -----------------------------------------------------------

        a. To uninstall the old RDAC Driver if previously installed, 
           type the following and press Enter:

                make uninstall

        b. Type the following and press Enter:

                make install

           This command will do the following things:
           * copy the driver modules to the kernel module tree.
           * build the new RAMdisk image (mpp-`uname -r`.img) which 
             includes the RDAC driver modules and all driver 
             modules that are needed at boot.

        c. Add a boot entry to the systems bootloader using the new RDAC 
           RAMdisk image.  Do this by copying a known good working 
           menu item for the concerned kernel and changing the 'initrd=xxxxx.img'
           section to the appropriate new RDAC RAMdisk image name. 

           Examples below, actual values for hdx, sdxx may change depending
           on system configuration.

           RHEL 4/RHEL 5 grub menu.lst:
             title Red Hat Enterprise Linux AS MPP (2.6.9-11.ELsmp)
                     root (hd0,0)
                     kernel /vmlinuz-2.6.9-11.ELsmp ro root=LABEL=/1 rhgb quiet
                     initrd /mpp-2.6.9-11.ELsmp.img
         
           SLES 9 grub menu.lst:
             title SUSE Linux Enterprise Server 9 MPP
                      root (hd0,1)
                      kernel /boot/vmlinuz root=/dev/sda2 vga=0x317 selinux=0 \
                      splash=silent console=tty0 resume=/dev/sda3 elevator=cfq showopts
                      initrd /boot/mpp-2.6.5-7.232-smp.img

            SLES 10 grub menu.lst:
              title SUSE Linux Enterprise Server 10 MPP
                      root (hd0,5)
                      kernel /boot/vmlinuz root=/dev/sda6 vga=0x314 resume=/dev/sda5 
                      splash=silent showopts
                      initrd /boot/mpp-2.6.16.21-0.8-smp.img

        d. Set the new menu item as the default.
        
        e. A reboot is required before the changes take effect


    5.4. RDAC Driver Post-Installation
    -----------------------------------------------------------
        a. Verify there are no duplicate 'alias scsi_hostadapterX? in 
           /etc/modules.conf or /etc/modprobe.conf.  If there are 
           duplicate entries, give each alias a unique number:

           alias scsi_hostadapter2 mp???
           alias scsi_hostadapter2 mp???

           becomes:

           alias scsi_hostadapter2 mp???
           alias scsi_hostadapter3 mp???

          (mp??? could be mptspi,mptsas,mptfc, etc)

        b. Restart the computer using the new boot menu option.

        c. Type in "lsmod" to verify that the driver stack is 
           properly loaded:
           * On Redhat 4.0/5.0 Platforms: scsi_mod, sd_mod, sg,
             mppUpper, mppVhba, and, for MD3000 only, low level HBA
             drivers (mptbase mptscsih) are loaded.

            * On SuSE platforms: sg, mppUpper, mppVhba, and for MD3000 only,
              low level HBA drivers (mptbase mptscsih mptsas) are loaded.

        d. To verify that the RDAC driver discovered the 
           available virtual disks connected to the adapter, type the 
           following command and press Enter (note: virtual disks must be 
           configured on the MD3000/MD3000i storage enclosure before this
           command will work):

                ls -lR /proc/mpp

        e. You can now issue I/Os to the virtual disks.

        f. If you make any of the following changes you must run 
           mppUpdate to re-build the MPP RAMdisk image:

           Change the RDAC configuration file (/etc/mpp.conf).
           Change persistent binding file (/var/mpp/devicemapping).
           Upgrade the iscsi driver.
           Upgrade the kernel.

           This will ensure that the new configuration file (or 
           persistent binding file) or new iscsi driver can be used on 
           the next system reboot.

        e. The file /etc/syslog.conf should have entries for
           kern.debug, kern.notice, kern.info and kern.warning
           in order to capture all debug and error messages
           for MPP driver.


    5.5  RDAC Driver Unloading Instructions
    ----------------------------------------------------------	
        a. The Unload order for the MPP driver stack is as follows.
           1. rmmod mppVhba
           2. rmmod mptbase, mptscsih, mptsas
           3. rmmod mppUpper

       NOTE: Reboot the system whenever a need to unload
       the driver stack arises. Use of rmmod to remove all the 
       drivers in the RDAC driver stack, in order, is not
       recommended.


6. Package Uninstall and Reinstall
================================================================
    To un-install the RDAC driver package, type the following 
    and press Enter:

          make uninstall

    MPP driver update:

    To Reinstall/Update the RDAC driver package, you need to do
    a "make uninstall" followed by "make install" under the 
    /linuxrdac-xx.xx.xx.xx directory in the new RDAC driver source 
    code bundle.

    For a Driver Update, if the system already has an old boot entry 
    for MPP, no change is required if the kernel version has not changed.


7. Kernel Update
================================================================

    a. Before applying the kernel update, change directory to the 
       linuxrdac source code directory.

    b. execute "make uninstall".

    c. Apply the kernel update or upgrade and boot into the new default 
       initrd (non MPP) kernel

    d. Follow the MPP driver building and installation procedure 
       described in Section 4.3 and Section 4.4.    


8.  Restrictions 
================================================================
    a. When the RDAC driver detects that all paths to a storage 
       array are failed, it will report an I/O failure immediately.

       Workaround: Follow the steps as mentioned below:
       1. Ensure that the storage array is connected to the host server
          and that all installation instructions have been completed
          including the connection of the out-of-band (Ethernet)
          connections to each RAID controller module.
       2. Create a virtual disk and map to LUN 0.
       3. Reboot the host for the LUN to be discovered and the MPP driver
          to be loaded. Thereafter, all other sequential or sparse LUNS can be
          created and registered to the OS by running hot_add.

    b. The Linux 2.4 SCSI layer does not support skipped (sparse)
       LUNs. If the mapped LUNs are not contiguous, the Linux kernel
       will not scan the rest of the LUNs. Therefore, the LUNs after
       the skipped LUN will not be available to the host. 

       Workaround: This is only on RedHat 3.0 - Linux 2.4. Run hot_add
       to map the missing LUN numbers every time the host is rebooted.

    c. Problem: On RHEL3 - Linux 2.4 the MPP failover driver component
       mpp_vhba will not load unless a storage array is connected and
       a LUN is mapped to the host server.

       Workaround: Follow the steps as mentioned below:
       1. Ensure that the storage array is connected to the host server
          and that all installation instructions have been completed
          including the connection of the out-of-band (Ethernet)
          connections to each RAID controller module.
       2. Create a virtual disk and map to LUN 0.
       3. Reboot the host for the LUN to be discovered and 
          the MPP driver to be loaded. Thereafter, all other
          sequential LUNS can be created and registered to
          the OS by running hot_add.


    d. The RDAC driver stack, which includes the mpp_Upper( or 
       mppUpper), the mpp_Vhba ( mppVhba) and the low level HBA driver
       (MD3000 Only), should not be loaded or unloaded using the modprobe
       kernel module utility. Any use of modprobe on the RDAC driver 
       stack is entirely the responsibility of the user. This Driver 
       does not support the use of modprobe with the RDAC driver stack. 

       Recommendation: Reboot the system whenever a need to unload
       the driver stack arises. Use of rmmod to remove all the 
       drivers in the RDAC driver stack, in order, is also not 
       recommended.

       - After this, for MD3000i, you can run "/etc/init.d/iscsi stop" 
       to stop the iscsi deamon and unload the iscsi driver.
       The script /opt/mpp/mppiscsi_unmountall script, called
       as part of iscsi stop or restart script  kills any 
       processes running I/Os to the devices and unmounts any 
       mounted filesystems. This same script will also unload the
       mppVhba driver module. 


9. Proc Entries
================================================================
    To verify that the RDAC driver discovered the 
    available physical LUNs and created virtual LUNs for
    them, type the following and press Enter:

    ls -lR /proc/mpp

    The linux system provides a /proc file system that is
    a special memory-only, software-created filesystem used
    by the kernel to export driver information to the user 
    space. The proc pseudo-filesystem is mounted to /proc. 
    The linux SCSI subsystem's proc filesystem directory is
    /proc/scsi. By convention each HBA driver creates a sub
    directory under /proc/scsi. The linux MPP driver's proc 
    entries are:

    1. /proc/mpp 
       Entry for the mpp driver itself

    2. /proc/scsi/mpp/<adaptor number> 
       The entry for the MPP virtual host adaptor. This can 
       differ from system to system and is assigned by the 
       scsi middle-layer.

    3. /proc/mpp/<storage-array name>
       There is an entry for each array that is visible to the 
       host.  

    4. /proc/mpp/<storage-array name>/controllerA
       /proc/mpp/<storage-array name>/controllerB  
       These are the entries for the 2 targets on each array 
       seen by the host. Each storage array has 2 controllers.

    5. /proc/mpp/<storage-array name>/controller<A/B>/<low-level-
       driver><HCT#>

       Here the low level driver can be any one of qlogic, lsi
       or emulex HBAs. The HCT# is the Host#, channel#, Target#,
       where Host# is the Host No of the low-level driver and is
       assigned by the scsi mid-layer. Channel# depends on whether
       the HBA card is single or dual channeled. Target# is the 
       Target # assigned to that controller on that array and is
       assigned by the Low-level HBA driver. 

    6. /proc/mpp/<storage-array name>/controller<A/B>/<low-level-
       driver><HCT#>/LUN #

       Lastly are the Volumes or LUN # of Volumes as mapped on 
       host partition on the storage array and seen through that
       path or Initiater(Host)-Target combination.


10. Man Pages
================================================================

    There are 4 man pages that can provide more information

    man RDAC - This man page talks about the RDAC(MPP) driver and
    the MPP configurable parameters.

    man mppUtil - This man page tells you how to use the
    mppUtil - the utility for the MPP driver.

    man mppBusRescan - This man page describes the hot_add (a.k.a 
    mppBusRescan) script that is available to add newly mapped luns and newly 
    added storage arrays.  

    man mppUpdate  - This man page instructs you as to how
    you can use the persistent device mapping facility
    available with the MPP driver and how to change the configuration 
    values for the MPP driver and build a new MPP ramdisk.


11. GPL License
================================================================
    RDAC driver modules (mppUpper.ko and mppVhba.ko) carry GPL License.
