Free Script: Find Orphaned Hyper-V VM Files

If you’ve had very much virtual machine churn in your environment, it’s almost inevitable that you’ve wound up with a few disconnected virtual machine files here and there. This free script will help you to locate orphaned Hyper-V VM files. For fellow infrastructure scripters, there is a special bonus script included as well.

The worst thing about my testing environment is that I often wind up with files that look legitimate, but are no longer part of any virtual machine. Even in live environments, some virtual machine moves and operations leave a trail of unwanted files. Errors and failures can produce more.

Finding virtual machine files isn’t hard, but ensuring that they’re not really attached to something can be much more difficult than it might at first seem. I tried very hard to include a great many features to cover every scenario I could think of.

Last Updated: April 11th, 2015

Feature List

  • Aware of snapshots/checkpoints
  • Aware of differencing disk chains
  • Cluster-aware
    • Will only scan Cluster Shared Volumes from a single node, and will not generate false positives while scanning other nodes
    • Will differentiate between shared and not shared storage, so you can scan local drives on nodes
    • Will detect all nodes in a cluster and scan each
    • Can be set to ignore cluster membership if you only want to scan non-shared locations
    • I didn’t do extensive testing with standard cluster disks as they’re not something I use, but it seems to work well enough. However, if a cluster disk were to move between the portion of the script where it scans for files to exclude and when it scans again for orphans, the results will be invalid.
    • The script understands raw volume identifiers, although I didn’t do a great deal of testing with those either.
  • Can be run from any system with PowerShell 4.0; the Hyper-V module is not required. I didn’t test it with PowerShell 3.0 systems because I haven’t got any left, but I think it will work
  • Can target 2012 and 2012 R2 systems simultaneously
  • Options to scan one or all of the following locations: the host’s default VM and VHD paths, all paths currently in use by VMs, and paths that you specify
  • All scans occur directly on the target host(s) except in the case of UNC paths, and each separate host is scanned in parallel
  • Detailed built-in help. Use Get-Help -Full to see it

Files that the Script Scans For

  • XML files with a base name in the format of a GUID. It does not parse the XML to see if they really are Hyper-V files, so watch out for false positives.
  • BIN files with a base name in the format of a GUID.
  • VSV files with a base name in the format of a GUID
  • SLP files with a base name in the format of a GUID and an intermediate extension
  • VHD, VHDX, AVHD, AVHDX, and VFD files; if you look at the script, it will match on anything that has VHD or VFD anywhere in the extension; please report false positives as I can update the script to be more selective if necessary.

Notes

  • All target hosts must have the Hyper-V PowerShell module installed. Any that don’t have it will throw errors that they cannot be scanned. The computer that you’re using to run the script does not need anything other than the default PowerShell modules installed. However, scanning SMB shares will be considerably faster if the Hyper-V module is installed locally.
  • The script will only exclude differencing disk chains from the point that a VM references it and upward to the root. For example, let’s say you have a “root.vhdx” with children “diff1.vhdx”, “diff2.vhdx”, and “diff3.vhdx”, with each one being a child of the previous disk. Let’s say you have a virtual machine that references “diff2.vhdx”. The scan will find the VM using “diff2.vhdx” and trace its chain upward through “diff1.vhdx” and “root.vhdx” and ignore them. If it doesn’t find any VM using “diff3.vhdx”, that file will be marked as orphaned. However, the script is snapshot/checkpoint aware so even complicated trees should not trigger a false positive.
  • The script uses a mix of implicit and explicit PowerShell Remoting with a very heavy dependence upon explicit. Even if you initiate directly from a system to be scanned, it will use PSRemoting. The drawback is that you can’t initiate this script inside a remote session unless you have CredSSP enabled and even then it might fail. To compensate, I ensured that you don’t need to have any special modules installed on the system that you run the script from.
  • You can’t specify connection credentials for scanning SMB 3 storage. I tried. It didn’t work. I didn’t get any errors to troubleshoot. It just didn’t work. If you use the -Credential parameter, the credentials will be used for retrieving host details, determining existing VM information and paths, and scanning storage local to the target hosts, but SMB 3 shares will be scanned using the credentials of the local session being used to invoke this function.
  • This script uses fully-qualified domain names to connect to domain members and you can’t get around it. The purpose of this is to ensure that cluster scans work correctly. For instance, if you pass in the short name of a cluster (“clhv1” in my case), it will use WSMan to attach to that address, query the system for its FQDN using WMI, and use that for all future connections. While it’s there, it will also determine the names of any other systems in the cluster and retrieve those as well. The side effect is that if you supply a DNS alias, it will be replaced with the true computer’s name for all subsequent connections. If you’re having trouble connecting to a system, this is probably why. Use the -Verbose switch to find out what system name it’s trying to connect to. If the target isn’t domain-joined, then the script should connect using only its NetBIOS name.
  • I had to install a lot of wiring to avoid returning false positives on Cluster Shared Volumes. The solution I settled on is that all scans of the ClusterStorage path will be handled only through the primary node in all cases. You won’t be able to bypass this behavior by any means, even by manually specifying a path of C: or C:ClusterStorage. I don’t think this will be a problem, but the explanation is here just in case you see behavior that you didn’t expect, such as by setting -IgnoreClusterMembership and scanning the C: drive of a node other than the primary.
  • The way I use PowerShell Remoting in parallel might cause some scans to take longer than you might think they would when you are only scanning the local system. That’s because of the behavior of the Wait-Job cmdlet. Since disk scans tend to be slow anyway, I don’t think that this adds enough time to the scan to be harmful, but if you think that something is taking a few seconds longer than it should, this is probably why.
  • The script will scan UNC paths, but might have some unexpected behavior in a few cases. For instance, let’s say you have a Windows Server system serving an SMB 3 share to hold VMs for other hosts. You also decide to stand up a local VM on that host and put it in the same location. From that host’s perspective, the VM might be stored in, let’s say D:VMs. D:VMs is also shared as \storage-serverVMs. If the scan is set to look at that share location, then it’s going to return all of that virtual machine’s files as orphans because it only knows them as being registered in D:VMs on that host.

There is no built-in option to remove the files that it finds. This would be a fairly trivial modification, but I’m not going to make it. I worked very hard to do almost everything I could to eliminate false positives, but they can and will happen and I won’t be responsible for someone accidentally wiping out all their templates or a completely unrelated file that happened to be named in the pattern of a Hyper-V file.

Script Usage

There are two parameter sets. The first is the default. It first finds all the virtual machines on a host for their files. It then scans all the folders that hold those files and the folders marked as the host’s defaults for orphans.

Default Parameter Set

  • ComputerName accepts a string array of computer names. If you don’t include any, the local system is scanned.
  • ExcludeDefaultPath prevents the host’s default paths from being scanned for orphaned files.
  • ExcludeExistingVMPaths prevents the paths of existing VMs from being scanned for orphaned files.
  • IgnoreClusterMembership treats the target system like a standalone machine even if it’s in a cluster. CSV folders will be ignored.
  • Credential allows you to specify a set of credentials that will be used to scan remote locations. Any SMB 3 shares will always be scanned from the perspective of the local system using the credentials of the local session.

Alternate Parameter Set

  • ComputerName in this set is the same as the default.
  • Path accepts a string array of paths to check. Each host in the ComputerName array will be scanned for this folder. If it’s not there, you’ll just get a warning about it, so there’s no harm in including it even for systems where you know it doesn’t exist. When you manually specify paths, only those locations are scanned by default.
  • IncludeDefaultPath instructs the script to scan the host’s default paths for orphans when -Path has been specified.
  • IncludeExistingVMPaths instructs the script to scan the folders of existing VMs for orphans when -Path has been specified.
  • IgnoreClusterMembership works in this set the same way as in the default.
  • Credential in this set is same as the default.

Sample Output

Get-OrphanedVMFiles ScreenshostThe output is essentially that of Get-ChildItem. Take a look at the PSComputerName column. That will tell you which computer the file was found on. If it reports “localhost”, that means the containing folder is on a share. All others will be local or on a CSV on the indicated computer.

Script Listing

Copy and paste the included script into a file. It’s written to expect Get-OrphanedVMFiles.ps1, but you’re welcome to use anything you like. Don’t forget that copying and pasting from this site includes a tag line at the very end that you’ll need to remove.

I did not write the script to be dot-sourced. If you want to do that, encase the contents as shown:

#requires -Version 3
function Get-VMOrphanedFiles
{
	<# 	comment-based help 	#>
	[CmdletBinding(DefaultParameterSetName='UnspecifiedPath')]
	param (
		... existing parameters...
	)
	BEGIN {
		... existing BEGIN script...
	}
	PROCESS
	{
		...
		existing PROCESS script
		...
	}
	END {}
}

And here’s the script:

<#
.SYNOPSIS
	Find virtual machine files that are no longer registered to a Hyper-V host or a virtual machine.

.DESCRIPTION
	Some operations may leave the XML definition file for a virtual machine orphaned, along with other files associated with a virtual machine.
	This script detects and returns those orphaned files.

	Use caution when interpreting results from a shared location. Files owned by a Hyper-V host that was not specified will be returned as a false positive.
	Use the Host parameter to specify other hosts to include in the same scan.

.PARAMETER Path
	A array string that contains one or more source paths to search. Subfolders will automatically be searched.
	If not specified, the behavior is the same as if the IncludeDefaultPath and IncludeExistingVMPaths parameters were specified.

.PARAMETER ComputerName
	A string array that contains the name(s) of host(s) to scan. It can also contain cluster name(s).
	If not specified, the local host will be used.

.PARAMETER IncludeDefaultPath
	If the Path parameter is specified, use this parameter to indicate that the Hyper-V host's default path should also be scanned.

.PARAMETER IncludeExistingVMPaths
	If the Path parameter is specified, use this parameter to indicate that the paths of existing VMs should also be scanned.

.PARAMETER ExcludeDefaultPath
	If the Path parameter is not specified, use this parameter to prevent the host's default VM path from being scanned.

.PARAMETER ExcludeExistingVMPaths
	If the Path parameter is not specified, use this parameter to prevent the paths of existing VMs from being scanned.

.PARAMETER IgnoreClusterMembership
	Ordinarily, the script will determine if a computer is part of a cluster and scan the VMs of all nodes as a fail-safe.
	If this switch is set, only the specified system(s) will be scanned. Any paths involving ClusterStorage will be skipped.

.PARAMETER Credential
	The credential to use to connect to and scan remote hosts.
	Has no effect on SMB 3 storage locations. These will always be scanned as the locally logged-on account.

