Please note:
You can download the required file from the Citrix downloads website by visiting the following link: https://www.citrix.com/downloads/citrix-tools

Profile Management Configuration Check Tool (UPMConfigCheck)

Created Date: February 27, 2012

Updated Date: August 23, 2023

Description

UPMConfigCheck is a PowerShell script that examines a live profile management system and determines whether it is configured optimally.

Prerequisites

UPMConfigCheck requires PowerShell 2. UPMConfigCheck is designed to run on the Citrix Virtual Apps and Desktops (formerly XenApp servers and on XenDesktop) virtual desktops with Profile Management installed. Supported operating systems are the same as for Profile Management.

For System Requirements, refer to https://docs.citrix.com/en-us/profile-management/current-release/system-requirements 

Installing UPMConfigCheck

The UPMConfigCheck tool is supplied in a zipped archive. Extract the contents of the file to a temporary folder on the machine under test.

Use Cases for UPMConfigCheck

UPMConfigCheck is designed to verify that Profile Management has been configured optimally for the environment in which it runs, taking into account:

• Hypervisor Detection – The presence or absence of supported hypervisors (for example, Citrix Hypervisor (formerly Citrix XenServer), VMWare vSphere, or Microsoft Hyper-V).
• Provisioning Detection – The presence or absence of a supported machine-provisioning solution (for example, Machine Creation Services or Citrix Provisioning Services)
• Citrix Virtual Apps and Desktops – Determines whether it is running in a Citrix Virtual Apps or Desktops environment
• Personal vDisk Configuration – Determines whether the Personal vDisk feature of Citrix Virtual Desktops is enabled; reports the percentage of the Personal vDisk that is reserved for Applications, the details of which are in the Personal vDisk configuration.
• User Store – Verifies whether the expanded path to user store exists.  If the expanded path could not be found when the current user is not processed by Profile Management, user store root path is also checked
• Profile Management Service Status Detection.  If Profile Management is not installed or enabled, this tool exits.
• WinLogon Hooking Test – Verifies that Profile management is correctly hooked to WinLogon processing. This test is for Windows versions later than Windows Vista  and requires the user running the Configuration Check Tool to have access permission to the relevant registry keys. Otherwise, an error might be returned.
• Miscellaneous – Other factors that to the tool does not determine through registry or WMI queries, such as whether the computer running Profile Management is a laptop

Updates (November 2018)

• Windows 10 / Windows 2016 / Windows 2019 support
  • Performs version checks for Windows 10, Windows 10 version 1607, Windows 10 version 1703, Windows 10 version 1709, Windows 10 version 1803, Windows 10 version 1809, Windows Server 2016, and Windows Server 2019.
• Fixes certain false alarms.
• Reorganizes checks against policy.
• Adds path accessibility check for log file path.
• Adds path accessibility check for user store root path.
• Adds Profile Management service status check.
• Adds a pause to wait for a user input so that the check result could be reviewed when this tool runs via right-click context menu.
• Optimizes error and warning messages.
• Adds an XML format output file for each check items in the temporary folder.

Updates (December 2013)

• Windows 8 and Windows Server 2012 support
  • Performs version checks for Windows 8, Windows 8.1, Windows Server 2012, and Windows Server 2012 R2.
  • Checks for Windows 8 known issue described in “Known issues in Profile Management 5.x”, if Delete Profile on Logoff is set.
• UPM 5.x Autoconfiguration Support
• XenDesktop 7.x Support
  • Reports whether provisioning is through PVS or MCS, when this is exposed (XenDesktop 7 or higher)
  • Reports on HDX policies (for example, configured by the Policy Node in Desktop Studio) as a mechanism of configuring Profile Management
  • Provides a summary of which policies have been explicitly configured (and by which mechanism), identify which policies have been defaulted. Excludes Cross-Platform Settings policies.
• App-V Support – detects the App-V client and checks for recommended exclusions when App-V is in use.
• ShareFile Support – detects whether ShareFile Enterprise Desktop Sync is installed and configured correctly for interoperability with Profile Management.
• Personal vDisk Support – Additional warning to remind that Profile Streaming and Delete Locally Cached Profiles settings are forcibly disabled if Personal vDisk is in use.
• Additional Consistency Checks
  • Path to User Store: for presence of supported attributes and variables that will assist scalability and optimum ordering.
  • Profile Management logging
  • Template profile policies
