I love Hyper-V. It’s awesome.  Mind you I also love vSphere. To be honest, I think I just love virtualisation. Clearly I still love Star Wars.

I thought the above quote was particularly fitting given the symptoms requiring Hyper-V permissions to be restored occur generally after somebody has just wiped the existing permissions out. All of them in fact.

This issue did get me curious as to what the standard Hyper-V permission requirements are, so that its possible to restore these permissions – particularly after someone has moved the Hyper-V files and the permissions have not been retained. I’ve read quite a few articles on the internet describing how to restore permissions to an individual VM for the purpose of successfully starting the VM, but they stop short at actually repairing the installation. Even after these methods are used to correct an individual VM’s permissions, there are still issues with creating snapshots, even with creating new VMs. I’ve created a script to repair the permissions, and attached the link at the bottom of the article.

The symptoms are generally first noticeable after the files are moved and an attempt is made to start a VM. You quite often see errors such as ‘an attempt to initialize VM saved state failed’, or ‘general access denied error.’ I do love general errors, generic errors, unexpected errors, and of course unspecified errors, they’re so informative. It reminds me of all of those poorly written applications over the years on Windows that have returned an error code of 0, and then matched that code to the Windows system error messages. It’s always fun trying to diagnose an issue when you see ‘General Error 0: The command completed successfully.’ Although on reflection, these applications may not have been poorly written – perhaps the application was expecting a function call to fail, and when that function call inexplicably succeeded, the application felt the need to throw an error message indicating its displeasure with the result. But I digress….

I decided to create a new Hyper-V installation on Windows Server 2012 R2, then create a new VM with a snapshot/checkpoint allowing me to observe and document the default permissions.

I used the CACLS built in command line tool to display the permissions. ICACLS works too, but the display out of CACLS is slightly better.

CACLS V:\ /T

To explain the information coming back from the tool, here’s an example:

BUILTIN\Administrators:(OI)(CI)(ID)F

This line indicates an Access Control Entry (ACE) for the BUILTIN\Administrators group. The OI indicates that the ACE will be inherited by child objects (in this case files). The CI indicates that the ACE will be inherited by child containers (in this case directories). The ID indicates that the ACE was inherited from a parent object. If we had observed IO, that would have indicate that the ACE should only apply to child objects, and not the current object where the ACE exists. Finally,  the F indicates the permission set of Full Control. As you’ll see below, some ACEs use a subset of the permissions, and those are listed as special access.

This first set of permissions is the base set without any VMs present. Some of the permissions to the Hyper-V folder have been inherited from the root directory V:\. As you’ll also see, there are some entries for the special Hyper-V security principals (the principals beginning with NT VIRTUAL MACHINE, similar to NT AUTHORITY). Additionally, most of the ACEs below have the ID flag, indicating they are inherited from the parent folder. The permissions are really only explicitly applied on the Hyper-V folder, and the Virtual Hard Disks folder (which in my case is nested under the base Hyper-V folder).

The Base Hyper-V Folder
v:\Hyper-V
CREATOR OWNER:(OI)(CI)(IO)F <- Explicit Permission (not inherited)
NT VIRTUAL MACHINE\Virtual Machines:(special access:)
- READ_CONTROL
- SYNCHRONIZE
- FILE_GENERIC_READ
- FILE_READ_DATA
- FILE_WRITE_DATA
- FILE_APPEND_DATA
- FILE_READ_EA
- FILE_READ_ATTRIBUTES
NT VIRTUAL MACHINE\Virtual Machines:(CI)(IO)(special access:)
- GENERIC_READ
- FILE_WRITE_DATA
- FILE_APPEND_DATA
NT AUTHORITY\SYSTEM:(OI)(CI)(ID)F <- Inherited from V:\
BUILTIN\Administrators:(OI)(CI)(ID)F <- Inherited from V:\

The Snapshots/Checkpoints Folder
v:\Hyper-V\Snapshots
NT AUTHORITY\SYSTEM:(ID)F
CREATOR OWNER:(OI)(CI)(IO)(ID)F
NT VIRTUAL MACHINE\Virtual Machines:(ID)(special access:)
- READ_CONTROL
- SYNCHRONIZE
- FILE_GENERIC_READ
- FILE_READ_DATA
- FILE_WRITE_DATA
- FILE_APPEND_DATA
- FILE_READ_EA
- FILE_READ_ATTRIBUTES
NT VIRTUAL MACHINE\Virtual Machines:(CI)(IO)(ID)(special access:)
- GENERIC_READ
- FILE_WRITE_DATA
- FILE_APPEND_DATA
NT AUTHORITY\SYSTEM:(OI)(CI)(IO)(ID)F
BUILTIN\Administrators:(OI)(CI)(ID)F