.OUTPUTS
	An array of deserialized FileInfo objects or $null if no items are found. GetType() shows the generic Object type.

.NOTES
	 Author: Eric Siron
	 Copyright: (C) 2014 Altaro Software
	 Version 1.1
	 Authored Date: October 25, 2014

	 1.2 April 11, 2016
	 ------------------------------
	 * Increased output verbosity (when -Verbose parameter is specified)
	 * Minor performance enhancements

	 1.1 December 13th, 2015
	 ------------------------------
	 * Changed suggested script name to Get-VMOrphanedFiles from Get-OrphanedVMFiles; makes more consistent with other VM scripts
	 * Replaced all instances of -notin with -notcontains to improve compatibility with other PowerShell hosts
	 * Any detected CSV will be scanned even if no host returns it as a search path (unless -SkipCSVs is specified)
	 * Added duplicate sub-folder check to SMB paths (was already functional for all other path types)
	 * Numerous refactorings for readability and a tiny bit of performance

.LINK
	 
Free Script: Find Orphaned Hyper-V VM Files
.EXAMPLE C:PS> .Get-VMOrphanedFiles Description ----------- Retrieves orphaned VM files in this host's default VM path and those of current VMs. .EXAMPLE C:PS> .Get-VMOrphanedFiles -Path D: Description ----------- Retrieves orphaned VMs on this host contained anywhere on the D: drive. .EXAMPLE C:PS> .Get-VMOrphanedFiles -ExcludeExistingVMPaths Description ----------- Retrieves orphaned VM files in this host's default VM path, ignoring any paths of VMs that are outside the default. C:PS> .Get-VMOrphanedFiles -ExcludeDefaultPath Description ----------- Retrieves orphaned VM files in the paths of existing VMs except those contained in the host's default path. C:PS> .Get-VMOrphanedFiles -ComputerName svhv1, svhv2 -Path \smb3sharevms Description ----------- Checks for VM files on the \smb3sharevms that are not connected to any VMs registered to svhv1 or svhv2. C:PS> .Get-VMOrphanedFiles -ComputerName svhv1, svhv2 -Path C: Description ----------- Checks for VM files on the local C: drives of svhv1 and svhv2. C:PS> Get-VMHost server1, server2, server3 | .Get-VMOrphanedFiles Description ----------- Retrieves orphaned VM files in the default and current VM paths for hosts named server1, server2, and server3. C:PS> .Get-VMOrphanedFiles -ComputerName svhv1 -Path C: -IgnoreClusterMembership Description ----------- Retrieves orphaned VM files on the C: drive of SVHV1, skipping the ClusterStorage folder and not scanning any other hosts in the cluster. C:PS> .Get-VMOrphanedFiles -ComputerName svhv1, svhv2 -Path -Credential (Get-Credential) Description ----------- Checks for orphaned VM files on svhv1's and svhv2's default paths using the credentials that you specify. Files on SMB 3 storage will be scanned using the credentials of the local session. #> #requires -Version 3 [CmdletBinding(DefaultParameterSetName='UnspecifiedPath')] param( [Alias('Host', 'HostName', 'VMHosts', 'Hosts', 'VMHost')] [Parameter(ValueFromPipeline=$true, ValueFromPipelineByPropertyName=$true)] [Object[]][email protected](,$env:COMPUTERNAME), [Alias("VirtualMachinePath")] [Parameter(ValueFromPipeline=$true, ValueFromPipelinebyPropertyName=$true,ParameterSetName='SpecifiedPath')] [String[]][email protected](), [Parameter(ValueFromPipelineByPropertyName=$true,ParameterSetName='SpecifiedPath')] [Switch]$IncludeDefaultPath, [Parameter(ValueFromPipelineByPropertyName=$true,ParameterSetName='SpecifiedPath')] [Switch]$IncludeExistingVMPaths, [Parameter(ValueFromPipelineByPropertyName=$true,ParameterSetName='UnspecifiedPath')] [Switch]$ExcludeDefaultPath, [Parameter(ValueFromPipelineByPropertyName=$true,ParameterSetName='UnspecifiedPath')] [Switch]$ExcludeExistingVMPaths, [Parameter(ValueFromPipelineByPropertyName=$true)] [Switch]$IgnoreClusterMembership, [Parameter(ValueFromPipeline=$true, ValueFromPipelineByPropertyName=$true)] [System.Management.Automation.PSCredential]$Credential ) BEGIN { ######################### Script block definitions ############################### $VMFilePathsScriptBlock = { param( [Parameter(Position=0)][Boolean]$ReturnDefaultPaths, [Parameter(Position=1)][Boolean]$ReturnVMPaths, [Parameter(Position=2)][System.Management.Automation.ActionPreference]$RemoteVerbosePreference = [System.Management.Automation.ActionPreference]::SilentlyContinue ) function Parse-LocalOrSharedVMFilePath { param( [Parameter()][String]$VMHost = '', [Parameter()][String]$ItemType, # 'path' for a file-system path, 'shared' for a UNC, 'metafile' for a non-disk VM file, 'disk' for a VM disk file [Parameter()][String]$PathOrFile, # this is the item that will be operated on [Parameter()][String]$VMNameToRemove = '', # if provided, it will be removed from the end of an item (usually to find the parent) [Parameter()][String]$VMId = $null ) if($ItemType -eq 'converttopath') { $PathOrFile = $PathOrFile -replace '(\)[^\]*\?$' # remove file name $ItemType = 'path' } if($ItemType -ne 'path') { $PathOrFile = $PathOrFile -replace '\$' # no trailing slashes on files } if($PathOrFile -match '^\\[^?|.]') # item is on a share { $HostPrefix = '' # Hyper-V doesn't support SMB3 loopback, so no VMHost owns the supplied file or path } else { $PathOrFile = $PathOrFile -replace '^\\?', '\.' # raw volume identifiers might come in with a ? but must go out with a . $HostPrefix = $VMHost } if(-not [String]::IsNullOrEmpty($VMNameToRemove)) { $PathOrFile = $PathOrFile -replace "$VMNameToRemove\?$" # lop off any remote path } [String]::Join(';', ($HostPrefix, $ItemType, $PathOrFile)) } function Get-DifferencingChain { param( [Parameter()][String]$VHDPath ) if($VHDPath -notmatch '^\\[^?|.]') # the calling host will have to deal with differencing disks on shares { $VHDPath = $VHDPath -replace '^\\?', '\.' # Get-VHD can only operate on raw volume identifiers with a . and these files haven't yet gone through the sanitizer Write-Verbose -Message ('Checking for parent disks of ' + $VHDPath) $VHD = Get-VHD -Path $VHDPath if($VHD.ParentPath) { Write-Verbose -Message ('Parent found, traversing chain...') $VHD.ParentPath Get-DifferencingChain $VHD.ParentPath } } } $VerbosePreference = $RemoteVerbosePreference $FileList = @() # this is what is returned to the calling system $MetaFileList = @() $DiskFileList = @() if(-not (Get-Module -Name Hyper-V -ListAvailable)) { throw((Get-WmiObject -Class Win32_ComputerSystem).Name + ' does not have the Hyper-V PowerShell module installed') } Write-Verbose -Message 'Retrieving Hyper-V host information...' $VMHostData = Get-VMHost $VMHostName = $VMHostData.Name if($VMHostData.FullyQualifiedDomainName.Contains('.')) { $VMHostName += '.' + $VMHostData.FullyQualifiedDomainName } $VMHostName = $VMHostName.ToLower() Write-Verbose -Message ('Host name: ' + $VMHostName) $HostHVRegistrationPath = (Resolve-Path "$($env:ProgramData)MicrosoftWindowsHyper-V").Path Write-Verbose -Message ('Virtual machine registration path: ' + $HostHVRegistrationPath) Write-Verbose -Message ('Default virtual machine path: ' + $VMHostData.VirtualMachinePath) if($VMHostData.VirtualMachinePath -match '^\\[^?|.]') { $ThisHostVMPathShared = $true $ThisHostVMPathType = 'shared' Write-Verbose -Message 'The default virtual machine path is on an SMB 3 share' } else { $ThisHostVMPathShared = $false $ThisHostVMPathType = 'path' Write-Verbose -Message 'The default virtual machine path is on locally-addressed storage' } Write-Verbose -Message ('Default virtual hard disk path: ' + $VMHostData.VirtualHardDiskPath) if($VMHostData.VirtualHardDiskPath -match '^\\[^?|.]') { $ThisHostVMHDShared = $true $ThisHostVMHDType = 'shared' Write-Verbose -Message 'The default virtual hard disk path is on an SMB 3 share' } else { $ThisHostVMHDShared = $false $ThisHostVMHDType = 'path' Write-Verbose -Message 'The default virtual hard disk path is on locally-addressed storage' } if($ReturnDefaultPaths) { $FileList += Parse-LocalOrSharedVMFilePath -VMHost $VMHostName -ItemType $ThisHostVMPathType -PathOrFile $VMHostData.VirtualMachinePath Write-Verbose -Message ($VMHostData.VirtualMachinePath + ' added to scan paths') $FileList += Parse-LocalOrSharedVMFilePath -VMHost $VMHostName -ItemType $ThisHostVMHDType -PathOrFile $VMHostData.VirtualHardDiskPath Write-Verbose -Message ($VMHostData.VirtualHardDiskPath + ' added to scan paths') $FileList += Parse-LocalOrSharedVMFilePath -VMHost $VMHostName -ItemType 'path' -PathOrFile $HostHVRegistrationPath Write-Verbose -Message ($HostHVRegistrationPath + ' added to scan paths') } if(Test-Path -Path ($env:SystemDrive + 'ClusterStorage')) { Write-Verbose -Message 'Enumerating cluster shared volumes' foreach ($CSVPath in Get-ChildItem -Path ($env:SystemDrive + 'ClusterStorage')) { $FileList += Parse-LocalOrSharedVMFilePath -VMHost $VMHostName -ItemType 'path' -PathOrFile $CSVPath.FullName Write-Verbose -Message ($CSVPath.FullName + ' added to scan paths') } } foreach ($VM in Hyper-VGet-VM) { $ThisVMId = $VM.VMId $ThisVMPrimaryPath = $VM.Path if($ThisVMPrimaryPath -match '^\\[^?|.]') { $ThisVMPrimaryPathShared = $true $ThisVMPrimaryPathType = 'shared' Write-Verbose -Message ('Primary path for "{0}" is on SMB share: "{1}"' -f $VM.Name, $ThisVMPrimaryPath) } else { $ThisVMPrimaryPathShared = $false $ThisVMPrimaryPathType = 'path' Write-Verbose -Message ('Primary path for "{0}" is in locally-addressed space: "{1}"' -f $VM.Name, $ThisVMPrimaryPath) } $ThisVMConfigurationPath = $VM.ConfigurationLocation if($ThisVMConfigurationPath -match '^\\[^?|.]') { $ThisVMConfigurationPathShared = $true $ThisVMConfigurationPathType = 'shared' Write-Verbose -Message ('Configuration files for "{0}" are on SMB share: "{1}"' -f $VM.Name, $ThisVMConfigurationPath) } else { $ThisVMConfigurationPathShared = $false $ThisVMConfigurationPathType = 'path' Write-Verbose -Message ('Configuration files for "{0}" are in locally-addressed space: "{1}"' -f $VM.Name, $ThisVMConfigurationPath) } $ThisVMSnapshotPath = $VM.SnapshotFileLocation if($ThisVMSnapshotPath -match '^\\[^?|.]') { $ThisVMSnapshotPathShared = $true $ThisVMSnapshotPathType = 'shared' Write-Verbose -Message ('Checkpoint files for "{0}" are on SMB share: "{1}"' -f $VM.Name, $ThisVMSnapshotPath) } else { $ThisVMSnapshotPathShared = $false $ThisVMSnapshotPathType = 'path' Write-Verbose -Message ('Checkpoint files for "{0}" are in locally-addressed space: "{1}"' -f $VM.Name, $ThisVMSnapshotPath) } $ThisVMSLPPath = $VM.SmartPagingFilePath if($ThisVMSLPPath -match '^\\[^?|.]') { $ThisVMSLPPathShared = $true $ThisVMSLPPathType = 'shared' Write-Verbose -Message ('Smart paging files for "{0}" are on SMB share: "{1}"' -f $VM.Name, $ThisVMSLPPath) } else { $ThisVMSLPPathShared = $false $ThisVMSLPPathType = 'path' Write-Verbose -Message ('Smart paging files for "{0}" are in locally-addressed space: "{1}"' -f $VM.Name, $ThisVMSLPPath) } # Get configuration files Write-Verbose -Message ('Adding configuration files for "' + $VM.Name + '" to scan list') $MetaFileList += (Get-ChildItem -File -Path $HostHVRegistrationPath -Recurse -Filter "$ThisVMId.xml").FullName if($ThisVMConfigurationPathShared) { $ThisItem = Parse-LocalOrSharedVMFilePath -ItemType 'shared' -PathOrFile $ThisVMConfigurationPath $FileList += [String]::Join(',', ($ThisItem, $ThisVMId, $VM.Name, 'configuration')) } else { $MetaFileList += (Get-ChildItem -File -Path $ThisVMConfigurationPath -Recurse -Filter "$ThisVMId.xml").FullName $MetaFileList += (Get-ChildItem -File -Path $ThisVMConfigurationPath -Recurse -Filter "$ThisVMId.bin").FullName $MetaFileList += (Get-ChildItem -File -Path $ThisVMConfigurationPath -Recurse -Filter "$ThisVMId.vsv").FullName } # Get snapshot files Write-Verbose -Message ('Adding checkpoint files for "' + $VM.Name + '" to scan list') if($ThisVMSnapshotPathShared) { $ThisItem = Parse-LocalOrSharedVMFilePath -ItemType 'shared' -PathOrFile $ThisVMSnapshotPath $FileList += [String]::Join(",", ($ThisItem, $ThisVMId, $VM.Name, 'snapshotpath')) } else { $SnapshotRoot = (Get-ChildItem -Directory -Path $ThisVMSnapshotPath -Filter 'Snapshots').FullName } Get-VMSnapshot -VM $VM | foreach { Write-Verbose -Message ('Adding checkpoint files for "' + $VM.Name + '" with ID: "' + $_.Id + '" to scan list') $MetaFileList += (Get-ChildItem -File -Path $HostHVRegistrationPath -Recurse -Filter "$($_.Id).xml").FullName if($ThisVMSnapshotPathShared) { $SharedFileList += [String]::Join(",", ($ThisVMSnapshotPath, $_.Id, 'snapshot')) } else { $MetaFileList += (Get-ChildItem -File -Path $SnapshotRoot -Recurse -Filter "$($_.Id).xml").FullName $MetaFileList += (Get-ChildItem -File -Path $SnapshotRoot -Recurse -Filter "$($_.Id).vsv").FullName $MetaFileList += (Get-ChildItem -File -Path $SnapshotRoot -Recurse -Filter "$($_.Id).bin").FullName } Get-VMHardDiskDrive -VMSnapshot $_ | foreach { $DiskFileList += $_.Path if($ReturnVMPaths) { $FileList += Parse-LocalOrSharedVMFilePath -VMHost $VMHostName -ItemType 'converttopath' -PathOrFile ($_.Path) } } if($VM.Generation -lt 2) { Get-VMFloppyDiskDrive -VMSnapshot $_ | foreach { if($_.Path) { $DiskFileList += $_.Path if($ReturnVMPaths) { $FileList += Parse-LocalOrSharedVMFilePath -VMHost $VMHostName -ItemType 'converttopath' -PathOrFile ($_.Path) } } } } } # Get Smart Paging files Write-Verbose -Message ('Adding smart paging files for "' + $VM.Name + '" to scan list') if($VM.SmartPagingFileInUse) { if($ThisVMSLPPathShared) { $ThisItem = Parse-LocalOrSharedVMFilePath -ItemType 'shared' -PathOrFile $ThisVMSLPPath $FileList += [String]::Join(',', ($ThisItem, $ThisVMId, $VM.Name, 'slp')) } else { $MetaFileList += (Get-ChildItem -File -Path $ThisVMSLPPath -Recurse -Filter "$($_.Id).*.slp").FullName } } # Get virtual hard/floppy disks Write-Verbose -Message ('Adding virtual disk files for "' + $VM.Name + '" to scan list') Get-VMHardDiskDrive -VM $VM | foreach { $ThisVMDiskList = @() $ThisVMDiskList += $_.Path $ThisVMDiskList += Get-DifferencingChain $_.Path if($ReturnVMPaths) { foreach($VMDisk in $ThisVMDiskList) { $FileList += Parse-LocalOrSharedVMFilePath -VMHost $VMHostName -ItemType 'converttopath' -PathOrFile ($VMDisk) } } $DiskFileList += $ThisVMDiskList } if($VM.Generation -lt 2) { $DiskFileList += (Get-VMFloppyDiskDrive -VM $VM).Path } } $MetaFileList | foreach { if(-not [String]::IsNullOrEmpty($_)) { $FileList += Parse-LocalOrSharedVMFilePath -VMHost $VMHostName -ItemType 'metafile' -PathOrFile $_ } } $DiskFileList | foreach { if(-not [String]::IsNullOrEmpty($_)) { $FileList += Parse-LocalOrSharedVMFilePath -VMHost $VMHostName -ItemType 'disk' -PathOrFile $_ } if($ReturnVMPaths) { $FileList += Parse-LocalOrSharedVMFilePath -VMHost $VMHostName -ItemType 'path' -PathOrFile $ThisVMPrimaryPath -VMNameToRemove $_.Name $FileList += Parse-LocalOrSharedVMFilePath -VMHost $VMHostName -ItemType 'path' -PathOrFile $ThisVMConfigurationPath -VMNameToRemove $_.Name $FileList += Parse-LocalOrSharedVMFilePath -VMHost $VMHostName -ItemType 'path' -PathOrFile $ThisVMSnapshotPath -VMNameToRemove $_.Name $FileList += Parse-LocalOrSharedVMFilePath -VMHost $VMHostName -ItemType 'path' -PathOrFile $ThisVMSLPPath -VMNameToRemove $_.Name } } $FileList | select -Unique } $SearchScriptBlock = { param ( [Parameter(Position=0)][String[]]$SearchPaths, [Parameter(Position=1)][String[]]$FileExclusions, [Parameter(Position=2)][String[]]$DiskExclusions, [Parameter(Position=3)][Boolean]$SkipCSVs ) function Escape-Path { param( [Parameter()][String]$Path ) try { $ReturnPath = (Resolve-Path -Path $Path -ErrorAction Stop).Path $ReturnPath -replace "\", "\" # This is not a typo. This turns single backslashes into double backslashes. I promise. } catch { # just means the path wasn't there } } $LocalClusterStorage = (Escape-Path -Path "$($env:SystemDrive)ClusterStorage") $DirectoryExclusions = @( (Escape-Path -Path "$($env:SystemRoot)Vss"), # vss writers are also registered as <guid>.xml (Escape-Path -Path "$($env:SystemRoot)WinSxs"), # many things in here will trigger a response (Escape-Path -Path "$($env:ProgramData)MicrosoftWindowsHyper-VResource Types") # HV resource types are also registered as <guid>.xml ) if($SkipCSVs) { $DirectoryExclusions += $LocalClusterStorage } foreach($SearchPath in $SearchPaths) { try # because Test-Path doesn't work on raw volume identifiers, that's why { Get-ChildItem -Path $SearchPath -ErrorAction Stop | Out-Null $PathFound = $true } catch { $PathFound = $false } if($PathFound) { $CompareGUID = New-Object System.Guid Get-ChildItem -File -Path $SearchPath -Recurse | where { # first, parse the extension for virtual hard/floppy disk files as that is the fastest of possible operations if($_.Extension -match "v(h|f)d") { if($SkipCSVs -and $_.DirectoryName -match $LocalClusterStorage) { $false } elseif($DiskExclusions -notcontains $_.FullName.ToLower()) { $true } } elseif($_.Extension -match "xml|bin|vsv") { $InExcludedDirectory = $false $DirectoryName = $_.DirectoryName $DirectoryExclusions | foreach { if($DirectoryName -match $_) { $InExcludedDirectory = $true } } if(-not $InExcludedDirectory) { #VM files of this type will all be formatted as a GUID if([System.Guid]::TryParse($_.BaseName, [ref]$CompareGUID)) { if($FileExclusions -notcontains $_.FullName.ToLower()) { $true } } } } } } } } ######################### Function definitions ############################### function Parse-LocalOrSharedItem { <# .DESCRIPTION Determines if a path is on a local system or is shared. If local, attaches it to the submitted host name for later processing. Also cleans up path entries for use with later functions and cmdlets. #> param( [Parameter()][String]$CurrentPath, [Parameter()][String]$CurrentHost = "" ) $CurrentPath = $CurrentPath -replace "`"|'" # remove quotes $CurrentPath = $CurrentPath -replace "^\\?", "\." if($CurrentPath -match "^\\[^.]" -or [String]::IsNullOrEmpty($CurrentHost)) { $($CurrentPath.ToLower()) } else { ([String]::Join(",", ($CurrentPath, $CurrentHost))).ToLower() } } function Dedupe-CSV <# Resets all items that target *clusterstorage* so that the same location isn't scanned from multiple nodes or false positives returned. Also, if the IgnoreClusterMembership flag is set, these items are simply removed so that they won't be scanned at all. #> { param( [Parameter()][String[]]$ClusterList, [Parameter()][String[]]$ArrayWithCSV # this script was designed so that computer names will always appear in element[1] ) $ItemsToRemove = @() $ReplacementItems = @() foreach($ClusterItem in $ClusterList) { $PrimaryNode = $ClusterItem.Split(";")[0] $NodeList = $ClusterItem.Split(";")[1] foreach($ItemWithCSV in $ArrayWithCSV) { if($ItemWithCSV -match ":\clusterstorage") { $PathOrItem = $ItemWithCSV.Split(",")[0] $OriginalNode = $ItemWithCSV.Split(",")[1] if($PrimaryNode -ne $OriginalNode) { $ItemsToRemove += $ItemWithCSV if(-not $IgnoreClusterMembership) { $ReplacementItems += [String]::Join(",", ($PathOrItem, $PrimaryNode)) } } } } } if($ItemsToRemove.Count -gt 0 -and $ReplacementItems.Count -gt 0) { $ArrayWithCSV = $ArrayWithCSV | where { $ItemsToRemove -notcontains $_ } $ArrayWithCSV + $ReplacementItems } else { $ArrayWithCSV } } function Remove-SubPaths { <# .DESCRIPTION Given an array of paths, finds items that are subpaths of another and removes them #> param( [Parameter()]$PathArray ) $PathsToRemove = @() foreach($PathOuter in $PathArray) { if($IgnoreClusterMembership -and $PathOuter -match "(:|\\[.|?]\Volume{.*})\ClusterStorage") # function re-usability warning on $IgnoreClusterMembership { $PathsToRemove += $PathOuter } else { foreach($PathInner in $PathArray) { if($PathOuter -ne $PathInner) { $Path1 = $PathOuter.Split(",") $Path2 = $PathInner.Split(",") $CanProcess = $true if($Path1[1].Length -gt 0 -and $Path2[1].Length -gt 0) { if($Path1[1] -ne $Path2[1]) { $CanProcess = $false } } if($CanProcess) { if($Path1[0].Contains($Path2[0])) { $PathsToRemove += $PathOuter } } } } } } $PathArray | where { $PathsToRemove -notcontains $_ } | select -Unique } function Get-RemoteData { <# .DESCRIPTION A generic function that runs the indicated scriptblock in parallel against the indicated group of hosts and returns the results as an array. #> param( [Parameter()][String[]]$VMHosts, [Parameter()][ScriptBlock]$ScriptBlock, [Parameter()][String]$InvokeErrorTemplate, [Parameter()][String]$ResultsErrorTemplate, [Parameter()][Object[]]$ArgumentList = $null, [Parameter()][System.Management.Automation.PSCredential]$Credential = $null, [Parameter()][String]$VerboseAction='' ) $SessionList = @() $JobList = @() $ResultsArray = @() $ArgumentList += $VerbosePreference foreach($VMHost in $VMHosts) { try { $SessionParameters = @{'ComputerName'=$VMHost;'ErrorAction'='Stop' } if($Credential) { $SessionParameters.Add('Credential', $Credential) } Write-Verbose -Message ('Establishing a PowerShell session on ' + $VMHost) $Session = New-PSSession @SessionParameters $JobList += Invoke-Command -Session $Session -ScriptBlock $ScriptBlock -ErrorAction Stop -AsJob -ArgumentList $ArgumentList $SessionList += $Session } catch [Exception] { Write-Error -Message ($InvokeErrorTemplate -f $VMHost, $_) } } if($JobList.Count) { Wait-Job -Job $JobList -ErrorAction Stop | Out-Null } foreach($Job in $JobList) { try { $ResultsArray += Receive-Job -Job $Job -ErrorAction Stop } catch { Write-Error -Message ($ResultsErrorTemplate -f $Job.Location, $_) $VMHosts = $VMHosts | where { $_ -ne $VMHost } } } $SessionList | Remove-PSSession $JobList | Remove-Job $ResultsArray } function Get-VHDDifferencingParent { param( [Parameter(Mandatory=$true, ValueFromPipeline=$true, ValueFromPipelineByPropertyName=$true)][String]$Path ) $AbsolutePath = "" $IdentifierSize = 8 $IdentifierBytes = New-Object Byte[] $IdentifierSize try { try { $VHDStream = New-Object System.IO.FileStream($Path, [System.IO.FileMode]::Open, [System.IO.FileAccess]::Read, [System.IO.FileShare]::ReadWrite) -ErrorAction Stop } catch { throw ("Unable to open differencing disk {0} to determine its parent: {1}" -f $Path, $_) } try { $BytesRead = $VHDStream.Read($IdentifierBytes, 0, $IdentifierSize) } catch { throw ("Unable to read the VHD type identifier for {0}: {1}" -f $Path, $_) } if([System.Text.Encoding]::ASCII.GetString($IdentifierBytes) -eq "vhdxfile") { $1stRegionOffset = 196608; $1stRegionEntryCount = 0; $2ndRegionOffset = 262144; $2ndRegionEntryCount = 0 $SignatureSize = 4; $EntryCountSize = 8; $GUIDSize = 16; $EntryOffsetSize = 8; $EntryLengthSize = 4 $ShortEntrySize = 2; $MetadataOffsetSize = 4; $KeyValueCountSize = 2; $LocatorEntrySize = 12 $SignatureBytes = New-Object Byte[] $SignatureSize; $EntryCountBytes = New-Object Byte[] $EntryCountSize $GUIDBytes = New-Object Byte[] $GUIDSize; $EntryOffset = New-Object Byte[] $EntryOffsetSize $ShortEntryBytes = New-Object Byte[] $ShortEntrySize; $MetadataOffsetBytes = New-Object Byte[] $MetadataOffsetSize $KeyValueCountBytes = New-Object Byte[] $KeyValueCountSize; $LocatorEntryBytes = New-Object Byte[] $LocatorEntrySize $LocatorEntries = @() ($1stRegionOffset, $2ndRegionOffset) | foreach { $VHDStream.Position = $_ try { $BytesRead = $VHDStream.Read($SignatureBytes, 0, $SignatureSize) } catch { throw ("Unable to read signature from header region of {0}: {1}" -f $Path, $_) } if([System.Text.Encoding]::ASCII.GetString($SignatureBytes) -eq "regi") { $VHDStream.Position += 4 # jump over the checksum try { $BytesRead = $VHDStream.Read($EntryCountBytes, 0, $EntryCountSize) } catch { throw ("Unable to determine number of header entries in {0}: {1}" -f $Path, $_) } $RegionEntryCount = [System.BitConverter]::ToInt32($EntryCountBytes, 0) if($_ = $1stRegionOffset) { $1stRegionEntryCount = $RegionEntryCount } else { $2ndRegionEntryCount = $RegionEntryCount } } } if($1stRegionEntryCount -ge $2ndRegionEntryCount) { $EntryCount = $1stRegionEntryCount $StartingEntryOffset = $1stRegionOffset + 16 } else { $EntryCount = $2ndRegionEntryCount $StartingEntryOffset = $2ndRegionOffset + 16 } 1..$EntryCount | foreach { $VHDStream.Position = $StartingEntryOffset + (32 * ($_ - 1)) # an entry is 32 bytes long try { $BytesRead = $VHDStream.Read($GUIDBytes, 0, $GUIDSize) } catch { throw ("Unable to retrieve the GUID of a header entry in {0}, {1}" -f $Path, $_) } if([System.BitConverter]::ToString($GUIDBytes) -eq "06-A2-7C-8B-90-47-9A-4B-B8-FE-57-5F-05-0F-88-6E") # this is the GUID of a metadata region { try { $BytesRead = $VHDStream.Read($EntryOffset, 0, $EntryOffsetSize) } catch { throw("Unable to determine the location of a metadata region in {0}: {1}" -f $Path, $_) } $MetadataStart = $VHDStream.Position = [System.BitConverter]::ToInt64($EntryOffset, 0) try { $BytesRead = $VHDStream.Read($IdentifierBytes, 0, $IdentifierSize) } catch { throw("Unable to parse the identifier of an expected metadata region in {0}: {1}"-f $Path, $_) } if([System.Text.Encoding]::ASCII.GetString($IdentifierBytes) -eq "metadata") { $VHDStream.Position += 2 # jump over reserved field try { $BytesRead = $VHDStream.Read($ShortEntryBytes, 0, $ShortEntrySize) } catch { throw("Unable to retrieve the number of header short entries in {0}: {1}" -f $Path, $_) } $VHDStream.Position += 20 # jump over the rest of the header 1..([System.BitConverter]::ToUInt16($ShortEntryBytes, 0)) | foreach { try { $BytesRead = $VHDStream.Read($GUIDBytes, 0, $GUIDSize) } catch { throw ("Unable to retrieve the GUID of a short entry in {0}: {1}" -f $Path, $_) } $SavedStreamPosition = $VHDStream.Position switch([System.BitConverter]::ToString($GUIDBytes)) { ## We're only watching for a single item so an "if" could do this, but switch is future-proofing. ## Should be able to query 37-67-A1-CA-36-FA-43-4D-B3-B6-33-F0-AA-44-E7-6B for a "HasParent" value, but either the documentation is wrong or the implementation is broken as this field holds the same value for all disk types "2D-5F-D3-A8-0B-B3-4D-45-AB-F7-D3-D8-48-34-AB-0C" { # Parent Locator try { $BytesRead = $VHDStream.Read($MetadataOffsetBytes, 0, $MetadataOffsetSize) } catch { throw ("Unable to read the location of a metadata entry in {0}: {1}" -f $Path, $_) } if($BytesRead) { $ParentLocatorOffset = $MetadataStart + [System.BitConverter]::ToInt32($MetadataOffsetBytes, 0) $VHDStream.Position = $ParentLocatorOffset + 18 # jump over the GUID and reserved fields try { $BytesRead = $VHDStream.Read($KeyValueCountBytes, 0, $KeyValueCountSize) } catch { throw("Unable to read the number of key/value metadata sets in {0}: {1}" -f $Path, $_) } if($BytesRead) { 1..[System.BitConverter]::ToUInt16($KeyValueCountBytes, 0) | foreach { try { $BytesRead = $VHDStream.Read($LocatorEntryBytes, 0, $LocatorEntrySize) } catch { throw ("Unable to retrieve a key/value metadata set from {0}: {1}" -f $Path, $_) } if($BytesRead) { $KeyOffset = [System.BitConverter]::ToUInt32($LocatorEntryBytes, 0) $ValueOffset = [System.BitConverter]::ToUInt32($LocatorEntryBytes, 4) $KeyLength = [System.BitConverter]::ToUInt16($LocatorEntryBytes, 8) $ValueLength = [System.BitConverter]::ToUInt16($LocatorEntryBytes, 10) $LocatorEntries += [String]::Join(",", ($KeyOffset, $ValueOffset, $KeyLength, $ValueLength)) } } foreach($Locator in $LocatorEntries) { $KeyValueSet = $Locator.Split(",") $KeyPosition = $ParentLocatorOffset + $KeyValueSet[0] $ValuePosition = $ParentLocatorOffset + $KeyValueSet[1] $KeyBytes = New-Object Byte[] $KeyValueSet[2] $ValueBytes = New-Object Byte[] $KeyValueSet[3] $VHDStream.Position = $KeyPosition try { # NOTE: we don't actually do anything with the key, technically could move the pointer past it to the value $BytesRead = $VHDStream.Read($KeyBytes, 0, $KeyBytes.Length) } catch { throw ("Unable to retrieve the parent path key in the key/value set of {0}: {1}") } if($BytesRead) { if([System.Text.Encoding]::Unicode.GetString($KeyBytes) -eq "absolute_win32_path") { try { $BytesRead = $VHDStream.Read($ValueBytes, 0, $ValueBytes.Length) } catch { throw ("Unable to retrieve the parent path value in the key/value set of {0}: {1}") } if($BytesRead) { $AbsolutePath = [System.Text.Encoding]::Unicode.GetString($ValueBytes) break } } } } } } } } # move to the start of the next entry $VHDStream.Position = $SavedStreamPosition + 16 } } } } } elseif([System.Text.Encoding]::ASCII.GetString($IdentifierBytes) -eq "conectix") # this is a VHD file { $TypeSize = 4; $ChunkSize = 2 $TypeBytes = New-Object Byte[] $TypeSize -ErrorAction Stop; $ChunkBytes = New-Object Byte[] $ChunkSize -ErrorAction Stop $ReverseParentBytes = [Byte[]]@() $VHDStream.Position = 60 # this is where the disk type is stored try { $BytesRead = $VHDStream.Read($TypeBytes, 0, $TypeSize) } catch { throw ("Unable to determine the disk type of {0}: {1}" -f $Path, $_) } if($BytesRead) { [Array]::Reverse($TypeBytes) # surprise byte reversal! if([System.BitConverter]::ToUInt32($TypeBytes, 0) -eq 4) # is the differencing type { $VHDStream.Position = 576 # this is where the name of the parent is stored, if any 1..256 | foreach { # there are 512 bytes in the name, but they're also reversed. this is much more miserable to fix try { $BytesRead = $VHDStream.Read($ChunkBytes, 0, $ChunkSize) } catch { throw ("Unable to read the parent of {0}: {1}" -f $Path, $_) } if($BytesRead) { [Array]::Reverse($ChunkBytes) $ReverseParentBytes += $ChunkBytes } } $AbsolutePath = [System.Text.Encoding]::Unicode.GetString($ReverseParentBytes) -replace "(?<=.vhd).*" # remove leftover noise } } } else { throw ("{0} is not a valid VHD(X) file or has a damaged header" -f $Path) } } catch { <# PowerShell does not implement any form of "goto" or "using", so the purpose of this outer try block is to simulate goto functionality with an ending point that ensures that the file is always closed, if one was opened. otherwise, PS's normal erroring is sufficient #> throw($_) } finally { if($VHDStream) { $VHDStream.Close() } } $AbsolutePath } } PROCESS { $VMHosts = [String[]]@() # verified list of hosts to scan; built from -ComputerName; cluster nodes will be added automatically $Clusters = [String[]]@() # discovered clusters. item format: primary node; node1, node2, node3, ... $RemotePathsToScan = @() # any paths to scan that are not on a share; even local paths will be scanned via remote session, includes host name $SharedPathsToScan = @() # any shared paths to scan $RemoteMetaFileExclusions = @() # known good xml, bin, vsv, and slp files that are not on a share, includes host name $RemoteDiskFileExclusions = @() # known good vhd, vhdx, avhd, avhdx, and vfd files that are not on a share, includes host name $SharedMetaFileExclusions = @() # known good xml, bin, vsv, and slp files that are on a share $SharedDiskFileExclusions = @() # known good vhd, vhdx, avhd, avhdx, and vfd files that are on a share ######################### Validate input parameters ############################### switch($PSCmdlet.ParameterSetName) { 'SpecifiedPath' { $UseDefaultPath = $IncludeDefaultPath $UseExistingVMPaths = $IncludeExistingVMPaths } 'UnspecifiedPath' { $UseDefaultPath = -not $ExcludeDefaultPath $UseExistingVMPaths = -not $ExcludeExistingVMPaths } } if([String]::IsNullOrEmpty($Path) -and -not $UseDefaultPath -and -not $UseExistingVMPaths) { throw('No path specified for scan') } Write-Verbose -Message "Using default path(s): $UseDefaultPath" Write-Verbose -Message "Using existing VM path(s): $UseExistingVMPaths" ######################### Validate host list ############################### Write-Verbose "Verifying hosts" foreach ($VMHost in $ComputerName) { if($VMHost.GetType().ToString() -match "Microsoft.HyperV.PowerShell.VMHost") { $VMHost = $VMHost.Name } try { $GwmiComputerParameters = @{'ComputerName'=$VMHost;'Class'='Win32_ComputerSystem';'ErrorAction'='Stop' } if($Credential) { $GwmiComputerParameters.Add('Credential', $Credential) } $ComputerObject = Get-WmiObject @GwmiComputerParameters } catch { Write-Warning "Unable to contact $VMHost. Skipping." $VMHost = "" } if(-not [String]::IsNullOrEmpty($VMHost)) { $ShortName = $ComputerObject.Name.ToLower() if($ComputerObject.Domain.Contains(".")) # this will drop the ball for single-level domains, but people with single-level domains have bigger problems than a few VM files going astray so the extra effort to determine if it's truly a domain member is probably not worth it { $VMHost = [String]::Join(".", ($ShortName, $ComputerObject.Domain)) if(-not $IgnoreClusterMembership) { try { $GwmiNodeParameters = @{'ComputerName'=$VMHost;'Class'='MSCluster_Node';'Namespace'='rootMSCluster';'ErrorAction'='Stop' } if($Credential) { $GwmiNodeParameters.Add('Credential',$Credential) } $Nodes = (Get-WmiObject @GwmiNodeParameters).Name $GwmiClusterDomainParameters = @{'ComputerName'=$VMHost;'Class'='Win32_ComputerSystem';'Namespace'='rootCIMV2';'ErrorAction'='Stop' } if($Credential) { $GwmiClusterDomainParameters.Add('Credential',$Credential) } $ClusterDomain = (Get-WmiObject @GwmiClusterDomainParameters).Domain $Nodes = $Nodes | foreach { "$_.$ClusterDomain" } foreach($Node in $Nodes) { if($VMHosts -notcontains $Node) { Write-Verbose "Adding $Node to scan list" $VMHosts += $Node } } $Clusters += [String]::Join(";", ("$($Nodes[0])", ([String]::Join(",", $Nodes)))) } catch { # this just means that the target system isn't a cluster node } } } else { $VMHost = $ShortName } if($VMHosts -notcontains $VMHost) { Write-Verbose -Message "Adding $VMHost to scan list" $VMHosts += $VMHost } } } ######################### Build exclusion and scan paths lists ############################### $ExclusionsAndPaths = Get-RemoteData ` -VMHosts $VMHosts ` -ScriptBlock $VMFilePathsScriptBlock ` -InvokeErrorTemplate "Unable to connect to {0}`r`n{1}" ` -ResultsErrorTemplate "An error occurred while retrieving host and VM data from {0}`r`n{1}" ` -ArgumentList @($UseDefaultPath, $UseExistingVMPaths) ` -Credential $Credential ` -VerboseAction 'Retrieving virtual machine files and paths' foreach($EPItem in $ExclusionsAndPaths) { $FullItem = $EPItem.Split(';') if($FullItem[1] -eq 'metafile') { $RemoteMetaFileExclusions += Parse-LocalOrSharedItem -CurrentPath $FullItem[2] -CurrentHost $FullItem[0] } elseif($FullItem[1] -eq 'disk') { $DiskFileExclusion = Parse-LocalOrSharedItem -CurrentPath $FullItem[2] -CurrentHost $FullItem[0] if($DiskFileExclusion.Contains(',')) { $RemoteDiskFileExclusions += $DiskFileExclusion } else { $SharedDiskFileExclusions += $DiskFileExclusion } } elseif($FullItem[1] -eq 'path') { $ThisPath = $FullItem[2] if($ThisPath -match '^\\[^?|.]') { $SharedPathsToScan += Parse-LocalOrSharedItem -CurrentPath $ThisPath } else { $RemotePathsToScan += Parse-LocalOrSharedItem -CurrentPath $ThisPath -CurrentHost $FullItem[0] } } else # 'shared' { $SharedPathItem = $FullItem[2].Split(',') $SharedPath = $SharedPathItem[0] $VMId = $SharedPathItem[1] $VMName = $SharedPathItem[2] $SharedItemType = $SharedPathItem[3] switch($SharedItemType) { { 'configuration' -or 'snapshot' } { $SharedMetaFileExclusions += (Get-ChildItem -File -Path $SharedPath -Recurse -Filter "$VMId.xml").FullName $SharedMetaFileExclusions += (Get-ChildItem -File -Path $SharedPath -Recurse -Filter "$VMId.bin").FullName $SharedMetaFileExclusions += (Get-ChildItem -File -Path $SharedPath -Recurse -Filter "$VMId.vsv").FullName } 'slp' { $SharedMetaFileExclusions += (Get-ChildItem -File -Path $SharedPath -Recurse -Filter "$VMId.*.slp").FullName } } } } foreach($SharedDiskFile in $SharedDiskFileExclusions) { try { $DiskFile = (Get-Item -Path $SharedDiskFile -ErrorAction Stop).FullName } catch { Write-Error -Message "Unable to access $SharedDiskFile`r`n$_" } if(-not [String]::IsNullOrEmpty($DiskFile)) { Write-Verbose -Message ("Determining the parent (if any) of {0}" -f $DiskFile) try { $Parent = Get-VHDDifferencingParent -Path $DiskFile -ErrorAction Stop while(-not [String]::IsNullOrEmpty($Parent)) { $SharedDiskFileExclusions += $Parent Write-Verbose -Message ("Determining the parent (if any) of {0}" -f $Parent) $Parent = Get-VHDDifferencingParent -Path $Parent } } catch { Write-Error $_ } } } # perform basic sanitization of user-supplied paths; no need to get crazy as PowerShell will throw its own errors on malformed paths without damaging the system if($Path.Count) { foreach($PathItem in $Path) { if($PathItem -notmatch '\$') { $PathItem += '' # for some reason, script behaves erratically when root drives are supplied without trailing slashes (e.g. 'c:'); forcing a trailing slash corrects this } if($PathItem -match '^\\[^?|.]') # matches on share paths but not raw volume identifiers { $SharedPathsToScan += Parse-LocalOrSharedItem -CurrentPath $PathItem } else { foreach($VMHost in $VMHosts) # when user supplies a path, look for it on every host; script can handle paths that don't exist everywhere { $RemotePathsToScan += Parse-LocalOrSharedItem -CurrentPath $PathItem -CurrentHost $VMHost } } } } # eliminate scanning the same CSV locations from different hosts by retargeting all CSV scans to the first cluster node $RemotePathsToScan = Dedupe-CSV -ClusterList $Clusters -ArrayWithCSV $RemotePathsToScan $RemoteMetaFileExclusions = Dedupe-CSV -ClusterList $Clusters -ArrayWithCSV $RemoteMetaFileExclusions $RemoteDiskFileExclusions = Dedupe-CSV -ClusterList $Clusters -ArrayWithCSV $RemoteDiskFileExclusions # Paths are collected; eliminate duplicates $RemotePathsToScan = $RemotePathsToScan | select -Unique $SharedPathsToScan = Remove-SubPaths -PathArray $SharedPathsToScan $SharedPathsToScan = $SharedPathsToScan | select -Unique if($PSCmdlet.MyInvocation.BoundParameters.ContainsKey('Verbose')) { foreach($PathItem in $RemotePathsToScan) { $PathDetail = $PathItem.Split(',') if($PathDetail[1].Length -gt 0) { $Addition = " on $($PathDetail[1])" } else { $Addition = '' } Write-Verbose -Message "Scan list entry: $($PathDetail[0])$Addition" } foreach($PathItem in $SharedPathsToScan) { Write-Verbose -Message "Scan list entry: $PathItem" } } # Start scanning $SessionList = @() $JobList = @() foreach($VMHost in $VMHosts) { $TargetSystemPaths = @() $TargetSystemFileExclusions = @() $TargetSystemDiskExclusions = @() $SkipCSVs = $IgnoreClusterMembership if(-not $SkipCSVs) { $VMHostIsPrimary = $false foreach($Cluster in $Clusters) { if($VMHost -eq $Cluster.Split(";")[0]) { $VMHostIsPrimary = $true } } $SkipCSVs = -not $VMHostIsPrimary } foreach($PathItem in $RemotePathsToScan) { $SearchPath = $PathItem.Split(",")[0] $SearchHost = $PathItem.Split(",")[1] if($VMHost -eq $SearchHost -or [String]::IsNullOrEmpty($SearchHost)) { $TargetSystemPaths += $SearchPath.ToLower() Write-Verbose -Message ('Adding "{0}" to search paths on "{1}"' -f $SearchPath, $VMHost) } } foreach($ExclusionItem in $RemoteMetaFileExclusions) { $Exclusion = $ExclusionItem.Split(",")[0] $ExclusionHost = $ExclusionItem.Split(",")[1] if($VMHost -eq $ExclusionHost) { $TargetSystemFileExclusions += $Exclusion.ToLower() Write-Verbose -Message ('Excluding "{0} from search on "{1}"' -f $Exclusion, $VMHost) } } foreach($ExclusionItem in $RemoteDiskFileExclusions) { $Exclusion = $ExclusionItem.Split(",")[0] $ExclusionHost = $ExclusionItem.Split(",")[1] if($VMHost -eq $ExclusionHost) { $TargetSystemDiskExclusions += $Exclusion.ToLower() Write-Verbose -Message ('Excluding "{0} from search on "{1}"' -f $Exclusion, $VMHost) } } # eliminate sub-paths of directories already marked to be scanned $TargetSystemPaths = Remove-SubPaths -PathArray $TargetSystemPaths # knock out any duplicates generated from previous operations $TargetSystemPaths = $TargetSystemPaths | select -Unique $SessionParameters = @{'ComputerName'=$VMHost} if($Credential) { $SessionParameters.Add('Credential', $Credential) } Write-Verbose "Establishing a remote session on $VMHost" $Session = New-PSSession @SessionParameters Write-Verbose "Initiating orphaned file scan on $VMHost" $JobList += Invoke-Command -Session $Session -ScriptBlock $SearchScriptBlock -AsJob -ArgumentList $TargetSystemPaths, $TargetSystemFileExclusions, $TargetSystemDiskExclusions, $SkipCSVs $SessionList += $Session } foreach($PathItem in $SharedPathsToScan) { Write-Verbose -Message "Scanning $PathItem for orphaned files" $JobList += Start-Job -ScriptBlock $SearchScriptBlock -ArgumentList $PathItem, $SharedMetaFileExclusions, $SharedDiskFileExclusions } if($JobList.Count) { Write-Verbose -Message 'Waiting for remote scans to complete' Wait-Job -Job $JobList | Out-Null Write-Verbose -Message "Retrieving file lists" $FileList = Receive-Job -Job $JobList $JobList | Remove-Job } $SessionList | Remove-PSSession $FileList } END {}

Bonus Script

The important parts of this script are contained in the body of the main script above, but I thought its contents might be useful to anyone trying to use PowerShell or .Net to work with the metadata or contents of VHD and/or VHDX files. I needed it in the above script because I promised that you could run it from any remote system, even one without the Hyper-V PowerShell module installed. Because of that, I needed some way to check VHD files to see if they are differencing disks, and if so, to retrieve their parent disk files to exclude them as orphans. To do that with a Microsoft-developed PowerShell script, you need Get-VHD. Get-VHD doesn’t only need the PowerShell module installed, it also requires the Hyper-V role to be enabled. I didn’t think it was fair to expect you to do all that just to see if a VHD on a share is a differencing disk or not, so I built a function that only needs the default PowerShell modules.

I only needed to know enough about the file to see what its parent VHD(X)s are, but there is more than enough example here to help someone go so far as to build a complete VHD(X) parser, if desired. I/O operations have always been one of my weakest programming skills, so I pretty much abandoned any notions of designing an efficient script and went for one that more or less maximizes readability. It works more than quickly enough for my purposes, but I would highly recommend that if you intend to build this into something intended for a heavier role that you spend some time optimizing what I’m leaving you.

This script illustrates how to safely open a VHD(X) file for reading, even if it’s in use by Hyper-V. It shows how to step through the components of the file to look for the information that you need. It also includes a couple of methods for deciphering the bizarre information encoding patterns of VHD files. Look in the .NOTES section of the comment-based help for links to download the specifications for both VHD and VHDX files which can help you to design a script for whatever you’re looking for.

Note: Even though this script is always safe to run, I’ve gotten semaphore timeouts while reading very large files at the other end of an SMB share.

Usage

  • Path is the script’s only input. This is a string field that will take the name of the disk file to scan. I didn’t test it, but based on my understanding of PowerShell, piping a string array to it that contains multiple file names should cause the script to run against each of them.

If the targeted file name has a parent, its complete path name will be returned as a string. If it doesn’t, the script will return nothing. The entire script is encapsulated in a single try block whose main purpose is to ensure that the targeted file is closed under any circumstances. Errors from earlier sections will be rethrown. If you call this script from one of your own, consider encapsulating it in a try block with -ErrorAction Stop.

Because this script was intended for use with the above script that does its own extensive validation, I didn’t bother with any validation of -Path. The script will fail predictably even without such checks so it’s not strictly necessary.

<#
.SYNOPSIS
Finds the parent of a differencing disk in environments where Get-VHD is not available.

.DESCRIPTION
Uses .Net functions to read a .VHD or .VHDX file to determine if it has a parent.
This is useful on computers that don't (or can't) have the Hyper-V role installed.

