Citrix Virtual Apps and Desktops Translate

Citrix Virtual Apps and Desktops
Citrix Product Documentation | docs.citrix.com January 19, 2022

Contents
Citrix Virtual Apps and Desktops 7 2006 3
Citrix Virtual Apps and Desktops 7 2006 3
Fixed issues 6
Known issues 12
Deprecation 16
System requirements 27
Technical overview 37
Active Directory 46
Databases 49
Delivery methods 56
Network ports 60
HDX 63
Adaptive transport 73
Citrix ICA virtual channels 82
Double hop in Citrix Virtual Apps and Desktops 91
Install and configure 94
Prepare to install 96
Microsoft System Center Virtual Machine Manager virtualization environments 104
Citrix Hypervisor virtualization environments 107
Microsoft System Center Configuration Manager environments 108
VMware virtualization environments 110
Nutanix virtualization environments 116
Install core components 118
© 1999 – 2021 Citrix Systems, Inc. All rights reserved. 2

Install VDAs 130
Install using the command line 143
Install VDAs using scripts 155
Install VDAs using SCCM 158
Create a site 160
Create machine catalogs 165
Manage machine catalogs 183
Create delivery groups 189
Manage delivery groups 194
Create application groups 216
Manage application groups 224
Remote PC Access 229
App‑V 238
Virtual Apps Secure Browser 252
Publish content 253
Server VDI 258
User personalization layer 260
Remove components 278
Upgrade and migrate 279
Upgrade a deployment 282
Secure 302
Security considerations and best practices 303
Integrate Citrix Virtual Apps and Desktops with Citrix Gateway 312
Delegated administration 312

Smart cards 320
Smart card deployments 326
Pass‑through authentication and single sign‑on with smart cards 332
App protection 334
Transport Layer Security (TLS) 340
Transport Layer Security (TLS) on Universal Print Server 354
Devices 364
Generic USB devices 366
Mobile and touch screen devices 366
Serial ports 370
Specialty keyboards 375
TWAIN devices 377
Webcams 377
Graphics 378
HDX 3D Pro 380
GPU acceleration for Windows multi‑session OS 381
GPU acceleration for Windows single‑session OS 384
Thinwire 388
Text‑based session watermark 394
Multimedia 396
Audio features 398
Browser content redirection 407
HDX video conferencing and webcam video compression 415
HTML5 multimedia redirection 419

Optimization for Microsoft Teams 422
Monitor, troubleshoot, and support Microsoft Teams 442
Windows Media redirection 449
General content redirection 450
Client folder redirection 451
Host to client redirection 452
Local App Access and URL redirection 457
Generic USB redirection and client drive considerations 465
Print 475
Printing configuration example 483
Best practices, security considerations, and default operations 486
Printing policies and preferences 488
Provision printers 490
Maintain the printing environment 498
Policies 503
Work with policies 504
Policy templates 507
Create policies 511
Compare, prioritize, model, and troubleshoot policies 516
Default policy settings 520
Policy settings reference 550
ICA policy settings 554
Auto client reconnect policy settings 561
Audio policy settings 563

Bandwidth policy settings 566
Bidirectional content redirection policy settings 571
Browser content redirection policy settings 574
Client sensors policy settings 581
Desktop UI policy settings 582
End user monitoring policy settings 583
Enhanced desktop experience policy setting 584
File Redirection policy settings 585
Graphics policy settings 589
Caching policy settings 595
Framehawk policy settings 596
Keep alive policy settings 596
Local App Access policy settings 597
Mobile experience policy settings 598
Multimedia policy settings 599
Multi‑stream connections policy settings 608
Port redirection policy settings 611
Printing policy settings 612
Client printers policy settings 615
Drivers policy settings 619
Universal Print Server policy settings 620
Universal printing policy settings 625
Security policy settings 627
Server limits policy settings 628

Session limits policy settings 629
Session reliability policy settings 630
Session watermark policy settings 632
Time zone control policy settings 634
TWAIN devices policy settings 635
USB devices policy settings 636
Virtual channel allow list policy settings 644
Visual display policy settings 645
Moving images policy settings 646
Still images policy settings 648
WebSockets policy settings 650
Load management policy settings 651
Profile management policy settings 652
Advanced policy settings 652
Basic policy settings 655
Cross‑platform policy settings 659
File system policy settings 661
Exclusions policy settings 661
Synchronization policy settings 663
Folder redirection policy settings 665
AppData(Roaming) policy settings 665
Contacts policy settings 666
Desktop policy settings 666
Documents policy settings 667

Downloads policy settings 667
Favorites policy settings 668
Links policy settings 669
Music policy settings 669
Pictures policy settings 670
Saved Games policy settings 671
Start menu policy settings 671
Searches policy settings 672
Video policy settings 672
Log policy settings 673
Profile handling policy settings 677
Registry policy settings 681
Streamed user profiles policy settings 682
User personalization policy settings 683
Virtual Delivery Agent policy settings 684
HDX 3D Pro policy settings 686
Monitoring policy settings 687
Virtual IP policy settings 690
Configure COM Port and LPT Port Redirection settings using the registry 691
Connector for Configuration Manager 2012 policy settings 692
Manage 695
Licensing 697
Multi‑type licensing 701
FAQ for licensing 709

Applications 721
Universal Windows Platform Apps 732
Zones 734
Connections and resources 746
Local Host Cache 757
Virtual IP and virtual loopback 767
Delivery Controllers 770
VDA registration 774
Sessions 784
Use Search in Studio 790
Tags 791
IPv4/IPv6 support 800
User profiles 801
Collect a Citrix Diagnostic Facility (CDF) trace at system startup 807
Citrix Insight Services 810
Citrix Scout 821
Monitor 842
Configuration logging 843
Event logs 848
Director 849
Install and configure 854
Advanced configuration 856
Configure PIV smart card authentication 860
Configure network analysis 863

Delegated administration and Director 864
Secure Director deployment 867
Configuring on‑premises sites with Citrix Analytics for Performance 870
Site Analytics 875
Alerts and notifications 885
Filter data to troubleshoot failures 898
Monitor historical trends across a site 900
Troubleshoot deployments 905
Troubleshoot applications 906
Application probing 910
Desktop probing 914
Troubleshoot machines 919
Troubleshoot user issues 926
Diagnose session startup issues 928
Diagnose user logon issues 933
Shadow users 940
Send messages to users 941
Resolve application failures 942
Restore desktop connections 943
Restore sessions 944
Run HDX channel system reports 945
Reset a user profile 945
Record sessions 949
Feature compatibility matrix 950

Data granularity and retention 954
Third party notices 960
SDKs and APIs 960

Citrix Virtual Apps and Desktops 7 2006
September 23, 2020
April 14, 2021
About this release
This Citrix Virtual Apps and Desktops release includes new versions of the Windows Virtual Delivery
Agents (VDAs) and new versions of several core components. You can:
• Install or upgrade a site
Use the ISO for this release to install or upgrade core components and VDAs. Installing or up‑
grading to the latest version allows you to use the latest features.
• Install or upgrade VDAs in an existing site
If you already have a deployment, and aren’t ready to upgrade your core components, you can
still use several of the latest HDX features by installing (or upgrading to) a new VDA. Upgrading
only the VDAs can be helpful when you want to test enhancements in a non‑production environ‑
ment.
After upgrading your VDAs to this version (from version 7.9 or later), you do not need to update
the machine catalog’s functional level. The 7.9 (or later) value remains the default functional
level, and is valid for this release. For more information, see VDA versions and functional levels.
For installation and upgrade instructions:
• If you are building a new site, follow the sequence in Install and configure.
• If you are upgrading a site, see Upgrade a deployment.
Upgrade: Removing unsupported items
As of version 2003, the following technologies and host types are not supported in Citrix Virtual Apps
and Desktops 7 Current Release deployments:
• Personal vDisks (PvD) for storing data next to users’ VMs. The user personalization layer fea‑
ture now handles user persistence.

• AppDisks for managing applications used in delivery groups.

• Host types for connections: Azure Classic, Azure Resource Manager (ARM), Amazon Web Ser‑
vices (AWS), CloudPlatform (the original Citrix product).
– For information about alternative ways you can continue using ARM and AWS, see
CTX270373.
– For host types supported in this release, see System requirements.
As of version 2006, if your current deployment uses PvDs or AppDisks, or has connections to unsup‑
ported host types, you can upgrade your deployment to version 2006 (or later supported versions)
only after removing items that use those technologies.
For VDAs, the installation or earlier upgrades might have included PvD and AppDisks components,
even if you never used it. You can upgrade VDAs to version 2006 (or later supported versions), only
after removing that software. When using the graphical interface, that removal can be done automat‑
ically. Or, you can include options when using the CLI.
For details, see Remove PvD, AppDisks, and unsupported hosts.
Install and upgrade: Self‑Service Password Reset no longer in full‑product installer or on

media
As of version 2003, the Self‑Service Password component is deprecated. As of version 2006, You can‑
not use the full‑product installer to install or upgrade the component. The component’s installer is
not available on the installation media.
You can get the component software from the download page for your Citrix Virtual Apps and Desktops
version.
EnhancedDesktopExperience MSI removed
The EnhancedDesktopExperience MSI has been removed from the Citrix Virtual Apps and Desktops
current release layout.
This feature was valid when installing VDAs on Windows Server 2012 R2 and earlier versions. The
feature is not valid on Windows OS versions that are currently supported for multi‑session VDAs.
If a VDA installation command contains the /nodesktopexperience option, that option is ignored.
The Enhanced Desktop Experience policy setting is also ignored, if specified.
Citrix Scout: Usage data collection
When you use Scout, Citrix uses Google Analytics to collect anonymous usage data to be used for
future product features and improvements. For details on configuring data collection, see Usage data
collection.

Citrix Scout: health check updates
Updates have been made to running health checks on Scout. For more information, see Run health
checks.
Delivery groups: Machine restart schedules
You can now indicate whether a restart schedule affects machines that are in maintenance mode.
This feature is available only in PowerShell. For details, see Scheduled restarts for machines in main‑
tenance mode.
Virtual Delivery Agents (VDAs) 2006
Version 2006 of the Windows single‑session OS and multi‑session OS VDAs includes the following en‑
hancements. These items are in addition to the VDA installation and upgrade items listed earlier in
this article.
Group policy to enable and disable keyboard synchronization and Input Method Editor (IME)
A Studio policy is included to replace registry configurations that enable or disable dynamic keyboard
layout synchronization, Input Method Editor (IME), Unicode keyboard layout mapping, and hide or
show the keyboard layout switch notification dialog message. For more information, see Keyboard
and Input Method Editor (IME).
Seamless window enhancement
When you lock a seamless session, its log‑on screen is now no longer full‑screen. The endpoint’s desk‑
top or other applications are accessible.
Virtual channel allow list
This feature enables the use of an allow list that specifies which virtual channels are allowed to be
opened in an ICA session. For more information, see Virtual channel allow list policy settings.
Citrix Licensing 11.16.6
Citrix Licensing 11.16.6 contains new features and fixed and known issues.
Citrix Federated Authentication Service 2006
Citrix Federated Authentication Service (FAS) 2006 contains new features.

Support for Active Directory‑Based Activation
This release adds support for Active Directory‑Based Activation (ADBA). ADBA enables you to activate
machines through their domain connections. Machines are immediately activated when they join
the domain. These machines remain activated as long as they remain joined to the domain and in
contact with it. This functionality is only supported on Windows 10, Windows Server 2012 R2 and
later versions. For more information, see Active Directory‑based activation.
Related components
For documentation about related components, see:
• Citrix App Layering

• HDX RealTime Optimization Pack
• Licensing
• Linux Virtual Delivery Agent
• Profile Management
• Citrix Provisioning
• Citrix SCOM Management Packs
• Self‑Service Password Reset
• Session Recording
• StoreFront
• Workspace Environment Management
More information
• Be sure to check Deprecation for any changes to announcement and removal versions.
• For information about product name and version number changes that were introduced in the
year 2018, see New names and numbers.
Fixed issues
September 15, 2021
The following issues have been fixed since Citrix Virtual Apps and Desktops 7 2003:
Citrix Director
• In Citrix Director, when you pull the report for a Delivery Group without a failed connection
on the Failure tab under Trends, the details populate correctly. But details of all the Delivery

Groups, including the Delivery Group that has no failed connections, might appear as failed con‑
nections when you export the report. [CVADHELP‑14392]
• When Citrix Director attempts to set up an email configuration using an SMTP server, this error
message might appear:
Invalid Email Server
[CVADHELP‑14449]
Citrix Provisioning
Citrix Provisioning 2006 documentation provides specific information about the updates in this re‑
lease.
Citrix Studio
• When you run Studio as a published app, Studio might become unresponsive. [CVADHELP‑
14207]
Delivery Controller
• Some published applications might cause application enumeration to fail. The issue occurs
when a corrupted application icon is present in an .exe file. [CVADHELP‑13133]
• When using the PowerShell command Get‑ApplibAppvPackage, the command might not rec‑
ognize AppVApplications as a returned property. [CVADHELP‑13296]
• When you add administrators of other domains to Citrix Studio, Studio might display the follow‑
ing error message:
Error: Failed to validate the Central Configuration Service Location.
You do not have sufficient permissions to administer the Site using Studio, or there is a
problem with the Delegated Administration service.
The issue occurs if a domain controller in any one of the domains is unreachable. [CVADHELP‑
13651]
• Attempts to import synchronized configurations to the Local Host Cache database might repeat‑
edly fail with an Error 505. [CVADHELP‑14237]
• Delivery Controllers might receive the following Local Host Cache Error 505 in the event log:
Unknown Error.
[CVADHELP‑14428]

• After you upgrade XenApp and XenDesktop 7.15 Cumulative Update 1 to Cumulative Update 3,
attempts to import Local Host Cache (LHC) might fail with an Error 505. [CVADHELP‑14429]
• When you log on to a new session using Citrix Director, the logon might not appear on the Aver‑
age Logon Duration graph available on the Logon Performance tab under Trends. However,
the logon appears in the Logon Duration by User Session form. [CVADHELP‑14740]
Federated Authentication Service
Federated Authentication Service 2006 contains no fixed issues.
General
• When you modify an existing VDA installation using the meta installer, you can add MCSIO stor‑
age optimization to the installation by selecting the option ‘Enable MCSIO write cache for stor‑
age optimization.’ The installation proceeds without installing the MCSIO driver. [HDX‑21754]
Licensing
Licensing 2006 documentation provides specific information about the updates in this release.
Linux VDA
Linux VDA 2006 documentation provides specific information about the updates in this release.
Profile Management
Profile Management 2006 documentation provides specific information about the updates in this re‑
lease.
Universal Print Server
Client
• When you attempt to launch an application, the Citrix Print Manager Service (CpSvc.exe) might
exit unexpectedly. [CVADHELP‑13945]

VDA for single‑session OS
Installing, Uninstalling, Upgrading
• When you upgrade a VDA, the MaxVideoMemoryBytes registry key might revert to the default
value. [CVADHELP‑13629]
Printing
• PDF printers automatically created might not be deleted. The issue occurs if they are created
under HKEY_LOCAL_MACHINE\SOFTWARE instead of HKEY_CURRENT_CONFIG. [CVADHELP‑
14280]
Session/Connection
• VDAs might experience a fatal exception on ctxdvcs.sys and display a blue screen. [CVADHELP‑
13000]
• When you reconnect to an active session on another machine, redirected printers and client
drives might be missing. The issue occurs when you move from one machine to another without
locking or disconnecting the active user session. [CVADHELP‑13035]
• When you configure the High DPI setting to use the native resolution instead of high DPI, DPI
scaling between the VDA and the user device might not match. The issue occurs during the
initial connection. [CVADHELP‑13205]
• In a multi‑monitor environment, applications might not display consistently on the same mon‑
itor. The issue occurs when you move to a new workstation. [CVADHELP‑13657]
• A VDA might become unresponsive after restart. The issue occurs when security software such
as Symantec SEP enforces security scans. [CVADHELP‑13832]
• With the Automatic keyboard display policy enabled, when you click on the Google search box,
the keyboard might not pop up automatically. The issue occurs when a session is running on
the Internet Explorer, Firefox, or Chrome browsers. [CVADHELP‑14065]
• In a double‑hop scenario, a single user might consume two Citrix Concurrent User (CCU) li‑
censes. Double hop is when a user launches the HDX session within another HDX session (for ex‑
ample, when you launch a published application within a virtual desktop session). [CVADHELP‑
14409]
• With the time zone policy set to Use local time of the client, the time zone might be redirected
incorrectly when you launch a session through Citrix Workspace app for HTML5. For example,

the time is set to UTC+01:00 instead of UTC+00:00. As a result, the Automatically adjust clock
for Daylight Saving setting is cleared instead of being checked. [CVADHELP‑14471]
Smart Cards
• After you configure smart card authentication on Windows 10, smart card pass‑through authen‑
tication might fail if you launch a desktop in a user session. The issue occurs when you launch
a desktop from a thin client. [CVADHELP‑11757]
System Exceptions
• USB redirection can cause VDAs to experience a fatal exception, displaying a blue screen with
bug check code SYSTEM_THREAD_EXCEPTION_NOT_HANDLED (7e). Also, global lock for USB
redirection might not be released, thus blocking other redirections. [CVADHELP‑9237]
• The Service Host (svchost.exe) process or the wfshell.exe process might experience an ac‑
cess violation and exit unexpectedly. The issue occurs because of the faulting module,
icaendpoint.dll. [CVADHELP‑14276]
User Experience
• Desktop sessions might display artifacts that obscure screen contents and other portions of the
display. [CVADHELP‑13301]
VDA for multi‑session OS
Printing
• Attempts to print documents to a different output printer tray might fail. The print job uses
the default tray to print documents even if you choose a different tray in the Print dialog box.
[CVADHELP‑13492]
• PDF printers automatically created might not be deleted. The issue occurs if they are created
under HKEY_LOCAL_MACHINE\SOFTWARE instead of HKEY_CURRENT_CONFIG. [CVADHELP‑
14280]
Session/Connection
• When you launch a published application on a multi‑session VDA, the Windows RunOnce reg‑
istry key might not execute. [CVADHELP‑11991]

• When attempting to highlight text in a user session, you might experience performance issues.
The issue occurs when you do that in Microsoft Outlook Version 2016 running in a published
desktop. [CVADHELP‑12886]
• VDAs might experience a fatal exception on ctxdvcs.sys and display a blue screen. [CVADHELP‑
13000]
• In a multi‑monitor environment, applications might not display consistently on the same mon‑
itor. The issue occurs when you move to a new workstation. [CVADHELP‑13657]
• A VDA might become unresponsive after restart. The issue occurs when security software such
as Symantec SEP enforces security scans. [CVADHELP‑13832]
• A user session might close unexpectedly. The issue occurs with unauthenticated (anonymous)
users when they launch a second application in windowed mode. [CVADHELP‑13917]
• With the Automatic keyboard display policy enabled, when you click on the Google search
box, the keyboard might not pop up automatically. The issue occurs when a session is running
on the Internet Explorer, Firefox, or Chrome browsers. [CVADHELP‑14065]
• If you connect a USB microphone to a user device and launch a session, the USB microphone
might fail to redirect. The USB device displays as Optimized, Policy Restricted. [CVADHELP‑
14301]
• When you lock a seamless session, the logon window might cover the entire screen, regardless
of the size of the session window. As a result, you cannot access the endpoint’s desktop and
other applications. [CVADHELP‑14589]
System Exceptions
• USB redirection can cause VDAs to experience a fatal exception, displaying a blue screen with
bug check code SYSTEM_THREAD_EXCEPTION_NOT_HANDLED (7e). Also, global lock for USB
redirection might not be released, thus blocking other redirections. [CVADHELP‑9237]
• VDAs might experience a fatal exception on picadm.sys and display a blue screen with bug check
code 0x22. [CVADHELP‑14332]
• After you upgrade a VDA from Version 1912 to Version 2003, the Group Policy engine
(CseEngine.exe) service might exit unexpectedly. [CVADHELP‑14515]
User Experience
• Desktop sessions might display artifacts that obscure screen contents and other portions of the
display. [CVADHELP‑13301]

Virtual Desktop Components – Other
• When you launch an App‑V application from a VDA hosting many App‑V applications, the VDA
might deregister. The issue occurs when the time it takes to process associated policy files is
long. [CVADHELP‑12592]
• When you open a file with the associated published App‑V application, the application opens.
But the file fails to open in the associated application. [CVADHELP‑13971]
• During a call, if a user opens a shared file on Microsoft Teams, the call might disconnect.
[CVADHELP‑14303]
• When you launch an App‑V application using a shortcut that is located outside of the application
package, the appve argument might be added to the command line. This appve argument is
unnecessary. [CVADHELP‑14369]
Known issues
September 17, 2021
The Citrix Virtual Apps and Desktops 7 2006 release contains the following issues. Components and
features that are documented separately have their own known issues articles.
This warning applies to any workaround that suggests changing a registry entry:
Warning:
Editing the registry incorrectly can cause serious problems that might require you to reinstall
your operating system. Citrix cannot guarantee that problems resulting from the incorrect use
of Registry Editor can be solved. Use Registry Editor at your own risk. Be sure to back up the
registry before you edit it.
Install and upgrade
• When you run the Citrix Virtual Apps and Desktops metainstaller, on the Diagnostics page if
you click Connect without first selecting Collect diagnostic information, after you close the
Connect to Citrix Insight Services dialog the Next button is disabled and you cannot move to
next page. To re‑enable the Next button, select and immediately deselect Collect diagnostic
information. [XAXDINST‑572]

General
• If you try to add a protected app to your Favorites, this message might appear, “Your apps are
not available at this time…” When you then click OK, this message appears, “Cannot add app.”
After you switch to the Favorites screen, the protected app is listed there, but you can’t remove
it from Favorites. [WSP‑5497]
• In the Chrome browser with browser content redirection in effect, when you click on a link that
opens a new tab, the tab might not open. As a workaround, select Always allow pop‑ups and
redirects in the Pop‑ups blocked message. [HDX‑23950]
• After installing the Skype for Business Web App Plug‑in, webcams might not be enumerated and
meeting pages on Firefox might not refresh automatically. [HDX‑13288]
• When using Windows 10 1809 LTSC, VCLibs dependencies fail to install. [HDX‑16754]
• The combo box might not display properly when a user selects a combo box that is already in
focus on the host. As a workaround, select another UI element and then select the combo box.
[HDX‑21671]
• You have enabled Local App Access. If you start a Windows 2012 R2 VDA session, disconnect and
reconnect the session, and then start a local application and maximize it, the VDA taskbar might
truncate the application. [HDX‑21913]
• When you use generic USB redirection to redirect a composite USB device that contains a mouse
as a subdevice into an RDS session, that device might not be available in the session. The most
common such device is a Wacom drawing tablet (not Wacom signature pad). As a workaround,
manually start icak2meng.exe in the session after logging on. We suggest creating a group pol‑
icy for Windows Multi‑session OS 2016 or 2019 (not needed for Windows 10) that automatically
starts C:\Program Files\Citrix\HDX\bin\icak2meng.exe. Create the policy to start the
program in each user’s session as they log on. Only one instance running in each user’s session.
The workaround is not need [HDX‑25085]
• When both IPv4 and IPv6 addressing is configured in your network, resources in a delivery group
may not be accessible when the delivery group uses a Broker Access Policy rule configured to
allow IPv4 address filtering only. To ensure all resource filtering behaves as expected, configure
the Broker Access Policy rule to include both client IPv4 and IPv6 addresses. [WADA‑7776]
For example, to set rules allowing IPv4 and IPv6 addresses via ‘direct to StoreFront’ and ‘Citrix
Gateway’ access, use PowerShell such as:
1 Set-BrokerAccessPolicyRule -Name "Apps_Direct" -

IncludedClientIPFilterEnabled $True -IncludedClientIPs @("
10.0.0.1","2001::3")
2 Set-BrokerAccessPolicyRule -Name "Apps_AG" -
IncludedClientIPFilterEnabled $True -IncludedClientIPs @("
10.0.0.1","2001::3")

To confirm a rule, use PowerShell such as:
1 Get-BrokerAccessPolicyRule -Name "Apps_Direct" | Select Name,

IncludedClientIPFilterEnabled,IncludedClientIPs
This returns the following when the rule is correctly set for IPv4 and IPv6 addresses:
1 Name IncludedClientIPFilterEnabled IncludedClientIPs

2 -- --------------------------- -----------------
3 Apps_Direct True {
4 10.0.0.1/32, 2001::3/128 }
• When applications from Microsoft Office 365 build 16.0.7967 and later are published as appli‑
cations from a Windows Server 2019 host, Office license activation fails. This is caused by a
Microsoft limitation. [LCM‑7637]
Director
• If you configure your on‑premises Citrix Virtual Apps and Desktop site with Citrix Analytics for
Performance and your subscription expires, you might experience memory spikes from the Mon‑
itor Service. As a workaround, use the Disconnect Site link on the Analytics tab in your on‑
premises Director console. [DIR‑12625]
• When you try to view the historical utilization of machines on the Machine Details page for VDA
versions 2003 and 2006, the following error message appears (even after you set Enable process
monitoring to Allowed in Citrix Studio).
Process data collection is disabled on this machine. Enable process monitoring policy to
start collection.
As a workaround, set the registry value of HKLM\Software\Citrix\GroupPolicy\

SaveRsopToFile to 1 to view the policy monitoring data in Citrix Director. [DIR‑11794]
• The Console link on Citrix Director > Machine Details does not launch the Machine Console in
the Microsoft Edge 44 and Firefox 68 ESR browsers. [DIR‑8160]
• If you have upgraded to Director 7 1903 or later from any previous releases and not cleared the
browser cache (not selected the ‘Disable cache’ check box), custom reports previously created
are lost and Director displays an “Unexpected Server error” on the Custom Reports tab. Dif‑
ferences in UI design between previous and current versions of Director can cause this issue.
Disable cache and perform a hard refresh to view old custom reports and create and view new
custom reports. [DIR‑7634]

Graphics
• Setting the policy View window contents while dragging to Prohibited does not work on ESXi
and Hyper‑V. [HDX‑22002]
• If you start a video preview using a 64‑bit webcam app over Theora compression, the session
might crash. [HDX‑21443]
• Skype Universal Windows app (UWA) launches with a black background. In some cases, this
background occupies the client’s entire screen. [HDX‑22088]
• In some cases, an application may launch in the background while another application is cur‑
rently in focus. As a result, local window ordering is lost. [HDX‑21569]
• The XenCenter console might display a blank screen after disconnecting a XenDesktop session.
As a workaround, send CTLR+ALT+DEL to the XenCenter console to make the console screen
appear. [HDX‑17261]
• DPI might not match during a session running on Windows Multi‑session OS 2016 or 2019 when
the DPI is changed on the client and the session is reconnected. As a workaround, resize the
session window to match the DPI. [HDX‑17313]
• These issues apply to AMD hardware encoding. [HDX‑20476]:
– Pixelation might occur when using Citrix Workspace app for Windows. As a workaround,
make the following registry setting on the client that has Citrix Workspace app for Windows
installed:
HKEY_LOCAL_MACHINE\Software\Citrix\ICA Client\Engine\Configuration\Advanced\Modules\GfxRender
(32‑bit)
HKEY_LOCAL_MACHINE\Software\Wow6432Node\Citrix\ICA Client\Engine\Configuration\Advanced\Module
(64‑bit)
Name: MaxNumRefFrames
Type: DWORD
Value: 5
– You might see less than optimal performance when using 4k resolution. This issue causes
a frame rate of only 7–10 frames per second. Also, encoding time increases.
– Video stutter might occur for the first two to five seconds of the video when using the Se‑
lective H.264 graphics mode. RapidFire SDK is not designed for this use case.
Printing
• Universal Print Server printers selected on the virtual desktop do not appear in the Devices and
Printers window in Windows Control Panel. However, when users are working in applications,

they can print using those printers. This issue occurs only on the Windows Server 2012, Win‑
dows 10 and Windows 8 platforms. For more information, see CTX213540. [HDX‑5043, 335153]
• The default printer might not be marked correctly in the printing dialog window. This issue does
not affect print jobs sent to the default printer.[HDX‑12755]
Third‑party issues
• Chrome supports UI Automation only for toolbars, tabs, menus, and buttons around a web
page. Because of this Chrome issue, the automatic keyboard display feature might not work
in a Chrome browser on touch devices. As a workaround, run chrome --force-renderer-
accessibility or you can open a new browser tab, type chrome://accessibility, and
enable Native accessibility API support for specific or all pages. In addition, when you pub‑
lish a seamless app, you can publish Chrome with the --force-renderer-accessibility
switch. [HDX‑20858]
• An issue in Microsoft Windows 10 version 1809 might cause slight erratic behavior when using
the Surface Pro and Surface Book pen. [HDX‑17649]
• A VDA running on Azure might freeze when using Enlightened Data Transport (EDT), requiring a
session reconnect. As a workaround, set edtMSS=1350 and OutbufLength=1350 in Azure envi‑
ronments. For more information, see CTX231821. [HDX‑12913]
• In browser content redirection, after starting a YouTube video using the YouTube HTML5 video
player, full‑screen mode might not work. You click the icon in the lower‑right corner of the video,
and the video doesn’t resize leaving the black background in the full area of the page. As a
workaround, click the full screen button, and then select theater mode. [HDX‑11294]
Deprecation
April 14, 2021
The announcements in this article are intended to give you advanced notice of platforms, Citrix prod‑
ucts, and features that are being phased out so that you can make timely business decisions. Citrix
monitors customer use and feedback to determine when they are withdrawn. Announcements can
change in subsequent releases and might not include every deprecated feature or functionality. For
details about product lifecycle support, see the Product Lifecycle Support Policy article. For infor‑
mation about the Long Term Service Release (LTSR) servicing option, see https://support.citrix.com/
article/CTX205549.

Deprecations and removals
The following table shows the platforms, Citrix products, and features that are deprecated or
removed.
Deprecated items are not removed immediately. Citrix continues to support them in Citrix Virtual Apps
and Desktops 7 2003, but they will be removed in a future release.
Removed items are either removed, or are no longer supported, in Citrix Virtual Apps and Desktops.
Dates in bold face indicate changes at this release.
Deprecation
announced in
Item version Removed in version Alternative
Citrix License 2003 2006 Use the Citrix

Administration Licensing Manager.
Console (last
included in the
Windows License
Server 11.16.3 build
30000 and removed
in the Windows
License Server
v11.16.6 build 31000).
Azure and AWS public 2003 2003 Consider using the
cloud (including Virtual Apps and
VMware Cloud on Desktops Service on
AWS) connections. Citrix Cloud.
Citrix Indirect Display 2003 2003 Use Citrix Virtual
Driver (IDD) graphics Apps and Desktops 7
adapter support on 1912 LTSR VDAs.
Windows 10 version
1709 and earlier.
Hardware encoding 2003 2003 Use GRID 10 display
with Nvidia GPUs drivers with Citrix
(NVENC) using GRID 9 Virtual Apps and
or earlier display Desktops 7 2003 or
drivers. later VDAs, or use
Citrix Virtual Apps
and Desktops 7 1912
LTSR VDAs.

Deprecation
announced in
Self‑Service Password 2003 2006

Reset (SSPR) feature.
Citrix SCOM 1912 Use Director for
Management Packs monitoring and
for XenApp and managing your
XenDesktop, deployment. For
Provisioning Services, more information on
and StoreFront. For SCOM EOL and
the product versions alternatives, see
that can be https:
monitored, see Citrix //support.citrix.com/
SCOM Management article/CTX266943.
Packs documention.
Support for Microsoft 1912 2003 Upgrade to .NET
.NET Framework Framework version
versions prior to 4.8.
version 4.8 for VDAs
and core server
components.
Includes Delivery
Controller, Studio,
Director, and
StoreFront.
VDAs on Windows 1912 2003 Install VDAs on a
Server 2012 R2. supported operating
system.
AppDNA application 1909 2003
migration component
of Citrix Virtual Apps
and Desktops
Premium edition.
Installing Studio on 1909 2003 Install on a supported
32‑bit (x86) machines. x64 operating system.

Deprecation
announced in
Support for the Excel 1909 1909

hook in seamless
applications. This
was used for creating
separate taskbar
icons for each
Microsoft Excel 2010
workbook.
Core server 1906 2003 Install on a newer
components on supported operating
Windows Server 2012 system.
R2 (including Service
Packs). Includes:
Delivery Controller,
Studio and Director.
Support for Site 1906 2003 Install databases on a
Configuration, supported Microsoft
Configuration SQL Server version.
Logging, and
Monitoring databases
on Microsoft SQL
Server versions 2008
R2, 2012, and 2014
(including all Service
Packs and editions).
Support for VDAs on 1906 1909* Install VDAs on a
Windows 10 on x86 supported x64
platforms. operating system.
*This feature is still
supported in Citrix
Virtual Apps and
Desktops 7 1912 LTSR.

Deprecation
announced in
Removal of Citrix 1903 1906

Smart Tools Agent
from Citrix Virtual
Apps and Desktops
installation media.
Removal of Citrix 7.15 LTSR CU3
Brokering Protocol
1.0.
Removal of Delivery 1903 1903
Controller options for
the following
end‑of‑life products
within StoreFront:
VDI‑in‑a‑Box, and
XenMobile (9.0 and
earlier).
Support for Linux VDA 1903 1903 Install Linux VDA on a
on Red Hat Enterprise later version of Red
Linux/CentOS 7.5. Hat Enterprise Linux.
StoreFront support 1811 1912 Use Desktop Lock for
for users to access nondomain‑joined
desktops on Desktop use cases.
Appliance sites
Support for 1811 1903 Use Thinwire with
Framehawk display adaptive transport
remoting technology enabled.

Deprecation
announced in
Support for Citrix 1808 1906 Consider using the

Smart Scale in all Virtual Apps and
Citrix Virtual Apps Desktops Service on
and Desktops (and Citrix Cloud for
XenApp and improved power
XenDesktop) management
versions. This functionality.
functionality will
reach End of Life on
31 May 2019.
Support for Microsoft 7.18 1808 Upgrade to .NET
.NET Framework Framework version
versions 4.5.1, 4.5.2, 4.7.1 or later. (The
4.6, 4.6.1, 4.6.2, and installer
4.7 by Citrix automatically installs
StoreFront, Citrix .NET Framework 4.7.1
VDAs, Citrix Studio, if it is not already
Citrix Director, and installed.)
Citrix Delivery
Controller.
Support for Linux VDA 7.18 1808 Install Linux VDA on a
on Red Hat Enterprise later version of Red
Linux 7.3. Hat Enterprise Linux.
StoreFront support 7.17 Upgrade Citrix
for TLS 1.0, and TLS Receivers to a Citrix
1.1 protocols Workspace app that
between Citrix Virtual supports the TLS 1.2
Apps and Desktops protocol. For more
(formerly XenApp and information on Citrix
XenDesktop) and Workspace app, see
Citrix Receiver, and https://docs.citrix.
Workspace Hub. com/en‑us/citrix‑
workspace‑app.

Deprecation
announced in
VDA support for 7.16 7.16 None. Policy setting

policy setting supported with VDAs
“Automatic on earlier OSs only
installation of in‑box (Windows 7, Windows
printer drivers”. Server 2012 R2 and
earlier).
Support for the Linux 7.16 7.16 Install Linux VDA on
VDA on SUSE Linux supported SUSE
Enterprise Server 11 version.
Service Pack 4.
Support for Citrix 7.16 7.16 The Citrix WDDM
WDDM driver on VDAs driver is no longer
installed with VDAs.
Mobility SDK / Mobile 7.16 Superseded by
SDK (from the former mobile experience
Citrix Labs) policy settings, and
native experiences for
hosted
desktops/apps.
VDAs on Windows 10 7.15 LTSR (and 7.12) 7.16 Install Single‑session
version 1511 OS VDAs on Windows
(Threshold 2) and 10 minimum version
earlier Windows 1607 (Redstone 1) or
Single‑session OS newer Semi‑Annual
releases, including Channels. If using
Windows 8.x and 1607 LTSB, we
Windows 7 (see recommend a 7.15
https://www.citrix. VDA. See CTX224843.
com/blogs/2018/01/
08/the‑citrix‑strategy‑
for‑windows‑7‑
virtual‑desktop‑
users/).

Deprecation
announced in
VDAs on Windows 7.15 LTSR (and 7.12) 7.16 Install VDAs on a

Server 2008 R2 and supported operating
Windows Server 2012 system.
(including Service
Packs)
Desktop Composition 7.15 LTSR 7.16 Use Thinwire.
Redirection (
previously known as
DirectX Command
Remoting) (DCR)
Citrix Receiver for 7.15 LTSR (and 1903 Citrix Receiver for
Web classic StoreFront 3.12) Web unified
experience (“green experience.
bubbles” user
interface)
Core components on 7.15 LTSR 7.18 Install components
Windows Server 2012 on a supported
and Windows Server operating system.
2008 R2 (including
Service Packs).
Includes: Delivery
Controller, Studio,
Director, StoreFront,
License Server, and
Universal Print
Server.
Self‑Service Password 7.15 LTSR 7.18 Install on a newer
Reset (SSPR) feature supported operating
on Windows Server system.
2012 and Windows
Server 2008 R2
(including Service
Packs)

Deprecation
announced in
Studio on Windows 7, 7.15 LTSR 7.18 Install Studio on a

Windows 8, and supported operating
Windows 8.1 system.
(including Service
Packs)
Flash Redirection 7.15 LTSR 1912 Create video content
as HTML5 Video. Use
HTML5 Video
Redirection for
managed content,
and Browser Content
Redirection for public
web sites. For more
information, see the
Flash Redirection End
of Life note.
Citrix Online 7.14 (and StoreFront StoreFront 3.12
Integration (Goto 3.11)
product) with
StoreFront
The user account, 7.14 7.14 The Windows service
CtxAppVCOMAdmin, CtxAppVService
which was created performs the same
during VDA function. It is
installation and automatically
added to the Local installed and
Administrators Group configured and
on the VDA machine, requires no user
is no longer created. interaction.
The underlying
“COM” mechanism is
also removed.

Deprecation
announced in
Universal Print Server 7.14 7.14 Install on a newer

UpsServer supported operating
component support system.
on Windows Server
2008 32‑bit
StoreFront and 7.13 7.13
Receiver for Web on
Internet Explorer 8
VDA command line 7.13 7.13 Use the command
installation option line installation
/no_appv to prevent option /exclude
installation of the “Citrix
Citrix App‑V Personalization for
components App‑V – VDA”.
The full‑product 7.13 7.13 Some PowerShell
installer no longer commands that were
installs the Cit‑ provided by the Cit‑
rix.Common.Commands rix.Common.Commands
snap‑in on new snap‑in are still
installations and available in the
automatically XenApp 6.5 SDK. For
removes it when more information,
upgrading existing see section
installations. “Removed features”
in XenApp and
XenDesktop version
7.13 documentation.
Partial functionality 7.13 7.13 Now provided by
to manipulate icon *‑BrokerIcon cmdlets
data that was in the Broker Service.
provided by *‑CtxIcon
cmdlets.

Deprecation
announced in
Legacy Thinwire 7.12 7.16 Use Thinwire. If you

mode are using Legacy
Thinwire mode on
Windows Server 2008
R2, migrate to
Windows Server 2012
R2 or Windows Server
2016, and use
Thinwire.
In‑place upgrades 7.13 7.16 Upgrade from one of
from StoreFront 2.0, these versions to a
2.1, 2.5, and 2.5.2 later supported
version and then to
XenApp and
XenDesktop 7.16.
In‑place upgrades 7.12 7.16 Migrate your
from XenDesktop 5.6 XenDesktop 5.6 or 5.6
or 5.6 FP1 FP1 deployment to
the current
XenDesktop version.
To do this, first
upgrade to
XenDesktop 7.6 LTSR
(with the latest CU),
then upgrade to the
latest Citrix Virtual
Desktops (formerly
XenDesktop) release
or LTSR version.
Installing Delivery 7.12 7.16 Install on a supported
Controller, Director, x64 operating system.
StoreFront, or License
Server on 32‑bit (x86)
machines.
Connection leasing 7.12 7.16 Use Local Host Cache.

Deprecation
announced in
XenDesktop 5.6 used 7.12 7.16 Install VDAs on a

on Windows XP. VDA supported operating
installations on system.
Windows XP are not
supported.
Support for 7.12 2003 Use a different
CloudPlatform supported hypervisor
connections or cloud service.
Support for Azure 7.12 2003 Consider using the
Classic (also known Virtual Apps and
as Azure Service Desktops Service on
Management) Citrix Cloud.
connections
AppDisks 7.13 2003 Use Citrix App
functionality (and the Layering.
AppDNA integration
into Studio, which
supports it)
Personal vDisk 7.15 2006† Use Citrix App
functionality Layering user layer or
user personalization
layer technology.
† At Citrix Virtual Apps and Desktops 7 2003, the Personal vDisk driver was removed from the VDA
installer. At Citrix Virtual Apps and Desktops 7 2006, the Personal vDisk driver workflow is removed
from Studio.
System requirements
April 14, 2021

Introduction
The system requirements in this document were valid when this product version released. Updates
are made periodically. System requirements for components not covered here (such as host systems,
Citrix Workspace app, and Citrix Provisioning) are described in their respective documentation.
Review Prepare to install before beginning an installation.
Unless noted, the component installer deploys software prerequisites automatically (such as .NET
and C++ packages) if the required versions are not detected on the machine. The Citrix installation
media also contains some of this prerequisite software.
The installation media contains several third‑party components. Before using the Citrix software,
check for security updates from the third party, and install them.
For globalization information, see Knowledge Center article CTX119253.
For components and features that can be installed on Windows Servers, Nano Server installations are
not supported, unless noted. Server Core is supported only for Delivery Controllers and Director.
Hardware requirements
RAM and disk space values are in addition to requirements for the product image, operating system,
and other software on the machine. Your performance will vary, depending on your configuration.
This includes the features you use, plus the number of users, and other factors. Using only the mini‑
mum can result in slow performance.
The following table lists the minimum requirements for core components.
Component Minimum
All core components and StoreFront on one 5 GB RAM

server, for an evaluation only, not a production
deployment
All core components and StoreFront on one 12 GB RAM
server, for a test deployment or a small
production environment
Delivery Controller (more disk space required 5 GB RAM, 800 MB hard disk, database: see
for Local Host Cache) Sizing guidance
Studio 1 GB RAM, 100 MB hard disk
Director 2 GB RAM, 200 MB hard disk
StoreFront 2 GB RAM, see the StoreFront documentation
for disk recommendations

Component Minimum
License Server 2 GB RAM; see the Licensing documentation for

disk recommendations
Sizing of VMs that deliver desktops and applications
Specific recommendations cannot be provided because of the complex and dynamic nature of hard‑
ware offerings, and every deployment has unique needs. Generally, sizing a Citrix Virtual Apps VM is
based on the hardware and not the user workloads. The exception is RAM. You’ll need more RAM for
applications that consume more.
For more information:
• Citrix VDI Handbook and Best Practices contains guidance on sizing.

• Citrix Virtual Apps and Desktops Single Server Scalability discusses how many users or VMs can
be supported on a single physical host.
Microsoft Visual C++ 2017 Runtime
Installing Microsoft Visual C++ 2017 Runtime on a machine that has Microsoft Visual C++ 2015 Runtime
installed can result in automatic removal of the Visual C++ 2015 Runtime. This is as designed.
If you’ve already installed Citrix components that automatically install the Visual C++ 2015 Runtime,
those components will continue to operate correctly with the Visual C++ 2017 version.
For more information, see the Microsoft article https://developercommunity.visualstudio.com/

content/problem/332815/visual‑c‑redistributable‑2017‑install‑removes‑visu.html.
Delivery Controller
Supported operating systems:
• Windows Server 2019, Standard and Datacenter Editions, and with the Server Core option
Requirements:
• Microsoft .NET Framework 4.8 is installed automatically if it (or a later version) is not already
installed.
• Microsoft Internet Information Services (installed automatically, and used by a feature currently
in development that is installed by the Citrix Orchestration Service).
• Windows PowerShell 3.0 or later.
• Microsoft Visual C++ 2017 Runtime, 32‑bit and 64‑bit.

Databases
Supported Microsoft SQL Server versions for the site configuration, configuration logging, and moni‑
toring databases:
• SQL Server 2019, Express, Standard, and Enterprise Editions.

• SQL Server 2017, Express, Standard, and Enterprise Editions.
– For new installations: By default, SQL Server Express 2017 with Cumulative Update 16 is
installed when installing the Controller, if an existing supported SQL Server installation is
not detected.
– For upgrades, any existing SQL Server Express version is not upgraded.
• SQL Server 2016 SP2, Express, Standard, and Enterprise Editions.
The following database high availability solutions are supported (except for SQL Server Express, which
supports only standalone mode):
• SQL Server AlwaysOn Failover Cluster Instances

• SQL Server AlwaysOn Availability Groups (including Basic Availability Groups)
• SQL Server Database Mirroring
Windows authentication is required for connections between the Controller and the SQL Server site
database.
Local Host Cache considerations: Microsoft SQL Server Express LocalDB is a feature of SQL Server
Express that Local Host Cache uses on a standalone basis. Local Host Cache does not require any
components of SQL Server Express other than SQL Server Express LocalDB.
• When installing a Controller, Microsoft SQL Server Express LocalDB 2017 with Cumulative Up‑
date 16 is installed for use with the Local Host Cache feature. (This installation is separate from
the default SQL Server Express installation for the site database.)
• When upgrading a Controller, the existing Microsoft SQL Server Express LocalDB version is not
automatially upgraded. For replacement requirements and procedures, see Replace SQL Server
Express LocalDB.
More database information:
• Databases
• CTX114501 lists the most current supported databases
• Database sizing guidance
• Local Host Cache
Citrix Studio
• Windows Server 2019, Standard and Datacenter Editions


• Windows 10 (64‑bit only)
Requirements:
installed.
• Microsoft Management Console 3.0 (included with all supported operating systems).
• Windows PowerShell 3.0 or later.
Citrix Director
Requirements:
installed.
• Microsoft Internet Information Services (IIS) 7.0 and ASP.NET 2.0. Ensure that the IIS server role
has the Static Content role service installed. If this software is not already installed, you are
prompted for the Windows Server installation media. Then, that software is installed for you.
• To view the event logs on machines where Citrix Director is installed, you must install Microsoft
.NET Framework 2.0.
Citrix User Profile Manager:
• Ensure that the Citrix User Profile Manager and Citrix User Profile Manager WMI Plugin are in‑
stalled on the VDA (Additional Components page in the installation wizard) and that the Citrix
Profile Management Service is running to view the user profile details in Director.
System Center Operations Manager (SCOM) integration requirements:
• Windows Server 2012 R2

• System Center 2012 R2 Operations Manager
Supported browsers for viewing Director:
• Internet Explorer 11. Compatibility mode is not supported for Internet Explorer. Use the rec‑
ommended browser settings to access Director. When you install Internet Explorer, accept the
default to use the recommended security and compatibility settings. If you already installed
the browser and chose not to use the recommended settings, go to Tools > Internet Options >
Advanced > Reset and follow the instructions.
• Microsoft Edge.

• Firefox ESR (Extended Support Release).

• Chrome.
The recommended optimal screen resolution for viewing Director is 1366 x 1024.
Virtual Delivery Agent (VDA) for single‑session OS
• Windows 10 (x64 only), minimum version 1607.

– For edition support, see Knowledge Center article CTX224843.
– For Citrix known issues with version 1709, see Knowledge Center article CTX229052.
Requirements:
installed.
• Microsoft Visual C++ 2017 Runtime, 32‑bit and 64‑bit.
Remote PC Access uses this VDA, which you install on physical office PCs. This VDA supports Secure
Boot for Citrix Virtual Desktops Remote PC Access on Windows 10.
Several multimedia acceleration features (such as HDX MediaStream Windows Media Redirection) re‑
quire that Microsoft Media Foundation be installed on the machine on which you install the VDA. If
the machine does not have Media Foundation installed, the multimedia acceleration features will not
be installed and will not work. Do not remove Media Foundation from the machine after installing
the Citrix software. Otherwise, users will not be able to log on to the machine. On most supported
Windows single‑session OS editions, Media Foundation support is already installed and cannot be re‑
moved. However, N editions do not include certain media‑related technologies; you can obtain that
software from Microsoft or a third party. For more information, see Prepare to install.
For Linux VDA information, see the Linux Virtual Delivery Agent articles.
To use the Server VDI feature, you can use the command line interface to install a VDA for Windows
single‑session OS on a Windows Server 2019 or Windows Server 2016 machine. See Server VDI for
guidance.
For information about installing a VDA on a Windows 7 machine, see Earlier operating systems.
Virtual Delivery Agent (VDA) for multi‑session OS


The installer automatically deploys the following requirements, which are also available on the Citrix
installation media in the Support folders:
installed.
• Microsoft Visual C++ 2017 Runtime, 32‑ and 64‑bit.
The installer automatically installs and enables Remote Desktop Services role services, if they are not
already installed and enabled.
Several multimedia acceleration features (such as HDX MediaStream Windows Media Redirection) re‑
quire that the Microsoft Media Foundation be installed on the machine on which you install the VDA. If
the machine does not have Media Foundation installed, the multimedia acceleration features will not
be installed and will not work. Do not remove Media Foundation from the machine after installing the
Citrix software; otherwise, users will not be able to log on to the machine. On most Windows Server
versions, the Media Foundation feature is installed through the Server Manager. For more informa‑
tion, see Prepare to install.
If Media Foundation is not present on the VDA, these multimedia features do not work:
• Windows Media Redirection

• HTML5 Video Redirection
• HDX Realtime Webcam Redirection
For Linux VDA information, see the Linux Virtual Delivery Agent articles.
For information about installing a VDA on a Windows Server 2008 R2 machine, see Earlier operating
systems.
Hosts / virtualization resources

Important:
If you’re upgrading, and your current version uses Microsoft Azure, Amazon Web Services, or
Citrix CloudPlatform connections, see the requirements in Remove unsupported host items.
The following host/virtualization resources (listed alphabetically) are supported. Where applicable,
the major.minor versions are supported, including updates to those versions. Knowledge Center arti‑
cle CTX131239 contains current version information, plus links to known issues.
Some features might not be supported on all host platforms or all platform versions. See the feature
documentation for details.
The Remote PC Access Wake on LAN feature requires Microsoft System Center Configuration Manager
minimum 2012.
• Citrix Hypervisor (formerly XenServer)

CTX131239 contains current version information, plus links to known issues.
For more information, see Citrix Hypervisor virtualization environments.
• Microsoft System Center Virtual Machine Manager
Includes any version of Hyper‑V that can register with the supported System Center Virtual Ma‑
chine Manager versions.
For more information, see Microsoft System Center Virtual Machine Manager virtualization en‑
vironments.
• Nutanix Acropolis
For more information, see Nutanix virtualization environments.
• VMware vSphere (vCenter + ESXi)
No support is provided for vSphere vCenter Linked Mode operation.
For more information, see VMware virtualization environments.
Active Directory functional levels
The following functional levels for the Active Directory forest and domain are supported:
• Windows Server 2016

HDX
Audio
UDP audio for Multi‑Stream ICA is supported on Citrix Workspace app for Windows and Citrix
Workspace app for Linux 13.
Echo cancellation is supported on Citrix Workspace app for Windows.
See the specific HDX feature support and requirements below. For more information on HDX features
and Citrix Workspace apps, see the Feature matrix.

HDX Windows Media delivery
The following clients are supported for Windows Media client‑side content fetching, Windows Media
redirection, and realtime Windows Media multimedia transcoding: Citrix Workspace app for Windows,
Citrix Workspace app for iOS, and Citrix Workspace app for Linux.
To use Windows Media client‑side content fetching on Windows 8 devices, set the Citrix Multimedia
Redirector as a default program: in Control Panel > Programs > Default Programs > Set your de‑
fault programs, select Citrix Multimedia Redirector and click either Set this program as default
or Choose defaults for this program. GPU transcoding requires an NVIDIA CUDA‑enabled GPU with
Compute Capability 1.1 or higher; see https://developer.nvidia.com/cuda/cuda‑gpus.
HDX 3D Pro
The VDA for Windows single‑session OS detects the presence of GPU hardware at runtime.
The physical or virtual machine hosting the application can use GPU Passthrough or Virtual GPU
(vGPU):
• GPU Passthrough is available with:
– Citrix XenServer
– Nutanix AHV
– VMware vSphere and VMware ESX, where it is referred to as virtual Direct Graphics Accel‑
eration (vDGA)
– Microsoft Hyper‑V in Windows Server 2016 where it is referred to as Discrete Device Assign‑
ment (DDA).
• vGPU is available with:
– Citrix Hypervisor
– Nutanix AHV
– VMware vSphere
See https://www.citrix.com/products/xenapp‑xendesktop/hdx‑3d‑pro.html.
Citrix recommends that the host computer have at least 4 GB of RAM and four virtual CPUs with a clock
speed of 2.3 GHz or higher.
Graphical Processing Unit (GPU):
• For CPU‑based compression (including lossless compression), HDX 3D Pro supports any display
adapter on the host computer that is compatible with the application being delivered.
• For virtualized graphics acceleration using the NVIDIA GRID API, you can use HDX 3D Pro with
all the NVIDIA GRID GPUs supported by the GRID 10 driver (see NVIDIA GRID). The NVIDIA GRID
delivers a high frame rate, resulting in a highly interactive user experience.

• Virtualized graphics acceleration is supported on the Intel Xeon Processor E3 Family of data
center graphics platform. For more information, see https://www.citrix.com/intel and https:
//www.intel.com/content/www/us/en/servers/data‑center‑graphics.html.
• Virtualized graphics acceleration is supported with AMD RapidFire on the AMD FirePro S‑series
server cards. See AMD Virtualization Solution).
User device:
• HDX 3D Pro supports all monitor resolutions that are supported by the GPU on the host com‑
puter. However, for optimum performance with the minimum recommended user device and
GPU specifications, Citrix recommends a maximum monitor resolution for user devices of 1920
x 1200 pixels for LAN connections, and 1280 x 1024 pixels for WAN connections.
• Citrix recommends that user devices have at least 1 GB of RAM and a CPU with a clock speed
of 1.6 GHz or higher. Use of the default deep compression codec, which is required on low‑
bandwidth connections, requires a more powerful CPU unless the decoding is done in hard‑
ware. For optimum performance, Citrix recommends that user devices have at least 2 GB of
RAM and a dual‑core CPU with a clock speed of 3 GHz or higher.
• For multi‑monitor access, Citrix recommends user devices with quad‑core CPUs.
• User devices do not need a GPU to access desktops or applications delivered with HDX 3D Pro.
• Citrix Workspace app must be installed.
For more information, see the HDX 3D Pro articles and www.citrix.com/xenapp/3d.
Universal Print Server
The Universal Print Server comprises client and server components. The UpsClient component is in‑
cluded in the VDA installation. You install the UpsServer component on each print server where shared
printers reside that you want to provision with the Citrix Universal Print Driver in user sessions.
The UpsServer component is supported on:

Requirements:
• Microsoft Visual C++ 2017 Runtimes, x86 and x64

• Microsoft .NET Framework 4.8 (minimum)
For VDAs for Multi‑session OS, user authentication during printing operations requires the Universal
Print Server to be joined to the same domain as the VDA.
Standalone client and server component packages are also available for download.
For more information, see Provision printers.

Other
Only Citrix License Server 11.16 and later are supported. For more information, see Licensing.
When using Citrix Provisioning (formerly Provisioning Services) with this release, version 7.x is covered
by the XenApp 7.x/XenDesktop 7.x lifecycle and the Citrix Virtual Apps and Desktops lifecycle. See the
Product Matrix for more information about version compatibility.
For supported StoreFront versions, see the StoreFront system requirements.
The Microsoft Group Policy Management Console (GPMC) is required if you store Citrix pol‑
icy information in Active Directory rather than the site configuration database. If you install
CitrixGroupPolicyManagement_x64.msi separately (for example, on a machine that does not
have a Citrix Virtual Apps and Desktops core component installed), that machine must have Visual
Studio 2015 runtime installed. For more information, see the Microsoft documentation.
If you want to edit domain GPOs using GPMC, enable the Group Policy Management feature (in the
Windows Server Manager) on all machines containing Delivery Controllers.
Multiple network interface cards are supported.
By default, the Citrix Workspace app for Windows is not installed when you install a current VDA. For
more information, see the Citrix Workspace app for Windows documentation.
See App‑V for supported versions of Microsoft App‑V.
See Local App Access for supported browser information for that feature.
This version of Citrix Virtual Apps and Desktops requires a minimum of HDX RealTime Connector 2.9
LTSR. For more information, see the HDX RealTime Optimization Pack documentation.
Technical overview
June 3, 2021
Citrix Virtual Apps and Desktops are virtualization solutions that give IT control of virtual machines,
applications, licensing, and security while providing anywhere access for any device.
Citrix Virtual Apps and Desktops allow:
• End users to run applications and desktops independently of the device’s operating system and
interface.
• Administrators to manage the network and control access from selected devices or from all de‑
vices.
• Administrators to manage an entire network from a single data center.

Citrix Virtual Apps and Desktops share a unified architecture called FlexCast Management Architecture
(FMA). FMA’s key features are the ability to run multiple versions of Citrix Virtual Apps or Citrix Virtual
Desktops from a single site and integrated provisioning.
Learn about product name changes.
Key components
This article is most helpful if you’re new to Citrix Virtual Apps and Desktops. If you currently have a 6.x
or earlier XenApp farm, or a XenDesktop 5.6 or earlier site, see Changes in 7.x.
This illustration shows the key components in a typical deployment, which is called a site.
Delivery Controller
The Delivery Controller is the central management component of a site. Each site has one or more
Delivery Controllers. It is installed on at least one server in the data center. For site reliability and
availability, install Controllers on more than one server. If your deployment includes a hypervisor or
other service, the Controller services communicate with it to:
• Distribute applications and desktops

• Authenticate and manage user access
• Broker connections between users and their desktops and applications
• Optimize use connections
• Load balance these connections.
The Controller’s Broker Service tracks which users are logged on and where, what session resources
the users have, and if users need to reconnect to existing applications. The Broker Service executes
PowerShell cmdlets and communicates with a broker agent on the VDAs over TCP port 80. It does not
have the option to use TCP port 443.

The Monitor Service collects historical data and places it in the monitoring database. This service uses
TCP port 80 or 443.
Data from the Controller services is stored in the site database.
The Controller manages the state of desktops, starting and stopping them based on demand and ad‑
ministrative configuration. In some editions, the Controller allows you to install Profile Management
to manage user personalization settings in virtualized or physical Windows environments.
Database
At least one Microsoft SQL Server database is required for every site to store configuration and session
information. This database stores the data collected and managed by the services that make up the
Controller. Install the database within your data center, and ensure it has a persistent connection to
the Controller.
The site also uses a configuration logging database and a monitoring database. By default, those
databases are installed in the same location as the site database, but you can change this.
Virtual Delivery Agent (VDA)
The VDA is installed on each physical or virtual machine in your site that you make available to users.
Those machines deliver applications or desktops. The VDA enables the machine to register with the
Controller, which in turn allows the machine and the resources it is hosting to be made available to
users. VDAs establish and manage the connection between the machine and the user device. VDAs
also verify that a Citrix license is available for the user or session, and apply policies that are configured
for the session.
The VDA communicates session information to the Broker Service in the Controller through the broker
agent in the VDA. The broker agent hosts multiple plug‑ins and collects real‑time data. It communi‑
cates with the Controller over TCP port 80.
The word “VDA” is often used to refer to the agent and the machine on which it is installed.
VDAs are available for Single‑session and Multi‑session Windows operating systems. VDAs for Multi‑
session Windows operating systems allow multiple users to connect to the server at one time. VDAs
for Single‑session Windows operating systems allow only one user to connect to the desktop at a time.
Linux VDAs are also available.
Citrix StoreFront
StoreFront authenticates users and manages stores of desktops and applications that users access. It
can host your enterprise application store, which gives users self‑service access to the desktops and
applications that you make available to them. It also keeps track of users’ application subscriptions,

shortcut names, and other data. This helps ensure that users have a consistent experience across
multiple devices.
Citrix Workspace app
Installed on user devices and other endpoints (such as virtual desktops), Citrix Workspace app pro‑
vides users with quick, secure, self‑service access to documents, applications, and desktops. Citrix
Workspace app provides on‑demand access to Windows, Web, and Software as a Service (SaaS) ap‑
plications. For devices that cannot install the device‑specific Citrix Workspace app software, Citrix
Workspace app for HTML5 provides a connection through an HTML5‑compatible web browser.
Citrix Studio
Studio is the management console where you configure and manage your Citrix Virtual Apps and Desk‑
tops deployment. Studio eliminates the need for separate management consoles for managing deliv‑
ery of applications and desktops. Studio provides wizards to guide you through environment setup,
creating workloads to host applications and desktops, and assigning applications and desktops to
users. You can also use Studio to allocate and track Citrix licenses for your site.
Studio gets the information it displays from the Broker Service in the Controller, communicating over
TCP port 80.
Citrix Director
Director is a web‑based tool that enables IT support and help desk teams to monitor an environment,
troubleshoot issues before they become system‑critical, and perform support tasks for end users. You
can use one Director deployment to connect to and monitor multiple Citrix Virtual Apps or Citrix Virtual
Desktops sites.
Director displays:
• Real‑time session data from the Broker Service in the Controller, which includes data the Broker
Service gets from the broker agent in the VDA.
• Historical site data from the Monitor Service in the Controller.
Director uses the ICA performance and heuristics data captured by the Citrix Gateway device to build
analytics from the data and then presents it to the administrators.
You can also view and interact with a user’s sessions through Director, using Windows Remote Assis‑
tance.

Citrix License Server
The License Server manages your Citrix product licenses. It communicates with the Controller to man‑
age licensing for each user’s session and with Studio to allocate license files. A site must have at least
one license server to store and manage your license files.
Hypervisor or other service
The hypervisor or other service hosts the virtual machines in your site. These can be the VMs you
use to host applications and desktops, and VMs you use to host the Citrix Virtual Apps and Desktops
components. A hypervisor is installed on a host computer dedicated entirely to running the hypervisor
and hosting virtual machines.
Citrix Virtual Apps and Desktops support various hypervisors and other services.
Although many deployments require a hypervisor, you don’t need one to provide Remote PC Access.
A hypervisor is also not required when you are using Provisioning Services (PVS) to provision VMs.
For more information, see:
• Network ports.
• Databases.
• Windows services in Citrix Virtual Apps and Desktops components: Configure user rights.
• Supported hypervisors and other services: System requirements.
Additional components
The following additional components can also be included in Citrix Virtual Apps and Desktops deploy‑
ments. For more information, see their documentation.
Citrix Provisioning
Citrix Provisioning (formerly Provisioning Services) is an optional component that is available with
some editions. It provides an alternative to MCS for provisioning virtual machines. Whereas MCS cre‑
ates copies of a master image, PVS streams the master image to user devices. PVS doesn’t require a
hypervisor to do this, so you can use it to host physical machines. PVS communicates with the Con‑
troller to provide users with resources.
Citrix Gateway
When users connect from outside the corporate firewall, Citrix Virtual Apps and Desktops can use Citrix
Gateway (formerly Access Gateway and NetScaler Gateway) technology to secure these connections
with TLS. The Citrix Gateway or VPX virtual appliance is an SSL VPN appliance that is deployed in the
demilitarized zone (DMZ). It provides a single secure point of access through the corporate firewall.

Citrix SD‑WAN
In deployments where virtual desktops are delivered to users at remote locations such as branch of‑
fices, Citrix SD‑WAN technology can be employed to optimize performance. Repeaters accelerate per‑
formance across wide‑area networks. With repeaters in the network, users in the branch office ex‑
perience LAN‑like performance over the WAN. Citrix SD‑WAN can prioritize different parts of the user
experience so that, for example, the user experience does not degrade in the branch location when a
large file or print job is sent over the network. HDX WAN optimization provides tokenized compression
and data deduplication, dramatically reducing bandwidth requirements and improving performance.
How typical deployments work
A site is made up of machines with dedicated roles that allow for scalability, high availability, and
failover, and provide a solution that is secure by design. A site consists of VDA‑installed servers and
desktop machines, and the Delivery Controller, which manages access.
The VDA enables users to connect to desktops and applications. It is installed on virtual machines in
the data center for most delivery methods, but it can also be installed on physical PCs for Remote PC
Access.
The Controller is made up of independent Windows services that manage resources, applications,
and desktops, and optimize and balance user connections. Each site has one or more Controllers.
Because sessions are affected by latency, bandwidth, and network reliability, all Controllers ideally
should be on the same LAN.
Users never directly access the Controller. The VDA serves as an intermediary between users and the

Controller. When users log on using StoreFront, their credentials pass through to the Broker Service on
the Controller. The Broker Service then obtains profiles and available resources based on the policies
set for them.
How user connections are handled
To start a session, the user connects either through Citrix Workspace app installed on the user’s device,
or a StoreFront website.
The user selects the physical or virtual desktop or virtual application that is needed.
The user’s credentials move through this pathway to access the Controller, which determines which
resources are needed by communicating with a Broker Service. Citrix recommends that administra‑
tors place an SSL certificate on StoreFront to encrypt the credentials coming from Citrix Workspace
app.
The Broker Service determines which desktops and applications the user is allowed to access.
After the credentials are verified, information about available applications or desktops is sent back to
the user through the StoreFront‑Citrix Workspace app pathway. When the user selects applications or
desktops from this list, that information goes back down the pathway to the Controller. The Controller
then determines the proper VDA to host the specific applications or desktop.
The Controller sends a message to the VDA with the user’s credentials, and then sends all the data
about the user and the connection to the VDA. The VDA accepts the connection and sends the infor‑
mation back through the same pathways to Citrix Workspace app. A set of required parameters is
collected on StoreFront. These parameters are then sent to Citrix Workspace app either as part of the

Citrix‑Workspace‑app‑StoreFront protocol conversation, or converted to an Independent Computing

Architecture (ICA) file and downloaded. As long as the site was properly set up, the credentials remain
encrypted throughout this process.
The ICA file is copied to the user’s device and establishes a direct connection between the device and
the ICA stack running on the VDA. This connection bypasses the management infrastructure (Citrix
Workspace app, StoreFront, and Controller).
The connection between Citrix Workspace app and the VDA uses the Citrix Gateway Protocol (CGP).
If a connection is lost, the Session Reliability feature enables the user to reconnect to the VDA rather
than having to relaunch through the management infrastructure. Session Reliability can be enabled
or disabled in Citrix policies.
After the client connects to the VDA, the VDA notifies the Controller that the user is logged on. The
Controller then sends this information to the site database and starts logging data in the monitoring
database.
How data access works
Every Citrix Virtual Apps and Desktops session produces data that IT can access through Studio or
Director. Using Studio, administrators can access real‑time data from the Broker Agent to manage
sites. Director accesses the same data plus historical data stored in the monitoring database. It also
accesses HDX data from NetScaler Gateway for help desk support and troubleshooting.
Within the Controller, the Broker Service reports session data for every session on the machine provid‑
ing real‑time data. The Monitor Service also tracks the real‑time data and stores it as historical data
in the monitoring database.

Studio communicates only with the Broker Service. It accesses only real‑time data. Director commu‑
nicates with the Broker Service (through a plug‑in in the Broker Agent) to access the site database.
Director can also access Citrix Gateway to get information on the HDX data.
Deliver desktops and applications
You set up the machines that deliver applications and desktops with machine catalogs. Then, you cre‑
ate delivery groups that specify the applications and desktops that will be available (using machines
in the catalogs), and which users can access them. Optionally, you can then create application groups
to manage collections of applications.
Machine catalogs
Machine catalogs are collections of virtual or physical machines that you manage as a single entity.
These machines, and the application or virtual desktops on them, are the resources you provide to
your users. All the machines in a catalog have the same operating system and the same VDA installed.
They also have the same applications or virtual desktops.
Typically, you create a master image and use it to create identical VMs in the catalog. For VMs you
can specify the provisioning method for the machines in that catalog: Citrix tools (Citrix Provisioning
or MCS) or other tools. Alternatively, you can use your own existing images. In that case, you must
manage target devices on an individual basis or collectively using third‑party electronic software dis‑
tribution (ESD) tools.
Valid machine types are:
• Multi‑session OS: Virtual or physical machines with a multi‑session operating system. Used for
delivering Citrix Virtual Apps published apps (also known as server‑based hosted applications)
and Citrix Virtual Apps published desktops (also known as server‑hosted desktops). These ma‑
chines allow multiple users to connect to them at one time.
• Single‑session OS: Virtual or physical machines with a single‑session operating system. Used
for delivering VDI desktops (desktops running single‑session OSs that can optionally be person‑
alized), VM hosted apps (applications from single‑session OSs), and hosted physical desktops.
Only one user at a time can connect to each of these desktops.
• Remote PC Access: Enables remote users to access their physical office PCs from any device
running Citrix Workspace app. The office PCs are managed through the Citrix Virtual Desktops
deployment, and require user devices to be specified in an allow list.
For more information, see Citrix Virtual Apps and Desktops Image Management and Create machine
catalogs.

Delivery groups
Delivery groups specify which users can access which applications, desktops, or both on which ma‑
chines. Delivery groups contain machines from your machine catalogs, and Active Directory users
who have access to your site. You might assign users to your delivery groups by their Active Direc‑
tory group, because Active Directory groups and delivery groups are ways to group users with similar
requirements.
Each delivery group can contain machines from more than one catalog, and each catalog can con‑
tribute machines to more than one delivery group. However, each individual machine can only be‑
long to one delivery group at a time.
You define which resources users in the delivery group can access. For example, to deliver different
applications to different users, you might install all of the applications on the master image for one
catalog and create enough machines in that catalog to distribute among several delivery groups. You
can then configure each delivery group to deliver a different subset of applications that are installed
on the machines.
For more information, see Create delivery groups.
Application groups
Application groups provide application management and resource control advantages over using
more delivery groups. Using the tag restriction feature, you can use your existing machines for
more than one publishing task, saving the costs associated with deployment and managing more
machines. A tag restriction can be thought of as subdividing (or partitioning) the machines in a
delivery group. Application groups can also be helpful when isolating and troubleshooting a subset
of machines in a delivery group.
For more information, see Create application groups.
More information
Citrix Virtual Apps and Desktops diagrams
Active Directory
April 14, 2021
Active Directory is required for authentication and authorization. The Kerberos infrastructure in Ac‑
tive Directory is used to guarantee the authenticity and confidentiality of communications with the
Delivery Controllers. For information about Kerberos, see the Microsoft documentation.

The System requirements article lists the supported functional levels for the forest and domain. To
use Policy Modeling, the domain controller must be running on Windows Server 2003 to Windows
Server 2012 R2; this does not affect the domain functional level.
This product supports:
• Deployments in which the user accounts and computer accounts exist in domains in a sin‑
gle Active Directory forest. User and computer accounts can exist in arbitrary domains within
a single forest. All domain functional levels and forest functional levels are supported in this
type of deployment.
• Deployments in which user accounts exist in an Active Directory forest that is different
from the Active Directory forest containing the computer accounts of the Controllers and
virtual desktops. In this type of deployment, the domains containing the Controller and virtual
desktop computer accounts must trust the domains containing user accounts. Forest trusts or
external trusts can be used. All domain functional levels and forest functional levels are sup‑
ported in this type of deployment.
• Deployments in which the computer accounts for Controllers exist in an Active Directory
forest that is different from one or more additional Active Directory forests that contain
the computer accounts of the virtual desktops. In this type of deployment a bi‑directional
trust must exist between the domains containing the Controller computer accounts and all do‑
mains containing the virtual desktop computer accounts. In this type of deployment, all do‑
mains containing Controller or virtual desktop computer accounts must be at “Windows 2000
native” functional level or higher. All forest functional levels are supported.
• Writable domain controllers. Read‑only domain controllers are not supported.
Optionally, Virtual Delivery Agents (VDAs) can use information published in Active Directory to deter‑
mine which Controllers they can register with (discovery). This method is supported primarily for
backward compatibility, and is available only if the VDAs are in the same Active Directory forest as the
Controllers. For information about this discovery method see Active Directory OU‑based discovery
and CTX118976.
Note:
Do not change the computer name or the domain membership of a Delivery Controller after the
site is configured.
Deploy in a multiple Active Directory forest environment
This information applies to minimum version XenDesktop 7.1 and XenApp 7.5. It does not apply to
earlier versions of XenDesktop or XenApp.
In an Active Directory environment with multiple forests, if one‑way or two‑way trusts are in place
you can use DNS forwarders or conditional forwarders for name lookup and registration. To allow the

appropriate Active Directory users to create computer accounts, use the Delegation of Control wizard.
See the Microsoft documentation for details about this wizard.
No reverse DNS zones are necessary in the DNS infrastructure if appropriate DNS forwarders are in
place between forests.
The SupportMultipleForest key is necessary if the VDA and Controller are in separate forests, re‑
gardless of whether the Active Directory and NetBIOS names are different. Use the following informa‑
tion to add the registry key to the VDA and the Delivery Controllers:
Caution:
Editing the registry incorrectly can cause serious problems that may require you to reinstall your
operating system. Citrix cannot guarantee that problems resulting from the incorrect use of Reg‑
istry Editor can be solved. Use Registry Editor at your own risk. Back up the registry before you
edit it.
On the VDA, configure: HKEY_LOCAL_MACHINE\Software\Citrix\VirtualDesktopAgent\

SupportMultipleForest.
• Name: SupportMultipleForest
• Type: REG_DWORD
• Data: 0x00000001 (1)
On all Delivery Controllers, configure: HKEY_LOCAL_MACHINE\Software\Citrix\DesktopServer

\SupportMultipleForest.
• Name: SupportMultipleForest
• Type: REG_DWORD
• Data: 0x00000001 (1)
You might need reverse DNS configuration if your DNS namespace is different than that of Active Di‑
rectory.
If external trusts are in place during setup, the ListOfSIDs registry key is required. The ListOfSIDs
registry key is also necessary if the Active Directory FQDN is different than the DNS FQDN, or if the
domain containing the Domain Controller has a different NetBIOS name than the Active Directory
FQDN. To add the registry key, use the following information:
For the VDA, locate the registry key HKEY_LOCAL_MACHINE\Software\Citrix\VirtualDesktopAgent

\ListOfSIDs.
• Name: ListOfSIDs
• Type: REG_SZ
• Data: Security Identifier (SID) of the Controllers. (SIDs are included in the results of the Get-
BrokerController cmdlet.)
When external trusts are in place, make the following change on the VDA:

1. Locate the file Program Files\Citrix\Virtual Desktop Agent\brokeragent.exe.

config.
2. Make a backup copy of the file.
3. Open the file in a text editing program such as Notepad.
4. Locate the text allowNtlm="false" and change the text to allowNtlm="true".
5. Save the file.
After adding the ListOfSIDs registry key and editing the brokeragent.exe.config file, restart
the Citrix Desktop Service to apply the changes.
The following table lists the supported trust types:
Supported in this
Trust type Transitivity Direction release
Parent and child Transitive Two‑way Yes

Tree‑root Transitive Two‑way Yes
External Nontransitive One‑way or two‑way Yes
Forest Transitive One‑way or two‑way Yes
Shortcut Transitive One‑way or two‑way Yes
Realm Transitive or One‑way or two‑way No
nontransitive
For more information about complex Active Directory environments, see CTX134971.
Databases
April 14, 2021
A Citrix Virtual Apps or Citrix Virtual Desktops site uses three SQL Server databases:
• Site: (also known as site configuration) stores the running site configuration, plus the current
session state and connection information.
• Configuration logging: (also known as logging) stores information about site configuration
changes and administrative activities. This database is used when the configuring logging fea‑
ture is enabled (default = enabled).
• Monitoring: stores data used by Director, such as session and connection information.
Each Delivery Controller communicates with the site database. Windows authentication is required
between the Controller and the databases. A Controller can be unplugged or turned off without af‑

fecting other Controllers in the site. This means, however, that the site database forms a single point
of failure. If the database server fails, existing connections continue to function until a user either
logs off or disconnects. For information about connection behavior when the site database becomes
unavailable, see Local Host Cache.
Citrix recommends that you back up the databases regularly so that you can restore from the backup
if the database server fails. The backup strategy for each database may differ. For instructions, see
CTX135207.
If your site contains more than one zone, the primary zone should always contain the site database.
Controllers in every zone communicate with that database.
High availability
There are several high availability solutions to consider for ensuring automatic failover:
• AlwaysOn Availability Groups (including Basic Availability Groups): This enterprise‑level

high availability and disaster recovery solution introduced in SQL Server 2012 enables you to
maximize availability for one or more databases. AlwaysOn Availability Groups requires that
the SQL Server instances reside on Windows Server Failover Clustering (WSFC) nodes. For more
information, see Windows Server Failover Clustering with SQL Server.
• SQL Server database mirroring: Mirroring the database ensures that, if you lose the active
database server, an automatic failover process happens in a matter of seconds, so that users
are generally unaffected. This method is more expensive than other solutions because full SQL
Server licenses are required on each database server; you cannot use SQL Server Express edition
in a mirrored environment.
• SQL clustering: The Microsoft SQL clustering technology can be used to automatically allow
one server to take over the tasks and responsibilities of another server that has failed. How‑
ever, setting up this solution is more complicated, and the automatic failover process is typically
slower than alternatives such as SQL mirroring.
• Using the hypervisor’s high availability features: With this method, you deploy the database
as a virtual machine and use your hypervisor’s high availability features. This solution is less
expensive than mirroring because it uses your existing hypervisor software and you can also
use SQL Server Express edition. However, the automatic failover process is slower, as it can
take time for a new machine to start for the database, which may interrupt the service to users.
The Local Host Cache feature supplements the SQL Server high availability best practices by enabling
users to connect and reconnect to applications and desktops even when the site database is not avail‑
able. For more information, see Local Host Cache.
If all Controllers in a site fail, you can configure the VDAs to operate in high availability mode so that
users can continue to access and use their desktops and applications. In high availability mode, the
VDA accepts direct ICA connections from users, rather than connections brokered by the Controller.

Use this feature only on the rare occasion when communication with all Controllers fails; it is not an
alternative to other high availability solutions. For more information, see CTX 127564.
Installing a Controller on a node in an SQL clustering or SQL mirroring installation is not supported.
Install database software
By default, SQL Server Express edition is installed when you install the first Delivery Controller if an‑
other SQL Server instance is not detected on that server. That default action is generally sufficient for
proof of concept or pilot deployments. However, SQL Server Express does not support Microsoft high
availability features.
The default installation uses the default Windows service accounts and permissions. See the Microsoft
documentation for details of these defaults, including the addition of Windows service accounts to the
sysadmin role. The Controller uses the Network Service account in this configuration. The Controller
does not require any additional SQL Server roles or permissions.
If necessary, you can select Hide instance for the database instance. When configuring the address of
the database in Studio, enter the instance’s static port number, rather than its name. See the Microsoft
documentation for details about hiding an instance of SQL Server Database Engine.
Most production deployments, and any deployment that uses Microsoft high availability features,
should use supported non‑Express editions of SQL Server installed on machines other than the server
where the first Controller is installed. The System requirements article lists the supported SQL Server
versions. The databases can reside on one or more machines.
Ensure the SQL Server software is installed before creating a site. You don’t have to create the
database, but if you do, it must be empty. Configuring Microsoft high availability technologies is also
recommended.
Use Windows Update to keep SQL Server up‑to‑date.
Set up the databases from the site creation wizard
Specify the database names and addresses (location) on the Databases page in the site creation wiz‑
ard. (See Database address formats.) To avoid potential errors when Director queries the Monitor
Service, do not use whitespace in the name of the monitoring database.
The Databases page offers two options for setting up the databases: automatic and using scripts.
Generally, you can use the automatic option if you (the Studio user and Citrix administrator) have the
required database privileges. (See Permissions required to set up databases.)
You can change the location of the configuration logging and monitoring database later, after you
create the site. See Change database locations.

To configure a site to use a mirror database, complete the following and then proceed with the auto‑
matic or scripted setup procedures.
1. Install the SQL Server software on two servers, A and B.

2. On Server A, create the database intended to be used as the principal. Back up the database on
Server A and then copy it to server B.
3. On Server B, restore the backup file.
4. Start mirroring on server A.
To verify mirroring after creating the site, run the PowerShell cmdlet get-configdbconnection to
ensure that the Failover Partner has been set in the connection string to the mirror.
If you later add, move, or remove a Delivery Controller in a mirrored database environment, see De‑
livery Controllers.
Automatic setup
If you have the required database privileges, select the “Create and set up databases from Studio”
option on the Databases page of the site creation wizard, and then provide the names and addresses
of the principal databases.
If a database exists at an address you specify, it must be empty. If databases don’t exist at a specified
address, you are informed that a database cannot be found, and then asked if you want the database
to be created for you. When you confirm that action, Studio automatically creates the databases, and
then applies the initialization scripts for the principal and replica databases.
Scripted setup
If you do not have the required database privileges, someone with those permissions must help, such
as a database administrator. Here’s the sequence:
1. In the site creation wizard, select the Generate scripts option. This action generates six scripts:
two for each of the three databases (one for each principal database and another for each
replica). You can indicate where to store the scripts.
2. Give those scripts to your database administrator. The site creation wizard stops automatically
at this point; you’ll be prompted when you return later to continue the site creation.
The database administrator then creates the databases. Each database must have the following char‑
acteristics:
• Use a collation that ends with “_CI_AS_KS”. Citrix recommends using a collation that ends with
“_100_CI_AS_KS”.
• For optimum performance, enable the SQL Server Read‑Committed Snapshot. For details, see
CTX 137161.

• Configured high availability features, if desired.

• To configure mirroring, first set the database to use the full recovery model (simple model is the
default). Back up the principal database to a file and copy it to the mirror server. On the mirror
database, restore the backup file to the mirror server. Then, start mirroring on the principal
server.
The database administrator uses the SQLCMD command‑line utility or SQL Server Management Stu‑
dio in SQLCMD mode to run each of the xxx_Replica.sql scripts on the high availability SQL Server
database instances (if high availability is configured), and then run each of the xxx_Principal.sql scripts
on the principal SQL Server database instances. See the Microsoft documentation for SQLCMD details.
When all the scripts complete successfully, the database administrator gives the Citrix administrator
the three principal database addresses.
In Studio, you are prompted to continue the site creation, and are returned to the Databases page.
Enter the addresses. If any of the servers hosting a database cannot be contacted, an error message
is displayed.
Permissions required to set up databases
You must be a local administrator and a domain user to create and initialize the databases (or change
the database location). You must also have certain SQL Server permissions. The following permis‑
sions can be explicitly configured or acquired by Active Directory group membership. If your Studio
user credentials do not include these permissions, you are prompted for SQL Server user credentials.
Operation Purpose Server role Database role
Create a database Create a suitable dbcreator

empty database
Create a schema Create all securityadmin* db_owner
service‑specific
schemas and add the
first Controller to the
site
Add a Controller Add a Controller securityadmin* db_owner
(other than the first)
to the site
Add a Controller Add a Controller login securityadmin*
(mirror server) to the database
server currently in the
mirror role of a
mirrored database

Operation Purpose Server role Database role
Remove Controller Remove controller ** db_owner

from site
Update a schema Apply schema db_owner
updates or hotfixes
* While technically more restrictive, in practice, the securityadmin server role should be treated as
equivalent to the sysadmin server role.
** When a controller is removed from a site, either directly through Desktop Studio, or using the scripts
generated by Desktop Studio or SDK, the controller logon to the database server is not removed. This
is to avoid potentially removing a logon being used by non‑XenDesktop services on the same machine.
The logon must be removed manually if it is no longer required; this requires securityadmin server role
membership.
When using Studio to perform these operations, the Studio user must either have a database server
account that is explicitly a member of the appropriate server roles, or be able to provide credentials
of an account that is.
Preferred database rights scripts
In enterprise environments, database setup includes scripts that must be handled by different teams
with different roles (rights): securityadmin or db_owner.
Using PowerShell, you can now specify the preferred database rights. (This feature is not available in
Studio, which supports only a single script containing all tasks.)
Specifying a nondefault value results in separate scripts being created. One script contains tasks that
need the securityadmin role. The other script requires only db_owner rights, and can be run by a
Citrix administrator without having to contact a database administrator.
In the get-*DBSchema cmdlets, the -DatabaseRights option has the following valid values:
• SA: Generates a script that creates the databases and the Delivery Controller login. These tasks
require securityadmin rights.
• DBO: Generates a script that creates the user roles in the database, adds the logins, and then
creates the database schemas. These tasks require db_owner rights.
• Mixed: (Default) All tasks in one script, regardless of required rights.
For more information, see the cmdlet help.

Database address formats
You can specify a database address in one of the following forms:
• ServerName
• ServerName\InstanceName
• ServerName,PortNumber
For an AlwaysOn Availability Group, specify the group’s listener in the location field.
Change database locations
After you create a site, you can change the location of the configuration logging and monitoring
databases. (You cannot change the location of the site database.) When you change the location of a
database:
• The data in the previous database is not imported to the new database.
• Logs cannot be aggregated from both databases when retrieving logs.
• The first log entry in the new database indicates that a database change occurred, but it does
not identify the previous database.
You cannot change the location of the configuration logging database when mandatory logging is
enabled.
To change the location of a database:
1. Ensure a supported version of Microsoft SQL Server is installed on the server where you want
the database to reside. Set up high availability features as needed.
2. Select Configuration in the Studio navigation pane.
3. Select the database for which you want to specify a new location and then select Change
Database in the Actions pane.
4. Specify the new location and the database name.
5. If you want Studio to create the database and you have the appropriate permissions, click OK.
When prompted, click OK, and then Studio creates the database automatically. Studio attempts
to access the database using your credentials. If that fails, you are prompted for the database
user’s credentials. Studio then uploads the database schema to the database. The credentials
are retained only for the database creation time frame.
6. If you do not want Studio to create the database, or you do not have sufficient permissions, click
Generate script. The generated scripts include instructions for manually creating the database
and a mirror database, if needed. Before uploading the schema, ensure that the database is
empty and that at least one user has permission to access and change the database.

More information
• Database sizing tool.

• Sizing the site database and configuring connection strings when using SQL Server high avail‑
ability solutions.
Delivery methods
April 14, 2021
Citrix Virtual Apps and Desktops offers various delivery methods. A single delivery method will likely
not meet all of your requirements.
Introduction
Choosing the appropriate application delivery method helps improve scalability, management, and
user experience.
• Installed app: The application is part of the base desktop image. The install process involves
dll, exe, and other files copied to the image drive, in addition to registry modifications. For
details, see Create machine catalogs.
• Streamed app (Microsoft App‑V): The application is profiled and delivered to the desktops
across the network on demand. Application files and registry settings are placed in a container
on the virtual desktop and isolated from the base operating system and each other. This isola‑
tion helps address compatibility issues. For details, see App‑V.
• Layered app (Citrix App Layering): Each layer contains a single application, agent, or operat‑
ing system. By integrating one OS layer, one platform layer (VDA, Citrix Provisioning agent) and
many application layers, an administrator can easily create new, deployable images. Layering
simplifies ongoing maintenance, as an OS, agent, and application exists in a single layer. When
you update the layer, all deployed images containing that layer are updated. For details, see
Citrix App Layering.
• Hosted Windows app: An application installed on a multi‑user Citrix Virtual Apps host and de‑
ployed as an application and not a desktop. A user accesses the hosted Windows app seamlessly
from the VDI desktop or endpoint device, hiding the fact that the app is executing remotely. For
details, see Create delivery groups.
• Local app: An application deployed on the endpoint device. The application interface appears
within the user’s hosted VDI session, even though it executes on the endpoint. For details, see
Local App Access and URL redirection.
• Remote PC Access: Remote PC Access enables employees to remotely access their physical
office PCs. When users access their office PCs, they can access all the applications, data, and

resources they need to do their work. Remote PC Access eliminates the need to introduce and
provide other tools to accommodate teleworking. For details, see Remote PC Access.
For desktops, consider published desktops or VDI desktops.
Citrix Virtual Apps published apps and desktops
Use multi‑session OS machines to deliver Citrix Virtual Apps and Desktops published apps and pub‑
lished desktops.
Use case:
• You want inexpensive server‑based delivery to minimize the cost of delivering applications to
many users, while providing a secure, high‑definition user experience.
• Your users perform well‑defined tasks and do not require personalization or offline access to
applications. Users can include task workers such as call center operators and retail workers,
or users that share workstations.
• Application types: any application.
Benefits and considerations:
• Manageable and scalable solution within your data center.

• Most cost effective application delivery solution.
• Hosted applications are managed centrally and users cannot modify the application. This pro‑
vides a user experience that is consistent, safe, and reliable.
• Users must be online to access their applications.
User experience:
• User requests one or more applications from StoreFront, their Start menu, or a URL you provide.
• Applications are delivered virtually and display seamlessly in high definition on user devices.
• Depending on profile settings, user changes are saved when the user’s application session ends.
Otherwise, the changes are deleted.
Process, host, and deliver applications:
• Application processing takes place on hosting machines, rather than on the user devices. The
hosting machine can be a physical or a virtual machine.
• Applications and desktops reside on a multi‑session OS machine.
• Machines become available through machine catalogs.
• Machines from machine catalogs are organized into delivery groups that deliver the same set of
applications to groups of users.
• Multi‑session OS machines support delivery groups that host either desktops or applications,
or both.
Session management and assignment:

• Multi‑session OS machines run multiple sessions from a single machine to deliver multiple appli‑
cations and desktops to multiple, simultaneously connected users. Each user requires a single
session from which they can run all their hosted applications.
For example, a user logs on and requests an application. One session on that machine becomes
unavailable to other users. A second user logs on and requests an application which that ma‑
chine hosts. A second session on the same machine is now unavailable. If both users request
more applications, no additional sessions are required because a user can run multiple applica‑
tions using the same session. If two more users log on and request desktops, and two sessions
are available on that same machine, that single machine is now using four sessions to host four
different users.
• Within the delivery group to which a user is assigned, a machine on the least loaded server is
selected. A machine with session availability is randomly assigned to deliver applications to a
user when that user logs on.
VM hosted apps
Use single‑session OS machines to deliver VM hosted applications

Use case:
• You want a client‑based application delivery solution that is secure, provides centralized man‑
agement, and supports many users per host server. You want to provide those users with appli‑
cations that display seamlessly in high definition.
• Your users are internal, external contractors, third‑party collaborators, and other provisional
team members. Your users do not require offline access to hosted applications.
• Application types: Applications that might not work well with other applications or might inter‑
act with the operation system, such as Microsoft .NET Framework. These types of applications
are ideal for hosting on virtual machines.
Benefits and considerations:
• Applications and desktops on the master image are securely managed, hosted, and run on ma‑
chines within your data center, providing a more cost‑effective application delivery solution.
• On logon, users can be randomly assigned to a machine within a delivery group that is config‑
ured to host the same application. You can also statically assign a single machine to deliver
an application to a single user each time that user logs on. Statically assigned machines allow
users to install and manage their own applications on the virtual machine.
• Running multiple sessions is not supported on single‑session OS machines. Therefore, each
user consumes a single machine within a delivery group when they log on, and users must be
online to access their applications.
• This method can increase the amount of server resources for processing applications and in‑
crease the amount of storage for users’ data.

User experience:
• The same seamless application experience as hosting shared applications on multi‑session OS

machines.
Process, host, and deliver applications:
• The same as multi‑session OS machines except they are virtual single‑session OS machines.
Session management and assignment:
• Single‑session OS machines run a single desktop session from a single machine. When access‑
ing applications only, a single user can use multiple applications (and is not limited to a single
application) because the operating system sees each application as a new session.
• Within a delivery group, when users log on they can access either a statically assigned machine
(each time the user logs on to the same machine), or a randomly assigned machine that is se‑
lected based on session availability.
VDI desktops
Use single‑session OS machines to deliver Citrix Virtual Apps and Desktops VDI desktops.
VDI desktops are hosted on virtual machines and provide each user with a desktop operating system.
VDI desktops require more resources than published desktops, but do not require that applications
installed on them support server‑based operating systems. Also, depending on the type of VDI desk‑
top you choose, these desktops can be assigned to individual users. This allows users a high level of
personalization.
When you create a machine catalog for VDI desktops, you create one of these types of desktops:
• Random non‑persistent desktop, also known as pooled VDI desktop: Each time a user logs
on to one of these desktops, that user connects to a desktop selected from a pool of desktops.
That pool is based on a single master image. All changes to the desktop are lost when the ma‑
chine restarts.
• Static non‑persistent desktop: During the first logon, a user is assigned a desktop from a pool
of desktops. (Each machine in the pool is based on a single master image.) After the first use,
each time a user logs on to use a desktop, that user connects to the same desktop that was
assigned on first use. All changes to the desktop are lost when the machine restarts.
• Static persistent desktop: Unlike other types of VDI desktops, users can fully personalize these
desktops. During the first logon, a user is assigned a desktop from a pool of desktops. Sub‑
sequent logons from that user connect to the same desktop that was assigned on first use.
Changes to the desktop are retained when the machine restarts.

Network ports
April 14, 2021
The following tables list the default network ports used by Delivery Controllers, Windows VDAs, Di‑
rector, and Citrix License Server. When Citrix components are installed, the operating system’s host
firewall is also updated, by default, to match these default network ports.
For an overview of communication ports used in other Citrix technologies and components, see
CTX101810.
You may need this port information:
• For regulatory compliance purposes.

• If there is a network firewall between these components and other Citrix products or compo‑
nents, so you can configure that firewall appropriately.
• If you use a third‑party host firewall, such as one provided with an anti‑malware package, rather
than the operating system’s host firewall.
• If you alter the configuration of the host firewall on these components (usually Windows Firewall
Service).
• If you reconfigure any features of these components to use a different port or port range, and
then want to disable or block ports that are not used in your configuration. Refer to the docu‑
mentation for the component for details.
• For port information about other components such as StoreFront and Citrix Provisioning (for‑
merly Provisioning Services), see the component’s current “System requirements” article.
The tables list only incoming ports. Outgoing ports are usually determined by the operating system
and use unrelated numbers. Information for outgoing ports is not normally needed for the purposes
listed above.
Some of these ports are registered with the Internet Assigned Numbers Authority (IANA). Details about
these assignments are available at http://www.iana.org/assignments/port‑numbers. However, the
descriptive information held by IANA does not always reflect today’s usage.
Additionally, the operating system on the VDA and Delivery Controller require incoming ports for its
own use. See the Microsoft Windows documentation for details.
VDA, Delivery Controller, and Director

Default
Component Usage Protocol incoming port Notes
VDA ICA/HDX TCP, UDP 1494 EDT protocol

requires 1494 to
be open for UDP.
See ICA policy
settings.
VDA ICA/HDX with TCP, UDP 2598 EDT protocol
Session requires 2598 to
Reliability be open for UDP.
If multi‑stream
and multi‑port
are enabled, the
administrator
defines the port
numbers for the
additional three
streams. See ICA
policy settings.
VDA ICA/HDX over TCP, UDP 443 All Citrix
TLS/DTLS Workspace apps
VDA ICA/HDX over TCP 8008 Citrix Workspace
WebSocket app for HTML5,
and Citrix
Workspace app
for Chrome 1.6
and earlier only
VDA ICA/HDX audio UDP 16500..16509
over UDP
Real‑time
Transport

Default
VDA ICA/Universal TCP 7229 Used by the

Print Server Universal Print
Server print data
stream CGP
(Common
Gateway
Protocol)
listener.
VDA ICA/Universal TCP 8080 Used by the
Print Server Universal Print
Server listener
for incoming
HTTP/SOAP
requests.
VDA Wake On LAN UDP 9 Remote PC
Access power
management
VDA Wake Up Proxy TCP 135 Remote PC
Access power
management
VDA Delivery TCP 80
Controller
Delivery VDA, StoreFront, TCP 80
Controller Director, Studio
Delivery StoreFront, TCP 443
Controller Director, Studio
over TLS
Delivery Delivery TCP 89 Local Host
Controller Controller, VDA Cache (This use
of port 89 might
change in future
releases.)
Delivery Orchestration TCP 9095 Orchestration
Controller

Default
Director Delivery TCP 80, 443

Controller
Citrix Licensing
The following ports are used for Citrix Licensing.
Component Usage Protocol Default incoming port
License Server License Server TCP 27000

License Server License Server for TCP 7279
Citrix (vendor
daemon)
License Server License TCP 8082
Administration
Console
License Server Web Services for TCP 8083
Licensing
HDX
April 14, 2021
Warning:
Citrix HDX represents a broad set of technologies that deliver a high‑definition experience to users of
centralized applications and desktops, on any device and over any network.

HDX is designed around three technical principles:
• Intelligent redirection
• Adaptive compression
• Data de‑duplication
Applied in different combinations, they optimize the IT and user experience, decrease bandwidth con‑
sumption, and increase user density per hosting server.
• Intelligent redirection ‑ Intelligent redirection examines screen activity, application com‑

mands, endpoint device, and network and server capabilities to instantly determine how and
where to render an application or desktop activity. Rendering can occur on either the endpoint
device or hosting server.
• Adaptive compression ‑ Adaptive compression allows rich multimedia displays to be delivered

on thin network connections. HDX first evaluates several variables, such as the type of input,
device, and display (text, video, voice, and multimedia). It chooses the optimal compression
codec and the best proportion of CPU and GPU usage. It then intelligently adapts based on
each unique user and basis. This intelligent adaptation is per user, or even per session.

• Data de‑duplication ‑ De‑duplication of network traffic reduces the aggregate data sent be‑
tween client and server. It does so by taking advantage of repeated patterns in commonly ac‑
cessed data such as bitmap graphics, documents, print jobs, and streamed media. Caching
these patterns allows only the changes to be transmitted across the network, eliminating dupli‑
cate traffic. HDX also supports multicasting of multimedia streams, where a single transmission
from the source is viewed by multiple subscribers at one location, rather than a one‑to‑one con‑
nection for each user.
For more information, see Boost productivity with a high‑definition user workspace.
At the device
HDX uses the computing capacity of user devices to enhance and optimize the user experience. HDX
technology ensures that users receive a smooth, seamless experience with multimedia content in
their virtual desktops or applications. Workspace control enables users to pause virtual desktops and
applications and resume working from a different device at the point where they left off.
On the network
HDX incorporates advanced optimization and acceleration capabilities to deliver the best perfor‑
mance over any network, including low‑bandwidth and high‑latency WAN connections.

HDX features adapt to changes in the environment. The features balance performance and band‑
width. They apply the best technologies for each user scenario, whether the desktop or application is
accessed locally on the corporate network or remotely from outside the corporate firewall.
In the data center
HDX uses the processing power and scalability of servers to deliver advanced graphical performance,
regardless of the client device capabilities.
HDX channel monitoring provided by Citrix Director displays the status of connected HDX channels on
user devices.
HDX Insight
HDX Insight is the integration of NetScaler Network Inspector and Performance Manager with Director.
It captures data about ICA traffic and provides a dashboard view of real time and historical details. This
data includes client‑side and server‑side ICA session latency, bandwidth use of ICA channels, and the
ICA round‑trip time value of each session.
You can enable NetScaler to use the HDX Insight virtual channel to move all the required data points
in an uncompressed format. If you disable this feature, the NetScaler device decrypts and decom‑
presses the ICA traffic spread across various virtual channels. Using the single virtual channel lessens
complexity, enhances scalability, and is more cost effective.
Minimum requirements:
• Citrix Virtual Apps and Desktops 7 v1808

• XenApp and XenDesktop 7.17
• NetScaler version 12.0 Build 57.x
• Citrix Workspace app for Windows 1808
• Citrix Receiver for Windows 4.10
• Citrix Workspace app for Mac 1808
• Citrix Receiver for Mac 12.8
Enable or disable HDX Insight virtual channel
To disable this feature, set the Citrix NetScaler Application Flow service properties to Disabled. To en‑
able, set the service to Automatic. In either case, we recommend that you restart the server machine
after changing these properties. By default, this service is enabled (Automatic).

Experience HDX capabilities from your virtual desktop
• To see how browser content redirection, one of four HDX multimedia redirection technologies,
accelerates delivery of HTML5 and WebRTC multimedia content:
1. Download the Chrome browser extension and install it on the virtual desktop.
2. To experience how browser content redirection accelerates the delivery of multimedia
content to virtual desktops, view a video on your desktop from a website containing
HTML5 videos, such as YouTube. Users don’t know when browser content redirection
is running. To see whether browser content redirection is being used, drag the browser
window quickly. You’ll see a delay or out of frame between the viewport and the user
interface. You can also right‑click on the webpage and look for About HDX Browser
Redirection in the menu.
• To see how HDX delivers high definition audio:
1. Configure your Citrix client for maximum audio quality; see the Citrix Workspace app doc‑
umentation for details.
2. Play music files by using a digital audio player (such as iTunes) on your desktop.
HDX provides a superior graphics and video experience for most users by default, and configuration
isn’t required. Citrix policy settings that provide the best experience for most use cases are enabled
by default.
• HDX automatically selects the best delivery method based on the client, platform, application,
and network bandwidth, and then self‑tunes based on changing conditions.
• HDX optimizes the performance of 2D and 3D graphics and video.
• HDX enables user devices to stream multimedia files directly from the source provider on the
internet or intranet, rather than through the host server. If the requirements for this client‑side
content fetching are not met, media delivery falls back to server‑side content fetching and mul‑
timedia redirection. Usually, adjustments to the multimedia redirection feature policies aren’t
needed.

• HDX delivers rich server‑rendered video content to virtual desktops when multimedia redirec‑
tion is not available: View a video on a website containing high definition videos, such as http:
//www.microsoft.com/silverlight/iis‑smooth‑streaming/demo/.
Good to know:
• For support and requirements information for HDX features, see the System requirements ar‑
ticle. Except where otherwise noted, HDX features are available for supported Windows Multi‑
session OS and Windows Single‑session OS machines, plus Remote PC Access desktops.
• This content describes how to optimize the user experience, improve server scalability, or re‑
duce bandwidth requirements. For information about using Citrix policies and policy settings,
see the Citrix policies documentation for this release.
• For instructions that include editing the registry, use caution: editing the registry incorrectly can
cause serious problems that might require you to reinstall your operating system. Citrix cannot
guarantee that problems resulting from the incorrect use of Registry Editor can be solved. Use
Registry Editor at your own risk. Be sure to back up the registry before you edit it.
Auto client reconnect and session reliability
When accessing hosted applications or desktops, network interruption might occur. To experience a
smoother reconnection, we offer auto client reconnect and session reliability. In a default configura‑
tion, session reliability starts and then auto client reconnect follows.
Auto client reconnect:
Auto client reconnect relaunches the client engine to reconnect to a disconnected session. Auto client
reconnect closes (or disconnects) the user session after the time specified in the setting. If auto client
reconnect is in progress, the system sends application and desktops network interruption notification
to the user as follows:
• Desktops. The session window is grayed out and a countdown timer shows the time until the
reconnections occur.
• Applications. The session window closes and a dialog appears to the user containing a count‑
down timer showing the time until the reconnections are attempted.
During auto client reconnect, sessions relaunch expecting network connectivity. User cannot interact
with sessions while auto client reconnect is in progress.
On reconnection, the disconnected sessions reconnect using saved connection information. The user
can interact with the applications and desktops normally.
Default auto client reconnect settings:
• Auto client reconnect timeout: 120 seconds

• Auto client reconnect: Enabled

• Auto client reconnect authentication: Disabled

• Auto client reconnect Logging: Disabled
For more information, see Auto client reconnect policy settings.
Session reliability:
Session reliability reconnects ICA sessions seamlessly across network interruptions. Session reliabil‑
ity closes (or disconnects) the user session after the time specified in the setting. After the session
reliability timeout, the auto client reconnect settings take effect, attempting to reconnect the user to
the disconnected session. When session reliability is in progress, application and desktops network
interruption notification are sent to the user as follows:
• Desktops. The session window becomes translucent and a countdown timer shows the time
until the reconnections occur.
• Applications. The window becomes translucent along with connection interrupted pop ups
from the notification area.
While session reliability is active, the user cannot interact with the ICA sessions. However, user ac‑
tions like keystrokes are buffered for few seconds immediately after the network interruption and
retransmitted when the network is available.
On reconnection, the client and the server resume at the same point where they were in their ex‑
change of protocol. The session windows lose translucency and appropriate notification area pop
ups are shown for applications.
Default session reliability settings
• Session reliability timeout: 180 seconds
• Reconnection UI opacity level: 80%
• Session reliability connection: Enabled
• Session reliability port number: 2598
For more information, see Session reliability policy settings.
NetScaler with auto client reconnect and session reliability:
If Multistream and Multiport policies are enabled on the server and any or all these conditions are
true, auto client reconnect does not work:
• Session reliability is disabled on NetScaler Gateway.
• A failover occurs on the NetScaler appliance.
• NetScaler SD‑WAN is used with NetScaler Gateway.
HDX adaptive throughput
HDX adaptive throughput intelligently fine‑tunes the peak throughput of the ICA session by adjusting
output buffers. The number of output buffers is initially set at a high value. This high value allows

data to be transmitted to the client more quickly and efficiently, especially in high latency networks.
Providing better interactivity, faster file transfers, smoother video playback, higher framerate and res‑
olution results in an enhanced user experience.
Session interactivity is constantly measured to determine whether any data streams within the ICA
session are adversely affecting interactivity. If that occurs, the throughput is decreased to reduce the
impact of the large data stream on the session and allow interactivity to recover.
Important:
HDX adaptive throughput changes the way that output buffers are set by moving this mechanism
from the client to the VDA, and no manual configuration is necessary.
This feature has the following requirements:
• VDA version 1811 or later

• Workspace app for Windows 1811 or later
For deployments that do not meet the minimum requirements, see Optimize HDX bandwidth over
high latency connections for information about manual output buffer configuration.
Improve the image quality sent to user devices
The following visual display policy settings control the quality of images sent from virtual desktops to
user devices.
• Visual quality. Controls the visual quality of images displayed on the user device: medium, high,
always lossless, build to lossless (default = medium). The actual video quality using the default
setting of medium depends on available bandwidth.
• Target frame rate. Specifies the maximum number of frames per second that are sent from the
virtual desktop to the user device (default = 30). For devices that have slower CPUs, specifying a
lower value can improve the user experience. The maximum supported frame rate per second
is 60.
• Display memory limit. Specifies the maximum video buffer size for the session in kilobytes (de‑
fault = 65536 KB). For connections requiring more color depth and higher resolution, increase
the limit. You can calculate the maximum memory required.
Improve video conference performance
Several popular video conferencing applications are optimized for delivery from Citrix Virtual Apps
and Desktops through multimedia redirection (see, for example, HDX RealTime Optimization Pack).
For applications that are not optimized, HDX webcam video compression improves bandwidth effi‑
ciency and latency tolerance for webcams during video conferencing in a session. This technology

streams webcam traffic over a dedicated multimedia virtual channel. This technology uses less band‑
width compared to the isochronous HDX Plug‑n‑Play USB redirection support, and works well over
WAN connections.
Citrix Workspace app users can override the default behavior by choosing the Desktop Viewer Mic &
Webcam setting Don’t use my microphone or webcam. To prevent users from switching from HDX
webcam video compression, disable USB device redirection by using the policy settings under ICA
policy settings > USB Devices policy settings.
HDX webcam video compression requires that the following policy settings be enabled (all are en‑
abled by default).
• Client audio redirection

• Client microphone redirection
• Multimedia conferencing
• Windows Media Redirection
If a webcam supports hardware encoding, HDX video compression uses the hardware encod‑
ing by default. Hardware encoding might consume more bandwidth than software encod‑
ing. To force software compression, add the following DWORD key value to the registry key:
HKCU\Software\Citrix\HdxRealTime: DeepCompress_ForceSWEncode=1.
Network traffic priorities
Priorities are assigned to network traffic across multiple connections for a session using Quality of
Service supported routers. Four TCP streams and two User Datagram Protocol (UDP) streams are avail‑
able to carry ICA traffic between the user device and the server:
• TCP streams ‑ real time, interactive, background, and bulk

• UDP streams ‑ voice and Framehawk display remoting
Each virtual channel is associated with a specific priority and transported in the corresponding con‑
nection. You can set the channels independently, based on the TCP port number used for the connec‑
tion.
Multiple channel streaming connections are supported for Virtual Delivery Agents (VDAs) installed on
Windows 10, Windows 8, and Windows 7 machines. Work with your network administrator to ensure
the Common Gateway Protocol (CGP) ports configured in the Multi‑Port Policy setting are assigned
correctly on the network routers.
Quality of Service is supported only when multiple session reliability ports, or the CGP ports, are con‑
figured.

Warning:
Use transport security when using this feature. Citrix recommends using Internet Protocol Se‑
curity (IPsec) or Transport Layer Security (TLS). TLS connections are supported only when the
connections traverse a NetScaler Gateway that supports multi‑stream ICA. On an internal corpo‑
rate network, multi‑stream connections with TLS are not supported.
To set Quality of Service for multiple streaming connections, add the following Citrix policy settings
to a policy (see Multi‑stream connections policy settings for details):
• Multi‑Port policy ‑ This setting specifies ports for ICA traffic across multiple connections, and
establishes network priorities.
– Select a priority from the CGP default port priority list. By default, the primary port (2598)
has a High priority.
– Type more CGP ports in CGP port1, CGP port2, and CGP port3 as needed, and identify pri‑
orities for each. Each port must have a unique priority.
Explicitly configure the firewalls on VDAs to allow the additional TCP traffic.
• Multi‑Stream computer setting ‑ This setting is disabled by default. If you use Citrix NetScaler
SD‑WAN with Multi‑Stream support in your environment, you do not need to configure this set‑
ting. Configure this policy setting when using third‑party routers or legacy Branch Repeaters to
achieve the desired Quality of Service.
• Multi‑Stream user setting ‑ This setting is disabled by default.
For policies containing these settings to take effect, users must log off and then log on to the network.
Show or hide the remote language bar
The language bar displays the preferred input language in an application session. If this feature is en‑
abled (default), you can show or hide the language bar from the Advanced Preferences > Language
bar UI in Citrix Workspace app for Windows. By using a registry setting on the VDA side, you can dis‑
able client control of the language bar feature. If this feature is disabled, the client UI setting doesn’t
take effect, and the per user current setting determines the language bar state. For more information,
see Improve the user experience.
To disable client control of the language bar feature from the VDA:
1. In the registry editor, navigate to HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Citrix\wfshell\

2. Create a DWORD value key, SeamlessFlags, and set it to 0x40000.

Unicode keyboard mapping
Non‑Windows Citrix Receivers use the local keyboard layout (Unicode). If a user changes the local
keyboard layout and the server keyboard layout (scan code), they might not be in sync and the output
is incorrect. For example, User1 changes the local keyboard layout from English to German. User1
then changes the server‑side keyboard to German. Even though both keyboard layouts are German,
they might not be in sync causing incorrect character output.
Enable or disable Unicode keyboard layout mapping
By default, the feature is disabled on the VDA side. To enable the feature, toggle on the feature by
using registry editor regedit on the VDA. Add the following registry key:
KEY_LOCAL_MACHINE/SOFTWARE/Citrix/CtxKlMap
Name: EnableKlMap
Type: DWORD
Value: 1
To disable this feature, set EnableKlMap to 0 or delete the CtxKlMap key.
Enable Unicode keyboard layout mapping compatible mode
By default, Unicode keyboard layout mapping automatically hooks some windows API to reload the
new Unicode keyboard layout map when you change the keyboard layout on the server side. A few ap‑
plications cannot be hooked. To keep compatibility, you can change the feature to compatible mode
to support these non‑hooked applications. Add the following registry key:
HKEY_LOCAL_MACHINE/SOFTWARE/Citrix/CtxKlMap
Name: DisableWindowHook
Type: DWORD
Value: 1
To use normal Unicode keyboard layout mapping, set DisableWindowHook to 0.
Adaptive transport
July 14, 2021

Adaptive Transport is a mechanism in Citrix Virtual Apps and Desktops that provides the ability to use
Enlightened Data Transport (EDT) as the transport protocol for ICA connections. Adaptive Transport
switches to TCP when EDT is not available.
EDT is a Citrix‑proprietary transport protocol built on top of User Datagram Protocol (UDP). It delivers
a superior user experience on challenging long‑haul connections while maintaining server scalability.
EDT improves data throughput for all ICA virtual channels on unreliable networks, providing a better
and more consistent user experience.
When Adaptive Transport is set to Preferred, EDT is used as the primary transport protocol and TCP is
used for fallback. By default, Adaptive Transport is set to Preferred. You can set Adaptive Transport
to Diagnostic mode for testing purposes, which only allows EDT and disables the fallback to TCP.
With Citrix Workspace app for Windows, Mac, and iOS, EDT and TCP connections are attempted in par‑
allel during the initial connection, session reliability reconnection, and automatic client reconnection.
Doing so reduces the connection time if the underlying UDP transport is unavailable and TCP must be
used instead. If Adaptive Transport is set to Preferred and the connection is established using TCP,
Adaptive Transport continues to attempt to switch to EDT every five minutes.
With Citrix Workspace app for Linux and Android, EDT connections are attempted first. If the connec‑
tion is unsuccessful, Citrix Workspace app tries to connect using TCP after the EDT request times out.

System requirements
The following are the requirements for using Adaptive Transport and EDT:
• Control plane
– Citrix Virtual Apps and Desktops Service

– Citrix Virtual Apps and Desktops 1912 or later
• Virtual Delivery Agent
– Version 1912 or later (2103 or later recommended)

– Version 2012 is the minimum required for using EDT with Citrix Gateway Service
• StoreFront
– Version 3.12.x
– Version 1912.0.x
• Citrix Workspace app
– Windows: version 1912 or later (2105 or later recommended)

– Linux: version 1912 or later (2104 or later recommended)
– Mac: version 1912 or later
– iOS: latest version available in Apple App Store
– Android: latest version available in Google Play
• Citrix Gateway (ADC)
– 13.0.52.24 or later
– 12.1.56.22 or later
• Firewall (from VDA perspective)
• UDP 1494 inbound – if session reliability is disabled

• UDP 2598 inbound – if session reliability is enabled
• UDP 443 inbound – if VDA SSL is enabled for ICA encryption (DTLS)
• UDP 443 outbound – if using Citrix Gateway Service. For more information, see the Citrix Gate‑
way service documentation.
Considerations
• Enable session reliability to use EDT MTU Discovery and to use EDT with Citrix Gateway and
Citrix Gateway service.
• Ensure that the EDT MTU is adequately set to avoid fragmentation. Otherwise, performance can
be impacted or sessions might fail to launch in some situations. For more information, see the
EDT MTU Discover.
• For details on requirements and considerations for using EDT with Citrix Gateway service, see
HDX Adaptive Transport with EDT support for Citrix Gateway service.
• For details on Citrix Gateway configuration to support EDT, see Configure Citrix Gateway to sup‑
port Enlightened Data Transport and HDX Insight.
• IPv6 is not supported currently.
Configuration
Adaptive Transport is enabled by default. You can configure the following options using the HDX
Adaptive Transport setting in Citrix policy.
• Preferred. This is the default setting. Adaptive Transport is enabled, and it uses EDT as the
preferred transport protocol, with fallback to TCP.
• Diagnostic mode. Adaptive Transport is enabled, and it forces the use of EDT. Fallback to TCP
is disabled. This setting is recommended for testing and troubleshooting only.
• Off. Adaptive Transport is disabled, and only TCP is used for transport.
To confirm that EDT is being used as the transport protocol for the session, you can use Director or the
CtxSession.exe command‑line utility on the VDA.
In Director, look up the session and select Details. If the Connection type is HDX and the Protocol is
UDP, EDT is being used as the transport protocol for the session. If the Connection type is RDP, ICA
is not in use, and the Protocol displays N/A. For more information, see Monitor sessions.

To use the CtxSession.exe utility, launch a Command Prompt or PowerShell within the session and run
ctxsession.exe. To see verbose statistics, run ctxsession.exe -v. If EDT is in use, the transport
protocol shows one of the following:
• UDP > ICA (Session Reliability disabled)

• UDP > CGP > ICA (Session Reliability enabled)
• UDP > DTLS > CGP > ICA (ICA is DTLS‑encrypted end‑to‑end)

EDT MTU Discovery
MTU Discovery allows EDT to automatically determine the Maximum Transmission Unit (MTU) when
establishing a session. Doing so prevents EDT packet fragmentation that might result in performance
degradation or failure to establish a session.
Requirements
• VDA minimum version 1912 (2103 or later recommended)

• Citrix Workspace app 1911 for Windows
• Citrix ADC:
– 13.0.52.24
– 12.1.56.22
• Session Reliability must be enabled
If you use client platforms or versions that don’t support this feature, see CTX231821 for details about
configuring a custom EDT MTU that is appropriate for your environment.
Important:
MTU Discovery is not supported with Multi‑Stream ICA.
To enable or disable EDT MTU Discovery on the VDA
Set the following registry key:

• Key: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Terminal Server\Wds\icawd

• Value name: MtuDiscovery
• Value type: DWORD
• Value data: 00000001
Restart the VDA and wait for the VDA to register.
To disable EDT MTU Discovery, delete this registry value and restart the VDA.
This setting is machine‑wide and affects all sessions connecting from a supported client.
Warning:
To control EDT MTU Discovery on the client
You can control EDT MTU Discovery selectively on the client by adding the MtuDiscovery parameter
in the ICA file. To disable the feature, set the following under the Application section:
MtuDiscovery=Off
To re‑enable the feature, remove the MtuDiscovery parameter from the ICA file.
Important:
For this ICA file parameter to work, enable the feature on the VDA. If the feature is not enabled
on the VDA, the ICA file parameter has no effect.
Loss tolerant mode

Important:
• The feature requires a minimum of Citrix Workspace app 2002 for Windows.
• Loss tolerant mode is not supported on Citrix Gateway or Citrix Gateway Service. This mode
is available only with direct connections.
Loss tolerant mode uses the EDT Lossy transport protocol to enhance the user experience for users
connecting through networks with high latency and packet loss.
Initially, sessions are established using EDT. If the latency and packet loss thresholds are reached or
surpassed, the applicable virtual channels switch from EDT to EDT Lossy, while leaving the other vir‑
tual channels on EDT. If the latency and packet loss decrease below the thresholds, the applicable
virtual channels switch back to EDT.
The default thresholds are:

• Packet loss: 5%
• Latency: 300 ms (RTT)
Loss tolerant mode is enabled by default. You can disable the mode or adjust the packet loss and
latency thresholds using the loss tolerant mode thresholds setting.
Requirements
• Citrix Virtual Delivery Agent (VDA) 2003

• Citrix Workspace app 2002 for Windows
• Session reliability enabled. For more information about session reliability, see Session reliabil‑
ity policy settings.
Known issues
Adaptive Transport and EDT contain the following issues:
• Packet fragmentation can cause performance degradation or even failure to launch sessions.
You can adjust the EDT MTU to avoid this. Use MTU Discovery or the workaround described in
CTX231821.
• A grey or black screen may appear when launching a session from a Windows client if MTU Dis‑
covery is enabled. To address this issue, upgrade to Workspace app for Windows 2105 or later
or Workspace app for Windows 1912 CU4 or later.
• Fallback to TCP may fail on Linux and Android clients when connecting through Citrix Gateway
or Citrix Gateway Service. This happens when there is a successful EDT negotiation between
the client and the Gateway, and the EDT negotiation fails between the Gateway and the VDA.
To address this issue, upgrade to Workspace app for Linux 2104 or later and Workspace app for
Android 21.5 or later.
• Asymmetrical network paths can cause MTU Discovery to fail for connections that do not go
through Citrix Gateway or Citrix Gateway Service. To address this issue, upgrade to VDA version
2103 or later. [CVADHELP‑16654]
• When using Citrix Gateway or Citrix Gateway Service, asymmetrical network paths can cause
MTU Discovery to fail. This is due to an issue on Gateway that causes the Don’t Fragment (DF)
bit in the EDT packets’ header not to be propagated. A fix for this issue is not yet available.
[CGOP‑18438]
• MTU Discovery may fail for users that connect through a DS‑Lite network. Some modems fail to
honor the DF bit when packet processing is enabled, preventing MTU Discovery from detecting
fragmentation. In this situation, these are the available options:
– Disable packet processing on the user’s modem.

– Disable MTU Discovery and use a hardcoded MTU as described in CTX231821.

– Disable Adaptive Transport to force sessions to use TCP. If only a subset of users is affected,
consider disabling it on the client‑side so that other users can continue to use EDT.
Troubleshoot
To troubleshoot Adaptive Transport and EDT, we suggest the following:
1. Thoroughly review and validate the requirements, considerations, and known issues.
2. Check if there are Citrix policies in Studio or GPO overwriting the desired HDX Adaptive Trans‑
port setting.
3. Check if there are settings on the client overwriting the desired HDX Adaptive Transport setting.
This can be a GPO preference, a setting configured using the optional Workspace app adminis‑
trative template, or a manual configuration of the HDXoverUDP setting in the registry or client’s
configuration file.
4. On multi‑session VDA machines, ensure that the UDP listeners are active. Open a command
prompt in the VDA machine and run netstat -a -p udp. For more information, see How to
Confirm HDX Enlightened Data Transport Protocol.
5. Launch a direct session internally, bypassing the Citrix Gateway, and check the protocol in use.
If the session uses EDT, the VDA is ready to use EDT for external connections through Citrix Gate‑
way.
6. If EDT works for direct internal connections and not for sessions going through Citrix Gateway:
• Ensure that Session Reliability is enabled

• Ensure that the Gateway has DTLS enabled
7. Check if the appropriate firewall rules have been configured in both network firewalls and fire‑
walls running on the VDA machines.
8. Check if your users’ connections require a non‑standard MTU. Connections with an effective
MTU lower than 1500 bytes cause EDT packet fragmentation, which in turn can affect perfor‑
mance or even cause session launch failures. This issue is common when using VPN, some Wi‑Fi
access points, and mobile networks, such as 4G and 5G. For information on how to address this
issue, see the MTU Discovery section.
Interoperability with Citrix SD‑WAN
Citrix SD‑WAN WAN optimization (WANOP) offers cross‑session tokenized compression (data dedupli‑
cation), including URL‑based video caching, providing significant bandwidth reduction. The reduc‑
tion occurs if two or more people at the office location watch the same client‑fetched video or trans‑
fer or print significant portions of the same file or document. Furthermore, by running the processes

for ICA data reduction and print job compression on the branch office appliance, WANOP offers VDA
server CPU offload and enables higher Citrix Virtual Apps and Desktops server scalability.
Currently, SD‑WAN WANOP does not support EDT. However, there is no need to disable Adaptive Trans‑
port if SD‑WAN WANOP is in use. When a user launches a session that goes through an SD‑WAN with
WANOP enabled, it automatically sets the session to use TCP as the transport protocol. Non‑WANOP
sessions continue to use EDT whenever possible.
Citrix ICA virtual channels
April 14, 2021
Warning:
What are ICA virtual channels?
A large portion of the functionality and communication between the Citrix Workspace app and the
Citrix Virtual Apps and Desktops servers occurs over virtual channels. Virtual channels are a necessary
part of the remote computing experience with the Citrix Virtual Apps and Desktops servers. Virtual
channels are used for:
• Audio
• COM ports
• Disks
• Graphics
• LPT ports
• Printers
• Smart cards
• Third‑party custom virtual channels
• Video
New virtual channels are sometimes released with new versions of the Citrix Virtual Apps and Desk‑
tops servers and Citrix Workspace app products to provide more functionality.

A virtual channel consists of a client‑side virtual driver that communicates with a server‑side applica‑
tion. Citrix Virtual Apps and Desktops ship with various virtual channels included. They’re designed
to allow customers and third‑party vendors to create their own virtual channels by using one of the
provided Software Development Kits (SDKs).
Virtual channels provide a secure way to accomplish various tasks. For example, an application that
is running on a Citrix Virtual Apps server that is communicating with a client‑side device or an appli‑
cation that is communicating with the client‑side environment.
On the client side, virtual channels correspond to virtual drivers. Each virtual driver provides a specific
function. Some are required for normal operation, and others are optional. Virtual drivers operate at
the presentation layer protocol level. There can be several protocols active at any time by multiplexing
channels that are provided by the Windows Station (WinStation) protocol layer.
The following functions are contained in the VirtualDriver registry value under this registry path:
HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\ICA Client\Engine\Configuration\Advanced
\Modules\ICA 3.0
Or

HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Citrix\ICA Client\Engine\Configuration
\Advanced\Modules\ICA 3.0 (for 64‑bit)
• Thinwire3.0 (Required)
• ClientDrive
• ClentPrinterQueue
• ClentPrinterPort
• Clipboard
• ClientComm
• ClientAudio
• LicenseHandler (Required)
• TWI (Required)
• SmartCard
• ICACTL (Required)
• SSPI
• TwainRdr
• UserEXperience
• Vd3d
Note:
You can disable specific client functionality by removing one or more of these values from the
registry key. For example, if you wanted to remove the Client Clipboard, remove the word Clip‑
board.
This list contains the client virtual driver files and their respective functions. Citrix Virtual Apps and
Citrix Workspace app for Windows use these files. They are in the form of Dynamic Link Libraries (user
mode), and not Windows drivers (kernel mode) except for Generic USB as described in the Generic
USB virtual channel.
• vd3dn.dll – Direct3D virtual channel used for desktop composition redirection

• vdcamN.dll – Bidirectional audio
• vdcdm30n.dll – Client drive mapping
• vdcom30N.dll ‑ Client COM port mapping
• vdcpm30N.dll – Client printer mapping
• vdctln.dll – ICA controls channel
• vddvc0n.dll – Dynamic virtual channel
• vdeuemn.dll ‑ End user experience monitoring
• vdgusbn.dll – Generic USB virtual channel
• vdkbhook.dll – Transparent key pass‑through
• vdlfpn.dll – Framehawk display channel over UDP like transport
• vdmmn.dll – Multimedia support
• vdmrvc.dll – Mobile Receiver virtual channel

• vdmtchn.dll ‑ Multi‑touch support

• vdscardn.dll – Smartcard support
• vdsens.dll – Sensors virtual channel
• vdspl30n.dll – Client UPD
• vdsspin.dll – Kerberos
• vdtuin.dll – Transparent UI
• vdtw30n.dll – Client Thinwire
• vdtwin.dll – Seamless
• vdtwn.dll – Twain
Some virtual channels are compiled into other files. For example Clipboard Mapping is available in
wfica32.exe
64‑bit compatibility
Citrix Workspace app for Windows is 64‑bit compatible. As with most of the binaries compiled for 32
bit, these client files have 64‑bit compiled equivalents:
• brapi64.dll
• confmgr.dll
• ctxlogging.dll
• ctxmui.dll
• icaconf.exe
• icaconfs.dll
• icafile.dll
• pnipcn64.dll
• pnsson.dll
• ssoncom.exe
• ssonstub.dll
• vdkbhook64.dll
Generic USB virtual channel
Generic USB virtual channel implementation uses two kernel mode drivers along with the virtual chan‑
nel driver vdgusbn.dll:
• ctxusbm.sys
• ctxusbr.sys

How ICA virtual channels work
Virtual channels are loaded in multiple ways. The Shell (WfShell for the server and PicaShell for the
workstation) load some virtual channels. Some virtual channels are hosted as windows services.
Virtual channel modules loaded by the Shell, for example:
• EUEM
• Twain
• Clipboard
• Multimedia
• Seamless session sharing
• Time Zone
Some are loaded as kernel mode, for example:
• CtxDvcs.sys – Dynamic virtual channel

• Icausbb.sys – Generic USB redirection
• Picadm.sys – Client drive mapping
• Picaser.sys – COM port redirection
• Picapar.sys – LPT port redirection
Graphics virtual channel on the server side
Starting with XenApp 7.0 and XenDesktop7.0, ctxgfx.exe hosts the graphics virtual channel for both
workstation and terminal server based sessions. Ctxgfx hosts platform specific modules that inter‑
act with the corresponding driver (Icardd.dll for RDSH and vdod.dll and vidd.dll for worksta‑
tion).
For XenDesktop 3D Pro deployments an OEM graphics driver is installed for the corresponding GPU
on the VDA. Ctxgfx loads specialized adaptor modules to interact with the OEM graphics driver.
Hosting specialized channels in windows services
On Citrix Virtual Apps and Desktops servers, various channels are hosted as windows services. Such
hosting provides one‑to‑many semantics for multiple applications in a session and multiple sessions
on the server. Examples of such services include:
• Citrix Device Redirector Service

• Citrix Dynamic Virtual Channel Service
• Citrix End User Experience Monitoring Service
• Citrix Location and Sensor Virtual Channel Service
• Citrix MultiTouch Redirection Service
• Citrix Print Manager Service

• Citrix Smartcard Service

• Citrix Audio Redirection Service (Citrix Virtual Desktops only)
The audio virtual channel on Citrix Virtual Apps is hosted using Windows Audio service.
On the server side, all client virtual channels are routed through the WinStation driver, Wdica.sys.
On the client side, the corresponding WinStation driver, built into wfica32.exe, polls the client virtual
channels. This image illustrates the virtual channel client‑server connection.
This overview contains a client‑server data exchange using a virtual channel.
1. The client connects to the Citrix Virtual Apps and Desktops server. The client passes information
about the virtual channels it supports to the server.
2. The server‑side application starts, obtains a handle to the virtual channel, and optionally
queries for additional information about the channel.
3. The client virtual driver and server‑side application pass data using the following two methods:
• If the server application has data to send to the client, the data is sent to the client imme‑
diately. When the client receives the data, the WinStation driver de‑multiplexes the virtual
channel data from the ICA stream and immediately passes it to the client virtual driver.
• If the client virtual driver has data to send to the server, the data is sent the next time the
WinStation driver polls it. When the server receives the data, it is queued until the virtual

channel application reads it. There is no way to alert the server virtual channel application
that data was received.
4. When the server virtual channel application is completed, it closes the virtual channel and frees
any allocated resources.
Creating your own virtual channel using the Virtual Channel SDK
Creating a virtual channel using the Virtual Channel SDK requires intermediate programming knowl‑
edge. Use this method to provide a major communication path between the client and the server. For
example, if you are implementing usage of a device on the client side, such as a scanner, to be used
with a process in the session.
Note:
• The Virtual Channel SDK requires the WFAPI SDK to write the server side of the virtual chan‑
nel.
• Because of enhanced security for Citrix Virtual Apps and Desktops and Citrix Workspace app
for Windows, you must take an extra step when installing a custom virtual channel.
Creating your own virtual channel using the ICA Client Object SDK
Creating a virtual channel using the ICA Client Object (ICO) is easier than using the Virtual Channel
SDK. Use the ICO by creating a named object in your program using the CreateChannels method.
Important:
Because of enhanced security starting with the 10.00 version of the Citrix Receiver for Windows
and later (and Citrix Workspace apps for Windows), you must take an extra step when creating
an ICO virtual channel.
For more information, see Client Object API Specification Programmer’s Guide.
Pass‑through functionality of virtual channels
Most virtual channels that Citrix provides operate unmodified when you use the Citrix Workspace app
for Windows within an ICA session (also known as a pass‑through session). There are considerations
when using the client in extra hops.
The following functions operate the same way in single or multiple hops:
• Client COM port mapping

• Client drive mapping
• Client printer mapping

• Client UPD
• End user experience monitoring
• Generic USB
• Kerberos
• Multimedia support
• Smartcard support
• Transparent key pass‑through
• Twain
As the inherent nature of latency and factors such as compression and decompression and rendering
being performed at each hop, performance might be affected with each additional hop that the client
undergoes. The affected areas are:
• Bidirectional audio
• File transfers
• Generic USB redirection
• Seamless
• Thinwire
Important:
By default, the client drives mapped by an instance of the client running in a pass‑through ses‑
sion are restricted to the client drives of the connecting client.
Pass‑through functionality of virtual channels between a Citrix Virtual Desktop

session and a Citrix Virtual App session
Most virtual channels provided by Citrix operate unmodified when you use Citrix Workspace app for
Windows within an ICA session on a Citrix Virtual Desktops server (also known as a pass‑through ses‑
sion).
Specifically, on the Citrix Virtual Desktops server, there is a VDA hook that runs picaPassthruHook.
This hook makes the client think it’s running on a CPS server, and placing the client into its traditional
pass‑through mode.
We support the following traditional virtual channels and their functionality:
• Client
• Client COM port mapping
• Client drive mapping
• Client printer mapping
• Generic USB (limited due to performance)
• Multimedia support
• Smartcard support

• SSON
• Transparent key pass‑through
Security and ICA virtual channels
Securing usage is an important part of planning, developing, and implementing virtual channels.
There are several references to specific areas of security located throughout this document.
Best practices
Open virtual channels when you Connect and Reconnect. Close virtual channels when you log off
and Disconnect.
Keep the following guidelines in mind when you create scripts that use virtual channel functions.
Naming the Virtual Channels:
You can create a maximum of 32 virtual channels. Seventeen of the 32 channels are reserved for spe‑
cial purposes.
• Virtual channel names must not be more than seven characters in length.
• The first three characters are reserved for the vendor name, and the next four for the channel
type. For example, CTXAUD represents the Citrix audio virtual channel.
Virtual channels are referred to by a seven‑character (or shorter) ASCII name. In some previous ver‑
sions of the ICA protocol, virtual channels were numbered. The numbers are now assigned dynam‑
ically based on the ASCII name, making implementation easier. Users who are developing virtual
channel code for internal use only can use any seven‑character name that does not conflict with ex‑
isting virtual channels. Use only numbers and upper and lowercase ASCII. Follow the existing naming
convention when adding your own virtual channels. There are several predefined channels. The pre‑
defined channels begin with the OEM identifier CTX and are for use only by Citrix.
Double‑Hop Support:
Virtual Channel Is double hop supported?
Audio No
Browser Content Redirection No
CDM Yes
CEIP No
Clipboard Yes
Continuum (MRVC) No

Virtual Channel Is double hop supported?
Control VC Yes
HTML5 Video Redirection (v1) Yes
Keyboard, Mouse Yes
MultiTouch No
NSAPVC No
Printing Yes
SensVC No
Smartcard Yes
Twain Yes
USB VC Yes
WAYCOM devices ‑K2M using USB VC Yes
Webcam Video Compression Yes
Windows Media Redirection Yes
See also
• ICA Virtual Channel SDK

• The Citrix Developer Network is the home for all technical resources and discussions involving
the use of Citrix SDKs. In this network, you can find access to SDKs, sample code and scripts, ex‑
tensions and plug‑ins, and SDK documentation. Also included are the Citrix Developer Network
forums, where technical discussions take place around each of the Citrix SDKs.
Double hop in Citrix Virtual Apps and Desktops
April 14, 2021
In the context of a Citrix client session, the term “double hop” refers to a Citrix Virtual App session that
is running within a Citrix Virtual Desktop session. The following diagram illustrates a double hop.

In a double hop scenario, when the user connects to a Citrix Virtual Desktop running on a single‑
session OS VDA (known as VDI) or a multi‑session OS VDA (known as a published desktop), that is
considered the first hop. After the user connects to the virtual desktop, the user can launch a Citrix
Virtual Apps session. That is considered the second hop.
You can use a double hop deployment model to support various use cases. The case where the Cit‑
rix Virtual Desktop and the Citrix Virtual Apps environments are managed by different entities is one
common example. This method can also be effective in resolving application compatibility issues.
System requirements
All Citrix Virtual Apps and Desktop editions including the Citrix Cloud service support double hop.
The first hop must use a supported version of the single‑session or multi‑session OS VDA and the Citrix
Workspace App. The second hop must use a supported version of the multi‑session OS VDA. See the
Product Matrix page for supported versions.
For best performance and compatibility, Citrix recommends using a Citrix client of the same version
or newer than the VDA versions in use.
In environments where the first hop involves a third‑party (non‑Citrix) virtual desktop solution in com‑
bination with a Citrix Virtual Apps session, support is limited to the Citrix Virtual Apps environment.
In the event of any issues related to the third‑party virtual desktop, including ‑ but not limited to ‑
Citrix Workspace app compatibility, redirection of hardware devices, and session performance, Citrix
can provide technical support in a limited capacity. A Citrix Virtual Desktop at the first hop might be
required as part of troubleshooting.
Deployment considerations for HDX in double hop
In general, each session in a double hop is unique and client‑server functions are isolated to a given
hop. This section includes areas that require special consideration by Citrix administrators. Citrix
recommends that customers conduct thorough testing of required HDX capabilities to ensure user
experience and performance is adequate for a given environment configuration.

Graphics
Use default graphics settings (selective encoding) on the first and second hops. In the case of HDX 3D
Pro, Citrix highly recommends that all applications that require graphics acceleration run locally in
the first hop with the appropriate GPU resources available to the VDA.
Latency
End‑to‑end latency can impact the overall user experience. Consider the added latency between the
first and second hops. This is especially important with redirection of hardware devices.
Multimedia
Server‑side (in session) rendering of audio and video content performs best in the first hop. Video
playback in the second hop requires decoding and re‑encoding at the first hop, increasing bandwidth
and hardware resource utilization as a result. Audio and video content must be limited to the first hop
whenever possible.
USB device redirection
HDX includes generic and optimized redirection modes to support a wide array of USB device types.
Pay special attention to the mode in use at each hop and use the following table as reference for best
results. For more information about generic and optimized redirection modes, see Generic USB de‑
vices.
First hop (VDI or published

desktop) Second hop (Virtual apps) Support notes
Optimized Optimized Recommended (based on

device support). For example,
USB mass storage, TWAIN
scanners, Webcam, Audio.
Generic Generic For devices where the
optimized option is not
available.
Generic Optimized While technically possible, it
is recommended to use the
optimized mode across both
hops when device support is
available.

First hop (VDI or published

desktop) Second hop (Virtual apps) Support notes
Optimized Generic Not supported
Note:
Due to the inherent chattiness of USB protocols, performance may decrease across hops. Func‑
tionality and results vary depending on specific device and application requirements. Validation
testing is highly recommended in all cases of device redirection and especially important in dou‑
ble hop scenarios.
Support exceptions
Double hop sessions support most HDX features and capabilities except for the following:
• Browser content redirection

• Local App Access
• RealTime Optimization Pack for Skype for Business
• Optimization for Microsoft Teams
Install and configure
April 14, 2021
Review the referenced articles before starting each deployment step, to learn about what you see and
specify during the deployment.
Use the following sequence to deploy Citrix Virtual Apps and Desktops.
Prepare
Review Prepare to install and complete any necessary tasks.
• Where to find information about concepts, features, differences from earlier releases, system
requirements, and databases.
• Considerations when deciding where to install core components.
• Permission and Active Directory requirements.
• Information about the available installers, tools, and interfaces.

Install core components
Install the Delivery Controller, Citrix Studio, Citrix Director, and Citrix License Server. You can also
install Citrix StoreFront. For details, see Install core components or Install using the command line.
Create a site
After you install the core components and launch Studio, you are automatically guided to create a site.
Install one or more Virtual Delivery Agents (VDAs)
Install a VDA on a machine running a Windows operating system, either on a master image or directly
on each machine. See Install VDAs or Install using the command line. Sample scripts are provided if
you want to install VDAs through Active Directory.
For machines with a Linux operating system, follow the guidance in Linux Virtual Delivery Agent.
For a Remote PC Access deployment, install a VDA for single‑session OS on each office PC. If you need
only the core VDA services, use the standalone VDAWorkstationCoreSetup.exe installer and your
existing Electronic Software Distribution (ESD) methods. (Prepare to install describes the available
VDA installers.)
Install optional components
If you plan to use the Citrix Universal Print Server, install its server component on your print servers.
See Install core components or Install using the command line.
To allow StoreFront to use authentication options such as SAML assertions, install the Citrix Federated
Authentication Service.
To enable end users to have greater control over their user accounts, install Self‑Service Password
Reset.
Optionally, integrate more Citrix components into your Citrix Virtual Apps and Desktops deployment.
• Citrix Provisioning is an optional component that provisions machines by streaming a master

image to target devices.
• Citrix Gateway is a secure application access solution that provides administrators with granular
application‑level policy and action controls to secure access to applications and data.
• Citrix SD‑WAN is a set of appliances that optimize WAN performance.
Create a machine catalog
After you create a site in Studio, you are guided to create a machine catalog.

A catalog can contain physical or virtual machines (VMs). Virtual machines can be created from a mas‑
ter image. When using a hypervisor or other service to provide VMs, you first create a master image
on that host. Then, when you create the catalog, you specify that image, which is used when creating
VMs.
Create a delivery group
After you create your first machine catalog in Studio, you are guided to create a delivery group.
A delivery group specifies which users can access machines in a selected catalog and the applications
available to those users.
Create an application group (optional)
After you create a delivery group, you can optionally create an application group. You can create ap‑
plication groups for applications that are shared across different delivery groups or used by a subset
of users within delivery groups.
Prepare to install
April 14, 2021
Deploying Citrix Virtual Apps and Desktops begins with installing the following components. This pro‑
cess 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 Au‑
thentication 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.
You can use the full‑product installer on the product ISO to deploy many components and technolo‑
gies. 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 Ac‑
tive Directory. You can also use the scripts to manage master images used by Machine Creation Ser‑
vices (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. Compo‑
nent 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 produc‑
tion 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 Con‑
troller allows you to manage the site remotely.
• For most production deployments, installing core components on separate servers is recom‑
mended.
• 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 ex‑
ample, 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 does not 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 com‑
ponents.
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 con‑
tains 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 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 Win‑
dows 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. Com‑
ponents that installed successfully are retained. You do not need to reinstall them.
• Citrix Analytics are collected automatically when you install (or upgrade) components. By de‑
fault, 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 Im‑
provement 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 er‑
ror 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 in‑
stall 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 docu‑
mentation.
• 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 in‑
stalling 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 automat‑
ically. 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 per‑
formance, 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 installa‑
tion.
• For Windows multi‑session OS machines, install and enable the RDS role services before in‑
stalling 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.
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, 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.
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 avail‑
able 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 avail‑
able 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.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 and /exclude "Citrix
Personalization for App-V - VDA""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 ac‑
tion enables you to install all missing components.
The VDAWorkstationCoreSetup.exe installer automatically installs the Browser Content Redirec‑

tion MSI. This automatic installation applies to 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 Mi‑
crosoft value.
• 0 = Success
• 1 = Failed
• 2 = PartialSuccess
• 3 = PartialSuccessAndRebootNeeded
• 4 = FailureAndRebootNeeded
• 5 = UserCanceled
• 6 = MissingCommandLineArgument
• 7 = NewerVersionFound
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.
Microsoft System Center Virtual Machine Manager virtualization

environments
April 14, 2021
Follow this guidance if you use Hyper‑V with Microsoft System Center Virtual Machine Manager (VMM)
to provide virtual machines.
This release supports the VMM versions listed in System requirements.
You can use Citrix Provisioning (formerly Provisioning Services) and Machine Creation Services to pro‑
vision:
• Generation 1 supported Desktop or Server OS VMs.

• Generation 2 supported Desktop or Server OS VMs, including Secure Boot support.
Install and configure a hypervisor

Important:
All Delivery Controllers must be in the same forest as the VMM servers.
1. Install Microsoft Hyper‑V server and VMM on your servers.
2. Install the System Center Virtual Machine Manager console on all Controllers. The console ver‑
sion must match the management server version. Although an earlier console can connect to
the management server, provisioning VDAs fails if the versions differ.
3. Verify the following account information:
The account you use to specify hosts in Studio is a VMM administrator or VMM delegated admin‑
istrator for the relevant Hyper‑V machines. If this account only has the delegated administrator
role in VMM, the storage data is not listed in Studio during the host creation process.
The user account used for Studio integration must also be a member of the administrators local
security group on each Hyper‑V server. This configuration supports VM life cycle management,
such as VM creation, update, and deletion.
Installing a Controller on a server running Hyper‑V is not supported.

Create a master VM
1. Install a VDA on the master VM, and select the option to optimize the desktop to improve per‑
formance.
2. Take a snapshot of the master VM to use as a backup.
Create virtual desktops
If you are using MCS to create VMs, when creating a site or a connection:
1. Select the Microsoft virtualization host type.
2. Enter the address as the fully qualified domain name of the host server.
3. Enter the credentials for the administrator account you set up earlier that has permissions to
create VMs.
4. In Host Details, select the cluster or standalone host to use when creating VMs.
Browse for and select a cluster or standalone host even if you are using a single Hyper‑V host
deployment.
MCS on SMB 3 file shares
For machine catalogs created with MCS on SMB 3 file shares for VM storage, ensure that credentials
meet the following requirements. These requirements ensure that calls from the Controller’s Hyper‑
visor Communications Library (HCL) connect successfully to SMB storage:
• VMM user credentials must include full read write access to the SMB storage.
• Storage virtual disk operations during VM life cycle events are performed through the Hyper‑V
server using the VMM user credentials.
When you use SMB storage, enable the Authentication Credential Security Support Provider (CredSSP)
from the Controller to individual Hyper‑V machines. Use this process for VMM 2012 SP1 with Hyper‑V
on Windows Server 2012. For more information, see CTX137465.
The HCL uses CredSSP to open a connection to the Hyper‑V machine. This feature passes Kerberos‑
encrypted user credentials to the Hyper‑V machine. The PowerShell commands in the session on the
remote Hyper‑V machine run with the credentials provided. In this case, the credentials of the VMM
user, so that communication commands to storage work correctly.
The following tasks use PowerShell scripts that originate in the HCL and are then sent to the Hyper‑V
machine to act on the SMB 3.0 storage.
• Consolidate master image: A master image creates a MCS provisioning scheme (machine cata‑
log). It clones and flattens the master VM ready for creating VMs from the new disk created (and
removes dependency on the original master VM).

ConvertVirtualHardDisk on the root\virtualization\v2 namespace
Example:
1 $ims = Get-WmiObject -class $class -namespace "root\\virtualization\\v2

";
2 $result = $ims.ConvertVirtualHardDisk($diskName, $vhdastext)
3 $result
4 
• Create difference disk: Creates a difference disk from the master image generated by consoli‑
dating the master image. The difference disk is then attached to a new VM.
CreateVirtualHardDisk on the root\virtualization\v2 namespace
Example:
1 $ims = Get-WmiObject -class $class -namespace "root\\virtualization\\v2

";
2 $result = $ims.CreateVirtualHardDisk($vhdastext);
3 $result
4 
• Upload identity disks: The HCL cannot directly upload the identity disk to SMB storage. There‑
fore, the Hyper‑V machine must upload and copy the identity disk to the storage. Because the
Hyper‑V machine cannot read the disk from the Controller, the HCL must first copy the identity
disk through the Hyper‑V machine as follows.
The HCL uploads the Identity to the Hyper‑V machine through the administrator share.
The Hyper‑V machine copies the disk to the SMB storage through a PowerShell script running in
the PowerShell remote session. A folder is created on the Hyper‑V machine and the permissions
on that folder are locked for the VMM user only (through the remote PowerShell connection).
The HCL deletes the file from the administrator share.
When the HCL finishes uploading the identity disk to the Hyper‑V machine, the remote Pow‑
erShell session copies the identity disks to SMB storage. It then deletes it from the Hyper‑V
machine.
The identity disk folder is recreated if it is deleted so that it is available for reuse.
• Download identity disks: As with uploads, the identity disks pass though the Hyper‑V machine
to the HCL. The following process creates a folder that only has VMM user permissions on the
Hyper‑V server if it does not exist.
The Hyper‑V machine copies the disk from the SMB storage to the local Hyper‑V storage through
a PowerShell script. This script runs in the PowerShell V3 remote session.

HCL reads the disk from the Hyper‑V machine’s administrator share into memory.
HCL deletes the file from the administrator share.
Citrix Hypervisor virtualization environments
April 14, 2021
Create a connection to Citrix Hypervisor
When you create a connection to Citrix Hypervisor (formerly XenServer), you must provide the creden‑
tials for a VM Power Admin or higher‑level user.
Citrix recommends using HTTPS to secure communications with Citrix Hypervisor. To use HTTPS, you
must replace the default SSL certificate installed on Citrix Hypervisor; see CTX128656.
You can configure high availability if it is enabled on the Citrix Hypervisor server. Citrix recommends
that you select all servers in the pool (from Edit High Availability) to allow communication with the
Citrix Hypervisor server if the pool master fails.
You can select a GPU type and group, or pass through, if the Citrix Hypervisor supports vGPU. The
display indicates if the selection has dedicated GPU resources.
When using local storage on one or more Citrix Hypervisor hosts for temporary data storage, make sure
that each storage location in the pool has a unique name. (To change a name in XenCenter, right‑click
the storage and edit the name property.)
vision:
• legacy BIOS for supported Desktop or Server OS VMs.
• UEFI for supported Desktop or Server OS VMs, including Secure Boot.
Use IntelliCache for Citrix Hypervisor connections
Using IntelliCache, hosted VDI deployments are more cost‑effective because you can use a combina‑
tion of shared storage and local storage. This enhances performance and reduces network traffic. The
local storage caches the master image from the shared storage, which reduces the number of reads on
the shared storage. For shared desktops, writes to the differencing disks are written to local storage
on the host and not to shared storage.
• Shared storage must be NFS when using IntelliCache.
• Citrix recommends that you use a high performance local storage device to ensure the fastest
possible data transfer.

To use IntelliCache, you must enable it in both this product and Citrix Hypervisor.
• When installing Citrix Hypervisor, select Enable thin provisioning (Optimized storage for Vir‑
tual Desktops). Citrix does not support mixed pools of servers that have IntelliCache enabled
and servers that do not. For more information, see the Citrix Hypervisor documentation.
• In Citrix Virtual Apps and Desktops, IntelliCache is disabled by default. You can change the set‑
ting only when creating a Citrix Hypervisor connection; you cannot disable IntelliCache later.
When you add a Citrix Hypervisor connection:
– Select Shared as the storage type.
– Select the Use IntelliCache check box.
Create a machine catalog using a Citrix Hypervisor connection
GPU‑capable machines require a dedicated master image. Those VMs require video card drivers that
support GPUs. Configure GPU‑capable machines to allow the VM to operate with software that uses
the GPU for operations.
1. In XenCenter, create a VM with standard VGA, networks, and vCPU.

2. Update the VM configuration to enable GPU use (either Passthrough or vGPU).
3. Install a supported operating system and enable RDP.
4. Install Citrix VM Tools and NVIDIA drivers.
5. Clear the Virtual Network Computing (VNC) Admin Console to optimize performance, and then
restart the VM.
6. You are prompted to use RDP. Using RDP, install the VDA and then restart the VM.
7. Optionally, create a snapshot for the VM as a baseline template for other GPU master images.
8. Using RDP, install customer‑specific applications that are configured in XenCenter and use GPU
capabilities.
More information
• Connections and resources

• Create machine catalogs
Microsoft System Center Configuration Manager environments
April 14, 2021
Sites using Microsoft System Center Configuration Manager (Configuration Manager) to manage ac‑
cess to applications and desktops can extend that use to XenApp or XenDesktop using these options:

• Citrix Connector 3.1: Citrix Connector provides a bridge between Configuration Manager and
Citrix Virtual Apps and Desktops. The Connector enables you to unify day‑to‑day operations
across the physical environments you manage with Configuration Manager. This support ex‑
tends to the virtual environments you manage with Citrix Virtual Apps and Desktops. For more
information, see Citrix Connector 3.1.
• Configuration Manager Wake Proxy feature: The Remote PC Access Wake on LAN feature re‑
quires Configuration Manager. For more information, see Remote PC Access.
• XenApp and XenDesktop properties: XenApp and XenDesktop properties enable you to iden‑
tify Citrix Virtual Desktops for management through Configuration Manager. (Configuration
Manager uses the former name of Citrix Virtual Apps and Desktops: XenApp and XenDesktop.)
These properties are automatically used by the Citrix Connector but can also be manually con‑
figured, as described in the following section.
Properties
Properties are available to Microsoft System Center Configuration Manager to manage virtual desk‑
tops.
Boolean properties displayed in Configuration Manager appear as 1 or 0, not true or false.
The properties are available for the Citrix_virtualDesktopInfo class in the Root\Citrix\DesktopInformation
namespace. Property names come from the Windows Management Instrumentation (WMI) provider.
Property Description
AssignmentType Sets the value of IsAssigned. Valid values are:

ClientIP, ClientName, None, and User (sets
IsAssigned to True)
BrokerSiteName Returns the same value as HostIdentifier
DesktopCatalogName Machine catalog associated with the desktop.
DesktopGroupName Delivery Group associated with the desktop.
HostIdentifier Returns the same value as BrokerSiteName.
IsAssigned True to assign the desktop to a user, set to
False for a random desktop

Property Description
IsMasterImage Allows decisions about the environment. For

example, install applications on the master
image and not on the provisioned machines.
Valid values are: True on a VM that is used as a
master image. This value is set during
installation based on a selection, or cleared on
a VM that is provisioned from that image.
IsVirtualMachine True for a virtual machine, false for a physical
machine.
OSChangesPersist False if the desktop operating system image is
reset to a clean state every time it is restarted;
otherwise, true.
PersistentDataLocation The location where Configuration Manager
stores persistent data. This is not accessible to
users.
PersonalvDiskDriveLetter For a desktop with a Personal vDisk, the drive
letter you assign to the Personal vDisk.
BrokerSiteName, DesktopCatalogName, Determined when the desktop registers with
DesktopGroupName, HostIdentifier the Controller. They are null for a desktop that
has not fully registered.
To collect the properties, run a hardware inventory in Configuration Manager. To view the properties,
use the Configuration Manager Resource Explorer. In these instances, the names include spaces or
vary slightly from the property names. For example, BrokerSiteName appears as Broker Site Name.
• Configure Configuration Manager to collect Citrix WMI properties from the Citrix VDA
• Create query‑based device collections using Citrix WMI properties
• Create global conditions based on Citrix WMI properties
• Use global conditions to define application deployment type requirements
You can also use Microsoft properties in the Microsoft class CCM_DesktopMachine in the Root\ccm_vdi
namespace. For more information, see the Microsoft documentation.
VMware virtualization environments
April 14, 2021

Follow this guidance if you use VMware to provide virtual machines.
Install vCenter Server and the appropriate management tools. (No support is provided for vSphere
vCenter Linked Mode operation.)
If you plan to use MCS, do not disable the Datastore Browser feature in vCenter Server (de‑
scribed in https://kb.vmware.com/selfservice/microsites/search.do?language=en_US&cmd=
displayKC&externalId=2101567). When you disable this feature, MCS does not work correctly.
vision:
• legacy BIOS for supported Desktop or Server OS VMs.

• UEFI for supported Desktop or Server OS VMs, including Secure Boot.
Required privileges
Create a VMware user account and one or more VMware roles with privileges listed in the following
section. Base the creation of these roles on the specific level of granularly required over the user’s
permissions. This process is used to request the various Citrix Virtual Apps and Desktops operations
at any time. To grant the user specific permissions at any point, associate them with the respective
role, at the data center level at a minimum.
The following tables show the mappings between Citrix Virtual Apps and Desktops operations and the
minimum required VMware privileges.
Add connections and resources
SDK User interface
System. Anonymous, System. Read, and Added automatically. Can use the built‑in
System.View read‑only role.
Provision machines (Machine Creation Services)
SDK User interface
Datastore.AllocateSpace Datastore \ > Allocate space

Datastore.Browse Datastore \ > Browse datastore
Datastore.FileManagement Datastore \ > Low level file operations
Network.Assign Network \ > Assign network

SDK User interface
Resource.AssignVMToPool Resource \ > Assign virtual machine to

resource pool
VirtualMachine.Config.AddExistingDisk Virtual machine > Configuration \ > Add
existing disk
VirtualMachine.Config.AddNewDisk Virtual machine > Configuration \ > Add new
disk
VirtualMachine.Config.AdvancedConfig Virtual machine > Configuration \ >
Advanced
VirtualMachine.Config.RemoveDisk Virtual machine > Configuration \ > Remove
disk
VirtualMachine.Interact.PowerOff Virtual machine > Interaction \ > Power Off
VirtualMachine.Interact.PowerOn Virtual machine > Interaction \ > Power On
VirtualMachine.Inventory.CreateFromExisting Virtual machine > Inventory \ > Create from
existing
VirtualMachine.Inventory.Create Virtual machine > Inventory \ > Create new
VirtualMachine.Inventory.Delete Virtual machine > Inventory \ > Remove
VirtualMachine.Provisioning.Clone Virtual machine > Provisioning \ > Clone
virtual machine
VirtualMachine.State.CreateSnapshot vSphere 5.0, Update 2 and vSphere 5.1, Update
1: Virtual machine > State \ > Create
snapshot. vSphere 5.5: Virtual machine >
Snapshot management \ > Create snapshot
If you want the VMs you create to be tagged, add the following permissions for the user account.
To ensure that you use a clean base image for creating VMs, tag VMs created with Machine Creation
Services to exclude them from the list of VMs available to use as base images.
SDK User interface
Global.ManageCustomFields Global \ > Manage custom attributes

Global.SetCustomField Global \ > Set custom attribute

Provision machines (Citrix Provisioning)
All privileges from Provision machines (Machine Creation Services) and the following.
SDK User interface
VirtualMachine.Config.AddRemoveDevice Virtual machine > Configuration \ > Add or

remove device
VirtualMachine.Config.CPUCount Virtual machine > Configuration \ > Change
CPU Count
VirtualMachine.Config.Memory Virtual machine > Configuration \ > Memory
VirtualMachine.Config.Settings Virtual machine > Configuration \ > Settings
VirtualMachine.Provisioning.CloneTemplate Virtual machine > Provisioning \ > Clone
template
VirtualMachine.Provisioning.DeployTemplate Virtual machine > Provisioning \ > Deploy
template
Power management
SDK User interface

VirtualMachine.Interact.Reset Virtual machine > Interaction \ > Reset
VirtualMachine.Interact.Suspend Virtual machine > Interaction \ > Suspend
Image update and rollback
SDK User interface
Datastore.AllocateSpace Datastore \ > Allocate space

Network.Assign Network \ > Assign network
Resource.AssignVMToPool Resource \ > Assign virtual machine to
resource pool

SDK User interface
VirtualMachine.Config.AddExistingDisk Virtual machine > Configuration \ > Add

existing disk
VirtualMachine.Config.AddNewDisk Virtual machine > Configuration \ > Add new
disk
VirtualMachine.Config.AdvancedConfig Virtual machine > Configuration \ >
Advanced
disk
VirtualMachine.Interact.Reset Virtual machine > Interaction \ > Reset
VirtualMachine.Inventory.CreateFromExisting Virtual machine > Inventory \ > Create from
existing
VirtualMachine.Inventory.Create Virtual machine > Inventory \ > Create new
VirtualMachine.Provisioning.Clone Virtual machine > Provisioning \ > Clone
virtual machine
Delete provisioned machines
SDK User interface

disk
Obtain and import a certificate
To protect vSphere communications, Citrix recommends that you use HTTPS rather than HTTP. HTTPS
requires digital certificates. Citrix recommends a digital certificate issued from a certificate authority

in accordance with your organization’s security policy.
If you are unable to use a digital certificate issued from a certificate authority, you can use the VMware‑
installed self‑signed certificate. Only use this method if your organization’s security policy permits it.
Add the VMware vCenter certificate to each Delivery Controller.
1. Add the fully qualified domain name (FQDN) of the computer running vCenter Server to the
hosts file on that server, at %SystemRoot%/WINDOWS/system32/Drivers/etc/. This step is
required only if the FQDN of the computer running vCenter Server is not already present in the
domain name system.
2. Obtain the vCenter certificate using any of the following three methods:
From the vCenter server.
a) Copy the file rui.crt from the vCenter server to a location accessible on your Delivery Con‑
trollers.
b) On the Controller, navigate to the location of the exported certificate and open the rui.crt
file.
Download the certificate using a web browser. If you are using Internet Explorer, right‑click
on Internet Explorer and choose Run as Administrator to download or install the certificate.
a) Open your web browser and make a secure web connection to the vCenter server (for ex‑
ample https://server1.domain1.com).
b) Accept the security warnings.
c) Click the address bar displaying the certificate error.
d) View the certificate and click the Details tab.
e) Select Copy to file and export in .CER format, providing a name when prompted to do
so.
f) Save the exported certificate.
g) Navigate to the location of the exported certificate and open the .CER file.
Import directly from Internet Explorer running as an administrator.
• Open your web browser and make a secure web connection to the vCenter server (for ex‑
ample https://server1.domain1.com).
• Accept the security warnings.
• Click the address bar displaying the certificate error.
• View the certificate.
3. Import the certificate into the certificate store on each of your Controllers.
a) Click the Install certificate option, select Local Machine, and then click Next.
b) Select Place all certificates in the following store, and then click Browse. Select Trusted
People and then click OK. Click Next and then click Finish.

If you change the name of the vSphere server after installation, you must generate a new self‑
signed certificate on that server before importing the new certificate.
Configuration considerations
Create a master VM:
Use a master VM to provide user desktops and applications in a machine catalog. On your hypervisor:
1. Install a VDA on the master VM, selecting the option to optimize the desktop, which improves
performance.
2. Take a snapshot of the master VM to use as a back‑up.
Create a connection:
In the connection creation wizard:
• Select the VMware connection type.

• Specify the address of the access point for the vCenter SDK.
• Specify the credentials for a VMware user account you set up earlier that has permissions to
create VMs. Specify the user name in the form domain/username.
VMware SSL thumbprint
The VMware SSL thumbprint feature addresses a frequently reported error when creating a host con‑
nection to a VMware vSphere hypervisor. Previously, administrators had to manually create a trust re‑
lationship between the Delivery Controllers in the Site and the hypervisor’s certificate before creating
a connection. The VMware SSL thumbprint feature removes that manual requirement: the untrusted
certificate’s thumbprint is stored on the Site database. This configuration ensures that the hypervi‑
sor can be continuously identified as trusted by Citrix Virtual Apps and Desktops, even if not by the
Controllers.
When creating a vSphere host connection in Studio, a dialog box allows you to view the certificate of
the machine you are connecting to. You can then choose whether to trust it.
Nutanix virtualization environments
April 14, 2021
Follow this guidance when using Nutanix Acropolis to provide virtual machines in your Citrix Virtual
Apps and Desktops deployment. The setup process includes the following tasks:
• Install and register the Nutanix plug‑in in your Citrix Virtual Apps and Desktops environment.

• Create a connection to the Nutanix Acropolis hypervisor.

• Create a machine catalog that uses a snapshot of a master image you created on the Nutanix
hypervisor.
For more information, see the Nutanix Acropolis MCS plug‑in Installation Guide, available at the Nu‑
tanix Support Portal.
Install and register the Nutanix plug‑in
After you install the Citrix Virtual Apps and Desktops components, complete the following procedure
to install and register the Nutanix plug‑in on the Delivery Controllers. Use Studio to create a connec‑
tion to the Nutanix hypervisor and then create a machine catalog that uses a snapshot of a master
image you created in the Nutanix environment.
1. Obtain the Nutanix plug‑in from Nutanix, and install it on the Delivery Controllers.
2. Verify that a Nutanix Acropolis folder has been created in C:\Program Files\Common
Files\Citrix\HCLPlugins\CitrixMachineCreation\v1.0.0.0.
3. Run C:\\Program Files\\Common Files\\Citrix\\HCLPlugins\\RegisterPlugins

.exe –PluginsRoot “C:\\Program Files\\Common Files\\Citrix\\HCLPlugins
\\CitrixMachineCreation\\v1.0.0.0”.
4. Restart the Citrix Host Service, Citrix Broker Service, and Citrix Machine Creation Service.
5. Run the following PowerShell cmdlets to verify that the Nutanix Acropolis plug‑in has been reg‑
istered:
1 Add-PSSnapin Citrix\*
2 Get-HypHypervisorPlugin
3 
Create a connection to Nutanix
See Create a Site or Connections and resources for complete information about all pages in the wiz‑
ards that create a connection.
In the Site Setup or Add Connection and Resources wizard, select the Nutanix connection type on the
Connection page. Specify the hypervisor address and credentials, plus a name for the connection.
On the Network page, select a network for the hosting unit.
Create a machine catalog using a Nutanix snapshot
This information is a supplement to the guidance in the Create machine catalogs article. It describes
only the fields that are unique to Nutanix.

The snapshot you select is the template that is used to create the VMs in the catalog. Before creating
the catalog, create images and snapshots in Nutanix.
• For information about master images in general, see the Create machine catalogs article.
• For Nutanix procedures for creating images and snapshots, see the Nutanix documentation.
The Operating System and Machine Management pages do not contain Nutanix‑specific informa‑
tion. Follow the guidance in the Create machine catalogs article.
On the Container page, which is unique to Nutanix, select the container where the VMs’ disks reside.
On the Master Image page, select the image snapshot. Use the Acropolis console to rename your
snapshots, if needed. If you rename snapshots, restart the Create Catalog wizard to see a refreshed
list.
On the Virtual Machines page, indicate the number of virtual CPUs and the number of cores per vCPU.
The Network Cards, Computer Accounts, and Summary pages do not contain Nutanix‑specific in‑
formation. Follow the guidance in the Create machine catalogs article.
Install core components
April 14, 2021
The core components are the Citrix Delivery Controller, Citrix Studio, Citrix Director, and Citrix License
Server.
(In versions before 2003, core components included Citrix StoreFront. You can still install StoreFront
by clicking the Citrix StoreFront tile or running the command available on the installation media.)
Before you start an installation, review this article and Prepare to install.
This article describes the installation wizard sequence when installing core components. Command‑
line equivalents are provided. For more information, see Install using the command line.
Step 1. Download the product software and launch the wizard
Use your Citrix account credentials to access the Citrix Virtual Apps and Desktops download page.
Download the product ISO file.
Unzip the file. Optionally, burn a DVD of the ISO file.
Log on to the machine where you are installing the core components, using a local administrator ac‑
count.
Insert the DVD in the drive or mount the ISO file. If the installer does not launch automatically, double‑
click the AutoSelect application or the mounted drive.

Step 2. Choose which product to install
Click Start next to the product to install: Virtual Apps or Virtual Apps and Desktops.
(If the machine already has Citrix Virtual Apps and Desktops components installed on it, this page does
not appear.)
Command‑line option: /xenapp to install Citrix Virtual Apps. Citrix Virtual Apps and Desktops is in‑
stalled if option is omitted.

Step 3. Choose what to install
If you’re just getting started, select Delivery Controller. (On a later page, you select the specific com‑
ponents to install on this machine.)
If you’ve already installed a Controller (on this machine or another) and want to install another com‑
ponent, select the component from the Extend Deployment section.
Command‑line option: /components

Step 4. Read and accept the license agreement
On the Licensing Agreement page, after you read the license agreement, indicate that you have read
and accepted it. Then click Next.

Step 5. Select the components to install and the installation location
On the Core components page:
• Location: By default, components are installed in C:\Program Files\Citrix. The default is

fine for most deployments. If you specify a different location, it must have execute permissions
for network service.
• Components: By default, the check boxes for all core components are selected. Installing all of
the core components on one server is fine for proof of concept, test, or small production deploy‑
ments. For larger production environments, Citrix recommends installing Director, StoreFront,
and the License Server on separate servers.
Select only the components you want to install on this machine. After you install components
on this machine, you can run the installer again on other machines to install other components.
An icon alerts you when you choose not to install a required core component on this machine.
That alert reminds you to install that component, although not necessarily on this machine.
Click Next.
Command‑line options: /installdir, /components, /exclude

Hardware check
When you install or upgrade a Delivery Controller, the hardware is checked. The installer alerts you
if the machine has less than the recommended amount of RAM (5 GB), which can affect site stability.
For more information, see Hardware requirements.
Graphical interface: A dialog box appears.
• Recommended: Click Cancel to stop the installation. Add more RAM to the machine and then
start the installation again.
• Alternatively, click Next to continue with the installation. The site might have stability issues.
Command‑line interface: The install/upgrade ends. The install logs contain a message that
describes what was found and the available options.
• Recommended: Add more RAM to the machine and then run the command again.
• Alternatively, run the command again with the /ignore_hw_check_failure option to over‑
ride the warning. Your site might have stability issues.
When upgrading, you’re also notified if the OS or SQL Server version is no longer supported. See Up‑
grade a deployment.

Step 6. Enable or disable features
On the Features page:
• Choose whether to install Microsoft SQL Server Express for use as the site database. By de‑
fault, this selection is enabled. If you’re not familiar with the Citrix Virtual Apps and Desktops
databases, review Databases.
• When you install Director, Windows Remote Assistance is installed automatically. You choose
whether to enable shadowing in Windows Remote Assistance for use with Director user shadow‑
ing. Enabling shadowing opens TCP port 3389. By default, this feature is enabled. The default
setting is fine for most deployments. This feature appears only when you are installing Director.
Click Next.
Command‑line options: /nosql (to prevent installation), /no_remote_assistance (to prevent en‑
abling)

Step 7. Open Windows firewall ports
By default, the ports on the Firewall page are opened automatically if the Windows Firewall Service
is running, even if the firewall is not enabled. The default setting is fine for most deployments. For
port information, see Network ports.
Click Next.
(The graphic shows the port lists when you install all the core components on this machine. That type
of installation is usually for test deployments only.)
Command‑line option: /configure_firewall

Step 8. Review prerequisites and confirm installation
The Summary page lists what will be installed. Use the Back button to return to earlier wizard pages
and change selections, if needed.
When you’re ready, click Install.
The display shows the progress of the installation:


Step 9. Diagnostics
On the Diagnostics page, choose whether to participate in Citrix Call Home.
This page appears when installing a Delivery Controller using the graphical interface. When you install
StoreFront (but not a Controller), the wizard displays this page. When you install other core compo‑
nents (but not a Controller or StoreFront), the wizard does not display this page.
During an upgrade, this page does not appear if Call Home is already enabled or if the installer en‑
counters an error related to the Citrix Telemetry Service.
If you choose to participate (the default), click Connect. When prompted, enter your Citrix account
credentials. You can change your enrollment choice later, after installation.
After your credentials are validated (or if you choose not to participate), click Next.
For more information, see Call Home.

Step 10. Finish this installation
The Finish page contains green check marks for all prerequisites and components that installed and
initialized successfully.
Click Finish.
Step 11. Install remaining core components on other machines
If you installed all the core components on one machine, continue with Next steps. Otherwise, run
the installer on other machines to install other components. You can also install more Controllers on
other servers.
Next steps
After you install all the required components, use Studio to create a site.
After creating the site, install VDAs.
At any time, you can use the full‑product installer to extend your deployment with the following com‑
ponents:

• Universal Print Server server component: Launch the installer on your print server.
1. Select Universal Print Server in the Extend Deployment section.

2. Accept the license agreement.
3. On the Firewall page, by default, TCP ports 7229 and 8080 are opened in the firewall if the
Windows Firewall Service is running, even if the firewall is not enabled. You can disable
that default action if you want to open the ports manually.
To install this component from the command line, see Command‑line options for installing a
Universal Print Server.
• Federated Authentication Service.
• Session Recording.
Install VDAs
April 14, 2021
Important:
If you’re upgrading, and your current version has the Personal vDisk or AppDisks software in‑
stalled, see Removing PvD, AppDisks, and unsupported hosts.
There are two types of VDAs for Windows machines: VDA for multi‑session OS and VDA for single‑
session OS. (For information about VDAs for Linux machines, see the Linux Virtual Delivery Agent doc‑
umentation.)
Before starting an installation, review Prepare to install and complete all preparation tasks.
Before installing VDAs, you should have already installed the core components. You can also create
the site before installing VDAs.
This article describes the installation wizard sequence when installing a VDA. Command‑line equiva‑
lents are provided. For details, see Install using the command line.
Step 1. Download the product software and launch the wizard
If you’re using the full‑product installer:
1. If you haven’t downloaded the product ISO yet:
• Use your Citrix account credentials to access the Citrix Virtual Apps and Desktops down‑
load page. Download the product ISO file.
• Unzip the file. Optionally, burn a DVD of the ISO file.

2. Use a local administrator account on the image or machine where you’re installing the VDA.
Insert the DVD in the drive or mount the ISO file. If the installer does not launch automatically,
double‑click the AutoSelect application or the mounted drive.
The installation wizard launches.
If you’re using a standalone package:
1. Use your Citrix account credentials to access the Citrix Virtual Apps and Desktops download
page. Download the appropriate package:
• VDAServerSetup.exe: Multi‑session OS VDA version

• VDAWorkstationSetup.exe: Single‑session OS VDA version
• VDAWorkstationCoreSetup.exe: Single‑session OS Core Services VDA version
2. Right‑click the package and choose Run as administrator.
The installation wizard launches.
Step 2. Choose which product to install
Click Start next to the product to install: Citrix Virtual Apps or Citrix Virtual Desktops. (If the machine
already has a Citrix Virtual Apps or Citrix Virtual Desktops component installed, this page does not
appear.)
Command‑line option: /xenapp to install Citrix Virtual Apps. Citrix Virtual Desktops is installed if
option is omitted.

Step 3. Select the VDA
Select the Virtual Delivery Agent entry. The installer knows whether it’s running on a single‑session
or multi‑session OS, so it offers only the appropriate VDA type.
For example, when you run the installer on a Windows Server 2016 machine, the VDA for multi‑session
OS option is available. The VDA for single‑session OS option is not offered.
If you try to install (or upgrade to) a Windows VDA on an OS that is not supported for this Citrix Virtual
Apps and Desktops version, a message guides you to information that describes your options.
Step 4. Specify how the VDA will be used
On the Environment page, specify how you plan to use the VDA, indicating whether you’ll use this
machine as a master image to provision additional machines.

The option you choose affects which Citrix provisioning tools are installed automatically (if any), and
the default values on the Additional Components page of the VDA installer.
Several MSIs (provisioning and other) are installed automatically when you install a VDA. The only way
to prevent their installation is with the /exclude option in a command‑line installation.
Choose one of the following:
• Create a master MCS image: Select this option to install a VDA on a VM master image, if you
plan to use Machine Creation Services to provision VMs. This option installs the Machine Identity
Service, which includes TargetOSOptimizer.exe. This is the default option.
Command‑line option: /mastermcsimage or /masterimage
• Create a master image using Citrix Provisioning or third‑party provisioning tools: Select
this option to install a VDA on a VM master image, if you plan to use either Citrix Provisioning
or third‑party provisioning tools (such as Microsoft System Center Configuration Manager) to
provision VMs.
Command‑line option: /masterpvsimage
• (Appears only on multi‑session OS machines) Enable brokered connections to a server: Se‑

lect this option to install a VDA on a physical or virtual machine that will not be used as a master
image to provision other machines.
Command‑line option: /remotepc
• (Appears only on single‑session OS machines) Enable Remote PC Access: Select this option to
install a VDA on a physical machine for use with Remote PC Access.
Command‑line option: /remotepc
Click Next.
This page does not appear:
• If you’re upgrading a VDA

• If you are using the VDAWorkstationCoreSetup.exe installer

Step 5. Select the components to install and the installation location
On the Core components page:
• Location: By default, components are installed in C:\Program Files\Citrix. This default

is fine for most deployments. If you specify a different location, that location must have execute
permissions for network service.
• Components: By default, Citrix Workspace app for Windows is not installed with the VDA. If
you are using the VDAWorkstationCoreSetup.exe installer, Citrix Workspace app for Windows is
never installed, so this check box is not displayed.
Click Next.
Command‑line options: /installdir, /components vda plugin to install the VDA and the Citrix
Workspace app for Windows

Step 6. Install additional components
The Additional Components page contains check boxes to enable or disable installation of other
features and technologies with the VDA. In a command‑line installation, you can use the /exclude or
/includeadditional option to expressly omit or include one or more available components.
The following table indicates the default setting of items on this page. The default setting depends on
the option you selected on the Environment page.
Environment page: “Enable

Environment page: “Master brokered connections to
image with MCS” or “Master server” (for multi‑session OS)
image with Citrix or “Remote PC Access” (for
Additional Components page Provisioning” selected single‑session OS) selected
Citrix Personalization for Not selected Not selected

App‑V
User Personalization Layer Not selected Not shown because it’s not
valid for this use case.
Citrix Supportability tools Selected Not selected
Citrix User Profile Manager Selected Not selected
Citrix User Profile Manager Selected Not selected
WMI Plugin

Environment page: “Enable

Environment page: “Master brokered connections to
image with MCS” or “Master server” (for multi‑session OS)
image with Citrix or “Remote PC Access” (for
Additional Components page Provisioning” selected single‑session OS) selected
Citrix Files for Windows Not selected Not selected

Citrix Files for Outlook Not selected Not selected
This page does not appear if:

• You are using the VDAWorkstationCoreSetup.exe installer. Also, the command‑line options
for the additional components are not valid with that installer.
• You are upgrading a VDA and all the additional components are already installed. If some of
the additional components are already installed, the page lists only components that are not
installed.
Select or clear the following check boxes:
• Citrix Personalization for App‑V: Install this component if you use applications from Microsoft
App‑V packages. For details, see App‑V.
Command‑line option: /includeadditional "Citrix Personalization for App-V –
VDA" to enable component installation, /exclude "Citrix Personalization for App
-V – VDA" to prevent component installation
• User Personalization Layer: Installs the MSI for the user personalization layer. For details, see
User personalization layer.
This component appears only when installing a VDA on a single‑session Windows 10 machine.
Command‑line option: /includeadditional "User Personalization Layer" to
enable component installation, /exclude "User Personalization Layer" to prevent
component installation
• Citrix Supportability Tools Installs the MSI that contains Citrix supportability tools, such as the
Citrix Health Assistant.
Command‑line option: /includeadditional "Citrix Supportability Tools" to
enable component installation, /exclude "Citrix Supportability Tools" to prevent
• Citrix User Profile Manager: This component manages user personalization settings in user
profiles. For details, see Profile Management.
Excluding Citrix Profile Management from the installation affects the monitoring and trou‑
bleshooting of VDAs with Citrix Director. On the User details and End Point 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 Manage‑
ment Service is not required.
Command‑line option: /includeadditional "Citrix User Profile Manager" to

enable component installation, /exclude "Citrix User Profile Manager" to prevent
• Citrix User Profile Manager WMI Plugin: This plug‑in provides Profile Management runtime
information in WMI (Windows Management Instrumentation) objects (for example, profile
provider, profile type, size, and disk usage). WMI objects provide session information to
Director.
Command‑line option: /includeadditional "Citrix User Profile Manager WMI

Plugin" to enable component installation, /exclude "Citrix User Profile Manager
WMI Plugin" to prevent component installation
• Citrix Files for Windows: This component enables users to connect to their Citrix Files account.
They can then interact with Citrix Files through a mapped drive in the Windows file system (with‑
out requiring a full sync of their content). For more information, see Content Collaboration.
Command‑line options: /includeadditional "Citrix Files for Windows" to enable

component installation, /exclude "Citrix Files for Windows" to prevent component
installation
• Citrix Files for Outlook: Citrix Files for Outlook allows you to bypass file size restrictions and
add security to your attachments or emails by sending them through Citrix Files. You can pro‑
vide a secure file upload request for co‑workers, customers, and partners directly in your email.
For more information, see Content Collaboration.
Command‑line options: /includeadditional "Citrix Files for Outlook" to enable

component installation, /exclude "Citrix Files for Outlook" to prevent component
installation

Step 7. Delivery Controller addresses
On the Delivery Controller page, choose how you want to enter the addresses of installed Controllers.
Citrix recommends that you specify the addresses while you’re installing the VDA (Do it manually).
The VDA cannot register with a Controller until it has this information. If a VDA cannot register, users
cannot access applications and desktops on that VDA.
• Do it manually: (default) Enter the FQDN of an installed Controller and then click Add. If you’ve
installed more Controllers, add their addresses.
• Do it later (Advanced): If you choose this option, the wizard asks you to confirm that’s what
you want to do before continuing. To specify addresses later, you can either rerun the installer
or use Citrix Group Policy. The wizard also reminds you on the Summary page.
• Choose locations from Active Directory: Valid only when the machine is joined to a domain
and the user is a domain user.
• Let Machine Creation Services do it automatically: Valid only when using MCS to provision
machines.
Click Next. If you selected Do it later (Advanced), you are prompted to confirm that you will specify
Controller addresses later.
Other considerations:
• The address cannot contain non‑alphanumeric characters.

• If you specify addresses during VDA installation and in Group Policy, the policy settings override
settings provided during installation.
• Successful VDA registration requires that the firewall ports used to communicate with the Con‑
troller are open. That action is enabled by default on the Firewall page of the wizard.
• After you specify Controller locations (during or after VDA installation), you can use the auto‑
update feature to update the VDAs when Controllers are added or removed. For details about
how VDAs discover and register with Controllers, see VDA registration.

Command‑line option: /controllers
Step 8. Enable or disable features
On the Features page, use the check boxes to enable or disable features you want to use.
• Optimize performance: When you use MCS and enable this feature (default), VM optimization
disables offline files, disables background defragmentation, and reduces event log size. For
details, see CTX125874.
In addition to enabling this feature, optimization requires that the Machine Identity Service be
installed. That service contains the TargetOSOptimizer.exe file. The Machine Identity Ser‑
vice is installed automatically when you:
– In the graphical interface, select Create a master MCS image on the Environment page.
– In the command‑line interface, specify /mastermcsimage or /masterimage (and do not

specify /exclude "Machine Identity Service").
Command‑line option: /optimize
If you are using the VDAWorkstationCoreSetup.exe installer, this feature does not appear
in the wizard and the command‑line option is not valid. If you are using another installer in a
Remote PC Access environment, disable this feature.
• Use Windows Remote Assistance: When this feature is enabled, Windows Remote Assistance
is used with the user shadowing feature of Director. Windows Remote Assistance opens the
dynamic ports in the firewall. (Default = disabled)
Command‑line option: /enable_remote_assistance

• Use Real‑Time Audio Transport for audio: Enable this feature if voice‑over‑IP is widely used in
your network. The feature reduces latency and improves audio resilience over lossy networks.
It allows audio data to be transmitted using RTP over UDP transport. (Default = disabled)
Command‑line option: /enable_real_time_transport
• MCS I/O: Valid only when using MCS to provision VMs. When selected, the MCSIO write caching
driver is installed. For more information, see Storage shared by hypervisors and Configure
cache for temporary data.
Command‑line option: /install_mcsio_driver
Click Next.
Step 9. Firewall ports
On the Firewall page, by default, the ports are opened automatically if the Windows Firewall Service
is running, even if the firewall is not enabled. This default setting is fine for most deployments. For
port information, see Network ports.
Click Next.
Command‑line option: /enable_hdx_ports

Step 10. Review prerequisites and confirm installation
The Summary page lists what will be installed. Use the Back button to return to earlier wizard pages
and change selections.
When you’re ready, click Install.
If prerequisites aren’t already installed/enabled, the machine might restart once or more times. See
Prepare to install.
Step 11. Diagnostics
On the Diagnostics page, choose whether to participate in Citrix Call Home. If you choose to partici‑

pate (the default), click Connect. When prompted, enter your Citrix account credentials.
After your credentials are validated (or if you choose not to participate), click Next.
For more information, see Call Home.
Step 12. Complete this installation
The Finish page contains green check marks for all prerequisites and components that installed and
initialized successfully.
Click Finish. By default, the machine restarts automatically. Although you can disable this automatic
restart, the VDA cannot be used until the machine restarts.
Next steps
Repeat the procedure above to install VDAs on other machines or images, if needed.
After you install all VDAs, launch Studio. If you haven’t created a site yet, Studio automatically guides
you to that task. After that’s done, Studio guides you to create a machine catalog and then a delivery
group. See:
• Create a site
• Create delivery groups
Customize a VDA
To customize an installed VDA:
1. From the Windows feature for removing or changing programs, select Citrix Virtual Delivery
Agent or Citrix Remote PC Access/VDI Core Services VDA. Then right‑click and select Change.

2. Select Customize Virtual Delivery Agent Settings. When the installer launches, you can
change:
• Controller addresses
• TCP/IP port to register with the Controller (default = 80)
• Whether to open Windows Firewall ports automatically
Troubleshoot
• For information about how Citrix reports the result of component installations, see Citrix instal‑
lation return codes.
• 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 Deliv‑
ery Controller.
To learn about VDA registration methods and how to troubleshoot registration issues, see VDA
registration.
Install using the command line
April 14, 2021
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.
Introduction
This article applies to installing components on machines with Windows operating systems. For infor‑
mation 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:
1. Download the product package from Citrix. Citrix account credentials are required to access the
download site.
2. Unzip the file. Optionally, burn a DVD of the ISO file.
3. Log on to the server where you are installing the components, using a local administrator ac‑
count.
4. Insert the DVD in the drive or mount the ISO file.
5. 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 the x64 > StoreFront folder

on the installation media.
To install the Universal Print Server: Follow the guidance in Command‑line options for in‑
stalling a Universal Print Server.
To install the Federated Authentication Service: Citrix recommends using the graphical in‑
terface.
To install Session Recording: Follow the guidance in Session Recording.
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.

1. Download the appropriate package from Citrix:
• Multi‑session OS Virtual Delivery Agent: VDAServerSetup.exe

• Single‑session OS Virtual Delivery Agent: VDAWorkstationSetup.exe
• Single‑session OS Core Services Virtual Delivery Agent: VDAWorkstationCoreSetup.
exe
2. 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 example
.\VDAWorkstationCoreSetup.exe /extract %temp%\CitrixVDAInstallMedia. The
directory must exist. Otherwise, the extract fails. Then in a separate command, run the appro‑
priate command below, 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, or VDAWorkstationCoreSetup.exe. Use the valid options listed in this article.
If you are familiar with the full product installer:
• Run the standalone VDAServerSetup.exe or VDAWorkstationSetup.exe installer as if it

was the XenDesktopVdaSetup.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 core components
The following options are valid when installing core components with the XenDesktopServerSetup
.exe command. For more detail about options, see Install core components.
• /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 noted 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. In most cases, 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_pending_reboot_check
When installing or upgrading core components, prevents checking for a pending restart from a
previous Windows installation on the machine.
• /no_remote_assistance
Valid only when installing Director. Disables the user shadowing feature that uses Windows Re‑
mote 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 au‑
tomatically 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 col‑
lected 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
Command‑line options for installing a VDA
The following options are valid with one or more of the following commands (installers):
XenDesktopVDASetup.exe, VDAWorkstationSetup.exe, and VDAWorkstationCoreSetup.
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 Citrix Workspace app).
This option is not valid when using the VDAWorkstationCoreSetup.exe installer. That in‑
staller cannot install 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 en‑
abled. If you are using a different firewall or no firewall, you must configure the firewall manu‑
ally. 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 Fire‑
wall 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 spec‑
ify 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

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:
– Machine Identity Service (includes TargetOSOptimizer.exe)

– 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
– Citrix Files for Windows
– Citrix Files for Outlook
– User personalization layer

Excluding Citrix Profile Management from the installation (/exclude "Citrix User
Profile Manager") 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 Manage‑
ment Service is not required.
If you plan to use MCS to provision VMs, do not exclude the Machine Identity Service. Excluding
that service also excludes installation of TargetOSOptimizer.exe.
If you specify both /exclude and /includeadditional with the same component name,
that component is not installed.
staller 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:

– Citrix Universal Print Client
– Citrix Telemetry Service
– Citrix Personalization for App-V - VDA
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

Enables MCS I/O write cache for storage optimization.
• /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. This
option also installs TargetOSOptimizer.exe (unless you also specify /exclude "Machine
Identity Service" which includes the optimizer installer). This option is equivalent to /
masterimage.
• /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 provi‑
sion 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 set‑
ting) is ignored, if specified.
Valid only when installing a VDA for multi‑session OS. Prevents enabling of the Enhanced Desk‑
top 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 au‑
tomatically 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.
• /optimize
When you use MCS and enable this feature (default), VM optimization disables offline files, dis‑
ables background defragmentation, and reduces event log size. For details, see CTX125874.
In addition to enabling this feature, optimization requires that the Machine Identity Service be
installed. That service contains the TargetOSOptimizer.exe. The Machine Identity Service
is installed automatically when you specify /mastermcsimage or /masterimage (and do not
specify /exclude "Machine Identity Service").
Do not specify this option for Remote PC Access deployments.
• /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 con‑
figuration 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 the following components on a single‑session OS:
– Citrix Personalization for App‑V

– Machine Identity Service (includes TargetOSOptimizer.exe)

staller 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), 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. This option is not available in the graph‑
ical 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.
• /virtualmachine
Valid only when installing a VDA on a VM. Overrides detection by the installer of a physical ma‑
chine, where BIOS information passed to VMs makes them appear as physical machines.
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 a master 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, optimization, 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"/optimize /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 auto‑
matically. 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 di‑
rectory 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
might not be the version installed on the machines. The machine’s Windows Programs and
Features display shows the actual VDA version.
ery Controller.
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 Support > VcRedist_2017 vcredist_x64.exe and

Runtime, 32‑bit and 64‑bit vcredist_x86.exe
Citrix Diagnostic Facility x64 > Virtual Desktop cdf_x64.msi
Components
Universal Print Server server x64 > Universal Print Server UpsServer_x64.msi
component
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 guid‑
ance in Provision printers.
More information
For information about how Citrix reports the result of component installations, see Citrix installation
return codes.
Install VDAs using scripts
April 14, 2021
This article applies to installing VDAs on machines with Windows operating systems. For information
about VDAs for Linux operating systems, see the Linux Virtual Delivery Agent documentation.
The installation media contains sample scripts that install, upgrade, or remove Virtual Delivery Agents
(VDAs) for machines in Active Directory. You can also use the scripts to maintain master images used
by Machine Creation Services and Citrix Provisioning (formerly Provisioning Services).
Required access:

• The scripts need Everyone Read access to the network share where the VDA installation com‑
mand is located. The installation command is XenDesktopVdaSetup.exe in the full product
ISO, or VDAWorkstationSetup.exe or VDAServerSetup.exe in a standalone installer.
• Logging details are stored on each local machine. To log results centrally for review and analysis,
the scripts need Everyone Read and Write access to the appropriate network share.
To check the results of running a script, examine the central log share. Captured logs include the script
log, the installer log, and the MSI installation logs. Each installation or removal attempt is recorded in
a time‑stamped folder. The folder title indicates the operation result with the prefix PASS or FAIL. You
can use standard directory search tools to find a failed installation or removal in the central log share.
Those tools offer an alternative to searching locally on the target machines.
Before beginning any installation, read and complete the tasks in Prepare to install.
Install or upgrade VDAs using the script
1. Obtain the sample script InstallVDA.bat from \Support\AdDeploy\ on the installation media.
Citrix recommends that you make a backup of the original script before customizing it.
2. Edit the script:
• Specify the version of the VDA to install: SET DESIREDVERSION. For example, version 7
can be specified as 7.0. The full value can be found on the installation media in the Pro‑
ductVersion.txt file. However, a complete match is not required.
• Specify the network share where the installer will be invoked. Point to the root of the
layout (the highest point of the tree). The appropriate version of the installer (32‑bit or
64‑bit) is called automatically when the script runs. For example: SET DEPLOYSHARE=\\
fileserver1\share1.
• Optionally, specify a network share location for storing centralized logs. For example: SET
LOGSHARE=\\fileserver1\log1).
• Specify VDA configuration options as described in Install using the command line. The
/quiet and /noreboot options are included by default in the script and are required:
SET COMMANDLINEOPTIONS=/QUIET /NOREBOOT.
3. Using Group Policy Startup Scripts, assign the script to the OU containing your machines. This
OU should contain only machines on which you want to install the VDA. When the machines in
that OU are restarted, the script runs on all of them. A VDA is installed on each machine that has
a supported operating system.
Remove VDAs using the script
1. Obtain the sample script UninstallVDA.bat from \Support\AdDeploy\ on the installation media.
Citrix recommends that you make a backup of the original script before customizing it.
2. Edit the script.

• Specify the version of the VDA to remove: SET CHECK\\_VDA\\_VERSION. For example,
version 7 can be specified as 7.0. The full value can be found on the installation media
in the ProductVersion.txt file (such as 7.0.0.3018). However, a complete match is not re‑
quired.
• Optionally, specify a network share location for storing centralized logs.
3. Using Group Policy Startup Scripts, assign the script to the OU containing your machines. This
OU should contain only machines from which you want to remove the VDA. When the machines
in the OU are restarted, the script runs on all of them. The VDA is removed from each machine.
Troubleshoot
• The script generates internal log files that describe script execution progress. The script copies
a Kickoff_VDA_Startup_Script log to the central log share within seconds of starting the
deployment. You can verify that the overall process is working. If this log is not copied to the
central log share as expected, troubleshoot further by inspecting the local machine. The script
places two debugging log files in the %temp% folder on each machine:
– Kickoff_VDA_Startup_Script_<DateTimeStamp>.log
– VDA_Install_ProcessLog_<DateTimeStamp>.log
Review these logs to ensure that the script is:
– Running as expected.
– Properly detecting the target operating system.
– Correctly configured to point to the ROOT of the DEPLOYSHARE share (contains the file
named AutoSelect.exe).
– Capable of authenticating to both the DEPLOYSHARE and LOG shares.
• For information about how Citrix reports the result of component installations, see Citrix instal‑
lation return codes.
might not be the version installed on the machines. The machine’s programs and features dis‑
play shows the actual VDA version.
ery Controller.
registration.

Install VDAs using SCCM
April 14, 2021
Overview
VDA installation has two phases:
• Install prerequisites
• Install the VDA
To successfully deploy the VDA using Microsoft System Center Configuration Manager (SCCM) or simi‑
lar software distribution tools, Citrix recommends addressing the phases separately. In other words,
instead of using the VDA installer to install both the prerequisites and the VDA, we recommend that
you first install the prerequisites using the prerequisites’ installers, and then install the VDA using a
VDA installer.
Identify requirements and task sequence
Prerequisites must be installed on the machine before the VDA is installed. VDA prerequisites vary,
depending on the VDA version. For guidance, see the system requirements for the VDA version you’re
installing:
• Citrix Virtual Apps and Desktops Current Release

• Citrix Virtual Apps and Desktops 1912 LTSR
• XenApp and XenDesktop 7.15 LTSR
Similarly, the need to install these prerequisites can vary between environments (for example, based
on the target machines’ operating system, and what the machines already have installed). Before
creating scripts or task sequences, it is important to understand your environment’s specific require‑
ments (such as which prerequisites need to be installed). Then, you can properly define the task se‑
quence.
Tip: A good way to collect this information is by manually installing the VDA in one of the machines
in the environment. This process reveals which prerequisites are identified as needed and installed
throughout the VDA installation process.
The installation files for the VDA’s prerequisites are included in the installation media for the Citrix
Virtual Apps and Desktops (or XenApp and XenDesktop) release under the Support folder. Use those
files to ensure that you’re installing the correct prerequisite versions.

Restarts
The required number of restarts during the installation of prerequisites and the VDA depends on the
environment. For example, a restart might be required for pending updates or restarts from earlier
software installations. Also, files previously locked by other processes might need updates.
• During the manual installation, identify which prerequisites trigger a restart.

• Some optional components in the VDA installer (such as Citrix User Profile Manager, Citrix Files)
might require a restart. During the manual installation, identify which component installations
trigger a restart.
Define the task sequence
After identifying all prerequisites and restarts, use the SCCM Task Sequencer to complete the follow‑
ing:
1. Create separate SCCM jobs for installing each prerequisite. This helps isolate any issues or fail‑
ures that occur during the deployment, which facilitates troubleshooting.
2. Create the VDA installation job. Do not execute this job until all prerequisites are successfully
installed. This can be accomplished one of two ways:
• Have the SCCM client monitor the prerequisites’ GUIDs to determine whether they are
present.
• Make the VDA installation job dependent on the prerequisites’ jobs.
SCCM installation sequence example
The following is an example SCCM installation sequence. Remember: Your prerequisite versions may
differ, depending on which VDA version you’re installing.
1. SCCM JOB1: Microsoft .NET Framework 4.8

2. SCCM JOB2: Microsoft Visual C++ 2017 Runtime (32‑bit and 64‑bit)
3. SCCM JOB3: VDA installation
a) Use the appropriate VDA installer command, based on requirements. Add the /quiet,
/noreboot, and /noresume options. (The /noresume option removes the dependency
on the interactive login to continue the install, thus allowing SCCM to drive the installation
process.)
b) Watch for return codes.
• 0: success, installation complete, restart required.
• 3: success, installation is not complete, restart required.
• 8: success, installation complete, restart required.
c) Restart the machine.

d) If the return code was 3, repeat step 3a.
For more information about return codes see Citrix installation return codes.
VDA installation command examples
The available installation options vary, depending on which installer is used. See the following arti‑
cles for command line option details. (Links are provided to Citrix Virtual Apps and Desktops Current
Release locations. If you’re using an LTSR product version, see the equivalent LTSR articles.)
• Install VDAs
• Install using the command line
Installation commands for Remote PC Access
• The following command uses the single‑session core VDA installer (standalone VDAWorkstationCoreSetup
.exe):
VDAWorkstationCoreSetup.exe /quiet /controllers “control.domain.com” /

enable_hdx_ports /noresume /noreboot
• The following command uses the single‑session full VDA installer (standalone VDAWorkstationSetup
.exe):
VDAWorkstationSetup.exe /quiet /remotepc /controllers “control.domain.
com” /enable_hdx_ports /noresume /noreboot
Installation command for dedicated VDI
• The following command uses the single‑session full VDA installer (standalone VDAWorkstationSetup
.exe):
VDAWorkstationSetup.exe /quiet /components vda /controllers “control
.domain.com” /enable_hdx_ports /optimize /enable_remote_assistance /

noresume /noreboot
Create a site
April 14, 2021
A site is the name you give to a Citrix Virtual Apps and Desktops deployment. It comprises the Delivery
Controllers and other core components, Virtual Delivery Agents (VDAs), connections to hosts, machine

catalogs, and delivery groups. You create the site after you install the core components and before
creating the first machine catalog and delivery group.
If your Controller is installed on Server Core, use PowerShell cmdlets in the Citrix Virtual Apps and
Desktops SDK to create a site.
When you create a site, you are automatically enrolled in the Citrix Customer Experience Improvement
Program (CEIP). CEIP collects anonymous statistics and usage information, and then sends it to Citrix.
The first data package is sent to Citrix approximately seven days after you create the site. You can
change your enrollment at any time after site creation. Select Configuration in the Studio navigation
pane, then the Product Support tab, and follow the guidance. For details, see http://more.citrix.com/
XD‑CEIP.
The user who creates a site becomes a full administrator; for more information, see Delegated admin‑
istration.
Review this article before you create the site, so you know what to expect.
Step 1. Open Studio and start the site creation wizard
Open Studio if it is not already open. You are automatically guided to the action that starts the site
creation wizard. Select that action.
Step 2. Site type and name
On the Introduction page, choose a site type:
• Application and desktop delivery Site. When you create an application and desktop delivery
site, you can further choose to create a full deployment site (recommended) or an empty site.
An empty site is only partially configured, and is usually created by advanced administrators.
• Remote PC Access Site. A Remote PC Access site allows designated users to remotely access
their office PCs through a secure connection.
If you create an application and desktop delivery deployment now, you can add a Remote PC Access
deployment later. Conversely, if you create a Remote PC Access deployment now, you can add a full
deployment later.
Type a name for the site. After the site is created, its name appears at the top of the Studio navigation
pane: Citrix Studio (site‑name).
Step 3. Databases
The Databases page contains selections for setting up the site, monitoring, and configuration logging
databases. For details about database setup choices and requirements, see Databases.

If you choose to install SQL Server Express for use as the site database (the default), a restart occurs
after that software is installed. That restart does not occur if you choose not to install the SQL Server
Express software for use as the site database.
If you are not using the default SQL Server Express, ensure that the SQL Server software is installed
on the machines before creating a site. System requirements lists the supported versions.
If you want to add more Delivery Controllers to the site, and have already installed the Controller
software on other servers, you can add those Controllers from this page. If you also plan to generate
scripts that set up the databases, add the Controllers before generating the scripts.
Step 4. Licensing
On the Licensing page, specify the License Server address and then indicate which license to use
(install).
• Specify the License Server address in the form name:[port]. The name must be an FQDN,
NetBIOS, or IP address. FQDN is recommended. If you omit the port number, the default is
27000. Click Connect. You cannot proceed to the next page until a successful connection is
made to the License Server.
• When a connection is made, Use an existing license is selected by default. The display lists
the compatible products that this product can be configured as, based on currently installed
licenses.
– If you want to configure this product as one of the listed products (for example, Citrix Vir‑
tual Apps Premium or Citrix Virtual Desktops Premium), using one of those licenses, select
that entry.
– If you already allocated and downloaded a license (using the Citrix Manage Licenses Tool)
to use with this product, but haven’t installed the license yet:
* Click Browse for license file.

* In the file explorer, locate and select the license you downloaded. The associated
products now appear on the Licensing page of the site creation wizard. Select the
entry you want to use.
– If the product you want is not displayed, or if you have no allocated and downloaded li‑
censes, you can allocate, download, and install a license. To do this, the License Server
must have internet access. You must have a License Access Code for the product you want.
Citrix emails that code to you.
* Click Allocate and download.

* In the Allocate Licenses dialog, enter the License Access Code sent by Citrix. Click
Allocate licenses.

* The products associated with the new license appear on the Licensing page of the
site creation wizard. Select the entry you want to use.
Alternatively, select Use the free 30‑day trial, and install licenses later. For details, see
the Licensing documentation.
Step 5. Power management (Remote PC Access only)
See Step 8. Remote PC Access.
Step 6. Host connection, network, and storage
If you are using VMs on a hypervisor or other service to deliver applications and desktops, you can
optionally create the first connection to that host. You can also specify storage and network resources
for that connection. After creating the site, you can modify this connection and resources, and create
more connections. For details, see Connections and resources.
• For information specified on the Connection page, see Connections and resources.
– If you are not using VMs on a hypervisor or other service (or if you use Studio to manage
desktops on dedicated blade PCs), select the connection type None.
– If you are configuring a Remote PC Access site and plan to use the Wake on LAN feature,
select the Microsoft System Center Configuration Manager type.
In addition to the connection type, specify whether you will use Citrix tools (such as Machine
Creation Services) or other tools to create VMs.
• For information specified on the Storage and Network pages, see Host storage, Storage man‑
agement, and Storage selection.
Step 7. Additional Features
On the Additional Features page, you can select features to customize your site. When you select the
check box for an item that requires information, a configuration box appears.
• App‑V Publishing: Select this feature if you use applications from Microsoft App‑V packages on
App‑V servers. Provide the URL of the App‑V management server and the URL and port number
of the App‑V publishing server.
If you use applications from App‑V packages on network share locations only, you do not need
to select this feature.
You can also enable/disable and configure this feature later in Studio. For more information,
see App‑V.

Step 8. Remote PC Access
For information about Remote PC Access deployments, see Remote PC Access.
If you use the Wake on LAN feature, complete the configuration steps on the Microsoft System Center
Configuration Manager before creating the site. For details, see Configuration Manager and Remote
PC Access Wake on LAN.
When you create a Remote PC Access site:
• If you’re using the Wake on LAN feature, specify the Microsoft System Center Configuration Man‑
ager address, credentials, and connection information on the Power Management page.
• Specify users or user groups on the Users page. There is no default action that automatically
adds all users. Also, specify machine accounts (domain and OU) information on the Machine
Accounts page.
To add user information, click Add Users. Select users and user groups, and then click Add
users.
To add machine accounts information, click Add machine accounts. Select the machine ac‑
counts, and then click Add machine accounts. Click Add OUs. Select the domain and Organi‑
zational Units, and indicate whether to include items in subfolders. Click Add OUs.
A machine catalog named Remote PC User Machine Accounts is created automatically. The cat‑
alog contains all the machine accounts you added in the site creation wizard. A delivery group named
Remote PC User Desktops is created automatically. The group contains all the users and user
groups you added.
Step 9. Summary
The Summary page lists the information you specified. Use the Back button if you want to change
anything. When you’re finished, click Create and the site creation begins.
Test a site configuration
To run the tests after you create the site, select Citrix Studio (Site site‑name) at the top of the nav‑
igation pane. Then click Test site in the center pane. You can view an HTML report of the site test
results.
The site test functionality might fail for a Controller installed on Windows Server 2016. The failure
occurs when a local SQL Server Express is used for the site database and the SQL Server Browser
service is not started. To avoid this failure, complete the following tasks.
1. Enable the SQL Server Browser service (if necessary) and then start it.
2. Restart the SQL Server (SQLEXPRESS) service.

Site tests run automatically when you upgrade an earlier deployment. For details, see Preliminary
site tests.
Troubleshoot
After configuring the site, you can install Studio and add it through the MMC as a snap‑in on a re‑
mote machine. If you later attempt to remove that snap‑in, the MMC might stop responding. As a
workaround, restart the MMC.
Create machine catalogs
April 14, 2021
Important:
As of Citrix Virtual Apps and Desktops 7 2006, if your current deployment uses any of the following
technologies or host types, you can upgrade your deployment to the current release only after
removing items that use those technologies.
• Personal vDisks (PvDs)

• AppDisks
• Public cloud host types: Amazon Web Services (AWS), Citrix CloudPlatform, Microsoft Azure
Classic, Microsoft Azure Resource Manager
For details, see Remove PVD, AppDisks, and unsupported hosts.
Introduction
Collections of physical or virtual machines are managed as a single entity called a machine catalog.
Machines in a catalog have the same type of operating system: multi‑session OS or single‑session OS.
A catalog containing multi‑session OS machines can contain either Windows or Linux machines, not
both.
Citrix Studio guides you to create the first machine catalog after you create the site. After you create
the first catalog, Studio guides you to create the first delivery group. Later, you can change the catalog
you created, and create more catalogs.
Tip:
Upgrading an existing deployment enables the Machine Creation Services (MCS) storage opti‑
mization (MCS I/O) feature, no additional configuration is required. The Virtual Delivery Agent
(VDA) and the Delivery Controller upgrade handle the MCS I/O upgrade.

Overview
When you create a catalog of VMs, you specify how to provision those VMs. You can use Citrix tools
such as Machine Creation Services (MCS) or Citrix Provisioning (formerly Provisioning Services). Or,
you can use your own tools to provide machines.
Consider:
• MCS supports a single system disk from the virtual machine image. It ignores the rest of the
data disks attached to that image.
• If you use Citrix Provisioning to create machines, see the Citrix Provisioning documentation for
instructions.
• If you use MCS to provision VMs, you provide a master image (or snapshot of an image) to create
identical VMs in the catalog. Before you create the catalog, you first use tools to create and
configure the master image. This process includes installing a Virtual Delivery Agent (VDA) on
the image. Then you create the machine catalog in Studio. You select that image (or snapshot),
specify the number of VMs to create in the catalog, and configure additional information.
• If your machines are already available, you must still create one or more machine catalogs for
those machines.
• If you are creating a catalog using the PowerShell SDK directly, you can specify a hypervisor
template (VMTemplates), rather than an image or a snapshot.
• Using a template to provision a catalog is considered an experimental feature. When using this
method, virtual machine preparation might fail. As a result, the catalog cannot be published
using the template.
When using MCS or Citrix Provisioning to create the first catalog, you use the host connection that you
configured when you created the site. Later (after you create your first catalog and delivery group),
you can change information about that connection or create more connections.
After you complete the catalog creation wizard, tests run automatically to ensure that it is configured
correctly. When the tests complete, you can view a test report. Run the tests at any time from Studio.
Note:
MCS does not support Windows 10 IoT Core and Windows 10 IoT Enterprise. Refer to the Microsoft
site for more information.
For technical details about the Citrix Provisioning tools, see Citrix Virtual Apps and Desktops Image
Management.
RDS license check
Citrix Studio currently does not perform the check for valid Microsoft RDS licenses while creating a ma‑
chine catalog that contains Windows multi‑session OS machines. To view the status of the Microsoft
RDS license for a Windows multi‑session OS machine, go to Citrix Director. View the status of the

Microsoft RDS license in the Machine Details panel. This panel is located in the Machine Details and
the User Details page. For more information, see Microsoft RDS license health.
VDA registration
A VDA must be registered with a Delivery Controller when launching brokered sessions. Unregistered
VDAs can result in underutilization of otherwise available resources. There are various reasons a VDA
might not be registered, many of which an administrator can troubleshoot. Studio provides trou‑
bleshooting information in the catalog creation wizard, and after you add machines from a catalog
to a delivery group.
After you add existing machines using the wizard, the list of computer account names indicates
whether each machine is suitable for adding to the catalog. Hover over the icon next to each machine
to display an informative message about that machine.
If the message identifies a problematic machine, either remove that machine, or add the machine.
For example, if a message indicates that information might not be obtained about a machine, add the
machine anyway.
For more information, see:
• CTX136668 for VDA registration troubleshooting guidance

• VDA versions and functional levels
• VDA registration methods
MCS catalog creation summary
Here’s a brief overview of default MCS actions after you provide information in the catalog creation
wizard.
• If you selected a master image (rather than a snapshot), MCS creates a snapshot.
• MCS creates a full copy of the snapshot and places the copy on each storage location defined in
the host connection.
• MCS adds the machines to Active Directory, which creates unique identities.
• MCS creates the number of VMs specified in the wizard, with two disks defined for each VM. In
addition to the two disks per VM, a master is also stored in the same storage location. If you
have multiple storage locations defined, each gets the following disk types:
– The full copy of the snapshot which is read‑only and shared across the just‑created VMs.
– A unique 16 MB identity disk that gives each VM a unique identity. Each VM gets an identity
disk.
– A unique difference disk to store writes made to the VM. This disk is thin provisioned (if
supported by the host storage) and increases to the maximum size of the master image, if
necessary. Each VM gets a difference disk. The difference disk holds changes made during

sessions. It is permanent for dedicated desktops. For pooled desktops, it is deleted and a
new one created after each restart via the delivery controller.
Alternatively, when creating VMs to deliver static desktops, you can specify (on the Machines page
of the catalog creation wizard) thick (full copy) VM clones. Full clones do not require retention of the
master image on every data store. Each VM has its own file.
MCS storage considerations
There are many factors when deciding on storage solutions, configurations, and capacities for MCS.
The following information provides proper considerations for storage capacity:
Capacity considerations:
• Disks
The Delta or Differencing (Diff) Disks consume the largest amount of space in most MCS deploy‑
ments for each VM. Each VM created by MCS is given at minimum 2 disks upon creation.
– Disk0 = Diff Disk: contains the OS when copied from the Master Base Image.
– Disk1 = Identity Disk: 16 MB ‑ contains Active Directory data for each VM.
As the product evolves, you might have to add more disks to satisfy certain use cases and feature
consumption. For example:
– MCS Storage Optimization creates a write cache style disk for each VM.
– MCS added the ability to use full clones as opposed to the Delta disk scenario described in
the previous section.
Hypervisor features might also enter into the equation. For example:
– Citrix Hypervisor IntelliCache creates a Read Disk on local storage for each Citrix Hyper‑
visor. This option saves on IOPS against the master image which might be held on the
shared storage location.
• Hypervisor overhead
Different hypervisors utilize specific files that create overhead for VMs. Hypervisors also use
storage for management and general logging operations. Calculate space to include overhead
for:
– Log files
– Hypervisor specific files. For example:
* VMware adds more files to the VM storage folder. See VMware Best Practices.
* Calculate your total virtual machine size requirements. Consider a virtual machine
containing 20 GB for the virtual disk, 16 GB for the swap file, and 100 MB for log files
consuming 36.1 GB total.

– Snapshots for XenServer; Snapshots for VMware.
• Process overhead
Creating a catalog, adding a machine, and updating a catalog have unique storage implications.
For example:
– Initial catalog creation requires a copy of the base disk to be copied to each storage loca‑
tion.
* It also requires you to create a Preparation VM temporarily.
– Adding a machine to a catalog does not require copying of the base disk to each storage
location. Catalog creation varies based on the features selected.
– Updating the catalog to create an extra base disk on each storage location. Catalog up‑
dates also experience a temporary storage peak where each VM in the catalog has 2 Diff
disks for a certain amount of time.
More considerations:
• RAM sizing: Affects the size of certain hypervisor files and disks, including I/O optimization
disks, write cache, and snapshot files.
• Thin / Thick provisioning: NFS storage is preferred due to the thin provisioning capabilities.
Machine Creation Services (MCS) storage optimization
With the Machine Creation Services (MCS) storage optimization feature, referred to as MCS I/O:
• The write cache container is file‑based, the same functionality found in Citrix Provisioning. For
example, the Citrix Provisioning write cache file name is D:\vdiskdif.vhdx and the MCS I/O
write cache file name is D:\mcsdif.vhdx.
• Achieve diagnostic improvements by including support for a Windows crash dump file written
to the write cache disk.
• MCS I/O retains the technology cache in RAM with overflow to hard disk to provide the most op‑
timal multi‑tier write cache solution. This functionality allows an administrator to balance be‑
tween the cost in each tier, RAM and disk, and performance to meet the desired workload ex‑
pectation.
Updating the write cache method from disk‑based to file‑based requires the following changes:
1. MCS I/O no longer supports RAM only cache. Specify a disk size in Citrix Studio during machine
catalog creation.
2. The VM write cache disk is created and formatted automatically when booting a VM for the first
time. Once the VM is up, the write cache file mcsdif.vhdx is written into the formatted volume
MCSWCDisk.
3. The pagefile is redirected to this formatted volume, MCSWCDisk. As a result, this disk size consid‑
ers the total amount of disk space. It includes the delta between the disk size and the generated

workload plus the pagefile size. This is typically associated with VM RAM size.
Enabling MCS storage optimization updates
To enable MCS I/O storage optimization functionality, upgrade the Delivery Controller and the VDA to
the latest version of Citrix Virtual Apps and Desktops.
Note:
If you upgrade an existing deployment which has MCS I/O enabled, no additional configuration
is required. The VDA and the Delivery Controller upgrade handle the MCS I/O upgrade.
When enabling the MCS storage optimization update, consider the following:
• When creating a machine catalog, the administrator can configure the RAM and disk size.
• Updating an existing machine catalog to a new VM snapshot containing a VDA configured for
version 1903 results in the following behavior: the new snapshot continues to use the existing
catalog’s MCS I/O setting for RAM and disk size. The existing raw disk is formatted.
Important:
MCS storage optimization changed with Citrix Virtual Apps and Desktops version 1903. This re‑

lease supports file‑based write cache technology, providing better performance and stability.
The new functionality provided by MCS I/O might require a higher write cache storage require‑
ment compared to previous Citrix Virtual Apps and Desktops releases. Citrix recommends that
you reevaluate the disk size to ensure that it has sufficient disk space for the allocated workflow
and extra pagefile size. The pagefile size is typically related to the amount of system RAM. If the
existing catalog disk size is insufficient, create a machine catalog and allocate a larger write cache
disk.
Using PowerShell to create a catalog with persistent write‑back cache disk
To configure a catalog with persistent write‑back cache disk, use the PowerShell parameter New
-ProvScheme CustomProperties. This parameter supports an extra property, PersistWBC,
used to determine how the write‑back cache disk persists for MCS provisioned machines. The
PersistWBC property is only used when the UseWriteBackCache parameter is specified, and when
the WriteBackCacheDiskSize parameter is set to indicate that a disk is created.
Examples of properties found in the CustomProperties parameter before supporting PersistWBC

include:
1 <CustomProperties xmlns="http://schemas.citrix.com/2014/xd/
machinecreation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-
instance">
2 <Property xsi:type="StringProperty" Name="UseManagedDisks" Value="true"
/>
3 <Property xsi:type="StringProperty" Name="StorageAccountType" Value="
Premium_LRS" />
4 <Property xsi:type="StringProperty" Name="ResourceGroups" Value="
benvaldev5RG3" />
5 </CustomProperties>
6 
When using these properties, consider that they contain default values if the properties are omitted
from the CustomProperties parameter. The PersistWBC property has two possible values: true
or false.
Setting the PersistWBC property to true does not delete the write‑back cache disk when the Citrix
Virtual Apps and Desktops administrator shuts down the machine using Citrix Studio.
Setting the PersistWBC property to false deletes the write‑back cache disk when the Citrix Virtual
Apps and Desktops administrator shuts down the machine using Citrix Studio.
Note:
If the PersistWBC property is omitted, the property defaults to false and the write‑back cache

is deleted when the machine is shutdown using Citrix Studio.
For example, using the CustomProperties parameter to set PersistWBC to true:
1 <CustomProperties xmlns="http://schemas.citrix.com/2014/xd/
machinecreation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-
instance">
2 <Property xsi:type="StringProperty" Name="UseManagedDisks" Value="true"
/>
3 <Property xsi:type="StringProperty" Name="StorageAccountType" Value="
Premium_LRS" />
4 <Property xsi:type="StringProperty" Name="ResourceGroups" Value="
benvaldev5RG3" />
5 <Property xsi:type="StringProperty" Name="PersistWBC" Value="true" />
6 </CustomProperties>
7 
Important:
The PersistWBC property can only be set using the New-ProvScheme PowerShell cmdlet. At‑
tempting to alter the CustomProperties of a provisioning scheme after creation has no impact
on the machine catalog and the persistence of the write‑back cache disk when a machine is shut
down.
For example, set New-ProvSchemeto use the write‑back cache while setting the PersistWBC prop‑
erty to true:
1 New-ProvScheme
2 -CleanOnBoot
3 -CustomProperties "<CustomProperties xmlns=`"http://schemas.citrix.com
/2014/xd/machinecreation`" xmlns:xsi=`"http://www.w3.org/2001/
XMLSchema-instance`"><Property xsi:type=`"StringProperty`" Name=`"
UseManagedDisks`" Value=`"true`" /><Property xsi:type=`"
StringProperty`" Name=`"StorageAccountType`" Value=`"Premium_LRS`"
/><Property xsi:type=`"StringProperty`" Name=`"ResourceGroups`"
Value=`"benvaldev5RG3`" /><Property xsi:type=`"StringProperty`" Name
=`"PersistWBC`" Value=`"true`" /></CustomProperties>"
4 -HostingUnitName "adSubnetScale1"
5 -IdentityPoolName "BV-WBC1-CAT1"
6 -MasterImageVM "XDHyp:\HostingUnits\adSubnetScale1\image.folder\
GoldImages.resourcegroup\W10MCSIO-01
_OsDisk_1_a940e6f5bab349019d57ccef65d2c7e3.manageddisk"
7 -NetworkMapping @{
8 "0"="XDHyp:\HostingUnits\adSubnetScale1\\virtualprivatecloud.folder\
CloudScale02.resourcegroup\adVNET.virtualprivatecloud\
adSubnetScale1.network" }

9
10 -ProvisioningSchemeName "BV-WBC1-CAT1"
11 -ServiceOffering "XDHyp:\HostingUnits\adSubnetScale1\serviceoffering.
folder\Standard_D2s_v3.serviceoffering"
12 -UseWriteBackCache
13 -WriteBackCacheDiskSize 127
14 -WriteBackCacheMemorySize 256
15 
Prepare a master image
For information about creating connections hosts, see Connections and resources.
The master image contains the operating system, non‑virtualized applications, VDA, and other soft‑
ware.
Good to know:
• A master image might also be known as a clone image, golden image, base VM, or base image.
Host vendors use different terms.
• When using Citrix Provisioning, you can use a master image or a physical computer as the master
target device. Citrix Provisioning uses different terminology than MCS to refer to images. See
the Citrix Provisioning documentation for details.
• Ensure that the host has enough processors, memory, and storage to accommodate the number
of machines created.
• Configure the correct amount of hard disk space needed for desktops and applications. That
value cannot be changed later or in the machine catalog.
• Remote PC Access machine catalogs do not use master images.
• Microsoft KMS activation considerations when using MCS: If your deployment includes 7.x VDAs
with a XenServer 6.1 or 6.2, vSphere, or Microsoft System Center Virtual Machine Manager host,
you do not need to manually rearm Microsoft Windows or Microsoft Office.
Install and configure the following software on the master image:
• Integration tools for your hypervisor (such as Citrix VM Tools, Hyper‑V Integration Services, or
VMware tools). If you omit this step, applications and desktops might not function correctly.
• A VDA. Citrix recommends installing the latest version to allow access to the newest features.
Failure to install a VDA on the master image causes the catalog creation to fail.
• Third‑party tools as needed, such as antivirus software or electronic software distribution
agents. Configure services with settings that are appropriate for users and the machine type
(such as updating features).
• Third‑party applications that you are not virtualizing. Citrix recommends virtualizing applica‑
tions. Virtualizing reduces costs by eliminating having to update the master image after adding

or reconfiguring an application. Also, fewer installed applications reduce the size of the master
image hard disks, which saves storage costs.
• App‑V clients with the recommended settings, if you plan to publish App‑V applications. The
App‑V client is available from Microsoft.
• When using MCS, if you localize Microsoft Windows, install the locales and language packs. Dur‑
ing provisioning, when a snapshot is created, the provisioned VMs use the installed locales and
language packs.
Important:
If you are using Citrix Provisioning or MCS, do not run Sysprep on master images.
To prepare a master image:
1. Using your hypervisor’s management tool, create a master image and then install the operating
system, plus all service packs and updates. Specify the number of vCPUs. You can also specify
the vCPU value if you create the machine catalog using PowerShell. You cannot specify the num‑
ber of vCPUs when creating a catalog using Studio. Configure the amount of hard disk space
needed for desktops and applications. That value cannot be changed later or in the catalog.
2. Ensure that the hard disk is attached at device location 0. Most standard master image tem‑
plates configure this location by default, but some custom templates might not.
3. Install and configure the software listed above on the master image.
4. When using Citrix Provisioning, create a VHD file for the virtual disk from your master target
device before you join the master target device to a domain. See the Citrix Provisioning docu‑
mentation for details.
5. If you are not using MCS, join the master image to the domain where applications and desk‑
tops are members. Ensure that the master image is available on the host where the machines
are created. If you are using MCS, joining the master image to a domain is not required. The
provisioned machines are joined to the domain specified in the catalog creation wizard.
6. Citrix recommends that you create and name a snapshot of your master image. If you specify a
master image rather than a snapshot when creating a catalog, Studio creates a snapshot. You
cannot name it.
Create a machine catalog using Studio
Before starting the catalog creation wizard, review this section.
If you are using a master image, ensure that you have installed a VDA on the image before creating the
catalog.
From Studio:
• If you already created a site but haven’t yet created a machine catalog, Studio guides you to the
correct starting place to create a catalog.

• If you already created a catalog and want to create another, select Machine Catalogs in the
Studio navigation pane. Then select Create Machine Catalog in the Actions pane.
The wizard walks you through the following items. The wizard pages you see differ, depending on the
selections you make.
Operating system
Each catalog contains machines of only one type. Select one.
• Multi‑session OS: A multi‑session OS catalog provides hosted shared desktops. The machines
can be running supported versions of the Windows or Linux operating systems, but the catalog
cannot contain both. (See the Linux VDA documentation for details about that OS.)
• Single‑session OS: A single‑session OS catalog provides VDI desktops that you can assign to
various different users.
• Remote PC Access: A Remote PC Access catalog provides users with remote access to their
physical office desktop machines. Remote PC Access does not require a VPN to provide security.
Machine management
This page does not appear when you are creating Remote PC Access catalogs.
The Machine Management page indicates how machines are managed and which tool you use to
deploy machines.
Choose whether machines in the catalog are power managed through Studio.
• Machines are power managed through Studio, for example, VMs or blade PCs. This option is
available only if you already configured a connection to a host.
• Machines are not power managed through Studio, for example, physical machines.
If you indicated that machines are power managed through Studio, choose which tool to use to create
VMs.
• Citrix Machine Creation Services (MCS): Uses a master image to create and manage virtual
machines. MCS is not available for physical machines.
• Citrix Provisioning: (Formerly Provisioning Services.) Manages target devices as a device col‑
lection. A Citrix Provisioning virtual disk imaged from a master target device delivers desktops
and applications.
• Other: A tool that manages machines already in the data center. Citrix recommends that you
use Microsoft System Center Configuration Manager or another third‑party application to en‑
sure that the machines in the catalog are consistent.

Desktop types (desktop experience)
This page appears only when you are creating a catalog containing single‑session OS machines.
The Desktop Experience page determines what occurs each time a user logs on. Select one of:
• Users connect to a new (random) desktop each time they log on.
• Users connect to the same (static) desktop each time they log on.
If you choose the second option and are using Citrix Provisioning to provision the machines, you can
configure how user changes to the desktop are handled:
• Save user changes to the desktop on the local disk.

• Discard user changes and clear the virtual desktop when the user logs off. Select this option if
you are using user personalization layer.
Master image
This page appears only when you are using MCS to create VMs.
On the Master image page, select the connection to the host, and then select the snapshot or VM
created earlier. If you are creating the first catalog, the only available connection is the one you con‑
figured when you created the site.
Remember:
• When you are using MCS or Citrix Provisioning, do not run Sysprep on master images.
• If you specify a master image rather than a snapshot, Studio creates a snapshot, but you cannot
name it.
To enable use of the latest product features, ensure the master image has the latest VDA version in‑
stalled. Do not change the default minimum VDA selection. However, if you must use an earlier VDA
version, see VDA versions and functional levels.
An error message appears if you select a snapshot or VM that is not compatible with the machine
management technology you selected earlier in the wizard.
Device Collection
This page appears only when using Citrix Provisioning to create VMs.
The Device Collection page displays the device collections and the devices that have not already been
added to catalogs.
Select the device collections to use.

Machines
The title of this page depends on what you selected on the Machine Management page: Machines,
Virtual Machines, or VMs and users.
When using MCS:
• Specify how many virtual machines to create.

• Choose the amount of memory (in MB) each VM has.
• Each created VM has a hard disk. Its size is set in the master image. You cannot change the hard
disk size in the catalog.
• If your deployment contains more than one zone, you can select a zone for the catalog.
• If you are creating static desktop VMs, select a virtual machine copy mode. See Virtual machine
copy mode.
• If you are creating random desktop VMs that do not use vDisks, you can configure a cache to be
used for temporary data on each machine. See Configure cache for temporary data.
When using Citrix Provisioning:
The Devices page lists the machines in the device collection that you selected on the previous wizard
page. You cannot add or remove machines on this page.
When using other tools:
Add (or import a list of) Active Directory machine account names. You can change the Active Direc‑
tory account name for a VM after you add/import it. If you specified static machines on the Desktop
Experience page, you can optionally specify the Active Directory user name for each VM you add.
After you add or import names, you can use the Remove button to delete names from the list, while
you are still on this page.
When using Citrix Provisioning or other tools (but not MCS):
An icon and tooltip for each machine added (or imported, or from a Citrix Provisioning device collec‑
tion) help identify machines that might not be eligible to add to the catalog, or be unable to register
with a Delivery Controller. For details, see VDA versions and functional levels.
Virtual machine copy mode
The copy mode you specify on the Machines page determines whether MCS creates thin (fast copy)
or thick (full copy) clones from the master image. (Default = thin clones)
• Use fast copy clones for more efficient storage use and faster machine creation.
• Use full copy clones for better data recovery and migration support, with potentially reduced
IOPS after the machines are created.

VDA versions and functional levels
A catalog’s functional level controls which product features are available to machines in the catalog.
Using features introduced in new product versions require a new VDA. Setting a functional level makes
all features introduced in that version (and later, if the functional level does not change) available
to machines in the catalog. However, machines in that catalog with an earlier VDA version cannot
register.
A menu near the bottom of the Machines (or Devices) page allows you to select the minimum VDA
level. This sets the catalog’s minimum functional level. By default, the most current functional level
is selected for on‑premises deployments. If you follow the Citrix recommendation to always install
and upgrade VDAs and core components to the latest version, you don’t need to change this selection.
However, if you must continue using older VDA versions, select the correct value.
A Citrix Virtual Apps and Desktops release might not include a new VDA version, or the new VDA does
not impact the functional level. In such cases, the functional level might indicate a VDA version that is
earlier than the installed or upgraded components. For example, although version 7.17 contains a 7.17
VDA, the default functional level (“7.9 or later”) remains the most current. Therefore, after installing
or upgrading components 7.9–7.16 to 7.17, you do not need to change the default functional level.
Each release’s What’s new article indicates any change in the default functional level.
The selected functional level affects the list of machines above it. In the list, a tooltip next to each
entry indicates whether the machine’s VDA is compatible with the catalog at that functional level.
Messages are posted on the page if the VDA on each machine does not meet or exceed the minimum
functional level selected. You can continue with the wizard. Those machines will likely not be able to
register with a Controller later. Alternatively, you can:
• Remove the machines containing older VDAs from the list, upgrade their VDAs and then add
them back to the catalog.
• Choose a lower functional level that prevents access to the latest product features.
A message is also posted if a machine was not be added to the catalog because it is the wrong machine
type. Examples include attempting to add a server to a single‑session OS catalog, or adding a single‑
session OS machine originally created for random allocation to a catalog of static machines.
Important:
At release 1811, an extra functional level was added: 1811 (or newer). That level is intended for
use with future Citrix Virtual Apps and Desktops features. The 7.9 (or newer) selection remains
the default. That default is valid for all deployments now.
If you select 1811 (or newer), any earlier VDA versions in that catalog are unable to register with
a Controller or Cloud Connector. However, if the catalog contains only VDAs at version 1811 or
later supported versions, they are all eligible to register. This includes catalogs containing VDAs

configured for later Citrix Virtual Apps and Desktops releases, including version 1903 and other
19XX releases prior to the current release.
Configure cache for temporary data
Caching temporary data locally on the VM is optional. You can enable use of the temporary data cache
on the machine when you use MCS to manage pooled (not dedicated) machines in a catalog. If the
catalog uses a connection that specifies storage for temporary data, you can enable and configure the
temporary data cache information when you create the catalog.
Important:
This feature requires a current MCS I/O driver. Installing this driver is an option when you install
or upgrade a VDA. By default, that driver is not installed.
You specify whether temporary data uses shared or local storage when you create the connection
that the catalog uses. For more information, see Connections and resources. To configure a cache
for temporary data on each machine, you can use the following two options: Memory allocated to
cache (MB) and Disk cache size (GB). By default, the two options are cleared. To enable the Memory
allocated to cache (MB) option, select the Disk cache size (GB) check box. If the Disk cache size check
box is not selected, the Memory allocated to cache option is grayed out. Depending on the connection
type, the default values for these options might differ. Generally, the default values are sufficient for
most cases. However, take into account the space needed for:
• Temporary data files created by Windows itself, including the Windows page file.
• User profile data.
• ShareFile data that is synced to users’ sessions.
• Data that might be created or copied by a session user or any applications users might install
inside the session.
Windows will not allow a session to use a cache disk that is larger than the amount of free space on
the original master image from which machines in the machine catalog are provisioned. For example,
there is no benefit specifying a 20 GB cache disk if there is only 10 GB of free space on the master image.

To configure a cache for temporary data on each machine, be aware of the following three scenarios:
• If you don’t select the Disk cache size check box and the Memory allocated to cache check box,
temporary data is not cached. It is directly written to the difference disk (located in the OS stor‑
age) for each VM. (This is the provisioning action in version 7.8 and earlier.)
• If you select the Disk cache size check box and don’t select the Memory allocated to cache check
box, temporary data is directly written to the cache disk, using a minimal amount of memory
cache.
• If you select the Disk cache size check box and the Memory allocated to cache check box, tem‑
porary data is initially written to the memory cache. When the memory cache reaches its con‑
figured limit (the Memory allocated to cache value), the oldest data is moved to the temporary
data cache disk.
Important:
• If the disk cache runs out of space, the user’s session becomes unusable.
• This feature is not available when using a Nutanix host connection.
• You cannot change the cache values in a machine catalog after the machine is created.
Note:
• The memory cache is part of the total amount of memory on each machine. Therefore, if
you enable the Memory allocated to cache option, consider increasing the total amount of
memory on each machine.
• Changing the Disk cache size from its default value can affect performance. The size must
match user requirements and the load placed on the machine.

Network Interface Cards (NICs)
On the Network Interface Cards page, if you plan to use multiple NICs, associate a virtual network
with each card. For example, you can assign one card to access a specific secure network, and another
card to access a more commonly used network. You can also add or remove NICs from this page.
Machine accounts
This page appears only when creating Remote PC Access catalogs.
On the Machine Accounts page, specify the Active Directory machine accounts or Organizational
Units (OUs) to add that correspond to users or user groups. Do not use a forward slash (/) in an OU
name.
You can choose a previously configured power management connection or elect not to use power
management. If you want to use power management but a suitable connection hasn’t been config‑
ured yet, you can create that connection later and then edit the machine catalog to update the power
management settings.
Computer accounts
This page appears only when using MCS to create VMs.
Each machine in the catalog must have a corresponding Active Directory computer account. On the
Computer Accounts page, indicate whether to create accounts or use existing accounts, and the lo‑
cation for those accounts.
• If you create accounts, you must have access to a domain administrator account for the domain
where the machines reside.
Specify the account naming scheme for the machine, using hash marks to indicate where se‑
quential numbers or letters appear. Do not use a forward slash (/) in an OU name. A name
cannot begin with a number. For example, a naming scheme of PC‑Sales‑## (with 0‑9 selected)
results in computer accounts named PC‑Sales‑01, PC‑Sales‑02, PC‑Sales‑03, and so on.
• If you use existing accounts, either browse to the accounts or click Import and specify a .csv file
containing account names. The imported file content must use the format:
1 [ADComputerAccount]
2 ADcomputeraccountname.domain
3 ...
4 

Ensure that there are enough accounts for all the machines you’re adding. Studio manages these
accounts, so either allow Studio to reset the passwords for all the accounts or specify the account
password, which must be the same for all accounts.
For catalogs containing physical machines or existing machines, select or import existing accounts.
Assign each machine to both an Active Directory computer account and to a user account.
For machines created with Citrix Provisioning, computer accounts for target devices are managed dif‑
ferently; see the Citrix Provisioning documentation.
Summary, name, and description
On the Summary page, review the settings you specified. Enter a name and description for the cata‑
log. This information appears in Studio.
When you’re done, click Finish to start the catalog creation.
Troubleshoot
Important:
After creating the machine catalog using Citrix Studio, you can no longer use the Get-ProvTask
PowerShell command to retrieve the tasks associated with machine catalog creation. This re‑
striction is a result of Studio deleting those tasks after machine catalog creation regardless of
whether the catalog is created successfully.
Citrix recommends collecting logs to help the Support team provide solutions. When using Citrix Pro‑
visioning, use the following procedure to generate log files:
1. On the master image, create the following registry key with the value of 1 (as a DWORD (32‑bit)
value): HKLM\Software\Citrix\MachineIdentityServiceAgent\LOGGING.
2. Shut down the master image and create a snapshot.
3. On the Delivery Controller, run the following PowerShell command: Set-ProvServiceConfigurationDat

-Name ImageManagementPrep_NoAutoShutdown -Value $True.
4. Create a catalog based on that snapshot.
5. When the preparation VM is created on the hypervisor, log in and extract the following files from
the root of C:\: Image‑prep.log and PvsVmAgentLog.txt.
6. Shut down the machine, at which point it reports the failure.
7. Run the following PowerShell command to re‑enable auto shutdown of the image preparation
machines: Remove-ProvServiceConfigurationData -Name ImageManagementPrep_NoAutoShutd
.

Where to go next
If this is the first catalog created, Studio guides you to create a delivery group.
Manage machine catalogs
April 14, 2021
Introduction
You can add or remove machines from a machine catalog, rename, change the description, or manage
a catalog’s Active Directory computer accounts.
Maintaining catalogs can also include making sure each machine has the latest OS updates. Including
antivirus updates, operating system upgrades, or configuration changes.
• Catalogs containing pooled random machines created using Machine Creation Services (MCS)
maintain machines by updating the master image used in the catalog and then updating the
machines. This method enables you to efficiently update large numbers of user machines.
• For machines created using Citrix Provisioning, updates to machines are propagated through
the virtual disk. See the Citrix Provisioning documentation for details.
• For catalogs containing static, permanently assigned machines, and for Remote PC Access Ma‑
chine catalogs, you manage updates to users’ machines outside of Studio. Perform this task
either individually or collectively using third‑party software distribution tools.
For information about creating and managing connections to host hypervisors, see Connections and
resources.
Note:
MCS does not support Windows 10 IoT Core and Windows 10 IoT Enterprise. Refer to the Microsoft
site for more information.
About persistent instances
When updating an MCS catalog created using persistent, or dedicated instances, any new machines
created for the catalog use the updated image. Pre‑existing instances continue to use the original in‑
stance. The process of updating an image is done the same way for any other type of catalog. Consider
the following:
• With persistent disk catalogs, the pre‑existing machines are not updated to the new image, but
any new machines added to the catalog use the new image.

• For non‑persistent disk catalogs, the machine image is updated the next time the machine is
reset.
• With persistent machine catalogs, updating the image also updates the catalog instances that
use it.
• For catalogs that do not persist, if you want different images for different machines, the images
must reside in separate catalogs.
Add machines to a catalog
Before you start:

• Make sure the virtualization host has sufficient processors, memory, and storage to accommo‑
date the additional machines.
• Make sure that you have enough unused Active Directory computer accounts. If you are using
existing accounts, the number of machines you can add is limited by the number of accounts
available.
• If you use Studio to create Active Directory computer accounts for the additional machines, you
must have appropriate domain administrator permission.
To add machines to a catalog:
1. Select Machine Catalogs in the Studio navigation pane.
2. Select a machine catalog and then select Add machines in the Actions pane.
3. Select the number of virtual machines to add.
4. If there are insufficient existing Active Directory accounts for the number of VMs you are adding,
select the domain and location where the accounts are created. Specify an account naming
scheme, using hash marks to indicate where sequential numbers or letters appear. Do not use
a forward slash (/) in an OU name. A name cannot begin with a number. For example, a naming
scheme of PC‑Sales‑## (with 0‑9 selected) results in computer accounts named PC‑Sales‑01, PC‑
Sales‑02 , PC‑Sales‑03, and so on.
5. If you use existing Active Directory accounts, either browse to the accounts or click Import and
specify a .csv file containing account names. Make sure that there are enough accounts for all
the machines you’re adding. Studio manages these accounts. Either allow Studio to reset the
passwords for all the accounts, or specify the account password, which must be the same for all
accounts.
The machines are created as a background process, and can take much time when creating many
machines. Machine creation continues even if you close Studio.
Delete machines from a catalog
After you delete a machine from a machine catalog, users can no longer access it, so before deleting
a machine, ensure that:

• User data is backed up or no longer required.

• All users are logged off. Turning on maintenance mode stops new connections from being made
to a machine.
• Machines are powered off.
To delete machines from a catalog:

2. Select a catalog and then select View Machines in the Actions pane.
3. Select one or more machines and then select Delete in the Actions pane.
Choose whether to delete the machines being removed. If you choose to delete the machines, indicate
if the Active Directory accounts for those machines are retained, disabled, or deleted.
Change a catalog description or change Remote PC Access settings

2. Select a catalog and then select Edit Machine Catalog in the Actions pane.
3. For Remote PC Access catalog, use the Power Management page to change the power manage‑
ment settings and select a power management connection. On the Organizational Units page,
add or remove Active Directory OUs.
4. On the Description page, change the catalog description.
Rename a catalog

2. Select a catalog and then select Rename Machine Catalog in the Actions pane.
3. Enter the new name.
Move a catalog to a different zone
If your deployment has more than one zone, you can move a catalog from one zone to another.
Moving a catalog to a different zone, other than the hypervisor containing the VMs in that catalog,
affects performance.

2. Select a catalog and then select Move in the Actions pane.
3. Select the zone where you want to move the catalog.
Delete a catalog
Before deleting a catalog, ensure that:

• All users are logged off and that no disconnected sessions are running.
• Maintenance mode is turned on for all machines in the catalog so that new connections cannot
be made.
• All machines in the catalog are powered off.
• The catalog is not associated a delivery group. In other words, the delivery group does not con‑
tain machines from the catalog.
To delete a catalog:

2. Select a catalog and then select Delete Machine Catalog in the Actions pane.
3. Indicate whether the machines in the catalog are deleted. If you choose to delete the machines,
indicate whether the Active Directory computer accounts for those machines are retained, dis‑
abled, or deleted.
Manage Active Directory computer accounts in a catalog
To manage Active Directory accounts in a machine catalog, you can:
• Free unused machine accounts by removing Active Directory computer accounts from single‑
session OS and multi‑session OS catalogs. Those accounts can then be used for other machines.
• Add accounts so that when more machines are added to the catalog, the computer accounts
are already in place. Do not use a forward slash (/) in an OU name.
To manage Active Directory accounts:
2. Select a catalog and then select Manage AD accounts in the Actions pane.
3. Choose whether to add or delete computer accounts. If you add accounts, specify what to do
with the account passwords: either reset them all or enter a password that applies to all ac‑
counts.
You might reset passwords if you do not know the current account passwords; you must have
permission to perform a password reset. When entering a password, the password is changed
on the accounts as they are imported. When deleting an account, choose whether the account
in Active Directory is kept, disabled, or deleted.
Indicate if Active Directory accounts are retained, disabled, or deleted when you remove machines
from a catalog or delete a catalog.
Update a catalog
Citrix recommends that you save copies or snapshots of master images before updating the machines
in the catalog. The database keeps a historical record of the master images used with each machine

catalog. Roll back, or revert, machines in a catalog to use the previous version of the master image.
Perform this task if users encounter problems with updates you deployed to their desktops. This min‑
imizes user downtime. Do not delete, move, or rename master images. You cannot revert a catalog
to use them.
For catalogs that use Citrix Provisioning (formerly Provisioning Services), you must publish a new vir‑
tual disk to apply changes to the catalog. For details, see the Citrix Provisioning documentation.
After a machine is updated, it restarts automatically.
Update or create a master image
Before you update the machine catalog, either update an existing master image or create a one on
your host hypervisor.
1. On your hypervisor, take a snapshot of the current VM and give the snapshot a meaningful name.
This snapshot can be used to revert (roll back) machines in the catalog, if needed.
2. If necessary, power on the master image, and log on.
3. Install updates or make any required changes to the master image.
4. Power off the VM.
5. Take a snapshot of the VM. Give it a meaningful name that is recognized when the catalog is
updated in Studio. Although Studio can create a snapshot, Citrix recommends that you create
it using the hypervisor management console. Then select that snapshot in Studio. This process
enables you to provide a meaningful name and description rather than an automatically gener‑
ated name. For GPU master images, you can change the master image only through the Citrix
Hypervisor console.
Update the catalog
To prepare and roll out the update to all machines in a catalog:

2. Select a catalog and then select Update Machines in the Actions pane.
3. On the Master Image page, select the host and the image you want to roll out.
4. On the Rollout Strategy page, choose when the machines in the machine catalog are updated
with the new master image: on the next shutdown or immediately.
5. Verify the information on the Summary page and then click Finish. Each machine restarts au‑
tomatically after it is updated.
When updating a catalog using PowerShell SDK directly, rather than Studio, specify a hypervisor tem‑
plate (VMTemplates). Use this as an alternative to an image or a snapshot of an image.
Rollout strategy:

Updating the image on next shutdown will immediately affect any machines not currently in use, that
is, machines that do not have an active user session. A system that is in use receives the update when
the current active session ends. Consider the following:
• New sessions cannot be launched until the update has completed on applicable machines.
• For desktop OS machines, machines are immediately updated when the machine is not in use,
or when users are not logged in.
• For a server OS with child machines, reboots do not occur automatically. They must be manu‑
ally shut down and restarted.
Tip:
Limit the number of machines being rebooted by using the advanced settings for a host connec‑
tion. Use these settings to modify the actions taken for a given catalog; advanced settings vary
depending on the hypervisor.
If you choose to update the image immediately, configure a distribution time and notifications.
• Distribution time: Choose to update all machines at the same time, or specify the total length
of time to begin updating all machines in the catalog. An internal algorithm determines when
each machine is updated and restarted during that interval.
• Notification: In the left notification drop‑down menu, choose whether to display a notifica‑
tion message on the machines before an update begins. By default, no message is displayed.
Choose to display a message 15 minutes before the update begins. Or, choose to repeat the
message every five minutes after the initial message. By default, the message is not repeated.
Unless you choose to update all machines at the same time, the notification message displays
on each machine at the appropriate time before the update begins.
Roll back an update
After you roll out an updated/new master image, you can roll it back. This process might be necessary
if issues occur with the newly updated machines. When you roll back, machines in the catalog are
rolled back to the last working image. Any new features that require the newer image are no longer
available. As with the rollout, rolling back a machine includes a restart.

2. Select the catalog and then select Rollback machine update in the Actions pane.
3. Specify when to apply the earlier master image to machines, as described in the preceding sec‑
tion for the rollout operation.
The rollback is applied only to machines that need to be reverted. Machines that have not been up‑
dated with the new/updated master image do not receive notification messages and are not forced to
log off.

Upgrade a catalog or revert an upgrade
Upgrade the machine catalog after you upgrade the VDAs on the machines to a newer version. Citrix
recommends upgrading all VDAs to the latest version to enable access to all the newest features.
Before upgrading a catalog:
• If you’re using Citrix Provisioning, upgrade the VDA version. The provisioning console does not
retain the VDA version. Citrix Provisioning communicates directly with the Citrix Virtual Apps
and Desktops Setup Wizard to set the VDA version in the created catalog.
• Start the upgraded machines so that they register with the Controller. This process lets Studio
determine that the machines in the catalog need upgrading.
To upgrade a catalog:

2. Select the catalog. The Details tab in the lower pane displays version information.
3. Select Upgrade Catalog. If Studio detects that the catalog needs upgrading, it displays a mes‑
sage. Follow the prompts. If one or more machines cannot be upgraded, a message explains
why. Citrix recommends you resolve machine issues before upgrading the catalog to ensure
that all machines function properly.
After the catalog upgrade completes, you can revert the machines to their previous VDA versions by
selecting the catalog and then selecting Undo in the Actions pane.
Troubleshoot
For machines with “Power State Unknown” status, see CTX131267 for guidance.
Create delivery groups
June 24, 2021
A delivery group is a collection of machines selected from one or more machine catalogs. The delivery
group specifies which users can use those machines, plus the applications and desktops available to
those users.
Creating a delivery group is the next step in configuring your deployment after creating a site and
creating a machine catalog. Later, you can change the initial settings in the first delivery group and
create other delivery groups. There are also features and settings you can configure only when editing
a delivery group, not when creating it.
For Remote PC Access, when you create a site, a delivery group named “Remote PC Access Desktops”
is automatically created.

To create a delivery group:
1. If you have created a site and a machine catalog, without a delivery group, Studio guides you to
the correct starting place to create one. If you have already created a delivery group and want
to create another, select Delivery Groups. Select Create Delivery Group in the Actions pane.
2. The wizard launches with an Introduction page, which you can remove from future launches
of this wizard.
3. The wizard then guides you through the pages described in the following section. When you are
done with each page, click Next until you reach the final page.
Step 1. Machines
On the Machines page, select a catalog and select the number of machines you want to use from that
catalog.
Good to know:
• At least one machine must remain unused in a selected catalog.

• A catalog can be specified in more than one delivery group. A machine can be used in only one
delivery group.
• A delivery group can use machines from more than one catalog; however, those catalogs must
contain the same machine types (multi‑session OS, single‑session OS, or Remote PC Access). In
other words, you cannot mix machine types in a delivery group. Similarly, if your deployment
has catalogs of Windows machines and catalogs of Linux machines, a delivery group can contain
machines from either OS type, but not both.
• Citrix recommends that you install or upgrade all machines with the most recent VDA version.
Upgrade catalogs and delivery groups as needed. When creating a delivery group, if you select
machines that have different VDA versions installed, the delivery group is compatible with the
earliest VDA version. This is called the group’s functional level. For example, if one of the ma‑
chines has VDA version 7.1 and other machines have the current version, all machines in the
group can use only those features that were supported in VDA 7.1. This means that some fea‑
tures that require later VDA versions might not be available in that delivery group.
• Each machine in a Remote PC Access catalog is automatically associated with a delivery group.
When you create a Remote PC Access site, a catalog named “Remote PC Access Machines” and
a delivery group named “Remote PC Access Desktops” are created automatically.
• The following compatibility checks are performed:
– MinimumFunctionalLevel must be compatible
– SessionSupport must be compatible
– AllocationType must be compatible for SingleSession
– ProvisioningType‘ must be compatible
– PersistChanges must be compatible for MCS and Citrix Provisioning

– RemotePC catalog is only compatible with RemotePC catalog

– AppDisk related check
Step 2. Delivery type
This page appears only if you chose a catalog containing static (assigned) single‑session OS machines.
On the Delivery Type page, choose either Applications or Desktops. You cannot enable both.
If you selected machines from a multi‑session OS or single‑session OS random (pooled) catalog, the
delivery type is assumed to be applications and desktops: you can deliver applications, desktops, or
both.
Step 3. Users
Specify the users and user groups who can use the applications and desktops in the delivery group.
Where user lists are specified
Active Directory user lists are specified when you create or edit the following:
• A site’s user access list, which is not configured through Studio. By default, the application enti‑
tlement policy rule includes everyone. See the PowerShell SDK BrokerAppEntitlementPolicyRule
cmdlets for details.
• Application groups (if configured).
• Delivery groups.
• Applications.
The list of users who can access an application through StoreFront is formed by the intersection of
the above user lists. For example, to configure the use of application A to a particular department,
without unduly restricting access to other groups:
• Use the default application entitlement policy rule that includes everyone.
• Configure the delivery group user list to allow all headquarters users to use any of the applica‑
tions specified in the delivery group.
• (If application groups are configured) Configure the application group user list to allow mem‑
bers of the Administration and Finance business unit to access applications A through L.
• Configure application A’s properties to restrict its visibility to only Accounts Receivable staff in
Administration and Finance.
Authenticated and unauthenticated users
There are two types of users: authenticated and unauthenticated (unauthenticated is also called
anonymous). You can configure one or both types in a delivery group.

• Authenticated: To access applications and desktops, the users and group members you specify
by name must present credentials such as smart card or user name and password to StoreFront
or Citrix Workspace app. For delivery groups containing single‑session OS machines, you can
import user data (a list of users) later by editing the delivery group.
• Unauthenticated (anonymous): For delivery groups containing multi‑session OS machines,

you can allow users to access applications and desktops without presenting credentials to
StoreFront or Citrix Workspace app. For example, at kiosks, the application might require
credentials, but the Citrix access portal and tools do not. An Anonymous Users Group is created
when you install the first Delivery Controller.
To grant access to unauthenticated users, each machine in the delivery group must have a VDA
for Windows Server OS (minimum version 7.6) installed. When unauthenticated users are en‑
abled, you must have an unauthenticated StoreFront store.
Unauthenticated user accounts are created on demand when a session is launched, and are
named AnonXYZ, in which XYZ is a unique three‑digit value.
Unauthenticated user sessions have a default idle timeout of 10 minutes, and are logged
off automatically when the client disconnects. Reconnection, roaming between clients, and
Workspace Control are not supported.
The following table describes your choices on the Users page:
Enable the “Give access to

Add/assign users and user unauthenticated users” check
Enable access for groups? box?
Only authenticated users Yes No

Only unauthenticated users No Yes
Both authenticated and Yes Yes
unauthenticated users
Step 4. Applications
Good to know:
• You cannot add applications to Remote PC Access delivery groups.

• By default, new applications you add are placed in a folder named Applications. You can specify
a different folder. For details, see the Manage Applications article.
• You can change the properties for an application when you add it to a delivery group, or later.
For details, see the Manage Applications article.
• If you try to add an application and one with the same name exists in that folder, you are

prompted to rename the application you are adding. If you decline, the application is added
with a suffix that makes it unique within that application folder.
• When you add an application to more than one delivery group, a visibility issue can occur if you
do not have sufficient permission to view the application in all of those delivery groups. In such
cases, either consult an administrator with greater permissions or have your scope extended to
include all the delivery groups to which the application was added.
• If you publish two applications with the same name to the same users, change the Application
name (for user) property in Studio; otherwise, users see duplicate names in Citrix Workspace
app.
Click Add to display the application sources.
• From Start menu: Applications that are discovered on a machine created from the master im‑
age in the selected catalog. When you select this source, a new page launches with a list of
discovered applications; select those you want to add and then click OK.
• Manually defined: Applications located in the site or elsewhere in your network. Selecting this
source launches a new page where you type the path to the executable, working directory, op‑
tional command line arguments, and display names for administrators and users. After entering
this information, click OK.
• Existing: Applications previously added to the site, perhaps in another delivery group. When
you select this source, a new page launches with a list of discovered applications. Add the ap‑
plications and click OK.
• App‑V: Applications in App‑V packages. When you select this source, a new page launches
where you select the App‑V server or the Application Library. Select the applications you want
to add from the resulting display and then click OK. For more information, see App‑V.
If an application source or application is not available or valid, it is either not visible or cannot be
selected. For example, the Existing source is not available if no applications have been added to the
site. Or, an application might not be compatible with the supported session types on machines in the
selected catalog.
Step 5. Desktops
The title of this page depends on the catalog you chose on the Machines page:
• If you chose a catalog containing pooled machines, this page is titled Desktops.
• If you chose a catalog containing assigned machines and specified “Desktops” on the Delivery
Type page, this page is titled Desktop User Assignments.
• If you chose a catalog containing assigned machines and specified “Applications” on the Deliv‑
ery Type page, this page is titled Application Machine User Assignments.
Click Add. In the dialog box:

• In the Display name and Description fields, type the information to be displayed in Citrix
Workspace app.
• To add a tag restriction to a desktop, select Restrict launches to machines with this tag and
then select the tag from the drop‑down list. For more information, see Tags.
• Use the radio buttons to launch a desktop or to assign a machine when launching the desktop.
The users can be either everyone who can access this delivery group, or specific users and user
groups.
• If the group contains assigned machines, specify the maximum number of desktops per user.
This must be a value of one or greater.
• Enable or disable the desktop (for pooled machines) or desktop assignment rule (for assigned
machines). Disabling a desktop stops desktop delivery. Disabling a desktop assignment rule
stops desktop auto‑assignment to users.
• When you are finished with the dialog box, click OK.
Maximum instances of a desktop in a site (PowerShell only)
To configure the maximum instances of a desktop in the site (PowerShell only):
• In PowerShell, use the appropriate BrokerEntitlementPolicyRule cmdlet with the MaxPerEnti‑

tlementInstances parameter. For example, the following cmdlet modifies the tsvda-desktop
rule to set the maximum concurrent instances of a desktop allowed in the site to two. When
there are two desktop instances running, an error occurs if a third subscriber attempts to start
a desktop.
Set-BrokerEntitlementPolicyRule -Name tsvda-desktop -MaxPerEntitlementInstances

2
• For guidance, use the Get‑Help cmdlet. For example, Get-Help Set-BrokerEntitlementPolicyRule
-Parameter MaxPerEntitlementInstances.
Step 6. Summary
Enter a name for the delivery group. You can also (optionally) enter a description, which appears in
the Citrix Workspace app and in Studio.
Review the summary information and then click Finish.
Manage delivery groups
April 14, 2021

Introduction
This article describes procedures for managing delivery groups from the management console. In
addition to changing settings specified when creating the group, you can configure other settings that
are not available when you create a delivery group.
Procedure categories include: general, users, machines, and sessions. Some tasks span more than
one category. For example, “Prevent users from connecting to machines” is described in the machines
category, but it also affects users. If you can’t find a task in one category, check a related category.
Other articles also contain related information:
• Applications contain information about managing applications in delivery groups.

• Managing delivery groups requires the Delivery Group Administrator built‑in role permissions.
For details, see Delegated administration.
General
• Change the delivery type

• Change StoreFront addresses
• Upgrade a delivery group
• Manage Remote PC Access delivery groups
Change the delivery type of a delivery group
The delivery type indicates what the group can deliver: applications, desktops, or both.
Before changing an application only or desktops and applications type to the desktops only type,
delete all applications from the group.
1. Select Delivery Groups in the navigation pane.

2. Select a group and then click Edit Delivery Group in the Actions pane.
3. On the Delivery Type page, select the delivery type you want.
4. Click Apply to apply any changes you made and keep the window open. Or, click OK to apply
changes and close the window.
Change StoreFront addresses

3. On the StoreFront page, select or add StoreFront URLs. These URLs are used by the Citrix
Workspace app, which is installed on each machine in the delivery group.

You can also specify StoreFront server addresses by selecting Configuration > StoreFront in the nav‑
igation pane.
Upgrade a delivery group or revert an upgrade
Upgrade a delivery group after you upgrade the Virtual Delivery Agents (VDAs) on its machines and
the machine catalogs containing the machines used in the delivery group.
Before you start the delivery group upgrade:
• If you use Citrix Provisioning (formerly Provisioning Services), upgrade the VDA version in the
Citrix Provisioning console.
• Start the machines containing the upgraded VDA so that they can register with a Delivery Con‑
troller. This process tells the console about what needs upgrading in the delivery group.
• If you continue to use earlier VDA versions, newer product features are not available. For more
information, see the upgrade documentation.
To upgrade a delivery group:

2. Select a group and then click Upgrade Delivery Group in the Actions pane. The Upgrade De‑
livery Group action appears only if upgraded VDAs are detected.
The display indicates you which, if any, machines cannot be upgraded and why. You can then cancel
the upgrade, resolve the machine issues, and then start the upgrade again.
After the upgrade completes, you can revert the machines to their previous states by selecting the
delivery group and then clicking Undo in the Actions pane.
Manage Remote PC Access delivery groups
If a machine in a Remote PC Access machine catalog is not assigned, the machine is temporarily as‑
signed to a delivery group associated with that catalog. This temporary assignment enables the ma‑
chine to be assigned to a user later.
The delivery group‑to‑machine catalog association has a priority value. Priority determines the ma‑
chine’s assigned delivery group when it registers with the system or when a user needs a machine
assignment. The lower the value, the higher the priority. If a Remote PC Access machine catalog has
multiple delivery group assignments, the software selects the match with the highest priority. Use
the PowerShell SDK to set this priority value.
When first created, Remote PC Access machine catalogs are associated with a delivery group. Machine
accounts or Organizational Units added to the catalog later can be added to the delivery group. This
association can be switched off or on.
To add or remove a Remote PC Access machine catalog association with a delivery group:


2. Select a Remote PC Access group.
3. In the Details section, click the Machine Catalogs tab and then select a Remote PC Access cat‑
alog.
4. To add or restore an association, click Add Desktops. To remove an association, click Remove
Association.
Users
• Change user settings

• Add or remove users
Change user settings in a delivery group
The name of this page appears as either User Settings or Basic Settings.

3. On the User Settings (or Basic Settings) page, change any of the settings in the following table.
Setting Description
Description The text that Citrix Workspace (or StoreFront)

uses and that users see.
Enable delivery group Whether the delivery group is enabled.
Time zone
Enable Secure ICA Secures communications to and from
machines in the delivery group using
SecureICA, which encrypts the ICA protocol.
The default level is 128‑bit. The level can be
changed using the SDK. Citrix recommends
using more encryption methods such as TLS
encryption when traversing public networks.
Also, SecureICA does not check data integrity.

Add or remove users in a delivery group
For detailed information about users, see Users.
3. On the Users page:
• To add users, click Add, and then specify the users you want to add.
• To remove users, select one or more users and then click Remove.
• Select or clear the check box to allow access by unauthenticated users.
Import or export user lists
For delivery groups containing physical single‑session OS machines, you can import user information
from a .csv file after you create the delivery group. You can also export user information to a .csv file.
The .csv file can contain data from a previous product version.
The first line in the .csv file must contain comma‑separated column headings (in any order), which can
include: ADComputerAccount, AssignedUser, VirtualMachine, and HostId. Subsequent lines
in the file contain comma‑separated data. The ADComputerAccount entries can be common names,
IP addresses, distinguished names, or domain and computer name pairs.
To import or export user information:

3. On the Machine Allocation page, select Import list or Export list, and then browse to the file
location.
Machines
• Change assignments of machines to users

• Change the maximum number of machines per user
• Update a machine
• Add, change, or remove a tag restriction for a desktop
• Remove a machine
• Restrict access to machines
• Prevent users from connecting to a machine (maintenance mode)

• Shut down and restart machines

• Create and manage restart schedules for machines
• Load managed machines
• Power managed machines
Change assignments of machines to users in a delivery group
You can change the assignments of single‑session OS machines provisioned with MCS. You cannot
change assignments for multi‑session OS machines or machines provisioned with Citrix Provisioning.

3. On the Desktops or Desktop Assignment Rules page (the page title depends on the type of
machine catalog the delivery group uses), specify the new users.
Change the maximum number of machines per user in a delivery group

3. On the Desktop Assignment Rules page, set the maximum desktops per user value.
Update a machine in a delivery group

2. Select a group and then click View Machines in the Actions pane.
3. Select a machine and then click Update Machines in the Actions pane.
To choose a different master image, select Master image and then select a snapshot.
To apply changes and notify machine users, select Rollout notification to end‑users. Then specify:
• When to update the master image: now or on the next restart

• The restart distribution time (the total time to begin updating all machines in the group)
• Whether users are notified of the restart
• The message users receive

Add, change, or remove a tag restriction for a desktop
Adding, changing, and removing tag restrictions can have unanticipated effects on which desktops
are considered for launch. Review the considerations and cautions in Tags.
3. On the Desktops page, select the desktop and click Edit.
4. To add a tag restriction, select Restrict launches to machines with the tag and then select the
tag.
5. To change or remove a tag restriction, either:
• Select a different tag.

• Remove the tag restriction by clearing Restrict launches to machines with this tag.
Remove a machine from a delivery group
Removing a machine deletes it from a delivery group. It does not delete it from the machine catalog
that the delivery group uses. Therefore, that machine is available for assignment to another delivery
group.
Machines must be shut down before they can be removed. To temporarily stop users from connecting
to a machine while you are removing it, put the machine into maintenance mode before shutting it
down.
Machines might contain personal data, so use caution before allocating the machine to another user.
Consider reimaging the machine.

3. Ensure that the machine is shut down.
4. Select the machine and then click Remove from Delivery Group in the Actions pane.
You can also remove a machine from a delivery group through the connection the machine uses.
Restrict access to machines in a delivery group
Any changes you make to restrict access to machines in a delivery group supersede previous settings,
regardless of the method you use. You can:

• Restrict access for administrators using delegated administration scopes: Create and as‑
sign a scope that permits administrators to access all applications, and another scope that pro‑
vides access to only certain applications. For details, see Delegated administration.
• Restrict access for users through SmartAccess policy expressions: Use policy expressions
to filter user connections made through Citrix Gateway.

3. On the Access Policy page, select Connections through NetScaler Gateway.
4. To choose a subset of those connections, select Connections meeting any of the follow‑
ing filters. Then define the Citrix Gateway site, and add, edit, or remove the SmartAccess
policy expressions for the allowed user access scenarios. For details, see the Citrix Gate‑
way documentation.
5. Click Apply to apply any changes you made and keep the window open. Or, click OK to
apply changes and close the window.
• Restrict access for users through exclusion filters: Use exclusion filters on access policies
that you set in the SDK. Access policies are applied to delivery groups to refine connections. For
example, you can restrict machine access to a subset of users, and you can specify allowed user
devices. Exclusion filters further refine access policies. For example, for security, you can deny
access to a subset of users or devices. By default, exclusion filters are disabled.
For example, a teaching lab on a corporate network subnet which prevents access from
that lab to a particular delivery group. Regardless of who is using the machines in the
lab, use the command: Set-BrokerAccessPolicy -Name VPDesktops_Direct -
ExcludedClientIPFilterEnabled $True -.
Use the asterisk (*) wildcard to match all tags that start with the same policy expression. For
example, if you add the tag VPDesktops_Direct to one machine and VPDesktops_Test to
another, setting the tag in the Set-BrokerAccessPolicy script to VPDesktops_* applies the
filter to both machines.
If you are connected using a web browser or with the Citrix Workspace app user experience
feature enabled in the store, you cannot use a client name exclusion filter.
Prevent users from connecting to a machine (maintenance mode) in a delivery group
When you need to temporarily stop new connections to machines, you can turn on maintenance mode
for one or all machines in a delivery group. You might do this before applying patches or using man‑
agement tools.
• When a multi‑session OS machine is in maintenance mode, users can connect to existing ses‑
sions, but cannot start new sessions.

• When a single‑session OS machine (or a PC using Remote PC Access) is in maintenance mode,

users cannot connect or reconnect. Current connections remain connected until they discon‑
nect or log off.
To turn maintenance mode on or off:
2. Select a group.
3. To turn on maintenance mode for all machines in the delivery group, click Turn On Mainte‑
nance Mode in the Actions pane.
To turn on maintenance mode for one machine, click View Machines in the Actions pane. Select
a machine, and then click Turn On Maintenance Mode in the Actions pane.
4. To turn maintenance mode off for one or all machines in a delivery group, follow the previous
instructions, but click Turn Off Maintenance Mode in the Actions pane.
Windows Remote Desktop Connection (RDC) settings also affect whether a multi‑session OS machine
is in maintenance mode. Maintenance mode is on when any of the following occur:
• Maintenance mode is set to on, as described earlier.

• RDC is set to Don’t allow connections to this computer.
• RDC is not set to Don’t allow connections to this computer. The Remote Host Configuration
User Logon Mode setting is either Allow reconnections, but prevent new logons or Allow
reconnections, but prevent new logons until the server is restarted.
You can also turn maintenance mode on or off for:
• A connection, which affects the machines using that connection.

• A machine catalog, which affects the machines in that catalog.
Shut down and restart machines in a delivery group
This procedure is not supported for Remote PC Access machines.
3. Select the machine and then click one of the following entries in the Actions pane:
• Force shut down: Forcibly powers off the machine and refreshes the list of machines.
• Restart: Requests the operating system to shut down and then start the machine again.
If the operating system cannot comply, the machine remains in its current state.
• Force restart: Forcibly shuts down the operating system and then restarts the machine.
• Suspend: Pauses the machine without shutting it down, and refreshes the list of
machines.

• Shut down: Requests the operating system to shut down.
For non‑force actions, if the machine does not shut down within 10 minutes, it is powered off. If Win‑
dows attempts to install updates during the shutdown, there is a risk that the machine is powered off
before the updates finish.
Citrix recommends that you prevent single‑session OS machine users from selecting Shut down
within a session. See the Microsoft policy documentation for details.
You can also shut down and restart machines on a connection.
Create and manage restart schedules for machines in a delivery group
A restart schedule specifies when machines in a delivery group are periodically restarted. You can
create one or more schedules for a delivery group. A schedule can affect either:
• All of the machines in the group.

• One or more (but not all) machines in the group. The machines are identified by a tag that you
apply to the machine. This is called a tag restriction, because the tag restricts an action to only
items that have the tag.
For example, let’s say all of your machines are in one delivery group. You want every machine
restarted once every week, and you want the machines used by the accounting team restarted daily.
To accomplish this, set up one schedule for all machines, and another schedule for only the machines
in accounting.
A schedule includes the day and time the restart begins, and the duration. The duration is either “start
all affected machines at the same time” or an interval it takes to restart all affected machines.
You can enable or disable a schedule. Disabling a schedule can be helpful when testing, during special
intervals, or when preparing schedules before you need them.
You cannot use schedules for automated power‑on or shutdown from the management console, only
to restart.
Schedule overlap
Multiple schedules can overlap. In the example above, both schedules affect the accounting ma‑
chines. Those machines might be restarted twice on Sunday. The scheduling code is designed to
avoid restarting the same machine more often than intended, but it cannot be guaranteed.
• If the schedules coincide precisely in start and duration times, it is more likely that the machines
are restarted only once.
• The more the schedules differ in start and duration times, it’s more likely that multiple restarts
occur.

• The number of machines affected by a schedule also affects the chance of an overlap. In the
example, the weekly schedule that affects all machines might initiate restarts faster than the
daily schedule for accounting machines, depending on the duration specified for each.
For an in‑depth look at restart schedules, see Reboot schedule internals.
View restart schedules

3. Select the Restart Schedule page.
The Restart Schedule page contains the following information for each configured schedule:
• Schedule name.
• Tag restriction used, if any.
• How often the machine restarts occur.
• Whether machine users receive a notification.
• Whether the schedule is enabled. Disabling a schedule can be helpful when testing, during spe‑
cial intervals, or when preparing schedules before you need them.
Add (apply) tags
When you configure a restart schedule that uses a tag restriction, ensure that the tag has been added
to the machines that the schedule affects. In the example above, each of the machines used by the
accounting team has a tag applied. For details, see Tags.
Although you can apply more than one tag to a machine, a restart schedule can specify only one tag.

2. Select the group containing the machines controlled by the schedule.
3. Click View Machines and then select the machines you want to add a tag to.
4. Click Manage Tags in the Actions pane.
5. If the tag exists, enable the check box next to the tag name. If the tag does not exist, click Create
and then specify the name for the tag. After the tag is created, enable the check box next to the
newly created tag name.
6. Click Save in the Manage Tags dialog.
Create a restart schedule
3. On the Restart Schedule page, click Add.

4. On the Add Restart Schedule page:
• Type a schedule name and description.
• If you’re using a tag restriction, select the tag.
• In Restart frequency, select how often the restart occurs: daily, weekdays, weekend days,
or a specific day each week.
• Using the 24‑hour clock, specify the time of day to begin the restart.
• For Restart duration, choose whether all machines are restarted at the same time, or the
total length of time to begin restarting all of the affected machines. An internal algorithm
determines when each machine is restarted during that interval.
• In Send notification to users, choose whether to display a notification message on the

affected machines before a restart begins. By default, no message is displayed.
• If you choose to display a message 15 minutes before the restart begins, you can choose (in
Notification frequency) to repeat the message every five minutes after the initial message.
By default, the message is not repeated.
• Enter the notification title and text. There is no default text.
If you want the message to include the number of minutes before restart, include the vari‑
able %m%. For example: “Warning: Your computer is automatically restarted in %m%
minutes.” The value decrements by five minutes in each repeated message. Unless you
chose to restart all machines at the same time, the message displays on each machine at
the appropriate time before the restart, calculated by the internal algorithm.
• To enable the schedule, select the check box. To disable the schedule, clear the check box.
5. Click Apply to apply the changes you made and keep the window open. Or, click OK to apply
Edit, remove, enable, or disable a restart schedule

3. On the Restart Schedule page, select the check box for a schedule.
• To edit a schedule, click Edit. Update the schedule configuration, using the guidance in
Create a restart schedule.
• To enable or disable a schedule, click Edit. Select or clear the Enable restart schedule
check box.
• To remove a schedule, click Remove. Confirm the removal. Removing a schedule does
not affect any tags applied to machines in the affected machines.

Scheduled restarts delayed due to database outage
Note:
This feature is available only through PowerShell.
If a site database outage occurs before a scheduled restart begins for machines (VDAs) in a delivery
group, the restarts begin when the outage ends. This can have unintended results.
For example, let’s say you’ve scheduled a delivery group’s restarts to occur during off‑production
hours (beginning at 03:00). A site database outage occurs one hour before a scheduled restart begins
(02:00). The outage lasts six hours (until 08:00). The restart schedule begins when the connection be‑
tween the Delivery Controller and the site database is restored. The VDA restarts now begin five hours
after their original schedule, resulting in VDAs restarting during production hours.
To help avoid this situation, you can use the MaxOvertimeStartMins parameter for the New-
BrokerRebootScheduleV2 and Set-BrokerRebootScheduleV2 cmdlets. The value specifies
the maximum number of minutes beyond the scheduled start time that a restart schedule can begin.
If the database connection is restored within that time (scheduled time + MaxOvertimeStartMins),
the VDA restarts begin.
If the database connection is not restored within that time, the VDA restarts do not begin.
If this parameter is omitted, the scheduled restart begins when the connection to the database is re‑
stored, regardless of the outage duration.
For more information, see the cmdlet help. This feature is available only in PowerShell. You cannot
set this value when configuring a restart schedule in Studio.
Scheduled restarts for machines in maintenance mode

Note:
This feature is available only in PowerShell.
To indicate whether a restart schedule affects machines that are in maintenance mode, use the
IgnoreMaintenanceMode option with BrokerRebootScheduleV2 cmdlets.
For example, the following cmdlet creates a schedule that restarts machines that are in maintenance
mode (in addition to machines that aren’t in maintenance mode).
New-Brokerrebootschedulev2 rebootSchedule1 -DesktopGroupName <myDesktopGroup

> -IgnoreMaintenanceMode $true
The following cmdlet modifies an existing restart schedule.
Set-Brokerrebootschedulev2 rebootSchedule1 -IgnoreMaintenanceMode $true
For more information, see the cmdlet help. This feature is available only in PowerShell.

Load managed machines in delivery groups
You can load manage multi‑session OS machines only.
Load management measures the server load and determines which server to select under the current
environment conditions. This selection is based on:
• Server maintenance mode status: A multi‑session OS machine is considered for load balanc‑
ing only when maintenance mode is off.
• Server load index: Determines how likely a server delivering multi‑session OS machines is to
receive connections. The index is a combination of load evaluators: the number of sessions and
the settings for performance metrics such as CPU, disk, and memory use. Load evaluators are
specified in load management policy settings.
A server load index of 10000 indicates that the server is fully loaded. If no other servers are
available, users might receive a message that the desktop or application is unavailable when
they launch a session.
You can monitor the load index in Director (Monitor), Studio (Manage) search, and the SDK.
In console displays, to display the Server Load Index column (which is hidden by default), se‑
lect a machine, right‑click a column heading, and then select Select Column. In the Machine
category, select Load Index.
In the SDK, use the Get-BrokerMachine cmdlet. For details, see CTX202150.
• Concurrent logon tolerance policy setting: The maximum number of concurrent requests to
log on to the server. (This setting is equivalent to load throttling in XenApp 6.x versions.)
When all servers are at or higher than the concurrent logon tolerance setting, the next logon
request is assigned to the server with the lowest pending logons. If more than one server meets
these criteria, the server with the lowest load index is selected.
Power managed machines in a delivery group
You can power manage only virtual single‑session OS machines, not physical machines (including Re‑
mote PC Access machines). Single‑session OS machines with GPU capabilities cannot be suspended,
so power‑off operations fail. For multi‑session OS machines, you can create a restart schedule.
In delivery groups containing pooled machines, virtual single‑session OS machines can be in one of
the following states:
• Randomly allocated and in use

• Unallocated and unconnected
In delivery groups containing static machines, virtual single‑session OS machines can be:
• Permanently allocated and in use

• Permanently allocated and unconnected (but ready)

• Unallocated and unconnected
During normal use, static delivery groups typically contain both permanently allocated and unallo‑
cated machines. Initially, all machines are unallocated, except for manually allocated ones when the
delivery group was created. As users connect, machines become permanently allocated. You can
fully power manage the unallocated machines in those delivery groups, but only partially manage
the permanently allocated machines.
• Pools and buffers: For pooled delivery groups and static delivery groups with unallocated ma‑
chines, a pool (in this instance) is a set of unallocated or temporarily allocated machines that
are kept in a powered‑on state, ready for users to connect. A user gets a machine immediately
after logon. The pool size (the number of machines kept powered‑on) is configurable by time
of day. For static delivery groups, use the SDK to configure the pool.
A buffer is an extra standby set of unallocated machines that are turned on when the number
of machines in the pool falls below a threshold. The threshold is a percentage of the delivery
group size. For large delivery groups, a significant number of machines might be turned on
when the threshold is exceeded. So, plan delivery group sizes carefully or use the SDK to adjust
the default buffer size.
• Power state timers: You can use power state timers to suspend machines after users have dis‑
connected for a specified amount of time. For example, machines suspend automatically out‑
side of office hours if users are disconnected for at least 10 minutes.
You can configure timers for weekdays and weekends, and for peak and nonpeak intervals.
• Partial power management of permanently allocated machines: For permanently allocated

machines, you can set power state timers, but not pools or buffers. The machines are turned on
at the start of each peak period, and turned off at the start of each off‑peak period. You do not
have the fine control that you have with unallocated machines over the number of machines
that become available to compensate for machines that are consumed.
Power manage virtual single‑session OS machines

3. On the Power Management page, select Weekdays in Power manage machines. By default,
weekdays are Monday to Friday.
4. For random Delivery groups, in Machines to be powered on, click Edit and then specify the
pool size during weekdays. Then, select the number of machines to power on.
5. In Peak hours, set the peak and off‑peak hours for each day.
6. Set the power state timers for peak and non‑peak hours during weekdays: In During peak hours
> When disconnected, specify the delay (in minutes) before suspending any disconnected ma‑

chine in the delivery group, and then select Suspend. In During off‑peak hours > When discon‑
nected, specify the delay before turning off any logged‑off machine in the delivery group, and
then select Shutdown. This timer is not available for delivery groups with random machines.
7. Select Weekend in Power manage machines, and then configure the peak hours and power
state timers for weekends.
Use the SDK to:
• Shut down, rather than suspend, machines in response to power state timers, or if you want the
timers to be based on logoffs, rather than disconnections.
• Change the default weekday and weekend definitions.
• Disable power management. See CTX217289.
Power manage VDI machines transitioning to a different time period with disconnected sessions
Important:
This enhancement applies only to VDI machines with disconnected sessions. It does not apply
to VDI machines with logged off sessions.
In earlier releases, a VDI machine transitioning to a time period where an action (disconnect ac‑
tion=“Suspend” or “Shutdown”) was required remained powered on. This scenario occurred if the
machine disconnected during a time period (peak or off‑peak times) where no action (disconnect
action=“Nothing”) was required.
Starting with Citrix Virtual Apps and Desktops 7 1909, the machine is suspended or powered off when
the specified disconnection time elapses, depending on the disconnect action configured for the des‑
tination time period.
For example, you configure the following power policies for a VDI delivery group:
• Set PeakDisconnectAction to “Nothing”
• Set OffPeakDisconnectAction to “Shutdown”
• Set OffPeakDisconnectTimeout to “10”
Note:
For more information about the disconnect action power policy, see https://developer‑docs.
citrix.com/projects/delivery‑controller‑sdk/en/latest/Broker/about_Broker_PowerManagement/
#power‑policy and https://developer‑docs.citrix.com/projects/delivery‑controller‑sdk/en/
latest/Broker/Get‑BrokerDesktopGroup/.
In earlier releases, a VDI machine with a session disconnected during peak times remained powered
on when it transitioned from peak to off‑peak. Starting with Citrix Virtual Apps and Desktops 7 1909,

the OffPeakDisconnectAction and the OffPeakDisconnectTimeout policy actions are applied

to the VDI machine on period transition. As a result, the machine is powered off 10 minutes after it
transitions to off‑peak.
If you want to revert to the previous behavior (that is, take no action on machines that transition from
peak to off‑peak or off‑peak to peak with disconnected sessions), do one of the following:
• Set the “LegacyPeakTransitionDisconnectedBehaviour” registry value to 1, the equivalent of

true which enables the previous behavior. By default, the value is 0, or false, which triggers
disconnect power policy actions on period transition.
– Path: HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\DesktopServer
– Name: LegacyPeakTransitionDisconnectedBehaviour
– Type: REG_DWORD
– Data: 0x00000001 (1)
• Configure the setting by using the Set-BrokerServiceConfigurationData PowerShell
command. For example:
– PS C:\> Set-BrokerServiceConfigurationData HostingManagement.
LegacyPeakTransitionDisconnectedBehaviour -SettingValue $true
A machine must meet the following criteria before power policy actions can be applied to it on period
transition:
• Has a disconnected session.

• Has no pending power actions.
• Belongs to a VDI (single session) delivery group that transitions to a different time period.
• Has a session that disconnects during a certain time period (peak or off‑peak times) and transi‑
tions to a period where a power action is assigned.
Change the percentage of VDAs in a powered state for catalogs
1. Adjust the peak hours for the delivery group from the Power management section for the de‑
livery group.
2. Make a note of the Desktop Group name.
3. With administrator privileges, start PowerShell and run the following commands. Replace
“Desktop Group Name” with the name of your desktop group that has a changed percentage
of the VDAs running.
asnp Citrix*
## Set-BrokerDesktopGroup "Desktop Group Name"-PeakBufferSizePercent

100
A value of 100 means that 100% of the VDAs are in the ready state.

4. Verify the solution by running:
##Get-BrokerDesktopGroup "Desktop Group Name"
It can take up to an hour for changes to take effect.
To shut down the VDAs after the user logs off, enter:
## Set-BrokerDesktopGroup "Desktop Group Name"-ShutDownDesktopsAfterUse

$True
To restart VDAs during peak hours, so that they’re ready for users after they log off, enter:
## Set-BrokerDesktopGroup "Desktop Group Name"-AutomaticPowerOnForAssignedDuringPeak

$True
Sessions
• Log off or disconnect a session, or send a message to users

• Configure session prelaunch and session linger

Log off or disconnect a session
1. In the Studio navigation pane, select Delivery Groups.

2. Select a delivery group and then select View Machines in the Actions pane.
3. In the middle pane, select the machine, select View Sessions in the Actions pane, and then
select a session.
• Alternatively, in the middle pane, select the Session tab and then select a session.
4. To log off from a session, select Log off in the Actions pane. The session closes and the user
is logged out. The machine becomes available to other users unless it is allocated to a specific
user.
5. To disconnect a session, select Disconnect in the Actions pane. Applications continue to run
in the session and the machine remains allocated to that user. The user can reconnect to the
same machine.
You can configure power state timers for single‑session OS machines to automatically handle unused
sessions. For details, see Power managed machines.
Send a message to a delivery group
1. In the Studio navigation pane, select Delivery Groups.

2. Select a delivery group and then select View Machines in the Actions pane.
3. In the middle pane, select a machine to which you want to send a message.
4. In the Actions pane, select View Sessions.
5. In the middle pane, select all sessions and then select Send Message in the Actions pane.
6. Type your message and click OK. You can specify the level of severity if needed. Options include
Critical, Question, Warning, and Information.
Alternatively, you can send a message by using Citrix Director. For more information, see Send mes‑
sages to users.
Configure session prelaunch and session linger in a delivery group
These features are supported only on multi‑session OS machines.

The session prelaunch and session linger features help specified users access applications quickly,
by starting sessions before they are requested (session prelaunch) and keeping application sessions
active after a user closes all applications (session linger).
By default, session prelaunch and session linger are not used. A session starts (launches) when a user
starts an application, and remains active until the last open application in the session closes.
Considerations:
• The delivery group must support applications, and the machines must be running a VDA for
multi‑session OS, minimum version 7.6.

• These features are supported only when using Citrix Workspace app for Windows, and also re‑
quire extra Citrix Workspace app configuration. For instructions, search for session prelaunch
in the product documentation for your Citrix Workspace app for Windows version.
• Citrix Workspace app for HTML5 is not supported.
• When using session prelaunch, if a user’s machine is put into suspend or hibernate mode,
prelaunch does not work (regardless of session prelaunch settings). Users can lock their
machines/sessions. However, if a user logs off from Citrix Workspace app, the session is ended
and prelaunch no longer applies.
• When using session prelaunch, physical client machines cannot use the suspend or hibernate
power management functions. Client machine users can lock their sessions but should not log
off.
• Prelaunched and lingering sessions consume a concurrent license, but only when connected.
If using a user/device license, the license lasts 90 days. Unused prelaunched and lingering ses‑
sions disconnect after 15 minutes by default. This value can be configured in PowerShell (New/
Set-BrokerSessionPreLaunch cmdlet).
• Careful planning and monitoring of your users’ activity patterns are essential to tailoring these
features to complement each other. Optimal configuration balances the benefits of earlier appli‑
cation availability for users against the cost of keeping licenses in use and resources allocated.
• You can also configure session prelaunch for a scheduled time of day in Citrix Workspace app.
How long unused prelaunched and lingering sessions remain active

There are several ways to specify how long an unused session remains active if the user does not start
an application: a configured timeout and server load thresholds. You can configure all of them. The
event that occurs first causes the unused session to end.
• Timeout: A configured timeout specifies the number of minutes, hours, or days an unused
prelaunched or lingering session remains active. If you configure too short a timeout,
prelaunched sessions end before they provide the user benefit of quicker application access.
If you configure too long a timeout, incoming user connections might be denied because the
server doesn’t have enough resources.
You can enable this timeout from the SDK only (New/Set-BrokerSessionPreLaunch
cmdlet), not from the management console. If you disable the timeout, it does not appear in
the console display for that delivery group or in the Edit Delivery Group pages.
• Thresholds: Automatically ending prelaunched and lingering sessions based on server load en‑
sures that sessions remain open as long as possible, assuming that server resources are avail‑
able. Unused prelaunched and lingering sessions do not cause denied connections because
they are ended automatically when resources are needed for new user sessions.
You can configure two thresholds: the average percentage load of all servers in the delivery
group, and the maximum percentage load of a single server in the group. When a threshold is

exceeded, the sessions that have been in the prelaunch or lingering state for the longest time
are ended. Sessions are ended one‑by‑one at minute intervals until the load falls below the
threshold. While the threshold is exceeded, no new prelaunch sessions are started.
Servers with VDAs that have not registered with a Controller and servers in maintenance mode are
considered fully loaded. An unplanned outage causes prelaunch and lingering sessions to end auto‑
matically to free capacity.
To enable session prelaunch
3. On the Application Prelaunch page, enable session prelaunch by choosing when sessions
launch:
• When a user starts an application. This is the default setting. Session prelaunch is dis‑
abled.
• When any user in the delivery group logs on to Citrix Workspace app for Windows.
• When anyone in a list of users and user groups logs on to Citrix Workspace app for Win‑
dows. Be sure to also specify users or user groups if you choose this option.

4. A prelaunched session is replaced with a regular session when the user starts an application.
If the user does not start an application (the prelaunched session is unused), the following set‑
tings affect how long that session remains active.
• When a specified time interval elapses. You can change the time interval (1–99 days, 1–
2376 hours, or 1–142,560 minutes).
• When the average load on all machines in the delivery group exceeds a specified percent‑
age (1–99%).
• When the load on any machine in the delivery group exceeds a specified percentage (1–
99%).
Recap: A prelaunched session remains active until one of the following events occurs: a user
starts an application, the specified time elapses, or a specified load threshold is exceeded.
To enable session linger
3. On the Application Lingering page, enable session linger by selecting Keep sessions active
until.

4. Several settings affect how long a lingering session remains active if the user does not start an‑
other application.
• When a specified time interval elapses. You can change the time interval: 1–99 days, 1–
2376 hours, or 1–142,560 minutes.
• When the average load on all machines in the delivery group exceeds a specified percent‑
age: 1–99%.
• When the load on any machine in the delivery group exceeds a specified percentage: 1–
99%.
Recap: A lingering session remains active until one of the following events occurs: a user starts
an application, the specified time elapses, or a specified load threshold is exceeded.
Troubleshoot
• VDAs that are not registered with a Delivery Controller are not considered when launching bro‑
kered sessions. This results in underutilization of otherwise available resources. There are var‑
ious reasons a VDA might not be registered, many of which an administrator can troubleshoot.
The details display provides troubleshooting information in the catalog creation wizard, and
after you add a catalog to a delivery group.
After you create a delivery group, the details pane for a delivery group indicates the number of
machines that can be registered but are not. For example, one or more machines are powered
on and not in maintenance mode, but are not currently registered with a Controller. When view‑
ing a “not registered, but should be” machine, review the Troubleshoot tab in the details pane
for possible causes and recommended corrective actions.
For messages about functional level, see VDA versions and functional levels.
For information about VDA registration troubleshooting, seeCTX136668.
• In the display for a delivery group, the Installed VDA version in the details pane might differ
from the actual version installed on the machines. The machine’s Windows Programs and Fea‑
tures display shows the actual VDA version.
• For machines with Power State Unknown status, see CTX131267 for guidance.
Create application groups
April 14, 2021

Introduction
Application groups let you manage collections of applications. Create application groups for appli‑
cations shared across different delivery groups. Or, applications used by a subset of users within
delivery groups. Application groups are optional; they offer an alternative to adding the same appli‑
cations to multiple delivery groups. Associate delivery groups with more than one application group,
and associate an application group with more than one delivery group.
Using application groups can provide application management and resource control advantages over
using more delivery groups:
• The logical grouping of applications and their settings lets you manage those applications as
a single unit. For example, you don’t have to add (publish) the same application to individual
delivery groups one at a time.
• Session sharing between application groups can conserve resource consumption. In other
cases, disabling session sharing between application groups can be beneficial.
• You can use the tag restriction feature to publish applications from an application group, con‑
sidering only a subset of the machines in selected delivery groups. With tag restrictions, you
can use your existing machines for more than one publishing task, saving the costs associated
with deploying and managing extra machines. A tag restriction can be thought of as subdivid‑
ing (or partitioning) the machines in a delivery group. Using an application group or desktops
with a tag restriction can be helpful when isolating and troubleshooting a subset of machines
in a delivery group.
Example configurations
Example 1:
The following graphic shows a Citrix Virtual Apps and Desktops deployment that includes application
groups:

In this configuration, applications are added to the application groups, not the delivery groups. The
delivery groups specify which machines are used. (Although not shown, the machines are in machine
catalogs.)
Application group 1 is associated with delivery group 1. Access the applications in application group
1 by the users specified in application group 1. These groups only appear as long as they are also in
the user list for delivery group 1. This configuration follows the guidance that the user list for an appli‑
cation group is a subset (a restriction) of the user lists for the associated delivery groups. The settings
in application group 1 (such as application session sharing between application groups, associated
delivery groups) apply to applications and users in that group. The settings in delivery group 1 apply
to users in application groups 1 and 2, because those application groups have been associated with
that delivery group.
Application group 2 is associated with two delivery groups: 1 and 2. Each of those delivery groups is as‑
signed a priority in application group 2, indicating the order in which the delivery groups are checked
when an application is launched. Delivery groups with equal priority are load balanced. Access the
applications in application group 2 by the users specified in application group 2. However, they must
also appear in the user lists for delivery group 1 and delivery group 2.
Example 2:
This simple layout uses tag restrictions to limit which machines are considered for certain desktop

and application launches. The site has one shared delivery group, one published desktop, and one
application group configured with two applications.
Tags have been added to each of the three machines (VDA 101–103).
The application group was created with the “Orange” tag restriction. Each of its applications is
launched only on machines in that delivery group that have the tag “Orange,” VDA 102 and 103.
For more comprehensive examples and guidance for using tag restrictions in application groups (and
for desktops), see Tags.
Guidance and considerations
Citrix recommends adding applications to either application groups or delivery groups, but not both.
Otherwise, the additional complexity of having applications in two group types can make it more
difficult to manage.
By default, an application group is enabled. After you create an application group, you can edit the
group to change this setting. See Manage application groups.
By default, application session sharing between application groups is enabled. See Session sharing
between application groups.
Citrix recommends upgrading your delivery groups to the current version. This process requires:
1. Upgrading VDAs on the machines used in the delivery group.

2. Upgrading the machine catalogs containing those machines.
3. Upgrading the delivery group.
For details, see Manage delivery groups.
To use application groups, your core components must be minimum version 7.9.
Creating application groups requires the delegated administration permission of the Delivery Group
Administrator built‑in role. See Delegated administration for details.

This article refers to “associating” an application with more than one application group. It differenti‑
ates that action from adding instances of that application from an available source. Similarly, delivery
groups are associated with application groups, rather than being additions or components of one an‑
other.
Session sharing with application groups
When application session sharing is enabled, all applications launch in the same application session.
This saves the costs associated with launching more application sessions, and allows the use of ap‑
plication features that involve the clipboard, such as copy‑paste operations. However, in some situa‑
tions you can clear session sharing.
When you use application groups you can configure application session sharing in the following three
ways which extend the standard session sharing behavior available when you are using only delivery
groups:
• Session sharing enabled between application groups.

• Session sharing enabled only between applications in the same application group.
• Session sharing disabled.
Session sharing between application groups
You can enable application session sharing between application groups, or you can disable it to limit
application session sharing only to applications in the same application group.
• An example when enabling session sharing between application groups is helpful:
Application group 1 contains Microsoft Office applications such as Word and Excel. Applica‑
tion group 2 contains other applications such as Notepad and Calculator, and both application
groups are attached to the same delivery group. A user who has access to both application
groups starts an application session by launching Word, and then launches Notepad. If the
controller finds that the user’s existing session running Word is suitable for running Notepad
then Notepad is started within the existing session. If Notepad cannot be run from the exist‑
ing session—for example if the tag restriction excludes the machine that the session is running
on—then a new session on a suitable machine is created rather than using session sharing.
• An example when disabling session sharing between application groups is helpful:
A configuration with a set of applications that do not interoperate well with other applications
that are installed on the same machines. Such as two different versions of the same software
suite or two different versions of the same web browser. You prefer not to allow a user to launch
both versions in the same session.

Create an application group for each version of the software suite, and add the applications for
each version of the software suite to the corresponding application group. If session sharing be‑
tween groups is disabled for each of those application groups, a user specified in those groups
can run applications of the same version in the same session. The user can still run other ap‑
plications at the same time, but not in the same session. When launching one of the different‑
versioned applications, or any application that is not contained in an application group, that
application is launched in a new session.
This session sharing between application groups feature is not a security sandboxing feature. It is not
foolproof, and it cannot prevent users from launching applications into their sessions through other
means (for example, through Windows Explorer).
If a machine is at capacity, new sessions are not started on it. New applications are started in existing
sessions on the machine as needed using session sharing.
You can only make prelaunched sessions available to application groups which have application ses‑
sion sharing allowed. (Sessions which use the session linger feature are available to all application
groups.) These features must be enabled and configured in each of the delivery groups associated
with the application group. You cannot configure them in the application groups.
By default, application session sharing between application groups is enabled when you create an
application group. You cannot change this when you create the group. After you create an application
group, you can edit the group to change this setting. See Manage application groups.
Disable session sharing within an application group
You can prevent application session sharing between applications which are in the same application
group.
• An example when disabling session sharing within application groups is helpful:
You want your users to access multiple simultaneous full screen sessions of an application on
separate monitors.
You create an application group and add the applications to it.
By default, application session sharing is enabled when you create an application group. You cannot
change this setting when you create the group. After you create an application group, you can edit the
group to change this setting. See Manage application groups.
Create an application group
To create an application group:
1. Select Applications in the Studio navigation pane, and then select Create Application Group
in the Actions pane.

2. The wizard launches with an Introduction page, which you can remove from future launches
of this wizard.
3. The wizard guides you through the pages described in the following section. When you are done
with each page, click Next until you reach the Summary page.
Step 1. Delivery Groups
The Delivery Groups page lists all delivery groups, with the number of machines each group contains.
• The Compatible Delivery Groups list contains delivery groups you can select. Compatible de‑
livery groups contain random (not permanently or statically assigned) multi‑session or single‑
session OS machines.
• The Incompatible Delivery Groups list contains delivery groups you cannot select. Each entry
explains why it is not compatible, such as containing statically assigned machines.
An application group can be associated with delivery groups containing shared (not private) machines
that can deliver applications.
You can also select delivery groups containing shared machines that deliver only desktops, if both of
the following conditions are met:
• The delivery group contains shared machines and was created with a XenDesktop version earlier
than 7.9.
• You have Edit Delivery Group permission.
The delivery group type is automatically converted to “desktops and applications” when the applica‑
tion group creation wizard is committed.
Although you can create an application group that has no associated delivery groups (perhaps to or‑
ganize applications or to serve as storage for applications not currently used) the application group
cannot be used to deliver applications until it specifies at least one delivery group. Also, you cannot
add applications to the application group from the From Start menu source if there are no delivery
groups specified.
The delivery groups you select specify the machines that are used to deliver applications. Select the
check boxes next to the delivery groups you want to associate with the application group.
To add a tag restriction, select Restrict launches to machines with the tag and then select the tag
from the drop‑down list.
Step 2. Users
Specify application users in the application group. Either allow all users and user groups in the de‑
livery groups you selected on the previous page, or select specific users and user groups from those
delivery groups. If you restrict use to specified users, then only the users specified in the delivery

group, the application group can access the applications in this group. Essentially, the user list in the
application group provides a filter on the user lists in the delivery groups.
Enabling or disabling application use by unauthenticated users is available only in delivery groups,
not in application groups.
For information about where user lists are specified in a deployment, see Where user lists are speci‑
fied.
Step 3. Applications
Good to know:
• By default, new applications you add are placed in a folder named Applications. You can spec‑
ify a different folder. If you try to add an application and one with the same name exists in
that folder, you are prompted to rename the application you are adding. If you agree with the
suggested unique name, the application is added with that new name. Otherwise, you must
rename it yourself before it can be added. For details, see Manage application folders.
• You can change an application’s properties (settings) when you add it, or later. See Change
application properties. If you publish two applications with the same name to the same users,
change the Application name (for user) property in Studio. Otherwise, users see duplicate
names in Citrix Workspace app.
• When you add an application to more than one application group, a visibility issue can occur
if you do not have sufficient permission to view the application in all of those groups. In such
cases, either consult an administrator with greater permissions or have your scope extended to
include all the groups to which the application was added.
Click the Add from the drop‑down menu to display the application sources.
• From Start menu: Applications that are discovered on a machine in the selected delivery
groups. When you select this source, a new page launches with a list of discovered applications.
Select the check boxes of applications to add, and then click OK.
This source cannot be selected if you selected any of the following:
– Application groups that have no associated delivery groups.

– Application groups with associated delivery groups that contain no machines.
– A delivery group containing no machines.
• Manually defined: Applications located in the site or elsewhere in your network. When you
select this source, a new page launches where you type the path to the executable, working
directory, optional command line arguments, and display names for administrators and users.
After entering this information, click OK.
• Existing: Applications previously added to the site. When you select this source, a new page

launches with a list of discovered applications. Select the check boxes of applications to add
and then click OK. This source cannot be selected If the site has no applications.
• App‑V: Applications in App‑V packages. When you select this source, a new page launches
where you select the App‑V server or the Application Library. From the resulting display, select
the check boxes of applications to add, and then click OK. For more information, see App‑V.
This source cannot be selected (or might not appear) if App‑V is not configured for the site.
As noted, certain entries in the Add drop‑down menu are not selectable if there is no valid source of
that type. Sources that are incompatible are not listed at all (for example, you cannot add application
groups to application groups, so that source is not listed when you create an application group).
Step 4. Scopes
This page appears only if you have previously created a custom scope. By default, the All scope is
selected. For more information, see Delegated administration.
Step 5. Summary
Enter a name for the application group. You can also (optionally) enter a description.
Review the summary information and then click Finish.
Manage application groups
April 14, 2021
Introduction
This article describes how to manage the application groups you created.
See Applications for information about managing applications in application groups or delivery
groups, including how to:
• Add or remove applications in an application group.

• Change application group associations.
Managing application groups requires the delegated administration permissions of the Delivery
Group Administrator built‑in role. See Delegated administration for details.

Enable or disable an application group
When an application group is enabled, it can deliver the applications that have been added to it. Dis‑
abling an application group disables each application in that group. However, if those applications
are also associated with other enabled application groups, they can be delivered from those other
groups. If the application was explicitly added to delivery groups associated with the application
group, disabling the application group does not affect the applications in those delivery groups.
An application group is enabled when you create it. You cannot change this configuration when you
create the group.
1. Select Applications in the Studio navigation pane.

2. Select an application group in the middle pane and then select Edit Application Group in the
Actions pane.
3. On the Settings page, select or clear the Enable Application Group check box.
4. Click Apply to keep the window open, or click OK to apply changes and close the window.
Enable or disable application session sharing between application groups
Session sharing between application groups is enabled when you create an application group. You
cannot change this configuration when you create the group. For more information, see Session shar‑
ing with application groups.

Actions pane.
3. On the Settings page, select or clear the Enable application session sharing between Appli‑
cation Groups check box.
4. Click Apply to keep the window open, or click OK to apply changes and close the window.
Disable application session sharing within an application group
Session sharing between applications in the same application group is enabled by default when you
create an application group. If you disable application session sharing between application groups,
session sharing between applications in the same application group remains enabled.
You can use the PowerShell SDK to configure application groups with application session sharing dis‑
abled between the applications they contain. In some circumstances this option is desirable. For
example, you might want users to start non‑seamless applications in full‑size application windows
on separate monitors.
When you disable application session sharing within an application group, each application in that
group launches in a new application session. If a suitable disconnected session is available which is

running the same application, it is reconnected. For example, when launching Notepad with a discon‑
nected session with Notepad running, that session is reconnected instead of creating a one. When
multiple suitable disconnected sessions are available, one of the sessions is chosen to reconnect to,
in a random but deterministic manner. When the situation reoccurs in the same circumstances, the
same session is chosen, but the session is not necessarily predictable otherwise.
Use the PowerShell SDK either to disable application session sharing for all applications in an existing
application group, or to create a group with application session sharing disabled.
PowerShell cmdlet examples
To disable session sharing, use the Broker PowerShell cmdlets New-BrokerApplicationGroup or

Set-BrokerApplicationGroup with the parameter SessionSharingEnabled set to False and
the parameter SingleAppPerSession set to True.
• For example, to create an application group with application session sharing disabled for all
applications in the group:
New-BrokerApplicationGroup AppGr1 -SessionSharingEnabled $False ‐

SingleAppPerSession $True
• For example, to disable application session sharing between all applications in an existing ap‑
plication group:
Set-BrokerApplicationGroup AppGR1 -SessionSharingEnabled $False ‐

SingleAppPerSession $True
Considerations
• To enable the SingleAppPerSession property you must set the SessionSharingEnabled

property to False. The two properties must not be enabled at the same time. The
SessionSharingEnabled parameter refers to sharing sessions between application
groups.
• Application session sharing works only for applications that are associated with application
groups but are not associated with delivery groups. All applications associated directly with
a delivery group share sessions by default.
• If an application is assigned to multiple application groups, make sure that the groups do not
have conflicting settings. For example, one group with the option set to True, and another
group’s option set to False results in unpredictable behavior.
Rename an application group

2. Select an application group in the middle pane and then select Rename Application Group in
the Actions pane.
3. Specify the new unique name and then click OK.
Add, remove, or change the priority of delivery group associations with an application
group
An application group can be associated with delivery groups containing shared (not private) machines
that can deliver applications.
You can also select delivery groups containing shared machines that deliver only desktops, if both of
the following conditions are met:
• The delivery group contains shared machines and was created with a version earlier than 7.9.
• You have Edit Delivery Group permission.
The delivery group type is automatically converted to “desktops and applications” when the Edit Ap‑
plication Group dialog is committed.

Actions pane.
3. Select the Delivery Groups page.
4. To add delivery groups, click Add. Select the check boxes of available delivery groups. (Incom‑
patible delivery groups cannot be selected.) When you finish your selections, click OK.
5. To remove delivery groups, select the check boxes of the groups you want to remove and then
click Remove. Confirm the deletion when prompted.
6. To change the priority of delivery groups, select the check box of the delivery group and then
click Edit Priority. Enter the priority (0 = highest) and then click OK.
7. Click Apply to apply any changes you made and keep the window open, or click OK to apply
Add, change, or remove a tag restriction in an application group
Adding, changing, and removing tag restrictions can have unanticipated effects on which machines
are considered for application launch. Review the considerations and cautions in Tags.

Actions pane.
3. Select the Delivery Groups page.
4. To add a tag restriction, select Restrict launches to machines with the tag and then select the
tag from the drop‑down list.

5. To change or remove a tag restriction, select a different tag or remove the tag restriction entirely
by clearing Restrict launches to machines with this tag.
Add or remove users in an application group
For detailed information about users, see Create application groups.

Actions pane.
3. Select the Users page. Indicate whether you want to allow all users in the associated delivery
groups to use applications in the application group, or only specific users and groups. To add
users, click Add, and then specify the users you want to add. To remove users, select one or
more users and then click Remove.
Change scopes in an application group
You can change a scope only if you have created a scope (you cannot edit the All scope). For more
information, see Delegated administration.
Actions pane.
3. Select the Scopes page. Select or clear the check box next to a scope.
Delete an application group
An application must be associated with at least one delivery group or application group. If deleting an
application group results in one or more applications no longer belonging to a group, you are warned
that deleting that group also removes those applications. You can then confirm or cancel the deletion.
Deleting an application does not delete it from its original source. However, if you want to make it
available again, you must add it again.
2. Select an application group in the middle pane and then select Delete Group in the Actions
pane.

3. Confirm the deletion when prompted.
Remote PC Access
April 14, 2021
Remote PC Access is a feature of Citrix Virtual Apps and Desktops that enables organizations to easily
allow their employees to access corporate resources remotely in a secure manner. The Citrix platform
makes this secure access possible by giving users access to their physical office PCs. If users can ac‑
cess their office PCs, they can access all the applications, data, and resources they need to do their
work. Remote PC Access eliminates the need to introduce and provide other tools to accommodate
teleworking. For example, virtual desktops or applications and their associated infrastructure.
Remote PC Access uses the same Citrix Virtual Apps and Desktops components that deliver virtual
desktops and applications. As a result, the requirements and process of deploying and configuring
Remote PC Access are the same as those required for deploying Citrix Virtual Apps and Desktops for
the delivery of virtual resources. This uniformity provides a consistent and unified administrative ex‑
perience. Users receive the best user experience by using Citrix HDX to deliver their office PC session.
The feature consists of a machine catalog of type Remote PC Access that provides this functionality:
• Ability to add machines by specifying OUs. This ability facilitates the addition of PCs in bulk.
• Automatic user assignment based on the user that logs into the office Windows PC. We support
single user and multiple users assignments.
Citrix Virtual Apps and Desktops can accommodate more use cases for physical PCs by using other
types of machine catalogs. These use cases include:
• Physical Linux PCs

• Pooled physical PCs (that is, randomly assigned, not dedicated)
Notes:
For details on the supported OS versions, see the system requirements for the VDA for single‑
session OS and Linux VDA.
For on‑premises deployments, Remote PC Access is valid only for Citrix Virtual Apps and Desktops
Advanced or Premium licenses. Sessions consume licenses in the same way as other Citrix Virtual
Desktops sessions. For Citrix Cloud, Remote PC Access is valid for the Citrix Virtual Apps and
Desktops Service and Workspace Premium Plus.

Considerations
While all the technical requirements and considerations that apply to Citrix Virtual Apps and Desktops
in general also apply to Remote PC Access, some might be more relevant or exclusive to the physical
PC use case.
Deployment considerations
While planning the deployment of Remote PC Access, make a few general decisions.
• You can add Remote PC Access to an existing Citrix Virtual Apps and Desktops deployment. Be‑
fore choosing this option, consider the following:
– Are the current Delivery Controllers or Cloud Connectors appropriately sized to support
the additional load associated with the Remote PC Access VDAs?
– Are the on‑premises site databases and database servers appropriately sized to support
the additional load associated with the Remote PC Access VDAs?
– Will the existing VDAs and the new Remote PC Access VDAs exceed the number of maxi‑
mum supported VDAs per site?
• You must deploy the VDA to office PCs through an automated process. The following are two of
options available:
– Electronic Software Distribution (ESD) tools such as SCCM: Install VDAs using SCCM.
– Deployment scripts: Install VDAs using scripts.
• Review the Remote PC Access security considerations.
Machine catalog considerations
The type of machine catalog required depends on the use case:
• Remote PC Access
– Windows dedicated PCs
– Windows dedicated multi‑user PCs
• Single‑session OS
– Static ‑ Dedicated Linux PCs
– Random ‑ Pooled Windows and Linux PCs
Once you identify the type of machine catalog, consider the following:
• A machine can be assigned to only one machine catalog at a time.

• To facilitate delegated administration, consider creating machine catalogs based on geographic
location, department, or any other grouping that eases delegating administration of each cata‑
log to the appropriate administrators.
• When choosing the OUs in which the machine accounts reside, select lower‑level OUs for greater
granularity. If such granularity is not required, you can choose higher‑level OUs. For example,

in the case of Bank/Officers/Tellers, select Tellers for greater granularity. Otherwise, you can
select Officers or Bank based on the requirement.
• Moving or deleting OUs after being assigned to a Remote PC Access machine catalog affects
VDA associations and causes issues with future assignments. Therefore, make sure to plan ac‑
cordingly so that OU assignment updates for machine catalogs are accounted for in the Active
Directory change plan.
• If it is not easy to choose OUs to add machines to the machine catalog because of the OU struc‑
ture, you don’t have to select any OUs. You can use PowerShell to add machines to the catalog
afterward. User auto‑assignments continue to work if the desktop assignment is configured
correctly in the Delivery Group. A sample script to add machines to the machine catalog along
with user assignments is available in GitHub.
• Integrated Wake on LAN is available only with the Remote PC Access type machine catalog.
Linux VDA considerations
These considerations are specific to the Linux VDA:
• Use the Linux VDA on physical machines only in non‑3D mode. Due to limitations on NVIDIA’s
driver, the local screen of the PC cannot be blacked out and displays the activities of the session
when HDX 3D mode is enabled. Showing this screen is a security risk.
• Use machine catalogs of type single‑session OS for physical Linux machines.
• The integrated Wake on LAN functionality is not available for Linux machines.
Technical requirements and considerations
This section contains the technical requirements and considerations for physical PCs.
• The following are not supported:
– KVM switches or other components that can disconnect a session.

– Hybrid PCs, including All‑in‑One and NVIDIA Optimus laptops and PCs.
• Connect the keyboard and mouse directly to the PC. Connecting to the monitor or other com‑
ponents that can be turned off or disconnected, can make these peripherals unavailable. If you
must connect the input devices to components such as monitors, do not turn those components
off.
• The PCs must be joined to an Active Directory Domain Services domain.
• Secure Boot is supported on Windows 10 only.
• The PC must have an active network connection. A wired connection is preferred for greater
reliability and bandwidth.
• If using Wi‑Fi, do the following:

1. Set the power settings to leave the wireless adapter turned on.
2. Configure the wireless adapter and network profile to allow automatic connection to the
wireless network before the user logs on. Otherwise, the VDA does not register until the
user logs on. The PC isn’t available for remote access until a user has logged on.
3. Ensure that the Delivery Controllers or Cloud Connectors can be reached from the Wi‑Fi
network.
• You can use Remote PC Access on laptop computers. Ensure the laptop is connected to a power
source instead of running on the battery. Configure the laptop power options to match the op‑
tions of a desktop PC. For example:
1. Disable the hibernate feature.

2. Disable the sleep feature.
3. Set the close lid action to Do Nothing.
4. Set the “press the power button” action to Shut Down.
5. Disable video card and NIC energy‑saving features.
• Remote PC Access is supported on Surface Pro devices with Windows 10. Follow the same guide‑
lines for laptops mentioned previously.
• If using a docking station, you can undock and redock laptops. When you undock the laptop, the
VDA reregisters with the Delivery Controllers or Cloud Connectors over Wi‑Fi. However, when
you redock the laptop, the VDA doesn’t switch to use the wired connection unless you discon‑
nect the wireless adapter. Some devices provide built‑in functionality to disconnect the wire‑
less adapter upon establishing a wired connection. The other devices require custom solutions
or third‑party utilities to disconnect the wireless adapter. Review the Wi‑Fi considerations men‑
tioned previously.
Do the following to enable docking and undocking for Remote PC Access devices:
1. In the Start menu, select Settings > System > Power & Sleep, and set Sleep to Never.
2. Under the Device Manager > Network adapters > Ethernet adapter go to Power Man‑
agement and clear Allow the computer to turn off this device to save power. Ensure
that Allow this device to wake the computer is checked.
• Multiple users with access to the same office PC see the same icon in Citrix Workspace. When
a user logs on to Citrix Workspace, that resource appears as unavailable if already in use by
another user.
• Install the Citrix Workspace app on each client device (for example, a home PC) that accesses
the office PC.

Configuration sequence
This section contains an overview of how to configure Remote PC Access when using the Remote PC
Access type machine catalog. For information on how to create other types of machine catalogs, see
the Create machine catalogs.
1. On‑premises site only ‑ To use the integrated Wake on LAN feature, configure the prerequisites
outlined in Wake on LAN.
2. If a new Citrix Virtual Apps and Desktops site was created for Remote PC Access:
a) Select the Remote PC Access Site type.

b) On the Power Management page, choose to enable or disable power management for the
default Remote PC Access machine catalog. You can change this setting later by editing the
machine catalog properties. For details on configuring Wake on LAN, see Wake on LAN.
c) Complete the information on the Users and Machine Accounts pages.
Completing these steps creates a machine catalog named Remote PC Access Machines and a
Delivery Group named Remote PC Access Desktops.
3. If adding to an existing Citrix Virtual Apps and Desktops site:
a) Create a machine catalog of type Remote PC Access (Operating System page of the wiz‑
ard). For details on how to create a machine catalog, see Create machine catalogs. Make
sure to assign the correct OU so that the target PCs are made available for use with Remote
PC Access.
b) Create a Delivery Group to provide users access to the PCs in the machine catalog. For
details on how to create a Delivery Group, see Create Delivery Groups. Make sure to assign
the Delivery Group to an Active Directory group that contains the users that require access
to their PCs.
4. Deploy the VDA to the office PCs.
• We recommend using the single‑session OS core VDA installer (VDAWorkstationCore‑

Setup.exe).
• You can also use the single‑session full VDA installer (VDAWorkstationSetup.exe) with the
/remotepc option, which achieves the same outcome as using the core VDA installer.
• Consider enabling Windows Remote Assistance to allow help desk teams to provide re‑
mote support through Citrix Director. To do so, use the /enable_remote_assistance
option. For details, see Install using the command line.
• To be able to see logon duration information in Director, you must use the single‑session
full VDA installer and include the Citrix User Profile Manager WMI Plugin component. In‑
clude this component by using the /includeadditional option. For details, see Install
using the command line.
• For information about deploying the VDA using SCCM, see Install VDAs using SCCM.

• For information about deploying the VDA through deployment scripts, see Install VDAs us‑
ing scripts.
After you successfully complete steps 2–4, users are automatically assigned to their own ma‑
chines when they log in locally on the PCs.
5. Instruct users to download and install Citrix Workspace app on each client device that they use
to access the office PC remotely. Citrix Workspace app is available from https://www.citrix
.com/downloads/ or the application stores for supported mobile devices.
Features managed through the registry

Caution:
Disable multiple user auto‑assignments
On each Delivery Controller, add the following registry setting:
HKEY_LOCAL_MACHINE\Software\Citrix\DesktopServer
• Name: AllowMultipleRemotePCAssignments
• Type: DWORD
• Data: 0
Sleep mode (minimum version 7.16)
To allow a Remote PC Access machine to go into a sleep state, add this registry setting on the VDA, and
then restart the machine. After the restart, the operating system power saving settings are respected.
The machine goes into sleep mode after the preconfigured idle timer passes. After the machine wakes
up, it reregisters with the Delivery Controller.
HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\PortICA
• Name: DisableRemotePCSleepPreventer
• Type: DWORD
• Data: 1

Session management
By default, a remote user’s session is automatically disconnected when a local user initiates a session
on that machine (by pressing CTRL+ATL+DEL). To prevent this automatic action, add the following
registry entry on the office PC, and then restart the machine.
HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\PortICA\RemotePC
• Name: SasNotification
• Type: DWORD
• Data: 1
By default, the remote user has preference over the local user when the connection message is not
acknowledged within the timeout period. To configure the behavior, use this setting:
HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\PortICA\RemotePC
• Name: RpcaMode
• Type: DWORD
• Data:
– 1 ‑ The remote user always has preference if he or she does not respond to the messaging UI
in the specified timeout period. This behavior is the default if this setting is not configured.
– 2 ‑ The local user has preference.
The timeout for enforcing the Remote PC Access mode is 30 seconds by default. You can configure this
timeout but do not set it lower than 30 seconds. To configure the timeout, use this registry setting:
HKLM\SOFTWARE\Citrix\PortICA\RemotePC
• Name: RpcaTimeout
• Type: DWORD
• Data: number of seconds for timeout in decimal values
When a user wants to forcibly get the console access: The local user can press Ctrl+Alt+Del twice in a
gap of 10 seconds to get local control over a remote session and force a disconnect event.
After the registry change and machine restart, if a local user presses Ctrl+Alt+Del to log on to that
PC while it is in use by a remote user, the remote user receives a prompt. The prompt asks whether
to allow or deny the local user’s connection. Allowing the connection disconnects the remote user’s
session.
Wake on LAN
Integrated Wake on LAN is available only in on‑premises Citrix Virtual Apps and Desktops and requires
Microsoft System Center Configuration Manager (SCCM).
Remote PC Access supports Wake on LAN, which gives users the ability to turn on physical PCs re‑
motely. This feature enables users to keep their office PCs turned off when not in use, saving energy

costs. It also enables remote access when a machine has been turned off inadvertently. For example,
because of a power outage.
The Remote PC Access Wake on LAN feature is supported with

PCs that have the Wake on LAN option enabled in the BIOS/UEFI.
SCCM and Remote PC Access Wake on LAN
To configure the Remote PC Access Wake on LAN feature, complete the following before deploying the
VDA.
• Configure SCCM 2012 R2, 2016, or 2019 within the organization. Then deploy the SCCM client
to all Remote PC Access machines, allowing time for the scheduled SCCM inventory cycle to run
(or force one manually, if necessary).
• For SCCM Wake Proxy or magic packet support:
– Configure Wake on LAN in each PC’s BIOS/UEFI settings.
– For Wake Proxy support, enable the option in SCCM. For each subnet in the organization
that contains PCs that use the Remote PC Access Wake on LAN feature, ensure that three
or more machines can serve as sentinel machines.
– For magic packet support, configure network routers and firewalls to allow magic packets
to be sent, using either a subnet‑directed broadcast or unicast.
After you install the VDA on office PCs, enable or disable power management when you create the
connection and the machine catalog.
• If you enable power management in the catalog, specify connection details: the SCCM address,
access credentials, and connection name. The access credentials must have access to collec‑
tions in the scope and the Remote Tools Operator role.
• If you do not enable power management, you can add a power management (Configuration
Manager) connection later and then edit a Remote PC Access machine catalog to enable power
management.
You can edit a power management connection to configure advanced settings. You can enable:
• Wake‑up proxy delivered by SCCM.

• Wake on LAN (magic) packets. If you enable Wake on LAN packets, you can select a Wake on LAN
transmission method: subnet‑directed broadcasts or Unicast.
The PC uses AMT power commands (if they are supported), plus any of the enabled advanced settings.
If the PC does not use AMT power commands, it uses the advanced settings.

Troubleshoot
Monitor blanking not working
If the Windows PC’s local monitor is not blank while there is an active HDX session (the local monitor
displays what’s happening in the session) it is likely due to issues with the GPU vendor’s driver. To
resolve the issue, give the Citrix Indirect Display driver (IDD) higher priority than the graphic card’s
vendor driver by setting the following registry value:
HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\Graphics\AdapterMerits
• Name: CitrixIDD
• Type: DWORD
• Data: 3
For more details about display adapter priorities and monitor creation, see the Knowledge Center
article CTX237608.
Session disconnects when you select Ctrl+Alt+Del on the machine that has session
management notification enabled
The session management notification controlled by the SasNotification registry value only works
when Remote PC Access mode is enabled on the VDA. If the physical PC has the Hyper‑V role or any
virtualization‑based security features enabled, the PC reports as a virtual machine. If the VDA detects
that it is running on a virtual machine, it automatically disables Remote PC Access mode. To enable
Remote PC Access mode, add the following registry value:
• Name: ForceEnableRemotePC
• Type: DWORD
• Data: 1
Restart the PC for the setting to take effect.
Diagnostic information
Diagnostic information about Remote PC Access is written to the Windows Application Event log. Infor‑
mational messages are not throttled. Error messages are throttled by discarding duplicate messages.
• 3300 (informational): Machine added to catalog

• 3301 (informational): Machine added to delivery group
• 3302 (informational): Machine assigned to user
• 3303 (error): Exception

Power management
If power management for Remote PC Access is enabled, subnet‑directed broadcasts might fail to start
machines that are on a different subnet from the Controller. If you need power management across
subnets using subnet‑directed broadcasts, and AMT support is not available, try the Wake‑up proxy
or Unicast method. Ensure those settings are enabled in the advanced properties for the power man‑
agement connection.
The active remote session records the local touchscreen input
When the VDA enables Remote PC Access mode, the machine ignores the local touchscreen input dur‑
ing an active session. If the physical PC has the Hyper‑V role or any virtualization‑based security fea‑
tures enabled, the PC reports as a virtual machine. If the VDA detects that it is running on a virtual
machine, it automatically disables Remote PC Access mode. To enable Remote PC Access mode, add
the following registry setting:
• Name: ForceEnableRemotePC
• Type: DWORD
• Data: 1
Restart the PC for the setting to take effect.
More resources
The following are other resources for Remote PC Access:
• Solution design guidance: Remote PC Access Design Decisions.

• Examples of Remote PC Access architectures: Reference Architecture for Citrix Remote PC Ac‑
cess Solution.
App‑V
April 14, 2021
Using App‑V with Citrix Virtual Apps and Desktops
Microsoft Application Virtualization (App‑V) lets you deploy, update, and support applications as ser‑
vices. Users access applications without installing them on their own devices. App‑V and Microsoft

User State Virtualization (USV) provide access to applications and data, regardless of location and con‑
nection to the internet.
The following table lists supported versions.
Citrix Virtual Apps and

Desktops Delivery Citrix Virtual Apps and
App‑V Controller Desktops VDA
5.0 and 5.0 SP1 XenDesktop 7 through 7.0 through current

current, XenApp 7.5 through
current
5.0 SP2 XenDesktop 7 through 7.1 through current
current
5.0 SP3 and 5.1 XenDesktop 7.6 through 7.6.300 through current
current
App‑V in Windows Server 2016 XenDesktop 7.12 through 7.12 through current
current
The App‑V client does not support offline access to applications. App‑V integration support includes
using SMB shares for applications. The HTTP protocol is not supported.
If you’re not familiar with App‑V, see the Microsoft documentation. Here’s a recap of the App‑V com‑
ponents mentioned in this article:
• Management server. Provides a centralized console to manage App‑V infrastructure and deliv‑
ers virtual applications to both the App‑V Desktop Client and a Remote Desktop Services Client.
The App‑V management server authenticates, requests, and provides the security, metering,
monitoring, and data gathering required by the administrator. The server uses Active Directory
and supporting tools to manage users and applications.
• Publishing server. Provides App‑V clients with applications for specific users, and hosts the
virtual application package for streaming. It fetches the packages from the management server.
• Client. Retrieves virtual applications, publishes the applications on the client, and automati‑
cally sets up and manages virtual environments at runtime on Windows devices. You install the
App‑V client on the VDA, where it stores user‑specific virtual application settings such as registry
and file changes in each user’s profile.
Applications are available seamlessly without any pre‑configuration or changes to operating system
settings. You can launch App‑V applications from Server OS and Desktop OS Delivery Groups:

• Through Citrix Workspace app

• Through the App‑V client and Citrix Workspace app
• Simultaneously by multiple users on multiple devices
• Through Citrix StoreFront
Modified App‑V application properties are implemented when the application is started. For example,
for applications with a modified display name or customized icon, the modification appears when
users start the application. Application customizations saved in dynamic configuration files are also
applied when the application is launched.
Management methods
You can use App‑V packages and dynamic configuration files created with the App‑V sequencer and
then located on either App‑V servers or network shares.
• App‑V servers: Using applications from packages on App‑V servers requires ongoing commu‑
nication between Studio and the App‑V servers for discovery, configuration, and downloading
to the VDAs. This incurs hardware, infrastructure, and administration overhead. Studio and the
App‑V servers must remain synchronized, particularly for user permissions.
This is called the dual admin management method because App‑V package and application ac‑
cess requires both Studio and the App‑V server consoles. This method works best in closely
coupled App‑V and Citrix deployments. In this method, the management server handles the dy‑
namic configuration files. When you use the dual admin management method, the Citrix App‑V
components manage the registration of the appropriate publishing server required for an ap‑
plication launch. This ensures that the publishing server is synchronized for the user at the
appropriate time. The publishing server maintains other aspects of the package life cycle (like
refresh on logon and connection groups) using the settings that it is configured with.
• Network share: Packages and XML deployment configuration files placed on a network share
remove Studio’s dependence on the App‑V server and database infrastructure, reducing over‑
head. (You must install the Microsoft App‑V client on each VDA.)
This is called the single admin management method because App‑V package and application
use only needs the Studio console. You browse to the network share and add one or more
App‑V packages from that location to the Site‑level Application Library [1]. In this method, the
Citrix App‑V components process the Deployment Configuration Files when the application is
launched. (User Configuration Files are not supported.) When you use the single admin man‑
agement method, the Citrix App‑V components manage all aspects of the Package’s life cycle on
the host machine. Packages are added to the machine at broker startup, or when a configura‑
tion change is detected (which can also be at session launch time). Packages are first published
to individual users on demand ‘just in time’ when a launch request is received from the Citrix
Workspace app.

Single Admin also manages the lifecycle of connection groups required to meet the Isolation
Group configuration definitions made in Studio.
[1] Application Library is a Citrix term for a caching repository that stores information about
App‑V packages. The Application Library also stores information about other Citrix application
delivery technologies.
In both management methods, if the VDA is configured to discard user data, the publishing (or syn‑
chronizing) must be redone at the next session launch.
You can use one or both management methods simultaneously. In other words, when you add appli‑
cations to Delivery Groups, the applications can come from App‑V packages located on App‑V servers
or on a network share.
Note:
If you are using both management methods simultaneously, and the App‑V package has a dy‑
namic configuration file in both locations, the file in the App‑V server (dual management) is used.
When you select Configuration > App‑V Publishing in the Studio navigation pane, the display shows
App‑V package names and sources. The source column indicates whether the packages are located
on the App‑V server or cached in the Application Library. When you select a package, the details pane
lists the applications and shortcuts in the package.
Dynamic configuration files
Overview
App‑V packages can be customized using dynamic configuration files, that when applied to the pack‑
age, can be used to change its characteristics. For example, you can use them to define extra appli‑
cation shortcuts and behaviors. Citrix App‑V supports both types of dynamic configuration file. File
settings are applied when the application is launched:
• Deployment Configuration Files provide machine‑wide configuration for all users. These files
are expected to be named <packageFileName>_DeploymentConfig.xml and located in the same
folder as the App‑V package they apply to. Supported by single and dual admin management.
• User Configuration Files provide user‑specific configuration which supports per‑user cus‑
tomizations to the package. Single Admin supports user config files named in the following
format: <packageFileName>_[UserSID | Username | GroupSID |GroupName_]UserConfig.xml
and located in the same folder as the App‑V package they apply to.
When multiple user config files exist for a particular package, they are applied with the following pri‑
ority:
1. User SID
2. Username

3. AD Group SID (First found wins)

4. AD Group Name (First found wins)
5. Default
For example
1 MyAppVPackage_S-1-5-21-000000001-0000000001-000000001-001_UserConfig.
xml
2 MyAppVPackage_joeblogs_UserConfig.xml
3 MyAppVPackage_S-1-5-32-547_UserConfig.xml
4 MyAppVPackage_Power Users_UserConfig.xml
5 MyAppVPackage_UserConfig.xml
Note:
The user‑specific portion of the file name can also optionally occur at the end (for example MyAp‑
pVPackage_UserConfig_joeblogs.xml).
Dynamic configuration file location

In single admin management, the Citrix App‑V components only process dynamic configuration files
which are found in the same folder as their App‑V package. When applications in the package are
launched, any changes to the corresponding dynamic configuration files are reapplied. If your dy‑
namic configuration files are located in a different location to their packages, use a mapping file to
map packages to their deployment configuration files.
To create a mapping file

1. Open a new text file.
2. For each dynamic configuration file, add a line which specifies the path to the package using
the format <PackageGuid> : path.
For example:
F1f4fd78ef044176aad9082073a0c780 : c:\widows\file\packagedeploy.xml
3. Save the file as ctxAppVDynamicConfigurations.cfg in the same folder as the package. The en‑
tire directory hierarchy on the same UNC share as the App‑V package is searched recursively
upwards for this file every time an application in the package is launched.
Note:
You cannot apply changes to Dynamic Deployment Configuration when there are user sessions
with an application in the package open. You can apply changes to Dynamic User Configuration

files if other users but not the current user have the an application from the package open.
Isolation groups
When you use the App‑V single admin method, creating isolation groups allow you to specify interde‑
pendent groups of applications that must run in the sandbox. This feature is similar, but not identical
to, App‑V connection groups. Instead of the mandatory and optional package terminology used by
the App‑V management server, Citrix uses automatic and explicit for package deployment options.
• When a user launches an App‑V application (the primary application), the isolation groups are
searched for other application packages that are marked for automatic inclusion. Those pack‑
ages are downloaded and included in the isolation group automatically. You do not need to add
them to the Delivery Group that contains the primary application.
• An application package in the isolation group that is marked for explicit inclusion is downloaded
only if you have explicitly added that application to the same Delivery Group that contains the
primary application.
This allows you to create isolation groups containing a mix of automatically included applications that
are available globally to all users. Plus, the group can contain a set of plug‑ins and other applications
(that might have specific licensing constraints), which you can limit to a certain set of users (identified
through Delivery Groups) without having to create more isolation groups.
For example, application “app‑a” requires JRE 1.7 to run. You can create an isolation group containing
app‑a (with an explicit deployment type) and JRE 1.7 (with an automatic deployment type). Then,
add those App‑V packages to one or more Delivery Groups. When a user launches app‑a, JRE 1.7 is
automatically deployed with it.
You can add an application to more than one App‑V isolation group. However, when a user launches
that application, the first isolation group to which that application was added is always used. You
cannot order or prioritize other isolation groups containing that application.
Load balancing App‑V servers
Load balancing management and publishing servers using DNS Round‑Robin is supported if you
are using the dual admin management method. Load balancing the management server behind
Netscaler, F5 (or similar) Virtual IP is not supported because of the way Studio needs to communicate
with the Management Server via remote PowerShell. For more information, see this Citrix blog
article.
Setup
The following table summarizes the sequence of setup tasks for using App‑V in Citrix Virtual Apps and
Desktops using single‑ and dual admin management methods.

Single admin Dual admin Task
X X Deploy App‑V
X X Packaging and placement
X Configure App‑V server
addresses in Studio
X X Install software on VDA
machines
X Add App‑V packages to the
Application Library
X Add App‑V isolation groups
(optional)
X X Add App‑V applications to
Delivery Groups
Deploy Microsoft App‑V
For App‑V deployment instructions, see https://docs.microsoft.com/en‑us/microsoft‑desktop‑

optimization‑pack/.
Optionally, change App‑V publishing server settings. Citrix recommends using the SDK cmdlets on
the Controller. See the SDK documentation for details.
• To view publishing server settings, enter Get‑CtxAppvServerSetting ‑AppVPublishingServer
<pubServer>.
• To ensure that App‑V applications launch properly, enter Set‑CtxAppvServerSetting –
UserRefreshonLogon 0.
If you previously used GPO policy settings to manage publishing server settings, the GPO settings
override any App‑V integration settings, including cmdlet settings. This can result in App‑V application
launch failure. Citrix recommends that you remove all GPO policy settings and then use the SDK to
configure those settings.
Packaging and placement
For either management method, create application packages using the App‑V sequencer. See the
Microsoft documentation for details.
• For single admin management, make the packages, and their corresponding dynamic configu‑
ration files, available on a UNC or SMB shared network location. Ensure that the Studio admin‑
istrator who adds applications to Delivery Groups has at least read access to that location.

• For dual admin management, publish the packages on the App‑V management server from a
UNC path. (Publishing from HTTP URLs is not supported.)
Regardless of whether packages are on the App‑V server or on a network share, ensure the packages
have appropriate security permissions to allow the Studio administrator to access them. Network
shares must be shared with “Authenticated users” to ensure that both the VDA and Studio have read
access by default.
Configure App‑V server addresses in Studio

Important:
Citrix recommends using the PowerShell cmdlets on the Controller to specify App‑V server ad‑
dresses if those servers use nondefault property values. See the SDK documentation for details.
If you change App‑V server addresses in Studio, some server connection properties you specify
might be reset to default values. These properties are used on the VDAs to connect to App‑V pub‑
lishing servers. If this happens, reconfigure the nondefault values for any reset properties on the
servers.
This procedure is valid only for the dual admin management method.
Specify App‑V management and publishing server addresses for the dual admin management method
either during or after Site creation. You can do this during or after creating the Site.
During Site creation:
• On the App‑V page of the wizard, enter the URL of the Microsoft App‑V management server, and
the URL and port number of the App‑V publishing server.
• Test the connection before continuing with the wizard. If the test fails, see the Troubleshoot
section below.
After Site creation:
1. Select Configuration > App‑V Publishing in the Studio navigation pane.

2. If you have not previously specified App‑V server addresses, select Add Microsoft Server in the
Actions pane.
3. To change App‑V server addresses, select Edit Microsoft Server in the Actions pane.
4. Enter the URL of the Microsoft App‑V management server, and the URL and port number of the
App‑V publishing server.
5. Test the connection to those servers before closing the dialog box. If the test fails, see the Trou‑
bleshoot section below.
Later, if you want to remove all links to the App‑V management and publishing servers and stop Stu‑
dio from discovering App‑V packages from those servers, select Remove Microsoft Server in the Ac‑
tions pane. This action is allowed only if no applications in packages on those servers are currently

published in any Delivery Groups. If they are, you must remove those applications from the Delivery
Groups before you can remove the App‑V servers.
Install software on VDA machines
Machines containing VDAs must have two sets of software installed to support App‑V: one from Mi‑
crosoft and the other from Citrix.
Microsoft App‑V client

This software retrieves virtual applications, publishes the applications on the client, and automati‑
cally sets up and manages virtual environments at runtime on Windows devices. The App‑V client
stores user‑specific virtual application settings, such as registry and file changes in each user’s pro‑
file.
The App‑V client is available from Microsoft. Install a client on each machine containing a VDA, or
on the master image that is used in a machine catalog to create VMs. Note: Windows 10 (1607 or
greater) and Windows Server 2016 already include the App‑V client. On those OSs only, enable the
App‑V client by running the PowerShell Enable‑AppV cmdlet (no parameters). The Get‑AppVStatus
cmdlet retrieves the current enablement status.
Tip:
After you install the App‑V client, with Administrator permissions, run the PowerShell Get‑
AppvClientConfiguration cmdlet, and ensure that EnablePackageScripts is set to 1. If it is not
set to 1, run Set‑AppvClientConfiguration ‑EnablePackageScripts $true.
Citrix App‑V components

The Citrix App‑V component software is excluded by default when you install a VDA.
You can control this default behavior during VDA installation. In the graphical interface, select the
Citrix Personalization for App‑V ‑ VDA check box on the Additional Components page. In the com‑
mand line interface, use the /includeadditional “Citrix Personalization for App‑V – VDA” option.
If you do not include the Citrix App‑V components during VDA installation, but later want to use App‑
V applications: In the Windows machine’s Programs and Features list, right‑click the Citrix Virtual
Delivery Agent entry and then select Change. A wizard launches. In the wizard, enable the option
that installs and enables App‑V publishing components.
Add or remove App‑V packages in the Application Library
These procedures are valid only for the single admin management method.
You must have at least read access to the network share containing the App‑V packages.

Add an App‑V package to the Application Library

2. Select Add Packages in the Actions pane.
3. Browse to the share containing the App‑V packages and select one or more packages.
4. Click Add.
Remove an App‑V package from the Application Library
Removing an App‑V package from the Application Library removes it from the Studio App‑V Publishing
node display. However, it does not remove its applications from Delivery Groups, and those applica‑
tions can still be launched. The package remains in its physical network location. (This effect differs
from removing an App‑V application from a Delivery Group.)

2. Select one or more packages to be removed.
3. Select Remove Package in the Actions pane.
Add, edit, or remove App‑V isolation groups
Add an App‑V isolation group
1. Select App‑V Publishing in the Studio navigation pane.

2. Select Add Isolation Group in the Actions pane.
3. In the Add Isolation Group Settings dialog box, type a name and description for the isolation
group.
4. From the Available Packages list, select the applications you want to add to the isolation group,
and then click the right arrow. The selected applications should now appear in the Packages
in Isolation Group list. In the Deployment drop‑down next to each application, select either
Explicit or Automatic. You can also use the up and down arrows to change the order of appli‑
cations in the list.
5. When you are done, click OK.
Edit an App‑V isolation group
1. Select App‑V Publishing from the Studio navigation pane.

2. Select the Isolation Groups tab in the middle pane and then select the isolation group you want
to edit.
3. Select Edit Isolation Group in the Actions pane.
4. In the Edit Isolation Group Settings dialog box, change the isolation group name or descrip‑
tion, add or remove applications, change their deployment type, or change the application or‑
der.

5. When you are done, click OK.
Remove an App‑V isolation group

Removing an isolation group does not remove the application packages. It removes only the grouping.
1. Select App‑V Publishing from the Studio navigation pane.
2. Select the Isolation Groups tab in the middle pane and then select the isolation group you want
to remove.
3. Select Remove Isolation Group from the Actions pane.
4. Confirm the removal.
Add App‑V applications to Delivery Groups
The following procedure focuses on how to add App‑V applications to Delivery Groups. For complete
details about creating a Delivery Group, see Create Delivery Groups.
Step 1: Choose whether you want to create a new Delivery Group or add App‑V applications to an
existing Delivery Group:
To create a Delivery Group containing App‑V applications:
1. Select Delivery Groups in the Studio navigation pane.
2. Select Create Delivery Group in the Actions pane.
3. On successive pages of the wizard, specify a machine catalog and users.
To add App‑V applications to existing Delivery Groups:
2. Select Add Applications in the Actions pane.
3. Select one or more Delivery Groups where the App‑V applications will be added.
Step 2: On the Applications page of the wizard, click the Add drop‑down to display application
sources. Select App‑V.
Step 3: On the Add App‑V Applications page, choose the App‑V source: the App‑V server or the Ap‑
plication Library. The resulting display includes the application names plus their package names and
package versions. Select the check boxes next to the applications or application shortcuts you want
to add. Then click OK.
Step 4: Complete the wizard.
Good to know:
• If you change an App‑V application’s properties when adding them to a Delivery Group, the
changes are made when the application is started. For example, if you modify an application’s
display name or icon when adding it to the group, the change appears when a user starts the
application.

• If you use dynamic configuration files to customize the properties of an App‑V application, those
properties override any changes you made when adding them to a Delivery Group.
• If you later edit a Delivery Group containing App‑V applications, there is no change in App‑V
application performance if you change the group’s delivery type from desktops and applications
to applications only.
• When you remove a previously published (single admin) App‑V package from a Delivery Group,
Citrix App‑V client components attempt to clean up, unpublish, and remove any packages that
are no longer in use by the single admin management method.
• If you are using a hybrid deployment—with packages delivered by the single admin manage‑
ment method and an App‑V publishing server, managed either by dual admin or by another
mechanism (such as Group policy)—it is not possible to determine which (now potentially re‑
dundant) packages came from which source. In this case, cleanup is not attempted.
• If you publish more than 100 App‑V applications in a single Delivery Group, applications may not
launch. If so, use the MaxReceivedMessageSize property on the appropriate binding element to
increase Max Receivable message size in the configuration of the Delivery Controller and/or the
Broker Agent on the VDA.
Troubleshoot
Issues that can occur only when using the dual admin method are marked (DUAL).
(DUAL) There is a PowerShell connection error when you select Configuration > App‑V Publishing in
the Studio navigation pane.
• Is the Studio administrator also an App‑V server administrator? The Studio administrator must
belong to the “administrators” group on the App‑V management server so that they can com‑
municate with it.
(DUAL) The Test connection operation returns an error when you specify App‑V server addresses in
Studio.
• Is the App‑V server powered on? Either send a Ping command or check the IIS Manager; each
App‑V server should be in a Started and Running state.
• Is PowerShell remoting enabled on the App‑V server? If not, see https://docs.microsoft.com/en‑

us/previous‑versions/technet‑magazine/ff700227(v=msdn.10).
• Is the Studio administrator also an App‑V server administrator? The Studio administrator must
belong to the administrators group on the App‑V management server so that they can commu‑
nicate with it.
• Is file sharing enabled on the App‑V server? Enter \\<App-V server FQDN> in Windows Ex‑
plorer or with the Run command.

• Does the App‑V server have the same file sharing permissions as the App‑V administrator? On
the App‑V server, add an entry for \\<App-V server FQDN> in Stored User Names and Pass‑
words, specifying the credentials of the user who has administrator privileges on the App‑V
server. For guidance, see http://support.microsoft.com/kb/306541.
• Is the App‑V server in Active Directory?
If the Studio machine and the App‑V server are in different Active Directory domains that do
not have a trust relationship, from the PowerShell console on the Studio machine, run winrm s
winrm/Config/client ‘@(TrustedHosts=”<App‑V server FQDN>”)’.
If TrustedHosts is managed by GPO, the following error message displays: “The config setting
TrustedHosts cannot be changed because use is controlled by policies. The policy would need to be
set to Not Configured to change the config setting.” In this case, add an entry for the App‑V server
name to the TrustedHosts policy in GPO (Administrative Templates > Windows Components >
Windows Remote Management (WinRM) > WinRM Client).
(DUAL) Discovery fails when adding an App‑V application to a Delivery Group.
• Is the Studio administrator also an App‑V management server administrator? The Studio ad‑
ministrator must belong to the administrators group on the App‑V management server so that
they can communicate with it.
• Is the App‑V management server running? Either send a Ping command or check the IIS Man‑
ager; each App‑V server should be in a Started and Running state.
• Is PowerShell remoting enabled on both App‑V servers? If not, see https://docs.microsoft.com/
en‑us/previous‑versions/technet‑magazine/ff700227(v=msdn.10).
• Do packages have the appropriate security permissions for the Studio administrator to access?
App‑V applications only launch in one browser version.
• If you publish multiple sequenced versions of the same browser app, only one version of the app
is able to launch at a time per user on the VDA. The same thing occurs even if Citrix components
are not involved and the user starts the sequenced apps from desktop shortcuts which point to
different paths.
Whichever browser version a user launches first, determines the browser version which runs
subsequently for them. When Firefox detects a second launch of itself, it prefers to create an
instance of the already running process, rather than create a new process. Other browsers may
behave in the same way.
You can make the application launch in the intended Firefox browser version, by adding the
command line parameter ‑no‑remote to the shortcut’s launch command. Other browsers offer
the same or similar facility.

Note:
You must be using XenApp 7.17 or higher to take advantage of the shortcut enumera‑
tion feature. You must also change the package in both versions of the app to get this
bi‑directional behavior.
App‑V applications do not launch.
• (DUAL) Is the publishing server running?

• (DUAL) Do the App‑V packages have appropriate security permissions so that users can access
them?
• (DUAL) On the VDA, ensure that Temp is pointing to the correct location, and that there is enough
space available in the Temp directory.
• (DUAL) On the App‑V publishing server, run Get-AppvPublishingServer \* to display the
list of publishing servers.
• (DUAL) On the App‑V publishing server, ensure that UserRefreshonLogon is set to False.
• (DUAL) On the App‑V publishing server, as an administrator, run Set‑AppvPublishingServer
and set UserRefreshonLogon to False.
• Is a supported version of the App‑V client installed on the VDA? Does the VDA have the enable
package scripts setting enabled?
• On the machine containing the App‑V client and VDA, from the Registry editor (regedit), go
to HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Citrix\AppV. Ensure that the AppVServers key
has the following value format: AppVManagementServer+metadata;PublishingServer (for
example: http://xmas-demo-appv.blrstrm.com+0+0+0+1+1+1+0+1;http://xmas-
demo-appv.blrstrm.com:8082).
• On the machine or master image containing the App‑V client and VDA, check that the Power‑
Shell ExecutionPolicy is set to RemoteSigned. The App‑V client provided by Microsoft is not
signed, and this ExecutionPolicy allows PowerShell to run unsigned local scripts and cmdlets.
Use one of the following two methods to set the ExecutionPolicy: (1) As an administrator, enter
the cmdlet: Set‑ExecutionPolicy RemoteSigned, or (2) From Group Policy settings, go to Com‑
puter Configuration > Policies > Administrative Templates > Windows Components > Windows
PowerShell> Turn on Script Execution.
• If the error “RegistrationManager.AttemptRegistrationWithSingleDdc: Failed to register”
appears, use the MaxReceivedMessageSize property on the appropriate binding element to
increase Max Receivable message size in the configuration of the Delivery Controller and/or the
Broker Agent on the VDA.
If these steps do not resolve the issues, enable and examine the logs.

Logs
App‑V configuration‑related logs are located at C:\CtxAppvLogs. The application launch logs are lo‑
cated at: %LOCALAPPDATA%\Citrix\CtxAppvLogs. LOCALAPPDATA resolves to the local folder for the
logged‑on user. Check the local folder of the user for whom the application launch failed.
To enable Studio and VDA logs used for App‑V, you must have administrator privileges. You will also
need a text editor such as Notepad.
To enable Studio logs:
1. Create the folder C:\CtxAppvLogs.
2. Go to C:\Program Files\Citrix\StudioAppVIntegration\SnapIn\Citrix.Appv.Admin.V1. Open
CtxAppvCommon.dll.config in a text editor and uncomment the line: <add key =”LogFileName”
value=”C:\CtxAppvLogs\log.txt”/>
3. Restart the Broker service to start logging.
To enable VDA logs:
1. Create the folder C:\CtxAppvLogs.
2. Go to C:\Program Files\Citrix\ Virtual Desktop Agent. Open CtxAppvCommon.dll.config in a text
editor and uncomment the following line: <add key =”LogFileName” value=”C:\CtxAppvLogs\log.txt”/>
3. Uncomment the line and set the value field to 1: <add key =”EnableLauncherLogs” value=”1”/>
4. Restart the machine to start logging.
Virtual Apps Secure Browser
April 14, 2021

As applications are ported to the web, users must rely on multiple browser vendors and versions in
order to achieve compatibility with web‑based apps. If the application is an internally hosted appli‑
cation, organizations are often required to install and configure complex VPN solutions in order to
provide access to remote users. Typical VPN solutions require a client‑side agent that must also be
maintained across numerous operating systems.
With the Secure Browser, users can have a seamless web‑based application experience where a
hosted web‑based application simply appears within the user’s preferred local browser. For example,
a user’s preferred browser is Mozilla Firefox but the application is compatible with only Microsoft
Internet Explorer. Secure Browser displays the Internet Explorer‑compatible application as a tab
within the Firefox browser.
Deploying Virtual Apps Secure Browser Edition
1. Download the Citrix Virtual Apps Secure Browser Edition ISO from the Citrix download site.

2. Follow the installation instructions for various components of Citrix Virtual Apps.
3. Configure the edition and license mode for the Secure Browser edition after installation, by per‑
forming the following additional steps:
a) On the Delivery Controller, start a PowerShell session by clicking the blue icon on the
taskbar, or by browsing to Start > All Programs > Accessories >Windows PowerShell > Win‑
dows PowerShell.
On 64‑bit systems, this starts the 64‑bit version. Both the 32‑bit or 64‑bit versions are sup‑
ported.
b) Type asnp Citrix* and press Enter to load the Citrix‑specific PowerShell modules.
(asnp represents Add-PSSnapin.)
c) Check the current site settings and license mode: run Get-ConfigSite.
d) Set the license mode to Virtual Apps Secure Browser edition: run Set-ConfigSite -
ProductCode XDT -ProductEdition BAS.
e) Confirm that the Virtual Apps Secure Browser edition and license mode is set correctly:
run Get-BrokerSite.
After completing the installation, further optimize your environment for web app delivery by using the
configuration steps specified in the XenApp Secure Browser Deployment Guide.
Publish content
April 14, 2021
You can publish an application that is simply a URL or UNC path to a resource, such as a Microsoft Word
document or a web link. This feature is known as published content. The ability to publish content
adds flexibility to how you deliver content to users. You benefit from the existing access control and
management of applications. You can also specify whether to use local or published applications to
open the content.
The published content appears just like other applications in StoreFront and Citrix Workspace app.
Users access it in the same way they access applications. On the client, the resource opens as usual.
• If a locally installed application is appropriate, it is launched to open the resource.

• If a File Type Association has been defined, a published application launches to open the re‑
source.
You publish content using the PowerShell SDK. You cannot use Studio to publish content. However,
you can use Studio to edit application properties later, after they are published.

Configuration overview and preparation
Publishing content uses the New-BrokerApplication cmdlet with the following key properties.
(See the cmdlet help for descriptions of all cmdlet properties.)
1 New-BrokerApplication – ApplicationType PublishedContent -

CommandLineExecutable location -Name app-name -DesktopGroup delivery
-group-name
2 
The ApplicationType property must be PublishedContent.
The CommandLineExecutable property specifies the location of the published content. The follow‑
ing formats are supported, with a limit of 255 characters.
• HTML website address (for example, http://www.citrix.com)

• Document file on a web server (for example, https://www.citrix.com/press/
pressrelease.doc)
• Directory on an FTP server (for example, ftp://ftp.citrix.com/code)
• Document file on an FTP server (for example, ftp://ftp.citrix.com/code/Readme.txt>)
• UNC directory path (for example, file://myServer/myShare or \\\\\myServer\\
myShare)
• UNC file path (for example, file://myServer/myShare/myFile.asf or \\myServer\
myShare\myFile.asf)
Ensure that you have the correct SDK.
• For Citrix Virtual Apps and Desktops service deployments, download and install the Citrix Virtual
Apps and Desktops Remote PowerShell SDK.
• For on‑premises Citrix Virtual Apps and Desktops deployments, use the PowerShell SDK that is
installed with the Delivery Controller. Adding a published content application requires a mini‑
mum version 7.11 Delivery Controller.
The following procedures use examples. In the examples:
• A machine catalog has been created.

• A delivery group named PublishedContentApps has been created. The group uses a multi‑
session OS machine from the catalog. The WordPad application has been added to the group.
• Assignments are made for the delivery group name, the CommandLineExecutable location,
and the application name.
Get started
On the machine containing the PowerShell SDK, open PowerShell.

The following cmdlet adds the appropriate PowerShell SDK snap‑in, and assigns the returned delivery
group record.
Add-PsSnapin Citrix\* $dg = Get-BrokerDesktopGroup –Name PublishedContentApps
If you are using the Citrix Virtual Apps and Desktops service, authenticate by entering your Citrix Cloud
credentials. If there is more than one customer, choose one.
Publish a URL
After assigning the location and application name, the following cmdlet publishes the Citrix home
page as an application.
1 $citrixUrl = "https://www.citrix.com/"
2 $appName = "Citrix Home Page"
3
4 New-BrokerApplication – ApplicationType PublishedContent –
CommandLineExecutable $citrixURL – Name $appName – DesktopGroup $dg.
Uid
5 
Verify success:
• Open StoreFront and log on as a user who can access applications in the PublishedContentApps
delivery group. The display includes the newly created application with the default icon. To
learn about customizing the icon, see https://www.citrix.com/blogs/2013/08/21/xd‑tipster‑
changing‑delivery‑group‑icons‑revisited‑xd7/.
• Click the Citrix Home Page application. The URL launches in a new tab in a locally running
instance of your default browser.
Publish resources located at UNC paths
In this example, the administrator has already created a share named PublishedResources. After
assigning the locations and application names, the following cmdlets publish an RTF and a DOCX file
in that share as a resource.
1 $rtfUNC = "\\GMSXJ-EDGE0.xd.local\\PublishedResources\\PublishedRTF.rtf
"
2 $rtfAppName = "PublishedRTF"
3
4 New-BrokerApplication – ApplicationType PublishedContent
5 – CommandLineExecutable $rtfUNC -Name $rtfAppName
6 -DesktopGroup $dg.Uid

7
8 $docxUNC = "\\GMSXJ-EDGE0.xd.local\PublishedResources\PublishedDOCX.
docx"
9 $docxAppName = "PublishedDOCX"
10
11 New-BrokerApplication – ApplicationType PublishedContent
12 – CommandLineExecutable $docxUNC -Name $docxAppName
13 -DesktopGroup $dg.Uid
14 
Verify success:
• Refresh your StoreFront window to see the newly published documents.

• Click the PublishedRTF and PublishedDOCX applications. Each document opens in a locally
running WordPad.
View and edit PublishedContent applications
You manage published content using the same methods that you use for other application types. The
published content items appear in the Applications list in Studio and can be edited in Studio.
Application properties (such as user visibility, group association, and shortcut) apply to the published
content. However, you cannot change the command‑line argument or working directory properties
on the Location page. To change the resource, modify the Path to the executable file field on that
page.

To use a published application to open a PublishedContent application (rather than a local applica‑
tion), edit the published application’s File Type Association property. In this example, the published
WordPad application was edited to create a File Type Association for .rtf files.
Turn on maintenance mode for the delivery group before editing the File Type Association. Remember
to turn off maintenance mode when you’re done.
Refresh StoreFront to load the File Type Association changes, and then click the PublishedRTF and
PublishedDOCX applications. Notice the difference. PublishedDOCX still opens in the local Word‑
Pad. However, PublishedRTF now opens in the published WordPad due to the file type association.

For more information

• Create delivery groups
• Change application properties
Server VDI
April 14, 2021
Use the Server VDI (Virtual Desktop Infrastructure) feature to deliver a desktop from a server operating
system for a single user.
• Enterprise administrators can deliver server operating systems as VDI desktops, which can be
valuable for users such as engineers and designers.
• Service Providers can offer desktops from the cloud. Those desktops comply with the Microsoft
Services Provider License Agreement (SPLA).
The following features cannot be used with Server VDI:
• Hosted applications
• Local App Access
• Direct (non‑brokered) desktop connections
• Remote PC Access

In Citrix Virtual Apps and Desktops 7 deployments, Server VDI is supported on Windows Server 2019
and Windows Server 2016.
In Citrix Virtual Apps and Desktops service deployments, server VDI is supported on Windows Server
2019, Windows Server 2016, and Windows 10 Enterprise for Virtual Desktops.
All Server VDI deployments support the user personalization layer technology.
For Server VDI to work with TWAIN devices such as scanners, the Windows Server Desktop Experience
feature must be installed.
Install and configure Server VDI
1. Prepare the Windows server for installation.
• Use Windows Server Manager to ensure that the Remote Desktop Services role services
are not installed. If they were previously installed, remove them. The VDA installation fails
if these role services are installed.
• Ensure that the Restrict each user to a single session property is enabled. On the Win‑
dows server, edit the registry for the Terminal Server setting:
HKEY\\_LOCAL\\_MACHINE\\SYSTEM\\CurrentControlSet\\Control\\TerminalServer
DWORD fSingleSessionPerUser = 1
2. Use the Citrix Virtual Apps and Desktops installer’s command line interface to install a VDA on a
supported server or server master image, specifying the /quiet and /servervdi options. (By
default, the installer’s graphical interface blocks the Windows single‑session OS VDA on a server
operating system. Using the command line overrides this behavior.) Use one of the following
commands:
• Citrix Virtual Apps and Desktops deployments:

– XenDesktopVdaSetup.exe /quiet /servervdi
– VDAWorkstationSetup.exe /quiet /servervdi
• Citrix Virtual Apps and Desktops service deployments:
– VDAWorkstationSetup.exe /quiet /servervdi
Other options:
• Use /controllers to specify Delivery Controllers or Cloud Connectors.

• Use /enable_hdx_ports to open ports in the firewall, unless the firewall is to be config‑
ured manually.
• Use /mastermcsimage (or /masterimage) if you are installing the VDA on an image, and
will use MCS to create server VMs from that image.
• For all option details, see Install using the command line.

3. Create a machine catalog for Server VDI. In the catalog creation wizard:
• On the Operating System page, select Single‑session OS.

• On the Summary page, specify a machine catalog name and description for administra‑
tors that clearly identifies it as Server VDI. This is the only indicator in Studio that the cat‑
alog supports Server VDI.
When using search in Studio, the Server VDI catalog is displayed on the Single‑session OS Ma‑
chines tab, even though the VDA is installed on a server.
4. Create a Delivery Group and select the Server VDI catalog you created.
If you did not specify Delivery Controllers or Cloud Connectors during VDA installation, remember to
specify them afterward. For details, see VDA registration.
User personalization layer
April 14, 2021
The user personalization layer feature for Citrix Virtual Apps and Desktops extends the capabilities
of non‑persistent machine catalogs. User personalization layers preserve users’ data and locally in‑
stalled applications across sessions. Powered by Citrix App Layering, this feature replaces Personal
vDisk (PvD).
Like PvD, the user personalization layer feature supports Citrix Provisioning and Machine Creation
Services (MCS) in a non‑persistent machine catalog. You install the feature components alongside the
Virtual Delivery Agent within the master image.
A VHD file stores any applications that the user installs locally. The VHD, which is mounted on the
image, acts as the user’s own user layer virtual hard drive.
This document includes instructions for deploying and configuring the user personalization layer fea‑
ture. It describes the requirements for successful deployment, limitations, and known issues.
To use the User personalization layer feature, you must first deploy it using the steps detailed in the
article. Until then, the feature is not available for you to use.
Application support
Aside from the following exceptions, all applications that a user installs locally on the desktop are
supported in the user personalization layer.

Exceptions
The following applications are the exception and are not supported on the user personalization layer:
• Enterprise applications, such as MS Office and Visual Studio.
• Applications that modify the network stack or hardware. Example: a VPN client.
• Applications that have boot level drivers. Example: a virus scanner.
• Applications with drivers that use the driver store. Example: a printer driver.
Note:
You can make printers available using Windows Group Policy Objects (GPOs).
Do not allow users to install any unsupported applications locally. Rather, install these applications
directly on the master image.
Applications that require a local user or administrator account
When a user installs an application locally, the app goes into their user layer. If the user then adds or
edits a local user or group, the changes do not persist beyond the session.
Important:
Add any required local user or group in the master image.
Requirements
The user personalization layer feature requires the following components:
• Citrix Virtual Apps and Desktops 7 1909 or later

• Virtual Delivery Agent (VDA), version 1912
• Citrix Provisioning, version 1909 or later
• Windows File Share (SMB), or Azure Files with on‑prem AD authentication enabled
You can deploy the User personalization layer feature on the following Windows versions when the
OS is deployed as single session. Support is limited to a single user on a single session.
• Windows 10 Enterprise x64, version 1607 or later

• Windows 10 Multi‑Session (Azure Files supported)
• Windows Server 2016 (Azure Files supported)
• Windows Server 2019 (Azure Files supported)
As indicated above, for Citrix Virtual Apps and Desktops 7, use of Azure Files with User personalization
layers is supported on Windows Server 2019, Windows Server 2016v, and Windows 10 client.

Note:
User personalization layer is only supported as a Server VDI deployment. For deployment details,
see the Server VDI article.
If you installed the preview version of the user personalization layer feature, uninstall the software
and reboot the master image before installing this release.
Set up your file share
The user personalization layer feature requires Windows Server Message Block (SMB) storage. To cre‑
ate a Windows file share, follow the usual steps for the Windows operating system that you are on.
For more about using Azure Files with Azure‑based catalogs, see Set up Azure Files storage for User
personalization layers.
Recommendations
Follow the recommendations in this section for a successful user personalization layer deployment.
Profile Management solution
User personalization layer stores all changes the user makes for a single machine catalog image. To
add enhanced capabilities such as roaming profile data across multiple catalog images, Citrix recom‑
mends also using Profile Management. Refer to the Profile Management documentation for more
details.
When using Profile Management with the user personalization layer feature, clear deletion of the
user’s information on logoff. You can clear deletion using a Group Policy Object (GPO) or the policy
on the Delivery Controller (DDC).
For details about available Profile Management policies, see Profile Management policy descriptions
and defaults.
Microsoft System Center Configuration Manager (SCCM)
If you are using SCCM with the user personalization layer feature, follow the Microsoft guidelines for
preparing your image in a VDI environment. Refer to this Microsoft TechNet article for more informa‑
tion.
User layer size
The default user layer size is 10 GB, the minimum we recommend.

Note:
During installation, if the value is set to zero (0), the default user layer size is set to 10 GB.
If you want to change the user layer size, you can enter a different value for the User Layer Size Studio
policy. (For details, see Step 5: Create delivery group custom policies).
Tools for overriding the User Layer Size (Optional)
You can override the User Layer Size by using a Windows tool to define a quota on the user layer file
share.
Use one of the following Microsoft quota tools to set a hard quota on the user layer directory named
Users:
• File Server Resource Manager (FSRM)
• Quota Manager
Note:
Increasing or decreasing the quota only impacts new user layers. It does not change the maxi‑
mum size of existing user layers. Existing user layers remain unchanged when the quota is up‑
dated.
Deploy a User personalization layer
When deploying the user personalization feature, you define the policies within Studio. You then as‑
sign the policies to the delivery group bound to the machine catalog, where the feature is deployed.
If you leave the master image with no user personalization layer configuration, the services remain
idle and do not interfere with authoring activities.
If you set the policies in the master image, the services attempt to run and mount a user layer within
the master image. The master image would exhibit unexpected behaviors and instability.
To deploy the user personalization layer feature, complete the following steps in this order:
• Step 1: Verify availability of a Citrix Virtual Apps and Desktops environment.
• Step 2: Prepare your master image.
• Step 3: Create a machine catalog.
• Step 4: Create a delivery group.
• Step 5: Create delivery group custom policies.
Step 1: Verify that the Citrix Virtual Apps and Desktops environment is available
Be sure that your Citrix Virtual Apps and Desktops environment is available to use with this new fea‑
ture. For setup details, see Install and configure Citrix Virtual Apps and Desktops.

Step 2: Prepare your master image
To prepare your master image:
1. Locate the master image. Install your organization’s enterprise applications and any other apps
your users generally find useful.
2. If you are deploying Server VDI, follow the steps in the Server VDI article. Be sure to include
the optional component, the User personalization layer. For details, see the Command‑line
options for installing a VDA.
3. If you are using Windows 10, install Virtual Delivery Agent (VDA) 1912. If an older version of the
VDA is already installed, uninstall the old version first. When installing the new version, be sure
to select and install the optional component, the Citrix User Personalization Layer, as follows:
a) Click the tile, Virtual Delivery Agent for Windows Desktop OS:
a) Environment: Select either Create a master MCS image or Create a master image using
Citrix Provisioning or third‑party provisioning tools.

a) Core Components: Click Next.
b) Additional Components: Check Citrix User Personalization Layer.

a) Click through the remaining installation screens, configuring the VDA as needed, and click
Install. The image reboots one or more times during installation.
4. Leave Windows updates disabled. The user personalization layer installer disables Windows
updates on the image. Leave the updates disabled.
The image is ready for you to upload into Studio.
Step 3: Create a machine catalog
In Studio, follow the steps to create a machine catalog. Use the following options during catalog cre‑
ation:
1. Select Operating System and set it to Single session OS.
2. Select Machine Management and set it to Machines that are power managed. For example,
virtual machines or blade PCs.
3. Select Desktop Experience and set it to either pooled‑random or pooled‑static catalog type,
as in the following examples:
• Pooled‑random:

• Pooled‑static: If you select pooled‑static, configure desktops to discard all changes and
clear virtual desktops when the user logs off, as shown in the following screenshot:

Note:
User personalization layer does not support pooled‑static catalogs configured to use Citrix
Personal vDisk or assigned as dedicated virtual machines.
4. If you are using MCS, select Master Image and the snapshot for the image created in the previ‑
ous section.
5. Configure the remaining catalog properties as needed for your environment.
Step 4: Create a delivery group
Create and configure a delivery group, including machines from the machine catalog you created.
For details, see the Create Delivery Groups.
Step 5: Create delivery group custom policies
To enable mounting of user layers within the Virtual Delivery Agents, you use the configuration param‑
eters to specify:
• Where on the network to access the user layers.
• How large to permit the user layer disks to grow.
To define the parameters as custom Citrix policies in Studio and assign them to your delivery group.

1. In Studio, select Policies in the navigation pane:
2. Select Create Policy in the Actions pane. The Create Policy window appears.
3. Type ‘user layer’ into the search field. The following two policies appear in the list of available
policies:
• User Layer Repository Path
• User Layer Size GB
Note:
Changing the User Layer Size in the policy does not change the size of existing layers.
4. Click Select next to User Layer Repository Path. The Edit Setting window appears.

5. Enter a path in the format \\server name or address\folder name in the Value field,
Click OK:

6. Optional: Click Select next to User Layer Size in GB:

7. The Edit Settings window appears.
8. Optional: Change the default value of ‘0’ to the maximum size (in GB) that the user layer can
grow. Click OK.
Note:
If you keep the default value, the maximum user layer size is 10 GB.
9. Click Next to configure Users and Machines. Click the Delivery Group Assign link highlighted in
this image:

10. In the Delivery Group menu, select the delivery group created in the previous section. Click OK.

11. Enter a name for the policy. Click the check box to enable the policy, and click Finish.

Configure security settings on the user layer folder
As a domain administrator, you can specify more than one storage location for your user layers. Create
a \Users subfolder For each storage location (including the default location). Secure each location
using the following settings.
Setting name Value Apply to
Creator Owner Modify Subfolders and Files only

Owner Rights Modify Subfolders and Files only
Users or group: Create Folder/Append Data; Selected Folder Only
Traverse Folder/Execute File;
List Folder/Read Data; Read
Attributes
System Full Control Selected Folder, Subfolders,
and Files

Setting name Value Apply to
Domain Admins, and selected Full Control Selected Folder, Subfolders,

Admin group and Files
User layer messages
When a user is unable to access their user layer, they receive one of these notification messages.
• User Layer In Use
We were unable to attach your user layer because it is in use. Any

changes you make to application settings or data will not be saved. Be
sure to save any work to a shared network location.
• User Layer Unavailable
We were unable to attach your user layer. Any changes you make to
application settings or data will not be saved. Be sure to save any
work to a shared network location.
• System not reset after user sign‑out
This system was not shut down properly. Please log off immediately and
contact your system administrator.
Log files to use when troubleshooting
The log file, ulayersvc.log, contains the output of the user personalization layer software where
changes are logged.
1 C:\ProgramData\Unidesk\Logs\ulayersvc.log
2 
Limitations
Keep the following limitations in mind when installing and using the user personalization layer fea‑
ture.
• Do not attempt to deploy the user personalization layer software on a layer within App Layering.
Either deploy user personalization layers in Citirix Virtual Apps and Desktops, or enable user
layers in an App Layering image template, not both. Either process produces the user layers you
need.‑ Do not configure the user personalization layer feature with persistent machine catalogs.

• Do not use Session hosts.
• Do not update the machine catalog with an image running a new OS install (even the same ver‑
sion of Windows 10). Best practice is to apply updates to the OS within the same master image
used when creating the machine catalog.
• Do not use boot‑time drivers, nor any other early boot personalization.
• Do not migrate PvD data to the user personalization layer feature.
• Do not migrate existing user layers from the full App Layering product to the user personaliza‑
tion layer feature.
• Do not change the user layer SMB path to access user layers created using a different master OS
image.
• Do not enable Secure Boot within User personalization layer virtual machines, as it is not cur‑
rently supported.
• When a user logs out of a session and then logs in again, the new session runs on a different
machine in the pool. In a VDI environment, Microsoft Software Center lists an application as
Installed on the first machine, but shows it as Unavailable on the second machine.
To find out the true status of the application, instruct the user to select the application in the
Software Center and click Install. SCCM then updates the status to the true value.
• Software Center occasionally stops immediately after launching within a VDA that has the user
personalization layer feature enabled. To avoid this issue, follow Microsoft’s recommendations
for Implementing SCCM in a XenDesktop VDI environment. Also, make sure that the ccmexec
service is running before you start the Software Center.
• In Group Polices (Computer Settings), User layer settings override settings applied to the mas‑
ter image. Therefore, the changes you make in Computer Settings using a GPO are not always
present for the user on the next session login.
To get around this issue, create a User Logon Script that issues the command:
gpupdate /force
For example, one customer set the following command to run at each user login:
gpudate /Target:Computer /force
For best results, apply changes to Computer Settings directly on the user layer, after the user
has logged in.

Remove components
April 14, 2021
To remove components, Citrix recommends using the Windows feature for removing or changing pro‑
grams. Alternatively, you can remove components using the command line, or a script on the instal‑
lation media.
When you remove components, prerequisites are not removed, and firewall settings are not changed.
For example, when you remove a Delivery Controller, the SQL Server software and the databases are
not removed.
If you upgraded a Controller from an earlier deployment that included Web Interface, you must re‑
move the Web Interface component separately. You cannot use the installer to remove Web Interface.
For information about removing features not mentioned below, see the feature’s documentation.
Preparation
Before removing a Controller, remove it from the Site. For details, see Remove a Controller.
Close Studio and Director before removing them.
Remove components using the Windows feature for removing or changing programs
From the Windows feature for removing or changing programs:
• To remove a Controller, Studio, Director, License Server, or StoreFront, right‑click Citrix Virtual
Apps version or Citrix Virtual Desktops version and select Uninstall. The installer launches.
Select the components to be removed.
Alternatively, you can remove StoreFront by right‑clicking Citrix StoreFront and selecting
Uninstall.
• To remove a VDA, right‑click Citrix Virtual Delivery Agent version and select Uninstall. The
installer launches and you can select the components to be removed. The machine restarts
automatically after the removal, by default.
• To remove the Universal Print Server, right‑click Citrix Universal Print Server and select Unin‑
stall.
Remove core components using the command line
From the \x64\XenDesktop Setup directory on the installation media, run the XenDesktopServerSetup
.exe command.

• To remove one or more components, specify the /remove and /components options.
• To remove all components, specify the /removeall option.
For command and parameter details, see Install using the command line.
For example, the following command removes Studio.
\x64\XenDesktop Setup\XenDesktopServerSetup.exe /remove /components studio
Remove VDAs using the command line
From the \x64\XenDesktop Setup directory on the installation media, run the XenDesktopVdaSetup
.exe command.
• To remove one or more components, use the /remove and /components options.
• To remove all components, use the /removeall option.
For command and parameter details, see Install using the command line.
The machine restarts automatically after the removal, by default.
For example, the following command removes the VDA and Citrix Workspace app.
\x64\XenDesktop Setup\XenDesktopVdaSetup.exe /removeall
To remove VDAs using a script in Active Directory; see Install or remove VDAs using scripts.
Upgrade and migrate
April 14, 2021
Introduction
Upgrading changes your deployment to the Citrix Virtual Apps and Desktops 7 Current Release (CR)
without having to set up new machines or sites. This is known as an in‑place upgrade.
Upgrading gives you access to the latest features and technologies that you’re eligible for. Upgrades
can also contain fixes, clarifications, and enhancements from earlier versions.
Upgrade overview
1. Review the Upgrade a deployment article before beginning the upgrade. This is the primary
information source for learning how to prepare for and implement an upgrade.
2. Complete the preparation guidance.
3. Run installers to upgrade core components.

4. Upgrade the system databases and the site.

5. Upgrade VDAs on master images (or directly on machines).
6. Upgrade other components.
Each preparation and upgrade step is detailed in Upgrade a deployment.
Versions you can upgrade
The Citrix Upgrade Guide lists the Citrix Virtual Apps and Desktops (and XenApp and XenDesktops)
versions you can upgrade from.
Frequently asked questions
This section answers some commonly asked questions about upgrading Citrix Virtual Apps and Desk‑
tops.
• What is the correct order to upgrade my Virtual Apps and Desktops environment?
The VDA can be upgraded at any time, in any order. Upgrade half of the Controllers before up‑
grading your site. Then upgrade the remaining Controllers after the site upgrade. For more
information, see Upgrade sequence and Upgrade procedure.
• My site has several Delivery Controllers (in different zones). What happens if I upgrade
only some of them? Am I required to upgrade every Controller in the site during the same
maintenance window?
The best practice is to upgrade all Delivery Controllers during the same maintenance window, as
various services on each Controller communicate with each other. Keeping different versions
might cause issues. During a maintenance window, we recommend you upgrade half of the
Controllers, upgrade the site, and then upgrade the remaining Controllers. (For details, see the
Upgrade procedure.)
• Can I go directly to the latest version, or do I have to do incremental upgrades?
You can almost always upgrade to the latest version and skip intermediate releases, unless ex‑
plicitly stated in the What’s new article for the version you’re upgrading to. See the Upgrade
Guide.
• Can a customer upgrade from a Long Term Service Release (LTSR) environment to a Cur‑
rent Release?
Yes. Customers are not required to remain on a Long Term Service Release for an extended
period. Customers can move an LTSR environment to a Current Release, based on business
requirements and features.
• Are mixed versions of components allowed?

Within each site, Citrix recommends upgrading all components to the same version. Although
you can use earlier versions of some components, all features in the latest version might not be
available. For more information, see Mixed environment considerations.
• How often must a Current Release be upgraded?
Current Releases reach End of Maintenance (EOM) 6 months after the release date. Citrix recom‑
mends customers adopt the latest Current Release. Current Releases reach End of Life (EOL) 18
months after the release date. For more information, see Current Release Lifecycle.
• What is recommended: upgrade to LTSR or CR?
Current Releases (CRs) deliver the latest and most innovative app, desktop, and server virtu‑
alization features and functionality. This allows you to stay on leading‑edge technology and
ahead of your competition.
Long Term Service Releases (LTSRs) are ideal for large enterprise production environments that
prefer to retain the same base version for an extended period.
For details, see Servicing Options.
• Do I need to upgrade my licenses?
Ensure that the current license date has not expired, and is valid for the release you are upgrad‑
ing to. See CTX111618. For information about renewal, see Customer Success Services renewal
licenses.
• How long does an upgrade take?
The time required to upgrade a deployment varies, depending on the infrastructure and net‑
work. So, we can’t provide an exact time.
• What are the best practices?
Ensure that you understand and follow the preparation guidance.
• Which operating systems are supported?
The System requirements article for the version you’re upgrading to lists the supported OSs.
If your current deployment uses operating systems that are no longer supported, see Earlier
operating systems.
• Which versions of VMware vSphere (vCenter + ESXi) are supported?
CTX131239 lists the supported hosts and versions, plus links to known issues.
• When does my version go EOL?
Check the Product Matrix.
• What are the known issues with the latest release?

– Citrix Virtual Apps and Desktops

– StoreFront
– Citrix Provisioning
– Citrix License Server
– Citrix Workspace app for Windows
More information
Long Term Service Release (LTSR) deployment updates use Cumulative Updates (CUs). A CU updates
baseline components of the LTSR, and each CU includes its own metainstaller.
Each CU has dedicated documentation. For example, for the 7.15 LTSR, check the link on that LTSR’s
What’s new page for the latest CU. Each CU page includes supported version information, instruc‑
tions, and a link to the CU download package.
Migrate
Migrating moves data from an earlier deployment to a newer version. The process includes installing
newer components and creating a new site, exporting data from the older farm, and then importing
the data to the new site.
There are no supported tools or scripts for migrating XenApp and XenDesktop versions, or migrating
earlier Citrix Virtual Apps and Desktops versions. Upgrading is supported for the Citrix Virtual Apps and
Desktops versions listed in the Citrix Upgrade Guide, and described in this product documentation.
For earlier XenApp 6.x migration content, see the following. Neither the scripts nor the articles are
supported or maintained.
• Open source migration scripts for XenApp 6.x versions are available at https://github.com/citrix/
xa65migrationtool. Citrix does not support or maintain these migration scripts
• Changes in 7.x
• Upgrade a XenApp 6.5 worker to a new VDA
• Migrate XenApp 6.x
Upgrade a deployment
April 14, 2021

Introduction
You can upgrade certain deployments to newer versions without having to first set up new machines
or sites. This is called an in‑place upgrade. To learn which Citrix Virtual Apps and Desktops versions
you can upgrade, see the Citrix Upgrade Guide.
To start an upgrade, you run the installer from the new version to upgrade previously installed core
components, VDAs, and certain other components. Then you upgrade the databases and the site.
You can upgrade any component that can be installed with the full‑product installer (and the stan‑
dalone VDA installers), if there is a newer version provided. For other components that are not in‑
stalled with the full‑product installer (such as Citrix Provisioning and Profile Management), see that
component’s documentation for guidance. For host upgrades, see the appropriate documentation.
Review all the information in this article before beginning an upgrade.
Upgrade sequence
The following diagram shows the steps the upgrade sequence. Upgrade procedure contains details of
each step in the diagram.
Upgrade procedure
Most of the main product components can be upgraded by running the product installer on the ma‑
chine containing the component.

If one machine contains more than one component (for example, Studio and License Server), all com‑
ponents on that machine are upgraded, if the product media contains newer versions of their soft‑
ware.
To use the installers:
• To run the full product installer’s graphical interface, log on to the machine and then insert the
media or mount the ISO drive for the new release. Double‑click AutoSelect.
• To use the command‑line interface, issue the appropriate command. See Install using the com‑
mand line.
Step 1: Prepare
Before you begin an upgrade, make sure you’re ready. Read and complete any necessary tasks:
• Remove PVD, App Disks, and unsupported hosts

• VDAs that have PvD or AppDisk components
• Limitations
• Mixed environment considerations
• Earlier operating systems
• Preparation
• Preliminary site tests
• SQL Server version check
Step 2: Upgrade License Server
If the installation has a new version of the Citrix License Server software, upgrade this component first
before any other components.
If you have not yet determined whether your License Server is compatible with the new version, it is
essential that you run the installer on the License Server before upgrading any other core components.
Step 3: Upgrade StoreFront
If the installation media contains a new version of the StoreFront software, run the installer on the
machine containing the StoreFront server.
• In the graphical interface, choose Citrix StoreFront from the Extend deployment section.
• From the command line, run CitrixStoreFront-x64.exe, which is available in the Citrix
Virtual Apps and Desktops installation media’s x64 folder.

Step 4: Upgrade Director
If the installation media contains a new version of the Director software, run the installer on the ma‑
chine containing Director.
Step 5: Upgrade Citrix Provisioning
The Citrix Provisioning installation media is available separately from the Citrix Virtual Apps and Desk‑
tops installation media. To learn how to install and upgrade Citrix Provisioning server and target de‑
vice software, see the Citrix Provisioning product documentation.
Step 6: Upgrade half of Delivery Controllers
For example, if your site has four Controllers, run the installer on two of them.
Leaving half of the Controllers active allows users to access the site. VDAs can register with the remain‑
ing Controllers. There might be times when the site has reduced capacity because fewer Controllers
are available. The upgrade causes only a brief interruption in establishing new client connections
during the final database upgrade steps. The upgraded Controllers cannot process requests until the
entire site is upgraded.
If your site has only one Controller, it is inoperable during the upgrade.
Preliminary site tests run on the first Controller, before the actual upgrade starts. For details, see
Preliminary site tests.
Step 7: Upgrade Studio
If you haven’t already upgraded Studio (because it was on the same machine as another component),
run the installer on the machine containing Studio.
Step 8: Restart Studio
Restart the upgraded Studio. The upgrade process automatically resumes.
Step 9: Upgrade database and site
Check Preparation for the permissions required to update the schema of the SQL Server databases.
• If you have sufficient permission to update the SQL Server database schema, you can initiate
an automatic database upgrade. Continue with Upgrade the database and site automatically.

• If you do not have sufficient database permissions, you can initiate a manual upgrade that uses
scripts, and proceed with the help of your database administrator (someone who has the re‑
quired permissions). For a manual upgrade, the Studio user generates the scripts and then runs
the scripts that enable and disable services. The database administrator runs other scripts that
update the database schema, using either the SQLCMD utility or the SQL Server Management
Studio in SQLCMD mode. Continue with Upgrade the database and site manually.
Citrix strongly recommends that you back up the database before upgrading. See CTX135207. During
a database upgrade, product services are disabled. During that time, Controllers cannot broker new
connections for the site, so plan carefully.
Upgrade the database and site automatically
1. Start the newly upgraded Studio.

2. Indicate that you want to start the site upgrade automatically and confirm that you are ready.
The database and site upgrade proceeds.
Upgrade the database and site manually
1. Start the newly upgraded Studio.
2. Indicate that you want to upgrade the site manually. The wizard checks for License Server com‑
patibility and requests confirmation.
3. Confirm that you have backed up the database.
The wizard generates and displays the scripts and a checklist of upgrade steps. If a database’s
schema has not changed since the product version being upgraded, that script is not generated.
For example, if the logging database schema does not change, the UpgradeLoggingDatabase
.sql script is not generated.
4. Run the following scripts in the order shown.
• DisableServices.ps1: The Studio user runs this PowerShell script on a Controller to

disable product services.
• UpgradeSiteDatabase.sql: The database administrator runs this SQL script on the
server containing the Site database
• UpgradeMonitorDatabase.sql: The database administrator runs this SQL script on the
server containing the Monitor database.
• UpgradeLoggingDatabase.sql: The database administrator runs this SQL script on the
server containing the Configuration Logging database. Run this script only if this database
changes (for example, after applying a hotfix).
• EnableServices.ps1: The Studio user runs this PowerShell script on a Controller to en‑
able product services.

After the database upgrade completes and product services are enabled, Studio automatically
tests the environment and configuration, and then generates an HTML report. If problems are
identified, you can restore the database backup. After resolving issues, you can upgrade the
database again.
5. After completing the checklist tasks, click Finish upgrade.
Step 10: Upgrade remaining Delivery Controllers
From the newly upgraded Studio, select Citrix Studio site‑name in the navigation pane. On the Com‑
mon Tasks tab, select Upgrade remaining Delivery Controllers.
After completing the upgrade and confirming completion, close and then reopen Studio. Studio might
prompt for an extra site upgrade to register the Controller’s services to the site, or to create a zone ID
if it does not exist.
Step 11: Upgrade VDAs

Important:
If you’re upgrading a VDA to version 1912 or later, see Upgrading VDAs to 1912 or later.
Run the product installer on machines containing VDAs.
If you used Machine Creation Services and a master image to create machines, go to your host and
upgrade the VDA on the master image. You can use any of the available VDA installers.
• For graphic interface guidance, see Install VDAs.

• For command line guidance, see Install using the command line.
If you used Citrix Provisioning to create machines, see the Citrix Provisioning product documentation
for guidance about upgrading.
Watch this video to learn more:

Step 12: Update machine catalogs and Delivery Groups
• Update catalogs that use machines with upgraded VDAs.

• Upgrade catalogs that use machines with upgraded VDAs.
• Upgrade Delivery Groups that use machines with upgraded VDAs.
Step 13: After the upgrade
After completing an upgrade, you can test the newly upgraded site. From Studio, select Citrix Stu‑
dio site‑name in the navigation pane. On the Common Tasks tab, select Test Site. These tests run
automatically after you upgrade the database, but you can run them again at any time.
The tests might fail for a Controller on Windows Server 2016 when a local Microsoft SQL Server Express
is used for the site database, if the SQL Server Browser Service is not started. To avoid this:
• Enable the SQL Server Browser Service (if necessary) and then start it.
• Restart the SQL Server (SQLEXPRESS) service.
Upgrade other components in your deployment. For guidance, see the following product documen‑
tation:
• StoreFront
• AppDNA
• Citrix App Layering
• HDX RealTime Optimization Pack

• Profile Management
• Citrix Provisioning
• Session Recording
• Workspace Environment Management
If you need to replace the Microsoft SQL Server Express LocalDB software with a later version, see
Replace SQL Server Express LocalDB.
Remove PvD, AppDisks, and unsupported hosts
The following technologies and host types are not supported in Citrix Virtual Apps and Desktops 7
Current Release deployments:
• Personal vDisks (PvD) for storing data next to users’ VMs in catalogs. The user personalization
layer feature now handles user persistence.
• AppDisks for managing applications used in Delivery Groups.
• Host types: Azure Classic, Azure Resource Manager (ARM), Amazon Web Services (AWS), Cloud‑
Platform (the original Citrix product).
– For host types supported in this release, see System requirements.

– For information about alternative ways you can continue using ARM and AWS, see
CTX270373.
If your current deployment uses PvDs or AppDisks, or has connections to unsupported host types, you
can upgrade to version 2006 (or later supported versions) only after removing items that use those
technologies.
When the installer detects one or more of the unsupported technologies or host types, the upgrade
pauses or stops, and an explanatory message appears. The installer logs contain details.
To help ensure a successful upgrade, review and follow the applicable guidance for removing the un‑
supported items.
• Remove PvD
• Remove AppDisks
• Remove unsupported host items
Even if you did not use PvD or AppDisks in your deployment, related MSIs might have been included
in an earlier VDA installation or upgrade. Before you can upgrade your VDAs to version 2006 (or a
later supported version), you must remove that software, even if you never used it. When using the
graphical interface, that removal can be done for you, or you can include removal options when using
the CLI. For details, see Upgrading VDAs that have PvD or AppDisks components.

Remove PvD
A deployment upgrade cannot succeed until you remove all machines that are configured to use PvD.
This affects catalogs and Delivery Groups.
To remove PvD from groups and catalogs:
1. From Studio, if a Delivery Group contains machines from a catalog that uses PvD, remove those
machines from the group.
2. From Studio, delete all catalogs containing machines that use PvD.
VDA upgrades: The deployment upgrade does not detect whether VDAs have the AppDisk or PvD
components installed. However, the VDA installers do. For details, see VDAs that have PvD or AppDisks
components.
If you plan to use App Layering instead of PvD, see Migrating PvD to App Layering for information about
moving data.
Remove AppDisks
A deployment upgrade cannot proceed until you remove AppDisks from all Delivery Groups that use
them, and then remove the AppDisks themselves.
1. Select Delivery Groups in the Studio navigation pane.
2. Select a group and then click Manage AppDisks in the Action pane.
3. Click the action that removes the AppDisk from the group.
4. Repeat steps 2 and 3 for each Delivery Group that uses AppDisks.
5. Select AppDisks in the Studio navigation pane.
6. Select an AppDisk and click the action that deletes the AppDisk.
7. Repeat steps 5 and 6 for each AppDisk.
VDA upgrades: The deployment upgrade does not detect whether VDAs have the AppDisk or PvD
components installed. However, the VDA installers do. For details, see VDAs that have PvD or AppDisks
components.
Remove unsupported host items
A deployment upgrade to version 2006 (or later supported version) cannot proceed if the site has con‑
nections to unsupported host types, such as Azure or AWS. Complete the following tasks before at‑
tempting an upgrade.
From Studio:
• Delete all connections to unsupported hosts.
• If a Delivery Group contains machines from a catalog created with a master image from an un‑
supported host, remove those machines from the group.

Citrix Virtual Apps and Desktops Translate

Uploaded by

Copyright:

Available Formats

Citrix Virtual Apps and Desktops Translate

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Citrix Virtual Apps and Desktops Translate

Uploaded by

Copyright:

Available Formats

Citrix Virtual Apps and Desktops

Citrix Product Documentation | docs.citrix.com January 19, 2022

Citrix Virtual Apps and Desktops 7 2006 3

Citrix ICA virtual channels 82

Double hop in Citrix Virtual Apps and Desktops 91

Install and configure 94

Microsoft System Center Virtual Machine Manager virtualization environments 104

Citrix Hypervisor virtualization environments 107

Microsoft System Center Configuration Manager environments 108

VMware virtualization environments 110

Nutanix virtualization environments 116

Install core components 118

© 1999 – 2021 Citrix Systems, Inc. All rights reserved. 2

Install VDAs 130

Install using the command line 143

Install VDAs using scripts 155

Install VDAs using SCCM 158

Create a site 160

Create machine catalogs 165

Manage machine catalogs 183

Create delivery groups 189

Manage delivery groups 194

Create application groups 216

Manage application groups 224

Remote PC Access 229

Virtual Apps Secure Browser 252

Publish content 253

Server VDI 258

User personalization layer 260

Remove components 278

Upgrade and migrate 279

Upgrade a deployment 282

Security considerations and best practices 303

Delegated administration 312

© 1999 – 2021 Citrix Systems, Inc. All rights reserved. 3

Smart cards 320

Smart card deployments 326

Pass‑through authentication and single sign‑on with smart cards 332

App protection 334

Transport Layer Security (TLS) 340

Transport Layer Security (TLS) on Universal Print Server 354

Generic USB devices 366

Mobile and touch screen devices 366

Serial ports 370

Specialty keyboards 375

TWAIN devices 377

HDX 3D Pro 380

GPU acceleration for Windows multi‑session OS 381

GPU acceleration for Windows single‑session OS 384

Text‑based session watermark 394

Audio features 398

Browser content redirection 407

HDX video conferencing and webcam video compression 415

HTML5 multimedia redirection 419

© 1999 – 2021 Citrix Systems, Inc. All rights reserved. 4

Optimization for Microsoft Teams 422

Monitor, troubleshoot, and support Microsoft Teams 442

Windows Media redirection 449

General content redirection 450

Client folder redirection 451