The Citrix App Layering user layer has been available now for several years. For a long time, it was a “Labs” feature. With version 4.1 in September 2018, the user layer was released for general availability. It provides is the ability to have near full desktop persistence on non-persistent VDI infrastructure. It achieves this by providing a writeable elastic layer that is connected right before the user logs on to the desktop. Once connected all (well, most) writes on the desktop go into the user layers.
This enables users to save not only settings and other things stored in their user profile, but also user-installed apps and even apps stored in a user profile. But what if a user installs an application that an administrator later makes into an application layer? Or what if the user deletes an application that admins then want to provide to them? Is there an easy way to handle removing the application from the user layer without mounting it offline and manually fixing it? Up until version 1907, there wasn’t. Then the Citrix App Layering team created User Layer Repair.
User Layer Repair
User Layer Repair is a method to clean out the user layer of files and registry settings defined in an app layer. If you were an original Unidesk customer, you will remember a similar feature called “uninstall.” To make it work, two files are required per application layer. There is a package app rules file that defines the files and registry settings that are part of the app layer. Then there is a User Layer Repair JSON file that tells the Citrix App Layering service to clean up the user layer for that application. These files are stored in two folders within the elastic layer share path, under > Unidesk > Layers > App, as seen below.
They are named by LayerID_LayerRevision (for example UserLayerRepair_5898241_5.json). To run a User Layer Repair, the repair JSON file needs to be copied to the same folder as the user’s user layer. The Citrix App Layering service on the desktop will check in that folder for repair files and perform the repair if one or more files is found. The repair will happen during the user logon, so it would be a good idea to let the user know their next logon may take longer than usual. The repair process is documented in a section of the ulayersvc.log file. Here’s an example section from a log file. This log is in ProgramData\Unidesk\Log on the VDI desktop (click the image to view larger).
For more information on User Layer Repair, click here and search for User Layer Repair.
The Utility
I saw several discussion posts about the User Layer Repair feature after it was released. People were asking, what if you wanted to roll a repair out to 500 users at the same time? What if you wanted to roll four repairs to 500 users? As is often the case, I had some free time during the holidays and I decided to get a few things out of my to-do queue. Creating a utility to help with challenges around repairing user layers was at the top of my list.
I call it the User Layer Repair Utility. It enables administrators to select an OS layer, then list all the app layers created with that OS layer and match the layers to their associated repair JSON file. They can then get a list of all the user layers associated with that OS layer and select both the desired app layers to repair and the user layers to repair against, then copy the repair files to those selected user layer folders. When you open the utility, you will see something similar to the following:
After setting it up, use the following process to copy repair files to user layer folders.
- First click the Get OS Layers button. This will query the Citrix App Layering appliance for the list of OS layers.
- Choose the desired OS layer from the drop down. This will load the chosen OS layer’s LayerId and query the Citrix App Layering database for all associated app layers.
- Click the Get Repair Files button. This will find all the repair files on the elastic layering share and match them to the app layers in the table. Note that if the Repair File Info is blank, then the share does not yet have a repair JSON matching the layer. See the setup section for details on how to fix this issue.
- Click the “Get User Folders” button, which will find all of the user folders for the selected OS layer.
- Select the repair files to copy. You can use Select All and Unselect all buttons to help.
- Select the user folders to copy files to. You can use Select All and UnSelect All buttons to help.
- Lastly, use the Copy Files button to run the script to copy the selected repair files to the selected folders.
Please note, the search boxes can be used to perform a wildcard search; however you can only perform your selection within the search. If you clear the search or use another search, the selections will be cleared. Also the utility will show the results of the copy for two minutes in the PowerShell Window, and it will create a log file in the Logs folder for every run.
The utility uses a combination of an hta file written in vbscript plus a few PowerShell scripts to do what it does. The copy script will also change the permissions on the copied json files to full control for Domain Users. This is to ensure the users have the right to delete the JSON files after they are used. If you want to disable this part of the scripting, edit the CopyRepairFiles.ps1 file and rem out the line: icacls $myRepairFiles /grant ‘Domain Users:F’ /t uisng a “#”.
Setup
To set up the utility, download (see below) and unblock the zip file. Then extract it to a folder and run the hta file. You will see the user interface. Click on the Setup tab and follow the directions below:
- First enter your Citrix App Layering appliance FQDN or IP address.
- Type the root password for the appliance or choose to be prompted every use. If the password is saved, it will be encrypted. However the file can be unencrypted by anyone with access to the utility hta file. Click Save to save these settings for 1 and 2.
- Enter the network share defined in the system settings on the appliance (for example, \\server\share). Do not enter the entire path to the App Layer folder; the utility will add the folders past the share.
- Enter the user folder share (for example, \\server\share). Do not enter the entire path to the user folders; the utility will add the folders past the share. Click Save to save the settings for 3 and 4. Because you can only enter one user layer share, if you use more than one user layer share, you will need a version of the utility created for each user layer share you want to manage. Just copy the utility into a different folder and set it up for the different user share.
- Lastly, the utility provides the ability to regenerate all repair and package rules files. This process works by searching the local app layer repository on the Citrix App Layering appliance (/mnt/repository/Unidesk/Layers/App), which contains vhd files comprising each revision of each app layer. When the upload process is triggered, the App Layering appliance mounts each app layer vhd file, extracts the package_app_rules file, and uploads it to the network share. The JSON file is generated and uploaded at the same time. The uploads do not behave as a “transaction”, meaning that it is possible, for example, for the package_app_rules upload to fail and the JSON upload to succeed. Normally these files are created when layer revisions are created. Use this function sparingly but if you are missing repair files as seen on the repair tab then this can be used to generate those files.
Lastly, and possibly most importantly, this is version 1.0 of this utility. I have tested it in my lab, but it has not been tested by customers at the time this blog was published. Please start by using this in your lab. Treat it like any script you would develop yourself and test it well before adding it to your production environment.
Update 7-6-2021 – Version 3.0 – Adds Reset and Compression plus the ability to compress, expand and reset FSLogix containers. See Revamping the User Layer Repair Utility for more details.
Updated 7-30-2021 – Version 3.1 – Updated to handle spaces in the OS Layer Name. I would always recommend you don’t use spaces but if you do the utility will now still work.
Updated 1-21-2022 – Version 3.2 – In tis version I changed the starting point for the search for user layers. Previously the script would append a “\users” to the share defined in the setup so that you were sure to only find user layers in our default path. I have had requests from customers that used custom paths that did not conform to this standard so I changed the utility to start at the share level and recurse all the way down any paths found. This allows for custom paths and it also allows you to use different subfolders in a share for different sets of user layers and the utility will still work.
Remember this is to be used at your own discretion and is not supported by Citrix.
This software application is provided to you “as is” with no representations, warranties or conditions of any kind. You may use and distribute it at your own risk. CITRIX DISCLAIMS ALL WARRANTIES WHATSOEVER, EXPRESS, IMPLIED, WRITTEN, ORAL OR STATUTORY, INCLUDING WITHOUT LIMITATION WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NONINFRINGEMENT. Without limiting the generality of the foregoing, you acknowledge and agree that (a) the software application may exhibit errors, design flaws or other problems, possibly resulting in loss of data or damage to property; (b) it may not be possible to make the software application fully functional; and (c) Citrix may, without notice or liability to you, cease to make available the current version and/or any future versions of the software application. In no event should the code be used to support of ultra-hazardous activities, including but not limited to life support or blasting activities. NEITHER CITRIX NOR ITS AFFILIATES OR AGENTS WILL BE LIABLE, UNDER BREACH OF CONTRACT OR ANY OTHER THEORY OF LIABILITY, FOR ANY DAMAGES WHATSOEVER ARISING FROM USE OF THE SOFTWARE APPLICATION, INCLUDING WITHOUT LIMITATION DIRECT, SPECIAL, INCIDENTAL, PUNITIVE, CONSEQUENTIAL OR OTHER DAMAGES, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. You agree to indemnify and defend Citrix against any and all claims arising from your use, modification or distribution of the code.
Citrix Tech Bytes – Created by Citrix Experts, made for Citrix Technologists! Learn from passionate Citrix Experts and gain technical insights into the latest Citrix Technologies.
Click here for more Tech Bytes and subscribe.
Want specific Tech Bytes? Let us know! tech-content-feedback@citrix.com.
