From 4f0024b269fb626eb311013ffd29ee31bd67abc5 Mon Sep 17 00:00:00 2001 From: devanladdu Date: Tue, 21 Jul 2026 13:22:24 -0400 Subject: [PATCH] Create Invoke-HyperVHostReboot Doc Create Invoke-HyperVHostReboot Doc --- docs/powershell/invoke-hypervhostreboot.md | 106 +++++++++++++++++++++ 1 file changed, 106 insertions(+) create mode 100644 docs/powershell/invoke-hypervhostreboot.md diff --git a/docs/powershell/invoke-hypervhostreboot.md b/docs/powershell/invoke-hypervhostreboot.md new file mode 100644 index 000000000..4293f1de8 --- /dev/null +++ b/docs/powershell/invoke-hypervhostreboot.md @@ -0,0 +1,106 @@ +--- +id: '8e8f6b86-b431-4176-aad5-797a446a0609' +slug: /8e8f6b86-b431-4176-aad5-797a446a0609 +title: 'Invoke-HyperVHostReboot' +title_meta: 'Invoke-HyperVHostReboot' +keywords: ['Hyper-V', 'Reboot', 'Maintenance Mode', 'Save-VM', 'Suspend', 'Resume', 'Virtual Machine', 'Domain Controller'] +description: 'Safely reboots a Hyper-V host without generating false-positive monitoring tickets and without losing the running state of its guests.' +tags: ['hyper-v', 'reboot', 'virtualization', 'windows', 'monitoring'] +draft: false +unlisted: false +last_update: + date: 2026-07-21 +--- + +## Overview + +`Invoke-HyperVHostReboot.ps1` safely reboots a Hyper-V host without generating false-positive monitoring tickets and without losing the running state of its guests. + +Because a host reboot terminates any running script, the work is split into two phases that share state through a state file and a one-time startup scheduled task: + +- **Suspend phase** (`-Suspend`, the default — this is what your RMM invokes): puts the host and its guests into maintenance mode, saves (suspends) every running guest so its state survives the reboot, registers the resume task, and reboots the host. +- **Resume phase** (`-Resume`, invoked automatically at startup by the scheduled task): starts the previously saved guests, clears maintenance mode, and cleans itself up. + +## Requirements + +- Runs on the Hyper-V host itself (the Hyper-V PowerShell module must be present). +- PowerShell 5.0+ and Administrator privileges. +- The `Strapper` module (auto-installed). +- **Maintenance mode is a stub.** `Set-MaintenanceMode` currently only logs the intended action. To actually suppress tickets, drop your ConnectWise call into the marked `TODO` region inside that function (CW RMM/Asio API request, CW Automate agent flag, or an internal helper). Until then, run with `-SkipMaintenanceMode`, or leave it as-is (it is a safe no-op that logs a warning). The suspend/reboot/resume workflow is fully functional without it. + +## Process + +### Suspend Process (`-Suspend`) + +1. Copies itself to a persistent path (`%ProgramData%\_Automation\Invoke-HyperVHostReboot`) so it and its state survive the reboot. +2. Enumerates running guests (healthy heartbeat) and classifies each as a Domain Controller or a standard VM (via guest FQDN + a DNS SRV lookup). If no running guests are found, it aborts without rebooting. +3. Places the host and running guests into maintenance mode (unless `-SkipMaintenanceMode`). +4. Saves each running guest (`Save-VM`) — standard VMs first, Domain Controllers last — waiting up to `LeadTime` seconds each. +5. If any guest fails to save, it rolls back (restarts the guests it already saved), clears maintenance mode, and does **not** reboot. +6. Writes the saved-guest list and settings to `reboot-state.xml` and registers the one-time `\ProVal\Invoke-HyperVHostReboot-Resume` startup task. +7. Waits `RebootDelaySeconds` (to let maintenance mode propagate) and reboots the host. Use `-NoReboot` to skip the actual reboot for testing. + +### Resume Process (`-Resume`) + +1. Runs automatically at startup via the scheduled task. If no state file is present, it removes the task and exits. +2. Waits for the Hyper-V Virtual Machine Management service (`vmms`) to be running. +3. Starts each saved guest — Domain Controllers first, standard VMs last — waiting up to `LeadTime` seconds each for a healthy heartbeat. +4. Clears maintenance mode for the host and guests (unless it was skipped during suspend). +5. Removes the state file and unregisters its own scheduled task. + +The maintenance window (`MaintenanceWindowMinutes`) acts as a safety net: if the resume phase never runs, monitoring resumes automatically once the window expires. + +## Payload Usage + +### Example 1 + +Standard use — put host + guests into maintenance, save all running guests, and reboot. Guests are resumed automatically at startup. + +```powershell +.\Invoke-HyperVHostReboot.ps1 -Suspend +``` + +### Example 2 + +Validate the save/resume flow without touching maintenance mode or rebooting. + +```powershell +.\Invoke-HyperVHostReboot.ps1 -Suspend -SkipMaintenanceMode -NoReboot +``` + +### Example 3 + +Manually run the resume phase (normally triggered automatically after reboot). + +```powershell +.\Invoke-HyperVHostReboot.ps1 -Resume +``` + +## Parameters + +| Parameter | Alias | Required | Default | Type | Description | +| -------------------------- | ----- | ----------- | ------- | ------ | ---------------------------------------------------------------------------------------------------- | +| `Suspend` | | True (Semi) | | Switch | Run the suspend phase: maintenance on, save guests, register resume task, reboot. Default action. | +| `Resume` | | True (Semi) | | Switch | Run the resume phase: start saved guests and clear maintenance mode. Invoked automatically at boot. | +| `LeadTime` | | False | `300` | Int | Seconds to wait for each guest to reach its target state (Saved on suspend / healthy on resume). | +| `RebootDelaySeconds` | | False | `60` | Int | Seconds to wait after saving guests before rebooting, to let maintenance mode propagate. | +| `MaintenanceWindowMinutes` | | False | `60` | Int | Length of the requested maintenance window, in minutes. Acts as a safety net if resume never runs. | +| `SkipMaintenanceMode` | | False | `False` | Switch | Skip all maintenance-mode calls (host is not monitored, or the stub is not yet wired up). | +| `NoReboot` | | False | `False` | Switch | Run the full suspend workflow but do not reboot the host (for testing). | + +## Output + +- Invoke-HyperVHostReboot-log.txt +- Invoke-HyperVHostReboot-error.txt + +During the reboot cycle, the persistent working copy, state file, and logs live under: + +``` +%ProgramData%\_Automation\Invoke-HyperVHostReboot\ +``` + +## Changelog + +### 2026-07-21 + +- Initial version of the document