Citrix Virtual Apps and Desktops service

Cloud Health Check

Cloud Health Check allows you to run checks that gauge the health and availability of the site and its components. You can run health checks for Virtual Delivery Agents (VDAs), StoreFront servers, and Profile Management. VDA health checks identify possible causes for common VDA registration, session launch, and time zone redirection issues.

If issues are present during the checks, Cloud Health Check provides a detailed report and the actions to fix the issues. Each time Cloud Health Check starts, it checks for the latest version of scripts on the Content Delivery Network (CDN) and automatically downloads the scripts if they do not exist on the local machine. Cloud Health Check always chooses the latest local version of scripts to run health checks.

Note:

Cloud Health Check does not update every time it runs.

In a Citrix Cloud environment, run Cloud Health Check from a domain-joined machine to run checks on one or more VDAs or StoreFront servers.

Note:

You cannot install or run Cloud Health Check on Cloud Connector.

The log for the Cloud Health Check application is stored in C:\ProgramData\Citrix\TelemetryService\CloudHealthCheck.log. You can use this file for troubleshooting.

Installation

To prepare your environment for installation of Cloud Health Check, you must have a domain-joined Windows machine.

Note:

You cannot install or run Cloud Health Check on Cloud Connector.

  1. On the domain-joined machine, download the Cloud Health Check installer.
  2. Double-click the CloudHealthCheckInstaller_x64.msi file.
  3. Click the box to accept the terms.
  4. Click Install.

    cloud health check 1

  5. After installation has completed, click Finish.

    cloud health check 2

Permissions and requirements

Permissions:

  • To run health checks:

    • You must be a member of the domain users group.
    • You must be a full administrator or have a custom role with read-only and Run Environment Tests permissions for the site.
    • Set the script execution policy to at least RemoteSigned to allow the scripts to run. For example: Set-ExecutionPolicy RemoteSigned. Note: other script execution privileges can work as well.
  • Use Run as administrator when launching Cloud Health Check.

For each VDA or StoreFront machine that you run health checks on:

  • The OS must be 64-bit.
  • Citrix Telemetry Service must be installed on the machine.
  • Cloud Health Check must be able to communicate with the machine.
  • File and printer sharing must be turned on.
  • PSRemoting and WinRM must be enabled. The machine must also be running PowerShell 3.0 or later.
  • Windows Management Infrastructure (WMI) access must be enabled on the machine.

About health checks

Health check data is stored in folders under C:\ProgramData\Citrix\TelemetryService\.

VDA health checks

For registration on the VDA, Cloud Health Check checks:

  • VDA software installation
  • VDA machine domain membership
  • VDA communication port availability
  • VDA service status
  • Windows firewall configuration
  • Communication with Controller
  • Time sync with Controller
  • VDA registration status

For session launches on VDAs, Cloud Health Check checks:

  • Session launch communication port availability
  • Session launch services status
  • Session launch Windows firewall configuration
  • VDA Remote Desktop Services Client Access Licenses
  • VDA application launch path

For time zone redirection on VDAs, Cloud Health Check checks:

  • Windows hotfix installation
  • Citrix hotfix installation
  • Microsoft group policy settings
  • Citrix group policy settings

For Profile Management on VDAs, Cloud Health Check checks:

  • Hypervisor detection
  • Provisioning detection
  • Citrix Virtual Apps and Desktops
  • Personal vDisk configuration
  • User store
  • Profile Management Service status detection
  • Winlogon.exe hooking test

To run checks on Profile Management, you must install and enable Profile Management on the VDA. For more information on Profile Management configuration checks, see Knowledge Center article CTX132805.

StoreFront health checks

StoreFront checks verify whether:

  • Citrix Default Domain service is running
  • Citrix Credential Wallet service is running
  • The connection from the StoreFront server to Active Directory is port 88
  • The connection from the StoreFront server to Active Directory is port 389
  • The base URL has a valid FQDN
  • The correct IP address from the base URL can be retrieved
  • The IIS application pool is using .NET 4.0
  • The certificate is bound to the SSL port for the host URL
  • The certificate chain is complete
  • The certificates have expired
  • A certificate is expiring within 30 days

