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. This table also shows what software to install on the platform layer, if you need one.

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

  Note:

  The RSA key generated by Citrix WEM causes issues when using WEM on the deployed image. If the RSA key is present when finalizing the layer, a message appears stating you must delete the RSA key file, which begins with the following path: C:\ProgramData\Microsoft\Crypto\RSA\S-1-5-18\fb8cc9e38d3e60ab60c17cdfd6dd6d99_.

• Citrix uberAgent
• 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:

1. Create a platform layer in the management console.
2. Connect to and log in to the packaging machine.
3. Install your provisioning and connection broker software.
4. Is the appliance running on a different hypervisor than the one where you create layers and publish images? If yes, we recommend installing the hypervisor tools too.
5. Verify the layer and shut down the packaging machine.
   • If the connector configuration selected 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. It is critical for deploying images, especially for network devices. Whenever you update the infrastructure software, add a version to the platform layer.

When you update the OS layer, the image sometimes has startup issues. To fix the problem, add a version to the platform layer using the new OS layer. Once the packaging machine starts, 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.

Requirements

When creating a platform layer, the software installers must be available in a location the packaging machine can access. For example, your provisioning server 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 publish images:

• Machine Creation for Azure
• Machine Creation for Nutanix AHV
• Machine Creation for vSphere
• Machine Creation for XenServer
• Citrix Provisioning
• XenServer
• MS Azure
• MS Hyper-V
• Nutanix AHV
• VMware vSphere
• Network File Share (other platforms)

A word on optimizations

The platform layer is the highest priority layer. You might think it would be the best place to include optimizations. However, on Windows 10, optimizations that remove Windows Apps only work on the OS layer. The Windows Apps are integrated with the Windows Store, which can only be modified in the OS layer.

Citrix offers an excellent optimization utility called the Citrix Optimizer. We recommend using this utility, rather than the optimizer shipped with App Layering because the Citrix Optimizer can usually reverse the optimizations if needed.

To speed up user logins. Log in using a network user account, and reboot the desktop. Then, log in as an 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, follow these steps:

• Prepare the layer using Create Platform Layer.
• Deploy a packaging machine in your environment.
• Install the tools and configure the settings for your environment.
• Finalize the layer.

Follow these steps, starting in the Action bar:

1. Select Layers > Platform Layers. Then select Create Platform Layer.

2. In the Layer Details tab, enter a Layer Name and Version, both required values. Optionally, you can also enter other values.

3. In the Version Details tab:

   1. (Required) Enter a New Version name. For example, enter the software version or other identifying information.
   2. 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.

4. In the OS layer tab, select the OS layer you want to associate with this Platform layer.

5. In the Connector tab, choose a Connector Configuration for the platform where you are creating this layer.

6. 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 software, and connection broker where you are publishing the layered image. Note: If you are not using provisioning or a connection broker, select None for each of those options.

7. 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.

8. 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 the layer uses one of the supplied icons and a connector with Offload Compositing selected, the packaging machine assigns an icon based on the layer’s contents.

9. 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.

10. Select the Tasks page, and click the Packaging Disk task. Click the info icon 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

The App Layering system creates a packaging machine in the location defined in the connector configuration. The packaging machine is a temporary VM where you install the software for the layer. Once you finalize the layer, the packing machine is removed.

XenServer, Hyper-V, Nutanix AHV, VMware vSphere

The appliance creates the packaging machine in the location defined in the connector configuration.

1. Go to the App Layering management console, and select the Tasks page.
2. Open the Create Platform layer task to get the name of the packaging machine.
3. Log in to your hypervisor management console, for example: XenServer, Azure, Hyper-V, Nutanix, or VMware.
4. 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 been completed:

1. Open an administrative command prompt on the packaging machine.
2. Run the command: ipconfig /all
3. Match the IP address of the streaming NIC (Legacy Network Adapter in Hyper-V) with the correct adapter name.
4. Renew the DHCP lease on the streaming NIC.
5. Again in an administrative command prompt run ipconfig /release *adapter-name* followed by ipconfig /renew *adapter-name*. This command forces the App Layering drivers to select this adapter as the “primary NIC”.
6. Run Shutdown for Finalize and finalize the layer as you normally would.

Important:

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.

Azure

1. Go to the App Layering management console and select the Tasks page. Open the Create App layer task and click the Info icon to see details.
2. Use the link in the task details to navigate to the packaging machine in Azure. The Custom deployment panel opens.
3. Log in to the Azure portal (https://portal.azure.com).
4. 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.
5. 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)

1. Locate the Packaging Disk in the following directory on the Network File Share: \Unidesk\Packaging Disks

