NetApp
Manageability SDK
(NMSDK) 5.2
Technical Overview
Jan 2014
1
NetApp OnCommand® Product Portfolio
 System Manager
 Report
 Balance
 Insight
 Unified Manager
 Workflow Automation
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 homegrown tools in your data center or cloud environment.
2
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
https://communities.netapp.com/community/interfaces_and_tools/de
veloper/apidoc .
3
Platforms Supported
Operating System
Version
Windows 32bit
2003, 2008
Windows 64 bit (x64, IA64)
2003, 2008
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
10.0
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.11.31 and later
VMware ESX server
3.5, 4.0, 4.1
VMware ESXi server
5.0, 5.1
FreeBSD (64-bit)
8.0
4
Languages Supported
Language/Environment
C/C++
Software Requirements
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
5
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
6
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
7
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
8
Architecture
NetApp Storage System
ONTAP APIs over
HTTP/HTTPS
Application
using
NMSDK
Client
OCUM APIs over
HTTP/HTTPS
OnCommand Unified
Manager
9
NMSDK API STRUCTURE
NMSDK
Product
APIs
Core APIs
Data ONTAP
APIs
Cluster-Mode
OCUM APIs
7-Mode
10
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).
11
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.
12
Core APIs
 Core APIs in C
 Core APIs in .NET
– na_elem_*
– NaServer
– na_server_*
– NaElement
– na_child_*
– NaException
– na_results_*
– NaApiFailedException
 Core classes in Java
 Core APIs in Python
– NaServer
– NaServer
– NaElement
– NaElement
– NaAPIFailedException
 Core classes in PERL
 Core classes Ruby
– NaServer
– NaServer
– NaElement
– NaElement
13
Cluster-Mode APIs
Vserver APIs
Cluster APIs
Cluster APIs (Cluster admin)
Vserver APIs (Vserver admin)
•
Connects to cluster management IP
•
Connects to Vserver IP
•
Used for administrating entire Cluster
•
Can only use APIs listed in Vserver
context
•
Can administer Vserver by using Vserver
tunneling
•
Optionally can delegate the administration
of the Vserver to a Vserver administrator
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
14
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
15
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
16
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
17
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
18
Default Session Parameters
 Server Type
– FILER
 Transport Type
– HTTP
 Server Style (authentication mechanism)
– Login-password
 Server Port
– 80
 User
– root
19
NMSDK
Programming
Basic
20
Basic elements of NMSDK : NaServer &
NaElement
 NaServer
– 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
21
Basic Algorithm to start programming
1. Set the reference to NMSDK library
2. Create a server context on client : create a
NaServer with IP address of server and
ONTAP version (use version as 1 if
unknown)
3. Set session parameters (server type,
transport type, authentication style, etc )
4. Create NaElement(s) i.e. build API
5. Send command to server : Invoke API on
NaServer element
6. Display results
22
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);
23
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 loginpassword.
– Example : In Java :
s.setStyle(NaServer.STYLE_LOGIN_PASSWORD);
s.setAdminUser(“<username>", "<password>");
24
NaElement and sending command to
server
 Create NaElement
– Example in Java :
NaElement api = new NaElement("system-get-version");
Product API
 Invoke the API (sending command to server)
– Invoke Core API always returns NaElement.
– Example in Java :
NaElement xo = s.invokeElem(api);
Core API
 Display results
– Example to get raw XML output in Java :
System.out.println(xo.toPrettyString(""));
25
Check for failures
 Always check for API failures :
– 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)
{
handleException(e);
} catch (IOException e)
{
handleException(e);
}
if (xo.results_status() == "failed") :
print ("Error:\n")
print (xo.sprintf())
sys.exit (1)
26
Programming Use Case Flowchart
27
Tools for NMSDK
Programmers
28
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.
29
ZExplore Development Interface (ZEDI)
30
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.
Options Description
-i
API specified as XML output, on the command line.
-I
API specified as XML output, on standard input.
-t
-s
-p
-x
-X
-h
Server type.
Following are the possible values:
•filer
•dfm
•agent
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.
Uses RPC transport.
Does not support Data ONTAP C-Mode APIs
Uses SSL.
Overrides port to use.
Shows the XML input and output.
Shows the raw XML input and output.
Authenticates hosts using the hosts.equiv file.
-c
Sets the connection timeout.
-v
-r
arg
The value of the input element.
31
Limitations
32
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 2.6.6 and later, Python 3.1.3 and later,
and Python 3.2 and later.
33
Troubleshooting
34
Troubleshooting Help
 Tools bundled with the SDK:
–
apitest : CLI tool to test APIs
–
ZEDI - GUI tool to test APIs, create workflows and do more complicated
tasks.
 External tools:
–
Evt2Txt (http://now.netapp.com/NOW/download/tools/evt2text)

This tool converts the Data ONTAP generated event file to text format.
–
Coregdb (/usr/local/bin/coregdb, core dump analysis tool)
–
Ethereal (http://www.ethereal.com/ , network analysis tool)
 Documents (Part of SDK Help)
–
Version Matrix
–
Release History
–
Known issues
–
API documentation
–
Troubleshooting Guidelines
–
Frequently Asked Questions
35
Logs
 Audit Logs
– 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/
36
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).
37
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.
38
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 nonblocking 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.
39
Tutorial exercises
40
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’
41
SDK Support Channels
 SDK Discussion Forum : http://developer.netapp.com
– This is the preferred way to get support
– Use this for non-confidential queries and issues regarding the SDK
 SDK mailing list: dl-sdk-answers@netapp.com
– 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
42
43