Configuring SNIA HBA API Library

Top  Previous  Next

The SNIA Common HBA API library was added to SMARTMon-UX in release 1.23. The library is an industry standard library used to manage Fibre Channel Host Bus Adapters and discover SAN resources. It was developed through the Storage Networking Industry Association (SNIA).

 

This library is supported by Q-Logic, Emulex, JNI, and other manufacturers of Fibre Channel HBAs as well as the major computer manufacturers such as Sun and HP. The library is safe to run from the perspective that it does not allow you to make any changes to anything on the SAN that can only be addressed through the SNIA drivers. That is, if your system is physically attached to disks on the SAN, and your HBA and optional switches are zoned such that a particular device can be accessed by your host computer, you will be able to make changes to it using the standard commands and options that have always been in SMARTMonUX.  If your system is not authorized by your administrators to access a particular device, you will be able to see basic information about it using the SNIA functions, but you will not be allowed to do anything else.

 

For example, suppose you have a LUN at WWN port number 20:00:00:99:88:AB:CD:EF and another at 20:00:00:99:88:AB:CD:F0. Both LUNs are attached to the HBA in this machine, but you configured your RAID engine or switch to prevent you from mounting the second (... CD:F0) device.  Our software would still let you see that the second device existed and report information about it.  It would not allow you to change mode pages for the device. That is because the SNIA HBA API library was designed to prevent this for security reasons.  

 

In general, the official SNIA web describes the API as:

 

"It defines a scope within which application software can be written without attention to vendor-specific infrastructure behavior. Included within the scope of the Common HBA API are vendor independent interfaces and services such as:

Observation and modification of descriptive and operational characteristics of Fibre Channel HBAs and ports;
Access to Fibre Channel Fabric Services;
Discovery and characterization of FCP-2 storage resources;
Access to Fibre Channel Extended Link Services sufficient to satisfy the FC-MI manageability profile for Host Bus Adapters;
Observation of Fibre Channel HBA, Port, and storage access traffic statistics;
Observation and modification of the availability and representation of Fibre Channel storage resources to Operating System applications;
Timely and selective reporting of HBA and fabric configuration, status, and statistical events."

 

This HBA API is distributed as a runtime file specific to your operating system and your HBA.  They are all available for download on your particular HBA vendor's web site and are typically bundled with the fibre channel device driver.

 

Below is the official HBA API FAQ. We removed some geeky parts only applicable to developers, reformatted, and appended SANtools-specific information on our implementation in RED.

 

HBA API FAQ

 

1.Introduction

This FAQ is intended to address frequently asked questions about the HBA API. This FAQ is maintained by Benjamin F. Kuo at TROIKA Networks, Inc. <benk@troikanetworks.com> and Dixon Hutchinson at Legato Systems, Inc. <dhutchin@legato.com> and is not endorsed or sponsored by the Storage Networking Industry Association (SNIA).

 

2.What's New

A little more information on iSCSI API's and the support Matrix.

Version history:

Version

Date

Description

1.0.0

June 29, 2001

Initial Draft

1.0.1

July 10, 2001

Resolved initial comments, added support matrix

1.0.2

August 16, 2001

Reformat, remove copyright

1.0.3 - 1. 0.7

September 15, 2001 - January 30, 2002

Update vendor support matrix

 

3.General Questions
3.1.What is the HBA API?

The SNIA Common HBA API is an industry standard, programming interface for accessing management information in Fibre Channel Host Bus Adapters (HBA). Developed through the Storage Networking Industry Association (SNIA), the HBA API has been overwhelmingly adopted by Storage Area Network vendors to help manage, monitor, and deploy storage area networks in an interoperable way.

 

The HBA API is implemented as a set of 'C' level API's which allow access to low level, Fibre Channel HBA information in a platform- and vendor- independent way. The API depends on vendor supplied, vendor specific code for the vendor's HBAs. The API does not support any vendor's HBA without a vendor specific library.

 

3.2.What is the history of the HBA API?

The HBA API effort began in March of 2000 in the SNIA Fibre Channel working group. In May of 2000, the HBA API subgroup was formed. In July of 2000 the 1.0 feature set was frozen and the initial draft submitted to the T11 FC-MI standards group. Version 1.0 was approved by the SNIA Fibre Channel working group in September of 2000 and is currently undergoing review as part of the T11 FC-MI Letter Ballot process. Version 2.0 efforts have been ongoing since December of 2000, with version 2.0 expected by Q2 2002.

 

3.3.How real is this standard? Specifically, when can I see this working?

The HBA API is in deployment today and was first demonstrated at the Fall 2000 Storage Networking World in Orlando. (Most, if not all FC HBAs now support the API, but not for all operating systems).

 

3.4.Is the HBA API an in-band or out-of-band mechanism?

The HBA API is neither. Information from the HBA API can be usually found through an out-of-band mechanism for management, however can also be accessed in-band through a IP over Fibre Channel connection.

 

