Product documentation
App Layering
View PDF

Known issues

October 24, 2024
Contributed by: 
C C

App Layering upgrade

App Layering 2409

  • You may encounter an incorrect message after migration completes with failed agents in Citrix App Layering. The message states, “The migration has completed successfully, but we were unable to register the following App Layering agents with the target appliance: System.Collections.Generic.List`1[System.String].” [UNI-91339]

  • After migration to the target Elastic Layer Manager (ELM), you will not be prompted to set the root and console administrator passwords. If these passwords were not set prior to migration, they will default to the factory settings.

    As a workaround:

    If the passwords were not set before migration, log into the target ELM console as root and change the passwords manually using the following commands:

    • Change the root password:

      passwd

      You will be prompted to set a password for root.

    • Change the administrator password:

      passwd administrator

      You will be prompted to set a password for administrator, use a lower-case ‘a’.[UNI-91472]

  • When you connect to a new ELM using a non-root user, you may receive an unclear error message that states, “Cannot convert undefined or null to object.” You should expect a specific message indicating that the user is incorrect. [UNI-91330]

  • You should avoid using special characters such as &, <, and > in your default administrator password on the ELM, as this may cause OS layer creation failures via the Import script. [UNI-87311]

  • After migration, the management console Administrator password on the target Elastic Layer Manager (ELM) will be overwritten with the password from the source ELM. As a workaround, you can log into the target ELM as a user with Administrator privileges and change the default Administrator password. [UNI-91451]

  • After migration, the Images, Connectors, Directory Services, and User Layer Storage blades on the Target ELM do not refresh automatically. You may notice that these blades appear empty, even though the Layers blade shows data. To display the correct information, manually refresh your browser or tab.[UNI-91374]

  • After performing a Copy migration, you are unable to launch elastically assigned app layers on images published by the target Elastic Layer Manager (ELM) when a new network share is created.

    Cause

    The new network share does not contain any app layers that were previously assigned and synced to the original network share on the source ELM.

    Workarounds

    Workaround 1: Execute the following command: mono /usr/local/unitools/MAService.exe -fire SyncRevisionsToShareEvent

    Workaround 2: Manually copy all app layers from the source ELM’s network share to the new network share associated with the target ELM.

    Workaround 3: Unassign and then reassign the app layers to you. This action will trigger a sync of the layers to the new network share.[UNI-91377]

App Layering 2312

Upgrading to App Layering 2312 might fail, returning the error “A failure occurred while upgrading the appliance. Try the upgrade again after reverting from a clean snapshot.” We are aware of an issue with some appliances that were upgraded from previous versions. In this scenario, the upgrade might fail due to the presence of legacy upgrader components. We are working on a patched build for App Layering 2306 that contains a permanent fix for this issue.

To work around this issue, it is necessary to remove the legacy module by making the following changes in the Layering appliance:

  1. Log in to the appliance console using the root login and password.
  2. Run the command “yum remove mod_http2”. It might take several minutes for the command to run.
  3. After the command completes, log back into the appliance using a web browser and rerun the upgrade.
  4. It might take 30 minutes or more for the upgrade to complete, but it must now succeed.

App Layering 2005

  • The App Layering 2005 upgrade package is large enough that older appliances cannot download it automatically. If you are running version 2001 or older, download the package manually from the downloads site.

  • We recommend running the upgrade from a management console in Secure HTTP (HTTPS). If you upgrade while in HTTP, messages do not display in the browser. If that happens, refresh the browser after 20 minutes. (Refreshing won’t cause issues despite the message that says not to refresh.) If the upgrade is still running, you get a “service unavailable error.” It is safe to ignore the message and keep refreshing the browser every few minutes until the login page appears.

  • If you have two upgrade packages with the same name in different folders in Network File Share, selecting one of those packages causes both packages to be selected. If both packages have the same version, the upgrade succeeds. If they have different versions, the system chooses the lower version number. This occurs with Enterprise Layer Manager (ELM) version 22.2.

App Layering appliance and management console

  • In the new UI, platform types cannot be edited. Edit Platform Types still functions correctly in the old UI. (UNI-86856)
  • When installing the App Layering appliance, you must use the default CPU setting of 4 CPUs.
  • If you use roles in a complex Active Directory environment and logins are slow, assign all roles to explicit users rather than to groups.

The documentation links in the management console open as a blank page in Internet Explorer 11. To get around this issue, paste the link into another browser. The documentation displays correctly.

App Layering agent

By default, the Citrix App Layering Agent runs under the Local System account on the Hyper-V server. If you change the account to anything other than Local System, the agent cannot transfer disks to and from the appliance.

App Layering OS Machine Tools

  • (Release 19.5 only) After upgrading to release 19.5 (or later) from 19.3 (or earlier), be sure to update KMS Office Activation to use Office 2019. When preparing your OS image for layering, download and run the new App Layering OS Machine Tools.

  • (Release 19.1 only) When preparing your OS image for layering, ensure that your KMS Office Activation is triggered at desktop startup. For this release only, download and run the App Layering OS Machine Tools from Release 18.12.

Microsoft Teams 2.x

Microsoft Teams 2.x has changed its installation method and now installs under C:\Program Files\WindowsApps. To support this change, you must be running App Layering version 2403.2 or later. You can download an upgrade disk in the App Layering downloads page that includes this fix.

Keep in mind:

  • You must still follow MSFT recommendations for the exclusion of certain folders/files from persisting.
  • Elastic-fit indicates these app layers are not suitable for elastic assignment (include the UWP/Appx app layers in the published image).
  • Existing user-layer users go through a “first-time” login experience if changes are made to the mix or versions of these two applications are changed in the image.
  • When updating Microsoft Teams in an app layer revision, remove the previous version before installing the newer version.
  • If Microsoft Teams 2.1 was previously installed into the OS layer, it must be removed from the OS layer, before creating App Layer(s).

If you are running an earlier version of App Layering, a workaround is required to install Microsoft Teams 2.1 in the OS Layer, use the following workaround.

Workaround:

  1. Create an OS layer version.
  2. Download the .exe installer for Windows 10 or 11.
  3. Download MSIX.

    Note:

    For more information on the .exe installer and MSIX, see the Microsoft documentation.

  4. Open an admin command prompt.
  5. Disable Microsoft Teams auto update using the following command: reg add hklm\software\microsoft\teams /v disableAutoUpdate /t REG_DWORD /d 1 /f
  6. Based on where your .MSIX is located, do the following steps:
    1. For Windows 10 or 11, use the following command: .\teamsbootstrapper.exe -p -o "c:\path\to\teams.msix"
    2. For Windows Server 2016, 2019, or 2022, use the following command: Dism /Online /Add-ProvisionedAppxPackage /PackagePath:<MSIX package path> /SkipLicense
  7. To complete the installation, launch Microsoft Teams.

  8. Create a UserExclusion file to include the following MSFT-recommended exclusions:

    • c:\Users\*\AppData\Local\Publishers\8wekyb3d8bbwe\TeamsSharedConfig\Meeting-Addin\
    • c:\Users\*\AppData\Local\Packages\MSTeams_8wekyb3d8bbwe\LocalCache\Microsoft\MSTeams\Logs\
    • c:\Users\*\AppData\Local\Packages\MSTeams_8wekyb3d8bbwe\LocalCache\Microsoft\MSTeams\PerfLogs\
    • c:\Users\*\AppData\Local\Packages\MSTeams_8wekyb3d8bbwe\LocalCache\Microsoft\MSTeams\EBWebView\WV2Profile_tfw\WebStorage\
  9. Finalize the OS layer version.
  10. (Optional) Ensure no application layers containing a previous Microsoft Teams version is assigned elastically or statistically.

Note:

  • Don’t run the .MSIX file itself. This installs Microsoft Teams and would be available in the Start menu but when clicked, the process doesn’t start.
  • Don’t log in to any Microsoft Teams accounts while creating an OS layer and don’t change any Microsoft Teams settings. Personal accounts are not supported with the new Microsoft Teams. For more information, see Microsoft documentation.

[UNI-90395]

Elastic Layering

User layers

  • Signing on after upgrade starts the Windows First Sign-in screens: When you sign in after upgrading to 4.10 or later, the usual Windows First Sign-in brings the user layer up-to-date with the OS version. The process preserves user layer files.

Windows 10 support

  • Windows 10, version 20H2 upgrades. If you upgrade the OS layer to Windows 10 20H2 from an earlier release, upgrade directly to Build 19042.630, or later. Upgrading from builds of Windows 10 20H2 released before 11/16/2020 can result in inconsistent image deployments. For example, if you publish images using a template with Generalize Offline selected, the published images might not work correctly.
  • Upgrading requires extra steps when going to a new Windows 10 major release: During the upgrade, Windows 10 can create a recovery volume on the same disk as the OS layer version. Always delete this volume before you finalize the OS layer version. Otherwise, the recovery volume can cause desktops to fail to start correctly. For more information, see Issue 9 under Windows 10 v2004, 20H2, 21H1 & 21H2 - Citrix Known Issues.
  • If you have generated and applied the App Layering Optimizations.cmd script to a Windows 10 1909 OS layer, the Search option on the Start menu might not work as expected. To avoid this issue, add a version to the OS layer and run the program c:\windows\setup\scripts\Optimize.hta. To build a new Optimizations.cmd script to apply to the new layer version, deselect Disable tablet input service (Section 6, Option M) and select Save File. Before finalizing the OS layer, run the command Powershell Set-Service TabletInputService -startuptype manual to undo the effect of any previous Optimizations.cmd that might have disabled the service.

Connectors

  • When using the Azure Deployments connector, if you delete all templates and edit the connector to choose a new template, a deleted template version appears. Then when you click Save, an error appears. As a workaround, reselect a valid template version before clicking Save. (UNI-88412)
  • When using the Windows mini-boot disk option, you can specify up to four Prerequisite layers for any given App layer. If an app requires more than four other applications to be present during installation, install multiple apps in one layer. (UNI-69524)
  • When creating a layer (app, OS, or platform) on Windows 7 64-bit, if you select Offload Compositing in the connector configuration, you can have issues adding a version to the layer. An error occurs and the packaging machine is not created. When Offload Compositing is not selected in the connector configuration, the packaging machine is created. (UNI-82545)
  • Receiving 503 error, “Server Busy issues” from Azure. If you consistently receive this error, follow the steps in CTX310868. This issue happens sporadically, and a solution for it is being tested. (ALHELP-1383)
  • If you attempt to enter a name for a connector, and that name already exists, you receive a generic error message from the system, rather than the correct error message. The issue occurs for the Azure Deployments, Machine Creation for Azure Deployments, VMware vSphere, and Machine Creation for vSphere connectors. (UNI-89218)

Citrix Provisioning

  • When you create an image template, the target device hardware settings must match the Windows operating system and platform layer settings. Ensure that the hardware settings on the target device match the operating system and platform layer hardware settings, especially the number of CPUs. If the settings don’t match, you can get a “restart required” message when you start the published image. (UNI-50799)
  • If you use Provisioning Services, you must disable IPv6 in the OS layer and not in the Platform layer. (UNI-53600)
  • When importing VHDX files published from App Layering to the PVS disk store, you sometimes receive an invalid disk message. Eliminate the error by changing the period (.) characters in the published file name’s date and time. A valid file name contains only one period for the VHDX file name extension. (UNI-75902)
  • When Offload Compositing is selected in the connector configuration:
    • The path for the Citrix Provisioning Store fails to validate if it contains spaces. Replace the spaces with %20 to make the name valid. (UNI-84868)
    • Publish jobs fail if the File Share Path ends with a backslash (\). (UNI-85045)
    • Publish jobs fail with a ComponentActivator error message if the Domain User does not have Read and Write permission to the File Share Path. (UNI-85020)
  • When you select a Hyper-V connector for the offload compositing configuration, and the OS Layer is Gen 2, you must create another version of the OS layer, and then create the platform layer from that OS version. Otherwise, the target does not boot. (UNI-85044)

  • When setting the Compositing File Share Path for the connector configuration, connectivity between the compositing engine and the Citrix Provisioning Store is not verified. If the store path doesn’t map to the File Share Path, you receive an error similar to:

    • Error: “An unexpected system error occurred. Retry the operation or contact technical support. Exception Message: Response status code does not indicate success: 404 (Not Found). [Exception Details] (UNI-85045), (UNI-85020)

XenServer

  • When you prepare your operating system image for use in your XenServer, you must open port 5900 to allow console access. (UNI-50846)
  • Always set the Citrix App Layering connector configuration to point to the master node. (UNI-52454)
  • Prerequisite layers:
    • If a machine hangs at boot and a prerequisite layer is selected, one of the layer disks is probably not attached. Ensure that the Citrix Guest Tools are included in either the OS or platform layers.
    • If you are using Prerequisite layers to create either the OS or platform layer, Citrix Tools must be present. Without the tools, the packaging machine fails and you receive a blue screen. XenServer isn’t able to see any devices attached after the DVD drive. The DVD drive is always in the third slot. (UNI-67741)

Citrix Virtual Apps and Desktops (CVAD)

  • When updating Citrix Virtual Apps and Desktops to version 7.15 CU4, you must first install .NET Framework 4.7.1 on a new version of your OS layer, rather than on the platform layer. Installing .NET Framework 4.7.1 on the OS layer ensures that all app layers, platform layers, and images work correctly. The latest Windows updates already include .NET Framework 4.7.1 as part of the updates. (ALHELP-588, UNI-75108)

Google Cloud

  • When importing layers from another platform, you must add a version to the OS layer, and switch to using the new layer version from then on. Otherwise, packaging machines and published images are likely to fail with a blue screen.

  • Google Cloud Connector Configuration. “Check Credentials” verifies the Service Account User role. If the service account specified in the Google Cloud connector configuration Service Account JSON key file is different than the service account associated with your selected Instance Template, your service account in the configuration must have the Service Account User role. If it does not, then you receive an error when deploying a machine using that connector configuration. (UNI-82082)

Nutanix Acropolis

  • The following message during app layer creation indicates that the app layer settings specify a platform layer. Do not use platform layers with the app layer’s performance-enhancing caching feature. (UNI-67742)

    image

VMware vSphere

  • When creating the OS layer using the Create OS Layer Wizard, Unified Extensible Firmware Interface (UEFI) virtual machines are listed. You cannot, however, create UEFI machines using the wizard. Instead, use the new ImportOsLayer.ps1 script to import the OS onto the new OS layer machine.
  • When using a vSphere connector configuration with VMware Cloud and a vSAN 7.0 Update 2 (or later) datastore, Offload Compositing must be selected. (UNI-85216)
  • When using the new VMware vSphere connector in AL 23.4, if you select an opaque network when creating or editing the connector, the connector fails. As a workaround, select a non-opaque network. Existing connector configurations using an opaque network created before AL 23.4 continue to function normally. (UNI-89439)

Microsoft Azure

  • App Layering does not support Azure File storage. For storage in Azure, create an SMB file share or a network file share. (UNI-42272)
  • Managed disks are only supported for OS imports. Packaging app layers and publishing images only produce unmanaged disks. When creating a virtual machine in Azure, select No managed disks.

Microsoft Hyper-V

  • When selecting a Hyper-V connector configuration for Offload compositing and your OS layer is Gen 2, the layer must have at least one version besides the original. Also, the platform layer where the Citrix Provisioning target device software is installed must be created using the new OS layer version. (UNI-85044)
  • When a Hyper-V connector configuration is set for Offload Compositing with Gen 2 (UEFI) and VHDX, choosing VHD as the Disk Format in the Citrix Provisioning connector configuration is allowed, but this configuration is not supported.
  • When you configure Elastic Layering in Hyper-V, you must use unmanaged RDS pools (UNI-53545)

  • When creating an app layer, if a platform layer is specified in the app layer settings, you receive an error. Do not use platform layers with App Layering’s caching feature. (UNI-71868, UNI-67743)

    image

  • Creating an OS layer on Hyper-V Server 2019 can result in this error:

    ‘Failed to create VHD. Make sure that there is enough space on the share specified in the connector configuration.’

    This error is due to an issue with the Microsoft PowerShell New-VHD cmdlet. We are keeping our eye out for a fix from Microsoft. In the meantime, use the following workaround for this error:

    1. Make sure that the Gold VM has no checkpoints.
    2. Make sure the Gold VMs disk is in the same directory path that is configured in the connector config. Example: Local path is D:\Brock
      Gold VM disk is stored in D:\Brock\WIn10Gold\Win10GoldDisk.vhdx

  • App Layering fails to create an app/platform layer if the path to storage in the Hyper-V connector configuration contains a backtick (`). For example:

     mystoragename`
 <!--NeedCopy-->

Printing

With App Layering images configured for Full User Layer, you can install your own printer devices directly. However, when you log out and log in, Printers & Scanners no longer show the self-installed printer devices.

As a workaround, you can access or select the printers from within the applications.

Network

Applications that include network components may not operate correctly when installed in an App Layer and then included in a published image. Applications of this type need to be installed into either the OS Layer or the Platform Layer to ensure a proper merge of the network-related registry information in the image.

Known issues
October 24, 2024
Contributed by: 
C C
October 24, 2024
Contributed by: 
C C

In this article

Site feedback | Your privacy choices footer linkYour Privacy Choices | Privacy and legal terms | Cookie preferences | Consent settings | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.