Running Cloud Health Check

To run Citrix Cloud Health Check:

  1. Select Citrix > Citrix Cloud Health Check from the machine’s Start menu, or run CloudHealthCheck.exe in C:\Program Files\Citrix\CloudHealthCheck.

    cloud health check 3

  2. On the main Cloud Health Check screen, click Add machine.

    cloud health check 4

  3. Type the FQDN of the machine you want to add. Note: Although entering a DNS alias instead of an FQDN can appear valid, the health checks might fail.
  4. Click Continue.
  5. Repeat to add other machines as needed.

    cloud health check 5

  6. To remove a manually added machine, click the X on the right end of the row and confirm the deletion. Repeat to delete other manually added machines.

Cloud Health Check remembers manually added machines until you remove them. When you close and then reopen Cloud Health Check, the manually added machines are still listed at the top of the list.

Import VDA machines

You can import VDA machines in the deployment when running health checks.

  1. On Connector, generate the machine list file with the following PowerShell command. On Connector, you must input Citrix credentials and select the customer in the pop-up dialog.

Get-BrokerMachine| foreach { $_.DnsName } | out-file C:\machineList.txt

  1. Copy the machineList.txt file to the domain-joined machine you want to run Cloud Health Check on.
  2. On the Cloud Health Check page, click Add Machine.
  3. Select the Windows VDA machine type.
  4. Click Import VDA machines.
  5. Select the machineList.txt file.
  6. Click Open.

    cloud health check 6

    The imported VDA machines are listed on the Cloud Health Check page.

  7. Select the check box next to each machine you want to run health checks on.

    Cloud Health Check automatically launches verification tests on each selected machine, making sure it meets the criteria listed in verification tests. If verification fails, a message appears in the Status column, and that machine’s check box is cleared. You can then:

    • Resolve the issue and then select the machine’s check box again. This triggers a retry of the verification tests.
    • Skip that machine by leaving its check box unselected. Health checks are not run for that machine.
  8. When the verification tests are complete, click Continue.

    cloud health check 7

  9. Run the health checks on the selected machines. The summary lists the machines where the tests run (the machines you selected that passed the verification tests).

  10. Click Start Checking.

    cloud health check 8

    During and after checking, the Status column indicates the current checking state for a machine.

  11. To stop all in-progress checks, click Stop Checking in the lower right corner of the page. You can’t cancel a single machine’s health check, you can only cancel the check for all selected machines.

    cloud health check 9

  12. When the checks are complete for all selected machines, the Stop Checking button in the lower right corner changes to Done.

    cloud health check 10

    • If a check fails, you can click Retry in the Action column.
    • If a check completes with no issues found, the Action column is empty.
    • If a check finds issues, click View Details to view the results.

    cloud health check 11

If you use Internet Explorer to view the report, you must click Allow blocked content to display the hyperlink.

cloud health check 12

After the check completes for all selected machines, clicking Back causes you to lose your check results.

When the checks complete, click Done to return to the Cloud Health Check main screen.

Heath check results

Health checks that generate reports contain the following elements:

  • Time and date when the results report was generated
  • FQDNs of the machines that were checked
  • Conditions checked on the target machines

Running Cloud Health Check on the command line

Cloud Health Check can be run on the command line to help customers to perform health checks. To use Cloud Health Check on the command line, you must be an administrator on the machine Cloud Health Check is running on.

Note:

When using Cloud Health Check on the command line, only one machine can be checked at a time. Only one instance of CloudHealthCheck.exe can be run at the same time on the target machine. If you want to check multiple machines, the machines must be checked one by one, by wrapping the cmdlets in a loop in cmdlet/PowerShell scripts. Any opened UI instance of Cloud Health Check must also be closed.

Cmdlets

The supported command line cmdlets are:

  • MachineFQDN - This cmdlet is mandatory. This is the fully qualified domain name of the target machine.
  • MachineType - This cmdlet is optional. The cmdlet value can be the Windows VDA (default value) or StoreFront.
  • ReportName - This cmdlet is optional. The cmdlet value must be a valid file name on Windows. The default value is HealthCheckReport.