3.5.Does the HBA API support SCSI adapters?

No, the HBA API is limited to supporting Fibre Channel HBAs.

 

3.6.Does the HBA API support iSCSI adapters?

 

Not yet, however there has been discussion on adding iSCSI support in the future. There is a separate working group (IPS TWG) within SNIA working on an API for iSCSI.

 

3.7.How secure is the HBA API? Can a rogue program disrupt my SAN through the HBA API?

There are no calls in the current HBA API which are able to read or write data from storage or otherwise affect SAN operation. All current SCSI calls in the HBA API are informational (read-only) calls. However, the CT pass through command does allow read and write of information from a switch, if allowed.

 

4.Installation and Usage

The HBA API is implemented as a common library which depends on vendor-specific libraries for specific HBA model support.

 

4.1.What files are installed to use the HBA API?

The HBA API consists of three major parts (vendor library, common library, and registration) that are installed on a system to operate.

On Windows systems:
HBAAPI.DLL is the common library, installed in %SYSTEMROOT%/SYSTEM32.
The vendor install software will write a registry entry in HKEY_LOCAL_MACHINE\Software\SNIA with the location of the vendor-specific library.
Vendors will install a vendor library, typically in the same location the vendor stores their driver software.
On Unix systems:
libHBAAPI.so is the common library, installed in /usr/lib for 32-bit systems, and the appropriate 64-bit library locations depending on operating system.
The vendor install software will write a line to /etc/hba.conf with the location of their vendor-specific library.
Vendors will install a vendor library, typically in the same location the vendor stores their driver software.

 

4.2.Where does the HBA API common library get installed?
On Windows systems:
HBAAPI.DLL is the common library, installed in %SYSTEMROOT%/SYSTEM32.
On Unix systems:
libHBAPAI.so is the common library, installed in /usr/lib for 32-bit systems, and the appropriate 64-bit library locations depending on operating system.
HP/UX (32-bit) links /opt/snia/api/lib/libHBAAPI.sl to /usr/lib
HP/UX (64-bit) links /opt/snia/api/lib/pa20_64/libHBAAPI.sl to /usr/lib
For LINUX32, LINUX64, and SPARC Solaris, we bundle our own HBA API library. Our installer will copy it to /usr/lib as libHBAAPISANtools.so. This was necessitated because we saw some inconsistencies between the API libraries bundled with Qlogic, Emulex, and JNI.  If you have installed the manufacturer's standard libHBAAPI.so file, and running one of these operating systems, that library will be ignored.  You must install the libHBAAPISANtools.so file in /usr/lib.  No entries will be required in the /etc/hba.conf file. If you have another application running that uses the standard libHBAAPI runtime,  it is not supposed to conflict.  If you discover an application that results in a conflict, please let us know.

 

4.3.Can I issue any arbitrary SCSI command with the HBA API?

No. The scope of the HBA API is limited to discovery of Fibre Channel components. Generic SCSI pass through has been discussed, but has been deemed generally dangerous, as it bypasses the operating system protections and also causes several SCSI-related issues (including problems with breaking reservations, potentially corrupting data, or interrupting I/O). As such it is not included in the API.

 

4.4.What is the difference between a platform WWN and a node WWN?
platform WWN - unique world-wide identifier for a computer system used to tie together in software the association between many components within that system
node WWN - unique world-wide identifier used to associate many port world wide names within a system. This is used currently in two ways: first, to specify the relationship between ports on a common device (one node WWN and several port WWNs on a HBA), secondly to identify ports on a system (one node WWN and many port WWNs on a system with many HBAs). Unfortunately the use of this is not consistent within currently deployed hardware.

 

4.5.What is persistent binding?

Persistent binding is a feature of HBAs which remembers the last SCSI address a particular Fibre Channel target has been mapped to. For example, that a port on a physical disk (world wide name 01:02:03:04:05:06:07, LUN 0) was last seen at SCSI address (bus=0,target=3,lun=0) on the operating system. Persistent binding ensures that this is consistent from reboot to reboot unless changed by the user.

 

Some HBA vendors automatically persistently bind devices, while others require manual configuration. Persistent binding is most important in the case of operating systems which remember devices by SCSI address or in the case of raw volumes used by databases.

 

5. Development Questions

5.1 What is the common HBA library?

The common library is a component of the HBA API, typically called HBAAPI.DLL or libHBAAPI.so which loads vendor specific library support for HBAs. (This library is specific to an operating system and is supposed to be bundled with the HBA API drivers supplied by your controller vendor. If that is not the case, please let both your HBA vendor know about this, as well as SANtools so we may work with your HBA vendor to supply the proper files and get them tested.)

 

5.2 What operating systems are supported by the HBA API common library?

