Introducing vSphere Guest API
If you want to read information about a virtual machine from the guest OS running on it, the vSphere Guest API is for you. It’s a C library coming with VMware Tools. Unlike the vSphere API which can be used anywhere, the vSphere Guest API is only available in the guest OS.
High Level Characteristics
- It’s read only. You can use it to retrieve state and performance of a virtual machine running on ESX, but you can NOT change anything via the API. To change things, you want to use the vSphere API.
- It requires VMware Tools which installs the vSphere Guest API component (vmGuestLib.dll on Windows, vmGuestLib.so on Linux) automatically.
- It’s enabled by default. To turn it off, set the “isolation.tools.guestlibGetInfo.disable” to “TRUE”. You can do it with either vSphere Client in the VM’s properties window, or via vSphere API.
What Info Can Be Retrieved?
Here is a partial list. Notice the last one about ESX CPU goes beyond the virtual machine itself.
- Amount of memory reserved for the virtual machine.
- Amount of memory being used by the virtual machine.
- Upper limit of memory available to the virtual machine.
- Number of memory shares assigned to the virtual machine.
- Maximum speed to which the virtual machine’s CPU is limited.
- Reserved rate at which the virtual machine is allowed to execute. An idling virtual machine might consume CPU cycles at a much lower rate.
- Number of CPU shares assigned to the virtual machine.
- Elapsed time since the virtual machine was last powered on or reset.
- CPU time consumed by a particular virtual machine. When combined with other measurements, you can estimate how fast the virtual machine’s CPUs are running compared to the host CPUs.
- The physical ESX CPU speed via VMGuestLib_GetHostProcessorSpeed().
How to Use the API?
The Guest API is probably the simplest API within vSphere family. The programming guide has only 16 pages including the cover page, TOC, index, etc.
There are two types of functions in the library. One is context functions which establishes and manages the context, for example VMGuestLib_OpenHandle(); the other is the access functions are 20 accessor functions like VMGuestLib_GetCpuLimitMHz(). If you know how to program in C and it’s pretty straight forward. For details, read the vSphere Guest Programming Guide.