Introducing the Manage ONTAP™ Developer SDK

This file is essentially an expanded version of the top-level README file for this SDK. If you like high-speed downloads, stick with the README file. If you would prefer more detail on each of the ONTAPI interfaces and what they are for, this document may help you.

The Manage ONTAP SDK contains resources necessary to develop third-party applications which monitor and manage Network Appliance® appliances. The kit contains libraries, code samples and bindings in C and Perl for the new ONTAPI™ programming interface set.

A filer simulator which runs on Linux or Solaris, that simulates the filer to a very low level, is also available as a separate distribution on the NOW site. It is not included in the SDK however

Manage ONTAP contains information and resources for of a number of API sets

• ONTAPI™ management APIs (ONTAPIs for short)
• SNMP variables and traps
• NDMP (Network Data Management Protocol)
• Windows standard APIs
• FPolicy™ RPCs
• syslog
• Windows audit logs
• rsh and telnet interfaces to the ONTAP CLI

ONTAPI client libraries are included so you can access the ONTAPI interfaces. The ONTAPI management API set is a proprietary set of interfaces which are the recommended API set for all client management-oriented access to the filer that is not covered by other well-known standards. Network Appliance is committed to this library, particularly with respect to unique capabilities of Netapp products which are not covered by other developing standards.

The MIB files used by Data ONTAP are in the doc/mib folder.

Data ONTAP® itself supports many Win32 APIs used by Windows for management and monitoring of the file server. As these are contained in standard Windows libraries, they are not included in Manage ONTAP, but a discussion of supported Win32 APIs may be found in the doc/Win32 folder of the distribution.

Manage ONTAP includes information about the FPolicy interfaces, which presently runs over DCE/RPC. Using this, third party applications can register as a file policy scanner. An almost unlimited control over file access via CIFS and NFS can be achieved with this revolutionary patent-pending API.

The filer also supports a VPolicy interface for virus scanning. This interface is documented separately from the SDK, and is available to partners whose product suites include virus scanning.

Syslog and the Windows audit log formats are supported by Data ONTAP. Documentation on using them is in the doc folder.

While the product documentation and sample code is primarily focused on C/C++, perl libraries and a subset of the sample programs in Perl are also provided.
Java support, with client libraries and limited sample code, was introduced in version 1.2 of the SDK.

Finally, simulators for the Network Appliance filer are provided as a separate distribution on the NOW site. These allow you to test against the Network Appliance product suite using the same tools that Netapp developers use. You can run multiple copies of the simulators when you need to test scenarios in which there are multiple appliances.

The following table lists common tasks that management applications might perform, along with recommendations on which API set(s) to use. These will be explained in more detail later.

Filer/Netcache discovery	SNMP
Network and overall system health monitoring	SNMP
On-demand virus scanning	vpolicy
On-access file filtering, access control and so on	fpolicy
Backup and data migration	NDMP
Management of standard CIFS features such as shares, directories, and file permissions	Win32 API
Security analysis	syslogs, Windows audit log
Management of Netapp-specific functionality such as SnapMirror®, snapshots, quotas and so on	ONTAPI
Command-line tasks not covered by any other API	rsh, telnet

Description of the APIs

This section describes each of the API sets and provides links to sample code and documentation.They are ordered roughly by the significance Network Appliance expects each of them to assume as Manage ONTAP matures.

ONTAPI management APIs

Each of the other API sets in Manage ONTAP have a fairly well-defined role and set of responsibilities. They do not, however, address all the unique functionality offered by Network Appliance products. There are no industry standard APIs at present for managing snapshots and qtrees, for example.The ONTAPI interface set exists to fill this hole. It is, however, designed to play well with emerging storage management standards.

ONTAPI functions are guaranteed by the Manage ONTAP program to remain backward compatible for the life of the API and the major version of the SDK. When APIs must be updated, the new versions will use new names, take new optional parameters, or in some other way arrange to provide new functionality only to those clients which expect it. Major and minor version numbers will be provided for this purpose. Anytime new APIs are introduced, new optional parameters for existing APIs become available, and so on, the minor version number will be incremented. Major version number changes are reserved for incompatible architectural changes, and are not expected in the near future.

The ONTAPI interface is the foundational API for Network Appliance products moving forward. We value your input. Please contact your Network Appliance representative with suggestions and issues.

SNMP is a well-known standard for network monitoring. Its original design included provisions for management as well, but that part of the protocol has never achieved critical mass in the industry. Many top-shelf network management applications make heavy use of SNMP for monitoring purposes, however.

To use SNMP, you must know the “OID” of the variable you desire. The MIB (Management Information Base) is an ASCII document which describes each variable, such as “sysDescr”, and assigns it an OID. The MIB document format is by design readable by both machines and humans. The filer has an extensive MIB, which is included in the doc directory of the distribution. The MIB format, however, does not make it easy to determine the OID of a given variable, as it is specified in terms of a “parent” variable. For this reason, we have included a file called traps.dat (but see the notes on versions) which lists each of the SNMP variables supported by Data ONTAP and the complete OID required to access it. This file, originally intended for users of the snmp traps command, prepends “snmp” to each OID, which should be ignored when using snmpget or snmpwalk. Network Appliance products also implement the MIB specified in RFC 1213. The MIB which implements this RFC describes the networking aspects of a machine and is widely used. You can view it here. (You may need to set a file type in your browser first). New features in Netapp appliances are generally documented and reported via SNMP in the major release in which they are introduced. Therefore, the MIB is always growing. Network Appliance Engineering has the goal of reporting as much as possible about an appliance via the MIB.

