Create or clone an app layer

An app layer is a virtual disk that includes one or more applications. Typically, an app layer includes one application. If you include more than one application in a layer, limit it to things that you normally update at the same time.

Create an app layer from scratch

This section walks you through app layer creation, including:

• Requirements and considerations
• Start a new app layer
• Deploy the packaging machine
• Install the application
• Layer integrity messages you might see
• Verify the layer and shut down the machine
• Expedite Microsoft Ngen.exe operations, if necessary
• Finalize the layer

Requirements and considerations

An app layer includes one or more applications and related settings. Always install MS Office in an app layer, and never in the OS layer.

• Anti virus applications: Always put your antivirus application in an App layer using the instructions provided here. Be strategic with your virus definition file updates. Also, be aware of file marking features, for example, Symantec’s Virtual Image Exception Tool. Consider host-based scanning engines, and keep in mind the delay at user logon. Be sure to scan the published layered image, not the layer. Scanning is only done on user access on Citrix Virtual Apps and Citrix Virtual Desktops.
• MS Office: Use this recipe to install Office. For VDI deployments of Office 2010 and later, consider KMS a requirement. For Office 2007 and earlier, consider Volume licensing a requirement. Using other licensing structures is not as convenient, because they require each license to be activated on each desktop. To persist user settings and data, enable Office 365 User layer stores.OST and streaming files. The search indexes are not stored.
• Recipes for layering certain applications: Virtually any application can be layered, but some are easier to layer if you start with the tips we’ve assembled in our App Layering Recipes forum. Before you start, consult the forum for tips and procedures about the specific applications you are layering.
• Applications that require you to add a local user or administrator. A local user or administrator that you add or change while installing an application on an app layer does not persist. The OS layer preserves any local users or groups that you add, but your app layers do not. Either add the local user or administrator to the OS layer before installing the application or consider installing the application on the OS layer.

Start a new app layer

To create a packaging machine where you can install the application:

1. Log in to the management console and select Layers > App Layers.
2. Click Create Layer in the Action bar.
3. Enter a Layer Name and Version, both required values. You can also enter other values.
4. On the OS Layer tab, select the OS Layer you want to associate with this app layer.
5. (Optional) The Prerequisite layers tab gives you the option to specify other app layers that must be present while installing the apps on this layer. Only use this when the required apps cannot be included in the same layer. For more information about this advanced feature, see Prerequisite layers in the following sections. Note: When adding a new version to an existing app layer, you must specify the Prerequisite layers you need. They are not carried over from version to version.
6. In the Connector tab, choose a connector configuration that includes the credentials for the platform where you plan to build the layer and the storage location. If the configuration you need isn’t listed, click New to add one.
7. On the Packaging Disk tab, type a file name for the packaging disk, and choose the disk format. This disk is used for the packaging machine, the virtual machine where you install the application.
8. On the Icon Assignment tab, choose 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 dialog box.
   • To import a new image, click Browse and select an image in PNG or JPG format.
   • If you are using a connector with Offload Compositing selected, and you choose one of the icons that came with App Layering, the packaging machine attempts to assign an icon based on the layer’s contents when the layer is finalized.
9. On the Confirm and Complete tab, review the details of the app layer and then click Create Layer. You can type an optional comment before creating the layer. Your comments appear in the Information view Audit History. After creating the packaging disk, the Tasks bar displays a link to the packaging disk in your hypervisor where you can deploy the packaging machine.
10. Select the Tasks page and click the Packaging Disk task. Click the info icon to show the full task description, including a link to the location where the packaging machine for this layer is published.

Next, you can deploy the packaging machine for your layer.

Deploy the packaging machine

Select your hypervisor:

• XenServer, Hyper-V, Nutanix, or vSphere
• Azure
• Other hypervisor (Network File Share)

XenServer, Hyper-V, Nutanix, vSphere

1. Log in to your hypervisor client (XenServer, Hyper-V Manager, Nutanix Prism, or vSphere).
2. Log in to the App Layering management console, and select the Tasks page so you can see the current tasks.
3. Select the Create App layer task and click the info icon to see the full task description.
4. Use the URL provided in the task description to navigate to the packaging machine in your hypervisor client.
5. The packaging machine is powered on.

You can now install the applications for this layer on the packaging machine.

Azure

The appliance opens the Azure Custom deployment template, where you can create the packaging machine.

