Install VDAs

This article begins with an description of VDAs and the available VDA installers. The rest of the article describes the steps in the VDA installation wizard. Command-line equivalents are provided. For details, see Install VDAs using the command line.

About VDAs

The Citrix Virtual Apps and Desktops service article describes what VDAs are and what they do. Here’s more helpful information.

  • Analytics collection: Analytics are collected automatically when you install (or upgrade) components. By default, that data is uploaded to Citrix automatically when the installation completes. Also, when you install components, you are automatically enrolled in the Citrix Customer Experience Improvement Program (CEIP), which uploads anonymous data. For information about these programs, see the relevant VDA information in Citrix Insight Services.
  • Citrix Workspace app: Citrix Workspace app for Windows is not installed by default when you install a VDA. You or your users can download and install (and upgrade) Citrix Workspace app for Windows and other Citrix Workspace apps from the Citrix website. Alternatively, you can make those Citrix Workspace apps available from the Workspace or a StoreFront server.
  • Print Spooler Service: The Print Spooler Service is enabled by default on supported Windows Servers. If you disable this service, you cannot successfully install a VDA for Server OS, so ensure that this service is enabled before installing a VDA.
  • Microsoft Media Foundation: Most supported Windows editions come with Media Foundation already installed. If the machine on which you’re installing a VDA does not have Microsoft Media Foundation (such as N editions), several multimedia features will not be installed and will not work. You can acknowledge the limitation, or end the VDA installation and restart it later, after installing Media Foundation. In the graphical interface, this choice is presented in a message. In the command line, you can use the /no_mediafoundation_ack option to acknowledge the limitation. If Media Foundation is not present on the VDA, these multimedia features do not work:
    • Flash Redirection
    • Windows Media Redirection
    • HTML5 Video Redirection
    • HDX Realtime Webcam Redirection
  • Local user group: When you install the VDA, a new local user group called Direct Access Users is created automatically. On a VDA for Desktop OS, this group applies only to RDP connections. On a VDA for Server OS, this group applies to ICA and RDP connections.
  • Cloud Connector address requirement: The VDA must have at least one valid Cloud Connector address (in the same resource location) with which to communicate. Otherwise, sessions cannot be established. You specify Cloud Connector addresses when you install the VDA. For information about other methods to specify Cloud Connector addresses where VDAs can register, see VDA registration.
  • Operating system considerations:
    • Review the System requirements for supported platforms, operating systems, and versions.
    • Ensure that each operating system maintains the latest updates.
    • Ensure that VDAs have synchronized system clocks. The Kerberos infrastructure that secures communication between the machines requires synchronization.
    • Optimization guidance for Windows 10 machines is available in CTX216252.
    • If you try to install (or upgrade to) a Windows VDA on an OS that is not supported for that VDA version, a message describes your options. For example, if you attempt to install the latest VDA on a Windows 7 machine, a message guides you to CTX139030. For more information, see Earlier operating systems.

VDA supportability tools

Each VDA installer includes a supportability MSI that contains Citrix tools for checking the VDA performance, such as its overall health and the quality of connections. Enable or disable installation of this MSI on the Additional Components page of the VDA installer’s graphical interface. From the command line, you can disable installation with the /exclude “Citrix Supportability Tools” option.

By default, the supportability MSI is installed in c:\Program Files (x86)\Citrix\Supportability Tools. You can change this location on the Components page of the VDA installer’s graphical interface, or with the /installdir command-line option. Keep in mind that changing the location changes it for all installed VDA components, not just the supportability tools.

Current tools in the supportability MSI:

  • Citrix Health Assistant: For details, see CTX207624.
  • VDA Cleanup Utility: For details, see CTX209255.

If you do not install the tools when you install the VDA, the CTX article contains a link to the current download package.

Restarts during VDA installation

A restart is required at the end of the VDA installation. That restart occurs automatically by default.

To minimize the number of restarts needed during VDA installation:

  • Ensure that a supported .NET Framework version is installed before beginning the VDA installation.
  • For Windows Server OS machines, install and enable the RDS role services before installing the VDA.

If you do not install those prerequisites before installing the VDA:

  • If you are using the graphical interface or the command line interface without the /noreboot option, the machine restarts automatically after installing the prerequisite.
  • If you are using the command line interface with the /noreboot option, you must initiate the restart.

After each restart, the VDA installation continues. (If you’re installing from the command line, you can prevent this with the /noresume option.)

NOTE:

