Configuring SNIA HBA API Library

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:

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

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).

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

Version history:

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.

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.

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).

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.

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

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.

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.

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

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

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.

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.

SANtools-specific

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.

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.