SNMP OIDs The OID space is tree structured. An OID such as .iso.org.dod.internet.mgmt.mib2. system.sysDescr.0 (which translates to .1.3.6.1.2.1.1.1.0) can be read much as you would read a filesystem path. The sysDescr variable lives within the system space, which is contained in the mib2 space, which is contained within mgmt, and so on. When the last number is a zero, it means that a single value is requested. Integers above zero are requests for individual elements in tables. The snmpwalk function is useful for learning about OIDs and how they relate to query output and the entries for them in the MIB. An snmpwalk of .1.3.6.1.2, for example, will return a slew of information about the appliance’s TCP/IP state. An snmpwalk of 1.3.6.1.4.1.789.1 will return all the entries in the Network Appliance MIB.

The full SNMP protocol specifies GET, SET and TRAP operations. For security reasons, Netapp products do not support SET operations.

 

When possible (and within the scope of file serving), Netapp filers emulate Windows servers by implementing the underlying management RPCs. Additionally, the redirector on Windows CIFS clients translates many Win32 API calls, such as _mkdir(), WriteFile(), CreateDirectory() and so on, into SMB requests which are handled by the CIFS protocol code on the filer. The SDK includes a list of Win32 APIs supported by the Netapp filer. While we have done our best to make this list comprehensive, it is hard to be completely sure that it in fact is, as there is no one-to-one mapping between many Win32 APIs and the actual RPC and SMB calls that the filer sees on the wire. When in doubt about whether a Win32 API not on this list is supported on the filer, the best thing to do is to add the call in question to a working Win32 application, and see if the call succeeds. Support for additional Microsoft APIs is added regularly by ONTAP developers, as new needs arise. Netapp is a partner of Microsoft and a licensee of it's interfaces.

CIFS and DCE/RPC CIFS (Common Internet File System) is the file-sharing protocol used natively by Microsoft Windows computers. CIFS requests are formatted on the wire as SMBs (Server Message Blocks). A client that wishes to read a file sends SMBs to set up a session, authenticate, and finally read the file. SMB requests can be decoded with the Netmon utility bundled with Windows, or the popular ethereal TCP/IP analyzer. DCE/RPC provides Remote Procedure Call services for Microsoft clients and servers. When you make a Win32 call such as NetFileEnum(), the system calls an RPC function called NetrFileEnum(). This is a “stub” routine that marshalls the arguments into a canonical wire format, and sends it via TCP/IP to the server. Similar stub code on the server unmarshalls the arguments into variables of the same type as the client sent, computes a reply, marshalls the reply onto the wire and sends it back. Finally, the stub code on the client unmarshalls the reply and fills in the appropriate variables, which then get passed back to the API call.

NDMP

 

NDMP (Network Data Management Protocol) was originally developed by Network Appliance and Legato Corporation as a standard for controlling network-based backups of file servers to tape servers and jukeboxes. Numerous other vendors now offer NDMP support. NDMP is true to its roots, in the sense that it is primarily useful for writing backup applications. It is at present the only protocol supported by Network Appliance for this purpose. No ONTAPI interfaces for performing backup tasks are presently included in the SDK.

NDMP — Network Data Management Protocol NDMP (homed at www.ndmp.org) is a data management protocol designed to move data from primary to backup servers without incurring load on the management client. Servers implement a connect interface for authentication and versioning, a configure interface for discovery of server configuration parameters, a data interface for initiating backups and restores, a tape interface for controlling tape drives and a scsi interface for controlling jukeboxes and so on. Backup software applications implement a notify interface which provides callbacks from the servers being controlled, a file history interface for use in later retrieval and a logging interface for monitoring progress and diagnosing problems. Actual data copying is server-to-server (e.g. filer to jukebox). Later versions of the protocol have support for advanced features which allow backup to multiple tapes and so on. The ndmpcopy program, available in source format from www.ndmp.org, makes use of Netapp-specific extensions to let you copy data directly from one filer to another.

Fpolicy and vpolicy

 

Fpolicy Fpolicy is an RPC-based mechanism that provides 3rd party control over CIFS file accesses to Network Appliance filers. Management applications register themselves as fpolicy servers with the filer. After this, every specified file access is given, via RPC, to the server for verification that the access is allowed. To use these RPCs, include the provided IDL files with your code, compile them with the Microsoft MIDL compiler as noted in the instructions (or create a subproject for them as shown in the sample code), and include the resulting stub files in your project. Once registered, your client will receive notification of every CIFS file access and have the opportunity to deny or allow access. Security is provided by standard NT security; the user invoking the application must have backup operator privilege on the filer. Network Appliance anticipates significant enhancements in fpolicy functionality over subsequent releases. Please talk to your Advantage Developer representative or send mail to sdk-feedback@netapp.com if you have requirements in this area. Vpolicy Vpolicy is an interface (a.k.a. vscan), also based on DCE/RPC, that was developed at Network Appliance as a means of doing on-access virus scanning without tying the system to one anti-virus (AV) package or vendor. So far, several leading antivirus vendors have modified their products to provide vscan services for filers.

