Install VDAs using the command line

This article applies to installing and customizing VDAs on machines with Windows operating systems.

Important:

This article describes how to issue VDA installation commands. Before beginning an installation, review Install VDAs to learn about installation considerations, installers, and what you specify during installation.

Citrix provides sample scripts to install, remove, or upgrade VDAs. For details, see Install VDAs using scripts.

Install a VDA

To install a VDA (and see command execution progress and return values), you must have elevated administrative privileges or use Run as administrator.

  1. On the machine where you’re installing the VDA, sign to Citrix Cloud.
  2. In the upper left menu, select My Services > Virtual Apps and Desktops.
  3. On the upper right side, click Downloads and select Download VDA from the drop-down. You are redirected to the VDA download page. Find the VDA installer you want and click Download File.
  4. After the download completes, run its name. Use the options described in this article.

    • For the Server OS Virtual Delivery Agent, run VDAServerSetup.exe

    • For the Desktop OS Virtual Delivery Agent, run VDAWorkstationSetup.exe

    • For the Desktop OS Core Services Virtual Delivery Agent, run VDAWorkstationCoreSetup.exe

To extract the files before installing them, use /extract with the absolute path, for example .\VDAWorkstationCoreSetup.exe /extract %temp%\CitrixVDAInstallMedia. (The directory must exist. Otherwise, the extract fails.) Then in a separate command, run VDAWorkstationCoreSetup.exe from the directory containing the extracted content (in the example above, CitrixVDAInstallMedia). Use the valid options listed in this article.

Command-line options to install a VDA

