1. NetApp Manageability SDK (NMSDK) 5.2 Technical Overview
Jan 2014

2. NetApp OnCommand® Product Portfolio
System Manager
Report
Unified Manager
Workflow Automation
Balance
Insight
NetApp Manageability SDK
SnapManager®
Snap Creator Framework
NMSDK is a bundle of open interfaces (APIs) that provides an infrastructure to develop applications to monitor and manage NetApp® storage system.
It enables integration with third party management tools, orchestration tools, or home-grown tools in your data center or cloud environment.

3. Product Offerings SDK Core API libraries.
ZExplore Development Interface (ZEDI) to test APIs, create sample codes, and create workflows in C#, C, JAVA, Perl, Python and Ruby.
Detailed documentation of APIs in Data ONTAP.
Detailed documentation of APIs in OnCommand Unified Manager.
Web Services support for OnCommand Unified Manager APIs.
Support to create PowerShell Cmdlets for Data ONTAP APIs and OnCommand Unified Manager APIs using .NET API Bindings.
Support for Java Bindings for both Data ONTAP APIs and OnCommand Unified Manager APIs.
Sample codes, Developer Tools and Design Guides.
Latest APIs documentation (ONTAP/OCUM) is available at veloper/apidoc .

4. Platforms Supported Operating System Version Windows 32bit 2003, 2008
Windows 64 bit (x64, IA64)
Windows x64
2008 R2, 2012
Red Hat Linux (32 bit and 64 bit)
V5, V6
Oracle Enterprise Linux
4.0, 4.8, 5.4, 5.5, 5.6, 5.7,5.8,6.0,6.1, 6.2 and 6.3
SUSE Linux (32 bit and 64 bit)
10.0, 11.0
Solaris SPARC 32 bit and 64 bit
10.0 and 11
Solaris x86 32 bit
10.0
Solaris x64-bit
AIX (32 bit and 64 bit)
5.2, 5.3, 6.1, 7.1
HP-UX PA-RISC 32 bit
11.11 and later
HP-UX IA64 64 bit
B and later
VMware ESX server
3.5, 4.0, 4.1
VMware ESXi server
5.0, 5.1
FreeBSD (64-bit)
8.0

5. Languages Supported Language/Environment Software Requirements C/C++
Visual Studio 2005 and 2010 for windows
To compile applications on a 32-bit UNIX-like environment, use GNU Make and GNU C/C++ Compiler.
To compile applications on the 64-bit UNIX-like environment, use GNU C/C++ Compiler 3.2 or later.
Java
Sun Java SDK 1.4, 5.0, 6.0, 7.0
HP-UX Java 1.4, 5.0, 6.0, 7.0
AIX Java 1.4, 5.0, 6.0, 7.0
Perl
Perl 5.8, 5.10, 5.16
C#, VB.NET and PowerShell
Microsoft .NET Framework 2.0, 3.0, 3.5, 4.0 PowerShell 1.0, 2.0
.NET Bindings for PowerShell Cmdlets
Microsoft .NET Framework 2.0, 3.0, 3.5, 4.0
Python
Python 2.4.x, 2.5.x, 2.6.x, 2.7.x, 3.1.x, 3.2.x, 3.3.0
Ruby
Ruby 1.8.7, 1.9.2, 1.9.3, 2.0

6. Features
Provides access to Data ONTAP features (both 7-Mode and Clustered ONTAP) through APIs.
Provides access to all capabilities of OnCommand core package through APIs.
Operations Capability
Performance Advisor
Provisioning Capability
Protection Capability
Supports multiple transport protocols :
HTTP, HTTPS and Windows RPC
Supports different authentication mechanisms
login/password, host.equiv, Windows RPC authentication and Certificate based authentication

7. Features Dynamic Library feature for C and C++
SDK core APIs are a small set of immutable Core APIs
Easy to learn API programming
The existing core APIs ideally do not get changed, there may be new additions though.
Easy to add new ONTAP API commands
Simple to use APIs
XML based request/response mechanism
XML type name-value pair arguments

