| Guest SDK 12.3.0 for vSphere 8.0 U2 | 21 September 2023 | SDK on developer.vmware.com For ESXi 8.0 U2 and vCenter Server 8.0 U2 | Last document update: 20 September 2023 Check back for additions and updates to these release notes. |
About the Guest SDK
You can download the VMware Guest SDK from the developer.vmware.com website. Documentation is provided on the landing page with SDK bits: tarball for Linux and Zip file for Windows. SDK version number 12.3.0 was prepared for and released with vSphere 8.0 Update 2.
The Guest SDK includes four components for different use cases:
- Guest API. The Guest API provides C/C++ language functions to monitor virtual machine statistics. Management agents running in a virtual machine's guest OS can use this data for reacting to changes in the application layer.
- Guest Statistics. The statistics fetch facility returns detailed data in several structured formats about virtual machines running on an ESXi host.
- DataSets. New in vSphere 8.0, the DataSets API can manipulate VM-related key-value entries using vSphere Automation from vCenter Server, or with VM Tools inside a guest OS.
- HA Application Monitoring. The vSphere High Availability (HA) feature for ESXi hosts in a cluster provides protection for a guest OS and applications running in a virtual machine by restarting the virtual machine if a failure occurs. Using the HA Application Monitoring APIs, developers can write software to monitor the process heartbeat of a guest OS.
Compatibility Notices
The Guest SDK in vSphere 8.0 U2 is compatible with VMware Tools version 12.3.0 and later.
As of vSphere 8.0, VMware Tools gets built by Visual Studio 2019, so on Windows the Guest SDK depends on runtime vc140.
The never-documented guest API VMGuestLib_GetHostMemKernOvhdMB was deprecated as of VMware Tools 11.2.0. The GUESTLIB_HOST_MEM_KERN_OVHD_MB performance counter that it returns was documented in vSphere Virtual Machine Administration for ESXi 5.5, but dropped in subsequent documentation.
For vSphere 6.0, HA Application Monitoring communication was revised to use the VMCI (virtual machine communication interface). The VMCI driver is preinstalled in Linux kernel 3.9 and higher, and in earlier kernel versions it can be installed with VMware Tools. On Windows, VMware Tools must be installed to obtain the VMCI driver.
Changes and New Features
The DataSets facility was new in version 12.1.0 for vSphere 8.0. The Guest SDK Programming Guide has a chapter about it, and the Virtual Machine Administration manual discusses it also.
The VMGuestLib_GetMemShares64 call was added in vSphere 7.0 to support large-memory virtual machines.
Known Issues and Workarounds
The HA Application Monitoring library is not thread safe. It assumes that only one monitor process generates heartbeats in the VM. If a program runs multiple monitor threads, the library will leak memory, and RPC processes might not exit when the program terminates. Moreover, unexpected VM resets may occur owing to lack of heartbeats in a different thread. Monitoring programs should either avoid multithreading, or call the library from a single thread only.
Security enforcement for the Guest and HA application monitoring SDK using the secure authentication VMX parameter guest_rpc.rpci.auth.app.APP_MONITOR=TRUE does not work for FT (fault tolerant) virtual machines. The vSphere platform supports only the non-secure channel for FT virtual machines.
Sample code for HA Application Monitoring does not demonstrate use of the new API to request reset of the guest virtual machine, VMGuestAppMonitor_PostAppState.
