Questions about various SDK components & API libaries/functions

[eshropshire]

I downloaded two different zip files for the NetApp Manageability SDK v5.1.  One zip file was the full SDK, and the other was only for the .Net Bindings.  My questions pertain to the differences between the content of the two different zip files.

In the full SDK, it appears that only the Core API functions are documented, and there are various DLL and SO libraries provided that implement those functions.  Specifically, for Windows, there are native DLL files for unmanaged C/C++ code to use, as well as a .Net DLL to be used by C#, VB.Net, etc.., and there is another DLL that is required for using Windows RPC as the transport regardless of whether the unmanaged or managed code implementations of the Core API functions are being used.

Unless I am misunderstanding what I've read, only the Core API functions are implemented, and pretty much anything that a developer wants to do w/respect to high level functionality requires writing wrapper functions that consume the Core API functions; the ZEDI Zexplore utility must be used to obtain information about how to perform high level operations.

In the SDK that was limited to just the .Net Bindings, there is a netapp-manage.dll file and then there are multiple DLL files for different versions of Data OnTap, where each DLL is named for a specific version [e.g. ontap-8-1-1.dll].  The documentation only shows information for classes in a .Net Assembly that provide very high level functionality, and there doesn't appear to be any documentation regarding low level functionality such as the Core API functions.  Additionally, the main focus seems to be purely for creating Power Shell Cmdlets, and not for generalized .Net applications.  No mention is made of using Windows RPC as the transport & authentication mechanism when using the classes in the various ontap-<version>.dll libraries, and all the  sample code for Power Shell Cmdlets shows a requirement for a username & password to be provided when the Cmdlet is executed.

My questions are as follows:

1)  What are the recommendations for the usage of these two very different sets of API libraries?

In our usage scenario, the goal is to have a mixture of unmanaged native C++ code [on Windows] and managed C# .Net code be able to query and manage quotas on legacy NetApp Filers running v7.x and on newer v8.x devices running in Cluster Mode or in 7-Mode.  It isn't clear which API libraries and/or .Net Assembly DLL libraries are most appropriate for doing this.  Please note that our unmanaged native C++ code would most likely consume .Net based functionality by way of a COM interface that wraps up the .Net managed C# code as a COM server and makes it consumable by unmanaged code.

2)  When using the ontap-<version>.dll .Net Assembly libraries, can the latest version [currently ontap-8-1-1.dll] be used with NetApp filers of running all older versions of Data OnTap, or is it necessary to first identify the target device's version and then use a specific assembly that matches the device's version?

3)  If a mixture of NetApp branded and IBM branded devices are being used, are the API library and/or assembly DLL requirements the same for a particular Data OnTap version regardless of what the vendor/brand name is?

4)  For the full v5.1 SDK, are there currently any libraries or assemblies that provide high level wrapper functions or classes, or is that type of functionality only present in the zip file that is specifically only for .Net Bindings?

5)  When using the ontap-<version>.dll .Net Assembly libraries, is the Windows RPC transport available for use in place of HTTP/HTTPS?

6)  Regardless of whether the Windows RPC mechanism is being used by unmanaged native C++ code or managed C# .Net code, does it fully honor thread-level impersonation such that the identity specified by the thread-level access-token is used as the identity that is presented to the remote RPC server on the NetApp device?

We make extensive use of thread-level impersonation and it is mandatory that all RPC calls honor the thread's current identity as the process level identity is not suitable for use in RPC calls to remote systems.

Any information that would help answer these questions or clarify how the SDK's various libraries are intended to be used would be helpful.

[sens]

Hi,

The core bundle provides you the interfaces (which we call as Core APIs) to invoke any API on the server (e.g. Data ONTAP). While using the Core APIs, you need to read the API Documentation to understand the structure of input and output parameters and then frame the input element (na_elem) and output element (na_elem) by yourself in order to successfully send appropriate inputs and receive the outputs of an API invocation.

