   SANsurfer FC HBA Command Line Interface (CLI) 
                  Readme File
                   5/20/2008
 
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 SANsurfer FC HBA CLI 
   5.1 Installing SANsurfer FC HBA CLI 
   5.2 Starting SANsurfer FC HBA CLI
   5.3 Removing SANsurfer FC HBA CLI 
6. Application Notes 
   6.1 General [Applies to All Operating Systems (OSes)]
   6.2 Windows Operating System
   6.3 Solaris Operating System
   6.4 VMware ESX
7. Known Issues / Workarounds 
   7.1 Windows Operating System
   7.2 Linux Operating System
   7.3 Solaris Operating System
   7.4 Mac OS X
   7.5 VMware ESX
   7.6 Others
8. Contacting Support  


1. Package Contents 

The following list identifies the SANsurfer FC HBA Command Line 
Interface (CLI) installation packages available for the supported 
OS platforms: 

 * scli-1.7.1-bb.windows.exe - All supported Windows platforms 
 * scli-1.7.1-bb.SPARC-X86.Solaris.pkg.Z - Solaris SPARC and x86
 * scli-1.7.1-bb.SPARC.Solaris26.pkg.Z  - Solaris SPARC 2.6
 * scli.1.7.1-bb.macosx.pkg.tgz - Mac OS X (Intel/Power PC) 
 * scli-1.7.1-bb.i386.rpm.gz - Linux (Intel x86, Intel 64 and AMD64) 
 * scli-1.7.1-bb.IA64.rpm.gz - Linux (Intel IA64) 
 * scli-1.7.1-bb.ppc64.rpm.gz - Linux (PPC64)

NOTE: The "bb" in the file names shown above represents the build 
number of the current software release.


2. Requirements

This section defines the minimum hardware and software requirements:

 * 2.1 Hardware Requirements
 * 2.2 Software Requirements 

2.1 Hardware Requirements

SANsurfer FC HBA CLI requires the following minimum hardware 
requirements: 

 * One or more of the following QLogic adapters:
    - QLx2xxx / QLx2xx FC HBAs
    - QLE80xx CNAs  

 * Single-processor or multiprocessor server or workstation: 

    - Pentium III with 450 MHz or greater for Windows XP Professional,
      Windows 2000, Windows Server 2003, Red Hat/SLES Linux, 
      Solaris x86, or NetWare 

    - Pentium III with 450 MHz or greater for Windows XP Professional,
      Windows 2000, Windows Server 2003, Red Hat/SLES Linux, 
      Solaris x86, or NetWare 

    - Power Mac G5 1.8 Mhz, Intel based Xserve/Mac Pro or greater with
      512 MB memory

 * Fibre Channel devices, such as disks and RAID subsystems. SANsurfer
   FC HBA CLI supports most FC devices. For a complete list of devices
   that support failover, see the QLogic SAN Interoperability Guide, 
   which you can download from the QLogic Web site, 
   http://www.qlogic.com

   NOTE: Tape devices appear as part of the configuration, even though
   SANsurfer FC HBA CLI does not fully support them. (It only provides
   persistent binding and LUN masking for tape devices.)

 * 256 MB physical RAM required to run SANsurfer FC HBA CLI; running
   with less memory can cause disk swapping, which severely affects 
   performance.

 * Video card capable of 256 colors and a screen resolution of 800x600
   pixels required.

 * About 7 MB disk space. 

2.2 Software Requirements

SANsurfer FC HBA CLI requires the following minimum software 
requirements: 
 
 * QLogic QLA2xxx drivers for your OS platform.

 * Administrative privileges to perform management. 
   functions 

 * One of the operating systems identified in the OS 
   Support section. 


3. OS Support