v:\Hyper-V\Virtual Hard Disks
BUILTIN\Administrators:(ID)F
CREATOR OWNER:(OI)(CI)(IO)(ID)F
NT VIRTUAL MACHINE\Virtual Machines:(ID)(special access:)
- READ_CONTROL
- SYNCHRONIZE
- FILE_GENERIC_READ
- FILE_READ_DATA
- FILE_WRITE_DATA
- FILE_APPEND_DATA
- FILE_READ_EA
- FILE_READ_ATTRIBUTES
NT VIRTUAL MACHINE\Virtual Machines:(CI)(IO)(ID)(special access:)
- GENERIC_READ
- FILE_WRITE_DATA
- FILE_APPEND_DATA
NT AUTHORITY\SYSTEM:(OI)(CI)(ID)F
BUILTIN\Administrators:(OI)(CI)(IO)(ID)F

v:\Hyper-V\Virtual Machines
CREATOR OWNER:(OI)(CI)(IO)F
NT VIRTUAL MACHINE\Virtual Machines:(special access:) <- Explicit Permission
- READ_CONTROL
- SYNCHRONIZE
- FILE_GENERIC_READ
- FILE_READ_DATA
- FILE_WRITE_DATA
- FILE_APPEND_DATA
- FILE_READ_EA
- FILE_READ_ATTRIBUTES
NT VIRTUAL MACHINE\Virtual Machines:(CI)(IO)(special access:) <- Explicit Permission
- GENERIC_READ
- FILE_WRITE_DATA
- FILE_APPEND_DATA
NT AUTHORITY\SYSTEM:(ID)F
CREATOR OWNER:(OI)(CI)(IO)(ID)F
NT VIRTUAL MACHINE\Virtual Machines:(ID)(special access:)
- READ_CONTROL
- SYNCHRONIZE
- FILE_GENERIC_READ
- FILE_READ_DATA
- FILE_WRITE_DATA
- FILE_APPEND_DATA
- FILE_READ_EA
- FILE_READ_ATTRIBUTES
NT VIRTUAL MACHINE\Virtual Machines:(CI)(IO)(ID)(special access:)
- GENERIC_READ
- FILE_WRITE_DATA
- FILE_APPEND_DATA
NT AUTHORITY\SYSTEM:(OI)(CI)(IO)(ID)F
BUILTIN\Administrators:(OI)(CI)(ID)F

The most interesting thing we’ve learnt here I believe is the NT VIRTUAL MACHINE\Virtual Machines group’s access to most of those folders. This is the group that needs access to the Virtual Hard Disks folder in order to create a new virtual hard disk, or to access the Virtual Machines folder in order to create new VMs.

This set of permissions below is for a single VM. As you’ll see here, the new VM’s ID is 53EE5757-C20E-41D6-9DE4-C3FE206D987B.  Hyper-V actually creates a security principal representing each individual VM. This security principal is not based on the name of the VM, but rather the VM’s internal identifier (e.g. NT VIRTUAL MACHINE\53EE5757-C20E-41D6-9DE4-C3FE206D987B). At present, you can not use the normal file permission graphical properties page to grant these principals access to a file, but you can observe the permissions.

Each VM stores a configuration XML file in the Virtual Machines folder
v:\Hyper-V\Virtual Machines\1A981CCB-6452-41E6-B771-2B0D8E69669F.xml
NT AUTHORITY\SYSTEM:(ID)F
BUILTIN\Administrators:(ID)F

A subfolder exists for each VM
v:\Hyper-V\Virtual Machines\1A981CCB-6452-41E6-B771-2B0D8E69669F
NT AUTHORITY\SYSTEM:(ID)F
CREATOR OWNER:(OI)(CI)(IO)(ID)F
NT VIRTUAL MACHINE\Virtual Machines:(ID)(special access:)
- READ_CONTROL
- SYNCHRONIZE
- FILE_GENERIC_READ
- FILE_READ_DATA
- FILE_WRITE_DATA
- FILE_APPEND_DATA
- FILE_READ_EA
- FILE_READ_ATTRIBUTES
NT VIRTUAL MACHINE\Virtual Machines:(CI)(IO)(ID)(special access:)
- GENERIC_READ
- FILE_WRITE_DATA
- FILE_APPEND_DATA
NT AUTHORITY\SYSTEM:(OI)(CI)(IO)(ID)F
BUILTIN\Administrators:(OI)(CI)(ID)F

The virtual hard disk for the VM - this file name bears no resemblance to the VM ID
v:\Hyper-V\Virtual Hard Disks\TestVM1 - Disk 0.vhdx
NT VIRTUAL MACHINE\1A981CCB-6452-41E6-B771-2B0D8E69669F:(special access:)
- READ_CONTROL
- SYNCHRONIZE
- FILE_GENERIC_READ
- FILE_GENERIC_WRITE
- FILE_READ_DATA
- FILE_WRITE_DATA
- FILE_APPEND_DATA
- FILE_READ_EA
- FILE_WRITE_EA
- FILE_READ_ATTRIBUTES
- FILE_WRITE_ATTRIBUTES
BUILTIN\Administrators:(ID)F
NT AUTHORITY\SYSTEM:(ID)F

