Using the APIs

Accessing commands through WS-API can be done through a Web browser, by constructing an appropriate URL, or programmatically through a machine-generated library that supports the SOAP HTTP Client Protocol. Examples of these are provided in the notes listed below and in an example client application written in C# that is included in the StorNext installation package.

The available WS-API commands and the structure of their arguments and parameters are defined in the Web Service Definition Language file (WSDL) for StorNext, which is available from the StorNext Metadata Controller (MDC). The StorNext WSDL file can be displayed by entering the following URL in the address window of a web browser:

http://<MDC>:81/axis2/services/stornext?wsdl

Microsoft Visual Studio provides a menu selection for adding a "Service Reference" to the WSDL, which gleans the interfaces from the WSDL to aid programmers. Visual Studio also provides a wsdl.exe command that can generate source code in supported programming languages for compiling into a dynamic-link library (DLL) that supports the SOAP HTTP Client Protocol. Instructions for doing this are included in the example client code provided with StorNext. The sample WS-API client-application code, written in C# for Visual Studio on Windows, is included in StorNext distributions for MDCs. The following pathname displays a typical location for the file:

/tmp/stornext/stornext_full/RedHat50AS_26x86_64/examples/SNAPITest.zip

In order to perform any command on the remote server (except for the getSNAPIVersion call), a matching password must be specified with the call. The server verifies this password against the one stored in the
/usr/adic/.snapipassword file on the server.

Make sure this file is the same on all metadata controllers (MDCs) you will be accessing. This is especially important if you are using virtual IP (vIP) addresses, because you can be communicating to different machines across different API calls or even retries of the same call.

The .snapipassword file is stored as clear text, and it should be set to be readable only by root. If this file does not exist, no calls other than getSNAPIVersion will succeed.

Using APIs With the High Availability MDC Feature

The StorNext High Availability MDC Feature (HA) uses a pair of redundant MDCs to maximize the availability of StorNext file systems. Under normal operation, one of the MDCs is the Primary server for all Storage Manager processing, and the Secondary server is ready to take over operations if the Primary server stops. This is called an HA Failover.

The Virtual IP Address (vIP) is a feature of StorNext HA which allows using a single IP address to automatically connect with whichever MDC is currently Primary. Using the vIP for WS-API calls simplifies development of client code. However, a client application must handle some transitional behaviors that occur during an HA Failover.

During an HA Failover, there is typically a delay of one to two minutes between the stop of the original Primary MDC and the transition of the Secondary MDC to full Primary MDC status. The former Primary MDC can stop abruptly without closing TCP/IP connections. For a period of time after that, attempts to make new connections to the vIP will fail until the new Primary brings up the vIP interface. Next is a period of time when the MySQL database has not fully started. Finally, there is a period when TSM has not fully started. Each of these periods presents a different type of error to the client application.

When using WS-API with a StorNext High Availability (HA) cluster, the following notes apply:

Configure a Virtual IP Address (vIP). The vIP is a static IP address that is automatically configured as a virtual interface on the Primary MDC. The vIP allows a client application to use a single IP address to locate the WS-API server.

Set a timeout that allows a client application to recover if it was connected to a server that stopped abruptly. (Since the client software is responsible for setting a timeout, the actual method of specifying a timeout value on each Web service request varies. Check with your client documentation for specific instructions.)

Stores and retrieves to tape may take longer than the timeout, but they will continue to run to completion if they can. Store and retrieve requests can also be submitted multiple times without impacting in-process transfers. When the transfer completes, all the identical requests will complete and return status if there is still a connection to the requestor.

When a request fails because the vIP server is not available, MySQL is not running, or TSM is not fully started, wait a few moments and retry the request.

The WS-API Server does not time-out until the target command completes with either success or failure. The Client application's Microsoft .NET SoapHttpClientProtocol class has a Timeout property with a default of 100 seconds. This is more than enough for status-type requests, but it is too short for tape-transfer-type requests, which are dependent on file size, system configuration and contention for resources. For example, a 100 GB file transferring at 100 MB/s will take about twenty minutes to complete. Setting the SoapHttpClientProtocol Timeout property to -1 is equivalent to infinity.