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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| $guestOpsMgr = (Get-View $global:DefaultVIServer.ExtensionData.Content.guestOperationsManager) | |
| $authMgr = (Get-View $guestOpsMgr.AuthManager) | |
| $vm = (Get-VM -Name MacOSX-10.11).ExtensionData.MoRef | |
| $credential = New-Object VMware.Vim.NamePasswordAuthentication | |
| $credential.InteractiveSession = $false | |
| $credential.Username = "lamw" | |
| $credential.Password = "vmware123" | |
| $authMgr.ValidateCredentialsInGuest($vm,$credential) | |
| $processMgr = (Get-View $guestOpsMgr.ProcessManager) | |
| $commandSpec = New-Object VMware.Vim.GuestProgramSpec | |
| $commandSpec.WorkingDirectory = "/Users/lamw" | |
| $commandSpec.ProgramPath = "/usr/sbin/system_profiler" | |
| $commandSpec.Arguments = "SPSoftwareDataType > /tmp/output" | |
| $processMgr.StartProgramInGuest($vm,$credential,$commandSpec) |
Additional Resources:
VMware Tools Download
- Tools 10.1 - https://my.vmware.com/web/vmware/details?downloadGroup=VMTOOLS1010&productId=614
- Tools 10.1.5 - https://my.vmware.com/web/vmware/details?downloadGroup=VMTOOLS1015&productId=614
- Tools 10.1.7 - https://my.vmware.com/web/vmware/details?downloadGroup=VMTOOLS1017&productId=614
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.
[logging] log = true vmtoolsd.level = debug vmtoolsd.handler = file vmtoolsd.data = /var/log/vmtoolsd.log vmsvc.level = debug vmsvc.handler = file vmsvc.data = /var/log/vmsvc.log
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.
Glad to see you're still working with Apple tech! 😀
I love your blog, William. So many great VMware articles.
Neat example. It looks like you were calling this from Powershell, so that does that mean this has to be invoked from a Windows host to the OSX guest? Is it possible to use the APIs that back `Invoke-VM-Script` to call from a Linux or OSX host, rather than a Windows host?