The VM’s own security principal has explicit permissions to its virtual hard disk files. Interestingly enough though, the XML file itself is only accessible by NT AUTHORITY\SYSTEM, not the NT VIRTUAL MACHINES\Virtual Machines group. Mind you that file is only used by the Hyper-V Management service I presume to initially load the configuration.

This set of permissions below is for the additional files created for a snapshot/checkpoint. Each snapshot/checkpoint will have its own set of files. The ID of the snapshot/checkpoint is not the same as the ID for the VM. The linkage between them is achieved through the VM’s XML configuration file – it points to the IDs of the snapshots/checkpoints that exist, and they in turn point to the virtual hard disk for that snapshot/checkpoint.

The configuration file for this particular snapshot/checkpoint
v:\Hyper-V\Snapshots\53EE5757-C20E-41D6-9DE4-C3FE206D987B.xml
NT AUTHORITY\SYSTEM:(ID)F
BUILTIN\Administrators:(ID)F

The folder for this particular snapshot/checkpoint
v:\Hyper-V\Snapshots\53EE5757-C20E-41D6-9DE4-C3FE206D987B
NT AUTHORITY\SYSTEM:(ID)F
CREATOR OWNER:(OI)(CI)(IO)(ID)F
NT VIRTUAL MACHINE\Virtual Machines:(ID)(special access:)
- READ_CONTROL
- SYNCHRONIZE
- FILE_GENERIC_READ
- FILE_READ_DATA
- FILE_WRITE_DATA
- FILE_APPEND_DATA
- FILE_READ_EA
- FILE_READ_ATTRIBUTES
NT VIRTUAL MACHINE\Virtual Machines:(CI)(IO)(ID)(special access:)
- GENERIC_READ
- FILE_WRITE_DATA
- FILE_APPEND_DATA
NT AUTHORITY\SYSTEM:(OI)(CI)(IO)(ID)F
BUILTIN\Administrators:(OI)(CI)(ID)F

This file contains the difference between the snapshot/checkpoint disk and the original disk
v:\Hyper-V\Virtual Hard Disks\TestVM1 - Disk 0_97D1FE92-B60E-4ED3-B584-D24D62866D2B.avhdx
NT VIRTUAL MACHINE\1A981CCB-6452-41E6-B771-2B0D8E69669F:(special access:)
- READ_CONTROL
- SYNCHRONIZE
- FILE_GENERIC_READ
- FILE_GENERIC_WRITE
- FILE_READ_DATA
- FILE_WRITE_DATA
- FILE_APPEND_DATA
- FILE_READ_EA
- FILE_WRITE_EA
- FILE_READ_ATTRIBUTES
- FILE_WRITE_ATTRIBUTES
NT VIRTUAL MACHINE\1A981CCB-6452-41E6-B771-2B0D8E69669F:(ID)F
NT AUTHORITY\SYSTEM:(ID)F
BUILTIN\Administrators:(ID)F

So this is all very interesting I hear you say. Or perhaps I was saying that to myself. Either way, the primary purpose of this entry was to make it easier to restore these permissions in the event of IPL – inexplicable permission loss (I hope that’s not a thing). There are multiple methods to restore access (no doubt more than I have outlined below):

1. Export the current VMs. Remove the Hyper-V Role. Reboot. Install the Hyper-V Role. Import all of the VMs. It works, its clean, but export/imports are painfully slow and who wants to reinstall Hyper-V.
2. Use the ICACLS command line tool to restore individual permissions. This works very effectively, however laborious it might be.

The problem with simply putting a few ICACLS commands into a trusty batch file, is that you still need to determine which virtual hard disk belongs to each virtual machine. This is where a more complex script/application can come in handy, as they can read the XML file to determine the appropriate virtual hard disk and snapshot/checkpoint.

The code I have linked below is just a simple .VBS file (Visual Basic Script). It can be executed from the command line on Windows with the cscript executable. In an effort to keep it simple, I’ve simply created the script to generate a batch file with a list of all relevant ICACLS commands, which will correctly associate each virtual hard disk (snapshot/checkpoint or normal) with the appropriate security principal. You simply pass the full path of the Hyper-V folder to the script as a command line argument. It will then generate a batch file in the same folder with all of the appropriate ICACLS commands.

cscript RepairHyperV.Vbs V:\Hyper-V

Yes, I could have made the script super fancy, determining the appropriate Hyper-V path for itself etc, using an XML parser and applying the permissions automatically, but for the purpose of this exercise its just as easy to generate a batch file for the operator, demonstrating the appropriate ICACLS commands.

I’ve tested this on my Windows 2012 R2 Hyper-V server at home after stopping all of the VMs, and purposely removing all of the permissions. The batch file was created, I executed it, and all permissions were back to normal.

The script can be downloaded from here. You’ll need to change the extension back to .Vbs.

Hopefully this helps shed some light on the issue if you have this problem with Hyper-V.

~ Mike