Product documentation
Citrix Cloud
View PDF

Cloud Connector Installation

September 12, 2024
Contributed by: 
C C

You can install the Cloud Connector software interactively or using the command line.

The installation occurs with the privileges of the user who begins the install. The Cloud Connector requires access to the cloud to:

  • Authenticate the user that performs the installation
  • Validate the installer’s permissions
  • Download and configure the Cloud Connector services

Information to review before installation

Installation considerations and guidance

  • Don’t install the Cloud Connector on an Active Directory domain controller or any other machine critical to your resource location infrastructure. Regular maintenance on the Cloud Connector performs machine operations that cause an outage to these additional resources.
  • Don’t download or install other Citrix products on the machines hosting the Cloud Connector.
  • Don’t upgrade individual components of the Cloud Connector separately.
  • Don’t download or install the Cloud Connector on machines that belong to other Citrix product deployments (for example, delivery controllers in an on-premises Citrix Virtual Apps and Desktops deployment).
  • Don’t upgrade a previously installed Cloud Connector with a newer version. Instead, uninstall the old Cloud Connector and then install the new one.
  • The Cloud Connector installer is downloaded from Citrix Cloud. So, your browser must allow downloading executable files.
  • If you are using the graphical installer, you must have a browser installed and the default system browser set.

Post-deployment guidance

After installation, keep all Cloud Connectors powered on continuously to ensure an always-on connection to Citrix Cloud.

Renaming machines

After installation, don’t rename the machine hosting the Cloud Connector. If you need to change the server name later on, perform the following tasks:

  1. Remove the machine from the resource location:
    1. From the Citrix Cloud menu, select Resource Locations.
    2. Locate the resource location you want to manage and then select the Cloud Connectors tile.
    3. Locate the machine you want to manage and then click the ellipsis menu. Select Remove Connector.
  2. Uninstall the Cloud Connector software.
  3. Rename the machine.
  4. Install the latest version of the Cloud Connector software, as described in this article.

Moving machines to a different domain

After installation, don’t move the machine hosting the Cloud Connector into a different domain. If you need to join the machine to a different domain later on, perform the following tasks:

  1. Remove the machine from the resource location.
  2. Uninstall the Cloud Connector software.
  3. Unjoin the machine from its current domain and rejoin the machine to the new domain.
  4. Install the latest version of the Cloud Connector software, as described in this article.

Considerations for cloned machines

Each machine hosting the Cloud Connector must have a unique SID and connector ID so that Citrix Cloud can communicate reliably with the machines in your resource location. If you intend to host the Cloud Connector on multiple machines in your resource location and you want to use cloned machines, perform the following steps:

  1. Prepare the machine template according to the requirements for your environment.
  2. Provision the number of machines that you intend to use as Cloud Connectors.
  3. Install the Cloud Connector on each machine, either manually or using the silent installation mode.

Installing the Cloud Connector on a machine template (before cloning) isn’t supported. If you clone a machine with the Cloud Connector installed, the Cloud Connector services won’t run and the machine can’t connect to Citrix Cloud.

Considerations for services

The installation steps in this article describe the process for deploying Cloud Connectors, regardless of the service for which they are used.

When deploying Cloud Connectors for Citrix DaaS, verify that the AD domains where the connectors reside are active and are not showing as “unused” in the Citrix Cloud console. If you specify an unused domain during machine catalog setup in Citrix DaaS, an error might occur. For more information, see Add a resource type or activate an unused domain in Citrix Cloud in the Citrix DaaS product documentation.

For additional considerations for other services, consult the service’s documentation.

Default resource locations

If you have no resource locations in your Citrix Cloud account and you install Cloud Connectors in your domain, the resource location that Citrix Cloud creates becomes the default resource location. You can have only one default resource location in your account. If needed, you can create additional resource locations in Citrix Cloud and then select the one you want when you install Cloud Connectors in other domains.

Alternatively, you can first create the resource locations you need in the console, before you install Cloud Connectors in your domains. The Cloud Connector installer prompts you to select the resource location you want during installation.

Interactive installation

You can download and install Cloud Connectors using the graphical installer interface. Before you do this, you must create one or more resource locations in the Citrix Cloud management console to deploy Cloud Connectors on. For more information on resource locations, see Location of resources.

To create a resource location

  1. Sign in as a Windows administrator to the machine you intend to install Citrix Cloud Connectors on.
  2. Visit https://citrix.cloud.com and sign in to your administrator account.

  3. In the Citrix Cloud console, navigate to Resource Locations from the main menu, or select Edit or Add New under Resource Locations at the top of the page.

    Resource Locations

  4. In Resource Locations, select + Resource Location at the top of the page and save a new, meaningful name for it.

    Add new resource location

