I have written a number of articles exploring the usage and some of the cool tricks that the vSphere Guest Operations (GuestOps) feature provides which you can be found here, here, here and here. I have been a huge fan and supporter of GuestOps since the early days where it was formally known as the VIX API. Having used GuestOps across many different GuestOS types including Nested ESXi, I have to admit, I had never tried it against an Apple macOS guests. I recently had a customer reach out who was looking to use the GuestOps API via PowerCLI (Invoke-VMScript) to automate updates against his guestOS templates that span across Windows, Linux and macOS (from 10.7 to latest). The customer was able to get all guestOSes working except for macOS.

Since I had never tried this before, I spun up my Apple Mac Mini which happen to have a macOS 10.11 (El Capitan) guests running. I tried using the vSphere API GuestOps directly to see if this was a PowerCLI and/or API issue. I too ran into issues and after enabling VMware Tools debugging on the guests (which you can find more details below), I found that it hit the following error:

[Jun 28 06:35:42.805] [   debug] [vix] >VixToolsImpersonateUser
[Jun 28 06:35:42.925] [ warning] [vmsvc] Failed to set gid for user root

 

Reaching out to Engineering regarding the problem, I came to learn that this particular issue was due to a syscall change made by Apple starting with macOS 10.10.3 and newer. Although the change was a positive thing from a security standpoint, it did break the GuestOps functionality. The good news was that this was already resolved with VMware Tools 10.1 or later. When I had initially provisioned the macOS guests, the latest VMware Tools at the time was 9.10.5. After I applied the latest version which is currently 10.1.7, the issue went away and I was able to successfully use the GuestOps API on my macOS guests.

Below are examples of running the system_profiler SPSoftwareDataType command using both the Invoke-VMScript cmdlet as well as the vSphere API and PowerCLI to consume the GuestOps APIs. Both approaches delivers the exact same outcome, the one benefit of using Invoke-VMScript is that if you want to easily return output from a given command, the cmdlet already does the heavy lifting. If you notice in the native vSphere API case, you do not get output but rather just the PID ID. If you want to return the output, you need to first save it into a file and then download the file to your client system, which may not be ideal for interactive usage but it all depends on your use case.

PowerCLI Invoke-VMScript

Invoke-VMScript -ScriptText "system_profiler SPSoftwareDataType" -vm MacOSX-10.11 -GuestUser lamw -GuestPassword vmware123 -ScriptType Bash

Here is a screenshot of the output

GuestOps API via PowerCLI

Additional Resources:

VMware Tools Download

VMware Tools Interoperability Matrix

Troubleshooting

If you are having issues with GuestOps or other things related to VMware Tools, it may be useful to enable additional logging on the guestOS side for the VMware Tools daemon and services. The following VMware KB 1007873 can be used to help enable the various options.

For macOS specifically, you would need to create the following configuration file /Library/Application\ Support/VMware\ Tools/tools.conf and here is an example of the configuration that I had used for troubleshooting this particular issue.

Once you create the file, the changes will go into effect within 5 seconds as the VMware Tools daemon will automatically look for this file periodically which makes enabling/disabling logging pretty trivia when needed.

One thought on “Using vSphere Guest Operations API on macOS Guests? 

Thanks for the comment!