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 extra component, such as Citrix Gateway. For an introduction, see Integrate Citrix Virtual Apps and Desktops with Citrix Gateway.
If your deployment includes Windows Server workloads, configure a Microsoft RDS License Server.
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. The standalone VDA installers are available on the Citrix download site. 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 images used by Machine Creation Services (MCS) and Citrix Provisioning (formerly Provisioning Services). For details, see Install VDAs using scripts.
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 other 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.
Install the Citrix License Server and licenses before installing other components on other servers.
- To install a supported component on a Server CoreOS (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.
Ensure that all machines have synchronized system clocks. The Kerberos infrastructure that secures communication between the machines requires synchronization.
With Citrix Hypervisors, the virtual machine’s power state might appear as unknown even if it appears registered. To resolve this issue, edit the registry key HostTime value to disable time synchronization with the host:
HKEY_LOCAL_MACHINE\Software\Citrix\XenTools\HostTime="Local"
HKEY_LOCAL_MACHINE\Software\Wow6432Node\Citrix\XenTools\HostTime="Local"
Tip:
The default value is
HostTime="UTC". Change this value to something other than UTC, for example,Local. This change effectively disables time synchronization with the host.
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.
If you try to install or upgrade a VDA on a Windows OS that this product version doesn’t support, a message guides you to an article describing 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 a 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.
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 a Delivery Controller, Studio, License Server, or Director from the full-product media, 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 does not have Media Foundation (such as N editions), several multimedia features are not installed and will not work.
- Windows Media Redirection
- HTML5 Video Redirection
- HDX RealTime Webcam Redirection
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_ackoption to acknowledge the limitation. -
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. Remember that it must be done. For more information, see VDA registration.
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.
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.
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
/norebootoption, the machine restarts automatically after installing the prerequisite. - If you are using the command line interface with the
/norebootoption, you must initiate the restart.
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.
Restore on install or upgrade failure
Note:
This feature is available only for single-session VDAs.
If a single-session VDA installation or upgrade fails, and the “restore on failure” feature is enabled, the machine is returned to a restore point that was set before the installation or upgrade began.
When a single-session VDA installation or upgrade starts with this feature enabled, the installer creates a system restore point before beginning the actual install or upgrade. If the VDA installation or upgrade fails, the machine is returned to the restore point state. The %temp%/Citrix folder contains deployment logs and other information about the restore.
By default, this feature is disabled.
If you plan to enable this feature, make sure that system restore is not disabled through a GPO setting (Computer Configuration > Administrative Templates > System > System Restore).
To enable this feature when installing or upgrading a single-session VDA:
-
When using a VDA installer’s graphical interface (such as using Autostart or the
XenDesktopVDASetup.execommand without any restore or quiet options), select the Enable automatic restore if update fails check box on the Summary page.If the install/upgrade completes successfully, the restore point is not used, but is retained.
-
Run a VDA installer with either the
/enablerestoreor/enablerestorecleanupoption.-
If you use the
/enablerestorecleanupoption, and the install/upgrade completes successfully, the restore point is removed automatically. -
If you use the
/enablerestoreoption, and the install/upgrade completes successfully, the restore point is not used, but is retained.
-
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, and License Server.
- Install or upgrade StoreFront.
- Install or upgrade Windows VDAs for single-session or multi-session operating systems.
- Install the Universal Print Server
UpsServercomponent on your print servers. - Install the Federated Authentication Service.
- Install Session Recording.
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. (They are not available from the product installation media.) 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.
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 an 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.exe 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.
- Citrix Supportability Tools.
- Citrix Files for Windows.
- Citrix Files for Outlook.
- Citrix WEM Agent.
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" "Machine Identity Service" "Citrix User Profile Management" "Citrix User Profile Management WMI Plugin" "Citrix Supportability Tools" "Citrix Files for Windows" "Citrix WEM Agent.
You can install the omitted components/features later by running the full-product installer. That action enables you to install all missing components.
The VDAWorkstationCoreSetup.exe installer automatically installs the Browser Content Redirection MSI. This automatic installation applies to VDA release 2003 and later supported releases.
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 an RDS 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.
Configure a Microsoft RDS License Server for Windows Server workloads
This product accesses Windows Server remote session capabilities when delivering a Windows Server workload, such as Windows 2016. This typically requires a Remote Desktop Services client access license (RDS CAL). The VDA must be able to contact an RDS license server to request RDS CALs. Install and activate the license server. For more information, see the Microsoft document Activate the Remote Desktop Services License Server. For proof of concept environments, you can use the grace period provided by Microsoft.
With this method, you can have this service apply the license server settings. You can configure the license server and per user mode in the RDS console on the image. You can also configure the license server using Microsoft Group Policy settings. For more information, see the Microsoft document License your RDS deployment with client access licenses (CALs).
To configure the RDS license server using Group Policy settings:
- Install a Remote Desktop Services License Server on an available machine. The machine must always be available. The Citrix product workloads must be able to reach this license server.
- Specify the license server address and per-user license mode using Microsoft Group Policy. For details, see the Microsoft document Specify the Remote Desktop Licensing Mode for an RD Session Host Server.
Windows 10 workloads require appropriate Windows 10 license activation. We recommend that you follow Microsoft documentation to activate Windows 10 workloads.