
          SANsurfer iSCSI Command Line Interface (iSCLI)                         
                          Readme File
 
      This software license applies only to QLogic customers.
                     QLogic Corporation.
                     All rights reserved. 


Table of Contents

1. Package Contents 
2. Requirements 
   2.1 Hardware Requirements 
   2.2 Software Requirements  
3. OS Support 
4. Supported Features 
5. Using the iSCLI
   5.1 Installing SANsurfer iSCSI Command Line Interface
   5.2 Unattended Installation of SANsurfer iSCSI Command 
       Line Interface (iSCLI)
   5.3 Removing SANsurfer iSCSI Command Line Interface
6. Application Notes 
   6.1 Two-Part Application for Windows 
   6.2 CHAP Table
   6.3 Linux PPC
   6.4 iSNS Targets 
   6.5 Boot Code
   6.6 Return Codes
   7. Known Issues / Workarounds 
8. Contacting Support  


1. Package Contents 

The following list describes the contents provided in the SANsurfer
iSCSI Command Line Interface (iSCLI) package: 

 * Windows package file: iscli-<version>-win.msi
    - Windows package file is an executable installer package

 * Linux package file: iscli-<version>_linux_<arch>.install.tar.gz
    - iscli.dkms.iunstall.sh - Install script
    - iscli-<version>_<arch>.rpm - RPM installer package file

 * Solaris package file: 
    - iscli-<version>_solaris_sparc_x86.Z
    - iscli-<version>_solaris_sparc_x86
    - pkgadd - installer package file


2. Requirements

This section defines the minimum hardware and software requirements:

 * 2.1 Hardware Requirements 
 * 2.2 Software Requirements  

2.1 Hardware Requirements

The SANsurfer iSCSI Command Line Interface (iSCLI) has the
following minimum hardware requirements:

 * QLogic QLA4xxx iSCSI HBA 

 * Single- or multi-processor server or workstation

 * Pentium II class 300 MHz, 64 MB RAM, 1 MB disk space
   or
   IBM PowerPC server/workstation, 512 MB RAM, 1MB disk space
   or
   Sun SPARC server/workstation running Solaris, 128MB RAM,
   1MB disk space.

2.2 Software Requirements

SANsurfer iSCSI Command Line Interface (iSCLI) has the following 
minimum software requirements:

 * QLogic QL4xxx drivers


3. OS Support

SANsurfer iSCSI Command Line Interface (iSCLI) runs on the 
following OS platforms:

* Windows:
   - Windows 2000, 32-bit (x86)
   - Windows Server 2003, 32-bit (x86, AMD64, Intel 64)
   - Windows Server 2003, 64-bit (AMD64, Intel 64)
   - Windows Server 2008, 32-bit (x86, AMD64) 
   - Windows Server 2008, 64-bit (AMD64, Intel 64)
   - Windows XP Professional, 32-bit (x86, AMD64, Intel 64) 
   - Windows XP Professional x64, 64-bit (AMD64, Intel 64)
   - Windows Vista, 32-bit (x86, AMD64, Intel 64) 
   - Windows Vista x64, 64-bit (AMD64, Intel 64)

 * Solaris:
   - Solaris 10, 32-bit (x86, AMD64, Intel 64)
   - Solaris 10, 64-bit (AMD64, Intel 64, 64-bit SPARC) 
   - Solaris 8, 9, 32-bit (SPARC 32-bit, 64-bit SPARC)
   - Solaris 8, 9, 64-bit (64-bit SPARC)

 * Linux
   - Red Hat RHEL AS/ES 5.2/5.1, 32-bit (x86) 
   - Red Hat RHEL AS/ES 5.2/5.1, 64-bit (Intel 64, AMD64)
   - Red Hat RHEL AS/ES 4.7/4.6, 32-bit (x86)
   - Red Hat RHEL AS/ES 4.7/4.6, 64-bit (Intel 64, AMD64)
   - Red Hat RHEL AS/ES 4.7/4.6, 32-bit (x86)
   - Red Hat RHEL AS/ES 4.7/4.6, 64-bit (Intel 64, AMD64)
   - Red Hat RHEL AS/ES 3 U9/U8, 32-bit (x86)
   - Red Hat RHEL AS/ES 3 U9/U8, 64-bit (Intel x86, AMD64)

   - Novell SLES 10 SP2/SP1, 32-bit (x86)
   - Novell SLES 10 SP2/SP1, 64-bit (Intel 64, AMD64)
   - Novell SLES 9 SP4/SP3, 32-bit (x86)
   - Novell SLES 9 SP4/SP3, 64-bit (Intel 64, AMD64)
   - Novell SLES 8 SP4/SP3, 32-bit (x86)
   - Novell SLES 8 SP4/SP3, 64-bit (AMD64)
	
