Create Platform layer
A platform layer includes the platform software and settings required for your layers and layered images to run flawlessly in your environment.
You can create platform layers for two purposes:
For creating and packaging layers: When you’ve imported the OS from a different hypervisor than the one where you create your layers, use this type of platform layer to create app layers.
For publishing layered images: Use this type of Platform layer in your image template so that the published layered images run flawlessly in your environment.
Platform layers for packaging layers or publishing layered images
Use the following table to determine whether you need a platform layer, and if you do, what software to install on it.
|Packaging layers||Publishing layered images|
|Platform layer required?||Only required if the OS image originated in a different hypervisor.||Required when publishing to a Provisioning Service and using a connection broker.|
|What to install||Hypervisor tools, when the OS originated on a different hypervisor.||Provisioning Service and connection broker software and settings. If publishing to a different hypervisor than the one where the OS originated, include the hypervisor tools.|
|Values to select||Select your hypervisor.||Select your hypervisor, Provisioning Service, and connection broker.|
|What you need||Installer for hypervisor||Installers for Provisioning Service and connection broker.|
Other software and settings to include in the platform layer
Besides the platform software specified above, you must include the following settings and software on the platform layer:
- Domain join
- NVIDIA Drivers, if applicable
- Citrix Receiver, for the single sign-on component
- Citrix Workspace Environment Management(WEM) agent
- Any software that impacts the logon stack, for example, Imprivata
- Citrix Provisioning on Hyper-V: Requires a Legacy Network Adapter to PXE boot
- Microsoft System Center Configuration Manager (SCCM) software, if you are using it
Process for creating a platform layer
The steps for creating a platform layer are to:
- Complete the Create platform Layer wizard in the management console.
- Connect to and log into the packaging machine.
- Install your Provisioning Service and connection broker software.
- If the appliance is installed on a different hypervisor than the one where you create layers or publish images, install the hypervisor tools on the platform layer.
- Verify the layer and shutdown the packaging machine.
- If the connector configuration selected in the wizard is set to use Offload Compositing, the layer is automatically finalized.
- If the connector configuration is not set to Offload Compositing, finalize the layer manually, as described in the detailed steps in this article.
When to update a platform layer
The platform layer is the highest priority layer and critical for the deployment of images, especially devices like your networks. Whenever you update the infrastructure software, you must add a version to the platform layer.
Whenever you update the OS layer, the image can have issues starting. To fix the issue, add a version to the platform layer using the new OS layer. Once the packaging machine has started, shut down the machine for finalization. The platform layer gathers the critical components from the new OS layer version, and updates them in the platform so that they match the OS version.
When creating a platform layer, the installers for your platform software must be available in a location that the packaging machine can access. For example, your Provisioning Service and connection broker software must be accessible. If the appliance is running on a different hypervisor, also include the hypervisor tools.
For detailed requirements, select the environment where you create layers or publishes images:
- Machine Creation for Azure
- Machine Creation for Nutanix AHV
- Machine Creation for vSphere
- Machine Creation for Citrix Hypervisor
- Citrix Provisioning
- Citrix Hypervisor
- MS Azure
- MS Hyper-V
- Nutanix AHV
- VMware Horizon View in vSphere
- VMware vSphere
- Network File Share (other platforms)
A word on optimizations
Since the platform layer is the highest priority layer you might think it would be the best layer to include optimizations. However, with Windows 10, any optimization that removes Windows Apps only works when run in the OS layer. Otherwise, the apps are integrated with the Windows Store and the store can only be modified in the OS layer. Recently Citrix has developed an excellent Optimizer (CTXOE). This tool is highly recommended for optimizations, as it can apply them and also usually reverse them, if needed.
You can speed up user logins by doing the following. After joining the domain login using a network user account, reboot the desktop, log on as administrator, and delete the profile created. When the first network user logs on, some system files are updated, then login performance usually improves.
Start a new platform layer
To create a platform layer, you:
- Prepare the layer using the Create Platform Layer wizard.
- Deploy a packaging machine in your environment.
- Install the tools and configure the settings for your environment.
- Finalize the layer.
Follow these steps:
Select Layers > Platform Layers and select Create Platform Layer in the Action bar. This opens the Create Platform Layer wizard.
In the Layer Details tab, enter a Layer Name and Version, both required values. Optionally, you can also enter other values.
In the Version Details tab:
- (Required) Enter a name for the New Version. This can be the software version or other identifying information.
- If you are adding a version to an existing layer, the Base Version field lets you choose which version to use as the starting point. The default choice is the latest version.
In the OS layer tab, select the OS layer you want to associate with this Platform layer.
In the Connector tab, choose a Connector Configuration for the platform where you are creating this layer. If the configuration you need isn’t listed, select New. Then, add a connector configuration, and select it.
In the Platform Types tab, select This platform will be used for publishing layered images, or This platform will be used for packaging. Then select the hypervisor, Provisioning Service, and connection broker where you are publishing the layered image. Note: If you are not using a Provisioning Service or connection broker, select None for each of those options.
In the Packaging Disk tab, enter a file name for the packaging disk. This disk is used for the packaging machine (the virtual machine) where you want to install the tools.
In the Icon Assignment tab, select an icon to assign to the layer. This icon represents the layer in the Layers module.
- To use an existing image, select an image in the image box.
- To import a new image, click Browse and select an image in PNG or JPG format.
- If you use a connector with Offload Compositing selected, and you choose one of the included icons, the packaging machine assigns an icon based on the layer’s contents.
In the Confirm and Complete tab, review the details of the App layer, enter a comment if necessary, and click Create Layer. Any comments you enter appear in the Information view of the Audit History.
Expand the tasks bar at the bottom of the UI, and double-click the Packaging Disk task to show the full task description.
Once the packaging disk has been created, the Tasks bar displays the location of the packaging disk in your environment.
Next, you can deploy the packaging machine for your layer.
Deploy a Packaging Machine
When you’ve completed the Create Layer wizard, the App Layering system creates a packaging machine (a virtual machine) in the location defined in the connector configuration. The packaging machine is a temporary virtual machine where you install the software to be included in the layer. It is deleted once the layer has been finalized.
Citrix Hypervisor, Hyper-V, Nutanix AHV, VMware vSphere
The appliance creates the packaging machine in the location defined in the connector configuration.
- Go to the App Layering management console, expand the Tasks bar at the bottom of the console, and open the Create Platform layer task to get the name of the packaging machine.
- Log into your hypervisor management console. (Citrix Hypervisor, Azure, Hyper-V, Nutanix, or VMware)
- From the hypervisor manager console, navigate to the packaging machine. If the packaging machine is not yet powered on, do so now.
Citrix Provisioning for Hyper-V: Configuring two network cards
When using dual network cards and running Citrix Provisioning for Hyper-V, you must configure the cards as follows on every new version of the Platform layer.
Once your provisioning software is installed and the required reboots have completed:
- Open an administrative command prompt on the packaging machine.
Run the command:
- Match the IP address of the streaming NIC (Legacy Network Adapter in Hyper-V) with the correct adapter name.
- Renew the DHCP lease on the streaming NIC.
- Again in an administrative command prompt run ipconfig /release adapter-name followed by ipconfig /renew adapter-name. This forces the App Layering drivers to select this adapter as the “primary NIC”.
- Run Shutdown for Finalize and finalize the layer as you normally would.
If you select Shutdown for Finalize, but then need to turn the machine back on for any reason, you must rerun the release and renew commands.
- Go to the App Layering management console, expand the Tasks bar at the bottom of the console. Open the Create App layer task details.
- Use the link in the task details to navigate to the packaging machine in Azure. The Custom deployment panel opens.
- Log into the Azure portal (https://portal.azure.com).
- Set the Azure parameters.
- Packaging Machine Name - must conform to Azure virtual machine name requirements.
- Size – virtual machine size.
- Virtual Network and Subnet - for deploying the packaging machine. IMPORTANT: Make sure the value for the Resource group location matches the Storage account location that you configured in the connector configuration. If these locations are not the same, the packaging machine fails to deploy. If your deployment does fail, you can paste the link into the browser again and start over.
- Once your packaging machine is powered on, you can install the applications you want to include in the layer.
Any other Hypervisor (via Network File Share)
Locate the Packaging Disk in the following directory on the Network File Share: \Unidesk\Packaging Disks
Copy the packaging disk to a separate location on your hypervisor. This allows space for the files generated by your hypervisor when you use the disk to create a new virtual machine.
IMPORTANT: Do not copy the disk to the Finalize folder until it is ready to finalize. A disk in the Finalize folder cannot be attached to the new virtual machine that you are going to create next.
Create a virtual machine using the packaging disk as the boot disk.
Power on the packaging machine.
Once your packaging machine is powered on, you can install your platform tools in the layer.
Install the platform tools on the packaging machine
Now it’s time to install the software for the platform where you are publishing your layered images. This includes the Provisioning Service, connection broker software that your layered images need to run in the target environment. Keep in mind that the state of the software before you finalize the layer is the state that the image uses.
- Remote log into the packaging machine. Be sure to log in using the User account you used to create the OS.
- Install the tools that your layered image must run in your environment. This includes any Provisioning Service, connection broker, and hypervisor tools you are using, along with any drivers, boot-level applications, and files needed.
- If the installation requires a system restart, restart it manually. The packaging machine does not restart automatically.
- Make sure the packaging machine is in the state you want it to be in when the image is booted:
- If the tools you install require any post-installation setup or registration, complete those steps now.
- Remove any settings, configurations, files, mapped drives, or applications that you do not want to include on the packaging machine.
Verify the layer and shut down the packaging machine
Once the tools are installed on the packaging machine, you can verify that the layer is ready to finalize. Any required post-installation processing needs to complete. For example, a reboot or a Microsoft
ngen process may need to complete.
To verify that outstanding processes are complete, run the Shutdown For Finalize tool. Look for the Shutdown For Finalize icon on the packaging machine’s desktop.
Shut down the packaging machine so you can finalize the layer
- If you are not logged into the packaging machine, remote login using the account set up during OS layer creation.
- Double-click the Shutdown For Finalize icon. A command line window displays messages detailing the layer verification process.
- If there is an outstanding operation, you are prompted to complete the process. For example, if a Microsoft
ngenoperation must complete, you can expedite the
ngenoperation, as detailed below.
- Once any pending operations are complete, double-click the Shutdown For Finalize icon again. This shuts down the packaging machine.
The Layer is now ready to finalize.
- If the connector configuration selected is set to Offload Compositing, the layer is automatically finalized.
- If you are not using Offload Compositing, finalize the layer manually.
Layer integrity messages you may see during the finalization process
The following layer integrity messages tell you what queued operations must be completed before the layer is ready to finalize:
A RunOnce script is outstanding - check and reboot the packaging machine.
A post-installation reboot is pending - check and reboot the packaging machine.
A Microsoft ngen operation is in progress in the background. - An MSI install operation is in progress - check the packaging machine.
A reboot is pending to update drivers on the boot disk - check and reboot the packaging machine.
A Microsoft ngen operation is needed.
Software Center Client is configured to run, but the SMSCFG.INI is still present.To learn more about deploying SCCM in a virtual environment, see the Microsoft TechNet article, Implementing SCCM in a XenDesktop VDI environment.
For details about what the layer integrity messages mean and how to debug them, see Debugging Layer Integrity Problems in Citrix App Layering 4.x and later.
You cannot bypass layer integrity messages by shutting down the machine, because the App Layering software stops and returns you to the packaging machine until the processes have completed.
If a Microsoft
ngen operation is in progress, you can try to expedite it, as described in the next section.
Expediting a Microsoft
Ngen operation is the Microsoft Native Image Generator. It is part of the .NET system, and basically recompiles .NET byte code into native images and constructs the registry entries to manage them. Windows decides when to run
ngen, based on what is being installed and what Windows detects in the configuration. Once the
ngen process is running, you must let it complete. An interrupted
ngen operation can leave you with non-functioning .NET assemblies or other problems in the .NET system.
You have the choice of waiting for the
ngen to complete in the background, or you can force the
ngen to the foreground. You can also check the status of the
ngen operation. However, when you check the queue status, you create foreground activity, which can cause the background processing to pause.
ngen to the foreground lets you view progress. Once the output completes, you can finalize the layer.
ngenoperation to the foreground.
Normally, ngen is a background operation and pauses if there is foreground activity. Bringing the task into the foreground can help the task to complete as quickly as possible.
Open a command prompt as Administrator.
Go to the Microsoft .NET Framework directory for the version currently in use:
ngencommand to run the queued items:
ngen update /force
ngentask comes to the foreground in the command prompt, and lists the assemblies being compiled.
Note: It is not a problem if you see several
Look in the Task Manager to see if an instance of MSCORSVW.EXE is running. If it is, you must allow it to complete, or rerun
ngen update /force. Do not reboot to stop the task. Allow it to complete.
Check the status of a
- Open a command prompt as Administrator.
Check status by running this command:
ngen queue status
When you receive the following status, the ngen is complete, and you can finalize the Layer.
The .NET Runtime Optimization Service is stopped.
Finalize the layer manually
Once the software has been installed and the packaging machine has been verified and shut down, you are ready to finalize the layer.
Citrix Hypervisor, Azure, Hyper-V, Nutanix AHV, VMware vSphere
Now that the layer has been verified and shut down, it is ready to finalize.
If you are using a connector with Offload Compositing selected, this finalization process is automated and you do not have to do these manual steps.
- Return to the management console.
- Select Layers > Platform layers, and the layer you prepared.
- Select Finalize in the Action bar. The Finalize wizard opens.
- Click Finalize to finish creating the layer.
- Monitor the task bar to verify that the action completes successfully.
Once the layer is verified, the packaging machine is removed to minimize the storage space used.
Any other hypervisor (via Network File Share)
Now that the Layer has been verified and shut down, it is ready to finalize.
Copy the Packaging Disk from the folder containing the packaging machine files to the Finalize folder on the Network File Share: \Unidesk\Finalize
Return to the management console.
Select Layers > Platform Layers.
Select Finalize in the Action bar.
Monitor the Task bar to verify that the action completes successfully and that the layer is deployable.
Create Platform layer
In this article
- Platform layers for packaging layers or publishing layered images
- Process for creating a platform layer
- When to update a platform layer
- A word on optimizations
- Start a new platform layer
- Deploy a Packaging Machine
- Install the platform tools on the packaging machine
- Verify the layer and shut down the packaging machine
- Shut down the packaging machine so you can finalize the layer
- Finalize the layer manually
- Any other hypervisor (via Network File Share)