VIRT-003 · Script
Guest Tools and Integration Status
Reports guest integration tool status and version, and can upgrade VMware Tools, set its upgrade policy, or enable Hyper-V integration services.
What it does
VMware: reports VMware Tools version, version status (current, upgrade available, not installed, unmanaged), whether Tools is running, and the Tools upgrade policy of each VM. Hyper-V: reports the integration services version and state of each VM, and every integration service with whether it is enabled and its status as reported by the guest.
Report mode (default) changes nothing and logs what -Action would do. Apply mode runs -Action:
- None: report only (default)
- Upgrade: VMware only: starts a VMware Tools upgrade on running VMs whose Tools
report that an upgrade is available. Guests are not rebooted unless -AllowReboot is set, but some Tools versions may still need a restart. SetUpgradePolicy VMware only: sets the Tools upgrade policy to -UpgradePolicy (upgradeAtPowerCycle = check and upgrade at each power on; manual).
- EnableService: Hyper-V only: enables the integration services named in -ServiceName.
Hyper-V integration components on current Windows guests are updated through Windows Update inside the guest, not from the host.
Flagged for attention: Tools not installed, not running on a powered-on VM, upgrade available or too old; Hyper-V integration services reported as needing an update, or an enabled service reporting a problem. Runs silently. No prompts.
Requirements
Windows PowerShell 5.1+. Hyper-V: the Hyper-V PowerShell module. VMware: VMware PowerCLI installed by you.
How to run it
- Run from: an admin workstation or scheduled task with the Microsoft modules installed and app sign-in configured
- This is an admin script for your Virtualization tenant, not a per-device endpoint script
- User interaction: none with app-only sign-in
- Schedule: run on demand, or weekly for reports
Settings
| Name | What it does | Options | Default |
|---|---|---|---|
| Platform | HyperV (default) or VMware. | HyperV, VMware | HyperV |
| Mode | Report (default) or Apply. | Report, Apply | Report |
| Action | None (default), Upgrade, SetUpgradePolicy or EnableService. See the description. | None, Upgrade, SetUpgradePolicy, EnableService | None |
| VMName | Virtual machine names, wildcards allowed, for example "LAB-*". Empty = all VMs. | (none) | |
| UpgradePolicy | For SetUpgradePolicy: upgradeAtPowerCycle (default) or manual. | upgradeAtPowerCycle, manual | upgradeAtPowerCycle |
| ServiceName | For EnableService: Hyper-V integration service names, for example "Guest Service Interface" or "Time Synchronization". Default "Guest Service Interface". | Guest Service Interface | |
| AllowReboot | For Upgrade: let the VMware Tools installer restart the guest if it wants to. Off by default. | False | |
| ComputerName | Hyper-V only. Name of a remote Hyper-V host, for example HV01. Leave empty to use this computer. The account running the script needs Hyper-V administrator rights on that host. | ||
| Server | VMware only. vCenter Server or ESXi host name, for example vcenter.school.local. | ||
| CredentialPath | VMware only. Path to a credential file created with Get-Credential | Export-Clixml, for example C:\ProgramData\Runbookia\Secure\vcenter.xml. Create the file as the same account (for example SYSTEM) on the same computer that runs this script; Windows encrypts it so no other account can read it. Not needed with UseExistingSession. | ||
| UseExistingSession | VMware only. Reuse a vCenter Server or ESXi connection that is already open in this PowerShell session (from Connect-VIServer) instead of CredentialPath. | False | |
| IgnoreCertificateErrors | VMware only. Accept an untrusted or self-signed server certificate for this run only. Off by default; the PowerCLI setting on disk is not changed. | False | |
| ReportDir | Folder for CSV reports. Default C:\ProgramData\Runbookia\Reports. | C:\ProgramData\Runbookia\Reports |
Exit codes
- 0 = All tools current and running (Report), or all actions done (Apply)
- 1 = Tools or integration services need attention (Report), an action failed (Apply),
- or a named VM was not found
- 2 = Script error (missing module, connection failed, bad parameters)
Testing steps
- Run it first with the mode set to Report on one test account or small group. Nothing is changed in that mode.
- Read the log and confirm the planned changes are what you expect.
- Run your chosen settings on the same test target and confirm the result.
- Check the exit code: 0 = OK, 1 = needs attention, 2 = error (see log), 9 = this copy is past its Valid until date.
- Roll out to a small group next, then everyone.
Rollback steps
Report mode changes nothing. SetUpgradePolicy: run again with the previous -UpgradePolicy value shown in the CSV report. EnableService: disable the service again in the VM settings (Integration Services) or with Disable-VMIntegrationService. A VMware Tools upgrade cannot be rolled back by the script; reinstall the earlier Tools version inside the guest if needed.
Version and change log
| Version | Date | Changes |
|---|---|---|
| 1.0.0 | November 2026 | First release. |