NOTE: For specific OS service packs (SP) and updates, refer to the 
descriptions where this software version is posted on the QLogic 
website (http://support.qlogic.com/support/drivers_software.aspx).


4. Supported Features

The SANsurfer iSCSI Command Line Interface (iSCLI) function set
closely mirrors the functionality provided in the SANsurfer iSCSI 
HBA Manager (graphical user interface). You may use the iSCLI as
an alternative to the GUI to view, configure, and diagnose the 
QLA4010, QLA405x, and QLE406x iSCSI HBAs.

NOTE: For detailed user information, syntax, and command options,
refer to the SANsurfer iSCSI HBA CLI User's Guide.

Functions include:

 * Asset Management

   - View information about attached iSCSI HBAs.
   - View information about iSCSI devices and LUNs connected to
     the iSCSI HBAs.
   - Save host configuration to text file.
   - View Vendor Private Data (VPD).
   - Clone all or parts of pre-saved HBA configuration
     for HBA replacement, quick configuration duplication, or to
     ensure consistent configurations.
   - Extend GUI to import HBA port config to all or multiple hosts.

 * Configuration Management

   - Configure QLogic iSCSI HBAs network and iSCSI parameters.
   - Configure connections to iSCSI targets.
   - View target negotiated parameters.
   - Specify ASCII secrets.
   - Display LUN properties.
   - Update firmware.
   - Update BIOS, FCODE, and ROM.
   - Restore firmware factory default settings.
   - Restore factory defaults using comprehensive feature
     (405x and 406x).
   - Configure VLAN (405x and 406x).
   - Configure ZIO (405x and 406x).
   - Update BIOS and FCode Boot targets.
   - Update iSCSI Boot configuration (disable, manual, DHCP for 405x and 406x.
   - Configure IPv6 network.
   - Support SNIA IMA for all OSes.
   - Support target redirection.
   - Update 405x and 406x network configuration without card reset.
   - Support DHCP boot path.
   - Display ARP log.
   - Display and log into multiple iSNS target portals to
     the same target.
   - Retrieve and display all discovered target portals 
     from a Send Target discovery.
   - Easily duplicate target portal connections to a 
     target for multiple connections.
   - Select which target portals to log into from a 
     discovered targets list acquired from Send Target discovery and 
     iSNS discovery.

 * Statistics

   - Statistics available for each iSCSI HBA.

 * Advanced Diagnostics

   - Ping a target to verify connectivity between HBA port and a target.
   - Perform read/write buffer tests.
   - Perform internal loop back tests.
   - Perform external loop back tests.
   - Generate firmware log dump (Type 1=fw flash and NVRAM).

 * HBA State and Target Session Connection State

   - View QLogic iSCSI HBAs and their states.
   - View target connections and their states.

 * Driver Installation

   - Available for Windows only.

 * Trace Capability

   - Set trace levels by parameters in config file (iscli.cfg).


5. Using SANsurfer iSCSI Command Line Interface

This section provides the following topics:

 * 5.1 Installing SANsurfer iSCSI Command Line Interface
 * 5.2 Unattended Installation of SANsurfer iSCSI Command
       Line Interface (iSCLI)
 * 5.3 Removing SANsurfer iSCSI Command Line Interface

5.1 Installing SANsurfer iSCSI Command Line Interface

The iSCLI is packaged by Operating System. One package for Solaris
SPARC and Solaris x86 together, one for Windows, one for IA32 
Linux(2.4.x kernel or 2.6.x kernel), and one for PPC Linux
(2.6.x kernel).

The install package name is:

iscli-A.B.CC-DD_<os type>_<subtype>.<installtype>
where
<os type> = "win", "linux", or "solaris"
<subtype> = i386, ppc64, or sparc_x86
AA.BB.CC-DD = version number
<installtype> is rpm for Linux, exe for Windows, and blank
for Solaris. 

The windows install package does not have a subtype.

The file extensions are as follows:

Windows: .msi
  Linux: .install.tar.gz
Solaris: .Z

For example, a Linux package is:

iscli-1.1.00-12_linux_i386.install.tar.gz

To install the package, follow the procedure for your operating system:

 * 5.1.1 Windows
 * 5.1.2 Linux
 * 5.1.3 Solaris

5.1.1 Windows

For packages prior to 1.1.00.06
-------------------------------

Run the self-extracting archive iscli-AA.BB.CC-DD_win.exe. Follow
the prompts in the install wizard. This adds the install path to
the environment variables but does not affect it until
you either restart the system or apply the environment variables
property list.

To uninstall the application, go to Add/Remove programs in control
panel and remove SANsurferiCLI.

For packages 1.1.00.06 and newer
--------------------------------

To view the MSI install command summary, enter the following command
without any parameters:
  
  msiexec

Use one of the following methods to install the package:

 * To start an interactive installation, run the following command:

   SANsurferiCLI.msi (with no parameters) 
   or 
   msiexec /i SANsurferiCLI.msi 

 * To perform a silent installation (without displaying any errors), 
  run the following command:

  SANsurferiCLI.msi /q 

 * To display only a progress bar with minimal interaction and no error 
  messages, run the following command:

  SANsurferiCLI.msi /passive 

 * To install the application in a specific directory:

  SANsurferiCLI.msi /q INSTALLDIR=directory
 
  NOTE: This requires using the full file path names. 

 * To overwrite any InstallAnywhere versions of the agent without asking
  for confirmation, run the following command:

  SANsurferiX_AgentOnly.msi /i FORCEINSTALL=TRUE 
      
5.1.2 Linux

Unzip and untar the iSCSI CLI gzipped tar bundle, then execute the
installation script:

tar -xvzf <iSCSI CLI gzipped tar bundle>
  ./iscli.dkms.install.sh install

This places the files automatically in the directory:

/opt/QLogic_Corporation/SANsurferiCLI

It also adds this directory automatically to the 
execution path.

5.1.3 Solaris

From a command prompt enter:

uncompress iscli-AA.BB.CC-DD_solaris_sparc_x86.Z
pkgadd -d iscli-AA.BB.CC-DD_solaris_sparc_x86

The script automatically places the files in the directory:

/opt/QLogic_Corporation/SANsurferiCLI

This command automatically adds the directory to the
execution path.
    
5.2 Unattended Installation of SANsurfer iSCSI Command Line 
Interface (iSCLI)

To start an unattended installation, see the instructions 
for your operating system:

 * 5.2.1 Windows
 * 5.2.2 Linux
 * 5.2.3 Solaris

5.2.1 Windows

Enter the following command:

<Install Package Filename> -q
      
For example:

iscli_1.1.00-06_win.msi  -q
      
5.2.2 Linux

Unzip and untar the iSCSI CLI gzipped tar bundle:

tar -xvzf <iSCSI CLI gzipped tar bundle>
./iscli.dkms.install.sh install
      
5.2.3 Solaris

First, create two files (response.txt and noask_pkgadd.txt), then run
the pkgadd command. To do this:

1. Create the response.txt file with contents of first question of arch.
   For example:
   
   <BOF>
    1
   <EOF>
      
2. Create the noask_pkgadd.txt file with contents:

   <BOF>
    action=nocheck
   <EOF>
      
3. Run the following commands:

   pkgadd -d ./<Install Package Filename>  -n -a 
   ./noask_pkgadd.txt < ./response.txt
      
   For example:
    
   pkgadd -d ./iscli-1.1.00-06_solaris_sparc_x86  -n -a 
   ./noask_pkgadd.txt < ./response.txt
 
5.3 Removing SANsurfer iSCSI Command Line Interface

To the remove SANsurfer iSCSI Command Line Interface (iSCLI),
follow the procedure for your operating system:

 * 5.3.1 Windows
 * 5.3.2 Linux
 * 5.3.3 Solaris

5.3.1 Windows

Use one of the following methods to remove the SANsurfer CLI 
application:

 * To start removing the application from the Windows Start
   menu, point to QLogic Management Suite and select SANsurfer 
   Uninstaller. 

 * To start interactive uninstall, run the following command:

   SANsurferiCLI.msi 

 * To start passive uninstall with a confirmation dialog box
   and progress bar only, run the following command:

   msiexec /x SANsurferiCLI.msi 

 * To perform a silent installation (without any error messages),
   run the following command:

   msiexec /q /x SANsurferiCLI.msi 

   NOTE: The application does not include an upgrade mechanism.

5.3.2 Linux

Enter one of the following commands:

rpm -e iscli-AA.BB.CC-DD   (be sure to omit the rest of the name)
   or
./iscli.dkms.install.sh uninstall  (to uninstall a prior or 
                                    current version of iscli)
        or

./iscli.dkms.install.sh uninstall all  (to uninstall iscli and also
                                        the iSCSI HBA IOCTL module)

NOTE: Other applications may depend on the iSCSI HBA IOCTL module.

5.3.3 Solaris

Enter one of the following commands:

pkgrm QLSisclix86    (for x86)

          or 

pkgrm QLSisclisparc  (for SPARC)

    
6. Application Notes 

The following topics provide additional information about the
SANsurfer iSCSI Command Line Interface (iSCLI):

 * 6.1 Two-Part Application for Windows 
 * 6.2 CHAP Table
 * 6.3 Linux PPC
 * 6.4 iSNS Targets 
 * 6.5 Boot Code
 * 6.6 Return Codes

6.1 Two-Part Application for Windows 

The Windows version of the iscli application consists of two parts:

 * The application program (iscli.exe) 
 * A support (SDMiSCSId.dll) library. 

If you copy the application to another directory, you must also copy 
the DLL to the same location. Note that SANsurfer iSCSI HBA Manager 
also uses this DLL. 

WARNING: Do not copy the application to the same directory where the 
SANsurfer iSCSI HBA Manager resides. Doing so may overwrite the support
DLL and cause incompatibilities.

6.2 CHAP Table

The format of the CHAP table (stored on the HBA) used by 
versions of SANsurfer earlier than 02.05.05 are not compatible 
with the CLI UI format. To convert the CHAP table to the newer 
format, use the chapConv application. 

NOTE: If you convert the CHAP table, you must also upgrade 
SANsurfer to a newer version (02.05.xx) since the new CHAP 
table format is not compatible with older software versions.

6.3 Linux PPC

When installing on a Linux PPC machine, to add the iscli to 
the execution path, you must configure the path variable to contain
/usr/local/bin.  This is not done automatically on Linux PPC.

6.4 iSNS Targets 

When discovering targets, the application displays a maximum of 
62 iSNS targets as persistent targets (target ID's 0 - 64). 
The iscli application cannot detect iSNS targets beyond 62.

6.5 Boot Code

You can download the BIOS and FCode, which are used for remote boot,
and configure them using the iscli application.

The processor/operating system platforms that BIOS and FCode work 
with include the following:

BIOS: 
 * Windows 2000 (SP4) Server and Advanced Server on IA32 
 * Windows Server 2003 (SP1/SP2/R2) on IA-32 and x64 
 * Windows XP Professional (SP2) on IA-32 and x64 
 * Red Hat Linux AS 3.0 (Update 7 and Update 6) on IA-32 and x64
 * Red Hat Linux AS 4.0 (Update 3 and Update 2) on IA-32 and x64
 * Novell SLES 8 (SP 4 and SP 3) on IA-32 and x64 
 * Novell SLES 9 (SP 3 and SP 2) on IA-32 and x64 
 * Novell SLES 10 on IA-32 and x64 

FCode: 
 * Solaris (SPARC) 9 and 10 
 * Novell SLES Linux ES 9.0 (PPC) 

6.6 Return Codes

This section lists and describes iSCSI CLI return codes. For full 
details, run the iSCSI CLI in command line mode using the -ei 
command line switch. 

For example: 

iscli -ei
 
    A summary of common return codes is available below:

    Value Return Code Description
    ===== =======================

      0   Success.
    100   A parameter was invalid. Please use iscli -h switch to 
          display proper usage.
    103   HBA instance specified is invalid.
    102   A call to the SDM Library failed.
    103   HBA instance specified is invalid.
    104   Failed to open the HBA for an operation.
    105   Failed to save the INITFW settings to the HBA.
    108   A required parameter was missing.
    109   An error occurred updating the firmware.
    119   An unknown system error occurred.
    152   Driver zip/inf file not found.
    153   Unable to unzip driver file.
    154   Unable to retrieve driver version from the driver file.
    155   Unable to get info from driver file.
    158   Driver update failed.
    164   Invalid configuration parameter.
    168   Operation not supported by this HBA model.
    169   User not privileged for this operation.
    170   There are no appropriate HBAs for this firmware image.
    172   No HBAs detected.
    173   No Driver Found.
 
NOTE: For complete Return Code information, see the iSCSI CLI 
Users Guide.


7. Known Issues and Workarounds

 * After installing the drivers, you must restart the iscli
   to view HBAs. This is regardless of the message regarding
   the need for the reboot.

 * When installing iscli on Linux with an iscli version is
   older than 1.0.39.02, the RPM update option "-U" does
   not work correctly.
    
   Workaround: Use the options "-ivh --force." For example:
   rpm -ivh --force iscli-1.0.39-02.ppc64.rpm

 * On Linux 2.6 and newer kernels, you may see the warning
   message "Error Read FW settings from HBA instance" if 
   the HBA is not initialized or is unable to acquire an
   IP address via DHCP. This occurs when the IPv4 address
   is "0.0.0.0".

   Workaround: Set the IP address to a non-zero value.
    
 * Driver installation on Vista can be performed only by
   true Administrator.


8. 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 
 Email: support@qlogic.com 

Support contact information for other regions of the world is 
available at the QLogic website: http://support.qlogic.com 


(c)Copyright 2008. 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. 