SANsurfer FC HBA CLI runs on the following OS platforms:

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

 * Solaris:
    - Solaris 9, 10 x86 32-bit, 64-bit Intel x86, Intel 64, AMD64 
    - Solaris 2.6, 7, 8, 9, and 10 SPARC 32-bit, 64-bit SPARC 

 * Apple Macintosh  Mac OS X (Panther/Tiger/leopard),  32-bit, 64-bit
   PowerPC/Intel

 * Linux
    - Red Hat RHEL AS 3.0 32-bit, 64-bit Intel x86, Intel 64, AMD64 
    - Novell SLES 8 32-bit, 64-bit Intel x86, Intel 64, AMD64 
    - Red Hat RHEL AS 4.0 32-bit, 64-bit Intel IA64, Intel 64, AMD64 
    - Red Hat RHEL AS 5.1 32-bit, 64-bit Intel IA64, Intel 64 
      nomenclature, AMD64 
    - Novell SLES 9 32-bit, 64-bit Intel IA64, Intel 64, AMD64 
    - Novell SLES 10  32-bit, 64-bit Intel IA64, Intel 64, AMD64 
 
  * VMWare ESX Server
    - ESX 3.5 32-bit, Intel 64, AMD64 
   
NOTE: For specific service packs (SP) and OS 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 FC HBA CLI provides a command line interface (CLI) that
lets you easily install, configure, and deploy QLogic Fibre Channel 
HBAs. It also provides robust diagnostic and troubleshooting 
capabilities and useful statistical information to optimize SAN 
performance. This application can only configure HBAs on the local 
machine upon which the application is installed.

You can operate the SANsurfer FC HBA CLI in two modes:

 * Interactive mode (menu-driven interface) - This mode requires 
   user intervention. 

 * Non-interactive mode (Command line interface) - Use this mode 
   for scripting or when you just want to perform a single operation.


5. Using SANsurfer FC HBA CLI 

This section describes how to install, start, and
remove the FC HBA CLI.  For details, see the following
topics:

 * 5.1 Installing SANsurfer FC HBA CLI 
 * 5.2 Starting SANsurfer FC HBA CLI
 * 5.3 Removing SANsurfer FC HBA CLI 

5.1 Installing SANsurfer FC HBA CLI 

For detailed procedures, refer to the SANsurfer FC HBA CLI 
Application User's Guide.

TIP: On Linux, add the verify-options "--nodeps" to skip the 
dependency check when installing the distribution rpm package 
on a Novell SLES 8/9/10 IA64 system. For example:

#rpm -iv scli-x.xx.xx-xx.IA64.rpm --nodeps

5.2 Starting SANsurfer FC HBA CLI

For detailed procedures, refer to the SANsurfer FC HBA CLI Application
User's Guide.

5.3 Removing SANsurfer FC HBA CLI 

For detailed procedures, refer to the SANsurfer FC HBA CLI 
Application User's Guide.

NOTE: The un-install process might leave certain files and 
directories behind. You must manually delete these files.


6. Application Notes 

The following topics provide additional information
according to operating system:

 * 6.1 General [Applies to All Operating Systems (OSes)]
 * 6.2 Windows Operating System
 * 6.3 Solaris Operating System
 * 6.4 VMware ESX

6.1 General [Applies to All Operating Systems (OSes)]

Two different measurement formats are used when 
displaying the hard drive size: decimal (GB) and binary
(GB). 

Both Linux and Windows display the correct number
using their numeric format:

 * Windows uses binary
 * Linux uses decimal 

Binary numbers are numbers that are a power of 2.

Decimal numbers are numbers that are a power of 10.

2^10 is 1,024. The closest decimal number is 10^3 or 1,000. 

2^20 is 1,048,576. The closest decimal number is 10^6 or 1,000,000.

2^30 is 1,073,741,824. The closest decimal number is 10^9 or 1,000,000,000.

6.2 Windows Operating System

6.2.1 ConfigRequired Parameter

Under Windows, the ConfigRequired parameter in the registry dictates 
how the OS sees devices.

When ConfigRequired=0, both persistently bound and new devices display
as enabled. This includes devices that might have been previously 
unconfigured using the SANsurfer FC HBA CLI. You can set this parameter
in the "Driver Setting" of SANsurfer FC HBA CLI called: "Present targets
that are persistently bound plus any new target(s) found".