2. Copy the packaging disk to a separate location on your hypervisor. Putting the disk in another location allows space for the files generated by your hypervisor when you 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.

3. Create a virtual machine using the packaging disk as the boot disk.

4. 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

Next, install the software for the platform where you publish layered images. Platform tools include provisioning and connection broker software that layered images require in the target environment. Keep in mind, the state of the software when you finalize the layer is the state the image uses.

1. Log in remotely to the packaging machine. Be sure to log in using the user account you used to create the OS.
2. Install the tools that your layered images are configured to run. For example, include your provisioning, connection broker, and hypervisor tools. Don’t forget your drivers, boot-level applications, and any required files.
3. If the installation requires a system restart, restart it manually. The packaging machine does not restart automatically.
4. Make sure that 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.
5. (Optional) To customize the image deployed from the ELM before deployment to MCS, follow these steps:
   1. Upgrade your master tools in OS revision 2308 and beyond.

   2. Then, create the file: c:\windows\setup\scripts\kmsdir\Admin_Controlled_Shutdown.txt

      Note:

      File contents are not important.

   3. When the image is deployed from the ELM, the booted image remains running so that you can do your customizations. A reboot does not affect the machine’s state.
   4. After you’ve completed your customization, run the command: c:\windows\setup\scripts\kmsdir\CompleteDeployment.cmd. At this point, the machine shuts down and is finished with the deployment task. With this, you can deploy the machine to MCS.

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 be completed. For example, a reboot or a Microsoft ngen process might 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

1. If you are not logged into the packaging machine, remote login using the account set up during OS layer creation.
2. Double-click the Shutdown For Finalize icon. A command-line window displays messages detailing the layer verification process.
3. If there is an outstanding operation, you are prompted to complete the process. For example, if a Microsoft ngen operation must be completed, you can expedite the ngen operation, as detailed in the section, Layer integrity messages during the finalization process.
4. Once pending operations are done, double-click the Shutdown For Finalize icon again.

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 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. The App Layering software returns you to the packaging machine until the processes have been completed.

If a Microsoft ngen operation is in progress, you can try to expedite it, as described in the next section.

Expedite Microsoft Ngen.exe operations, if necessary

Once all software updates have been installed, you must allow Ngen.exe to essentially recompile .NET byte code into native images and construct the registry entries to manage them.

The Ngen.exe executable is the Microsoft Native Image Generator, which is part of the .NET system. Windows determines when to run Ngen.exe based on what software is being installed and what Windows detects in the configuration.

Important: When Ngen.exe is running, you must let it complete. An interrupted Ngen.exe operation can leave you with non-functioning .NET assemblies or other problems in the .NET system.

Normally, Ngen.exe is a background operation that pauses when there is a foreground activity. To expedite an Ngen.exe operation, bring the task into the foreground to complete it.

To bring the task into the foreground:

1. Open a command prompt as Administrator.

2. Go to the Microsoft.NET\Framework directory for the version currently in use:

   cd C:\Windows\Microsoft.NET\FrameworkNN\vX.X.XXXXX <!--NeedCopy-->

3. Enter the following Ngen.exe command to run all queued items. This command processes queued component installs before building assemblies.

   ngen eqi 3 <!--NeedCopy-->

   The Ngen.exe task moves to the foreground in the command prompt and lists the assemblies being compiled. It is OK if you see compilation messages.

   You can use the Task Manager to see if an instance of MSCORSVW.EXE is running. If it is, allow it to complete, or run ngen eqi 3.

   Caution: Do not reboot to stop the task. Allow the task to complete!

4. Ensure that all Ngen.exe processes have run to completion.
5. When complete, shut down the virtual machine using the Shutdown For Finalize shortcut available on your desktop.

Finalize the layer manually

Layer finalization is fastest when you use a connector on one of the tested hypervisors. See the next section for details.

You can also finalize a layer on other hypervisors by using the Network File Share. See the last section of this article.

XenServer, Azure, Hyper-V, Nutanix AHV, VMware vSphere

Now that the layer has been verified and shut down, it is ready to finalize.

Hyper-V:

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.

1. Return to the management console.
2. Select Layers > Platform layers, and the layer version on the Version Information tab you prepared.
3. Click Finalize to finish creating the layer.
4. Monitor the taskbar to verify that the action is completed 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.

1. Copy the Packaging Disk from the folder containing the packaging machine files to the Finalize folder on the Network File Share: \Unidesk\Finalize

2. Return to the management console.

3. Select Layers > Platform Layers.

4. Select Finalize in the Action bar.

5. Monitor the taskbar to verify that the action completes successfully and that the layer is deployable.