VIRT-002 · Script
Guest Filesystem Capacity Report
Reports free space on the filesystems inside virtual machine guests and flags any that are running low.
What it does
Read-only. Nothing is changed.
VMware: reads each guest's filesystems (drive letters or mount points, capacity and free space) as reported by VMware Tools. VMs that are off or have no VMware Tools running are listed with Source "No guest data".
Hyper-V: Hyper-V does not report guest filesystem free space on its own. When -GuestCredentialPath is given and the script runs on the Hyper-V host, it reads the fixed drives inside running Windows guests through PowerShell Direct. Otherwise, and for VMs it cannot read, it reports each virtual hard disk file instead: maximum size, current file size and the free space left on the host volume that stores it.
A filesystem is flagged when its free space is below -WarnPercentFree or below -MinFreeGB. Results are written to a CSV in -ReportDir. Runs silently. No prompts.
Requirements
Windows PowerShell 5.1+. Hyper-V: the Hyper-V PowerShell module. VMware: VMware PowerCLI installed by you and VMware Tools in the guests.
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 |
| VMName | Virtual machine names, wildcards allowed, for example "SRV-*". Empty = all VMs. | (none) | |
| WarnPercentFree | Flag filesystems with less free space than this percentage. Default 15. | 15 | |
| MinFreeGB | Also flag filesystems with less than this many GB free. 0 (default) turns this check off. Example: 10. | 0 | |
| GuestCredentialPath | Hyper-V only, optional. Path to a Windows guest credential file made with Get-Credential | Export-Clixml, for example C:\ProgramData\Runbookia\Secure\guest.xml. | ||
| 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 = No filesystem below the thresholds
- 1 = At least one filesystem is low on space, or a named VM was not found
- 2 = Script error (missing module, connection failed)
Testing steps
- Run it on one test tenant or small OU and check the output and log.
- 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 only. Nothing is changed, so nothing needs to be rolled back.
Version and change log
| Version | Date | Changes |
|---|---|---|
| 1.0.0 | November 2026 | First release. |