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

• System requirements: To prepare the machines for hosting the Cloud Connector.
• Antivirus Exclusions section of the Endpoint Security and Antivirus Best Practices Tech Zone article: Provides guidelines to help you determine the appropriate balance between security and performance for the Cloud Connectors in your environment. Citrix strongly recommends reviewing these guidelines with your organization’s antivirus and security teams, and performing rigorous lab-based testing before applying them to a production environment.
• System and Connectivity Requirements: To ensure all machines hosting the Cloud Connector can communicate with Citrix Cloud.
• Cloud Connector Proxy and Firewall Configuration: If you’re installing the Cloud Connector in an environment that has a web proxy or strict firewall rules.
• Scale and size considerations for Cloud Connectors: Provides details of tested maximum capacities and best practice recommendations for configuring machines to host the Cloud Connector.

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

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.

   

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

   

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.

   

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

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. (Optional) If required, click Configure proxy to add a proxy server. You are prompted to add the proxy information.
3. Click Sign in and install to sign in to Citrix Cloud.
4. 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.
5. 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.

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

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.

A sample configuration file:

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

A sample command line that installs using the parameter file:

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

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