• Additional CSV Reporting – extra file UPMListPolicySummary.csv for reporting on Profile Management Policies that are lists of paths or Active Directory groups. This file is in addition to the existing CSV files (UPMEnvironmentSummary.csv and UPMPolicySummary.csv) and are used to assist offline analysis.
  • Bug Fixes – Miscellaneous bug fixes.

Updates (December 2012)

• Profile Size Reporting – For the currently logon user, reports the disk usage for the profile volume, and summary analysis of all profiles on the volume (profile type, local path, network path for Profile Management and Microsoft Roaming Profiles). A warning message can be returned if free space on profile volume is below 15% (this value is configurable via command-line parameter—ProfileDriveThresholdPercent)
• Folder Direction – Compares the folder exclusion list with the Citrix-recommended exclusions and report on divergences. Also reports on folder redirection for the logon user, with recommendations.
• Caching – Performs the analysis described at Profiles: To cache or not to cache, that is the question… and recommends configuration changes in accordance with that article.
• VDA Configuration – For a XenDesktop environment, queries the Virtual Desktop Agent (VDA) WMI API (ROOT\citrix\DesktopInformation) to report on VDA configuration
• Additional Tests:
• Check if UPHClean or User Profile Service is installed and active.
• Check for VDI-in-a-Box or Kaviza installed and active
• Check for Hypervisor tools and/or shutdown services for XenServer, Hyper-V and VMware (these are required for graceful shutdown of VDA and avoid profile data loss).
• Identify origin of all policies applied to the system, if by INI-file or GPO policy. Warns if INI and GPO policies are both used.
• Increased Reporting:
• Added notes to all recommendations provided by the tool, containing reasons and/or explanations.
• Include the date, time and UPMConfigCheck version for each run
• Report inventory of installed Citrix products and components.
• CSV Reporting – By using the new command-line switch -WriteCsvFiles details of settings and policies can be output to two separate CSV files (UPMEnvironmentSummary.csv and UPMPolicySummary.csv) to assist subsequent offline automated analysis.
• Bug Fixes – Miscellaneous bug fixes.
• Bug Fix – Corrected INI file processing.
• • Included help text, for use with PowerShell Get-Help command.
  • Report on when and how the profile was created and whether this is the first logon (from UPMSettings.ini and similar files). Report install and boot times.
  • Warnings, errors and recommendations are now collected and displayed at the end of the script execution, so you don’t have to read through all the output.

Updates (Aug 2012)

• Improved Hypervisor Detection – recognition for newer versions of Hyper-V and reporting details of manufacturer for ‘unknown’ Hypervisors.
• WinLogon hooking test – verifies that Profile Management is correctly hooked to WinLogon processing. This test is for Windows Vista, Windows 7, Windows Server 2008, Windows Server 2008 R2, and requires the user running the Configuration Check Tool to have access permission to the relevant registry keys. Otherwise, an error might be returned.
• Personal vDisk test – Reports the percentage of the Personal vDisk reserved for Applications, the details of which are in the Personal vDisk configuration.
• Verifies Path to User Store – Tests to determine whether the expanded Path to User Store exists.

For an explanation on how all of these factors influence the Profile Management configuration, see the Citrix Documentation topic Deciding on a Configuration.

UPMConfigCheck is intended to be used to help identify or solve problems and optimize configurations:

• In a pilot deployment, to help set up the initial configuration for testing
• In a production environment, to ensure that the pilot configuration has been correctly replicated
• In either pilot or production environments, to detect a number of common known issues and misconfigurations

Important:

This tool is being released to customers on an “AS IS” basis. No support is implied, and customers are referred to the documentation Deciding on a Configuration to inform themselves on the suggestions made by the tool, and to decide for themselves whether the tool’s suggestions are appropriate for their own environment.

Support for Profile Management remains a part of your normal support contract. Nevertheless, your support representative might ask you to run this tool as part of the normal diagnostics gathering procedure.

Using UPMConfigCheck

Note 1: UPMConfigCheck does not require any special permissions to run.

Note 2: UPMConfigCheck does not make any changes to the file system or the registry.

Unless otherwise directed, run UPMConfigCheck when logging on as a normal user to a physical or virtual machine in the target OU.

