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-server\VMs. 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
The 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:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
#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:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 |
<# .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 https://www.altaro.com/hyper-v/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 \\smb3share\vms Description ----------- Checks for VM files on the \\smb3share\vms 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[]]$ComputerName=@(,$env:COMPUTERNAME), [Alias("VirtualMachinePath")] [Parameter(ValueFromPipeline=$true, ValueFromPipelinebyPropertyName=$true,ParameterSetName='SpecifiedPath')] [String[]]$Path=@(), [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)\Microsoft\Windows\Hyper-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-V\Get-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)\Microsoft\Windows\Hyper-V\Resource 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'='root\MSCluster';'ErrorAction'='Stop' } if($Credential) { $GwmiNodeParameters.Add('Credential',$Credential) } $Nodes = (Get-WmiObject @GwmiNodeParameters).Name $GwmiClusterDomainParameters = @{'ComputerName'=$VMHost;'Class'='Win32_ComputerSystem';'Namespace'='root\CIMV2';'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.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 |
<# .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 https://www.altaro.com/hyper-v/free-script-find-orphaned-hyper-v-vm-files .EXAMPLE C:\PS> .\Get-VHDDifferencingParent -Path C:\TestVHDs\diff1.vhdx Description ----------- Retrieves the parent disk of C:\TestVHDs\diff1.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 |
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
It’s not yet updated for 2016/2019 so that might be it.
Worked perfectly for me, though it didn’t recognize Shared VHD sets (.VHDS). It considered the associated AVHDX files as orphaned.
I’ll mark this for a feature update.
Perfect! Works in my Cluster 2012 R2 and all CSVs!
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)
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.
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?
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?
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.
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.
There is information on how to reach me in the little about blurb at the end of all of my posts.
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.
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.
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.
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.
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?
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.
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-V\Get-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?
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.
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!
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!
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.
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
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.
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:\Users\badmin\Documents\Disk 1 100.00 GB Bus 0 Lun 0 Target 5’ is not an existing virtual
hard disk file.
At D:\tools\vmm\Get-VMOrphanedFiles.ps1:1005 char:24
+ $ExclusionsAndPaths = Get-RemoteData `
+ ~~~~~~~~~~~~~~~~
+ CategoryInfo : NotSpecified: (:) [Write-Error], WriteErrorException
+ FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException,Get-RemoteData
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.
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
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:\clusterstorage\volume1 and not the other 20.
Thanks,
Will
1.1 update is published. Try that and let me know.
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
Is there an error in the script?
You must provide a value expression on the right-hand side of the ‘-‘ operator.
At C:\Users\************.***\desktop\Get-OrphanedVMFiles.ps1:407 char:38
+ elseif($_.FullName.ToLower() – <<<< notin $DiskExclusions)
+ CategoryInfo : ParserError: (:) [], ParseException
+ FullyQualifiedErrorId : ExpectedValueExpression
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())