As Machine Creation Service (MCS) creates many machines from a single image, a number of steps must be performed to ensure that all machines created are unique and correctly licensed.
As part of the catalog creation process, an image preparation stage is run. This ensures that that all provisioned machines created have unique IP addresses and correctly announce themselves to the KMS server as unique instances.
How does MCS do Image preparation?
After the master image snapshot is selected, a copy is made, so that the catalog is isolated from the selected machine. A preparation virtual machine (VM) is created based on the original VM, but with the network disconnected, so it does not conflict with other machines and only attached to the newly copied disk.
A small “instruction” disk, which contains the steps of the image preparation to run, is attached to that VM. The preparation virtual machine is then started, the image preparation process begins and the virtual machine is shut down.
The default steps are:
- Enable DHCP
- Microsoft Windows KMS Rearm
- Microsoft Office KMS Rearm (if Microsoft Office is installed)
- Personal vDisk Inventory collection. (if a personal vDisk catalog is being created)
When the process is complete, the “instruction” disk is obtained from the hypervisor as it contains the results of the steps run.
Enable DHCP
To ensure that provisioned machines don’t cause IP address conflicts, DHCP is enabled on all network cards
Microsoft Windows Rearm
To ensure that window is correctly licensed, OS rearmed is invoked so it is correctly reported as a new instance to the KMS license server.
Microsoft Office Rearm
To ensure that any version of Microsoft Office (2010+) is registered correctly with their KMS server. Microsoft Office rearm is invoked, so correctly reporting as a new instance to the KMS license server.
Personal vDisk Inventory collection.
As a Personal vDisk catalog requires an inventory to be taken on all provisioned virtual machines before Personal vDisk can work. Rather than running it on an each VM created, it is run on the preparation virtual machine once. As the inventory can take a while to complete, it is run as two stages. The first stage to check that the VDA is installed on the master image and then the full PVD inventory is taken. The second stage runs without a timeout as it is known the tools are installed. Depending on the size of the OS disk, this may take a while.
Common Issues
There are a number of reason that the Image Preparation stage can fail. This section covers how and why it can fail, and how to solve some of the common issues.
Enable DHCP
The failure cases seen are by network cards that do not support Static IP address. For example, before it was fixed, Dell SonicWall network cards. The operation failed as a SonicWall card is a firewall network card, so setting the card to DHCP makes no sense as that only supports DHCP. This was fixed in XenDesktop 7.6. However, if it is seen on other types of network cards it should be reported to Citrix via the forums or your support contact so that we can address the issue in a future version.
However if this issue is seen with other cards, it can be worked around via the following PowerShell on the XenApp/XenDesktop Delivery Controller:
Set-ProvServiceConfigurationData -Name ImageManagementPrep_Excluded_Steps -Value EnableDHCP
Note that this setting is applied to the XenApp/XenDesktop site, so it will affect all new catalogs and Image Updates performed to existing catalogs.
Microsoft Office rearm
As MCS only supports KMS version of Office, there are a number of KMS rearm failures that can happen during the Office rearm stage. The main failures reported are:
- Some Microsoft Office runtimes for example Access Runtime can cause the office rearm to be invoke causing it to fail
- A KMS version of Microsoft Office is not installed.
- Rearm count exceeded
If the error is a false positive, it can be worked around by running the following PowerShell on the Delivery Controller. This issue is currently worked on, but current versions of XenApp/XenDesktop can experience this failure
Set-ProvServiceConfigurationData -Name ImageManagementPrep_Excluded_Steps -Value OfficeRearm
Note that this setting is applied to the XenApp/XenDesktop site, so it will affect all new catalogs and Image Updates performed to existing catalogs.
Windows rearm
As MCS only supports KMS versions of Microsoft Windows, there are a number of KMS failures can happen during the Windows rearm stage. The main failures cases are:
- The version of Windows installed is not activated using KMS for example it is using a Multiple Activation Key (MAK).
- Rearm count exceeded.
If you happy that that version of Windows is correctly licensed, you can turn off OS rearm by executing the following PowerShell on the Delivery Controller:
Set-ProvServiceConfigurationData -Name ImageManagementPrep_Excluded_Steps -Value OsRearm
Note this setting is applied to the XenApp/XenDesktop site, so will affect all new catalogs and Image Updates performed to existing catalogs.
Complete failure
As the preparation machine is not connected to the network by design, this means that sometimes the image preparation stage can only report a complete failure.
While this is rare this can happen. The main reasons for failure are:
Virtual Desktop Agent (VDA) is not installed, or VDA version 5.x is installed
If the VDA 7.x is not installed on the master image, then image preparation will timeout after 20 minutes and report the above error. This is because there is no software installed on the master image to run the image preparation stage and report success or failure. The solution to this is to make sure the VDA is installed and is of a least of version 7 on the snapshot selected as the master image
DISKPART SAN Policy
The whole image preparation stage can fail due to the DISKPART SAN policy set on the master image. If it not set to bring online the image preparation instruction disk, after 20 minutes the machine will be shut down and Image preparation will report failure
To check this on the Master Image run the follow commands
C:\> Diskpart.exe
DISKPART> San This will return the current policy, if it is not “Online All” it can be change by running
DISKPART> San policy=OnlineAllShut the master image down, create a new snapshot of that machine and then use that as the base MCS image.
If the issue is not covered by the notes above.
If Image prep is failing and there is no clear reason for failure, image preparation can be bypassed from the MCS create catalog process, however this may cause issues with KMS licensing and networking (DHCP) on your site
Set-ProvServiceConfigurationData -Name ImageManagementPrep_DoImagePreparation -Value $false
Whenever possible, logs can be collected allowing us to work out issue and help with a more permanent solutions so no work arounds are required in the future. Either report the issue to Citrix via the forums or via your support contact
On the master image create the following registry key with the value of 1 (as a “DWORD (32-bit) value”)
HKLM\Software\Citrix\MachineIdentityServiceAgent\LOGGING
Shutdown the master image and create a new snapshot, on the DDC start PowerShell with the Citrix PowerShell snap-ins loaded and run
Set-ProvServiceConfigurationData -Name ImageManagementPrep_NoAutoShutdown -Value $True
Create a new catalog based on that snapshot
When the preparation VM is created on the hypervisor, log in and extract from the root of C:\
- Image-prep.log
- PvsVmAgentLog.txt
Shut the machine down, at which point it will then report failure
Run from following PowerShell command to re-enable auto shutdown of the Image Preparation machines
Remove-ProvServiceConfigurationData -Name ImageManagementPrep_NoAutoShutdown
