1

Jan 2014

NetApp Manageability SDK (NMSDK) 5.2Technical Overview

NetApp OnCommand® Product Portfolio

2

System Manager Report

Balance Insight

Unified Manager Workflow Automation

SnapManager®

Snap Creator Framework

NetApp Manageability SDK

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 https://

communities.netapp.com/community/interfaces_and_tools/developer/apidoc .

4

Platforms SupportedOperating 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

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.0HP-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

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

9

NetApp Storage System

ONTAP APIs over HTTP/HTTPS

OnCommand Unified Manager

OCUM APIs over HTTP/HTTPS

Application using NMSDK

Client

NMSDK API STRUCTURE

10

NMSDK

Cluster-Mode 7-Mode

Data ONTAP APIs

OCUM APIs

Product APIs Core APIs

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

13

Core APIs in C

– na_elem_*

– na_server_*

– na_child_*

– na_results_*

Core classes in Java

– NaServer

– NaElement

– NaAPIFailedException

Core classes in PERL

– NaServer

– NaElement

Core APIs in .NET

– NaServer

– NaElement

– NaException

– NaApiFailedException

Core APIs in Python

– NaServer

– NaElement

Core classes Ruby

– NaServer

– NaElement

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

14

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

Cluster-Mode APIs

Cluster APIs Vserver APIs

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 typeIndicates 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

20

Basic

NMSDK Programming

Basic elements of NMSDK : NaServer & NaElementNaServer

– 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 results22

Create Server Context on client

Create NaServerSpecify 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 login-password.– 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");

Invoke the API (sending command to server)– Invoke Core API always returns NaElement.

– Example in Java :

NaElement xo = s.invokeElem(api);

Display results – Example to get raw XML output in Java :

System.out.println(xo.toPrettyString(""));

25

Product API

Core API

Check for failures

Always check for API failures :– Catch exceptions– Check result status– Check if result is NULL (for example in C)

Example :

26

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)

Programming Use Case Flowchart

27

28

Tools for NMSDK Programmers

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

31

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

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

34

Troubleshooting

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

39

40

Tutorial exercises

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