This post describes the actions taken to create an OS Layer in Citrix App Layering 4.x running on Hyper-V with Citrix PVS. You are also shown how to add new versions to the OS Layer for the purpose of patching, upgrading and making changes to the OS Layer image. Here you will see how the Platform Layer and Image Template plays a key part in packaging and deploying complete system images.
To create an OS Layer, you must have the App Layering ELM (Enterprise Layer Manager) appliance installed. Read http://www.jgspiers.com/installing-configuring-unidesk-4/
This guide deploys an OS Layer using App Layering on Hyper-V. For VMware instructions, see Carl Stalhood’s App Layering OS Layer and Platform Layer post.
- When adding a version to your Windows 10 layer to perform an upgrade, change the Max Layer Size from 30GB to 60GB.
- Windows 10 sometimes creates a Recovery Volume as a new partition on the same disk as the OS Layer version. This volume needs to be removed before the finalize the OS Layer version. This is because the Recovery Volume can cause boot failures.
When adding a version to your OS Layer you must package the layer on the same Hypervisor from which you imported the OS during layer creation. This isn’t the same as packaging Application Layers. Application Layers can be packaged on any supported hypervisor of your choice so long as you are using a Platform Layer for packaging with the correct hypervisor tools installed to support the application installation.
Other points to note when creating an OS Layer:
- .NET Framework 4.5 must be installed on any layered image when Elastic Layers are used on top of that layer.
- You should install .NET 3.5, 4.6 and any Visual C++ Redistributable Packages inside of the OS Layer. This will prevent the possibility of .NET or Visual C++ conflicts coming from multiple layers as many applications depend on these components and will each install them in their own Application Layers if the components are not found in the OS Layer. Keeping these components in the OS Layer will also help with patching.
- Do not use periods in the image file name when using PVS.
- You must disable IPv6 in the OS Layer when using PVS. Do not disable in the Platform Layer. Also, disabling IPv6 by unchecking the option within network adapters isn’t good enough. You must actually disable IPv6 using the Registry in the OS Layer to ensure new network interfaces used with Target Devices automatically have IPv6 disabled on them. I show you how to do this further down the post. If you created a Platform Layer before disabling IPv6 in the OS Layer, you must create a new Platform Layer after IPv6 is disabled in the OS Layer.
- Do not disable 8.3 name creation or NTFS last access time stamps. These are used by App Layering.
- UEFI is not supported for the OS Layer. This is because the OS Layer must be partitioned with MBR rather than with GPT (not supported). In our case, we are using PVS with Hyper-V. That means you cannot build the OS Layer using a Generation 2 Virtual Machine. You must use a Generation 1 machine. To boot in to PVS, you must then use the Legacy NIC to boot in to a Gold Image regardless if the bootstrap is delivered by BDM or TFTP. Your Target Devices should also contain a Synthetic NIC to take over streaming once the Target Device has booted. See http://www.jgspiers.com/citrix-pvs-synthetic-nic-streaming-with-hyper-v/ for more information.
- When using Hyper-V to create the OS Layer, use a machine with one Legacy NIC when building the OS Layer. I have found that not doing this results in a BSOD when it comes to booting to the published vDisk.
- Make sure your PVS Target Device hardware settings match those set in the OS and Platform Layer hardware settings. If the number of CPUs in your Target Device VMs are larger than what was used during OS Layer creation for example, you may get a reboot required message when the published image is booted.
- If using App-V 5.1 with Unidesk 4.0.8, you may encounter BSODs on the VDA. There seems to be a conflict between the unifltr.sys and AppvStrm.sys mini-filter drivers. Upgrade to 4.1 or above which contains the required hotfixes.
- You cannot install the OS Layer on any drive other than C:\.
To begin using Hyper-V create a Virtual Machine as Generation 1.
Ensure the machine is configured with a Legacy Network Adapter. You should not configure any other network adapters on the machine as your Gold Image should only have one network adapter. Install a supported Operating System. You should also fully patch the OS with Windows Updates.
As we are using PVS it is important that you disable IPv6 by opening RegEdit and navigating to HKLM\System\CurrentControlSet\Services\TCPIP6\Parameters. Create a REG_DWORD object with a name of DisabledComponents and a value of 0xFF.
Another requirement is to disable Automatic Updates which can be done via gpedit.msc on the local machine using Local Group Policy Editor.
Right-click citrix_app_layering_os_machine_tools_4.6.0 and choose to Run as administrator.
Click Install. The containing files are extracted to C:\Windows\Setup\Scripts\.
Navigate to the extracted location and run setup_x64.
Since we are using PVS there is no need to use an answer file. Click Next.
During installation of the Image Preparation Utility, a Startup Script should be created which is configured to run kmssetup.cmd. You can view the Startup Script by running gpedit.msc locally.
Note: To be safe, right-click C:\Windows\Setup\Scripts\kmsdir\kmssetup.cmd and click Properties. Make sure the file is not blocked. If it is it will not run.
From an elevated Command Prompt, run C:\Windows\Setup\Scripts\SetKMSVersion.hta”.
Click Save Script. This creates a runipkato.cmd script within C:\Windows\Setup\scripts\kmsdir. The ELM runs this script when publishing an image.
Note: If you are using MCS to distribute your App Layering image, disable the OS Rearm MCS step by running PowerShell command Set-ProvServiceConfigurationData -Name ImageManagementPrep_Excluded_Steps -Value OsRearm from a Delivery Controller. Note that OsRearm is case-sensitive.
Note: To remove the excluded step, run Remove-ProvServiceConfigurationData -Name ImageManagementPrep_Excluded_Steps.
At this stage you should be ready to convert the Operating System you have just prepared in to an OS Layer. Copy the VHD file to the ELM Share that is used by the ELM appliance.
Importing the OS Layer in to ELM:
Log on to the App Layering Management Console and navigate to Layers -> OS Layers -> Create OS Layer.
Specify an appropriate name, description, version and maximum layer size. The layer disk will be thin provisioned.
The connector that points to your ELM share should already be configured. If not, you’ll need to create one. Select the ELM Share connector and continue. For information on creating an ELM Share see http://www.jgspiers.com/installing-configuring-unidesk-4/#Create-Share
Expand the ELM share and select the VHDX file to be used for your gold image. Click Choose.
Now click the down arrow.
Specify an icon for the OS Layer. You can also upload your own icons.
Review the settings and click Create Layer.
A Creating OS Layer task begins which you can view the details of. This task imports the VHDX you specified in to the ELM Appliances Layering Service storage repository.
The next step involved is to create a Platform Layer. The Platform Layer normally consists of the hypervisor tools, VDA tools and PVS Target Device software. The Platform Layer is also where you would join the image to the domain and perform any Operating System optimisations. Within the Management Console, navigate to Layers -> Platform Layers -> Create Platform Layer.
Specify an appropriate name, description, version and maximum layer size.
Choose the OS Layer you just imported. The Platform Layer is created based off the OS Layer.
Choose a Hyper-V Connector. You will have to create one if you have not done so already. Prior to App Layering 4.6, you would have had to specify the ELM Share which then resulted in you having two separate disks which require manual attaching to a Packaging VM, which you also had to manually create. Now with a native Hyper-V connector, the Packaging Machine is automatically provisioned.
The Packaging VM is what you use to boot in to the Platform Layer and install the necessary tools. In previous versions this VM was called an Installation Machine.
For steps on creating a Hyper-V connector see http://www.jgspiers.com/installing-configuring-unidesk-4/#HyperV-Connector
There are two types of Platform Layers you can create. One for packaging layers and one for publishing layers. Since we are publishing a layer, we can select the second radio box. Specify Microsoft Hyper-V for Hypervisor, Citrix PVS for Provisioning Service and Citrix XenDesktop or XenApp for Connection Broker.
Click the down arrow. If you are publishing to the ELM Share, you are given the option to specify the disk format (VHD/VMDK).
Pick an icon or upload one yourself.
Click on Create Layer.
After a few minutes you should be informed that the Packaging Machine has been created. At this stage connect to your SCVMM console or Hyper-V Manager.
Connect to newly created virtual machine.
Install Hyper-V Integration Services.
Click Yes to restart. It is safe to restart as many times as you like. Once restarted join the machine to your domain.
To install the Target Device software, launch the PVS media and click Target Device Installation.
Once the install is complete click Finish.
Reboot the machine again.To install the VDA software launch your XenApp & XenDesktop media. Select Create a Master Image. Uncheck Citrix Receiver. Receiver should be installed as an Application Layer.
Unselect Optimize Performance. Uncheck/check any other components you need.
Click Close to restart
Eventually the VDA installation will complete. Click Finish. The machine will restart for the last time.
In your Platform Layer launch Command Prompt as an administrator and run command set devmgr_show_nonpresent_devices=1 followed by devmgmt.msc.
Click View -> Show hidden devices.
Expand Software devices, right-click Microsoft IPv4 IPv6 Transition Adapter Bus and click Uninstall.
You should now make all necessary optimizations to the gold image by disabling unneeded scheduled tasks and services etc. See http://www.jgspiers.com/citrix-tips-tricks-tweaks-suggestions/ for pointers and if using Windows Server 2016 see http://www.jgspiers.com/windows-server-2016-optimisation-script/. Citrix and VMware have optimization tools that allow you to hand pick common optimizations for VDI and SBC machines.
Now that all the required tools are installed and optimisations are completed within the Platform Layer we can finalize the disk. To do so, you must run Shutdown For Finalize which is located on the Packaging Machine’s desktop.
The Shutdown For Finalize tool runs a quick integrity check to ensure no pending operations are queued. In this case as you can see, an NGen operation is still in progress so the layer finalization does not proceed.
Note: I have an App Layering preparation script which runs NGEN, cleans up many temporary folders, Event Viewer and so on. See http://www.jgspiers.com/citrix-app-layering-preparation-script/
To check the progress of NGen, you can monitor the ngen.exe service. Once it dissapears you will be able to finalize the image.
Alternatively you can run ngen update /force to force a regeneration of native images.
Once the compiles are complete, you can finalize the image. The Packaging Machine will be shut down.
Return to the App Layering Management Console, select the Platform Layer and click Finalize.
The disks will be imported into local storage on the ELM Appliance.
The disk contents are being converted into a layer.
The Platform Layer has been successfully created.
Finally to publish the OS Layer out to PVS we need to create an Image Template. Image Template’s bundle the OS Layer, Platform Layer and any number of Application Layer’s together. It is when you are publishing an Image Template that all these different layers are merged together to create a desktop for end user consumption. In the Management Console, navigate to Images -> Create Template.
Note: At any time you can edit an Image Template and assign/remove Application Layers and so on.
Enter an appropriate name and description. Select an icon or upload your own.
Select the only available OS Layer recently created.
No Application Layer’s are available at the moment so we can continue on. When we have an Application Layer available we can come back and edit this Image Template to include the layer.
Rather than have ELM publish the image to the ELM Share, instead we want the ELM Appliance to publish the image out to PVS. Click on New.
Note: You could publish the image to the ELM Share and manually import in to PVS, however that is a more manual approach.
Underneath Type, there are several connectors available to create such as MCS, PVS, Nutanix, XenServer. Click on Citrix PVS.
Now click New.
A new popup appears. Make sure your popup blocker is not interfering. The popup webpage directs you to a PVS Connector creation screen. Underneath Console use the dropdown to select your PVS server. Any PVS server that you have successfully installed the App Layering Agent on and registered with ELM will appear here.
Note: A quick tip – Install App Layering Agent’s on “master” PVS servers, ones that you normally nominate to perform all changes on. This server must also have the PVS Console installed.
Enter service account credentials that has Farm Administrator permissions on PVS. Click Check Credentials and wait for the The credentials have been verified message.
Now that credentials have been provided the PVS farm is queried for the Site Name, Store Name(s) and so on. Select the appropriate details as below. In terms of Write Cache and License Mode etc. App Layering will import the published image in to PVS and automatically configure these settings on the vDisk for you. Click Test.
Note: You could publish all images to a staging store for example, then move them to their appropriate stores afterwards. You can also create multiple connectors, so one for VDI machines and one for Session Host machines with different Write Cache sizes.
Enter a Configuration Name (at the top of page) and then click Save.
You should receive a These settings were successfully saved message.
Returning back to the App Layering Management Console you’ll see your newly created PVS Connector. Highlight it, then click the down arrow.
Choose the only available Platform Layer. This Platform Layer is tied to your OS Layer.
Specify an appropriate name and layered disk size. The disk is thin provisioned. If you are using Elastic Layering, choose Application Layers Only. This installs a App Layering Service inside the image and prepares the image for Elastic Layering capabilities.
Click Create Template.
The new Image Template shows underneath as publishable. You now have to publish the image out to PVS. Click Publish Layered Image.
Note: You can highlight and publish multiple Image Templates at once. App Layering will publish up to 4 concurrently.
Click Publish Layered Image.
A new task begins for publishing the image.
At this stage the image is transferring to the PVS store.
As you can see on the PVS Store a .tmp file is placed in the directory which will later become the published vDisk.
Image is registering with PVS.
The published job is complete and we should now have the image in PVS.
Within the PVS Store we can now see the vDisk and relevant .lok and .pvp files.
The vDisk also appears in the PVS console, configured with Cache in Device RAM with Overflow to Hard Disk. Create some Target Device VM’s and boot in to the image to confirm everything is in place.
The PVS Target Device software and VDA is present. The Hyper-V tools are also installed but just do not show in Add/Remove Programs.
When the time comes, you’ll eventually need to add versions to the OS Layer image to make changes. The majority of times you’ll only need to perform Windows Update patching on the OS Layer image as generally most applications will be in separate Application Layer’s which come with their own versions. When you create an OS Layer version, the existing latest OS Layer is copied and marked as read/write. You then use a Packaging Machine to boot in to the read/write layer and make the required changes to the image.
To create an OS Layer version navigate to Layers -> OS Layers -> select the OS Layer and -> Add Version.
Enter a new version number, description and max layer size. The Max Layer Size value should be large enough to host the OS Layer and any updates you are performing.
Choose a Hyper-V Connector. You may have to create one. Prior to App Layering 4.6, you would have had to specify the ELM Share which then resulted in you having two separate disks which require manual attaching to a Packaging VM, which you also had to manually create. Now with a native Hyper-V connector, the Packaging Machine is automatically provisioned.
The Packaging VM is what you use to boot in to the OS Layer version so you can perform your changes. In previous versions this VM was called an Installation Machine.
Specify a packaging disk filename. You’ll likely keep the defaults. If you were publishing the new OS Layer version to the ELM Share, you would also be asked for a disk format (VHD/VMDK). Click the down arrow.
Click Create Version.
The Packaging Machine has been created. At this stage open your SCVMM or Hyper-V Manager console.
Connect to the Packaging Machine VM.
During the Platform Layer optimizations Windows Update was disabled, general VDI/SBC requirement. You must temporarily start the Windows Update service.
Note: In newer versions of App Layering, when creating OS Layer versions the Windows Update service is automatically disabled.
Also set Automatic Updates to Enabled. Make sure to turn these off again after patching.
Search for and install patches.
Reboot the Packaging VM to finish installing updates.
When the machine is back up log on and run the Shutdown For Finalize tool.
Return to the Management Console, select the OS Layer and click Finalize.
Click Finalize to finalize version 2 of the OS Layer.
At this stage the new OS Layer version will be imported in to the ELM local storage.
The new layer version is ready to be used.
To publish the new layer version out to PVS you need to edit your existing Image Template to include the new OS Layer version. Navigate to Images -> click on the relevant Image Template and select Edit Template.
Navigate to the OS Layer tab and then expand the OS Layer, selecting Version 2.
Click Save Template Changes.
Now go through the Publish Layered Image wizard to publish the disk to PVS, attatch to Target Device VM’s and power them on.
Confirm the new OS Layer version is in effect by looking for the updates you just installed.
That’s it. You have just successfully updated an OS Layer!
To create Application Layers and Elastic Layers, see http://www.jgspiers.com/application-layers-elastic-layering-unidesk-4/