8. Features Role Based Access Control (RBAC) support
Make use of RBAC in Data ONTAP and Operations Manager
ONTAP API access can be restricted as per the user from Data ONTAP 7G
Multithreading
NMSDK APIs are Thread-safe
Faster integration and storage abstraction by leveraging policy based management tools as point of integration
Policy-based efficient storage provisioning
Policy-based data protection
Operational Monitoring

9. Architecture NetApp Storage System Client OnCommand Unified Manager
ONTAP APIs over HTTP/HTTPS
Application using NMSDK
OnCommand Unified Manager
OCUM APIs over HTTP/HTTPS
Client

10. NMSDK API STRUCTURE NMSDK Product APIs Core APIs Data ONTAP APIs
OCUM APIs
Cluster-Mode
7-Mode

11. Product APIs (ZAPIs)
Product API requests and responses are XML messages transmitted over HTTP(S)
Conceptually similar to SOAP
Product APIs follow NetApp proprietary protocol - Zephyr.
Zephyr API = ZAPI
Includes ONTAP API (ONTAPI) and OnCommand Unified Manager (DFM API)
ZAPI requests and responses are programmatically handled in the form of a structure named “element”, also known as NetApp Element (NaElement or na_elem).

12. Core APIs Core APIs are language specific interfaces to
Create and manage the input/output elements [na_elem/NaElement]
Connect to API server and invoke a well-formed API request [na_server/NaServer]
Read the responses and invocation status [na_results/NaElement]
Core APIs independent (loosely coupled) of individual ZAPIs, but compliant to Zephyr protocol.

13. Core APIs Core APIs in C na_elem_* na_server_* na_child_* na_results_*
Core classes in Java
NaServer
NaElement
NaAPIFailedException
Core classes in PERL
Core APIs in .NET
NaServer
NaElement
NaException
NaApiFailedException
Core APIs in Python
Core classes Ruby

14. What has changed from 7-Mode
Cluster-Mode APIs
Cluster APIs
Vserver APIs
Cluster APIs (Cluster admin)
Vserver APIs (Vserver admin)
Connects to cluster management IP
Used for administrating entire Cluster
Can administer Vserver by using Vserver tunneling
Optionally can delegate the administration of the Vserver to a Vserver administrator
Connects to Vserver IP
Can only use APIs listed in Vserver context
What has changed from 7-Mode
Iterative APIs – Single iter API in Cluster-Mode compared to 3 APIs in 7-Mode
Article and Sample code for iterative APIs are part of NMSDK
Design Guide for basic Cluster-Mode tasks using APIs

15. Configurable Session Parameters
SDK provides flexibility for the clients to configure the session parameters
Following session parameters are configurable
Server type
Server style
Transport type
Server port
These session parameters are persistent till the session is closed

16. Configurable Session Parameters : Server type
Indicates the target appliance for API calls
It can be set to :
FILER
API calls to NetApp Storage system
DFM
API calls to NetApp OnCommand Unified Manager

17. Configurable Session Parameters : Server Style
Indicates the authentication mechanism to be used for communicating with the Server
It can be set to
Remote Procedure Call (RPC)
Available only on Windows
Uses native Windows authentication and authorization. Available only for Data ONTAP APIs
hosts.equiv
Available only for Data ONTAP APIs
Authenticates against the /etc/hosts.equiv file on the filer
hosts.equiv file entries are in the following format : Hostname [User name]
Requests coming from the named host and the named user are allowed in as root
login-password
Authenticates against the user provided login/password details
Certificate
Available only for OnCommand Unified Manager APIs
Authenticate clients who attempt to connect to a server, without using login credentials

18. Configurable Session Parameters : Transport type
Indicates the transport mechanism to be used for sending API commands
It can be set to
HTTP
Default transport type
Must use login-password/hosts.equiv mechanism for authentication
HTTPS
Similar to HTTP connection
Provides secure communication by encrypting the API requests/responses

19. Default Session Parameters
Server Type
FILER
Transport Type
HTTP
Server Style (authentication mechanism)
Login-password
Server Port 80
User
root

20. NMSDK Programming
Basic