1. Start a PowerShell command window and ensure that PowerShell is set up to allow scripts to run.
   
   PS > Get-ExecutionPolicy
   
   RemoteSigned
   
   Choose and set an appropriate execution policy according to your in-house guidelines. See about_Execution_Policies for help on understanding execution policies.
    
2. Run the script from the temporary folder to which it was unzipped.
   
   PS > .\UpmConfigCheck.ps1
   
   The script does have the following optional parameters.
    
3. The script analyses the environment for any factors that influence the optimum Profile Management configuration. It reports the environment and any non-optimal settings in the configuration, defined either with .ini files or Group Policy. UPMConfigCheck does not make any changes to the configuration, and Citrix recommends that you read and understand the appropriate section of the Citrix Documentation topic Deciding on a Configuration before making any changes.
4.  
   • WriteCsvFiles – Outputs details of settings and policies to two separate CSV files (UPMEnvironmentSummary.csv and UPMPolicySummary.csv)
   • ProfileDriveThresholdPercent – a warning message will be returned if free space on the profile volume is below this value, in percent.

Understanding and Processing UPMConfigCheck Output

Non-optimal settings now are grouped and shown as warnings and errors such as:

************************************Errors******************************************************

Profile Management Log Settings

*** Error: PathToLogFile \\MyTestPath is not accessible. Reason: Log file path should be accessible so that log files can be saved.

************************************Warnings****************************************************

Profile Management Basic Settings

*** Warning: ProcessAdmins actual/effective setting (Disabled) does not match preferred setting (Enabled) Reason: ProcessAdmins should be enabled in desktop OS environments, where the end user also has the needs to administer the machine.  ProcessAdmins is not recommended in server OS environments.

Profile Management Advanced Settings

*** Warning: ProcessCookieFiles actual/effective setting (Disabled) does not match preferred setting (Enabled) Reason: Citrix recommends to configure this setting to prevent cookie bloat.

*** Warning: OutlookSearchRoamingEnabled actual/effective setting (Disabled) does not match preferred setting (Enabled) Reason: Enable search index roaming for Outlook feature is recommended to be enabled to improve the user experience when searching mail in Microsoft Outlook. If enabled, the user-specific Microsoft Outlook offline folder file (*.ost) and Microsoft search database are roamed along with the user profile.

FolderRedirection

*** Consider redirecting local folder (C:\Users\Administrator\Music, C:\Users\Administrator\Pictures, C:\Users\Administrator\Videos, C:\Users\Administrator\Documents, C:\Users\Administrator\Downloads, ) to a network share

Press any key to continue...

Profile Management Basic Settings, Profile Management Advanced Settings, FolderRedirection are the categories while the warnings and errors start with three asteroids.

If you have been asked by Citrix Technical Support to run the tool and collect diagnostics from it, you should export the output to a file.

PS > .\UpmConfigCheck.ps1 > diagnostics.txt

To gather the information about configuration in CSV format, run the utility with the -WriteCsvFiles command line switch.

PS > .\UpmConfigCheck.ps1 -WriteCsvFiles

Then send the resultant files (diagnostics.txt, UPMEnvironmentSummary.csv and UPMPolicySummary.csv) as directed by your Citrix contact.

Removing UPMConfigCheck

To remove the tool from a computer, delete the UPMConfigCheck.ps1 script from the temporary folder created earlier.

Known Issues with UPMConfigCheck

None

Feedback / Contact Information

Feedback on the tool is welcome and can be provided via the Profile Management Forum.

Disclaimer

These software applications are 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.

The above mentioned sample code is provided to you as is with no representations, warranties or conditions of any kind. You may use, modify 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 sample code 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 sample code 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 sample code. 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 SAMPLE CODE, INCLUDING WITHOUT LIMITATION DIRECT, SPECIAL, INCIDENTAL, PUNITIVE, CONSEQUENTIAL OR OTHER DAMAGES, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Although the copyright in the code belongs to Citrix, any distribution of the code should include only your own standard copyright attribution, and not that of Citrix. You agree to indemnify and defend Citrix against any and all claims arising from your use, modification or distribution of the code.

Please note:
You can download the required file from the Citrix downloads website by visiting the following link: https://www.citrix.com/downloads/citrix-tools