When upgrading a VDA to version 7.17 or a later supported version, a restart occurs during the upgrade. This cannot be avoided.

VDA installers

VDA installers can be downloaded directly from the Citrix Cloud console.

By default, files in the self-extracting installers are extracted to the Temp folder. The files extracted to the Temp folder are automatically deleted after the installation completes. Alternatively, you can use the /extract command with an absolute path.

Three standalone VDA installers are available for download.

VDAServerSetup.exe

Installs a VDA for Server OS.

VDAWorkstationSetup.exe

Installs a VDA for Desktop OS.

VDAWorkstationCoreSetup.exe

Installs a VDA for Desktop OS that is optimized for Remote PC Access deployments or core VDI installations. Remote PC Access uses physical machines. Core VDI installations are VMs that are not being used as a master image. This installer deploys only the core services necessary for VDA connections. Therefore, it supports only a subset of the options that are valid with the VDAWorkstationSetup installer.

This installer does not install or contain the components used for:

  • App-V.
  • Profile management. Excluding Citrix Profile management from the installation affects Monitor displays.
  • Machine Identity Service.
  • Personal vDisk or AppDisks.
  • Citrix Workspace app for Windows.
  • Citrix Supportability Tools.
  • Citrix Files for Windows.

This installer dos not install or contain a Citrix Workspace app for Windows.

Using VDAWorkstationCoreSetup.exe is equivalent to using the VDAWorkstationSetup installer to install a Desktop OS VDA and either:

  • In the graphical interface: Selecting the Remote PC Access option on the Environment page.
  • In the command line interface: Specifying the /remotepc option.
  • In the command line interface: Specifying /components vda and /exclude “Citrix Personalization for App-V - VDA” “Personal vDisk” “Machine Identity Service” “Citrix User Profile Manager” “Citrix User Profile Manager WMI Plugin” “Citrix Citrix Supportability Tools” “Citrix Files for Windows”.

If you originally install a VDA with the VDAWorkstationCoreSetup.exe installer and later upgrade that VDA using the VDAWorkstationSetup.exe installer, you have the option to install the omitted components/features.

Install a VDA

Step 1. Download the product software and launch the wizard

  1. On the machine where you’re installing the VDA, sign in to Citrix Cloud.
  2. In the upper left menu, select select My Services > Virtual Apps and Desktops.
  3. On the right side, click Downloads and select Download VDA. You are redirected to the VDA download page. Find the VDA installer you want and then click Download File.
  4. After the download completes, right-click the file and select Run as administrator. The installation wizard launches.

As an alternative to steps 1-3, you can download the VDA directly from the Citrix download page.

Step 2. Specify how the VDA will be used

Environment image

On the Environment page, specify how you plan to use the VDA, indicating whether or not you’ll use this machine as a master image to provision additional machines. The option you choose affects which Citrix provisioning tools are installed automatically (if any), and the default values on the Additional Components page of the VDA installer. Several MSIs (provisioning and other) are installed automatically when you install a VDA. The only way to prevent their installation is with the /exclude option in a command-line installation.

Choose one of the following:

  • Create a master MCS image: Select this option to install a VDA on a VM master image, if you plan to use Machine Creation Services to provision VMs. This is the default option. Command-line option: /mastermcsimage or /masterimage
  • Create a master image using Citrix Provisioning or third-party provisioning tools: Select this option to install a VDA on a VM master image, if you plan to use either Citrix Provisioning or third-party provisioning tools (such as Microsoft System Center Configuration Manager) to provision VMs. Command-line option: /masterpvsimage
  • (Appears only on server OS machines) Enable brokered connections to a server: Select this option to install a VDA on a physical or virtual machine that will not be used as a master image to provision other machines. Command-line option: /remotepc
  • (Appears only on desktop OS machines) Enable Remote PC Access: Select this option to install a VDA on a physical machine for use with Remote PC Access. Command-line option: /remotepc

Click Next.

This page does not appear:

  • If you’re upgrading a VDA
  • If you are using the VDAWorkstationCoreSetup.exe installer

Step 3. Select the components to install and the installation location

Select the components to install and the installation location image

On the Core components page:

  • Location: By default, components are installed in C:\Program Files\Citrix. This default is fine for most deployments. If you specify a different location, that location must have execute permissions for network service. Command-line option: /installdir
  • Components: By default, Citrix Workspace app for Windows is not installed with the VDA. If you are using the VDAWorkstationCoreSetup.exe installer, Citrix Workspace app for Windows is never installed, so this check box is not displayed. Command-line option: /components vda,plugin to install the VDA and the Citrix Workspace app for Windows