When ConfigRequired=1, only persistently bound devices display as
configured. New devices or devices that were previously unconfigured 
using the SANsurfer FC HBA CLI display as unconfigured. You can set 
this parameter in the "Driver Setting" of SANsurfer FC HBA CLI called
"Present target(s) that are persistently bound only".

NOTE: With the new Windows driver (version 8.2.0.10 and later), you 
must set the ConfigRequired parameter to 1 to prevent the OS from
seeing unconfigured entries.

6.3 Solaris Operating System

On Solaris, the qla_mp_config_required parameter in the configuration 
file dictates how the OS sees devices.

The qla_mp_config_required flag in the QLogic configuration file
(qla2x00.conf) controls persistent binding of targets. The default
configuration file that comes with the QLogic driver does not have
an entry for this flag. An entry for this flag appears in the 
configuration file only when target configuration data is saved
using SANsurfer FC HBA CLI.

SANsurfer FC HBA CLI sets the qla_mp_config_required flag to 1 by 
default. When this flag is set to 1, the driver reports only target
devices that are persistently bound in the configuration file to 
the OS. The driver does not report any new or unconfigured targets 
to the OS. In other words, the default behavior for this flag is 
'Persistent Targets Only'.

When the qla_mp_config_required flag is set to 0, the driver 
reports both persistently bound and new targets to the OS. This
is equivalent to 'Persistent Plus New'.

NOTEs:

* SANsurfer FC HBA CLI does not read the value of the 
  persistent-binding-configuration parameter from the configuration
  file.

* The QLC driver does not support persistent binding/failover 
  configuration.

* The QLC driver does not support selective LUN configuration.

6.4 VMWare ESX

None


7. Known Issues and Workarounds

The following topics provide known issues
according to operating system:

 * 7.1 Windows Operating System
 * 7.2 Linux Operating System
 * 7.3 Solaris Operating System
 * 7.4 Mac OS X
 * 7.5 VMware ESX
 * 7.6 Others

7.1 Windows Operating System

7.1.1 Unsigned Windows Driver Update

Issue: When performing a driver update on unsigned Windows drivers, the
OS displays a confirm dialog box in front of the application (focus).

Workaround: None

7.1.2 Driver Parameters Revert Back to Their Default Values

Issue: When updating the Windows driver using SANsurfer FC HBA CLI, 
the driver parameters revert back to their default values:
    
Present targets that are persistently bound plus any new target(s) found

Workaround: Bind by world wide port name

7.1.3 Windows Server 2008/Vista installation Limits

Issue: SANsurfer FC CLI installation fails on Windows Server 2008/Vista
if you are not logged in as an administrator.

Workaround:  Right-click the installation setup file and select
"Run as Administrator" from the short-cut menu.

7.2 Linux Operating System

7.2.1 Information Left After Deleting Persistent Configuration

Issue: After deleting the Persistent Configuration, the string "options
qla2x00 ConfigRequired=1 ql2xuseextopts=1" remains in the /etc/modules 
file.

Workaround: You must manually edit this file to fully delete any and all
persistent data.

7.2.2 Non-Failover Driver

Issue: Under Linux, when running with a non-failover driver, the 
ConfigRequired=1 parameter is ignored. Consequently, the driver 
automatically configures the device if it does not find 
a persistent binding entry. When running with a failover
driver, the ConfigRequired=1 parameter indicates that a device
must have the matching config entry for it to be configured by 
the driver.

Workaround: Do one of the following: 

 * Make sure there is a persistent binding entry.
 * Make sure the device has a matching config entry.

7.2.3 Features Not Available when Running IOCTL Module Driver

Issue: When running the IOCTL module driver on a Linux OS, the following features
are not available:
	
 * Persistent binding
 * Selective LUN
 * HBA port statistics
 * Driver settings
 * Host topology

7.2.4 Features Not Available when Running Sysfs Inbox Driver

Issue: When running the Sysfs Inbox driver on a Linux OS, the following
features are not available:

 * Persistent binding
 * Selective LUN
 * HBA port statistics
 * Driver settings
 * Host topology
 * Link Status
 * Loopback test