.PARAMETER Path
The path to the .VHD or .VHDX file to be scanned. Due to a .Net limitation, you cannot supply raw volume identifiers. You must use a drive letter or a share.

.OUTPUTS
A string containing the absolute path to the parent, or null if none exists.

.NOTES
Author: Eric Siron
Copyright: (C) 2014 Altaro Software
Version 1.1
Authored Date: October 25, 2014

Comments in this file are sparse because they more or less follow along directly from the specification documents.
VHD specification: http://www.microsoft.com/en-us/download/details.aspx?id=23850
VHDX 1.0 specification: http://www.microsoft.com/en-us/download/details.aspx?id=34750

1.1 December 13,2015
--------------------
* Changed suggested function name to Get-VHDDifferencingParent to be more consistent with existing VM cmdlet
* Added a check for the presence of Get-VHD; if available, will use that instead of the more complicated method
* Added more granular error-checking; not much can actually be done about errors, but they'll be reported more accurately

.LINK
Free Script: Find Orphaned Hyper-V VM Files
.EXAMPLE C:PS> .Get-VHDDifferencingParent -Path C:TestVHDsdiff1.vhdx Description ----------- Retrieves the parent disk of C:TestVHDsdiff1.vhdx, if any. #> param( [Parameter(Mandatory=$true, ValueFromPipeline=$true, ValueFromPipelineByPropertyName=$true)][String]$Path ) $AbsolutePath = "" $IdentifierSize = 8 $IdentifierBytes = New-Object Byte[] $IdentifierSize try # the easy way first { Get-Command -Name Get-VHD -ErrorAction Stop try { (Get-VHD -Path $Path -ErrorAction Stop).ParentPath return } catch { # probably means we have to try something harder, but let the next section worry about that } } catch { # just means we have to try something harder } try { try { $VHDStream = New-Object System.IO.FileStream($Path, [System.IO.FileMode]::Open, [System.IO.FileAccess]::Read, [System.IO.FileShare]::ReadWrite) -ErrorAction Stop } catch { throw ("Unable to open differencing disk {0} to determine its parent: {1}" -f $Path, $_) } try { $BytesRead = $VHDStream.Read($IdentifierBytes, 0, $IdentifierSize) } catch { throw ("Unable to read the VHD type identifier for {0}: {1}" -f $Path, $_) } if([System.Text.Encoding]::ASCII.GetString($IdentifierBytes) -eq "vhdxfile") { $1stRegionOffset = 196608; $1stRegionEntryCount = 0; $2ndRegionOffset = 262144; $2ndRegionEntryCount = 0 $SignatureSize = 4; $EntryCountSize = 8; $GUIDSize = 16; $EntryOffsetSize = 8; $EntryLengthSize = 4 $ShortEntrySize = 2; $MetadataOffsetSize = 4; $KeyValueCountSize = 2; $LocatorEntrySize = 12 $SignatureBytes = New-Object Byte[] $SignatureSize; $EntryCountBytes = New-Object Byte[] $EntryCountSize $GUIDBytes = New-Object Byte[] $GUIDSize; $EntryOffset = New-Object Byte[] $EntryOffsetSize $ShortEntryBytes = New-Object Byte[] $ShortEntrySize; $MetadataOffsetBytes = New-Object Byte[] $MetadataOffsetSize $KeyValueCountBytes = New-Object Byte[] $KeyValueCountSize; $LocatorEntryBytes = New-Object Byte[] $LocatorEntrySize $LocatorEntries = @() ($1stRegionOffset, $2ndRegionOffset) | foreach { $VHDStream.Position = $_ try { $BytesRead = $VHDStream.Read($SignatureBytes, 0, $SignatureSize) } catch { throw ("Unable to read signature from header region of {0}: {1}" -f $Path, $_) } if([System.Text.Encoding]::ASCII.GetString($SignatureBytes) -eq "regi") { $VHDStream.Position += 4 # jump over the checksum try { $BytesRead = $VHDStream.Read($EntryCountBytes, 0, $EntryCountSize) } catch { throw ("Unable to determine number of header entries in {0}: {1}" -f $Path, $_) } $RegionEntryCount = [System.BitConverter]::ToInt32($EntryCountBytes, 0) if($_ = $1stRegionOffset) { $1stRegionEntryCount = $RegionEntryCount } else { $2ndRegionEntryCount = $RegionEntryCount } } } if($1stRegionEntryCount -ge $2ndRegionEntryCount) { $EntryCount = $1stRegionEntryCount $StartingEntryOffset = $1stRegionOffset + 16 } else { $EntryCount = $2ndRegionEntryCount $StartingEntryOffset = $2ndRegionOffset + 16 } 1..$EntryCount | foreach { $VHDStream.Position = $StartingEntryOffset + (32 * ($_ - 1)) # an entry is 32 bytes long try { $BytesRead = $VHDStream.Read($GUIDBytes, 0, $GUIDSize) } catch { throw ("Unable to retrieve the GUID of a header entry in {0}, {1}" -f $Path, $_) } if([System.BitConverter]::ToString($GUIDBytes) -eq "06-A2-7C-8B-90-47-9A-4B-B8-FE-57-5F-05-0F-88-6E") # this is the GUID of a metadata region { try { $BytesRead = $VHDStream.Read($EntryOffset, 0, $EntryOffsetSize) } catch { throw("Unable to determine the location of a metadata region in {0}: {1}" -f $Path, $_) } $MetadataStart = $VHDStream.Position = [System.BitConverter]::ToInt64($EntryOffset, 0) try { $BytesRead = $VHDStream.Read($IdentifierBytes, 0, $IdentifierSize) } catch { throw("Unable to parse the identifier of an expected metadata region in {0}: {1}"-f $Path, $_) } if([System.Text.Encoding]::ASCII.GetString($IdentifierBytes) -eq "metadata") { $VHDStream.Position += 2 # jump over reserved field try { $BytesRead = $VHDStream.Read($ShortEntryBytes, 0, $ShortEntrySize) } catch { throw("Unable to retrieve the number of header short entries in {0}: {1}" -f $Path, $_) } $VHDStream.Position += 20 # jump over the rest of the header 1..([System.BitConverter]::ToUInt16($ShortEntryBytes, 0)) | foreach { try { $BytesRead = $VHDStream.Read($GUIDBytes, 0, $GUIDSize) } catch { throw ("Unable to retrieve the GUID of a short entry in {0}: {1}" -f $Path, $_) } $SavedStreamPosition = $VHDStream.Position switch([System.BitConverter]::ToString($GUIDBytes)) { ## We're only watching for a single item so an "if" could do this, but switch is future-proofing. ## Should be able to query 37-67-A1-CA-36-FA-43-4D-B3-B6-33-F0-AA-44-E7-6B for a "HasParent" value, but either the documentation is wrong or the implementation is broken as this field holds the same value for all disk types "2D-5F-D3-A8-0B-B3-4D-45-AB-F7-D3-D8-48-34-AB-0C" { # Parent Locator try { $BytesRead = $VHDStream.Read($MetadataOffsetBytes, 0, $MetadataOffsetSize) } catch { throw ("Unable to read the location of a metadata entry in {0}: {1}" -f $Path, $_) } if($BytesRead) { $ParentLocatorOffset = $MetadataStart + [System.BitConverter]::ToInt32($MetadataOffsetBytes, 0) $VHDStream.Position = $ParentLocatorOffset + 18 # jump over the GUID and reserved fields try { $BytesRead = $VHDStream.Read($KeyValueCountBytes, 0, $KeyValueCountSize) } catch { throw("Unable to read the number of key/value metadata sets in {0}: {1}" -f $Path, $_) } if($BytesRead) { 1..[System.BitConverter]::ToUInt16($KeyValueCountBytes, 0) | foreach { try { $BytesRead = $VHDStream.Read($LocatorEntryBytes, 0, $LocatorEntrySize) } catch { throw ("Unable to retrieve a key/value metadata set from {0}: {1}" -f $Path, $_) } if($BytesRead) { $KeyOffset = [System.BitConverter]::ToUInt32($LocatorEntryBytes, 0) $ValueOffset = [System.BitConverter]::ToUInt32($LocatorEntryBytes, 4) $KeyLength = [System.BitConverter]::ToUInt16($LocatorEntryBytes, 8) $ValueLength = [System.BitConverter]::ToUInt16($LocatorEntryBytes, 10) $LocatorEntries += [String]::Join(",", ($KeyOffset, $ValueOffset, $KeyLength, $ValueLength)) } } foreach($Locator in $LocatorEntries) { $KeyValueSet = $Locator.Split(",") $KeyPosition = $ParentLocatorOffset + $KeyValueSet[0] $ValuePosition = $ParentLocatorOffset + $KeyValueSet[1] $KeyBytes = New-Object Byte[] $KeyValueSet[2] $ValueBytes = New-Object Byte[] $KeyValueSet[3] $VHDStream.Position = $KeyPosition try { # NOTE: we don't actually do anything with the key, technically could move the pointer past it to the value $BytesRead = $VHDStream.Read($KeyBytes, 0, $KeyBytes.Length) } catch { throw ("Unable to retrieve the parent path key in the key/value set of {0}: {1}") } if($BytesRead) { if([System.Text.Encoding]::Unicode.GetString($KeyBytes) -eq "absolute_win32_path") { try { $BytesRead = $VHDStream.Read($ValueBytes, 0, $ValueBytes.Length) } catch { throw ("Unable to retrieve the parent path value in the key/value set of {0}: {1}") } if($BytesRead) { $AbsolutePath = [System.Text.Encoding]::Unicode.GetString($ValueBytes) break } } } } } } } } # move to the start of the next entry $VHDStream.Position = $SavedStreamPosition + 16 } } } } } elseif([System.Text.Encoding]::ASCII.GetString($IdentifierBytes) -eq "conectix") # this is a VHD file { $TypeSize = 4; $ChunkSize = 2 $TypeBytes = New-Object Byte[] $TypeSize -ErrorAction Stop; $ChunkBytes = New-Object Byte[] $ChunkSize -ErrorAction Stop $ReverseParentBytes = [Byte[]]@() $VHDStream.Position = 60 # this is where the disk type is stored try { $BytesRead = $VHDStream.Read($TypeBytes, 0, $TypeSize) } catch { throw ("Unable to determine the disk type of {0}: {1}" -f $Path, $_) } if($BytesRead) { [Array]::Reverse($TypeBytes) # surprise byte reversal! if([System.BitConverter]::ToUInt32($TypeBytes, 0) -eq 4) # is the differencing type { $VHDStream.Position = 576 # this is where the name of the parent is stored, if any 1..256 | foreach { # there are 512 bytes in the name, but they're also reversed. this is much more miserable to fix try { $BytesRead = $VHDStream.Read($ChunkBytes, 0, $ChunkSize) } catch { throw ("Unable to read the parent of {0}: {1}" -f $Path, $_) } if($BytesRead) { [Array]::Reverse($ChunkBytes) $ReverseParentBytes += $ChunkBytes } } $AbsolutePath = [System.Text.Encoding]::Unicode.GetString($ReverseParentBytes) -replace "(?<=.vhd).*" # remove leftover noise } } } else { throw ("{0} is not a valid VHD(X) file or has a damaged header" -f $Path) } } catch { <# PowerShell does not implement any form of "goto" or "using", so the purpose of this outer try block is to simulate goto functionality with an ending point that ensures that the file is always closed, if one was opened. otherwise, PS's normal erroring is sufficient #> throw($_) } finally { if($VHDStream) { $VHDStream.Close() } } $AbsolutePath

 