Click Next.

Step 4. Install additional components

Install additional components image

The Additional Components page contains check boxes to enable or disable installation of other features and technologies with the VDA. In a command-line installation, you can use the /exclude or /includeadditional option to expressly omit or include one or more available components.

The following table indicates the default setting of items on this page. The default setting depends on the option you selected on the Environment page.

Additional Components page Environment page: “Master image with MCS” or “Master image with Citrix Provisisioning …” selected Environment page: “Enable brokered connections to server” (for server OS) or “Remote PC Access” (for desktop OS) selected
Citrix Personalization for App-V Not selected Not selected
Citrix AppDisk/Personal vDisk Not selected Not shown because it’s not valid for this use case.
Citrix Supportability tools Selected Not selected
Citrix User Profile Manager Selected Not selected
Citrix User Profile Manager WMI Plugin Selected Not selected
Citrix Files for Windows Not selected Not selected

This page does not appear if:

  • You are using the VDAWorkstationCoreSetup.exe installer. Also, the command-line options for the additional components are not valid with that installer.
  • You are upgrading a VDA and all the additional components are already installed. (If some of the additional components are already installed, the page lists only components that are not installed.)

The components list can include:

  • Citrix Personalization for App-V: Install this component if you use applications from Microsoft App-V packages. For details, see App-V.

    Command-line option: /includeadditional “Citrix Personalization for App-V – VDA” to enable component installation, /exclude “Citrix Personalization for App-V – VDA” to prevent component installation

  • Citrix AppDisk / Personal vDisk: These technologies are deprecated. Valid only when installing a VDA for Desktop OS on a VM. Installs components used for AppDisk and Personal vDisk.

    Command-line option: /includeadditional “Personal vDisk” to enable component installation, /exclude “Personal vDisk” to prevent AppDisk and Personal vDisk component installation

  • Citrix Supportability Tools: Installs the MSI that contains Citrix supportability tools, such as the Citrix Health Assistant.

    Command-line option: /includeadditional “Citrix Supportability Tools” to enable component installation, /exclude “Citrix Supportability Tools” to prevent component installation

  • Citrix User Profile Manager: This component manages user personalization settings in user profiles. For details, see Profile Management.

    Excluding Citrix Profile management from the installation affects the monitoring and troubleshooting of VDAs in Citrix Cloud. On the User details and EndPoint pages of the Monitor tab, the Personalization panel and the Logon Duration panel fail. On the Dashboard and Trends pages, the Average Logon Duration panel display data only for machines that have Profile management installed.

    Even if you are using a third-party user profile management solution, Citrix recommends that you install and run the Citrix Profile management Service. Enabling the Citrix Profile management Service is not required.

    Command-line option: /includeadditional “Citrix User Profile Manager” to enable component installation, /exclude “Citrix User Profile Manager” to prevent component installation

  • Citrix User Profile Manager WMI Plugin: This plug-in provides Profile management runtime information in WMI (Windows Management Instrumentation) objects (for example, profile provider, profile type, size, and disk usage). WMI objects provide session information to Director.

    Command-line option: /includeadditional “Citrix User Profile Manager WMI Plugin” to enable component installation, /exclude “Citrix User Profile Manager WMI Plugin” to prevent component installation

  • Citrix Files for Windows: This component enables users to connect to their Citrix Files account. They can then interact with Citrix Files through a mapped drive in the Windows file system (without requiring a full sync of their content).

    Command-line options: /includeadditional “Citrix Files for Windows” to enable component installation, /exclude “Citrix Files for Windows” to prevent component installation

Step 5. Cloud Connector addresses

Cloud connector addresses image

On the Delivery Controller page, select Do it manually. Enter the DNS name of an installed Cloud Connector and then click Add. If you’ve installed additional Cloud Connectors in the resource location, add their DNS names.

Click Next.

Considerations:

  • The address can contain only alphanumeric characters.
  • Successful VDA registration requires that the firewall ports used to communicate with the Cloud Connector are open. That action is enabled by default on the Firewall page of the wizard.

Command-line option: /controllers

Step 6. Enable or disable features

Enable or disable features image