1. Log in to the Azure portal (https://portal.azure.com). Note: You must log in before attempting the next step.
2. Go to the App Layering management console and select the Tasks page. Select the Create App layer task and click the info icon to see details.
3. Use the link in the task details to navigate to the packaging machine in Azure. The Custom deployment panel opens.
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 of 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 application you want to include in the layer.

Other hypervisor (by way of the appliance’s 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. 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.

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 the application you want to include in the layer.

Install the application

When installing your application on the packaging machine, leave the application as you want users to see it when they log in. The application’s state is what users experience every time they access the app.

1. Log in remotely to the packaging machine with the User account used to create the operating system.
2. Install the application, along with any drivers, boot-level applications, or files required for the app.
3. If a system restart is required, restart it manually. The packaging machine does not restart automatically. If the application you install affects boot-level components, restart the packaging machine as part of finalizing the layer.
4. Make sure that the packaging machine is in the state you want it to be in for the user:
   • If the application requires 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 machine

Once the application is installed on the packaging machine, verify that the layer is ready to be finalized. A layer is ready to be finalized when all post-installation processing is complete.

To verify that all outstanding processes are complete, you can run the Shutdown For Finalize tool on the packaging machine’s desktop.

To use the Shutdown For Finalize tool:

1. If you are not logged into the packaging machine, remote login as the user who created the machine.
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 to be completed before the layer can be finalized, you are prompted to complete the process. If a Microsoft Ngen.exe operation must be completed, you might be able to expedite the Ngen.exe operation, as detailed later in this article.
4. Once any pending operations are complete, double-click the Shutdown For Finalize icon again. This shuts down the packaging machine, and the layer is ready to finalize.

Layer integrity messages you might 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.exe 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.exe 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 layer, see the article, App Layering Recipe: How to deploy Microsoft SCCM in a layer.

For details about what the layer integrity messages mean and how to debug them, see Debugging Layer Integrity Problems in Citrix App Layering.

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 all of the processes have been completed.

If a Microsoft Ngen.exe operation is in progress, you might be able 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.

Ngen.exe 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. If you want to expedite an Ngen.exe operation, you can bring the task into the foreground to complete it as quickly as possible.

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

Once the software has been installed and the packaging machine has been verified and shut down, you are ready to finalize the layer.

Hyper-V:

If Offload Compositing is selected in your connector configuration, finalization happens automatically as part of the compositing process.

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 > App layers, and the layer you prepared.
3. Select your layer version on the Version Information tab and click Finalize in the Action bar.
4. Click Finalize to finish creating the layer.
5. 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.

Other hypervisor (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 > App Layers.

4. Select your layer version on the Version Information tab and click Finalize in the Action bar.

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

Clone an app layer

You can create an app layer that is the same as an existing layer by cloning a specific version of the layer. During the cloning process, you are prompted for information specific to the layer. You can update the app layer by adding versions to it. Since only one version of a layer is cloned, the new layer has just one version to start, even if the layer it was cloned from had many.

To clone a layer:

1. Select the app layer that you want to copy and click Clone Layer in the Action bar.
2. Select the Source Layer Version to clone. You can choose the version you want from the drop-down menu.
3. Enter a name for the layer, and a description, if the extra information is helpful. Descriptions are optional.
4. Enter the version, and a description of the version, if the extra information is helpful.
5. On the Icon Assignment tab, select the icon for the new layer.
6. On the Confirm and Clone tab, verify the settings and click the Clone Layer button.

A new layer is created with the same layer properties as the source, except for the icon. The layer priority is higher than that of the source layer because every new App layer has a higher priority than the last app layer created. The new layer size could be smaller than the original, but this just indicates that empty space was removed during cloning. The layer functions the same as the source.

You can use the new layer like any other layer, and it is not associated in any way with the original layer.

Advanced app layer options

When creating and updating app layers, keep in mind the following advanced features.

• Custom Layer script
• Layer caching
• Prerequisite layers

Custom Layer Script

You can include a script in an app layer that runs once, upon system startup. To configure the script, edit the properties of the application layer.

Note:

You can also edit the properties for the layer revision either while the revision is being created, or even after it has been finalized.

The script runs the first time any layered image that includes the app layer starts. If the app layer is elastically layered, the Custom Layer script runs when mounting the app layer disk. Custom Layer scripts are typically used for apps, such as MS Office, that require license activation the first time it starts.

Layer Caching for faster app layer creation

You can use layer caching to speed up layer creation times.

How caching works

The first time you create an app layer, if the cache size is set to a large enough value, a template consisting of the boot disk and the empty packaging disk is saved in the cache. The boot disk includes the OS layer, Platform layer, and Prerequisite layer (if any) that are specified in the app layer settings.

Whenever you create an app layer that uses the same OS layer, Prerequisite layer, and Platform layer combination, the App Layering software reuses the template, significantly reducing creation time.

If you then create an app layer that uses a different OS layer, Prerequisite layer, and Platform layer combination, the App Layering software creates a template and adds it to the cache.

Recommended cache size

The recommended cache size depends upon how many OS, Platform, and Prerequisite layer combinations you require for your app layers. The number of combinations determines the number of templates saved in the cache.

To estimate the space required for each template:

1. Select the i icon for each OS, Platform, and Prerequisite layer, and look up the Maximum Layer Size.
2. Add the Maximum Disk Sizes. The total is the Cache size that you need for that template.

To estimate the space required for the cache, add the size you determined for each of your templates.

Prerequisite layers

Rarely recommended, Prerequisite layers let you include one or more existing app layers on the packaging disk when creating a layer or adding a version to it.

Use prerequisite layers only if they are required, because they can add something into the layer that is not required to deploy the current application. This behavior can cause conflict in the future.

When to use Prerequisite layers

Prerequisite layers can be required for several reasons:

• When installing the application on the current layer requires the presence of another application. For example, when you install an application that requires Java, and Java is located in a separate layer.
• When the installation of the software adds settings to an existing application. For example, when you install an Office add-in, you must install Microsoft Office first.
• When two applications change the same registry key, and the second application must add to a key and not replace it. For example, two applications that both change login keys in Windows, such as Citrix Agent and Imprivata.

Note

Some of these issues can also be handled by putting the two applications in the same layer rather than using prerequisite layers.

Prerequisite layer characteristics

Prerequisite layers have the following characteristics:

• Prerequisite layers are not included in the app layer that they are used to create.
• The app layer that you create and each of its Prerequisite layers must use the same OS Layer.
• When adding a version to an app layer, Prerequisite layers are not included by default. Each time you add a version to a layer, you must select one or more Prerequisite layers.