Download the Citrix Cloud Connector software

  1. Locate the resource location you want to manage and select + Cloud Connectors.

    New Resource Location with no Connectors

  2. Select Download in the window that opens. Save the cwcconnector.exe file to a local file location on your connector machine. Add a Cloud Connector window

Install the Citrix Cloud Connector software

Prerequisites

  1. Right-click on the cwcconnector.exe installer file and select Run as administrator. The installer performs an initial connectivity check to ensure you can connect to Citrix Cloud before installing the Cloud Connector.

  2. Click Manage to update Proxy Server.

Install Cloud Connector

Note:

There is only one proxy server supported in both the legacy and new UI due to a limitation in Microsoft WinHTTP. For more information, see AutoProxy Issues in WinHTTP

  1. Click Advanced Connectivity Check to run a verbose check to ensure that the basic connectivity requirements for Connector installation are met on the machine.

    Advanced Connectivity Check

Initial upgrade and tests

  1. After updating the Proxy Server and checking the Advanced Connectivity Check, click Install Cloud Connector.

  2. On the Sign-in page, click Sign in and Install

    Cloud Connector login

  3. The Citrix Cloud Connectivity Test window appears and the status of the Initial upgrade and tests are displayed along with Event logs.

    Initial tests in progress

  4. Click View logs to open the directory (C:\ProgramData\Citrix\WorkspaceCloud\InstallLogs) that includes all connectivity check debug logs.

  5. Once the Initial upgrade and tests are completed, you’ll see the Citrix Cloud Connectivity Test is Successful as shown in the following image. The connectivity check results are displayed in the Event log box after the first upgrade.

    Initial tests complete

Cloud Connector check

The new UI displays the results of connectivity checks, detailing the specific checks that have been conducted. It includes a copy button for duplicating this information as needed. Additionally, there is a dedicated button to access the path where debug log files are stored C:\ProgramData\Citrix\WorkspaceCloud\Logs\Plugins\ConnectivityCheck. These logs generated by the connectivity check plugin can be used to troubleshoot and analyze issues encountered during checks.

Enable Active Directory misconfiguration resource location check

The Active Directory misconfiguration check is disabled by default.

Active Directory misconfiguration check disabled

To enable this feature, admins need to rerun the installer again and proceed to configure it manually.

Active Directory misconfiguration check enabled

Within the installer interface, navigate to Advanced Connectivity Check, select Active Directory Check and then click Edit, where you can enable the feature by selecting the corresponding checkbox and providing your Citrix Cloud service principal ID and secret.

Active Directory check config

This ensures that the Active Directory check is properly configured to monitor and address any misconfigurations effectively.

Enable Packet Capture

On the Advanced Connectivity Check screen of the new installer UI, the Enable packet capture checkbox is added. For more information on the legal notice regarding the packet collection and the types of the data captured, click the Learn more link.

Connectivity ad checks

Connectivity Check tool

The Connectivity Check tool will now feature two new buttons, Clear results and Run tests, both will be disabled while a connectivity check is in progress. Connectivity checks will continue to start automatically, without packet capture. Once the initial check is complete, users can select the new Enable packet capture checkbox and then click Run tests to rerun the connectivity checks with packet capture enabled. Optionally, users can click Clear results before running the tests to reset the results.

Connectivity tests

Once the initial connectivity check has completed, the new UI elements are enabled.

Testing service connectivity

When you start a new connectivity check with packet capture enabled, a new log entry indicates that the packet capture has begun.

Enable packet capture

Once the connectivity check with packet capture is complete, a new log entry will be created, providing the location where the packet capture has been saved.

Packet capture log

The Connectivity Check tool continues to start automatically after the Cloud Connector installation and initiates a connectivity check as it did previously.

Activate unused domains

If you’re creating resource locations and deploying Cloud Connectors for Citrix DaaS, verify that the AD domains that you’re using with Citrix DaaS are active and are not considered unused. If you specify an unused domain when setting up machine catalogs in Citrix DaaS, an error could occur.

For more information, see Add a resource type or activate an unused domain in Citrix Cloud in the Citrix DaaS product documentation.