On the Features page, use the check boxes to enable or disable features you want to use.

  • Optimize performance: Valid only when installing a VDA on a VM, not a physical machine. When this feature is enabled (default), the optimization tool is used for VDAs running in a VM on a hypervisor. VM optimization includes disabling offline files, disabling background defragmentation, and reducing event log size. For details, see CTX125874.

    Command-line option: /optimize

    If you are using the VDAWorkstationCoreSetup.exe installer, this feature does not appear in the wizard and the command-line option is not valid. If you are using another installer in a Remote PC Access environment, disable this feature.

  • Use Windows Remote Assistance: When this feature is enabled, Windows Remote Assistance is used with the user shadowing feature of the Director component in Citrix Cloud. Windows Remote Assistance opens the dynamic ports in the firewall. (Default = disabled)

    Command-line option: /enable_remote_assistance

  • Use Real-Time Audio Transport for audio: Enable this feature if voice-over-IP is widely used in your network. The feature reduces latency and improves audio resilience over lossy networks. It allows audio data to be transmitted using RTP over UDP transport. (Default = disabled)

    Command-line option: /enable_real_time_transport

  • Framehawk: When this feature is enabled, bidirectional UDP ports 3224-3324 are opened. (Default = disabled)

    You can change the port range later with the “Framehawk display channel port range” Citrix policy setting. You must then open local firewall ports. A UDP network path must be open on any internal (VDA to Citrix Workspace app or Citrix Gateway) and external (Citrix Gateway to Citrix Workspace app) firewalls. If Citrix Gateway is deployed, Framehawk datagrams are encrypted using DTLS (default UDP port 443). For details, see the Framehawk article.

    Command-line option: /enable_framehawk_port

  • AppDisk / Personal vDisk: These technologies are deprecated. Valid only when installing a VDA for Desktop OS on a VM. This check box is available only if the Citrix AppDisk / Personal vDisk check box is selected on the Additional Components page. When this check box is enabled, AppDisks and Personal vDisks can be used.

    Command-line option: /baseimage

    If you are using the VDAWorkstationCoreSetup.exe installer, this feature does not appear in the wizard and the command-line option is not valid.

  • MCS I/O: Valid only when using MCS to provision VMs. When selected, the MCSIO write caching driver is installed. For more information, see Storage shared by hypervisors and Configure cache for temporary data.

    Command-line option: /install_mcsio_driver

    Important:

    This feature is not enabled by default (so the driver is not installed). You must install that driver to use the MCS temporary data caching feature.

Click Next.

Step 7. Firewall ports

Firewall ports image

The Firewall page indicates which ports the VDA and Cloud Connectors use to communicate with each other. By default, these ports are opened automatically if the Windows Firewall Service is running, even if the firewall is not enabled. This default setting is fine for most deployments. For port information, see Network ports.

Click Next.

Command-line option: /enable_hdx_ports

Step 8. Review prerequisites and confirm installation

Summary image

The Summary page lists what will be installed. Use the Back button to return to earlier wizard pages and change selections.

When you’re ready, click Install.

If prerequisites aren’t already installed/enabled, the machine may restart once or twice. See Prepare to install.

Step 9. Participate in Call Home

Smart tools image

On the Smart Tools page, choose whether to participate in Citrix Call Home, which is now a part of Citrix Smart Tools. If you choose to participate (the default), click Connect. When prompted, enter your Citrix account credentials.

After your credentials are validated (or if you choose not to participate), click Next.

Step 10. Complete this installation

Finish installation image

The Finish page contains green check marks for all prerequisites and components that installed and initialized successfully.

Click Finish. By default, the machine restarts automatically. (Although you can disable this automatic restart, the VDA cannot be used until the machine restarts.)

(If you are installing a VDA on individual machines (rather than a master image), repeat the steps above to install a VDA on other machines, as needed.)

Troubleshoot

In the Studio display for a Delivery Group, the “Installed VDA version” entry in the Details pane might not be the version installed on the machines. The machine’s Windows Programs and Features display shows the actual VDA version.

Customize a VDA

Later, to customize (change information for) an installed VDA:

  1. From the Windows feature for removing or changing programs, select Citrix Virtual Delivery Agent or Citrix Remote PC Access/VDI Core Services VDA. Then right-click and select Change.
  2. Select Customize Virtual Delivery Agent Settings. When the installer launches, you can change:
  • Cloud Connector addresses
  • TCP/IP port to register with the Controller (default = 80)
  • Whether to open Windows Firewall ports automatically

Where to go next

Create machine catalogs

To review the entire configuration process, see Install and configure.

Install VDAs