The following options are valid with one or more of the commands: VDAServerSetup.exe, VDAWorkstationSetup.exe, and VDAWorkstationCoreSetup.exe.

  • /baseimage

    This technology is deprecated. Valid only when installing a VDA for Desktop OS on a VM. Enables the use of Personal vDisks with a master image.

    This option is not valid when using the VDAWorkstationCoreSetup.exe installer.

  • /components component[,component]

    Comma-separated list of components to install or remove. Valid values are:

    • VDA: Virtual Delivery Agent

    • PLUGINS: Citrix Workspace app for Windows

    To install the VDA and Citrix Workspace app, specify /components vda,plugins.

    This option is not valid when using the VDAWorkstationCoreSetup.exe installer. That installer cannot install Citrix Workspace app.

  • /controllers “controller [controller] […]”

    Space-separated FQDNs of Citrix Cloud Connectors with which the VDA can communicate, enclosed in quotation marks. Do not specify both the /site_guid and /controllers options.

  • /disableexperiencemetrics

    Prevents the automatic upload of analytics collected during installation, upgrade, or removal to Citrix.

  • /enable_framehawk_port

    Opens the UDP ports used by Framehawk. Default = false

  • /enable_hdx_ports

    Opens ports in the Windows firewall required by the Cloud Connector and enabled features (except Windows Remote Assistance), if the Windows Firewall Service is detected, even if the firewall is not enabled. If you are using a different firewall or no firewall, you must configure the firewall manually. For port information, see Network ports.

    To open the UDP ports that HDX adaptive transport uses to communicate with the Controller, specify the /enable_hdx_udp_ports option, in addition to the /enable_hdx_ports option.

  • /enable_hdx_udp_ports

    Opens UDP ports in the Windows firewall that are required by HDX adaptive transport, if the Windows Firewall Service is detected, even if the firewall is not enabled. If you are using a different firewall or no firewall, you must configure the firewall manually. For port information, see Network ports.

    To open additional ports that the VDA uses to communicate with the Controller and enabled features, specify the /enable_hdx_ports option, in addition to the /enable_hdx_udp_ports option.

  • /enable_real_time_transport

    Enables or disables use of UDP for audio packets (Real-Time Audio Transport for audio). Enabling this feature can improve audio performance. Include the /enable_hdx_ports option if you want the UDP ports opened automatically when the Windows Firewall Service is detected.

  • /enable_remote_assistance

    Enables the shadowing feature in Windows Remote Assistance for use with the monitoring functions of the Citrix Cloud Director component. If you specify this option, Windows Remote Assistance opens the dynamic ports in the firewall.

  • /exclude “<component>”[,”<component>”]

    Prevents installation of one or more comma-separated optional components, each enclosed in quotation marks. For example, installing or upgrading a VDA on an image that is not managed by MCS does not require the Machine Identity Service component. Valid values are:

    • AppDisks VDA Plug-in
    • Personal vDisk
    • Machine Identity Service
    • Citrix User Profile Manager
    • Citrix User Profile Manager WMI Plugin
    • Citrix Universal Print Client
    • Citrix Telemetry Service
    • Citrix Personalization for App-V - VDA
    • Citrix Supportability Tools
    • Smart Tools Agent
    • Citrix Files for Windows

    Excluding Citrix Profile management from the installation (using the /exclude “Citrix User Profile Manager” option) affects monitoring and troubleshooting of VDAs with the Citrix Cloud Director component. On the User details and EndPoint pages, 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.

    If you plan to use MCS to provision VMs, do not exclude the Machine Identity Service.

    If you specify both /exclude and /includeadditional with the same additional component name, the component is not installed.

    This option is not valid when using the VDAWorkstationCoreSetup.exe installer. That installer automatically excludes many of these items.

  • /h or /help

    Displays command help.

  • /hdxflashv2only

    Prevents installation of Flash redirection legacy binaries, for enhanced security.

    This option is not available in the graphical interface.

  • /includeadditional

    Includes installation of one or more comma-separated optional components, each enclosed in quotation marks. This option can be helpful when you are creating a Remote PC Access deployment, and want to install additional components that are not included by default. Valid values are:

    • Personal vDisk
    • Citrix User Profile Manager
    • Citrix User Profile Manager WMI Plugin
    • Citrix Universal Print Client
    • Citrix Telemetry Service
    • Citrix Personalization for App-V - VDA
    • Citrix Supportability Tools
    • Smart Tools Agent
    • Citrix Files for Windows

    If you specify both /exclude and /includeadditional with the same additional component name, that component is not installed.

  • /installdir <directory>

    Existing empty directory where components will be installed. Default = c:\Program Files\Citrix.

  • /logpath <path>

    Log file location. The specified folder must exist. The installer does not create it. Default = “%TEMP%\Citrix\XenDesktop Installer”

    This option is not available in the graphical interface.

  • /masterimage

    Valid only when installing a VDA on a VM. Sets up the VDA as a master image. This option is equivalent to /mastermcsimage.

    This option is not valid when using the VDAWorkstationCoreSetup.exe installer.

  • /mastermcsimage

    Specifies that this machine will be used as a master image with Machine Creation Services to provision VMs.

  • /masterpvsimage

    Specifies that this machine will be used as a master image with either Citrix Provisioning or a third-party provisioning tool (such as Microsoft System Center Configuration Manager) to provision VMs.

  • /no_mediafoundation_ack

    Acknowledges that Microsoft Media Foundation is not installed, and several HDX multimedia features will not be installed and will not work. If this option is omitted and Media Foundation is not installed, the VDA installation fails. Most supported Windows editions come with Media Foundation already installed, with the exception of N editions.

  • /nodesktopexperience

    Valid only when installing a VDA for Server OS. Prevents enabling of the Enhanced Desktop Experience feature. This feature is also controlled with the Enhanced Desktop Experience Citrix policy setting.

  • /noreboot

    Prevents a restart after installation. The VDA cannot be used until after a restart.

  • /noresume

    By default, when a machine restart is needed during an installation, the installer resumes automatically after the restart completes. To override the default, specify /noresume. This can be helpful if you must re-mount the media or want to capture information during an automated installation.

  • /optimize

    Valid only when installing a VDA on a VM. Enables optimization for VDAs running in a VM on a hypervisor. VM optimization includes disabling offline files, disabling background defragmentation, and reducing event log size. Do not specify this option for Remote PC Access deployments. For more information, see CTX125874.

  • /portnumber port

    Valid only when the /reconfig option is specified. Port number to enable for communications between the VDA and the Controller. The previously configured port is disabled, unless it is port 80.

  • /quiet or /passive

    No user interface appears during the installation. The only evidence of the installation and configuration process is in Windows Task Manager. If this option is omitted, the graphical interface launches.

  • /reconfigure

    Customizes previously configured VDA settings when used with the /portnumber, /controllers, or /enable_hdx_ports options. If you specify this option without also specifying the /quiet option, the graphical interface for customizing the VDA launches.

  • /remotepc

    Valid only for Remote PC Access deployments (desktop OS) or brokered connections (server OS). Excludes installation of the following components:

    • Citrix Personalization for App-V
    • Citrix User Profile Manager
    • Citrix User Profile Manager WMI Plugin
    • Machine Identity Service
    • Personal vDisk
    • Citrix Supportability Tools
    • Citrix Files for Windows

    This option is not valid when using the VDAWorkstationCoreSetup.exe installer. That installer automatically excludes installation of these components.

  • /remove

    Removes the components specified with the /components option.

  • /removeall

    Removes all installed VDA components.

  • /sendexperiencemetrics

    Automatically sends analytics collected during the installation, upgrade, or removal to Citrix. If this option is omitted (or the /disableexperiencemetrics option is specified), the analytics are collected locally, but not sent automatically.

  • /servervdi

    Installs a VDA for Desktop OS on a supported Windows server. Omit this option when installing a VDA for Server OS on a Windows server. Before using this option, see Server VDI.

    This option is not available in the graphical interface.

  • /site_guid guid

    Globally Unique Identifier of the site Active Directory Organizational Unit (OU). This associates a virtual desktop with a Site when you are using Active Directory for discovery (auto-update is the recommended and default discovery method). The site GUID is a site property displayed in Studio. Do not specify both the /site_guid and /controllers options.

  • /tempdir directory

    Directory to hold temporary files during installation. Default = c:\Windows\Temp.

    This option is not available in the graphical interface.

  • /virtualmachine

    Valid only when installing a VDA on a VM. Overrides detection by the installer of a physical machine, where BIOS information passed to VMs makes them appear as physical machines.

    This option is not available in the graphical interface.

Examples: Install a VDA

The following command installs a VDA on a server OS. The VDA will be used as a master image.

VDAServerSetup.exe /quiet /controllers "Contr-East.domain.com" /enable_hdx_ports /masterimge

The following command installs a Core Services VDA on a Desktop OS for use in a Remote PC Access or VDI deployment. Citrix Workspace app and other non-core services are not installed. The address of a Cloud Connector is specified, and ports in the Windows Firewall Service will be opened automatically. The administrator will handle restarts.

VDAWorkstationCoreSetup .exe /quiet /controllers "Contr-East.domain.com" /enable_hdx_ports /noreboot

Customize a VDA using the command line

After you install a VDA, you can customize several settings. Run XenDesktopVDASetup.exe, using one or more of the following options.

  • /reconfigure (required when customizing a VDA)
  • /h or /help
  • /quiet
  • /noreboot
  • /controllers
  • /portnumber port
  • /enable_hdx_ports

Where to go next

Create machine catalogs

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