Examples:

CloudHealthCheck.exe -MachineFQDN machine.domain.local

CloudHealthCheck.exe -MachineFQDN machine.domain.local -ReportName checkreport

Note:

The parameter names are not case sensitive.

By default, the console output is not shown in the command line console window. You can manually display the output by appending |more to the cmdlet.

Example: CloudHealthCheck.exe -MachineFQDN machine.domain.local|more

Multiple machine checks

To run Cloud Health Check on the command line for multiple machines, use the following example:

@echo off
for %%n in (machine1.domain.local,machine2.domain.local,machine3.domain.local) do (
start /wait CloudHealthCheck.exe -FQDN %%n
echo %errorlevel%)

Exit codes

Exit codes explain the result of Cloud Health Check checks within the command line. To get the exit code, you must add start /wait before the cmdlet.

Example: start /wait CloudHealthCheck.exe -MachineFQDN machine.domain.local

Exit codes are:

  • 0 - Normal, check completed and passed.
  • 1 - Failure, check completed with issues.
  • 2 - Error, check not completed with errors.

You can also use the cmdlet echo %errorlevel% to get the exit code for the last ran command.

Reports

Cloud Health Check creates folders with the name of the machine in HealthCheckDataFolder for the target machine. An .html file and a .json file are created on the machine Cloud Health Check is installed on. Health check reports are located in the HealthCheckDataFolder in %ProgramData%\Citrix\TelemetryService\HealthCheck\Data.

Reports are only created when issues exist on the target machine.

Note:

The report files are overwritten if the specified report name exists.

Alerts and basic information are stored in the .json report.

JSON report screenshot

Report codes are:

  • issueKey: a plain text description of the issue.
  • issueUuid: a unique identifying string for the issue.
  • fixRecommendation: the fix recommendation for the issue.
  • severity: indicates if the issue must be fixed. An error can indicate that the component (VDA or StoreFront) malfunctioned, and a warning indicates that the component can work but might have some potential issues.
  • issueName: the title of the issue.
  • issueDescription: a detailed description of the issue.

Verification tests

Before a health check starts, verification tests run automatically for each selected machine. These tests make sure that the requirements are met for a health check to run. If a test fails for a machine, Cloud Health Check displays a message with suggested corrective actions.

  • Cloud Health Check cannot reach this machine - Ensure that:
    • The machine is powered on.
    • The network connection is working properly. (This can include verifying that your firewall is properly configured.)
    • File and printer sharing is turned on. See the Microsoft documentation for instructions.
  • Enable PSRemoting and WinRM - You can enable PowerShell remoting and WinRM by running PowerShell as an administrator, then running the Enable-PSRemoting cmdlet. For details, see the Microsoft help for the cmdlet.
  • Cloud Health Check requires PowerShell 3.0 or later - Install PowerShell 3.0 or later on the machine, and then enable PowerShell remoting.
  • WMI is not running on the machine - Ensure that Windows Management Instrumentation (WMI) access is enabled.
  • WMI connections blocked - Enable WMI in the Windows Firewall service.

Usage data collection

When you use Cloud Health Check, Citrix uses Google Analytics to collect anonymous usage data to be used for future product features and improvements. Data collection is enabled by default.

To change usage data collection and upload, click the Settings gear in the Cloud Health Check UI. You can then choose whether to send the information by selecting Yes or No and then clicking Save.

cloud health check 13

Troubleshooting

When Cloud Health Check fails to run or any exception occurs, check the Cloud Health Check log in C:\ProgramData\Citrix\TelemetryService\CloudHealthCheck.log.

The Cloud Health Check log for each target machine is in C:\ProgramData\Citrix\TelemetryService\HealthCheck\Data\$TargetMachineFQDN\log.txt.

To enable the debug log:

Edit C:\Program Files\Citrix\CloudHealthCheck\CloudHealthCheck.exe.config, update <add name="TraceLevelSwitch" value="3" /> to <add name="TraceLevelSwitch" value="4" />, save the file and reopen Cloud Health Check.

Feedback

To leave feedback on Cloud Health Check, fill out the Citrix survey.