Workaround: None

7.2.5 Features Not Available when Running VMWare Driver

Issue: When running the VMWare driver on a Linux OS, the following
features are not available with virtual ports:

 * HBA parameters settings
 * HBA parameters restore default
 * Flash update from file
 * Flash save to file
 * HBA parameters update from file
 * HBA parameters save to file
 * HBA parameters update from templates
 * iiDMA (Intelligence Interleave Factor) settings
 * Boot device settings
 * Driver settings 
 * HBA beacon

Workaround: None

7.2.6 Features Not Available when Running Windows driver with
      NPIV Enabled

Issue: When running the driver with NPIV enabled on Windows, the
following features are not available with virtual port:

 * HBA parameters settings
 * HBA parameters restore default
 * Flash update from file
 * Flash save to file
 * HBA parameters update from file
 * HBA parameters save to file
 * HBA parameters update from templates
 * Target link speed
 * Boot device settings
 * Driver settings
 * HBA beacon
 * Target / LUN list

Workaround: None

7.2.7 Warning Messages on Startup

Issue: When launching the SANsurfer FC HBA CLI, the following warning
messages may appear on the console:

qla2xxx 0000:01:02.0: Unable to read SFP data (102/a0/0).
qla2xxx 0000:01:02.0: Unable to read SFP data (102/a0/0).
qla2xxx 0000:01:02.1: Unable to read SFP data (102/a0/0).
qla2xxx 0000:01:02.1: Unable to read SFP data (102/a0/0).
qla2xxx 0000:01:02.0: Unable to read SFP data (102/a0/0).
qla2xxx 0000:01:02.1: Unable to read SFP data (102/a0/0).
qla2xxx 0000:01:02.0: Unable to read SFP data (102/a0/0).

The driver displays these messages when it is unable to read SFP data.
You can safely ignore them.

Workaround: None
 
7.3 Solaris Operating System

7.3.1 Slow Startup in Interactive Mode with Serial Console Server

Issue: On Solaris, when launching the SANsurfer FC HBA CLI in 
interactive mode from a telnet session using a serial console port
login, the application takes a long time to start.

Workaround: To resolve the issue, add the flag "int" to the
command to start the interactive mode. For example:

#scli int

7.3.2 Stale Semaphore Left Behind

Issue: During normal operation of SANsurfer FC HBA Manager on Solaris,
a stale semaphore may be left behind, causing all applications 
(SANsurfer FC HBA Manager and SANsurfer FC HBA CLI) to fail on load.  

Workaround: Manually remove the following two files:

/var/tmp/.SEMD
/var/tmp/.SEML

7.3.3 FCode/BIOS Update not Available with Sun-branded 2Gb HBAs

Issue: SANsurfer FC HBA CLI does not support FCode/BIOS update 
with Sun-branded 2Gb HBAs.

Workaround: None

7.4 Mac OS X

7.4.1 HBA Instance Number Changes at Reboot

Issue: With Mac OS X, the HBA instance number may not be the same as 
current with a next reboot. SANsurfer FC HBA CLI does not accept the
HBA number as a valid input and will abort the command.

Workaround: None

TIP: Use the HBA WWPN instead of HBA number when writing scripts. 

7.4.2 Unable to save configuration

Issue: Under Mac OS X, non-root users with admin privilege cannot 
save Target Persistent Binding or Selective LUN configuration.

Workaround: Use the "sudo" command.  This allows you to run the
application as the superuser or another user. For example:

#sudo scli [options]
    
By default, sudo requires that users authenthicate themselves with a password.

NOTE: By default, this is the user's password, not the root password. 

7.5 VMWare ESX

Issue: None

N/A

7.6 Others

7.6.1 Port Incorrectly Displayed in HBA in Topology

Issue: Depending on certain switch zoning 
configurations, an attached port may appear in the 
Topology as an HBA when it is not actually an HBA.

Workaround: None


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 

 North America Contact Information 
 
  Email: support@qlogic.com 

  Phone: (952) 932-4040 

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. 