The fpolicy interface Fpolicy is a simple RPC-based mechanism. The sequence of operations looks like this: (1) Fpolicy server registers with filer (future: multiple policies allowed) (2) Filer sends RPC with path and file info to fpolicy server upon client file requests: DOT 6.4: CIFS open, create, rename DOT 6.5: CIFS delete, close DOT 7.0: most NFS ops (inode number only, no path) (3) Server checks for file extension and optionally opens file via fopen() or equivalent and scans for matter of interest (4) Server rewrites file if desired. (5) Server returns success or failure (6) Filer denies access on failed return, allows access on success

The vpolicy interface is not at present included in the SDK, but it is available on request to established antivirus developers. Please see your Advantage Developer representative if you have virus scanning requirements and need access to this interface.

Filers and NetCaches log a plethora of system events to files in the /etc/log directory. System options allow you to specify file size, wraparound method and so on. The SAG (System Administrator's Guide) for each appliance is the best place to find authoritative info on how these are set up. Log files are usually inspected via scripts or other client program code. To do this, copy them to the client for analysis, or analyze them in place. The client program must have root access to the appliance to access the files, as they are kept in the /etc system directory.

It’s also possible to set up syslog to forward events to a syslog host, which could be your client management host. In this case, you can inspect the logs as they are generated, store them locally or remotely for security purposes, and so on. See the SAG or the man pages for syslogd for details on how to set up syslog in this way. A short document about syslog contains links.

Win32 Event Log

Filers also log security events to an NT event log. To view this log manually, use the event viewer and select the “Open Log File” item from the Action menu, then browse to the /etc/log directory and select the adtlog.evt file (the name of this file is configurable by an option). If your application understands the event log file format, treat the log on the filer as if it were a system log from a Windows machine. A short document about Windows logging contains links.

Historically, 3rd party applications and scripts have often resorted to rsh or telnet to execute commands on the filer or netcache, and then parsed the results if information was needed back. The biggest problem with these interfaces is command line interface (CLI) change. While Network Appliance makes every effort not to break existing scripts with CLI changes, this is at times unavoidable. Using the ONTAPI interface, on the other hand, gives you strict control over which semantics you use, as API functions are guaranteed to be backward compatible within major versions, and you have control over which version of the interface you use.

Links are in this document about using rsh and telnet.

Each major release of the ONTAP operating system provides interfaces, such as the MIB, ndmp and ONTAPI, which are supersets of the interfaces provided in earlier releases. The chart at ONTAP_Interface_Versions.html contains links to the versions of various interfaces and lists correspondences to major ONTAP releases.

Manage ONTAP includes simulators for both the Network Appliance filer running on either Linux or Solaris. Using these, you can test your 3rd party application without fear of disrupting the operation of a production machine. You can also run multiple copies of the simulator to simulate a number of appliances working simultaneously. At least 250MB of main memory per simulator is advised, and each simulator needs its own real or virtual Ethernet interface.

The simulator simulates a filer or netcache to a very low level; even the network device drivers use ONTAP code. Each disk in the appliance is simulated by a file in the ,disks (“comma disks”) directory located in the top-level simulator installation directory. A ,mac-address (“comma mac address”) file in the simulator’s directory tells it what Ethernet MAC address to use. Address conflicts can be fixed by changing one or more of the numbers in that file.

A frequently stumbled over “gotcha” is that simulators cannot contact the host machine on the host’s primary interface. So if you attempt to telnet from the host to the simulator’s command line, the telnet session will hang.

Performance of the simulator is acceptable for unit and integration testing purposes. Performance tests always require real equipment. The simulated disks use approximately twice the disk capacity of the ones they are simulating.

The simulator does NOT provide the kind of data protection one might suppose. The data is only as safe as the disk in the underlying system that stores the files containing the simulated disks.

Setup of simulators requires several steps. The instructions for these are bundled with the simulator itself.

Simulators are not currently supported by Network Appliance Customer Satisfaction, nor is it advised that you use the simulator as a "cheap filer" Complaints about data loss when using a simulator as a file storage appliance will be met with polite derision. If your testing requires a large amount of data on the simulator, we advise storing it elsewhere and writing a script to write it to the simulator's simulated filesystem should it become necessary to reinitialize it for any reason.

The long term goal of the Manage ONTAP SDK is to bring the unparalleled simplicity of Network Appliance’s products to the APIs that you, a third party development partner, depend on to build your products.

The sample code and documents in the SDK are unsupported by Network Appliance CS. To obtain direct engineering support for your development effort, please contact Network Appliance by sending email to dl-manage-ontap-api@netapp.com.

Your feedback is important to us. If you have suggestions for improvement of this sample code or documentation, please send them to sdk-feedback@netapp.com.

Trade and service marks incorporated herein are the property of their respective owners.