21. Basic elements of NMSDK : NaServer & NaElement
Specify connection options
Create a connection to a Data ONTAP storage system or OnCommand Unified Manager.
Issue API requests
NaElement
Pack and unpack data that is sent to and from the server
Allows multiple values and nested values

22. Basic Algorithm to start programming
Set the reference to NMSDK library
Create a server context on client : create a NaServer with IP address of server and ONTAP version (use version as 1 if unknown)
Set session parameters (server type, transport type, authentication style, etc )
Create NaElement(s) i.e. build API
Send command to server : Invoke API on NaServer element
Display results

23. Create Server Context on client
Create NaServer
Specify Server details
IP address or fully qualified domain name of server
Product API version (Enter 1 for major version and 0 for minor version if unknown)
Example : In Java.
NaServer s = new NaServer(“<my IP address>", 1 , 0);

24. Set Session Parameters
Set Server Type
FILER : Data ONTAP system.
DFM : OnCommand Unified Manager (OCUM)
Example : In Java : s.setServerType(NaServer.SERVER_TYPE_FILER);
Set Transport mechanism : HTTP or HTTPS
Example : In Java : s.setTransportType(NaServer.TRANSPORT_TYPE_HTTPS);
Set Login Style : RPC, Certificate, hosts.equiv or login- password.
Example : In Java : s.setStyle(NaServer.STYLE_LOGIN_PASSWORD);
s.setAdminUser(“<username>", "<password>");

25. NaElement and sending command to server
Create NaElement
Example in Java :
NaElement api = new NaElement("system-get-version");
Invoke the API (sending command to server)
Invoke Core API always returns NaElement.
NaElement xo = s.invokeElem(api);
Display results
Example to get raw XML output in Java :
System.out.println(xo.toPrettyString(""));
Product API
Core API

26. Check for failures Always check for API failures : Example :
Catch exceptions
Check result status
Check if result is NULL (for example in C)
Example :
Java (try/catch)
Python (result status)
try {
NaServer….
NaElem… }
catch (NaException e)
handleException(e);
} catch (UnknownHostException e)
} catch (IOException e)
if (xo.results_status() == "failed") :
print ("Error:\n")
print (xo.sprintf())
sys.exit (1)

27. Programming Use Case Flowchart

28. Tools for NMSDK Programmers

29. ZExplore Development Interface (ZEDI)
ZEDI is a GUI tool that is bundled with NMSDK. It allows you to connect to Data ONTAP servers or OCUM and test APIs on them.
ZEDI lists APIs and generates code automatically for the APIs chosen hence reducing developer burden.
ZEDI can be used to make/save new workflows and use pre-existing workflows to perform a series of commonly done tasks easily.

30. ZExplore Development Interface (ZEDI)

31. APITEST Command Line utility to try out both Data ONTAP and OCUM APIs
Command syntax :
apitest {options} <host> <user> <password> <API> [ <paramname> <arg> ...]
Command details
Description
apitest
The command name.
options
An optional parameter.
See the table on right for more information.
host
The host name or IP address of the server.
user
The user name.
password
The corresponding password.
API
The name of the API.
paramname
The input element of the API.
arg
The value of the input element.
Options
Description -i
API specified as XML output, on the command line. -I
API specified as XML output, on standard input. -t
Server type.
Following are the possible values:
filer
dfm
agent -v
The vFiler unit name or the Vserver name, if the API has to be executed in the context of a vFiler unit or a Vserver respectively. -r
Uses RPC transport.
Does not support Data ONTAP C-Mode APIs -s
Uses SSL. -p
Overrides port to use. -x
Shows the XML input and output. -X
Shows the raw XML input and output. -h
Authenticates hosts using the hosts.equiv file. -c
Sets the connection timeout.

32. Limitations

33. Limitations NMSDK will support only UTF-8 character encoding format.
ZEDI does not support .NET family of languages.
IPv6 is not supported on the Perl versions earlier than 5.14.
Certificate-based authentication is supported only on the following Python versions:
Python and later, Python and later, and Python 3.2 and later.

34. Troubleshooting

