iscsi Adapter Inbox Driver Update for Linux Kernel 2.6.x QLogic Corporation All rights reserved Table of Contents 1 Package Contents 2 OS Support 3 Supported Features 4 Using the iscsi Adapter Driver for Linux 4.1 Installing the Driver 4.2 Building the iscsi Adapter Driver for RHEL 5.4 and RHEL 5.5 4.3 Building the iscsi Adapter Driver for SLES 10 SP3 and SLES 11 4.4 Building the iscsi Adapter Driver for RHEL 6.0 and SLES 11 SP1 5 Driver System Parameters 6 Additional Notes 6.1 Booting from SAN 6.2 RHEL 5 Boot from SAN Installation on Non-LUN 0 LUN 6.3 Dynamically Modifying SCSI Blacklist Entries 7 Contacting Support 1 Package Contents The iscsi Adapter Inbox Driver Update for the Linux Kernel 2.6.x package contains the following files: File Name qla4xxx-vx.xx.xx.xx.xx.xx-kx.tgz qla4xxx-vx.xx.xx.xx.xx.x-dx.tar.tgz qla4xxx-vx.xx.xx.xx.xx.xx-cx.tar.tgz qla4xxx-vx.xx.xx.xx.xx.xx-kx.tar.tgz Description Compressed package that contains the driver and qisioctl for RHEL 5.4/5.5 Compressed package that contains the driver and qisioctl for SLES 10 SP3 Compressed package that contains the driver and qisioctl for RHEL 6 and SLES11 SP1 Compressed package that contains the driver and qisioctl for SLES 11 NOTE: xx indicates the driver package version number. 2 OS Support The iscsi Adapter Inbox Driver Update for Linux is compatible with the operating system (OS) platforms listed in the following table. iscsi Adapter Inbox Driver Update for Linux Kernel 2.6.x Page 1 of 11
Operating Systems OS Name OS Type Hardware Platform Red Hat RHEL 5.4 32-bit, 64-bit Intel x86, Intel 64, AMD64 Red Hat RHEL 5.5 32-bit, 64-bit Intel x86, Intel 64, AMD64 Red Hat RHEL 6.0 32-bit, 64-bit Intel x86, Intel 64, AMD64 Novell SLES 10 SP3 32-bit, 64-bit Intel x86, Intel 64, AMD64 Novell SLES 11 32-bit, 64-bit Intel x86, Intel 64, AMD64 Novell SLES 11 SP1 32-bit, 64-bit Intel x86, Intel 64, AMD64 3 Supported Features The iscsi Adapter Inbox Driver Update for Linux supports the following features: iscsi and TCP/IP protocol offloaded to adapter IPv4 and IPv6 (IPv6 supported on QLE406x and 8200 Series Adapters) Boot from SAN Send Targets discovery Asynchronous PDU dynamic LUN detection Up to 512 targets 4 Using the iscsi Adapter Driver for Linux This section provides the following procedures for using the driver: 4.1 Installing the Driver 4.2 Building the iscsi Adapter Driver for RHEL 5.4 and RHEL 5.5 4.3 Building the iscsi Adapter Driver for SLES 10 SP3 and SLES 11 4.4 Building the iscsi Adapter Driver for RHEL 6.0 and SLES 11 SP1 4.1 Installing the Driver Driver installation makes extensive use of the build.sh script located in the driver source (extras/build.sh). 4.2 Building the iscsi Adapter Driver for RHEL 5.4 and RHEL 5.5 4.2.1 Building and Installing the Adapter Driver 1. Go to the directory that contains the driver package file qla4xxx-srcx.xx.xx.xx.xx.xx-k.tar.gz. 2. Issue the following commands: # tar -xzvf qla4xxx-vx.xx.xx.xx.xx.xx-kx.tar.gz # cd qla4xxx-vx-x.xx.xx.xx.xx.xx-kx # tar -xvzf qla4xxx-src-vxx.xx.xx.xx.xx-ky.tar.gz # cd qla4xxx-vx.xx.xx.xx.xx.xx-kx iscsi Adapter Inbox Driver Update for Linux Kernel 2.6.x Page 2 of 11
3. Build and install the driver modules from the source code by executing the build.sh script as follows: #./extras/build.sh install The build.sh script does the following: Builds the driver.ko files Copies the.ko files to the appropriate directory: /lib/modules/2.6.../extra/qlgc-qla4xxx Adds the appropriate directive in the modprobe.conf (if applicable) Building the iscsi IOCTL Driver for RHEL 5.x # tar xvzf qisioctl-src-vx.xx.xx-kx.tar.gz # cd qisioctl-src-vx.xx.xx-kx #./build.sh install 4.2.2 Manually Loading the Adapter Driver 1. To load the driver, use one of the following methods: To directly load the driver from the local build directory, issue the following commands: # insmod /lib/modules/2.6.../kernel/drivers/scsi/scsi_transport_iscsi2.ko # insmod qla4xxx.ko To load the driver using modprobe, issue the following command: # modprobe -v qla4xxx 2. To load the qisioctl module using modprobe, issue the following command: # modprobe -v qisioctl 3. Start the iqlremote daemon by issuing the following command: # service iqlremote start 4.2.3 Unloading the Adapter Driver To replace an existing inbox driver with a new out-of-box iscsi driver, unload the existing driver and load the new driver, qisioctl module and iqlremote daemon. To unload the driver, stop all applications using the driver and then unload the driver. 1. Stop the iqlremote daemon by issuing the following command: iscsi Adapter Inbox Driver Update for Linux Kernel 2.6.x Page 3 of 11
# service iqlremote stop 2. Unload the qisioctl module, by issuing the following command: # modprobe -r qisioctl 3. To unload the driver using modprobe, issue the following command: # modprobe -r qla4xxx 4.2.4 Rebuilding the RAM Disk with the New Driver 1. Edit the /etc/modprobe.conf file and add the following entry (if it is not present): alias scsi_hostadapterx qla4xxx Where X is based on the order of the SCSI modules being loaded. 2. To create a backup copy of the RAM disk image, issue the following commands: # cd /boot # cp initrd-[kernel version].img initrd-[kernel version].img.bak 3. Rebuild the initrd image by issuing the following commands: # mkinitrd -f initrd-[kernel version].img `uname -r` 4. Reboot to boot from the new initrd image and new driver. NOTE: The RAM disk file name may be different depending on server hardware. 4.3 Building the iscsi Adapter Driver for SLES 10 SP3 and SLES 11 4.3.1 Building and Installing the Adapter Driver 1. Go to the directory that contains the source driver file, qla4xxx-vx.xx.xx.xx.xx.xxdx.tar.gz. 2. Enter the following commands: # tar -xzvf qla4xxx-vx.xx.xx.xx.xx.xx-dx.tar.gz # cd qla4xxx-x.xx.xx.xx.xx.x-dx 3. Build and install the driver modules from the source code by executing the build.sh script as follows: #./extras/build.sh install The build.sh script does the following: Builds the driver.ko files iscsi Adapter Inbox Driver Update for Linux Kernel 2.6.x Page 4 of 11
Copies the.ko files to the appropriate directory: /lib/modules/2.6.../updates Adds the appropriate directive in the modprobe.conf (if applicable) 4. To build the iscsi IOCTL Driver for SLES 10 SP3 and SLES 11, issue the following commands: # tar xvzf qisioctl-src-vx.xx.xx-dx.tar.gz # cd qisioctl-src-vx.xx.xx-dx #./build.sh install 4.3.2 Manually Loading the Adapter Driver 1. To load the driver, use one of the following methods: To load the driver directly from the local build directories, issue the following command: # insmod /lib/modules/2.6.../updates/qla4xxx.ko To load the driver using modprobe, issue the following command: # modprobe -v qla4xxx 2. To load the qisioctl module using modprobe, issue the following command: # modprobe -v qisioctl 3. Start the iqlremote daemon by issuing the following command: # service iqlremote start 4.3.3 Unloading the Adapter Driver To replace an existing inbox driver with a new out-of-box iscsi driver, unload the existing driver and load the new driver, qisioctl module and iqlremote daemon. To unload the driver, stop all applications using the driver, and then unload the driver. 1. Stop the iqlremote daemon by issuing the following command: # service iqlremote stop 2. Unload the qisioctl module using the modprobe command as follows: # modprobe -r qisioctl 3. To unload the driver using modprobe, enter the following command: # modprobe -r qla4xxx iscsi Adapter Inbox Driver Update for Linux Kernel 2.6.x Page 5 of 11
4.3.4 Rebuilding the RAM Disk with the New Driver 1. Edit the /etc/sysconfig/kernel file and add the qla4xxx parameter to the existing INITRD_MODULES line. For example: INITRD_MODULES="......... qla4xxx" NOTE: For SLES 11, edit the /etc/modprobe.d/unsupported_modules file to make the following change: allow_unsupported_modules 1 (replace 0 by 1) 2. To create a backup copy of the RAM disk image, issue the following commands: # cd /boot # cp initrd-[kernel version].img initrd-[kernel version].img.bak 3. Rebuild the initrd image by issuing the following commands: # mkinitrd 4. Reboot the host to boot from the new initrd image with the new driver. NOTE: The RAM disk file name may be different depending on server hardware. 4.4 Building the iscsi Adapter Driver for RHEL 6.0 and SLES 11 SP1 4.4.1 Building and Installing the Adapter Driver 1. In the directory that contains the source driver file, qla4xxx-src-vx.xx.xx.xx.xx.xxk.tar.gz, issue the following commands: # tar -xzvf qla4xxx-vx.xx.xx.xx.xx.xx-cx.tar.gz # cd qla4xxx-vx.xx.xx.xx.xx.xx-cx 2. Build and install the driver modules from the source code by executing the build.sh script as follows: #./extras/build.sh install The build.sh script does the following: Builds the driver.ko files Copies the.ko files to the appropriate directory: /lib/modules/2.6.../updates Adds the appropriate directive in the modprobe.conf (if applicable) iscsi Adapter Inbox Driver Update for Linux Kernel 2.6.x Page 6 of 11
4.4.2 Manually Loading the Adapter Driver 1. To load the driver, use one of the following methods: To load the driver directly from the local build directories, issue the following commands: # insmod /lib/modules/2.6.../kernel/drivers/scsi/scsi_transport_iscsi.ko # insmod /lib/modules/2.6.../updates/qla4xxx.ko To load the driver using modprobe, issue the following command: # modprobe -v qla4xxx 2. To load the qisioctl module, issue the following command: # modprobe -v qisioctl 3. Start the iqlremote daemon by issuing the following command: # service iqlremote start 4.4.3 Unloading the Adapter Driver To replace an existing inbox driver with a new out-of-box iscsi driver, unload the existing driver and load the new driver, qisioctl module and iqlremote daemon. To unload the driver, stop all applications using the driver, and then unload the driver. 1. Stop the iqlremote daemon by issuing the following commands: # service iqlremote stop 2. Unload the qisioctl module, using the modprobe command as follows: # modprobe -r qisioctl 3. To unload the driver using modprobe, issue the following command: # modprobe -r qla4xxx 4.4.4 Rebuilding the RAM Disk To automatically load the driver by rebuilding the RAM disk to include the driver, issue the following commands: 1. To create a backup copy of the RAM disk image, issue the following command: # cd /boot # cp initramfs-[kernel version].img initramfs-[kernel version].img.bak iscsi Adapter Inbox Driver Update for Linux Kernel 2.6.x Page 7 of 11
2. Rebuild the initrd image with driver by issuing the following command: # mkinitrd -f initramfs-[kernel version].img `uname -r` 3. Reboot the host to boot from the new initrd image with new driver. NOTE: The RAM disk file name may be different depending on the server hardware. 5 Driver System Parameters The driver gets its parameters when specified with the insmod command. For example: # insmod qla4xxx.ko ql4xextended_error_logging=1 If using the modprobe command, you must specify the parameters under the /etc/modprobe.conf for Redhat (or /etc/modprobe.conf.local for SLES) file. For example: options qla4xxx ql4xextended_error_logging=1 NOTE: For RHEL 6.0, create the file /etc/modprobe.d/qla4xxx.conf to add the parameters. Configurable parameters are listed in the following table. Driver System Parameters Parameter Description Values Default ql4xdiscoverywait Defines the discovery wait time in seconds. 60 ql4xkeepalive Defines keep alive timeout for port. 0xDEAD ql4xdontresethba Specifies that the adapter is not reset when the driver gets F/W hung AEN (0x8002) 0=reset adapter; 1=do not reset adapter ql4xcmdretrycount Defines the maximum number of mid-layer retries allowed for a command. NOTE: This parameter is supported only for SLES 10. ql4xqfullrampup Specifies the number of seconds to wait to begin to ramp up the queue depth for a device after a queue-full condition is detected. ql4xmaxqdepth Specifies the maximum queue depth to report for target devices. ql4xextended_error_logging Enables extended error logging. 0=no logging; 1=log errors; 2=debug logging ql4xmaxcmds displayconfig Specifies the maximum number of outstanding commands per host adapter. Enables display of the configuration used in the /etc/modules.conf file. 0=use driver default of 1024 0=do not display; 1=display the configuration 0 20 120 0 0 0 0 iscsi Adapter Inbox Driver Update for Linux Kernel 2.6.x Page 8 of 11
To view a comprehensive list of parameters, issue the following command: # /sbin/modinfo qla4xxx 6 Additional Notes Additional information is included in the following sections: 6.1 Booting from SAN 6.2 RHEL 5 Boot from SAN Installation on Non-LUN 0 LUN 6.3 Dynamically Modifying SCSI Blacklist Entries 6.1 Booting from SAN Booting from SAN means booting to the OS from an iscsi target device. QLogic recommends using the QLogic inbox driver to install the OS to an iscsi target device that is attached to a QLogic adapter. If no QLogic inbox driver is available that supports the adapter, you should use a driver update disk to boot from SAN. 6.2 RHEL 5 Boot from SAN Installation on Non-LUN 0 LUN NOTE: The following procedure is only for the RHEL 5 distribution. When installing to a LUN other than LUN 0 and LUN 0 is present, follow these steps to successfully boot from the LUN: 1. At the Boot Loader Configuration window, select the Configure Advance Boot Loader Option, and then click Next. 2. At the Advanced Boot Loader Configuration window, select Change Driver Order. 3. At the Edit Drive Order window, move the entry for the boot LUN, and then click OK. 4. Continue with the OS installation as usual. 6.3 Dynamically Modifying SCSI Blacklist Entries On 2.6.x kernels, you can dynamically change the SCSI blacklist, either by writing to a /proc entry or using the scsi_mod module parameter, which allows persistence across reboot. This change requires the SCSI Vendor/Model information for the SCSI device, available at /proc/scsi/scsi. Blacklist entries are in the following format: vendor:model:flags[v:m:f] Where flags can be the following integer values: 0x001 /* Only scan LUN 0 */ 0x002 /* Known to have LUNs, force scanning, deprecated: Use max_luns=n */ 0x004 /* Flag for broken handshaking */ 0x008 /* unlock by special command */ 0x010 /* Do not use LUNs in parallel */ iscsi Adapter Inbox Driver Update for Linux Kernel 2.6.x Page 9 of 11
0x020 /* Buggy Tagged Command Queuing */ 0x040 /* Non-consecutive LUN numbering */ - -> value need to be passed to "flags" variable for sparse LUN 0x080 /* Avoid LUNS >= 5 */ 0x100 /* Treat as (removable) CD-ROM */ 0x200 /* LUNs past 7 on a SCSI-2 device */ 0x400 /* override additional length field */ 0x800 /*... for broken inquiry responses */ 0x1000 /* do not do automatic start on add */ 0x2000 /* do not send ms page 0x08 */ 0x4000 /* do not send ms page 0x3f */ 0x8000 /* use 10 byte ms before 6 byte ms */ 0x10000 /* 192 byte ms page 0x3f request */ 0x20000 /* try REPORT_LUNS even for SCSI-2 devs (if adapter supports more than 8 LUNs) */ 0x40000 /* do not try REPORT_LUNS scan (SCSI-3 devs) */ 0x80000 /* do not use PREVENT-ALLOW commands */ 0x100000 /* device is actually for RAID config */ 0x200000 /* select without ATN */ 0x400000 /* retry HARDWARE_ERROR */ For example: # echo <VENDOR>:<MODEL>:040 > /proc/scsi/device_info To enable persistence across reboots: 1. Add the following line: options scsi_mod dev_flags=<vendor>:<model>:<flags> to the following file (based on distribution): /etc/modprobe.conf for RHEL 5 2. Rebuild the RAM disk (see the procedures in Section 4: Using the iscsi Adapter Driver for Linux). 7 Contacting Support Please feel free to contact your QLogic approved reseller or QLogic Technical Support at any phase of integration for assistance. QLogic Technical Support can be reached by the following methods: Web: http://support.qlogic.com E-mail: support@qlogic.com Go to Top iscsi Adapter Inbox Driver Update for Linux Kernel 2.6.x Page 10 of 11
Copyright 2010. All rights reserved worldwide. QLogic, the QLogic logo, and the Powered by QLogic logo are registered trademarks of QLogic Corporation. All other brand and product names are trademarks or registered trademarks of their respective owners. iscsi Adapter Inbox Driver Update for Linux Kernel 2.6.x Page 11 of 11