VIRT-001 · Script
Virtual Machine Guest Operations
Reports virtual machine power state and can start, stop, restart, checkpoint, run a command in, or copy a file into a virtual machine guest.
What it does
Works with Hyper-V (built-in Hyper-V module) or VMware vSphere (VMware PowerCLI, which you install yourself). Status lists the selected virtual machines with their power state, uptime and checkpoint or snapshot count, and changes nothing.
Every other -Action is planned in Report mode (default): the log lists exactly what would be done to which virtual machine, and nothing is changed. Apply mode carries it out:
- Start: powers on virtual machines that are off
- Stop: asks the guest to shut down; with -HardPowerOff it turns the VM off instead
- Restart: asks the guest to restart; with -HardPowerOff it resets the VM instead
- Checkpoint: creates a Hyper-V checkpoint or a VMware snapshot named -CheckpointName
- RunCommand: runs -ScriptText inside the guest and logs its output (needs a guest credential)
CopyToGuest copies -SourcePath from this computer to -DestinationPath in the guest
Hyper-V notes: RunCommand uses PowerShell Direct, so it must run on the Hyper-V host itself and the guest must be Windows 10, Windows Server 2016 or later. CopyToGuest needs the Guest Service Interface integration service enabled in the VM. A graceful Restart is a guest shutdown followed by a start. VMware notes: graceful Stop and Restart, RunCommand and CopyToGuest need VMware Tools running in the guest.
Actions are only taken on virtual machines named in -VMName; there is no "all VMs" default for changes. Runs silently. No prompts, no user interaction.
Requirements
Windows PowerShell 5.1+. Hyper-V: the Hyper-V PowerShell module and Hyper-V admin rights.
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) logs what would be done. Apply makes the change. | Report, Apply | Report |
| Action | Status (default), Start, Stop, Restart, Checkpoint, RunCommand or CopyToGuest. | Status, Start, Stop, Restart, Checkpoint, RunCommand, CopyToGuest | Status |
| VMName | Virtual machine names, wildcards allowed, for example "LAB-PC-*" or "FILESRV01". Empty lists every VM for Status. Required for every other action. | (none) | |
| HardPowerOff | With Stop or Restart, turn off or reset the VM without a guest shutdown. Unsaved work in the guest is lost. Off by default. | False | |
| CheckpointName | Name for a new checkpoint or snapshot, for example "Before-Update". Empty uses Runbookia-<date>-<time>. | ||
| ShutdownTimeoutSeconds | Hyper-V graceful Restart only: how long to wait for the guest to shut down before giving up. Default 300. | 300 | |
| GuestCredentialPath | RunCommand (and CopyToGuest on VMware): path to a guest operating system credential file made with Get-Credential | Export-Clixml, for example C:\ProgramData\Runbookia\Secure\guest.xml. | ||
| ScriptText | RunCommand only. The command to run in the guest, for example "Get-Service Spooler" or "ipconfig /all". | ||
| ScriptType | VMware RunCommand only: PowerShell (default), Bat or Bash. Hyper-V always uses PowerShell. | PowerShell, Bat, Bash | PowerShell |
| SourcePath | CopyToGuest only. File on this computer (Hyper-V: on the Hyper-V host), for example C:\Deploy\agent.msi. | ||
| DestinationPath | CopyToGuest only. Full path in the guest, for example C:\Temp\agent.msi. | ||
| 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 = Status done, plan logged with all VMs found, or all actions done
- 1 = A named VM was not found, a VM was in the wrong state, or an action failed
- 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 and Status change nothing. After Apply: start a stopped VM again with Action Start, or stop a started one with Action Stop. Remove an unwanted checkpoint in Hyper-V Manager (Delete Checkpoint) or the vSphere Client (Manage Snapshots > Delete). Files copied with CopyToGuest can be deleted inside the guest. Effects of a command run with RunCommand must be undone by hand inside the guest.
Version and change log
| Version | Date | Changes |
|---|---|---|
| 1.0.0 | November 2026 | First release. |