35. Troubleshooting Help Tools bundled with the SDK: External tools:
apitest : CLI tool to test APIs
ZEDI - GUI tool to test APIs, create workflows and do more complicated tasks.
External tools:
Evt2Txt (
This tool converts the Data ONTAP generated event file to text format.
Coregdb (/usr/local/bin/coregdb, core dump analysis tool)
Ethereal ( , network analysis tool)
Documents (Part of SDK Help)
Version Matrix
Release History
Known issues
API documentation
Troubleshooting Guidelines
Frequently Asked Questions

36. Logs Audit Logs EMS Logs Syslog
Provides Data ONTAP API invocation history
Located at /etc/log/auditlog
For OCUM, you can find the invocation history at :
<dfm-server-install-directory>/log/
EMS Logs
Provides Data ONTAP API processing information
Located at at /etc/log/ems
Syslog
Provides Data ONTAP API error messages
Located at /etc/messages
DFM server Logs
Provides error logging information about OCUM APIs.
Located at <dfm-server-install-directory>/log/

37. Troubleshooting Example – 1
Scenario :
While requesting large data, the client application does not receive complete data from the Data ONTAP API or the DataFabric Manager APIs for the OnCommand Package, and the application does not receive any error message.
Possible Causes:
The server takes a longer time to process the request because of the large amount of data. This might trigger the server to reset the connection.
The reset packets are received at the transport layer of the client host, which is not handled at the API layer of the client application. In this case, the client does not receive the relevant error code.
Diagnosis:
Begin a TCP packet trace using tools such as Ethereal, and check for any error messages from the server.
Workaround:
Increase the connection timeout at the server.
Use the iterative APIs when requesting a large amount of data (for example,  thousands of qtrees).

38. Troubleshooting Example – 2
Scenario :
'No such file or directory' (error number: 13001)
Possible Causes:
There is a problem in the API handler code in Data ONTAP.
The application is sending the wrong input (for example, the wrong iteration tag input to the iterative APIs).
Race condition in the iterative APIs.
Diagnosis:
Check the Audit Log (/etc/log/auditlog) for API invocation history. It hints about possible concurrent calls of APIs leading to race conditions.
Check the EMS Log (/etc/log/ems) for any errors that occurred while processing the API requests (for example, the wrong iteration tag).
Workaround:
Upgrade to Data ONTAP 7.3. Race condition of the iterative APIs issue is fixed in Data ONTAP 7.3.

39. Troubleshooting Example – 3
Scenario :
The client application hangs.
Possible Causes:
The server reboots during API processing and the application is using blocking connection APIs.
Network failure between the client and the server.
Diagnosis:
In case of a failed Data ONTAP API call, check uptime of the storage system (using the uptime command). If the uptime indicates that the storage system booted recently, then check whether there was a recent crash in the core file at /etc/crash/core-*.
In case of a failed call for DataFabric Manager APIs for the OnCommand Package, check if there was a crash recently at the core file in <dfm-server-install-directory>/log/core-*.
If there is no crash or no API-related message in the crash stack trace, then it might be a power failure or a network-related problem.
Workaround:
Restart the client application.
Use non-blocking calls in C.
For Data ONTAP API, use the set-time-out() function to change blocking connection API to non- blocking connection API.
For DataFabric Manager APIs for the OnCommand Package, you can use the na_server_set_timeout() function to change blocking connection API to non-blocking connection API.

40. Tutorial exercises

41. Tutorial Exercises
Install ONTAP simulator and get API version on the simulator using zexplore tool
Hint: Use the command ‘system-get-ontapi-version’
Create a Flexvol using apitest.exe tool and then check the volume using System Manager
Hint: Get the list of aggregates on the NetApp storage system with ‘aggr-list-info’ command
Create the flex-volume on one of the aggregates with the command ‘volume-create’

42. SDK Support Channels
SDK Discussion Forum :
This is the preferred way to get support
Use this for non-confidential queries and issues regarding the SDK
SDK mailing list:
Use this dl for posting any confidential info
NetApp Global Support (NGS)
SDK customers and end customers of partner products can contact NGS to log issues related to SDK
NGS does not offer support on SDK usage during solution development