Citrix Cloud

Cloud Connector Installation

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 download or install the Cloud Connector on machines that belong to other Citrix product deployments (for example, Delivery Controllers in a 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.
  • After installation, do not move the machine hosting the Cloud Connector into a different domain. If you need to join the machine to a different domain, uninstall the Cloud Connector and then reinstall it after the machine is joined to the different domain.
  • After installation, keep all Cloud Connectors powered on continuously to ensure an always-on connection to Citrix Cloud.

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.

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

  5. Repeat these steps on each machine you want to use for Cloud Connectors.

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

  1. Right-click 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.
  2. When prompted, sign in to Citrix Cloud.
  3. To install and configure the Cloud Connector, follow the wizard instructions. When the installation finishes, the installer performs a final connectivity check to verify communication between the Cloud Connector and Citrix Cloud.
  4. Repeat these steps on other machines you want to use as Citrix Cloud Connectors. For high availability, Citrix recommends that you install at least two Cloud Connectors for every resource location.

Citrix Cloud displays the newly installed Cloud Connector on the Connectors page for your resource location.

New Resource Location with a Connector

New Resource Location with two Connectors

After installation, Citrix Cloud also registers your domain in Identity and Access Management > Domains. For more information, see Identity and access management.

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 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.

A sample configuration file:

{
"customerName": "*CustomerID*",
"clientId": "*ClientID*",
"clientSecret": "*ClientSecret*",
"resourceLocationId": "*ResourceLocationId*",
"acceptTermsOfService": "true"
}

A sample command line that installs using the parameter file:

CWCConnector.exe /q /ParametersFilePath:c:\cwcconnector_install_params.json

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.

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. Set up an identity provider to authenticate your workspace subscribers. You can change the default Citrix identity provider to your Active Directory or other identity providers in the **Identity and Access Management” console. For more information, visit 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 could 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 Cloud Gateway
  • 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 web site.

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