Product documentation
Citrix Virtual Apps and Desktops
Service Current Release 2402 LTSR 2311 2308 2305 2303 2212 2209 2206 2203 LTSR 1912 LTSR
View PDF

Prepare to install

August 29, 2024
Contributed by: 
C C

Deploying Citrix Virtual Apps and Desktops begins with installing the following components. This process prepares for the delivery of applications and desktops to users inside your firewall.

  • One or more Delivery Controllers
  • 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.

Note:

Make sure that the following Microsoft prerequisites are met on the server OS and the workstation OS:

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 an 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: To familiarize yourself with the product and its components.
  • Security: When planning your deployment environment.
  • Known issues: Issues you might come across 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.
  • Public Cloud host connections: If you have a Hybrid Rights License, you can create host connections to the public cloud. For information related to the Hybrid Rights License, see Hybrid Rights Renewals. For information related to public cloud entitlement and the reasons for this change, see CTX270373.

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.

Make sure that each operating system has the latest updates.

Make sure that all machines have synchronized system clocks. The Kerberos infrastructure that secures communication between the machines requires synchronization.

With XenServers, 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 joined 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:

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_check option 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 Microsoft Print Spooler Service must be enabled. You cannot successfully install a VDA if that service is disabled.

  • 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_ack option 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.

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 /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.

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 for single-session and multi-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.

If a multi-session VDA installation or upgrade fails, and the “restore on failure” feature is enabled, the machine is returned to a backup that was performed 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.

When a multi-session VDA installation or upgrade starts with this feature enabled, the installer creates a server backup before beginning the actual install or upgrade. If the VDA installation or upgrade fails, the machine is returned to the backup state. The %temp%/Citrix folder contains deployment logs and other information about the restore. The amount of time to create the server backup is based on the size of the backup needed and the amount of resources available to the server. The backup is stored in C:\WindowsImageBackup\servername.

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).

Note:

This GPO setting does not apply to restoring a multi-session VDA.

To enable this feature when installing or upgrading a single or multi-session VDA:

  • When using a VDA installer’s graphical interface (such as using Autostart or the XenDesktopVDASetup.exe command 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/backup is not used, but is retained.

  • Run a VDA installer with either the /enablerestore or /enablerestorecleanup option using the command line.

    • If you use the /enablerestorecleanup option, and the install/upgrade completes successfully, the restore point/server backup is removed automatically.

    • If you use the /enablerestore option, 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 UpsServer component on your print servers.
  • Install the Federated Authentication Service.
  • Install Session Recording.

  • Install Workspace Environment Management.

    Note:

    The Workspace Environment Management Agent installer is not localized. It is available only in English.

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.

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 /remotepc option.
  • In the command line interface: Specifying /components vda plus the /exclude option that lists all of the valid additional component names.

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:

  1. 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.
  2. 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.

More information

For setting up resource location for specific host types:

Prepare to install
August 29, 2024
Contributed by: 
C C
August 29, 2024
Contributed by: 
C C

In this article

Site feedback | Your privacy choices footer linkYour Privacy Choices | Privacy and legal terms | Cookie preferences | Consent settings | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.