Create additional resource locations

  1. From the Citrix Cloud management console, click the menu button and select Resource Locations.
  2. Click + Resource Location and enter a meaningful name.
  3. Click Save. Citrix Cloud displays a tile for the new resource location.
  4. Click Cloud Connectors and then click Download to acquire the Cloud Connector software.
  5. On each prepared machine, install the Cloud Connector software using either the installation wizard or the command-line installation. Citrix Cloud prompts you to select the resource location you want to associate with the Cloud Connector.

Installation with multiple customers and existing resource locations

If you’re an administrator for multiple customer accounts, Citrix Cloud prompts you to select the customer account you want to associate with the Cloud Connector.

If your customer account has multiple resource locations already, Citrix Cloud prompts you to select the resource location you want to associate with the Cloud Connector.

Command-line installation

Silent or automated installation is supported. However, using the same installer for repeated installations isn’t recommended. Download a new Cloud Connector from the Resource Locations page in the Citrix Cloud console.

Requirements

To use the command line installation with Citrix Cloud, you need to supply the following information:

  • The customer ID of the Citrix Cloud account for which you are installing the Cloud Connector. This ID appears at the top of the API Access tab in Identity and Access Management.
  • The client ID and secret of the secure API client you want to use to install the Cloud Connector. To acquire these values, you must first create a secure client. The client ID and secret ensures that your access to the Citrix Cloud API is secured appropriately. When you create a secure client, the client operates with the same level of administrator permissions that you have. To install a Cloud Connector, you must use a secure client which was created by a Full Access administrator, which means the secure client that also has full access permissions.
  • The resource location ID for the resource location that you want to associate with the Cloud Connector. To retrieve this value, select the ID button located beneath the resource location name on the Resource Locations page. If you don’t supply this value, Citrix Cloud uses the ID of the default resource location.

Create a secure client

When creating a secure client, Citrix Cloud generates a unique client ID and secret. You must supply these values when you invoke the API through the command line.

  1. From the Citrix Cloud menu, select Identity and Access Management and then select API Access.
  2. From the Secure Clients tab, enter a name for your client and select Create Client. Citrix Cloud generates and displays a client ID and secret for the secure client.
  3. Select Download to download the client ID and secret as a CSV file and store it in a secure location. Alternatively, select Copy to manually acquire each value. When finished, select Close to return to the console.

Supported parameters

To ensure the security of the secure client details, a JSON configuration file must be provided to the installer. This file must be deleted after the installation has completed. Supported values for the configuration file are:

  • customerName Required. The customer ID shown on the API Access page in the Citrix Cloud console (within Identity and Access Management).
  • clientId Required. The secure client ID an administrator can create, located on the API Access page.
  • clientSecret Required. The secure client secret that can be downloaded after the secure client is created. Located on the API Access page.
  • resourceLocationId Recommended. The unique identifier for an existing resource location. Select the ID button to retrieve the resource location ID on the Resource Locations page in the Citrix Cloud console. If no value is specified, Citrix Cloud uses the ID of the first resource location in the account.
  • acceptTermsOfService Required. Must be set to true.

Sample configuration file 

{
"customerName": "*CustomerID*",
"clientId": "*ClientID*",
"clientSecret": "*ClientSecret*",
"resourceLocationId": "*ResourceLocationId*",
"acceptTermsOfService": "true"
}
<!--NeedCopy-->

Sample command

The following command silently installs the Cloud Connector software using a JSON configuration file:

CWCConnector.exe /q /ParametersFilePath:c:\cwcconnector_install_params.json
<!--NeedCopy-->

Use /q to specify a silent install.

Use Start /Wait CWCConnector.exe /ParametersFilePath:value to examine a potential error code in the case of a failure. You can use the standard mechanism of running echo %ErrorLevel% after the installation completes.

Note:

Using parameters to pass the Client ID and Client Secret is no longer supported, the configuration file must be used for automated installations.

HTTPS Configuration

To allow StoreFront and NetScaler Gateway appliances to security connect to the cloud connector, it is strongly recommended that you enable HTTPS. This requires an SSL certificate. This can be generated from a 3rd party or internal certificate authority, as long as the StoreFront and gateway servers trust the root certificate.

To enable HTTPS:

  1. Open the Certificates MMC snap-in.

  2. Install your certificate into the Personal Certificates store.

  3. Open the certificate, go to the Details tab and take a note of the Thumbprint, ignoring any spaces.

    Screenshot of certificate details

  4. Determine the Service GUID of the Citrix Remote Broker Provider. You can do this using PowerShell, for example:

    PS C:\Users\user> WmiObject -Class Win32_Product | Where-Object Name -match 'Citrix Remote Broker Provider'