In case of dotnet-bindings, all the APIs have been converted in "class" definitions and the input and output elements of the APIs are defined as the member variables of the corresponding classes. This provides you a completely Object Oriented approach. You can create "Objects" of the APIs and invoke them.

This is the primary difference between the two bundles. With this brief description, I am trying to answer the questions you posted above:

1. What are the recommendations for the usage of these two very different sets of API libraries?

>> In a pure .NET environment, we would recommend using dotnet-bindings as the development activity becomes much easier (particularly if you are using Visual Studio) and less prone to human error. In other cases where you may need a lot of customization with the API structure, you may consider using the core APIs.

2. When using the ontap-<version>.dll .Net Assembly libraries, can the latest version [currently ontap-8-1-1.dll] be used with NetApp filers of running all older versions of Data OnTap, or is it necessary to first identify the target device's version and then use a specific assembly that matches the device's version?

>> Using the latest version should be fine. However, please be aware that higher ONTAP version would contain some APIs (and hence would show up in the namespace) which are not present in the lower ONTAP versions. If you invoke such an APIs on a lower ONTAP version, you will receive "Unable to find API" exception. Similarly, some of the existing APIs may have undergone parameter changes in higher ONTAP versions. However, such instances are minimal.

3. If a mixture of NetApp branded and IBM branded devices are being used, are the API library and/or assembly DLL requirements the same for a particular Data OnTap version regardless of what the vendor/brand name is?

>> Yes, vendor/brand does not affect the API definitions and the assembly DLLs.

4. For the full v5.1 SDK, are there currently any libraries or assemblies that provide high level wrapper functions or classes, or is that type of functionality only present in the zip file that is specifically only for .Net Bindings?

>> High level wrappers are not available in SDK. You need to make individual invocations for each APIs.

5. When using the ontap-<version>.dll .Net Assembly libraries, is the Windows RPC transport available for use in place of HTTP/HTTPS?

>> No, ontap-<version>.dll files support only HTTP and HTTPS transport protocols. Please note that Clustered ONTAP does not support RPC.

6. Regardless of whether the Windows RPC mechanism is being used by unmanaged native C++ code or managed C# .Net code, does it fully honor thread-level impersonation such that the identity specified by the thread-level access-token is used as the identity that is presented to the remote RPC server on the NetApp device?

>> Since managed C# .NET code (part of dotnet-bindings) does not support RPC, this question only pertains to unmanaged native C++ code (part of core NMSDK). I am not sure if I understood this question correctly, but if you are asking if NMSDK libraries are "thread safe", then the answer is - yes. The libraries having "_md" (or "_mdd" for debug version) appended to the files names (e.g. libnetapp_md.lib, libxml_md.lib, etc.) are thread-safe.

Please revert back to us if some of your questions are unanswered or if you have any further queries on this.

Regards,

Sen.

[eshropshire]

Thank you for the reply.  It was helpful and informative, but I do still need further clarification your answer to question #5, and I need to better explain what I was asking about with question #6.

5. When using the ontap-<version>.dll .Net Assembly libraries, is the Windows RPC transport available for use in place of HTTP/HTTPS?

>> No, ontap-<version>.dll files support only HTTP and HTTPS transport protocols. Please note that Clustered ONTAP does not support RPC.

With Clustered OnTap, are you saying even a virtual filer doesn't support Windows RPC, or is it only when making API calls directly to a cluster member node that Windows RPC isn't supported?

I can understand it if the cluster member nodes themselves don't support Windows RPC as they don't actually run a CIFS service and don't have any Windows user/group accounts that are associated with management roles.  However, I would have expected that a virtual filer that is configured to run the CIFS service would support Windows RPC.

Is there a document that clearly states what versions and/or configurations or modes of operation do or don't support Windows RPC?  I need to know if an OnTap 8.x system configured to run in 7-Mode supports Windows RPC, as well as what the support is in v7.x & older "legacy" NetApp Filer devices.

6. Regardless of whether the Windows RPC mechanism is being used by unmanaged native C++ code or managed C# .Net code, does it fully honor thread-level impersonation such that the identity specified by the thread-level access-token is used as the identity that is presented to the remote RPC server on the NetApp device?

