Install using the command line
Important:
If you’re upgrading, and your current version uses or has the Personal vDisk or AppDisks software installed, see Removing PvD, AppDisks, and unsupported hosts.
Citrix collects basic licensing data as necessary for its legitimate interests, including licensing compliance. For more information, see Citrix Licensing Data.
Introduction
This article applies to installing components on machines with Windows operating systems. For information about VDAs for Linux operating systems, see Linux Virtual Delivery Agents.
This article describes how to issue product installation commands. Before beginning any installation, review Prepare to install. That article includes descriptions of the available installers.
To see command execution progress and return values, you must be the original administrator or use Run as administrator. For more information, see the Microsoft command documentation.
As a complement to using the installation commands directly, sample scripts are provided on the product ISO that install, upgrade, or remove VDAs on machines in Active Directory. For details, see Install VDAs using scripts.
If you attempt to install or upgrade on a Windows OS version that is not supported for this Citrix Virtual Apps and Desktops version, a message guides you to information about your options. See Earlier operating systems.
For information about how Citrix reports the result of component installations, see Citrix installation return codes.
Use the full-product installer
To access the full product installer’s command-line interface:
- Download the product package from Citrix. Citrix account credentials are required to access the download site.
- Unzip the file. Optionally, burn a DVD of the ISO file.
- Log on to the server where you are installing the components, using a local administrator account.
- Insert the DVD in the drive or mount the ISO file.
-
From the
\x64\XenDesktop Setup
directory on the media, run the appropriate command.To install core components: Run
XenDesktopServerSetup.exe
, with the options listed in Command-line options for installing core components.To install a VDA: Run
XenDesktopVDASetup.exe
with the options listed in Command-line options for installing a VDA.To install StoreFront: Run
CitrixStoreFront-x64.exe
in thex64 > StoreFront
folder on the installation media.To install the Universal Print Server: Follow the guidance in Command-line options for installing a Universal Print Server.
To install the Federated Authentication Service: Citrix recommends using the graphical interface.
To install Session Recording: Follow the guidance in Session Recording.
To install Workspace Environment Management: Follow the guidance in Workspace Environment Management.
Command-line options for installing core components
The following parameter options are valid when installing core components with the XenDesktopServerSetup.exe
command. For more detail about options, see Install core components.
-
/ceipoptin ceipoptin [,ceipoptin] …
Enables collection of Call Home data and Customer Experience Improvement Program (CEIP) data. Valid values are:
-
DIAGNOSTIC
: Choose this value to enable Citrix Licensing to collect Call Home data. -
ANONYMOUS
: Choose this value to enable Citrix Licensing to collect unidentified CEIP data (which does not identify users). -
NONE
: Choose this value to disable Citrix Licensing collection of CEIP data.
For more information about Call Home data collection, see Citrix Licensing Call Home.
For more details about CEIP data collection, see Citrix Licensing Customer Experience Improvement Program.
For more details about CEIP data, see Citrix Licensing CEIP data elements.
For more details about License Server licensing data, see Citrix Licensing Data.
-
-
/components component [,component] …
Comma-separated list of components to install or remove. Valid values are:
-
CONTROLLER
: Controller -
DESKTOPSTUDIO
: Studio -
DESKTOPDIRECTOR
: Director -
LICENSESERVER
: Citrix License Server
If this option is omitted, all components are installed (or removed, if the
/remove
option is also specified).(In releases before 2003, valid values included
STOREFRONT
. For version 2003 and later, use the dedicated StoreFront installation command mentioned in Use the full-product installer). -
-
/configure_firewall
Opens all ports in the Windows firewall used by the components being installed, if the Windows Firewall Service is running, even if the firewall is not enabled. If you are using a third-party firewall or no firewall, you must manually open the ports.
-
/disableexperiencemetrics
Prevents automatic upload of analytics collected during installation, upgrade, or removal to Citrix.
-
/exclude “feature”[,”feature”]
Prevents installation of one or more comma-separated features, services, or technologies, each enclosed in straight quotation marks. Valid values are:
-
"Local Host Cache Storage (LocalDB)"
: Prevents installation of the database used for Local Host Cache. This option has no effect on whether SQL Server Express is installed for use as the site database.
-
-
/help or /h
Displays command help.
-
/ignore_hw_check_failure
Allows the Delivery Controller installation or upgrade to continue, even if the hardware checks fail (for example, due to insufficient RAM). For more information, see Hardware check.
-
/ignore_site_test_failure
Valid only during Controller upgrade. Usually, any site test failures are ignored and the upgrade proceeds. If omitted (or set to false), any site test failure causes the installer to fail, without performing the upgrade. Default = false
During an upgrade, this option is ignored if an unsupported SQL Server version is detected. For details, see SQL Server version check.
-
/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
-
/no_remote_assistance
Valid only when installing Director. Disables the user shadowing feature that uses Windows Remote Assistance.
-
/noreboot
Prevents a restart after installation. (For most core components, a restart is not enabled by default.)
-
/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 remount the media or want to capture information during an automated installation. -
/nosql
Prevents installation of Microsoft SQL Server Express on the server where you are installing the Controller. If this option is omitted, SQL Server Express is installed for use as the site database.
This option has no effect on the installation of SQL Server Express LocalDB used for Local Host Cache.
-
/quiet or /passive
No user interface appears during the installation. The only evidence of the installation process is in Windows Task Manager. If this option is omitted, the graphical interface launches.
-
/remove
Removes the core components specified with the
/components
option. -
/removeall
Removes all installed core components.
-
/sendexperiencemetrics
Automatically sends analytics collected during the installation, upgrade, or removal to Citrix. If this option is omitted (or
/disableexperiencemetrics
is specified), the analytics are collected locally, but not sent automatically. -
/tempdir directory
Directory that holds temporary files during installation. Default = c:\Windows\Temp.
-
/xenapp
Installs Citrix Virtual Apps. If this option is omitted, Citrix Virtual Apps and Desktops is installed.
Examples of installing core components
The following command installs a Delivery Controller, Studio, Citrix Licensing, and SQL Server Express on a server. Firewall ports required for component communications are opened automatically.
\x64\XenDesktop Setup\XenDesktopServerSetup.exe /components controller,desktopstudio,licenseserver /configure_firewall
The following command installs a Citrix Virtual Apps Controller, Studio, and SQL Server Express on the server. Firewall ports required for component communication are opened automatically.
\x64\XenDesktop Setup\\XenDesktopServerSetup.exe /xenapp /components controller,desktopstudio /configure_firewall
Use a standalone VDA installer
Citrix account credentials are required to access the download site. You must either have elevated administrative privileges before starting the installation, or use Run as administrator.
- Download the appropriate package from Citrix:
- Multi-session OS Virtual Delivery Agent:
VDAServerSetup_xxxx.exe
- Single-session OS Virtual Delivery Agent:
VDAWorkstationSetup_xxxx.exe
- Single-session OS Core Services Virtual Delivery Agent:
VDAWorkstationCoreSetup_xxxx.exe
- Multi-session OS Virtual Delivery Agent:
-
Either extract the files from the package to an existing directory first and then run the installation command, or simply run the package.
To extract the files before installing them, use
/extract
with the absolute path, for exampleC:\YourExtractFolder\VDAWorkstationCoreSetup.exe /extract %temp%\CitrixVDAInstallMedia
. The directory must exist. Otherwise, the extract fails. Then in a separate command, run the appropriate command, using the valid options listed in this article.-
For
VDAServerSetup_XXXX.exe
, run<extract folder>\Extract\Image-Full\x64\XenDesktop Setup\XenDesktopVDASetup.exe
-
For
VDAWorkstationCoreSetup_XXXX.exe
, run<extract folder>\Extract\Image-Full\x64\XenDesktop Setup\XenDesktopRemotePCSetup.exe
-
For
VDAWorkstationSetup_XXXX.exe
, run<extract folder>\Extract\Image-Full\x64\XenDesktop Setup\XenDesktopVDASetup.exe
To run the downloaded package, run its name:
VDAServerSetup.exe
,VDAWorkstationSetup.exe
, orVDAWorkstationCoreSetup.exe
. Use the valid options listed in this article. -
If you are familiar with the full product installer:
-
Run the standalone
VDAServerSetup.exe
orVDAWorkstationSetup.exe
installer as if it was theXenDesktopVdaSetup.exe
command in everything except its name. -
The
VDAWorkstationCoreSetup.exe
installer is different, because it supports a subset of the options available to the other installers.
Command-line options for installing a VDA
The following options are valid with one or more of the following commands (installers): VDAServerSetup_xxxx.exe
, VDAWorkstationSetup_xxxx.exe
, and VDAWorkstationCoreSetup_xxxx.exe
.
For more detail about options, see Install VDAs.
-
/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 for Windows, specify
/components vda,plugins
.If this option is omitted, only the VDA is installed (not the Citrix Workspace app).
This option is not valid when using the
VDAWorkstationCoreSetup_xxxx.exe
installer. That installer cannot install the Citrix Workspace app. -
-
/controllers “controller [controller]”
Space-separated FQDNs of Controllers with which the VDA can communicate, enclosed in straight 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_hdx_ports
Opens ports in the Windows firewall required by the VDA 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, specify the
/enable_hdx_udp_ports
option, in addition to this/enable_hdx_ports
option. -
/enable_hdx_udp_ports
Opens UDP ports in the Windows firewall that HDX adaptive transport uses, 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 extra ports that the VDA uses, specify the
/enable_hdx_ports
option, in addition to this/enable_hdx_udp_ports
option. -
/enable_real_time_transport
Enables or disables use of UDP for audio packets (RealTime 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 Director. If you specify this option, Windows Remote Assistance opens the dynamic ports in the firewall.
-
/enablerestore or /enablerestorecleanup
(Valid only for single-session VDAs) Enables automatic return to the restore point, if the VDA install or upgrade fails.
If the install/upgrade completes successfully:
-
/enablerestorecleanup
instructs the installer to remove the restore point. -
/enablerestore
instructs the installer to retain the restore point, even though it was not used.
For details, see Restore on install or upgrade failure.
-
-
/enable_ss_ports
Opens ports in the Windows Firewall that are required for screen sharing, 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.
-
/exclude “component”[,”component”]
Prevents installation of one or more comma-separated optional components, each enclosed in straight 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 as follows:
Multi-session OS Single-session OS Single-session OS Core Services Citrix Authentication Identity Assertion VDA Plug-in
Citrix Authentication Identity Assertion VDA Plug-in
Citrix Authentication Identity Assertion VDA Plug-in
Citrix Backup and Restore
Citrix Backup and Restore
Citrix Browser Content Redirection
Citrix Browser Content Redirection
Citrix Browser Content Redirection
Citrix Personalization for App-V - VDA
Citrix MCS IODriver
Citrix MCS IODriver
Citrix Telemetry Service
Citrix Personalization for App-V - VDA
Citrix Personalization for App-V - VDA
Citrix Universal Print Client
Citrix Profile Management
Citrix Profile Management
Citrix Vda Log Capture Service
Citrix Profile Management WMI Plug-in
Citrix Profile Management WMI Plug-in
CSE Component
Citrix Rendezvous V2
Citrix Rendezvous V2
Director VDA Plug-in
Citrix Telemetry Service
Citrix Telemetry Service
Machine Management Provider
Citrix Universal Print Client
Citrix Universal Print Client
VDA Monitor Plug-in
Citrix Vda Log Capture Service
Citrix Vda Log Capture Service
VDA WMI Proxy Plug-in
Citrix VDA Upgrade Agent
Citrix VDA Upgrade Agent
CSE Component
CSE Component
Director VDA Plug-in
Director VDA Plug-in
Machine Identity Service
Machine Identity Service
Machine Management Provider
Machine Management Provider
VDA Monitor Plug-in
User Personalization Layer
VDA WMI Proxy Plug-in
VDA Monitor Plug-in
VDA WMI Proxy Plug-in
Excluding Citrix Profile Management from the installation (
/exclude "Citrix Profile Management"
) affects monitoring and troubleshooting of VDAs with Citrix Director. 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 displays 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 specify both
/exclude
and/includeadditional
with the same component name, that 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.
-
/includeadditional “component”[,”component”]
Includes installation of one or more comma-separated optional components, each enclosed in straight quotation marks. This option can be helpful when you are creating a Remote PC Access deployment, and want to install other components that are not included by default. Valid values are as follows:
Multi-session OS Single-session OS Citrix Backup and Restore
Citrix Backup and Restore
Citrix MCS IODriver
Citrix MCS IODriver
Citrix Personalization for App-V - VDA
Citrix Personalization for App-V - VDA
Citrix Profile Management
Citrix Profile Management
Citrix Profile Management WMI Plug-in
Citrix Profile Management WMI Plug-in
Citrix Rendezvous V2
Citrix Rendezvous V2
Citrix VDA Upgrade Agent
Citrix VDA Upgrade Agent
Citrix Web Socket Vda Registration Tool
Citrix Web Socket Vda Registration Tool
Machine Identity Service
Machine Identity Service
User Personalization Layer
If you specify both
/exclude
and/includeadditional
with the same component name, that component is not installed. -
/installdir directory
Existing empty directory where components will be installed. Default = c:\Program Files\Citrix.
-
/install_mcsio_driver
Do not use. Instead, use
/includeadditional "Citrix MCS IODriver"
or/exclude "Citrix MCS IODriver"
-
/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 an image to be used to create other machines. This option is equivalent to
/mastermcsimage
.This option is not valid when using the
VDAWorkstationCoreSetup_xxxx.exe
installer. -
/mastermcsimage
Specifies that this machine will be used as an image with Machine Creation Services. This option is equivalent to
/masterimage
. -
/masterpvsimage
Specifies that this machine will be used as an 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, except N editions.
-
/nodesktopexperience
The Enhanced Desktop Experience feature is no longer available. This option (and policy setting) is ignored, if specified.
Valid only when installing a VDA for multi-session 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 remount the media or want to capture information during an automated installation. -
/physicalmachine
Use this argument along with
/remotepc
for RemotePC installation. Otherwise the VDA might not behave as expected in certain user scenarios. -
/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. -
/proxyconfig “address or PAC file path”
Valid only if command contains
/includeadditional “Citrix Rendezvous V2”
. The address or PAC file path of the proxy for use with the Rendezvous protocol. For feature details, see Rendezvous protocol.- Proxy address format:
http://<url-or-ip>:<port>
- PAC file format:
http://<url-or-ip>:<port>/<path>/<filename>.pac
- Proxy address format:
-
/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 (single-session OS) or brokered connections (multi-session OS). Excludes installation of any additional components (see component lists with
/exclude
and/includeadditional
options).This option is not valid when using the
VDAWorkstationCoreSetup.exe
installer. That installer automatically excludes installation of these components./remotepc
is not compatible with the/servervdi
option. -
/remove
Removes the components specified with the
/components
option. -
/remove_appdisk_ack
Authorizes the VDA installer to uninstall the AppDisks VDA plug-in if it’s installed.
-
/remove_pvd_ack
Authorizes the VDA installer to uninstall Personal vDisk if it’s installed.
-
/removeall
Removes the VDA. It does not remove the Citrix Workspace app (if installed).
-
/sendexperiencemetrics
Automatically sends analytics collected during the installation, upgrade, or removal to Citrix. If this option is omitted (or the
/disableexperiencemetrics
option is specified), analytics are collected locally, but not sent automatically. -
/servervdi
Installs a VDA for single-session OS on a supported Windows multi-session machine. Omit this option when installing a VDA for multi-session OS on a Windows multi-session machine.
Before using this option, see Server VDI.
Use this option only with the full-product VDA installer.
-
/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.
-
/xendesktopcloud
Indicates that the VDA is installed in a Citrix DaaS (Citrix Cloud) deployment.
Examples of installing a VDA
Install a VDA with the full-product installer:
The following command installs a VDA for single-session OS and Citrix Workspace app to the default location on a VM. This VDA will be used as an image and use MCS to provision VMs. The VDA will register initially with the Controller on the server named Contr-Main
in the domain mydomain
. The VDA will use user personalization layer and Windows Remote Assistance.
\x64\XenDesktop Setup\XenDesktopVdaSetup.exe /quiet /components vda,plugins /controllers "Contr-Main.mydomain.local" /enable_hdx_ports /includeadditional "user personalization layer" /mastermcsimage /enable_remote_assistance
Install a single-session OS VDA with the VDAWorkstationCoreSetup standalone installer:
The following command installs a Core Services VDA on a single-session 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 Controller 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
After you install a VDA, you can customize several settings. From the \x64\XenDesktop Setup
directory on the product media, run XenDesktopVdaSetup.exe
, using one or more of the following options, which are described in Command-line options for installing a VDA.
-
/reconfigure
(required when customizing a VDA) -
/h
or/help
/quiet
/noreboot
/controllers
/portnumber port
/enable_hdx_ports
Troubleshoot VDAs
-
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.
-
After a VDA is installed, it cannot deliver apps or a desktop to users until it registers with a Delivery Controller.
To learn about VDA registration methods and how to troubleshoot registration issues, see VDA registration.
Command-line options for installing a Universal Print Server
The following option is valid with the XenDesktopPrintServerSetup.exe
command.
- /enable_upsserver_port
Software | Folder | File name |
---|---|---|
Microsoft Visual C++ 2017 Runtime, 32-bit and 64-bit | Support > VcRedist_2017 |
vcredist_x64.exe and vcredist_x86.exe
|
Citrix Diagnostic Facility | x64 > Virtual Desktop Components | cdf_x64.msi |
Universal Print Server server component | x64 > Universal Print Server | UpsServer_x64.msi |
When this option is not specified, the installer displays the Firewall page from the graphical interface. Select Automatically to have the installer automatically add the Windows firewall rules, or Manually to let the administrator manually configure the firewall.
After installing the software on your print servers, configure the Universal Print Server using the guidance in Provision printers.
More information
For information about how Citrix reports the result of component installations, see Citrix installation return codes.
In this article
- Introduction
- Use the full-product installer
- Command-line options for installing core components
- Examples of installing core components
- Use a standalone VDA installer
- Command-line options for installing a VDA
- Examples of installing a VDA
- Customize a VDA
- Troubleshoot VDAs
- Command-line options for installing a Universal Print Server
- More information