Threat Monitor
Share this post

Not a DOJO Member yet?

Join thousands of other IT pros and receive a weekly roundup email with the latest content & updates!

36 thoughts on "Free Script: Find Orphaned Hyper-V VM Files"

  • Fred De Smedt says:

    Is there an error in the script?

    You must provide a value expression on the right-hand side of the ‘-‘ operator.
    At C:Users************.***desktopGet-OrphanedVMFiles.ps1:407 char:38
    elseif($_.FullName.ToLower() – <<<< notin $DiskExclusions)
    CategoryInfo : ParserError: (:) [], ParseException
    FullyQualifiedErrorId : ExpectedValueExpression

    • Eric Siron says:

      First, make sure there isn’t a space between the – and notin. Copy/paste out of these online editors can be tricky.
      If the space is OK, it could be your PowerShell host. Some don’t recognize -notin as a valid operator. For those, you should be able to replace line 407 with:

      elseif ($DiskExclusions -notcontains $_.FullName.ToLower())

  • Fred De Smedt says:

    Is there an error in the script?

    You must provide a value expression on the right-hand side of the ‘-‘ operator.
    At C:Users************.***desktopGet-OrphanedVMFiles.ps1:407 char:38
    elseif($_.FullName.ToLower() – <<<< notin $DiskExclusions)
    CategoryInfo : ParserError: (:) [], ParseException
    FullyQualifiedErrorId : ExpectedValueExpression

  • Will says:

    This doesn’t seem to scan all CSVs. I’m running it on a machine with system center installed (windows 2012 r2) and with the flag -ComputerName clustername

    It scans one volume of the cluster only (e.g. c:clusterstoragevolume1 and not the other 20.

    Thanks,
    Will

  • Will says:

    This doesn’t seem to scan all CSVs. I’m running it on a machine with system center installed (windows 2012 r2) and with the flag -ComputerName clustername

    It scans one volume of the cluster only (e.g. c:clusterstoragevolume1 and not the other 20.

    Thanks,
    Will

  • Sven Buerger says:

    I have two hyper-v clusters which both configured almost the same. On one cluster the script works fine. On the other it lists a lot of vm files that are currently in use as orphaned. Any idea?

    Its the same for both cluster hosts.

    I see an error at the start of the script for both hosts:

    Get-RemoteData : An error occurred while retrieving host and VM data from HV3.saxsys.de
    A parameter is invalid. ‘C:UsersbadminDocumentsDisk 1 100.00 GB Bus 0 Lun 0 Target 5’ is not an existing virtual
    hard disk file.
    At D:toolsvmmGet-VMOrphanedFiles.ps1:1005 char:24
    $ExclusionsAndPaths = Get-RemoteData `
    ~~~~~~~~~~~~~~~~
    CategoryInfo : NotSpecified: (:) [Write-Error], WriteErrorException
    FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException,Get-RemoteData

    • Eric Siron says:

      The error that you get looks like it’s tripping on a pass-through disk? I never tested for that. It might be causing the remote data pull to return early without completely populating the exclusions list, which would cause false positives.
      If you can verify that you are using pass-through, I can investigate that angle.

  • Sven Buerger says:

    I have two hyper-v clusters which both configured almost the same. On one cluster the script works fine. On the other it lists a lot of vm files that are currently in use as orphaned. Any idea?

    Its the same for both cluster hosts.

    I see an error at the start of the script for both hosts:

    Get-RemoteData : An error occurred while retrieving host and VM data from HV3.saxsys.de
    A parameter is invalid. ‘C:UsersbadminDocumentsDisk 1 100.00 GB Bus 0 Lun 0 Target 5’ is not an existing virtual
    hard disk file.
    At D:toolsvmmGet-VMOrphanedFiles.ps1:1005 char:24
    $ExclusionsAndPaths = Get-RemoteData `
    ~~~~~~~~~~~~~~~~
    CategoryInfo : NotSpecified: (:) [Write-Error], WriteErrorException
    FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException,Get-RemoteData

    • Eric Siron says:

      The error that you get looks like it’s tripping on a pass-through disk? I never tested for that. It might be causing the remote data pull to return early without completely populating the exclusions list, which would cause false positives.
      If you can verify that you are using pass-through, I can investigate that angle.

  • Anopetia says:

    Hi,

    Thank you for your script!

    it works great for xml orphaned files.

    However it does not warn for orphaned vhd….

    If I remove a vm, and not the VHD, launching the scan will not warn that.

    Will be awesome to get this feature.

    Thank you again!

    • Eric Siron says:

      It detects orphaned VHD files. Something is going wrong for you. Please read all of the script’s notes and see if there is an obvious reason that applies to your case.

  • Anopetia says:

    Hi,

    Thank you for your script!

    it works great for xml orphaned files.

    However it does not warn for orphaned vhd….

    If I remove a vm, and not the VHD, launching the scan will not warn that.

    Will be awesome to get this feature.

    Thank you again!

  • Brian Clark says:

    This script is pretty amazing. I was looking through it and on line 257, I don’t know that i have ever seen that format “Hyper-VGet-VM”.
    Can you explain a little how that works? Is that explicitly stating to use the “Get-VM” from the Hyper-V module? Is there a benefit from doing it this way?

    I am running a SCVMM 2012 R2 environment, should this still work if I ran this script from the VMM machine? When I run this from there I get only the XML orphans and not the VHD orphans.

    Is there a “better” place to run this script?

    • Eric Siron says:

      Hi Brian,
      Thanks!
      The inclusion of the Hyper-V prefix is specifically because of VMM environments. VMM includes an alias for Get-VM that redirects to one of its own cmdlets. There’s nothing overtly wrong with that, although the standing best practice for any non-malicious script that shadows a native cmdlet is that it should at the very least implement all of the parameters and functionality of the shadowed cmdlet. VMM’s scripts do not take the care to do that. By using the Hyper-V prefix, I am forcing PowerShell to use Get-VM from the Hyper-V module and not any other.

      This script should be safe to run from almost anywhere, but you can try running it directly from a host node to see if the results are different. Since this is the second report that I’ve had of orphaned VHDs not being detected, I’ll take a look at it over the weekend and see if an update inadvertently broke something. It did work for me after my last round of modifications.

  • Brian Clark says:

    This script is pretty amazing. I was looking through it and on line 257, I don’t know that i have ever seen that format “Hyper-VGet-VM”.
    Can you explain a little how that works? Is that explicitly stating to use the “Get-VM” from the Hyper-V module? Is there a benefit from doing it this way?

    I am running a SCVMM 2012 R2 environment, should this still work if I ran this script from the VMM machine? When I run this from there I get only the XML orphans and not the VHD orphans.

    Is there a “better” place to run this script?

    • Eric Siron says:

      Hi Brian,
      Thanks!
      The inclusion of the Hyper-V prefix is specifically because of VMM environments. VMM includes an alias for Get-VM that redirects to one of its own cmdlets. There’s nothing overtly wrong with that, although the standing best practice for any non-malicious script that shadows a native cmdlet is that it should at the very least implement all of the parameters and functionality of the shadowed cmdlet. VMM’s scripts do not take the care to do that. By using the Hyper-V prefix, I am forcing PowerShell to use Get-VM from the Hyper-V module and not any other.

      This script should be safe to run from almost anywhere, but you can try running it directly from a host node to see if the results are different. Since this is the second report that I’ve had of orphaned VHDs not being detected, I’ll take a look at it over the weekend and see if an update inadvertently broke something. It did work for me after my last round of modifications.

  • Brian Clark says:

    That makes perfect sense, and was what I understood it to be. Thank you for the clarification.
    With regards to no orphaned VHD’s showing up, let me know if there is anything I can send you, or do to help you with this.

    • Eric Siron says:

      My testing is still locating orphaned VHD/X files. I have expanded the capabilities of the -Verbose switch. Please use that and scan the output for any indication as to why your virtual disk files are not being located.

  • Brian Clark says:

    That makes perfect sense, and was what I understood it to be. Thank you for the clarification.
    With regards to no orphaned VHD’s showing up, let me know if there is anything I can send you, or do to help you with this.

  • Brian Clark says:

    Thank you for this. I will take a look now and see what I have going on. Originally, I found that it was trying to scan our clusterstorage from an old machine that had recently died and wasn’t yet evicted from the cluster. I will see if this produces something different.

  • Matt Browne says:

    Hi Eric,
    Great script but its not showing orphaned/VHD(x)’s not in use in the c:clusterstorage location.
    I’ve tried with the various parameters: -IncludeDefaultPath -IncludeExistingVMPaths -Verbose
    But it does not show them in the results, if I move the VHD(x)’s out of that folder and onto the C drive it then shows them in the result?
    Any ideas?

    • Eric Siron says:

      Hm, it was working OK the last time I tested it.
      Can you run it with -Verbose and see if there are any clues there? You can e-mail the output to me if you don’t want it publicly visible.

      • Matt Browne says:

        Hi Eric,
        Verbose doesn’t give any clues that I can see.
        What’s your email and I will send you the output.
        Would really like to get this script running as we have a real need for it and could help us a lot.

        • Eric Siron says:

          There is information on how to reach me in the little about blurb at the end of all of my posts.

  • Matt Browne says:

    Hi Eric,
    Great script but its not showing orphaned/VHD(x)’s not in use in the c:clusterstorage location.
    I’ve tried with the various parameters: -IncludeDefaultPath -IncludeExistingVMPaths -Verbose
    But it does not show them in the results, if I move the VHD(x)’s out of that folder and onto the C drive it then shows them in the result?
    Any ideas?

  • Tyler Rosolowski says:

    I have the same problem with it listing a whole bunch of VHDX’s which are in use which it lists as orphaned on a 2012R2 cluster (8 nodes)

    • Eric Siron says:

      That’s why I didn’t allow this script to delete. I’m not confident that there’s ever going to be any way to be 100% certain, especially with VHDX files.
      Best guess would be to use the -Verbose switch to verify that the VMs that own the false positives are being detected. If they are, then axreen cap that part and sent it to me and I’ll see if there’s some way to improve the detection.

  • Jorge Limas says:

    Perfect! Works in my Cluster 2012 R2 and all CSVs!

  • Stephan van Helden says:

    Worked perfectly for me, though it didn’t recognize Shared VHD sets (.VHDS). It considered the associated AVHDX files as orphaned.

  • Ronald Rossi says:

    Could not get to run
    I must be doing something wrong, I know I have one leftover checkpoint
    I ran this command
    .Get-VMOrphanedFiles -Path D:
    as my hyper-v files are on the D drive
    NO OUTPUT??
    thank you
    Ron

Leave a comment or ask a question

Your email address will not be published. Required fields are marked *

Your email address will not be published. Required fields are marked *

Notify me of follow-up replies via email

Yes, I would like to receive new blog posts by email

What is the color of grass?

Please note: If you’re not already a member on the Dojo Forums you will create a new account and receive an activation email.