Prepare to install
Deploying Citrix Virtual Apps and Desktops begins with installing the following components. This process prepares for delivery of applications and desktops to users inside your firewall.
- One or more Delivery Controllers
- Citrix Studio
- Citrix Director
- Citrix StoreFront
- Citrix License Server
- One or more Citrix Virtual Delivery Agents (VDAs)
- Optional components and technologies such as the Universal Print Server, the Federated Authentication Service, and Self-Service Password Reset
For users outside your firewall, install and configure an additional component, such as Citrix Gateway. For an introduction, see Integrate Citrix Virtual Apps and Desktops with Citrix Gateway.
You can use the full-product installer on the product ISO to deploy many components and technologies. You can use a standalone VDA installer to install VDAs. All installers offer graphical and command line interfaces. See Installers.
The product ISO contains sample scripts that install, upgrade, or remove VDAs for machines in Active Directory. You can also use the scripts to manage master images used by Machine Creation Services (MCS) and Citrix Provisioning (formerly Provisioning Services). For details, see Install VDAs using scripts.
Learn about product name changes.
Information to review before installation
- Technical overview: If you’re unfamiliar with the product and its components.
- Security: When planning your deployment environment.
- Known issues: Issues you might encounter in this version.
- Databases: Learn about the system databases and how to configure them. During Controller installation, you can install SQL Server Express for use as the Site database. You configure most database information when you create a site, after you install the core components.
- Remote PC Access: If you’re deploying an environment that enables your users to access their physical machines in the office remotely.
- Connections and resources: If you’re using a hypervisor or cloud service to host or provision VMs for applications and desktops. You can configure the first connection when you create a site (after you install the core components). Set up your virtualization environment before then.
- Microsoft System Center Configuration Manager: If you’re using ConfigMgr to manage access to applications and desktops, or if you’re using the Wake on LAN feature with Remote PC Access.
Where to install components
Review the System requirements for supported platforms, operating systems, and versions. Component prerequisites are installed automatically, except as noted. See the Citrix StoreFront and the Citrix License Server documentation for their supported platforms and prerequisites.
You can install the core components on the same server or on different servers.
- Installing all the core components on one server can work for evaluation, test, or small production deployments.
- To accommodate future expansion, consider installing components on different servers. For example, installing Studio on a different machine than the server where you installed the Controller allows you to manage the site remotely.
- For most production deployments, installing core components on separate servers is recommended.
- To install a supported component on a Server Core OS (such as a Delivery Controller), you must use the command line. That OS type does not offer a graphical interface, so install Studio and other tools elsewhere, and then point them to the Controller server.
You can install both a Delivery Controller and a VDA for multi-session OS on the same server. Launch the installer and select the Delivery Controller (plus any other core components you want on that machine). Then launch the installer again and select the Virtual Delivery Agent for multi-session OS.
Ensure that each operating system has the latest updates. For example, installation of a Controller or VDA on Windows Server 2012 R2 fails if Windows update KB2919355 is not installed.
Ensure that all machines have synchronized system clocks. The Kerberos infrastructure that secures communication between the machines requires synchronization.
Optimization guidance for Windows 10 single-session machines is available in CTX216252.
Where NOT to install components:
- Do not install any components on an Active Directory domain controller.
- Installing a Controller on a node in a SQL Server clustering installation, SQL Server mirroring installation, or on a server running Hyper-V is not supported.
- Do not install Studio on a server running XenApp 6.5 Feature Pack 2 for Windows Server 2008 R2 or any earlier version of XenApp.
If you attempt to install (or upgrade to) a Windows VDA on an OS that is not supported for this product version, a message guides you to an article that describes your options.
Permission and Active Directory requirements
You must be a domain user and a local administrator on the machines where you are installing components.
To use the standalone VDA installer, you must have elevated administrative privileges or use Run as administrator.
Configure your Active Directory domain before starting an installation.
- System requirements lists the supported Active Directory functional levels. Active Directory contains more information.
- You must have at least one domain controller running Active Directory Domain Services.
- Do not install any Citrix Virtual Apps and Desktops components on a domain controller.
- Do not use a forward slash (/) when specifying Organizational Unit names in Studio.
The Windows user account used to install the Citrix License Server is automatically configured as a Delegated Administration full administrator on the license server.
For more information:
- Security best practices
- Delegated Administration
- Microsoft documentation for Active Directory configuration
Installation guidance, considerations, and best practice
During installation of any component
-
When installing or upgrading core components (Delivery Controller, Studio, Lixense Server, Director, StoreFront) from the full-product ISO, if the Citrix installer detects that a restart is pending from a previous Windows installation on the machine, the installer stops with exit/return code 9. You are prompted to restart the machine.
This is not a Citrix forced restart. It is due to other components installed earlier on the machine. If this occurs, restart the machine and then launch the Citrix installer again.
When using the command-line interface, you can prevent the check for the pending restart by including the
/no_pending_reboot_checkoption in the command. -
Usually, if a component has prerequisites, the installer deploys them if they are not present. Some prerequisites might require a machine restart.
-
When you create objects before, during, and after installation, specify unique names for each object. For example, provide unique names for networks, groups, catalogs, and resources.
-
If a component does not install successfully, the installation stops with an error message. Components that installed successfully are retained. You do not need to reinstall them.
-
Citrix 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. During installation, you can also choose to participate in other Citrix technologies that collect diagnostics for maintenance and troubleshooting. For information about these programs, see Citrix Insight Services.
-
Google Analytics are collected (and later uploaded) automatically when you install (or upgrade) Studio. After installing Studio, you can change this setting with the registry key
HKLM\Software\Citrix\DesktopStudio\GAEnabled. A value of 1 enables collection and upload, 0 disables collection and upload. -
If a VDA installation fails, an MSI analyzer parses the failing MSI log, displaying the exact error code. The analyzer suggests a CTX article, if it’s a known issue. The analyzer also collects anonymized data about the failure error code. This data is included with other data collected by CEIP. (If you end enrollment in CEIP, the collected MSI analyzer data is no longer sent to Citrix.
During VDA installation
The Citrix Workspace app for Windows is available, but 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 your StoreFront server. See the StoreFront documentation.
The Print Spooler Service is enabled by default on supported Windows servers. If you disable this service, you cannot successfully install a VDA for Windows multi-session OS, so ensure that this service is enabled before installing a VDA.
Most supported Windows editions come with Microsoft Media Foundation already installed. If the machine on which you’re installing a VDA does not have 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 to acknowledge the limitation.
If Media Foundation is not present on the machine with the VDA, these multimedia features do not work:
- Windows Media Redirection
- HTML5 Video Redirection
- HDX RealTime Webcam Redirection
When you install the VDA, a new local user group called Direct Access Users is created automatically. On a VDA for single-session OS, this group applies only to RDP connections. On a VDA for multi-session OS, this group applies to ICA and RDP connections.
The VDA must have valid Controller addresses with which to communicate. Otherwise, sessions cannot be established. You can specify Controller addresses when you install the VDA or later. Just remember that it must be done.
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 after and 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 multi-session 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
/norebootoption, 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 you’re upgrading a VDA to version 7.17 or a later supported version, a restart occurs during the upgrade. This cannot be avoided.
Installers
Full-product installer
Using the full-product installer provided in the ISO, you can:
- Install, upgrade, or remove core components: Delivery Controller, Studio, Director, StoreFront, License Server.
- Install or upgrade Windows VDAs for server or desktop operating systems.
- Install the Universal Print Server UpsServer component on your print servers.
- Install the Federated Authentication Service.
- Install the Self-Service Password Reset Service.
To deliver a desktop from a multi-session OS for one user (for example, for web development), use the full-product installer’s command line interface. For details, see Server VDI.
Standalone VDA installers
Standalone VDA installers are available on the Citrix download pages. The standalone VDA installers are much smaller than the full-product ISO. They more easily accommodate deployments that:
- Use Electronic Software Distribution (ESD) packages that are staged or copied locally
- Have physical machines
- Have remote offices
By default, files in the self-extracting standalone VDAs are extracted to the Temp folder. More disk space is required on the machine when extracting to the Temp folder than when using the full-product installer. However, 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. (They are not available on the full-product installation media.)
VDAServerSetup.exe:
Installs a VDA for multi-session OS. It supports all the VDA for multi-session OS options that are available with the full-product installer.
VDAWorkstationSetup.exe:
Installs a VDA for single-session OS. It supports all the VDA for single-session OS options that are available with the full-product installer.
VDAWorkstationCoreSetup.exe:
Installs a VDA for single-session 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. It installs only the core services necessary for VDA connections such deployments. Therefore, it supports only a subset of the options that are valid with the full-product or VDAWorkstationSetup installers.
This installer does not install or contain the components used for:
- App-V.
- Profile Management. Excluding Citrix Profile Management from the installation affects Citrix Director displays. For details, see Install VDAs.
- Machine Identity Service.
- Personal vDisk or AppDisks.
- Citrix Supportability Tools.
- Citrix Files for Windows.
- Citrix Files for Outlook.
The VDAWorkstationCoreSetup.exe installer does not install or contain a Citrix Workspace app for Windows.
Using VDAWorkstationCoreSetup.exe is equivalent to using the full-product or VDAWorkstationSetup installer to install a single-session 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
/remotepcoption. - In the command line interface: Specifying
/components vdaand/exclude "Citrix Personalization for App-V - VDA" "Personal vDisk" "Machine Identity Service" "Citrix User Profile Manager" "Citrix User Profile Manager WMI Plugin" "Citrix Supportability Tools" "Citrix Files for Windows".
You can install the omitted components/features later by running the full-product installer. That action installs all missing components.
The VDAWorkstationCoreSetup.exe installer does not automatically install the Browser Content Redirection MSI. (All other VDA installers install that MSI automatically.) To enable use of the browser content redirection feature, install BCR_x64.msi on the machine after you install the VDA. The MSI is located in the x64 > Virtual Desktop Components folder on the full-product installation media.
Citrix installation return codes
The installation log contains the result of component installations as a Citrix return code, not a Microsoft value.
- 0 = Success
- 1 = Failed
- 2 = PartialSuccess
- 3 = PartialSuccessAndRebootNeeded
- 4 = FailureAndRebootNeeded
- 5 = UserCanceled
- 6 = MissingCommandLineArgument
- 7 = NewerVersionFound
- 8 = SuccessRebootNeeded
- 9 = FileLockReboot
- 10 = Aborted
- 11 = FailedMedia
- 12 = FailedLicense
- 13 = FailedPrecheck
- 14 = AbortedPendingRebootCheck
- -1 = Exit
For example, when using tools such as Microsoft System Center Configuration Manager, a scripted VDA installation might appear to fail when the installation log contains the return code 3. This can occur when the VDA installer is waiting for a restart that you must initiate (for example, after a Remote Desktop Services role prerequisite installation on a server). A VDA installation is considered successful only after all prerequisites and selected components are installed, and the machine is restarted after the installation.
Alternatively, you can wrap your installation in CMD scripts (which return Microsoft exit codes) or change the success codes in your Configuration Manager package.