How to Search for Checkpoints using PowerShell

Checkpoints, or snapshots in previous versions of Hyper-V, can be a lifesaver when used properly in certain situations. For example, if applying a patch to the company payroll software goes south, being able to quickly roll a server back to its previous state is a huge benefit. However, checkpoints are also one of the Hyper-V features that admins have to be careful with. Improper use can cause more harm than good, which is why it is a valuable skill to be able to easily check for any and all existing checkpoints.

Reasons to Check for Checkpoints

Why would I ever want to know if there are active checkpoints on my VMs? Well, for one, checking for any pre-existing checkpoints is a very important step when performing any modifications to VHDs such as expanding the file, especially when using PowerShell. When using the GUI to edit the VHD of a VM that has a checkpoint, the option to edit the disk will be greyed out with the warning message “Edit is not available because checkpoints exist for this virtual machine”:

But, if the VHD is modified through PowerShell while a checkpoint still exists, an error message will not prevent you from performing the modification to the VHD. The result is a broken VHD file. Recently, I heard a horror story about an admin that did this without verifying backups and it was not pretty. So, lesson learned: make sure you check for checkpoints when doing any sort of VHD file modification through PowerShell.

Another reason is to look for lingering checkpoints that have been forgotten. Checkpoints are not backups; they are not meant to be long-term. If left alone long enough, they can potentially eat up all the storage on the CSV or LUN which can in turn cause VMs to pause. For more information on this and how it works be sure to check out Eric Siron’s post on “Why Hyper-V Snapshots Don’t Replace Backups”.  Because of this, routinely checking all hosts for any lingering checkpoints is not a bad idea; especially if your organization uses a lot of checkpoints and there are other admins with their hands in the pot. There’s nothing more annoying than waiting hours to increase the disk space on a host because someone forgot to remove the checkpoint on a heavily used server 2 years ago.

How to Find Checkpoints

The command to check for any existing checkpoints is easy enough that it should be stored in the back pocket of every Hyper-V Admin. The syntax is very simple: use the Get-VMSnapshot cmdlet with the –VMname parameter. In this example we will check the TGLAB-SQL01 server for any checkpoints:

Get-VMsnapshot –VMname TGLAB-SQL01

All checkpoints of the VM are displayed in the console.

PowerShell also gives us the ability to search for all checkpoints on the host which is one of the most beneficial uses of this cmdlet. Simply use the asterisk symbol (*) or wildcard for the –VMname parameter, this will then list the checkpoints for all VMs:

Get-VMSnapshot –VMname *

For finding checkpoints on multiple hosts at once, simply use the –computername parameter to list all the hosts to check. In the example I check both hosts TGLAB-HV01 and TGLAB-HV02 for checkpoints:

Get-VMsnapshot –VMname * -ComputerName tglab-hv01,tglab-hv02

How to Remove Checkpoints

Removing all checkpoints in PowerShell is just as easy as searching for them. There are a few ways to do this but the simplest, if you’re already searching for existing checkpoints, is to pipe the list obtained from the Get-VMsnapshot cmdlet to the Remove-VMSnapshot cmdlet:

Get-VMsnapshot –VMname * -Computername tglab-hv01,tglab-hv02 | Remove-VMsnapshot

The AVHD file will merge with the VHD and the checkpoint will be removed. Next, run the Get-VMsnapshot cmdlet again to verify that the checkpoints are gone:

To remove checkpoints from just one VM, don’t use Get-VMsnapshot. Instead, use the Remove-VMsnapshot by itself with the –VMname parameter. In this example, we will remove all checkpoints from the VM TGLAB-SQL01:

Remove-VMsnapshot –VMname TGLAB-SQL01

You can also remove checkpoints by name. For example, let’s say I did a big HR software upgrade on a few servers. Before the patching process I created checkpoints for the servers in case something went wrong. I named the checkpoint for each server “Before Patch”, and now it’s time to remove them.

To do this use the Get-VMsnapshot cmdlet and the -name parameter to filter out just the checkpoints that are named “Before Patch”. Then, pipe the list to Remove-VMsnapshot:

Get-VMSnapshot –VMname * -name “before patch" | remove-vmsnapshot

Now when we check again we can see the checkpoints labelled “Before Patch” were removed.