IdentifyingNumber : {253EDCD0-D52B-4A95-9C20-2AECD623EB6B}
Name              : Citrix Remote Broker Provider - x64
Vendor            : Citrix Systems, Inc.
Version           : 7.42.26225.32639
Caption           : Citrix Remote Broker Provider - x64
<!--NeedCopy-->

    Make a note of the returned IdentifyingNumber GUID, including the hyphens.

  5. Determine which IP address to bind the certificate to. Normally you can use IP address of 0.0.0.0 to apply to all IPv4 addresses. If IPv6 is enabled then use [::] to apply to all IPv6 addresses. If you only want to apply the change to a specific network adapter then make a note of the IP address of the network adapter.

  6. In an elevated command prompt run

    netsh http add sslcert ipport=<IP address>:<Port number> certhash=<Certificate Hash Number> appid={<Citrix Broker Service GUID>}
<!--NeedCopy-->

    For example:

    C:\> netsh http add sslcert ipport=0:0:0:0:443 certhash=BC96F958848639FD101A793B87915D5F2829B0B6 appid={253EDCD0-D52B-4A95-9C20-2AECD623EB6B}

SSL Certificate successfully added
<!--NeedCopy-->

  7. To disable HTTP, in the registry go to HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\DesktopServer and create a DWORD with name XMLServicesEnableNonSSL and value 0.

Next steps

  1. Set up the Citrix Cloud Connector update schedule. For information on Citrix Cloud Connector updates and managing update schedules, visit Connector updates.
  2. If you are using StoreFront, configure StoreFront so it can use the connector to reach DaaS to enumerate and launch resources. If this is the first connector in a new DaaS deployment then create a new resource feed. If this is an additional connector then it is recommended for resiliency that you add all Cloud Connectors to the server list for your existing DaaS resource feed. For more information, see Manage the resources made available in stores.
  3. If you are using StoreFront with a NetScaler gateway, you can use the connector to reach the Citrix Cloud Secure Ticket Authority (STA). For more information, see Configure Citrix Gateways.
  4. If this is the first connector on a particular Active Directory domain then you can connect that domain to Citrix Cloud. For more information, see To connect your Active Directory to Citrix Cloud.

Troubleshooting installation issues

This section details some ways of diagnosing and fixing problems you might encounter during installation. For more guidance about troubleshooting installation issues, see the Citrix Cloud Connector Troubleshooting Guide.

Installation logs

You can troubleshoot issues encountered with installation by first consulting the available log files.

Events that occurred during installation are available in the Windows Event Viewer. You can also review Cloud Connector installation logs, which are located at %LOCALAPPDATA%\Temp\CitrixLogs\CloudServicesSetup. Logs are also added to %ProgramData%\Citrix\WorkspaceCloud\InstallLogs after installation.

Exit codes

The following exit codes might be returned depending on the success or failure of the installation process:

  • 1603 - An unexpected error occurred
  • 2 - A prerequisite check failed
  • 0 - Installation completed successfully

Installation error

If you install the Citrix Cloud Connector software by double-clicking the installer, you might receive the following error message:

Can't reach this page.

This error can occur even if you are logged in to the machine as an administrator to install the Citrix Cloud Connector. To avoid this error, run the Citrix Cloud Connector software as an administrator by right-clicking the installer and selecting Run as administrator.

Connectivity failures

To ensure that the Cloud Connector can communicate with Citrix Cloud, confirm that the following Citrix services are in a Started state:

  • Citrix Cloud AD Provider
  • Citrix Cloud Agent Logger
  • Citrix Cloud Agent System
  • Citrix Cloud Agent Watchdog
  • Citrix Cloud Credential Provider
  • Citrix Config Synchronizer Service
  • Citrix High Availability Service
  • Citrix NetScaler CloudGateway
  • Citrix Remote Broker Provider
  • Citrix Remote HCL Server
  • Citrix Session Manager Proxy

For more information about these services, see Installed Services.

If you continue to experience connectivity failures, use the Cloud Connector Connectivity Check Utility available from the Citrix Support Knowledge Center. For more information, see CTX260337 on the Knowledge Center website.

The tool can be used to perform the following tasks:

  • Test whether Citrix Cloud and its related services are reachable.
  • Check for commonly misconfigured settings.
  • Configure proxy settings on the Citrix Cloud Connector.

For more information on how to resolve a failed connectivity check, see CTX224133: Cloud Connector Connectivity Check Failed.

Cloud Connector Installation
September 12, 2024
Contributed by: 
C C
September 12, 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.