The initial work on the HBA API was done on Windows NT, Windows 2000, and Solaris 2.6, 2.7, and 2.8. Other operating systems are also planned for support. (SPARC Solaris 7-9, Windows 2000/XP/2003, HPUX, and LINUX are available. Other operating systems may have them as well, but are not supported by SMARTMon-UX.)

 

5.3 Does the HBA API support asynchronous event notification?

Version 1.0 of the spec does not support asynchronous event notification, however this capability is a central part of Version 2.0 of the spec.

 

5.4 What is the maximum buffer size that can be passed to the common HBA function HBA_SendCTPassThru?

This is a vendor specific limitation and depends on the vendor of your HBA.  (It does not matter, we do not use this function call ... yet).

 

5.5 Why was the HBA_ResetStatistics call removed?

The HBA_ResetStatistics call was removed because it was decided that resetting statistics counters is an undesirable function. Because any application accessing the HBA API could reset statistics, this could potentially confuse other software monitoring statistics counters. (We did not implement this feature for obvious reasons).

 

6. Resources

6.1 Who is behind the HBA API standard?

During the first Storage Networking World conference with the HBA API demo the following vendors endorsed the HBA API Interoperability Theme: Adaptec, Agilent, BMC Software, Brocade, Connex, EMC, Emulex, FCIA, FibreAlliance, HP, Highground, Hitachi Data Systems, Interphase, InterSAN, JNI, Legato, McData, NCITS, Prisa, Qlogic, StorageNetworks, SNIA, Tivoli, TROIKA Networks, Veritas, and Vixel. Other vendors also have announced their support since that time.

 

6.2 What HBA vendors support the HBA API?

Agilent, Emulex, Interphase, JNI, and Qlogic, TROIKA Networks have all publicly announced their support for the HBA API. You should check with your individual vendor if they are not listed here.

 

6.3 Which HBA manufacturers/models have HBA API libraries available?

Below is just a subset of manufacturers and models which have downloadable SNIA libraries. You should check with your hardware vendor for current drivers and runtimes.

 

Vendor Name

HBA

Supported O/S

Contact

Emulex

Almost all

Windows, Solaris, LINUX

http://www.emulex.com

JNI

Almost all

Windows, Solaris, LINUX

http://www.jni.com/Drivers

LSI Logic

Almost all

Windows, Solaris, LINUX

http://adapters.lsilogic.com

TROIKA Networks

Zentai Z-2400+

Windows

http://www.troikanetworks.com

Qlogic Corp

QLA2100+

Windows, Solaris, LINUX

http://www.qlogic.com

ATTO Technology

ExpressPCI FC 3300

ExpressPCI FC 3305

ExpressPCI FC 2600

ExpressPCI FCSW

(and more)

Windows

http://www.attotech.com/software

Agilent Technologies

HHBA-5101C

HHBA-5121A

HHBA-5221A

HHBA-5220A

Windows

http://www.agilent.com

Hewlett-Packard

All Tachyon HBAs, rev B.11.00.10 or higher (except A3591B, A3404A, A3636A, A3740A)

HPUX 10.1 and above

HP Support (they are bundled with HPUX and the HBA cards) and available through the registered support site.

 

They are also part of the standard HPUX 11.0 and above O/S distribution CDROMs, and are pre-loaded on all systems.

 

SANtools-specific

7.1.What happens if the HBA API runtime is not installed on this system?

If you run the software with either the -fc, -fcping, or any other option that starts with "fc", the software will just report that there are non SNIA-supported HBAs attached to your system.  All of the other functionality relating to direct-attached fibre channel devices will be unaffected.

 

7.2.What if I have more than one make and/or model of HBA in my system?

Everything. It works just fine, provided all of the adapter-specific drivers are properly installed and configured.  If they are not, then the software simply will not report anything for the adapters that do not have the library files installed.

 

7.3 Where are the configuration files stored on my UNIX/LINUX machine.

The runtime library files are ordinarily stored in /usr/lib. The file, /etc/hba.conf instructs the library how to cross-reference the description of the card with the specific library file. See the below example:

 

# contents of file /etc/hba.conf

#

# This file contains names and references to HBA libraries

#

# Format:

#

# <library name>  <library pathname>

#

# The library name should be pre pended with the domain of

# the manufacturer or driver author.

org.snia.sample32          /usr/lib/libsample.so                

com.jni.fibrestar32        /usr/lib/libhbaapijni.so

com.qlogic.qla32                 /usr/lib/libhbaapiqla.so

com.emulex.lightpulse32    /usr/lib/libhbaapiemu.so

com.jni.fibrestar64        /usr/lib/sparcv9/libhbaapijni.so

com.emulex.lightpulse64    /usr/lib/sparcv9/libhbaapiemu.so

 

7.3 Where are the configuration files stored on my Windows-family PC?

Registry entries are made to provide the windows-specific implementation of the /etc/hba.conf file. The HBA library installers created by all the HBA vendors automatically do this for you.  They are also supposed to append additional entries for other HBAs as needed.