Linux Driver for the Intel(R) PRO/1000 T IP Storage Adapter =========================================================== December 1, 2003 Contents ======== - In This Release - System Requirements - Using isiconfig to Upgrade the Firmware - Firmware Compatibility - Installing the Driver and Software - Uninstalling the Driver - Upgrading the Driver - Configuring and Using the Software (isiconfig) - Enabling Persistent Volumes - Configuring and Using CHAP - Using SLP (Service Location Protocol) - Fail-Safe Upgrade of the Firmware - Troubleshooting and FAQ - Product Limitations - Support - License In This Release =============== This file describes key features, setup instructions, and descriptions of special features of version 2.0 of the Linux driver and supporting applications for the Intel(R) PRO/1000 T IP storage adapter. The RPM on this CD contains: 1. Precompiled (binary) versions of the driver for the Pro 1000/T for IP Storage adapter for use with: a. Red Hat* Enterprise Linux AS 2.1 as available from Red Hat with kernel 2.4.9-e.3 (single and multiprocessor versions). b. Red Hat* 9 as available out of the box with kernel 2.4.20-6, or as downloaded from the Red Hat* website with kernel 2.4.20-8 (single and multiprocessor versions). 2. Source code for the driver. The RPM installs the source code for the driver, library, configuration utility, and event daemon in a tarball in the path /usr/share/is1000-2.0/is1000-2.0.tgz. An experienced Linux user should be able to build the entire package for an unsupported kernel, but may need to modify the makefiles and/or source code to resolve build issues that are likely to arise in unsupported configurations. (Intel(R) guarantees customer support for the precompiled, binary versions of the driver only.) Issue the following commands to unpack, compile, and install from source: cd /usr/share/is1000-2.0 tar xvzf is1000-2.0.tgz cd is1000-2.0 make install The source tarball contains the source for the utilities in addition to the driver. For more information see the Troubleshooting and FAQ section at the end of these notes. System Requirements =================== This driver requires Linux kernel versions that are installed during a fresh Red Hat* Enterprise Linux AS 2.1 or Red Hat* 9 installation. These versions are 2.4.9-e.3 (Red Hat* Enterprise Linux AS 2.1) and 2.4.20-6, or 2.4.20-8 (Red Hat* 9). For questions related to hardware requirements, refer to the User Configuration Guide supplied with your Intel PRO/1000 T IP Storage Adapter. All hardware requirements listed apply to use with Red Hat* Linux. Other Linux kernel versions may work, but are unsupported. See In This Release for information on using the source code to build a driver for your Linux environment. Using isiconfig to Upgrade the Firmware ====================================== There are two ways to upgrade the firmware on your adapters. The preferred approach, described here, uses an operating-system native procedure to upgrade your adapter firmware. However, to use the preferred procedure, your adapters must be loaded with firmware version 2.5.39.x or later. If the firmware is not version 2.5.39.x or later, you must use the procedure described in the Fail-Safe Upgrade of the Firmware section, which you can also use as a fail-safe method of upgrading the adapter firmware in the event the card's nonvolatile memory is corrupted. 1. See the Installing the Driver and Software section below to install the latest Intel(R) PRO/1000 T IP Storage adapter drivers. 2. Make sure the is1000 system is running by verifying that the is1000 kernel module is loaded (via the lsmod command). If it is not loaded, enter the following command to load it: service is1000 start 3. Check the version of the firmware on your adapters. Run 'isiconfig -v' If the firmware is not version 2.5.39.x or later, you cannot continue with this method and must instead use the procedure described in the Fail-Safe Upgrade of the Firmware section. 4. Locate the new firmware image. On the CD-ROM, it is located in the Firmware directory. 5. Upgrade the adapters by entering the following command (where xx is the latest version available): isiconfig -as IPS4_6_xx.bin 6. Restart the is1000 service to make the new firmware available: service is1000 restart Firmware Compatibility ====================== The Intel PRO/1000 T IP Storage Adapter contains field upgradeable firmware designed to support both current and future versions of the iSCSI specification. To locate the most appropriate firmware for your solution, visit the Intel website. See the Upgrading the Firmware section of the online Intel PRO/1000 T IP Storage Adapter User Configuration Guide for information on upgrading your firmware. It is important that the iSCSI specification supported by the firmware match that of your target. The following information shows the compatibility between the Intel initiator and Network Appliance* or Cisco* targets. Firmware Version: 4.6.87.2 iSCSI Spec Version: 0.20 Tested Targets: Network Appliance* F87 and 825C Cisco* SN5420, SN5428 and MDS 9216 (see your target vendor for compatibility) NOTE: The first three sets of digits of the PRO/1000 T for IP Storage firmware version number represents the firmware version and the last set of digits represents the CPLD version. Installing the Driver and Software ================================== To install the driver and software, follow these steps: 1. Locate the RPM package you want to install. is1000-2.0-#.i386.rpm = Driver package (# represents the package version number) 2. Using RPM version 4, install the desired RPM package. This example installs the drivers: rpm -i is1000-2.0-#.i386.rpm (# represents the package version number) 3. Consult RPM man pages or external documentation for all available options to use with RPM utility. Uninstalling the Driver ======================= To uninstall the driver: 1. This example will remove the drivers. Consult RPM man pages or external documentation for all available options to use with RPM utility. rpm -e is1000 Upgrading the Driver =================== To upgrade the driver, follow these steps: 1. Stop the service if it is still running by entering the following command: service is1000 stop 2. Locate and go to the directory of the appropriate RPM package: (*) is1000-2.0-#.i386.rpm for a single or multiple processor server (# represents the package version number). 3. Enter the appropriate command to install the driver. For example, the following command for a single processor can be entered: rpm -U is1000-2.0-#.i386.rpm (# represents the package version number) Consult the RPM man pages or external documentation for all available options to use with the RPM utility. Configuring and Using the Software (isiconfig) ============================================== To configure the software, follow these steps: 1. Reboot the system to automatically load the device driver or execute the following command to manually load the software: service is1000 start or /etc/rc.d/init.d/is1000 start 2. Configure the network settings for the installed adapter(s). The adapters are identified by a number starting at 0. Executing the following command will display information about the adapter(s) found in the system: isiconfig For each adapter reported, the minimal configuration required is to enable DHCP and allow an automatically generated Initiator Name to be used. For example: isiconfig -au --adapternumber=0 --usedhcp Specific network settings and Initiator Name can be used by specifying additional options, for example: isiconfig -au --adapternumber=0 --ip=192.168.1.1 --subnetmask=255.255.255.0 --gateway=192.168.1.2 --initiatorname=myinitiatorname Other configuration options are available and described via the help and usage display: isiconfig -? 3. Add iSCSI target connections. The simplest way to add a connection to an iSCSI target that does not require CHAP is, for example: isiconfig -t --add --targetname=sometargetname --ip=192.168.1.3 --port=3260 Note: You can omit the port option if you use the default port (3260). To discover the targets available on a router, use a form of the following example command: isiconfig -t --query=192.168.1.4:3260 Note: You can omit the port option if you use the default port (3260). For convenience, an interactive utility is provided to make adding target connections simple: add-iscsi-targets 4. Mount the available iSCSI devices (assuming the targets added provide storage facilities). For disk devices, standard commands like fdisk, mkfs, mount, and fsck will work just as they do on local drives. For information on available iSCSI devices, disk partitions, and for information about the Intel PRO/1000 T IP storage adapter, execute the following command with no arguments: isiconfig Also, the following standard Linux pseudo-files are available for reference: /proc/scsi/scsi --- contains information about the SCSI devices. /proc/partitions --- contains information about available disk partitions. NOTE: there are two device naming schemes available to access iSCSI target devices. Standard Linux SCSI device names (/dev/sda1, /dev/sg1, etc.) are available, but not preferred. The Intel PRO/1000 T IP system provides access to iSCSI target devices by persistent device nodes that are available via the /dev/is1000devs device directory. These device names are safe to use across reboots and are not affected by SCSI device load ordering like the standard SCSI devices are. These preferred names are reported by the isiconfig utility when executed with no arguments. The device name code came from scsidev, a program written by Eric Youngdale and reworked by Kurt Garloff . NOTE: After partitioning connected storage targets, it may be necessary to execute the following command before the newly created partitions are visible: isiconfig --rescan 5. To stop and unload the driver, first make sure no SCSI devices bound to the Intel PRO/1000 T IP storage adapter are mounted or otherwise in use, then issue the following command: service is1000 stop or /etc/rc.d/init.d/is1000 stop Enabling Persistent Volumes =========================== Partitions on configured iSCSI targets can be automatically mounted when the is1000 service starts. To enable this capability, you must create a file named /etc/fstab.is1000. The format of this file is similar to the standard Linux /etc/fstab file. Each line describes one partition to mount with the format: /dev/is1000devs/ 0 0 Note: The last two entries ("0 0") are ignored. For more information regarding valid , consult the man page for mount(8). When the is1000 service starts, it executes /usr/sbin/is1000-mountall, which processes /etc/fstab.is1000. When the service stops, it executes /usr/sbin/is1000-mountall -u, which unmounts the entries in /etc/fstab.is1000. Configuring and Using CHAP ========================== This release of the Linux driver for the Intel PRO/1000 T IP adapter supports bi-directional CHAP for authentication. CHAP (Challenge-Handshake Authentication Protocol) is a security feature that may be enabled to restrict router or device access to initiators that can be authenticated. Per Connection Authentication: If enabled, CHAP can be configured to authenticate an initiator or both an initiator and a target. If CHAP has been enabled on a target, you must configure your adapter to provide the appropriate authentication information. To do this, execute a command like the following example: isiconfig -tu --targetname=foo --ip=1.1.1.1 --usechap --username=joe --password=schmoe Note that the password will be stored in plain text in the configuration file (/etc/is1000.conf). Ensure that, like other security sensitive files, access is restricted to root. If the target device has been configured to authenticate itself via reverse or "inbound" CHAP, you should also configure your adapter accordingly. To do this, specify these additional CHAP options for the target, for example: isiconfig -tu --targetname=foo --ip=1.1.1.1 --usechap --username=joe --password=schmoe --useinboundchap --inusername=jack --inpassword=jill Note: The password for inbound and outbound CHAP must be different. Discovery Authentication: If CHAP has been enabled for discovery on a router, the following command format can be used to provide authentication information to the router and, optionally, to authenticate the router via inbound CHAP. For example: isiconfig -t --query=192.168.1.10:3260 --usechap --username=joe --password=schmoe or, isiconfig -t --query=192.168.1.10:3260 --usechap --username=joe --password=schmoe --useinboundchap --inusername=jack --inpassword=jill Note that discovery authentication parameters are not stored in the configuration file. Note: The password for inbound and outbound CHAP must be different. Using SLP (Service Location Protocol) ===================================== The OpenSLP project (http://www.openslp.org) provides user tools to discover services via SLP on Linux. With OpenSLP, iSCSI targets can be discovered and configured without having to know the IP address and port of the iSCSI router. This release of the Linux tools for the Intel PRO/1000 T IP adapter supports SLP and discovers iSCSI targets that support SLP. The discovery is done via a standard NIC, hence the NIC should be configured to communicate with the Management port of the iSCSI targets that support SLP. The NIC can be located in either the management network or in the same network as the initiator and target. To add a target via SLP discovery, execute the interactive target configuration tool: add-iscsi-targets and select the "SLP Query" option. Fail-Safe Upgrade of the Firmware ================================ Use this procedure only if you cannot use isiconfig to update the firmware or if you need a fail-safe method of upgrading your adapter firmware in the event of corruption of the card's nonvolatile memory. If you have adapters with no dipswitches on them, you can still use the instructions below. Disconnect the Ethernet cable and follow the instructions, ignoring the ones involving dipswitches. If this procedure fails and your flash becomes corrupted, contact http://support.intel.com. If you are using a single adapter, see the set of instructions immediately following. If you are using multiple adapters, skip to the instructions for multiple adapters. To upgrade a single adapter's firmware, follow these steps: 1. If your version of DOS does not support CD-ROMs, create a DOS-bootable disk. 2. Next, create a flash upgrade disk. Insert a disk into your floppy drive. From the Intel software \Firmware\Failsafe directory, execute the batch file by typing: MakeFlashUpdateDisk a:\ (or whatever letter represents your floppy drive). This will copy update.bat, frucmd.exe, dos4gw.exe and IPS4_6_xx.bin (where xx is the latest version of the Draft 20 -compliant binary) to the floppy disk. For additional information, visit http://support.intel.com. 3. Turn off your computer, ensure proper grounding, remove the adapter, and locate the S1 switch. Newly manufactured adapters will have cellophane over the S1 switch, which you must remove. Flip S1-1 and S1-2 to the ON position. Then reinsert the adapter. 4. Reboot the host system in DOS from a DOS-bootable disk. 5. Once you boot to DOS, remove the boot disk and insert the flash update disk you created in Step 2. 6. At the DOS prompt, enter the command: a:\update IPS4_6~1.bin. 7. Wait for the utility to finish erasing the firmware and writing the file to flash. 8. Turn off your computer, remove the adapter, and flip the S1-1 and S1-2 dipswitches back to the OFF position. Then reinsert the adapter. 9. Remove the boot disk from the system and reboot the host operating system. 10.Upgrade the driver, as described in the Upgrading the Driver section above. NOTE: To verify the new firmware version, run isiconfig -v and compare it to the version listed in the Firmware Compatibility section above. Multiple Adapters To upgrade the firmware of multiple adapters, follow these steps: 1. If your version of DOS does not support CD-ROMs, create a DOS-bootable disk. 2. Next, create a flash update disk. Insert a disk into your floppy drive. From the Intel software \Firmware\Failsafe directory, execute the batch file by typing: MakeFlashUpdateDisk a:\ (or whatever letter represents your floppy drive). This will copy update.bat, frucmd.exe, dos4gw.exe and IPS4_6_xx.bin (where xx is the latest version of the Draft 20 -compliant binary) to the floppy disk. For additional information, visit http://support.intel.com. 3. Turn off your computer, ensure proper grounding, remove each adapter, and locate the S1 switch. Newly manufactured adapters will have cellophane over the S1 switch, which you must remove. Flip S1-1 and S1-2 to the ON position for every adapter. Then reinsert the adapters. 4. Reboot the host system in DOS from a DOS-bootable disk. 5. Once you boot to DOS, remove the boot disk or CD and insert the flash update disk you created in Step 2. 6. At the DOS prompt, enter a:\frucmd for a list of frucmd.exe command options. 7. Enter a:\frucmd -P for a list of adapters in your system. frucmd.exe assigns a number (0, 1, or 2) to each adapter. 8. Enter a:\frucmd -N # -E -L 0 to erase the image currently stored in the adapter's flash memory. The N parameter specifies the adapter to be addressed as listed in the a:\frucmd -p command above. For example, if you chose adapter 2, you would enter a:\frucmd -N 2 -E -L 0. 9. Enter a:\frucmd -N # -d -f IPS4_6~1.bin and frucmd.exe will write the latest firmware image file to the designated adapter (-N). 10.Repeat steps 8 and 9 for each adapter in your system. 11.Turn off your computer, remove each adapter, and flip the S1-1 and S1-2 dipswitches back to the OFF position. Then reinsert each adapter. 12.Remove the boot disk from the system and reboot the host operating system. 13.Upgrade the driver, as described in the Upgrading the Driver section above. NOTE: To verify the new firmware version, run isiconfig -v and compare it to the version listed in the Firmware Compatibility section above. Troubleshooting and FAQ ======================= 1. Which Linux kernel versions are supported by this driver? This driver requires Linux kernel version: - 2.4.9-e.3 (Red Hat* Enterprise Linux AS 2.1 SMP and UP) - 2.4.20-6 (Red Hat* 9 SMP and UP) - 2.4.20-8 (Red Hat* 9 SMP and UP) This driver has not been tested with kernels other than those listed above. 2. I tried to install the Red Hat Linux rpm and got an error message that the verfile.tic file was not present and I could not proceed. Why? Always install from the full CD or downloaded image. (From the CD, install from the full CD mounted at /mnt/cdrom.) That ensures that all files, including verfile.tic, are present, during install. The verfile.tic file contains important version information for the release and helps support personnel distinguish the versions of the software installed on the system and ensure consistency across all of the Intel(r) PRO/1000 T IP Storage Adapter software components. 3. Where do I find properties of the adapters, devices and targets? To get information about the adapters, routers, and targets, run the isiconfig application without parameters: isiconfig For more information refer to the section on isiconfig above. 4. What do I do if I can't connect to my targets? a. Ensure that your adapter(s) network settings have been configured. Check the output of isiconfig (no arguments). b. Ensure that your target's name, ip, and port have been correctly configured. Check the output of isiconfig (no arguments). c. Verify that you can ping the target router from the Intel PRO/1000 T IP Storage Adapter via isiconfig -ap . d. If your target requires CHAP authentication, ensure that the correct username and password are configured via the instructions provided in the Configuring and Using CHAP section. e. Some target routers require initiators to have specific names. If you used an autogenerated initiator name, ensure that this is compatible with your router. f. Ensure all cables are well-connected and link is established. 5. What do I do if I lose my connection to a target? a. Target connection events are posted to syslog (/var/log/messages). The current connection status of all targets can be obtained by executing isiconfig with no arguments. If a target's connection status is "FAILED," then the system is in the process of retrying the connection automatically. If the connection status is "FAULTED," then the system has exhausted the specified recovery options and the target will not come back online without user intervention. Check the options listed in #3 above, or attempt a manual reset via isiconfig -tx. b. Ensure all cables are well-connected and link is established. 6. Can I connect more than one adapter, whether in one machine or in different machines, to the same target? If by "target" you mean a LUN, no. Connecting multiple Intel PRO/1000 T IP storage adapters (from the same machine or different machines) to one LUN is the logical equivalent of connecting two computers to one hard drive, which can result in data loss, target disconnection, system crash (Windows) or an inability to mount the drives (Linux). There are, however, more sophisticated arrangements in which a "target" is a collection of LUNs and multiple adapters can connect to it under controlled circumstances for specific purposes. 7. Can I place more than one Intel PRO/1000 T IP storage adapter in a single machine? Yes. The software and drivers shipped with the PRO/1000 T IP storage adapter will support up to three Intel PRO/1000 T IP storage adapters in a single machine. 8. How do I build an is1000 module in a Red Hat* Enterprise Linux AS 2.1 system with a Linux kernel other than the supported version of 2.4.9-e.3? This is usually accomplished by modifying the is1000 driver Makefile. It is possible that the driver source code will require changes to compile and/or function as well. Please note that compiling your own driver will result in an unsupported configuration. For example, to build a module for 2.4.9-e.25smp, first extract the source code from the main tarball: cd /usr/share/is1000-2.0 tar xzvf is1000-2.0.tgz Next, identify your kernel version as being compatible with Red Hat Enterprise Linux AS 2.1 in the driver Makefile (is1000-2.0/driver/Makefile). For example, if you are trying to build a driver for kernel 2.4.9-e.25, modify the driver Makefile by adding the following block after similar checks for other kernel versions: ifeq ($(KSRC), /usr/src/linux-2.4.9-e.25) $(warning building for kernel version ($(KSRC))) IS1000_KERNEL_VER := AS endif Typing 'make' in the driver directory will now create an is1000.o module for 2.4.9-e.25. Simply move this new driver module to /usr/share/is1000- 2.0/drivers/2.4.9-e.25/is1000.o. 9. I've set up 32 storage devices on one of my Cisco SN 5428's interfaces. Why do I only see 20 devices in Linux isiconfig? This is an implementation limitation. Only 20 targets are allowed per storage router interface. If more than 20 targets are required, configure another interface on the SN 5428 and add the extra targets to it. Product Limitations =================== The maximum number of simultaneously connected logical units (LUNs) supported by the Intel PRO/1000 T IP Storage Adapter is 128, but the maximum number of simultaneously connected dynamic SCSI disks (which includes iSCSI disks) supported by Red Hat Linux kernels is 40. Support ======= For general information and support, go to the Intel support Website at: http://support.intel.com License ======= This readme.txt, as well as the software described in it, is furnished under license and may only be used or copied in accordance with the terms of the license. The information in this manual is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Intel Corporation. Intel Corporation assumes no responsibility or liability for any errors or inaccuracies that may appear in this document or any software that may be provided in association with this document. Except as permitted by such license, no part of this document may be reproduced, stored in a retrieval system, or transmitted in any form or by any means without the express written consent of Intel Corporation. Copyright (c) Intel Corporation (2003)