>> Since managed C# .NET code (part of dotnet-bindings) does not support RPC, this question only pertains to unmanaged native C++ code (part of core NMSDK). I am not sure if I understood this question correctly, but if you are asking if NMSDK libraries are "thread safe", then the answer is - yes. The libraries having "_md" (or "_mdd" for debug version) appended to the files names (e.g. libnetapp_md.lib, libxml_md.lib, etc.) are thread-safe.

No, that's not exactly what I was asking for.  I did see the thread-safety statement in the SDK as it pertains to the Core API functions.  However, what I was asking about was how thread-level impersonation of an access token is honored when it comes to using the Windows RPC mechanism as the transport for making API calls to NetApp Filer devices.  Initially, when a thread is created, it doesn't have a thread-level access-token, and so its "identity" comes from the process-level access-token.  In our applications, the main process runs as "Local System", but when threads need to interact with remove file systems or Active Directory, those threads then authenticate some stored credentials to create an access-token, which the thread then impersonates.  From that point on, the thread's identity is that of the account that was used to create the access-token, and all Win32 API calls and DCOM operations result in the thread-level identity being used.

What I was wanting to confirm is that the NetApp API functions honor thread-level identity when passing the API call request along to a remote NetApp Filer [or virtual filer] via the Windows RPC mechanism.  The intuitive answer is "yes", but I don't want to make any bad assumptions.

Also, I realized that there was a 7th question I should have asked:

When using HTTP/HTTPS and passing in credentials to establish a server connection, where do those credentials get created & managed on the NetApp?  Are these Unix account credentials for a local Unix account that exists within a particular NetApp device or a virtual filer hosted on a cluster member node?  If directly accessing a cluster member node, then the same question applies... where do the credentials get created & managed?

[sens]

Hi,

Please find my responses below:

With Clustered OnTap, are you saying even a virtual filer doesn't support Windows RPC, or is it only when making API calls directly to a cluster member node that Windows RPC isn't supported?

>> With Clustered ONTAP, even the virtual filer (called vserver in the context of Clustered ONTAP) does not support Windows RPC for invoking any API. So, you need to use only HTTP or HTTPS transport protocol for using an API. ONTAP 7-Mode systems and legacy systems do support RPC. However, if you are using .NET bindings [managed C# .NET codes] (e.g. ontap-<ver>.dll with netapp-manage.dll), you can only use HTTP or HTTPS for Clustered ONTAP and even for 7-Mode and legacy systems (as the bindings do not have provision for Windows RPC). But if you use core NMSDK [unmanaged C++ code], you will be able invoke an API through Windows RPC for 7-Mode and legacy systems by setting na_server_style() with "NA_STYLE_RPC".

What I was wanting to confirm is that the NetApp API functions honor thread-level identity when passing the API call request along to a remote NetApp Filer [or virtual filer] via the Windows RPC mechanism.

>> We have not tried NMSDK APIs with thread-level impersonation. However, we believe, there should not be any issues as long as the threads invoke the APIs as recommended in the NMSDK documentation.

When using HTTP/HTTPS and passing in credentials to establish a server connection, where do those credentials get created & managed on the NetApp?  Are these Unix account credentials for a local Unix account that exists within a particular NetApp device or a virtual filer hosted on a cluster member node?  If directly accessing a cluster member node, then the same question applies... where do the credentials get created & managed?

>> The credentials are created and managed on the ONTAP server side. These are credentials you need to access the ONTAP system.

Regards,

Sen.

[eshropshire]

Thank you for answering those questions.

I have one remaining question to help clarify something that is stated in a PDF document that is titled "NMSDK - Technial Overview".  Specifically, on page 33, it states that, "NSMSDK will only support UTF-8 character encoding format."

I take this to mean that for every NetApp SDK API function that takes input parameter types of "char *" or "const char *", or which returns values of those same types, then those strings are UTF-8 encoded values.

Is this correct?

[sens · Accepted solution]

Yes, you are right.